Lib/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 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         its 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     has_option(section, option)
  40         return whether the given option exists in the given section
  41
  42     options(section)
  43         return list of configuration options for the named section
  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.  Return list of successfully read files.
  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=False, 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 case
  70         insensitively defined as 0, false, no, off for False, and 1, true,
  71         yes, on for True).  Returns False or True.
  72
  73     items(section, raw=False, vars=None)
  74         return a list of tuples with (name, value) for each option
  75         in the section.
  76
  77     remove_section(section)
  78         remove the given file section and all its options
  79
  80     remove_option(section, option)
  81         remove the given option from the given section
  82
  83     set(section, option, value)
  84         set the given option
  85
  86     write(fp)
  87         write the configuration state in .ini format
  88 """
  89
  90 import re
  91
  92 __all__ = ["NoSectionError", "DuplicateSectionError", "NoOptionError",
  93            "InterpolationError", "InterpolationDepthError",
  94            "InterpolationSyntaxError", "ParsingError",
  95            "MissingSectionHeaderError",
  96            "ConfigParser", "SafeConfigParser", "RawConfigParser",
  97            "DEFAULTSECT", "MAX_INTERPOLATION_DEPTH"]
  98
  99 DEFAULTSECT = "DEFAULT"
 100
 101 MAX_INTERPOLATION_DEPTH = 10
 102
 103
 104
 105 # exception classes
 106 class Error(Exception):
 107     """Base class for ConfigParser exceptions."""
 108
 109     def _get_message(self):
 110         """Getter for 'message'; needed only to override deprecation in
 111         BaseException."""
 112         return self.__message
 113
 114     def _set_message(self, value):
 115         """Setter for 'message'; needed only to override deprecation in
 116         BaseException."""
 117         self.__message = value
 118
 119     # BaseException.message has been deprecated since Python 2.6.  To prevent
 120     # DeprecationWarning from popping up over this pre-existing attribute, use
 121     # a new property that takes lookup precedence.
 122     message = property(_get_message, _set_message)
 123
 124     def __init__(self, msg=''):
 125         self.message = msg
 126         Exception.__init__(self, msg)
 127
 128     def __repr__(self):
 129         return self.message
 130
 131     __str__ = __repr__
 132
 133 class NoSectionError(Error):
 134     """Raised when no section matches a requested option."""
 135
 136     def __init__(self, section):
 137         Error.__init__(self, 'No section: %r' % (section,))
 138         self.section = section
 139
 140 class DuplicateSectionError(Error):
 141     """Raised when a section is multiply-created."""
 142
 143     def __init__(self, section):
 144         Error.__init__(self, "Section %r already exists" % section)
 145         self.section = section
 146
 147 class NoOptionError(Error):
 148     """A requested option was not found."""
 149
 150     def __init__(self, option, section):
 151         Error.__init__(self, "No option %r in section: %r" %
 152                        (option, section))
 153         self.option = option
 154         self.section = section
 155
 156 class InterpolationError(Error):
 157     """Base class for interpolation-related exceptions."""
 158
 159     def __init__(self, option, section, msg):
 160         Error.__init__(self, msg)
 161         self.option = option
 162         self.section = section
 163
 164 class InterpolationMissingOptionError(InterpolationError):
 165     """A string substitution required a setting which was not available."""
 166
 167     def __init__(self, option, section, rawval, reference):
 168         msg = ("Bad value substitution:\n"
 169                "\tsection: [%s]\n"
 170                "\toption : %s\n"
 171                "\tkey    : %s\n"
 172                "\trawval : %s\n"
 173                % (section, option, reference, rawval))
 174         InterpolationError.__init__(self, option, section, msg)
 175         self.reference = reference
 176
 177 class InterpolationSyntaxError(InterpolationError):
 178     """Raised when the source text into which substitutions are made
 179     does not conform to the required syntax."""
 180
 181 class InterpolationDepthError(InterpolationError):
 182     """Raised when substitutions are nested too deeply."""
 183
 184     def __init__(self, option, section, rawval):
 185         msg = ("Value interpolation too deeply recursive:\n"
 186                "\tsection: [%s]\n"
 187                "\toption : %s\n"
 188                "\trawval : %s\n"
 189                % (section, option, rawval))
 190         InterpolationError.__init__(self, option, section, msg)
 191
 192 class ParsingError(Error):
 193     """Raised when a configuration file does not follow legal syntax."""
 194
 195     def __init__(self, filename):
 196         Error.__init__(self, 'File contains parsing errors: %s' % filename)
 197         self.filename = filename
 198         self.errors = []
 199
 200     def append(self, lineno, line):
 201         self.errors.append((lineno, line))
 202         self.message += '\n\t[line %2d]: %s' % (lineno, line)
 203
 204 class MissingSectionHeaderError(ParsingError):
 205     """Raised when a key-value pair is found before any section header."""
 206
 207     def __init__(self, filename, lineno, line):
 208         Error.__init__(
 209             self,
 210             'File contains no section headers.\nfile: %s, line: %d\n%r' %
 211             (filename, lineno, line))
 212         self.filename = filename
 213         self.lineno = lineno
 214         self.line = line
 215
 216
 217 class RawConfigParser:
 218     def __init__(self, defaults=None, dict_type=dict):
 219         self._dict = dict_type
 220         self._sections = self._dict()
 221         self._defaults = self._dict()
 222         if defaults:
 223             for key, value in defaults.items():
 224                 self._defaults[self.optionxform(key)] = value
 225
 226     def defaults(self):
 227         return self._defaults
 228
 229     def sections(self):
 230         """Return a list of section names, excluding [DEFAULT]"""
 231         # self._sections will never have [DEFAULT] in it
 232         return self._sections.keys()
 233
 234     def add_section(self, section):
 235         """Create a new section in the configuration.
 236
 237         Raise DuplicateSectionError if a section by the specified name
 238         already exists.
 239         """
 240         if section in self._sections:
 241             raise DuplicateSectionError(section)
 242         self._sections[section] = self._dict()
 243
 244     def has_section(self, section):
 245         """Indicate whether the named section is present in the configuration.
 246
 247         The DEFAULT section is not acknowledged.
 248         """
 249         return section in self._sections
 250
 251     def options(self, section):
 252         """Return a list of option names for the given section name."""
 253         try:
 254             opts = self._sections[section].copy()
 255         except KeyError:
 256             raise NoSectionError(section)
 257         opts.update(self._defaults)
 258         if '__name__' in opts:
 259             del opts['__name__']
 260         return opts.keys()
 261
 262     def read(self, filenames):
 263         """Read and parse a filename or a list of filenames.
 264
 265         Files that cannot be opened are silently ignored; this is
 266         designed so that you can specify a list of potential
 267         configuration file locations (e.g. current directory, user's
 268         home directory, systemwide directory), and all existing
 269         configuration files in the list will be read.  A single
 270         filename may also be given.
 271
 272         Return list of successfully read files.
 273         """
 274         if isinstance(filenames, basestring):
 275             filenames = [filenames]
 276         read_ok = []
 277         for filename in filenames:
 278             try:
 279                 fp = open(filename)
 280             except IOError:
 281                 continue
 282             self._read(fp, filename)
 283             fp.close()
 284             read_ok.append(filename)
 285         return read_ok
 286
 287     def readfp(self, fp, filename=None):
 288         """Like read() but the argument must be a file-like object.
 289
 290         The `fp' argument must have a `readline' method.  Optional
 291         second argument is the `filename', which if not given, is
 292         taken from fp.name.  If fp has no `name' attribute, `<???>' is
 293         used.
 294
 295         """
 296         if filename is None:
 297             try:
 298                 filename = fp.name
 299             except AttributeError:
 300                 filename = '<???>'
 301         self._read(fp, filename)
 302
 303     def get(self, section, option):
 304         opt = self.optionxform(option)
 305         if section not in self._sections:
 306             if section != DEFAULTSECT:
 307                 raise NoSectionError(section)
 308             if opt in self._defaults:
 309                 return self._defaults[opt]
 310             else:
 311                 raise NoOptionError(option, section)
 312         elif opt in self._sections[section]:
 313             return self._sections[section][opt]
 314         elif opt in self._defaults:
 315             return self._defaults[opt]
 316         else:
 317             raise NoOptionError(option, section)
 318
 319     def items(self, section):
 320         try:
 321             d2 = self._sections[section]
 322         except KeyError:
 323             if section != DEFAULTSECT:
 324                 raise NoSectionError(section)
 325             d2 = self._dict()
 326         d = self._defaults.copy()
 327         d.update(d2)
 328         if "__name__" in d:
 329             del d["__name__"]
 330         return d.items()
 331
 332     def _get(self, section, conv, option):
 333         return conv(self.get(section, option))
 334
 335     def getint(self, section, option):
 336         return self._get(section, int, option)
 337
 338     def getfloat(self, section, option):
 339         return self._get(section, float, option)
 340
 341     _boolean_states = {'1': True, 'yes': True, 'true': True, 'on': True,
 342                        '0': False, 'no': False, 'false': False, 'off': False}
 343
 344     def getboolean(self, section, option):
 345         v = self.get(section, option)
 346         if v.lower() not in self._boolean_states:
 347             raise ValueError, 'Not a boolean: %s' % v
 348         return self._boolean_states[v.lower()]
 349
 350     def optionxform(self, optionstr):
 351         return optionstr.lower()
 352
 353     def has_option(self, section, option):
 354         """Check for the existence of a given option in a given section."""
 355         if not section or section == DEFAULTSECT:
 356             option = self.optionxform(option)
 357             return option in self._defaults
 358         elif section not in self._sections:
 359             return False
 360         else:
 361             option = self.optionxform(option)
 362             return (option in self._sections[section]
 363                     or option in self._defaults)
 364
 365     def set(self, section, option, value):
 366         """Set an option."""
 367         if not section or section == DEFAULTSECT:
 368             sectdict = self._defaults
 369         else:
 370             try:
 371                 sectdict = self._sections[section]
 372             except KeyError:
 373                 raise NoSectionError(section)
 374         sectdict[self.optionxform(option)] = value
 375
 376     def write(self, fp):
 377         """Write an .ini-format representation of the configuration state."""
 378         if self._defaults:
 379             fp.write("[%s]\n" % DEFAULTSECT)
 380             for (key, value) in self._defaults.items():
 381                 fp.write("%s = %s\n" % (key, str(value).replace('\n', '\n\t')))
 382             fp.write("\n")
 383         for section in self._sections:
 384             fp.write("[%s]\n" % section)
 385             for (key, value) in self._sections[section].items():
 386                 if key != "__name__":
 387                     fp.write("%s = %s\n" %
 388                              (key, str(value).replace('\n', '\n\t')))
 389             fp.write("\n")
 390
 391     def remove_option(self, section, option):
 392         """Remove an option."""
 393         if not section or section == DEFAULTSECT:
 394             sectdict = self._defaults
 395         else:
 396             try:
 397                 sectdict = self._sections[section]
 398             except KeyError:
 399                 raise NoSectionError(section)
 400         option = self.optionxform(option)
 401         existed = option in sectdict
 402         if existed:
 403             del sectdict[option]
 404         return existed
 405
 406     def remove_section(self, section):
 407         """Remove a file section."""
 408         existed = section in self._sections
 409         if existed:
 410             del self._sections[section]
 411         return existed
 412
 413     #
 414     # Regular expressions for parsing section headers and options.
 415     #
 416     SECTCRE = re.compile(
 417         r'\['                                 # [
 418         r'(?P<header>[^]]+)'                  # very permissive!
 419         r'\]'                                 # ]
 420         )
 421     OPTCRE = re.compile(
 422         r'(?P<option>[^:=\s][^:=]*)'          # very permissive!
 423         r'\s*(?P<vi>[:=])\s*'                 # any number of space/tab,
 424                                               # followed by separator
 425                                               # (either : or =), followed
 426                                               # by any # space/tab
 427         r'(?P<value>.*)$'                     # everything up to eol
 428         )
 429
 430     def _read(self, fp, fpname):
 431         """Parse a sectioned setup file.
 432
 433         The sections in setup file contains a title line at the top,
 434         indicated by a name in square brackets (`[]'), plus key/value
 435         options lines, indicated by `name: value' format lines.
 436         Continuations are represented by an embedded newline then
 437         leading whitespace.  Blank lines, lines beginning with a '#',
 438         and just about everything else are ignored.
 439         """
 440         cursect = None                            # None, or a dictionary
 441         optname = None
 442         lineno = 0
 443         e = None                                  # None, or an exception
 444         while True:
 445             line = fp.readline()
 446             if not line:
 447                 break
 448             lineno = lineno + 1
 449             # comment or blank line?
 450             if line.strip() == '' or line[0] in '#;':
 451                 continue
 452             if line.split(None, 1)[0].lower() == 'rem' and line[0] in "rR":
 453                 # no leading whitespace
 454                 continue
 455             # continuation line?
 456             if line[0].isspace() and cursect is not None and optname:
 457                 value = line.strip()
 458                 if value:
 459                     cursect[optname] = "%s\n%s" % (cursect[optname], value)
 460             # a section header or option header?
 461             else:
 462                 # is it a section header?
 463                 mo = self.SECTCRE.match(line)
 464                 if mo:
 465                     sectname = mo.group('header')
 466                     if sectname in self._sections:
 467                         cursect = self._sections[sectname]
 468                     elif sectname == DEFAULTSECT:
 469                         cursect = self._defaults
 470                     else:
 471                         cursect = self._dict()
 472                         cursect['__name__'] = sectname
 473                         self._sections[sectname] = cursect
 474                     # So sections can't start with a continuation line
 475                     optname = None
 476                 # no section header in the file?
 477                 elif cursect is None:
 478                     raise MissingSectionHeaderError(fpname, lineno, line)
 479                 # an option line?
 480                 else:
 481                     mo = self.OPTCRE.match(line)
 482                     if mo:
 483                         optname, vi, optval = mo.group('option', 'vi', 'value')
 484                         if vi in ('=', ':') and ';' in optval:
 485                             # ';' is a comment delimiter only if it follows
 486                             # a spacing character
 487                             pos = optval.find(';')
 488                             if pos != -1 and optval[pos-1].isspace():
 489                                 optval = optval[:pos]
 490                         optval = optval.strip()
 491                         # allow empty values
 492                         if optval == '""':
 493                             optval = ''
 494                         optname = self.optionxform(optname.rstrip())
 495                         cursect[optname] = optval
 496                     else:
 497                         # a non-fatal parsing error occurred.  set up the
 498                         # exception but keep going. the exception will be
 499                         # raised at the end of the file and will contain a
 500                         # list of all bogus lines
 501                         if not e:
 502                             e = ParsingError(fpname)
 503                         e.append(lineno, repr(line))
 504         # if any parsing errors occurred, raise an exception
 505         if e:
 506             raise e
 507
 508
 509 class ConfigParser(RawConfigParser):
 510
 511     def get(self, section, option, raw=False, vars=None):
 512         """Get an option value for a given section.
 513
 514         All % interpolations are expanded in the return values, based on the
 515         defaults passed into the constructor, unless the optional argument
 516         `raw' is true.  Additional substitutions may be provided using the
 517         `vars' argument, which must be a dictionary whose contents overrides
 518         any pre-existing defaults.
 519
 520         The section DEFAULT is special.
 521         """
 522         d = self._defaults.copy()
 523         try:
 524             d.update(self._sections[section])
 525         except KeyError:
 526             if section != DEFAULTSECT:
 527                 raise NoSectionError(section)
 528         # Update with the entry specific variables
 529         if vars:
 530             for key, value in vars.items():
 531                 d[self.optionxform(key)] = value
 532         option = self.optionxform(option)
 533         try:
 534             value = d[option]
 535         except KeyError:
 536             raise NoOptionError(option, section)
 537
 538         if raw:
 539             return value
 540         else:
 541             return self._interpolate(section, option, value, d)
 542
 543     def items(self, section, raw=False, vars=None):
 544         """Return a list of tuples with (name, value) for each option
 545         in the section.
 546
 547         All % interpolations are expanded in the return values, based on the
 548         defaults passed into the constructor, unless the optional argument
 549         `raw' is true.  Additional substitutions may be provided using the
 550         `vars' argument, which must be a dictionary whose contents overrides
 551         any pre-existing defaults.
 552
 553         The section DEFAULT is special.
 554         """
 555         d = self._defaults.copy()
 556         try:
 557             d.update(self._sections[section])
 558         except KeyError:
 559             if section != DEFAULTSECT:
 560                 raise NoSectionError(section)
 561         # Update with the entry specific variables
 562         if vars:
 563             for key, value in vars.items():
 564                 d[self.optionxform(key)] = value
 565         options = d.keys()
 566         if "__name__" in options:
 567             options.remove("__name__")
 568         if raw:
 569             return [(option, d[option])
 570                     for option in options]
 571         else:
 572             return [(option, self._interpolate(section, option, d[option], d))
 573                     for option in options]
 574
 575     def _interpolate(self, section, option, rawval, vars):
 576         # do the string interpolation
 577         value = rawval
 578         depth = MAX_INTERPOLATION_DEPTH
 579         while depth:                    # Loop through this until it's done
 580             depth -= 1
 581             if "%(" in value:
 582                 value = self._KEYCRE.sub(self._interpolation_replace, value)
 583                 try:
 584                     value = value % vars
 585                 except KeyError, e:
 586                     raise InterpolationMissingOptionError(
 587                         option, section, rawval, e[0])
 588             else:
 589                 break
 590         if "%(" in value:
 591             raise InterpolationDepthError(option, section, rawval)
 592         return value
 593
 594     _KEYCRE = re.compile(r"%\(([^)]*)\)s|.")
 595
 596     def _interpolation_replace(self, match):
 597         s = match.group(1)
 598         if s is None:
 599             return match.group()
 600         else:
 601             return "%%(%s)s" % self.optionxform(s)
 602
 603
 604 class SafeConfigParser(ConfigParser):
 605
 606     def _interpolate(self, section, option, rawval, vars):
 607         # do the string interpolation
 608         L = []
 609         self._interpolate_some(option, L, rawval, section, vars, 1)
 610         return ''.join(L)
 611
 612     _interpvar_re = re.compile(r"%\(([^)]+)\)s")
 613     _badpercent_re = re.compile(r"%[^%]|%$")
 614
 615     def _interpolate_some(self, option, accum, rest, section, map, depth):
 616         if depth > MAX_INTERPOLATION_DEPTH:
 617             raise InterpolationDepthError(option, section, rest)
 618         while rest:
 619             p = rest.find("%")
 620             if p < 0:
 621                 accum.append(rest)
 622                 return
 623             if p > 0:
 624                 accum.append(rest[:p])
 625                 rest = rest[p:]
 626             # p is no longer used
 627             c = rest[1:2]
 628             if c == "%":
 629                 accum.append("%")
 630                 rest = rest[2:]
 631             elif c == "(":
 632                 m = self._interpvar_re.match(rest)
 633                 if m is None:
 634                     raise InterpolationSyntaxError(option, section,
 635                         "bad interpolation variable reference %r" % rest)
 636                 var = self.optionxform(m.group(1))
 637                 rest = rest[m.end():]
 638                 try:
 639                     v = map[var]
 640                 except KeyError:
 641                     raise InterpolationMissingOptionError(
 642                         option, section, rest, var)
 643                 if "%" in v:
 644                     self._interpolate_some(option, accum, v,
 645                                            section, map, depth + 1)
 646                 else:
 647                     accum.append(v)
 648             else:
 649                 raise InterpolationSyntaxError(
 650                     option, section,
 651                     "'%%' must be followed by '%%' or '(', found: %r" % (rest,))
 652
 653     def set(self, section, option, value):
 654         """Set an option.  Extend ConfigParser.set: check for string values."""
 655         if not isinstance(value, basestring):
 656             raise TypeError("option values must be strings")
 657         # check for bad percent signs:
 658         # first, replace all "good" interpolations
 659         tmp_value = self._interpvar_re.sub('', value)
 660         # then, check if there's a lone percent sign left
 661         m = self._badpercent_re.search(tmp_value)
 662         if m:
 663             raise ValueError("invalid interpolation syntax in %r at "
 664                              "position %d" % (value, m.start()))
 665         ConfigParser.set(self, section, option, value)