iramuteq.org Git - iramuteq/blob - configparser.py

   1 #!/usr/bin/env python
   2 # -*- coding: utf-8 -*-
   3
   4 u"""Configuration file parser.
   5
   6 A configuration file consists of sections, lead by a "[section]" header,
   7 and followed by "name: value" entries, with continuations and such in
   8 the style of RFC 822.
   9
  10 Intrinsic defaults can be specified by passing them into the
  11 ConfigParser constructor as a dictionary.
  12
  13 class:
  14
  15 ConfigParser -- responsible for parsing a list of
  16                     configuration files, and managing the parsed database.
  17
  18     methods:
  19
  20     __init__(defaults=None, dict_type=_default_dict, allow_no_value=False,
  21              delimiters=('=', ':'), comment_prefixes=('#', ';'),
  22              inline_comment_prefixes=None, strict=True,
  23              empty_lines_in_values=True):
  24         Create the parser. When `defaults' is given, it is initialized into the
  25         dictionary or intrinsic defaults. The keys must be strings, the values
  26         must be appropriate for %()s string interpolation.
  27
  28         When `dict_type' is given, it will be used to create the dictionary
  29         objects for the list of sections, for the options within a section, and
  30         for the default values.
  31
  32         When `delimiters' is given, it will be used as the set of substrings
  33         that divide keys from values.
  34
  35         When `comment_prefixes' is given, it will be used as the set of
  36         substrings that prefix comments in empty lines. Comments can be
  37         indented.
  38
  39         When `inline_comment_prefixes' is given, it will be used as the set of
  40         substrings that prefix comments in non-empty lines.
  41
  42         When `strict` is True, the parser won't allow for any section or option
  43         duplicates while reading from a single source (file, string or
  44         dictionary). Default is True.
  45
  46         When `empty_lines_in_values' is False (default: True), each empty line
  47         marks the end of an option. Otherwise, internal empty lines of
  48         a multiline option are kept as part of the value.
  49
  50         When `allow_no_value' is True (default: False), options without
  51         values are accepted; the value presented for these is None.
  52
  53     sections()
  54         Return all the configuration section names, sans DEFAULT.
  55
  56     has_section(section)
  57         Return whether the given section exists.
  58
  59     has_option(section, option)
  60         Return whether the given option exists in the given section.
  61
  62     options(section)
  63         Return list of configuration options for the named section.
  64
  65     read(filenames, encoding=None)
  66         Read and parse the list of named configuration files, given by
  67         name.  A single filename is also allowed.  Non-existing files
  68         are ignored.  Return list of successfully read files.
  69
  70     read_file(f, filename=None)
  71         Read and parse one configuration file, given as a file object.
  72         The filename defaults to f.name; it is only used in error
  73         messages (if f has no `name' attribute, the string `<???>' is used).
  74
  75     read_string(string)
  76         Read configuration from a given string.
  77
  78     read_dict(dictionary)
  79         Read configuration from a dictionary. Keys are section names,
  80         values are dictionaries with keys and values that should be present
  81         in the section. If the used dictionary type preserves order, sections
  82         and their keys will be added in order. Values are automatically
  83         converted to strings.
  84
  85     get(section, option, raw=False, vars=None, fallback=_UNSET)
  86         Return a string value for the named option.  All % interpolations are
  87         expanded in the return values, based on the defaults passed into the
  88         constructor and the DEFAULT section.  Additional substitutions may be
  89         provided using the `vars' argument, which must be a dictionary whose
  90         contents override any pre-existing defaults. If `option' is a key in
  91         `vars', the value from `vars' is used.
  92
  93     getint(section, options, raw=False, vars=None, fallback=_UNSET)
  94         Like get(), but convert value to an integer.
  95
  96     getfloat(section, options, raw=False, vars=None, fallback=_UNSET)
  97         Like get(), but convert value to a float.
  98
  99     getboolean(section, options, raw=False, vars=None, fallback=_UNSET)
 100         Like get(), but convert value to a boolean (currently case
 101         insensitively defined as 0, false, no, off for False, and 1, true,
 102         yes, on for True).  Returns False or True.
 103
 104     items(section=_UNSET, raw=False, vars=None)
 105         If section is given, return a list of tuples with (section_name,
 106         section_proxy) for each section, including DEFAULTSECT. Otherwise,
 107         return a list of tuples with (name, value) for each option
 108         in the section.
 109
 110     remove_section(section)
 111         Remove the given file section and all its options.
 112
 113     remove_option(section, option)
 114         Remove the given option from the given section.
 115
 116     set(section, option, value)
 117         Set the given option.
 118
 119     write(fp, space_around_delimiters=True)
 120         Write the configuration state in .ini format. If
 121         `space_around_delimiters' is True (the default), delimiters
 122         between keys and values are surrounded by spaces.
 123 """
 124
 125 from __future__ import with_statement
 126 from collections import MutableMapping
 127 from io import open
 128 try:
 129     from collections import OrderedDict as _default_dict
 130 except ImportError:
 131     from ordereddict import OrderedDict as _default_dict
 132 import functools
 133 import io
 134 import itertools
 135 import re
 136 import sys
 137 import warnings
 138
 139 from configparser_helpers import _ChainMap
 140
 141 __all__ = [u"NoSectionError", u"DuplicateOptionError", u"DuplicateSectionError",
 142            u"NoOptionError", u"InterpolationError", u"InterpolationDepthError",
 143            u"InterpolationSyntaxError", u"ParsingError",
 144            u"MissingSectionHeaderError",
 145            u"ConfigParser", u"SafeConfigParser", u"RawConfigParser",
 146            u"DEFAULTSECT", u"MAX_INTERPOLATION_DEPTH"]
 147
 148 DEFAULTSECT = u"DEFAULT"
 149
 150 MAX_INTERPOLATION_DEPTH = 10
 151
 152
 153
 154 # exception classes
 155 class Error(Exception):
 156     u"""Base class for ConfigParser exceptions."""
 157
 158     def _get_message(self):
 159         u"""Getter for 'message'; needed only to override deprecation in
 160         BaseException.
 161         """
 162         return self.__message
 163
 164     def _set_message(self, value):
 165         u"""Setter for 'message'; needed only to override deprecation in
 166         BaseException.
 167         """
 168         self.__message = value
 169
 170     # BaseException.message has been deprecated since Python 2.6.  To prevent
 171     # DeprecationWarning from popping up over this pre-existing attribute, use
 172     # a new property that takes lookup precedence.
 173     message = property(_get_message, _set_message)
 174
 175     def __init__(self, msg=u''):
 176         self.message = msg
 177         Exception.__init__(self, msg)
 178
 179     def __repr__(self):
 180         return self.message
 181
 182     __str__ = __repr__
 183
 184
 185 class NoSectionError(Error):
 186     u"""Raised when no section matches a requested option."""
 187
 188     def __init__(self, section):
 189         Error.__init__(self, u'No section: %r' % (section,))
 190         self.section = section
 191         self.args = (section, )
 192
 193
 194 class DuplicateSectionError(Error):
 195     u"""Raised when a section is repeated in an input source.
 196
 197     Possible repetitions that raise this exception are: multiple creation
 198     using the API or in strict parsers when a section is found more than once
 199     in a single input file, string or dictionary.
 200     """
 201
 202     def __init__(self, section, source=None, lineno=None):
 203         msg = [repr(section), u" already exists"]
 204         if source is not None:
 205             message = [u"While reading from ", source]
 206             if lineno is not None:
 207                 message.append(u" [line {0:2d}]".format(lineno))
 208             message.append(u": section ")
 209             message.extend(msg)
 210             msg = message
 211         else:
 212             msg.insert(0, u"Section ")
 213         Error.__init__(self, u"".join(msg))
 214         self.section = section
 215         self.source = source
 216         self.lineno = lineno
 217         self.args = (section, source, lineno)
 218
 219
 220 class DuplicateOptionError(Error):
 221     u"""Raised by strict parsers when an option is repeated in an input source.
 222
 223     Current implementation raises this exception only when an option is found
 224     more than once in a single file, string or dictionary.
 225     """
 226
 227     def __init__(self, section, option, source=None, lineno=None):
 228         msg = [repr(option), u" in section ", repr(section),
 229                u" already exists"]
 230         if source is not None:
 231             message = [u"While reading from ", source]
 232             if lineno is not None:
 233                 message.append(u" [line {0:2d}]".format(lineno))
 234             message.append(u": option ")
 235             message.extend(msg)
 236             msg = message
 237         else:
 238             msg.insert(0, u"Option ")
 239         Error.__init__(self, u"".join(msg))
 240         self.section = section
 241         self.option = option
 242         self.source = source
 243         self.lineno = lineno
 244         self.args = (section, option, source, lineno)
 245
 246
 247 class NoOptionError(Error):
 248     u"""A requested option was not found."""
 249
 250     def __init__(self, option, section):
 251         Error.__init__(self, u"No option %r in section: %r" %
 252                        (option, section))
 253         self.option = option
 254         self.section = section
 255         self.args = (option, section)
 256
 257
 258 class InterpolationError(Error):
 259     u"""Base class for interpolation-related exceptions."""
 260
 261     def __init__(self, option, section, msg):
 262         Error.__init__(self, msg)
 263         self.option = option
 264         self.section = section
 265         self.args = (option, section, msg)
 266
 267
 268 class InterpolationMissingOptionError(InterpolationError):
 269     u"""A string substitution required a setting which was not available."""
 270
 271     def __init__(self, option, section, rawval, reference):
 272         msg = (u"Bad value substitution:\n"
 273                u"\tsection: [%s]\n"
 274                u"\toption : %s\n"
 275                u"\tkey    : %s\n"
 276                u"\trawval : %s\n"
 277                % (section, option, reference, rawval))
 278         InterpolationError.__init__(self, option, section, msg)
 279         self.reference = reference
 280         self.args = (option, section, rawval, reference)
 281
 282
 283 class InterpolationSyntaxError(InterpolationError):
 284     u"""Raised when the source text contains invalid syntax.
 285
 286     Current implementation raises this exception when the source text into
 287     which substitutions are made does not conform to the required syntax.
 288     """
 289
 290
 291 class InterpolationDepthError(InterpolationError):
 292     u"""Raised when substitutions are nested too deeply."""
 293
 294     def __init__(self, option, section, rawval):
 295         msg = (u"Value interpolation too deeply recursive:\n"
 296                u"\tsection: [%s]\n"
 297                u"\toption : %s\n"
 298                u"\trawval : %s\n"
 299                % (section, option, rawval))
 300         InterpolationError.__init__(self, option, section, msg)
 301         self.args = (option, section, rawval)
 302
 303
 304 class ParsingError(Error):
 305     u"""Raised when a configuration file does not follow legal syntax."""
 306
 307     def __init__(self, source=None, filename=None):
 308         # Exactly one of `source'/`filename' arguments has to be given.
 309         # `filename' kept for compatibility.
 310         if filename and source:
 311             raise ValueError(u"Cannot specify both `filename' and `source'. "
 312                              u"Use `source'.")
 313         elif not filename and not source:
 314             raise ValueError(u"Required argument `source' not given.")
 315         elif filename:
 316             source = filename
 317         Error.__init__(self, u'Source contains parsing errors: %s' % source)
 318         self.source = source
 319         self.errors = []
 320         self.args = (source, )
 321
 322     @property
 323     def filename(self):
 324         u"""Deprecated, use `source'."""
 325         warnings.warn(
 326             u"The 'filename' attribute will be removed in future versions.  "
 327             u"Use 'source' instead.",
 328             DeprecationWarning, stacklevel=2
 329         )
 330         return self.source
 331
 332     @filename.setter
 333     def filename(self, value):
 334         u"""Deprecated, user `source'."""
 335         warnings.warn(
 336             u"The 'filename' attribute will be removed in future versions.  "
 337             u"Use 'source' instead.",
 338             DeprecationWarning, stacklevel=2
 339         )
 340         self.source = value
 341
 342     def append(self, lineno, line):
 343         self.errors.append((lineno, line))
 344         self.message += u'\n\t[line %2d]: %s' % (lineno, line)
 345
 346
 347 class MissingSectionHeaderError(ParsingError):
 348     u"""Raised when a key-value pair is found before any section header."""
 349
 350     def __init__(self, filename, lineno, line):
 351         Error.__init__(
 352             self,
 353             u'File contains no section headers.\nfile: %s, line: %d\n%r' %
 354             (filename, lineno, line))
 355         self.source = filename
 356         self.lineno = lineno
 357         self.line = line
 358         self.args = (filename, lineno, line)
 359
 360
 361 # Used in parser getters to indicate the default behaviour when a specific
 362 # option is not found it to raise an exception. Created to enable `None' as
 363 # a valid fallback value.
 364 _UNSET = object()
 365
 366
 367 class Interpolation(object):
 368     u"""Dummy interpolation that passes the value through with no changes."""
 369
 370     def before_get(self, parser, section, option, value, defaults):
 371         return value
 372
 373     def before_set(self, parser, section, option, value):
 374         return value
 375
 376     def before_read(self, parser, section, option, value):
 377         return value
 378
 379     def before_write(self, parser, section, option, value):
 380         return value
 381
 382
 383 class BasicInterpolation(Interpolation):
 384     u"""Interpolation as implemented in the classic ConfigParser.
 385
 386     The option values can contain format strings which refer to other values in
 387     the same section, or values in the special default section.
 388
 389     For example:
 390
 391         something: %(dir)s/whatever
 392
 393     would resolve the "%(dir)s" to the value of dir.  All reference
 394     expansions are done late, on demand. If a user needs to use a bare % in
 395     a configuration file, she can escape it by writing %%. Other other % usage
 396     is considered a user error and raises `InterpolationSyntaxError'."""
 397
 398     _KEYCRE = re.compile(ur"%\(([^)]+)\)s")
 399
 400     def before_get(self, parser, section, option, value, defaults):
 401         L = []
 402         self._interpolate_some(parser, option, L, value, section, defaults, 1)
 403         return u''.join(L)
 404
 405     def before_set(self, parser, section, option, value):
 406         tmp_value = value.replace(u'%%', u'') # escaped percent signs
 407         tmp_value = self._KEYCRE.sub(u'', tmp_value) # valid syntax
 408         if u'%' in tmp_value:
 409             raise ValueError(u"invalid interpolation syntax in %r at "
 410                              u"position %d" % (value, tmp_value.find(u'%')))
 411         return value
 412
 413     def _interpolate_some(self, parser, option, accum, rest, section, map,
 414                           depth):
 415         if depth > MAX_INTERPOLATION_DEPTH:
 416             raise InterpolationDepthError(option, section, rest)
 417         while rest:
 418             p = rest.find(u"%")
 419             if p < 0:
 420                 accum.append(rest)
 421                 return
 422             if p > 0:
 423                 accum.append(rest[:p])
 424                 rest = rest[p:]
 425             # p is no longer used
 426             c = rest[1:2]
 427             if c == u"%":
 428                 accum.append(u"%")
 429                 rest = rest[2:]
 430             elif c == u"(":
 431                 m = self._KEYCRE.match(rest)
 432                 if m is None:
 433                     raise InterpolationSyntaxError(option, section,
 434                         u"bad interpolation variable reference %r" % rest)
 435                 var = parser.optionxform(m.group(1))
 436                 rest = rest[m.end():]
 437                 try:
 438                     v = map[var]
 439                 except KeyError:
 440                     raise InterpolationMissingOptionError(
 441                         option, section, rest, var)
 442                 if u"%" in v:
 443                     self._interpolate_some(parser, option, accum, v,
 444                                            section, map, depth + 1)
 445                 else:
 446                     accum.append(v)
 447             else:
 448                 raise InterpolationSyntaxError(
 449                     option, section,
 450                     u"'%%' must be followed by '%%' or '(', "
 451                     u"found: %r" % (rest,))
 452
 453
 454 class ExtendedInterpolation(Interpolation):
 455     u"""Advanced variant of interpolation, supports the syntax used by
 456     `zc.buildout'. Enables interpolation between sections."""
 457
 458     _KEYCRE = re.compile(ur"\$\{([^}]+)\}")
 459
 460     def before_get(self, parser, section, option, value, defaults):
 461         L = []
 462         self._interpolate_some(parser, option, L, value, section, defaults, 1)
 463         return u''.join(L)
 464
 465     def before_set(self, parser, section, option, value):
 466         tmp_value = value.replace(u'$$', u'') # escaped dollar signs
 467         tmp_value = self._KEYCRE.sub(u'', tmp_value) # valid syntax
 468         if u'$' in tmp_value:
 469             raise ValueError(u"invalid interpolation syntax in %r at "
 470                              u"position %d" % (value, tmp_value.find(u'%')))
 471         return value
 472
 473     def _interpolate_some(self, parser, option, accum, rest, section, map,
 474                           depth):
 475         if depth > MAX_INTERPOLATION_DEPTH:
 476             raise InterpolationDepthError(option, section, rest)
 477         while rest:
 478             p = rest.find(u"$")
 479             if p < 0:
 480                 accum.append(rest)
 481                 return
 482             if p > 0:
 483                 accum.append(rest[:p])
 484                 rest = rest[p:]
 485             # p is no longer used
 486             c = rest[1:2]
 487             if c == u"$":
 488                 accum.append(u"$")
 489                 rest = rest[2:]
 490             elif c == u"{":
 491                 m = self._KEYCRE.match(rest)
 492                 if m is None:
 493                     raise InterpolationSyntaxError(option, section,
 494                         u"bad interpolation variable reference %r" % rest)
 495                 path = m.group(1).split(u':')
 496                 rest = rest[m.end():]
 497                 sect = section
 498                 opt = option
 499                 try:
 500                     if len(path) == 1:
 501                         opt = parser.optionxform(path[0])
 502                         v = map[opt]
 503                     elif len(path) == 2:
 504                         sect = path[0]
 505                         opt = parser.optionxform(path[1])
 506                         v = parser.get(sect, opt, raw=True)
 507                     else:
 508                         raise InterpolationSyntaxError(
 509                             option, section,
 510                             u"More than one ':' found: %r" % (rest,))
 511                 except (KeyError, NoSectionError, NoOptionError):
 512                     raise InterpolationMissingOptionError(
 513                         option, section, rest, u":".join(path))
 514                 if u"$" in v:
 515                     self._interpolate_some(parser, opt, accum, v, sect,
 516                                            dict(parser.items(sect, raw=True)),
 517                                            depth + 1)
 518                 else:
 519                     accum.append(v)
 520             else:
 521                 raise InterpolationSyntaxError(
 522                     option, section,
 523                     u"'$' must be followed by '$' or '{', "
 524                     u"found: %r" % (rest,))
 525
 526
 527 class LegacyInterpolation(Interpolation):
 528     u"""Deprecated interpolation used in old versions of ConfigParser.
 529     Use BasicInterpolation or ExtendedInterpolation instead."""
 530
 531     _KEYCRE = re.compile(ur"%\(([^)]*)\)s|.")
 532
 533     def before_get(self, parser, section, option, value, vars):
 534         rawval = value
 535         depth = MAX_INTERPOLATION_DEPTH
 536         while depth:                    # Loop through this until it's done
 537             depth -= 1
 538             if value and u"%(" in value:
 539                 replace = functools.partial(self._interpolation_replace,
 540                                             parser=parser)
 541                 value = self._KEYCRE.sub(replace, value)
 542                 try:
 543                     value = value % vars
 544                 except KeyError, e:
 545                     raise InterpolationMissingOptionError(
 546                         option, section, rawval, e.args[0])
 547             else:
 548                 break
 549         if value and u"%(" in value:
 550             raise InterpolationDepthError(option, section, rawval)
 551         return value
 552
 553     def before_set(self, parser, section, option, value):
 554         return value
 555
 556     @staticmethod
 557     def _interpolation_replace(match, parser):
 558         s = match.group(1)
 559         if s is None:
 560             return match.group()
 561         else:
 562             return u"%%(%s)s" % parser.optionxform(s)
 563
 564
 565 class RawConfigParser(MutableMapping):
 566     u"""ConfigParser that does not do interpolation."""
 567
 568     # Regular expressions for parsing section headers and options
 569     _SECT_TMPL = ur"""
 570         \[                                 # [
 571         (?P<header>[^]]+)                  # very permissive!
 572         \]                                 # ]
 573         """
 574     _OPT_TMPL = ur"""
 575         (?P<option>.*?)                    # very permissive!
 576         \s*(?P<vi>{delim})\s*              # any number of space/tab,
 577                                            # followed by any of the
 578                                            # allowed delimiters,
 579                                            # followed by any space/tab
 580         (?P<value>.*)$                     # everything up to eol
 581         """
 582     _OPT_NV_TMPL = ur"""
 583         (?P<option>.*?)                    # very permissive!
 584         \s*(?:                             # any number of space/tab,
 585         (?P<vi>{delim})\s*                 # optionally followed by
 586                                            # any of the allowed
 587                                            # delimiters, followed by any
 588                                            # space/tab
 589         (?P<value>.*))?$                   # everything up to eol
 590         """
 591     # Interpolation algorithm to be used if the user does not specify another
 592     _DEFAULT_INTERPOLATION = Interpolation()
 593     # Compiled regular expression for matching sections
 594     SECTCRE = re.compile(_SECT_TMPL, re.VERBOSE)
 595     # Compiled regular expression for matching options with typical separators
 596     OPTCRE = re.compile(_OPT_TMPL.format(delim=u"=|:"), re.VERBOSE)
 597     # Compiled regular expression for matching options with optional values
 598     # delimited using typical separators
 599     OPTCRE_NV = re.compile(_OPT_NV_TMPL.format(delim=u"=|:"), re.VERBOSE)
 600     # Compiled regular expression for matching leading whitespace in a line
 601     NONSPACECRE = re.compile(ur"\S")
 602     # Possible boolean values in the configuration.
 603     BOOLEAN_STATES = {u'1': True, u'yes': True, u'true': True, u'on': True,
 604                       u'0': False, u'no': False, u'false': False, u'off': False}
 605
 606     def __init__(self, defaults=None, dict_type=_default_dict,
 607                  allow_no_value=False, **_3to2kwargs):
 608
 609         if 'interpolation' in _3to2kwargs: interpolation = _3to2kwargs['interpolation']; del _3to2kwargs['interpolation']
 610         else: interpolation = _UNSET
 611         if 'default_section' in _3to2kwargs: default_section = _3to2kwargs['default_section']; del _3to2kwargs['default_section']
 612         else: default_section = DEFAULTSECT
 613         if 'empty_lines_in_values' in _3to2kwargs: empty_lines_in_values = _3to2kwargs['empty_lines_in_values']; del _3to2kwargs['empty_lines_in_values']
 614         else: empty_lines_in_values = True
 615         if 'strict' in _3to2kwargs: strict = _3to2kwargs['strict']; del _3to2kwargs['strict']
 616         else: strict = True
 617         if 'inline_comment_prefixes' in _3to2kwargs: inline_comment_prefixes = _3to2kwargs['inline_comment_prefixes']; del _3to2kwargs['inline_comment_prefixes']
 618         else: inline_comment_prefixes = None
 619         if 'comment_prefixes' in _3to2kwargs: comment_prefixes = _3to2kwargs['comment_prefixes']; del _3to2kwargs['comment_prefixes']
 620         else: comment_prefixes = (u'#', u';')
 621         if 'delimiters' in _3to2kwargs: delimiters = _3to2kwargs['delimiters']; del _3to2kwargs['delimiters']
 622         else: delimiters = (u'=', u':')
 623         self._dict = dict_type
 624         self._sections = self._dict()
 625         self._defaults = self._dict()
 626         self._proxies = self._dict()
 627         self._proxies[default_section] = SectionProxy(self, default_section)
 628         if defaults:
 629             for key, value in defaults.items():
 630                 self._defaults[self.optionxform(key)] = value
 631         self._delimiters = tuple(delimiters)
 632         if delimiters == (u'=', u':'):
 633             self._optcre = self.OPTCRE_NV if allow_no_value else self.OPTCRE
 634         else:
 635             d = u"|".join(re.escape(d) for d in delimiters)
 636             if allow_no_value:
 637                 self._optcre = re.compile(self._OPT_NV_TMPL.format(delim=d),
 638                                           re.VERBOSE)
 639             else:
 640                 self._optcre = re.compile(self._OPT_TMPL.format(delim=d),
 641                                           re.VERBOSE)
 642         self._comment_prefixes = tuple(comment_prefixes or ())
 643         self._inline_comment_prefixes = tuple(inline_comment_prefixes or ())
 644         self._strict = strict
 645         self._allow_no_value = allow_no_value
 646         self._empty_lines_in_values = empty_lines_in_values
 647         self.default_section=default_section
 648         self._interpolation = interpolation
 649         if self._interpolation is _UNSET:
 650             self._interpolation = self._DEFAULT_INTERPOLATION
 651         if self._interpolation is None:
 652             self._interpolation = Interpolation()
 653
 654     def defaults(self):
 655         return self._defaults
 656
 657     def sections(self):
 658         u"""Return a list of section names, excluding [DEFAULT]"""
 659         # self._sections will never have [DEFAULT] in it
 660         return list(self._sections.keys())
 661
 662     def add_section(self, section):
 663         u"""Create a new section in the configuration.
 664
 665         Raise DuplicateSectionError if a section by the specified name
 666         already exists. Raise ValueError if name is DEFAULT.
 667         """
 668         if section == self.default_section:
 669             raise ValueError(u'Invalid section name: %r' % section)
 670
 671         if section in self._sections:
 672             raise DuplicateSectionError(section)
 673         self._sections[section] = self._dict()
 674         self._proxies[section] = SectionProxy(self, section)
 675
 676     def has_section(self, section):
 677         u"""Indicate whether the named section is present in the configuration.
 678
 679         The DEFAULT section is not acknowledged.
 680         """
 681         return section in self._sections
 682
 683     def options(self, section):
 684         u"""Return a list of option names for the given section name."""
 685         try:
 686             opts = self._sections[section].copy()
 687         except KeyError:
 688             raise NoSectionError(section)
 689         opts.update(self._defaults)
 690         return list(opts.keys())
 691
 692     def read(self, filenames, encoding=None):
 693         u"""Read and parse a filename or a list of filenames.
 694
 695         Files that cannot be opened are silently ignored; this is
 696         designed so that you can specify a list of potential
 697         configuration file locations (e.g. current directory, user's
 698         home directory, systemwide directory), and all existing
 699         configuration files in the list will be read.  A single
 700         filename may also be given.
 701
 702         Return list of successfully read files.
 703         """
 704         if isinstance(filenames, unicode):
 705             filenames = [filenames]
 706         read_ok = []
 707         for filename in filenames:
 708             try:
 709                 with open(filename, encoding=encoding) as fp:
 710                     self._read(fp, filename)
 711             except IOError:
 712                 continue
 713             read_ok.append(filename)
 714         return read_ok
 715
 716     def read_file(self, f, source=None):
 717         u"""Like read() but the argument must be a file-like object.
 718
 719         The `f' argument must be iterable, returning one line at a time.
 720         Optional second argument is the `source' specifying the name of the
 721         file being read. If not given, it is taken from f.name. If `f' has no
 722         `name' attribute, `<???>' is used.
 723         """
 724         if source is None:
 725             try:
 726                 source = f.name
 727             except AttributeError:
 728                 source = u'<???>'
 729         self._read(f, source)
 730
 731     def read_string(self, string, source=u'<string>'):
 732         u"""Read configuration from a given string."""
 733         sfile = io.StringIO(string)
 734         self.read_file(sfile, source)
 735
 736     def read_dict(self, dictionary, source=u'<dict>'):
 737         u"""Read configuration from a dictionary.
 738
 739         Keys are section names, values are dictionaries with keys and values
 740         that should be present in the section. If the used dictionary type
 741         preserves order, sections and their keys will be added in order.
 742
 743         All types held in the dictionary are converted to strings during
 744         reading, including section names, option names and keys.
 745
 746         Optional second argument is the `source' specifying the name of the
 747         dictionary being read.
 748         """
 749         elements_added = set()
 750         for section, keys in dictionary.items():
 751             section = unicode(section)
 752             try:
 753                 self.add_section(section)
 754             except (DuplicateSectionError, ValueError):
 755                 if self._strict and section in elements_added:
 756                     raise
 757             elements_added.add(section)
 758             for key, value in keys.items():
 759                 key = self.optionxform(unicode(key))
 760                 if value is not None:
 761                     value = unicode(value)
 762                 if self._strict and (section, key) in elements_added:
 763                     raise DuplicateOptionError(section, key, source)
 764                 elements_added.add((section, key))
 765                 self.set(section, key, value)
 766
 767     def readfp(self, fp, filename=None):
 768         u"""Deprecated, use read_file instead."""
 769         warnings.warn(
 770             u"This method will be removed in future versions.  "
 771             u"Use 'parser.read_file()' instead.",
 772             DeprecationWarning, stacklevel=2
 773         )
 774         self.read_file(fp, source=filename)
 775
 776     def get(self, section, option, **_3to2kwargs):
 777         if 'fallback' in _3to2kwargs: fallback = _3to2kwargs['fallback']; del _3to2kwargs['fallback']
 778         else: fallback = _UNSET
 779         if 'vars' in _3to2kwargs: vars = _3to2kwargs['vars']; del _3to2kwargs['vars']
 780         else: vars = None
 781         if 'raw' in _3to2kwargs: raw = _3to2kwargs['raw']; del _3to2kwargs['raw']
 782         else: raw = False
 783         u"""Get an option value for a given section.
 784
 785         If `vars' is provided, it must be a dictionary. The option is looked up
 786         in `vars' (if provided), `section', and in `DEFAULTSECT' in that order.
 787         If the key is not found and `fallback' is provided, it is used as
 788         a fallback value. `None' can be provided as a `fallback' value.
 789
 790         If interpolation is enabled and the optional argument `raw' is False,
 791         all interpolations are expanded in the return values.
 792
 793         Arguments `raw', `vars', and `fallback' are keyword only.
 794
 795         The section DEFAULT is special.
 796         """
 797         try:
 798             d = self._unify_values(section, vars)
 799         except NoSectionError:
 800             if fallback is _UNSET:
 801                 raise
 802             else:
 803                 return fallback
 804         option = self.optionxform(option)
 805         try:
 806             value = d[option]
 807         except KeyError:
 808             if fallback is _UNSET:
 809                 raise NoOptionError(option, section)
 810             else:
 811                 return fallback
 812
 813         if raw or value is None:
 814             return value
 815         else:
 816             return self._interpolation.before_get(self, section, option, value,
 817                                                   d)
 818
 819     def _get(self, section, conv, option, **kwargs):
 820         return conv(self.get(section, option, **kwargs))
 821
 822     def getint(self, section, option, **_3to2kwargs):
 823         if 'fallback' in _3to2kwargs: fallback = _3to2kwargs['fallback']; del _3to2kwargs['fallback']
 824         else: fallback = _UNSET
 825         if 'vars' in _3to2kwargs: vars = _3to2kwargs['vars']; del _3to2kwargs['vars']
 826         else: vars = None
 827         if 'raw' in _3to2kwargs: raw = _3to2kwargs['raw']; del _3to2kwargs['raw']
 828         else: raw = False
 829         try:
 830             return self._get(section, int, option, raw=raw, vars=vars)
 831         except (NoSectionError, NoOptionError):
 832             if fallback is _UNSET:
 833                 raise
 834             else:
 835                 return fallback
 836
 837     def getfloat(self, section, option, **_3to2kwargs):
 838         if 'fallback' in _3to2kwargs: fallback = _3to2kwargs['fallback']; del _3to2kwargs['fallback']
 839         else: fallback = _UNSET
 840         if 'vars' in _3to2kwargs: vars = _3to2kwargs['vars']; del _3to2kwargs['vars']
 841         else: vars = None
 842         if 'raw' in _3to2kwargs: raw = _3to2kwargs['raw']; del _3to2kwargs['raw']
 843         else: raw = False
 844         try:
 845             return self._get(section, float, option, raw=raw, vars=vars)
 846         except (NoSectionError, NoOptionError):
 847             if fallback is _UNSET:
 848                 raise
 849             else:
 850                 return fallback
 851
 852     def getboolean(self, section, option, **_3to2kwargs):
 853         if 'fallback' in _3to2kwargs: fallback = _3to2kwargs['fallback']; del _3to2kwargs['fallback']
 854         else: fallback = _UNSET
 855         if 'vars' in _3to2kwargs: vars = _3to2kwargs['vars']; del _3to2kwargs['vars']
 856         else: vars = None
 857         if 'raw' in _3to2kwargs: raw = _3to2kwargs['raw']; del _3to2kwargs['raw']
 858         else: raw = False
 859         try:
 860             return self._get(section, self._convert_to_boolean, option,
 861                              raw=raw, vars=vars)
 862         except (NoSectionError, NoOptionError):
 863             if fallback is _UNSET:
 864                 raise
 865             else:
 866                 return fallback
 867
 868     def items(self, section=_UNSET, raw=False, vars=None):
 869         u"""Return a list of (name, value) tuples for each option in a section.
 870
 871         All % interpolations are expanded in the return values, based on the
 872         defaults passed into the constructor, unless the optional argument
 873         `raw' is true.  Additional substitutions may be provided using the
 874         `vars' argument, which must be a dictionary whose contents overrides
 875         any pre-existing defaults.
 876
 877         The section DEFAULT is special.
 878         """
 879         if section is _UNSET:
 880             return super(RawConfigParser, self).items()
 881         d = self._defaults.copy()
 882         try:
 883             d.update(self._sections[section])
 884         except KeyError:
 885             if section != self.default_section:
 886                 raise NoSectionError(section)
 887         # Update with the entry specific variables
 888         if vars:
 889             for key, value in vars.items():
 890                 d[self.optionxform(key)] = value
 891         value_getter = lambda option: self._interpolation.before_get(self,
 892             section, option, d[option], d)
 893         if raw:
 894             value_getter = lambda option: d[option]
 895         return [(option, value_getter(option)) for option in d.keys()]
 896
 897     def optionxform(self, optionstr):
 898         return optionstr.lower()
 899
 900     def has_option(self, section, option):
 901         u"""Check for the existence of a given option in a given section.
 902         If the specified `section' is None or an empty string, DEFAULT is
 903         assumed. If the specified `section' does not exist, returns False."""
 904         if not section or section == self.default_section:
 905             option = self.optionxform(option)
 906             return option in self._defaults
 907         elif section not in self._sections:
 908             return False
 909         else:
 910             option = self.optionxform(option)
 911             return (option in self._sections[section]
 912                     or option in self._defaults)
 913
 914     def set(self, section, option, value=None):
 915         u"""Set an option."""
 916         if value:
 917             value = self._interpolation.before_set(self, section, option,
 918                                                    value)
 919         if not section or section == self.default_section:
 920             sectdict = self._defaults
 921         else:
 922             try:
 923                 sectdict = self._sections[section]
 924             except KeyError:
 925                 raise NoSectionError(section)
 926         sectdict[self.optionxform(option)] = value
 927
 928     def write(self, fp, space_around_delimiters=True):
 929         u"""Write an .ini-format representation of the configuration state.
 930
 931         If `space_around_delimiters' is True (the default), delimiters
 932         between keys and values are surrounded by spaces.
 933         """
 934         if space_around_delimiters:
 935             d = u" {0} ".format(self._delimiters[0])
 936         else:
 937             d = self._delimiters[0]
 938         if self._defaults:
 939             self._write_section(fp, self.default_section,
 940                                     self._defaults.items(), d)
 941         for section in self._sections:
 942             self._write_section(fp, section,
 943                                 self._sections[section].items(), d)
 944
 945     def _write_section(self, fp, section_name, section_items, delimiter):
 946         u"""Write a single section to the specified `fp'."""
 947         fp.write(u"[{0}]\n".format(section_name))
 948         for key, value in section_items:
 949             value = self._interpolation.before_write(self, section_name, key,
 950                                                      value)
 951             if value is not None or not self._allow_no_value:
 952                 value = delimiter + unicode(value).replace(u'\n', u'\n\t')
 953             else:
 954                 value = u""
 955             fp.write(u"{0}{1}\n".format(key, value))
 956         fp.write(u"\n")
 957
 958     def remove_option(self, section, option):
 959         u"""Remove an option."""
 960         if not section or section == self.default_section:
 961             sectdict = self._defaults
 962         else:
 963             try:
 964                 sectdict = self._sections[section]
 965             except KeyError:
 966                 raise NoSectionError(section)
 967         option = self.optionxform(option)
 968         existed = option in sectdict
 969         if existed:
 970             del sectdict[option]
 971         return existed
 972
 973     def remove_section(self, section):
 974         u"""Remove a file section."""
 975         existed = section in self._sections
 976         if existed:
 977             del self._sections[section]
 978             del self._proxies[section]
 979         return existed
 980
 981     def __getitem__(self, key):
 982         if key != self.default_section and not self.has_section(key):
 983             raise KeyError(key)
 984         return self._proxies[key]
 985
 986     def __setitem__(self, key, value):
 987         # To conform with the mapping protocol, overwrites existing values in
 988         # the section.
 989
 990         # XXX this is not atomic if read_dict fails at any point. Then again,
 991         # no update method in configparser is atomic in this implementation.
 992         self.remove_section(key)
 993         self.read_dict({key: value})
 994
 995     def __delitem__(self, key):
 996         if key == self.default_section:
 997             raise ValueError(u"Cannot remove the default section.")
 998         if not self.has_section(key):
 999             raise KeyError(key)
