Lib/idlelib/ConfigParser.py

   1 """Configuration file parser.
   2
   3 A setup file consists of sections, lead by a "[section]" header,
   4 and followed by "name: value" entries, with continuations and such in
   5 the style of RFC 822.
   6
   7 The option values can contain format strings which refer to other values in
   8 the same section, or values in a special [DEFAULT] section.
   9
  10 For example:
  11
  12     something: %(dir)s/whatever
  13
  14 would resolve the "%(dir)s" to the value of dir.  All reference
  15 expansions are done late, on demand.
  16
  17 Intrinsic defaults can be specified by passing them into the
  18 ConfigParser constructor as a dictionary.
  19
  20 class:
  21
  22 ConfigParser -- responsible for for parsing a list of
  23                 configuration files, and managing the parsed database.
  24
  25     methods:
  26
  27     __init__(defaults=None)
  28         create the parser and specify a dictionary of intrinsic defaults.  The
  29         keys must be strings, the values must be appropriate for %()s string
  30         interpolation.  Note that `__name__' is always an intrinsic default;
  31         it's value is the section's name.
  32
  33     sections()
  34         return all the configuration section names, sans DEFAULT
  35
  36     has_section(section)
  37         return whether the given section exists
  38
  39     options(section)
  40         return list of configuration options for the named section
  41
  42     has_option(section, option)
  43         return whether the given section has the given option
  44
  45     read(filenames)
  46         read and parse the list of named configuration files, given by
  47         name.  A single filename is also allowed.  Non-existing files
  48         are ignored.
  49
  50     readfp(fp, filename=None)
  51         read and parse one configuration file, given as a file object.
  52         The filename defaults to fp.name; it is only used in error
  53         messages (if fp has no `name' attribute, the string `<???>' is used).
  54
  55     get(section, option, raw=0, vars=None)
  56         return a string value for the named option.  All % interpolations are
  57         expanded in the return values, based on the defaults passed into the
  58         constructor and the DEFAULT section.  Additional substitutions may be
  59         provided using the `vars' argument, which must be a dictionary whose
  60         contents override any pre-existing defaults.
  61
  62     getint(section, options)
  63         like get(), but convert value to an integer
  64
  65     getfloat(section, options)
  66         like get(), but convert value to a float
  67
  68     getboolean(section, options)
  69         like get(), but convert value to a boolean (currently defined as 0 or
  70         1, only)
  71 """
  72
  73 import sys
  74 import string
  75 import re
  76
  77 DEFAULTSECT = "DEFAULT"
  78
  79
  80 \f
  81 # exception classes
  82 class Error:
  83     def __init__(self, msg=''):
  84         self._msg = msg
  85     def __repr__(self):
  86         return self._msg
  87
  88 class NoSectionError(Error):
  89     def __init__(self, section):
  90         Error.__init__(self, 'No section: %s' % section)
  91         self.section = section
  92
  93 class DuplicateSectionError(Error):
  94     def __init__(self, section):
  95         Error.__init__(self, "Section %s already exists" % section)
  96         self.section = section
  97
  98 class NoOptionError(Error):
  99     def __init__(self, option, section):
 100         Error.__init__(self, "No option `%s' in section: %s" %
 101                        (option, section))
 102         self.option = option
 103         self.section = section
 104
 105 class InterpolationError(Error):
 106     def __init__(self, reference, option, section, rawval):
 107         Error.__init__(self,
 108                        "Bad value substitution:\n"
 109                        "\tsection: [%s]\n"
 110                        "\toption : %s\n"
 111                        "\tkey    : %s\n"
 112                        "\trawval : %s\n"
 113                        % (section, option, reference, rawval))
 114         self.reference = reference
 115         self.option = option
 116         self.section = section
 117
 118 class MissingSectionHeaderError(Error):
 119     def __init__(self, filename, lineno, line):
 120         Error.__init__(
 121             self,
 122             'File contains no section headers.\nfile: %s, line: %d\n%s' %
 123             (filename, lineno, line))
 124         self.filename = filename
 125         self.lineno = lineno
 126         self.line = line
 127
 128 class ParsingError(Error):
 129     def __init__(self, filename):
 130         Error.__init__(self, 'File contains parsing errors: %s' % filename)
 131         self.filename = filename
 132         self.errors = []
 133
 134     def append(self, lineno, line):
 135         self.errors.append((lineno, line))
 136         self._msg = self._msg + '\n\t[line %2d]: %s' % (lineno, line)
 137
 138
 139 \f
 140 class ConfigParser:
 141     def __init__(self, defaults=None):
 142         self.__sections = {}
 143         if defaults is None:
 144             self.__defaults = {}
 145         else:
 146             self.__defaults = defaults
 147
 148     def defaults(self):
 149         return self.__defaults
 150
 151     def sections(self):
 152         """Return a list of section names, excluding [DEFAULT]"""
 153         # self.__sections will never have [DEFAULT] in it
 154         return self.__sections.keys()
 155
 156     def add_section(self, section):
 157         """Create a new section in the configuration.
 158
 159         Raise DuplicateSectionError if a section by the specified name
 160         already exists.
 161         """
 162         if self.__sections.has_key(section):
 163             raise DuplicateSectionError(section)
 164         self.__sections[section] = {}
 165
 166     def has_section(self, section):
 167         """Indicate whether the named section is present in the configuration.
 168
 169         The DEFAULT section is not acknowledged.
 170         """
 171         return self.__sections.has_key(section)
 172
 173     def options(self, section):
 174         """Return a list of option names for the given section name."""
 175         try:
 176             opts = self.__sections[section].copy()
 177         except KeyError:
 178             raise NoSectionError(section)
 179         opts.update(self.__defaults)
 180         return opts.keys()
 181
 182     def has_option(self, section, option):
 183         """Return whether the given section has the given option."""
 184         try:
 185             opts = self.__sections[section]
 186         except KeyError:
 187             raise NoSectionError(section)
 188         return opts.has_key(option)
 189
 190     def read(self, filenames):
 191         """Read and parse a filename or a list of filenames.
 192
 193         Files that cannot be opened are silently ignored; this is
 194         designed so that you can specify a list of potential
 195         configuration file locations (e.g. current directory, user's
 196         home directory, systemwide directory), and all existing
 197         configuration files in the list will be read.  A single
 198         filename may also be given.
 199         """
 200         if type(filenames) is type(''):
 201             filenames = [filenames]
 202         for filename in filenames:
 203             try:
 204                 fp = open(filename)
 205             except IOError:
 206                 continue
 207             self.__read(fp, filename)
 208             fp.close()
 209
 210     def readfp(self, fp, filename=None):
 211         """Like read() but the argument must be a file-like object.
 212
 213         The `fp' argument must have a `readline' method.  Optional
 214         second argument is the `filename', which if not given, is
 215         taken from fp.name.  If fp has no `name' attribute, `<???>' is
 216         used.
 217
 218         """
 219         if filename is None:
 220             try:
 221                 filename = fp.name
 222             except AttributeError:
 223                 filename = '<???>'
 224         self.__read(fp, filename)
 225
 226     def get(self, section, option, raw=0, vars=None):
 227         """Get an option value for a given section.
 228
 229         All % interpolations are expanded in the return values, based on the
 230         defaults passed into the constructor, unless the optional argument
 231         `raw' is true.  Additional substitutions may be provided using the
 232         `vars' argument, which must be a dictionary whose contents overrides
 233         any pre-existing defaults.
 234
 235         The section DEFAULT is special.
 236         """
 237         try:
 238             sectdict = self.__sections[section].copy()
 239         except KeyError:
 240             if section == DEFAULTSECT:
 241                 sectdict = {}
 242             else:
 243                 raise NoSectionError(section)
 244         d = self.__defaults.copy()
 245         d.update(sectdict)
 246         # Update with the entry specific variables
 247         if vars:
 248             d.update(vars)
 249         option = self.optionxform(option)
 250         try:
 251             rawval = d[option]
 252         except KeyError:
 253             raise NoOptionError(option, section)
 254         # do the string interpolation
 255         if raw:
 256             return rawval
 257
 258         value = rawval                  # Make it a pretty variable name
 259         depth = 0
 260         while depth < 10:               # Loop through this until it's done
 261             depth = depth + 1
 262             if string.find(value, "%(") >= 0:
 263                 try:
 264                     value = value % d
 265                 except KeyError, key:
 266                     raise InterpolationError(key, option, section, rawval)
 267             else:
 268                 return value
 269
 270     def __get(self, section, conv, option):
 271         return conv(self.get(section, option))
 272
 273     def getint(self, section, option):
 274         return self.__get(section, string.atoi, option)
 275
 276     def getfloat(self, section, option):
 277         return self.__get(section, string.atof, option)
 278
 279     def getboolean(self, section, option):
 280         v = self.get(section, option)
 281         val = string.atoi(v)
 282         if val not in (0, 1):
 283             raise ValueError, 'Not a boolean: %s' % v
 284         return val
 285
 286     def optionxform(self, optionstr):
 287         return string.lower(optionstr)
 288
 289     #
 290     # Regular expressions for parsing section headers and options.  Note a
 291     # slight semantic change from the previous version, because of the use
 292     # of \w, _ is allowed in section header names.
 293     SECTCRE = re.compile(
 294         r'\['                                 # [
 295         r'(?P<header>[-\w_.*,(){}]+)'         # a lot of stuff found by IvL
 296         r'\]'                                 # ]
 297         )
 298     OPTCRE = re.compile(
 299         r'(?P<option>[-\w_.*,(){}]+)'         # a lot of stuff found by IvL
 300         r'[ \t]*(?P<vi>[:=])[ \t]*'           # any number of space/tab,
 301                                               # followed by separator
 302                                               # (either : or =), followed
 303                                               # by any # space/tab
 304         r'(?P<value>.*)$'                     # everything up to eol
 305         )
 306
 307     def __read(self, fp, fpname):
 308         """Parse a sectioned setup file.
 309
 310         The sections in setup file contains a title line at the top,
 311         indicated by a name in square brackets (`[]'), plus key/value
 312         options lines, indicated by `name: value' format lines.
 313         Continuation are represented by an embedded newline then
 314         leading whitespace.  Blank lines, lines beginning with a '#',
 315         and just about everything else is ignored.
 316         """
 317         cursect = None                            # None, or a dictionary
 318         optname = None
 319         lineno = 0
 320         e = None                                  # None, or an exception
 321         while 1:
 322             line = fp.readline()
 323             if not line:
 324                 break
 325             lineno = lineno + 1
 326             # comment or blank line?
 327             if string.strip(line) == '' or line[0] in '#;':
 328                 continue
 329             if string.lower(string.split(line)[0]) == 'rem' \
 330                and line[0] in "rR":      # no leading whitespace
 331                 continue
 332             # continuation line?
 333             if line[0] in ' \t' and cursect is not None and optname:
 334                 value = string.strip(line)
 335                 if value:
 336                     cursect[optname] = cursect[optname] + '\n ' + value
 337             # a section header or option header?
 338             else:
 339                 # is it a section header?
 340                 mo = self.SECTCRE.match(line)
 341                 if mo:
 342                     sectname = mo.group('header')
 343                     if self.__sections.has_key(sectname):
 344                         cursect = self.__sections[sectname]
 345                     elif sectname == DEFAULTSECT:
 346                         cursect = self.__defaults
 347                     else:
 348                         cursect = {'__name__': sectname}
 349                         self.__sections[sectname] = cursect
 350                     # So sections can't start with a continuation line
 351                     optname = None
 352                 # no section header in the file?
 353                 elif cursect is None:
 354                     raise MissingSectionHeaderError(fpname, lineno, `line`)
 355                 # an option line?
 356                 else:
 357                     mo = self.OPTCRE.match(line)
 358                     if mo:
 359                         optname, vi, optval = mo.group('option', 'vi', 'value')
 360                         optname = string.lower(optname)
 361                         if vi in ('=', ':') and ';' in optval:
 362                             # ';' is a comment delimiter only if it follows
 363                             # a spacing character
 364                             pos = string.find(optval, ';')
 365                             if pos and optval[pos-1] in string.whitespace:
 366                                 optval = optval[:pos]
 367                         optval = string.strip(optval)
 368                         # allow empty values
 369                         if optval == '""':
 370                             optval = ''
 371                         cursect[optname] = optval
 372                     else:
 373                         # a non-fatal parsing error occurred.  set up the
 374                         # exception but keep going. the exception will be
 375                         # raised at the end of the file and will contain a
 376                         # list of all bogus lines
 377                         if not e:
 378                             e = ParsingError(fpname)
 379                         e.append(lineno, `line`)
 380         # if any parsing errors occurred, raise an exception
 381         if e:
 382             raise e