1000         self.remove_section(key)
1001
1002     def __contains__(self, key):
1003         return key == self.default_section or self.has_section(key)
1004
1005     def __len__(self):
1006         return len(self._sections) + 1 # the default section
1007
1008     def __iter__(self):
1009         # XXX does it break when underlying container state changed?
1010         return itertools.chain((self.default_section,), self._sections.keys())
1011
1012     def _read(self, fp, fpname):
1013         u"""Parse a sectioned configuration file.
1014
1015         Each section in a configuration file contains a header, indicated by
1016         a name in square brackets (`[]'), plus key/value options, indicated by
1017         `name' and `value' delimited with a specific substring (`=' or `:' by
1018         default).
1019
1020         Values can span multiple lines, as long as they are indented deeper
1021         than the first line of the value. Depending on the parser's mode, blank
1022         lines may be treated as parts of multiline values or ignored.
1023
1024         Configuration files may include comments, prefixed by specific
1025         characters (`#' and `;' by default). Comments may appear on their own
1026         in an otherwise empty line or may be entered in lines holding values or
1027         section names.
1028         """
1029         elements_added = set()
1030         cursect = None                        # None, or a dictionary
1031         sectname = None
1032         optname = None
1033         lineno = 0
1034         indent_level = 0
1035         e = None                              # None, or an exception
1036         for lineno, line in enumerate(fp, start=1):
1037             comment_start = None
1038             # strip inline comments
1039             for prefix in self._inline_comment_prefixes:
1040                 index = line.find(prefix)
1041                 if index == 0 or (index > 0 and line[index-1].isspace()):
1042                     comment_start = index
1043                     break
1044             # strip full line comments
1045             for prefix in self._comment_prefixes:
1046                 if line.strip().startswith(prefix):
1047                     comment_start = 0
1048                     break
1049             value = line[:comment_start].strip()
1050             if not value:
1051                 if self._empty_lines_in_values:
1052                     # add empty line to the value, but only if there was no
1053                     # comment on the line
1054                     if (comment_start is None and
1055                         cursect is not None and
1056                         optname and
1057                         cursect[optname] is not None):
1058                         cursect[optname].append(u'') # newlines added at join
1059                 else:
1060                     # empty line marks end of value
1061                     indent_level = sys.maxsize
1062                 continue
1063             # continuation line?
1064             first_nonspace = self.NONSPACECRE.search(line)
1065             cur_indent_level = first_nonspace.start() if first_nonspace else 0
1066             if (cursect is not None and optname and
1067                 cur_indent_level > indent_level):
1068                 cursect[optname].append(value)
1069             # a section header or option header?
1070             else:
1071                 indent_level = cur_indent_level
1072                 # is it a section header?
1073                 mo = self.SECTCRE.match(value)
1074                 if mo:
1075                     sectname = mo.group(u'header')
1076                     if sectname in self._sections:
1077                         if self._strict and sectname in elements_added:
1078                             raise DuplicateSectionError(sectname, fpname,
1079                                                         lineno)
1080                         cursect = self._sections[sectname]
1081                         elements_added.add(sectname)
1082                     elif sectname == self.default_section:
1083                         cursect = self._defaults
1084                     else:
1085                         cursect = self._dict()
1086                         self._sections[sectname] = cursect
1087                         self._proxies[sectname] = SectionProxy(self, sectname)
1088                         elements_added.add(sectname)
1089                     # So sections can't start with a continuation line
1090                     optname = None
1091                 # no section header in the file?
1092                 elif cursect is None:
1093                     raise MissingSectionHeaderError(fpname, lineno, line)
1094                 # an option line?
1095                 else:
1096                     mo = self._optcre.match(value)
1097                     if mo:
1098                         optname, vi, optval = mo.group(u'option', u'vi', u'value')
1099                         if not optname:
1100                             e = self._handle_error(e, fpname, lineno, line)
1101                         optname = self.optionxform(optname.rstrip())
1102                         if (self._strict and
1103                             (sectname, optname) in elements_added):
1104                             raise DuplicateOptionError(sectname, optname,
1105                                                        fpname, lineno)
1106                         elements_added.add((sectname, optname))
1107                         # This check is fine because the OPTCRE cannot
1108                         # match if it would set optval to None
1109                         if optval is not None:
1110                             optval = optval.strip()
1111                             cursect[optname] = [optval]
1112                         else:
1113                             # valueless option handling
1114                             cursect[optname] = None
1115                     else:
1116                         # a non-fatal parsing error occurred. set up the
1117                         # exception but keep going. the exception will be
1118                         # raised at the end of the file and will contain a
1119                         # list of all bogus lines
1120                         e = self._handle_error(e, fpname, lineno, line)
1121         # if any parsing errors occurred, raise an exception
1122         if e:
1123             raise e
1124         self._join_multiline_values()
1125
1126     def _join_multiline_values(self):
1127         defaults = self.default_section, self._defaults
1128         all_sections = itertools.chain((defaults,),
1129                                        self._sections.items())
1130         for section, options in all_sections:
1131             for name, val in options.items():
1132                 if isinstance(val, list):
1133                     val = u'\n'.join(val).rstrip()
1134                 options[name] = self._interpolation.before_read(self,
1135                                                                 section,
1136                                                                 name, val)
1137
1138     def _handle_error(self, exc, fpname, lineno, line):
1139         if not exc:
1140             exc = ParsingError(fpname)
1141         exc.append(lineno, repr(line))
1142         return exc
1143
1144     def _unify_values(self, section, vars):
1145         u"""Create a sequence of lookups with 'vars' taking priority over
1146         the 'section' which takes priority over the DEFAULTSECT.
1147
1148         """
1149         sectiondict = {}
1150         try:
1151             sectiondict = self._sections[section]
1152         except KeyError:
1153             if section != self.default_section:
1154                 raise NoSectionError(section)
1155         # Update with the entry specific variables
1156         vardict = {}
1157         if vars:
1158             for key, value in vars.items():
1159                 if value is not None:
1160                     value = unicode(value)
1161                 vardict[self.optionxform(key)] = value
1162         return _ChainMap(vardict, sectiondict, self._defaults)
1163
1164     def _convert_to_boolean(self, value):
1165         u"""Return a boolean value translating from other types if necessary.
1166         """
1167         if value.lower() not in self.BOOLEAN_STATES:
1168             raise ValueError(u'Not a boolean: %s' % value)
1169         return self.BOOLEAN_STATES[value.lower()]
1170
1171     def _validate_value_types(self, **_3to2kwargs):
1172         if 'value' in _3to2kwargs: value = _3to2kwargs['value']; del _3to2kwargs['value']
1173         else: value = u""
1174         if 'option' in _3to2kwargs: option = _3to2kwargs['option']; del _3to2kwargs['option']
1175         else: option = u""
1176         if 'section' in _3to2kwargs: section = _3to2kwargs['section']; del _3to2kwargs['section']
1177         else: section = u""
1178         u"""Raises a TypeError for non-string values.
1179
1180         The only legal non-string value if we allow valueless
1181         options is None, so we need to check if the value is a
1182         string if:
1183         - we do not allow valueless options, or
1184         - we allow valueless options but the value is not None
1185
1186         For compatibility reasons this method is not used in classic set()
1187         for RawConfigParsers. It is invoked in every case for mapping protocol
1188         access and in ConfigParser.set().
1189         """
1190         if not isinstance(section, basestring):
1191             raise TypeError(u"section names must be strings")
1192         if not isinstance(option, basestring):
1193             raise TypeError(u"option keys must be strings")
1194         if not self._allow_no_value or value:
1195             if not isinstance(value, basestring):
1196                 raise TypeError(u"option values must be strings")
1197         return (unicode(section), unicode(option), (value if value is None
1198             else unicode(value)))
1199
1200
1201 class ConfigParser(RawConfigParser):
1202     u"""ConfigParser implementing interpolation."""
1203
1204     _DEFAULT_INTERPOLATION = BasicInterpolation()
1205
1206     def set(self, section, option, value=None):
1207         u"""Set an option.  Extends RawConfigParser.set by validating type and
1208         interpolation syntax on the value."""
1209         _, option, value = self._validate_value_types(option=option, value=value)
1210         super(ConfigParser, self).set(section, option, value)
1211
1212     def add_section(self, section):
1213         u"""Create a new section in the configuration.  Extends
1214         RawConfigParser.add_section by validating if the section name is
1215         a string."""
1216         section, _, _ = self._validate_value_types(section=section)
1217         super(ConfigParser, self).add_section(section)
1218
1219
1220 class SafeConfigParser(ConfigParser):
1221     u"""ConfigParser alias for backwards compatibility purposes."""
1222
1223     def __init__(self, *args, **kwargs):
1224         super(SafeConfigParser, self).__init__(*args, **kwargs)
1225         warnings.warn(
1226             u"The SafeConfigParser class has been renamed to ConfigParser "
1227             u"in Python 3.2. This alias will be removed in future versions."
1228             u" Use ConfigParser directly instead.",
1229             DeprecationWarning, stacklevel=2
1230         )
1231
1232
1233 class SectionProxy(MutableMapping):
1234     u"""A proxy for a single section from a parser."""
1235
1236     def __init__(self, parser, name):
1237         u"""Creates a view on a section of the specified `name` in `parser`."""
1238         self._parser = parser
1239         self._name = name
1240
1241     def __repr__(self):
1242         return u'<Section: {0}>'.format(self._name)
1243
1244     def __getitem__(self, key):
1245         if not self._parser.has_option(self._name, key):
1246             raise KeyError(key)
1247         return self._parser.get(self._name, key)
1248
1249     def __setitem__(self, key, value):
1250         _, key, value = self._parser._validate_value_types(option=key, value=value)
1251         return self._parser.set(self._name, key, value)
1252
1253     def __delitem__(self, key):
1254         if not (self._parser.has_option(self._name, key) and
1255                 self._parser.remove_option(self._name, key)):
1256             raise KeyError(key)
1257
1258     def __contains__(self, key):
1259         return self._parser.has_option(self._name, key)
1260
1261     def __len__(self):
1262         return len(self._options())
1263
1264     def __iter__(self):
1265         return self._options().__iter__()
1266
1267     def _options(self):
1268         if self._name != self._parser.default_section:
1269             return self._parser.options(self._name)
1270         else:
1271             return self._parser.defaults()
1272
1273     def get(self, option, fallback=None, **_3to2kwargs):
1274         if 'vars' in _3to2kwargs: vars = _3to2kwargs['vars']; del _3to2kwargs['vars']
1275         else: vars = None
1276         if 'raw' in _3to2kwargs: raw = _3to2kwargs['raw']; del _3to2kwargs['raw']
1277         else: raw = False
1278         return self._parser.get(self._name, option, raw=raw, vars=vars,
1279                                 fallback=fallback)
1280
1281     def getint(self, option, fallback=None, **_3to2kwargs):
1282         if 'vars' in _3to2kwargs: vars = _3to2kwargs['vars']; del _3to2kwargs['vars']
1283         else: vars = None
1284         if 'raw' in _3to2kwargs: raw = _3to2kwargs['raw']; del _3to2kwargs['raw']
1285         else: raw = False
1286         return self._parser.getint(self._name, option, raw=raw, vars=vars,
1287                                    fallback=fallback)
1288
1289     def getfloat(self, option, fallback=None, **_3to2kwargs):
1290         if 'vars' in _3to2kwargs: vars = _3to2kwargs['vars']; del _3to2kwargs['vars']
1291         else: vars = None
1292         if 'raw' in _3to2kwargs: raw = _3to2kwargs['raw']; del _3to2kwargs['raw']
1293         else: raw = False
1294         return self._parser.getfloat(self._name, option, raw=raw, vars=vars,
1295                                      fallback=fallback)
1296
1297     def getboolean(self, option, fallback=None, **_3to2kwargs):
1298         if 'vars' in _3to2kwargs: vars = _3to2kwargs['vars']; del _3to2kwargs['vars']
1299         else: vars = None
1300         if 'raw' in _3to2kwargs: raw = _3to2kwargs['raw']; del _3to2kwargs['raw']
1301         else: raw = False
1302         return self._parser.getboolean(self._name, option, raw=raw, vars=vars,
1303                                        fallback=fallback)
1304
1305     @property
1306     def parser(self):
1307         # The parser object of the proxy is read-only.
1308         return self._parser
1309
1310     @property
1311     def name(self):
1312         # The name of the section on a proxy is read-only.
1313         return self._name