2 # -*- coding: utf-8 -*-
4 u"""Configuration file parser.
6 A configuration file consists of sections, lead by a "[section]" header,
7 and followed by "name: value" entries, with continuations and such in
10 Intrinsic defaults can be specified by passing them into the
11 ConfigParser constructor as a dictionary.
15 ConfigParser -- responsible for parsing a list of
16 configuration files, and managing the parsed database.
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.
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.
32 When `delimiters' is given, it will be used as the set of substrings
33 that divide keys from values.
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
39 When `inline_comment_prefixes' is given, it will be used as the set of
40 substrings that prefix comments in non-empty lines.
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.
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.
50 When `allow_no_value' is True (default: False), options without
51 values are accepted; the value presented for these is None.
54 Return all the configuration section names, sans DEFAULT.
57 Return whether the given section exists.
59 has_option(section, option)
60 Return whether the given option exists in the given section.
63 Return list of configuration options for the named section.
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.
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).
76 Read configuration from a given string.
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
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.
93 getint(section, options, raw=False, vars=None, fallback=_UNSET)
94 Like get(), but convert value to an integer.
96 getfloat(section, options, raw=False, vars=None, fallback=_UNSET)
97 Like get(), but convert value to a float.
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.
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
110 remove_section(section)
111 Remove the given file section and all its options.
113 remove_option(section, option)
114 Remove the given option from the given section.
116 set(section, option, value)
117 Set the given option.
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.
125 from __future__ import with_statement
126 from collections import MutableMapping
129 from collections import OrderedDict as _default_dict
131 from ordereddict import OrderedDict as _default_dict
139 from configparser_helpers import _ChainMap
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"]
148 DEFAULTSECT = u"DEFAULT"
150 MAX_INTERPOLATION_DEPTH = 10
155 class Error(Exception):
156 u"""Base class for ConfigParser exceptions."""
158 def _get_message(self):
159 u"""Getter for 'message'; needed only to override deprecation in
162 return self.__message
164 def _set_message(self, value):
165 u"""Setter for 'message'; needed only to override deprecation in
168 self.__message = value
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)
175 def __init__(self, msg=u''):
177 Exception.__init__(self, msg)
185 class NoSectionError(Error):
186 u"""Raised when no section matches a requested option."""
188 def __init__(self, section):
189 Error.__init__(self, u'No section: %r' % (section,))
190 self.section = section
191 self.args = (section, )
194 class DuplicateSectionError(Error):
195 u"""Raised when a section is repeated in an input source.
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.
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 ")
212 msg.insert(0, u"Section ")
213 Error.__init__(self, u"".join(msg))
214 self.section = section
217 self.args = (section, source, lineno)
220 class DuplicateOptionError(Error):
221 u"""Raised by strict parsers when an option is repeated in an input source.
223 Current implementation raises this exception only when an option is found
224 more than once in a single file, string or dictionary.
227 def __init__(self, section, option, source=None, lineno=None):
228 msg = [repr(option), u" in section ", repr(section),
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 ")
238 msg.insert(0, u"Option ")
239 Error.__init__(self, u"".join(msg))
240 self.section = section
244 self.args = (section, option, source, lineno)
247 class NoOptionError(Error):
248 u"""A requested option was not found."""
250 def __init__(self, option, section):
251 Error.__init__(self, u"No option %r in section: %r" %
254 self.section = section
255 self.args = (option, section)
258 class InterpolationError(Error):
259 u"""Base class for interpolation-related exceptions."""
261 def __init__(self, option, section, msg):
262 Error.__init__(self, msg)
264 self.section = section
265 self.args = (option, section, msg)
268 class InterpolationMissingOptionError(InterpolationError):
269 u"""A string substitution required a setting which was not available."""
271 def __init__(self, option, section, rawval, reference):
272 msg = (u"Bad value substitution:\n"
277 % (section, option, reference, rawval))
278 InterpolationError.__init__(self, option, section, msg)
279 self.reference = reference
280 self.args = (option, section, rawval, reference)
283 class InterpolationSyntaxError(InterpolationError):
284 u"""Raised when the source text contains invalid syntax.
286 Current implementation raises this exception when the source text into
287 which substitutions are made does not conform to the required syntax.
291 class InterpolationDepthError(InterpolationError):
292 u"""Raised when substitutions are nested too deeply."""
294 def __init__(self, option, section, rawval):
295 msg = (u"Value interpolation too deeply recursive:\n"
299 % (section, option, rawval))
300 InterpolationError.__init__(self, option, section, msg)
301 self.args = (option, section, rawval)
304 class ParsingError(Error):
305 u"""Raised when a configuration file does not follow legal syntax."""
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'. "
313 elif not filename and not source:
314 raise ValueError(u"Required argument `source' not given.")
317 Error.__init__(self, u'Source contains parsing errors: %s' % source)
320 self.args = (source, )
324 u"""Deprecated, use `source'."""
326 u"The 'filename' attribute will be removed in future versions. "
327 u"Use 'source' instead.",
328 DeprecationWarning, stacklevel=2
333 def filename(self, value):
334 u"""Deprecated, user `source'."""
336 u"The 'filename' attribute will be removed in future versions. "
337 u"Use 'source' instead.",
338 DeprecationWarning, stacklevel=2
342 def append(self, lineno, line):
343 self.errors.append((lineno, line))
344 self.message += u'\n\t[line %2d]: %s' % (lineno, line)
347 class MissingSectionHeaderError(ParsingError):
348 u"""Raised when a key-value pair is found before any section header."""
350 def __init__(self, filename, lineno, line):
353 u'File contains no section headers.\nfile: %s, line: %d\n%r' %
354 (filename, lineno, line))
355 self.source = filename
358 self.args = (filename, lineno, line)
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.
367 class Interpolation(object):
368 u"""Dummy interpolation that passes the value through with no changes."""
370 def before_get(self, parser, section, option, value, defaults):
373 def before_set(self, parser, section, option, value):
376 def before_read(self, parser, section, option, value):
379 def before_write(self, parser, section, option, value):
383 class BasicInterpolation(Interpolation):
384 u"""Interpolation as implemented in the classic ConfigParser.
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.
391 something: %(dir)s/whatever
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'."""
398 _KEYCRE = re.compile(ur"%\(([^)]+)\)s")
400 def before_get(self, parser, section, option, value, defaults):
402 self._interpolate_some(parser, option, L, value, section, defaults, 1)
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'%')))
413 def _interpolate_some(self, parser, option, accum, rest, section, map,
415 if depth > MAX_INTERPOLATION_DEPTH:
416 raise InterpolationDepthError(option, section, rest)
423 accum.append(rest[:p])
425 # p is no longer used
431 m = self._KEYCRE.match(rest)
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():]
440 raise InterpolationMissingOptionError(
441 option, section, rest, var)
443 self._interpolate_some(parser, option, accum, v,
444 section, map, depth + 1)
448 raise InterpolationSyntaxError(
450 u"'%%' must be followed by '%%' or '(', "
451 u"found: %r" % (rest,))
454 class ExtendedInterpolation(Interpolation):
455 u"""Advanced variant of interpolation, supports the syntax used by
456 `zc.buildout'. Enables interpolation between sections."""
458 _KEYCRE = re.compile(ur"\$\{([^}]+)\}")
460 def before_get(self, parser, section, option, value, defaults):
462 self._interpolate_some(parser, option, L, value, section, defaults, 1)
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'%')))
473 def _interpolate_some(self, parser, option, accum, rest, section, map,
475 if depth > MAX_INTERPOLATION_DEPTH:
476 raise InterpolationDepthError(option, section, rest)
483 accum.append(rest[:p])
485 # p is no longer used
491 m = self._KEYCRE.match(rest)
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():]
501 opt = parser.optionxform(path[0])
505 opt = parser.optionxform(path[1])
506 v = parser.get(sect, opt, raw=True)
508 raise InterpolationSyntaxError(
510 u"More than one ':' found: %r" % (rest,))
511 except (KeyError, NoSectionError, NoOptionError):
512 raise InterpolationMissingOptionError(
513 option, section, rest, u":".join(path))
515 self._interpolate_some(parser, opt, accum, v, sect,
516 dict(parser.items(sect, raw=True)),
521 raise InterpolationSyntaxError(
523 u"'$' must be followed by '$' or '{', "
524 u"found: %r" % (rest,))
527 class LegacyInterpolation(Interpolation):
528 u"""Deprecated interpolation used in old versions of ConfigParser.
529 Use BasicInterpolation or ExtendedInterpolation instead."""
531 _KEYCRE = re.compile(ur"%\(([^)]*)\)s|.")
533 def before_get(self, parser, section, option, value, vars):
535 depth = MAX_INTERPOLATION_DEPTH
536 while depth: # Loop through this until it's done
538 if value and u"%(" in value:
539 replace = functools.partial(self._interpolation_replace,
541 value = self._KEYCRE.sub(replace, value)
545 raise InterpolationMissingOptionError(
546 option, section, rawval, e.args[0])
549 if value and u"%(" in value:
550 raise InterpolationDepthError(option, section, rawval)
553 def before_set(self, parser, section, option, value):
557 def _interpolation_replace(match, parser):
562 return u"%%(%s)s" % parser.optionxform(s)
565 class RawConfigParser(MutableMapping):
566 u"""ConfigParser that does not do interpolation."""
568 # Regular expressions for parsing section headers and options
571 (?P<header>[^]]+) # very permissive!
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
583 (?P<option>.*?) # very permissive!
584 \s*(?: # any number of space/tab,
585 (?P<vi>{delim})\s* # optionally followed by
587 # delimiters, followed by any
589 (?P<value>.*))?$ # everything up to eol
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}
606 def __init__(self, defaults=None, dict_type=_default_dict,
607 allow_no_value=False, **_3to2kwargs):
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']
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)
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
635 d = u"|".join(re.escape(d) for d in delimiters)
637 self._optcre = re.compile(self._OPT_NV_TMPL.format(delim=d),
640 self._optcre = re.compile(self._OPT_TMPL.format(delim=d),
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()
655 return self._defaults
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())
662 def add_section(self, section):
663 u"""Create a new section in the configuration.
665 Raise DuplicateSectionError if a section by the specified name
666 already exists. Raise ValueError if name is DEFAULT.
668 if section == self.default_section:
669 raise ValueError(u'Invalid section name: %r' % section)
671 if section in self._sections:
672 raise DuplicateSectionError(section)
673 self._sections[section] = self._dict()
674 self._proxies[section] = SectionProxy(self, section)
676 def has_section(self, section):
677 u"""Indicate whether the named section is present in the configuration.
679 The DEFAULT section is not acknowledged.
681 return section in self._sections
683 def options(self, section):
684 u"""Return a list of option names for the given section name."""
686 opts = self._sections[section].copy()
688 raise NoSectionError(section)
689 opts.update(self._defaults)
690 return list(opts.keys())
692 def read(self, filenames, encoding=None):
693 u"""Read and parse a filename or a list of filenames.
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.
702 Return list of successfully read files.
704 if isinstance(filenames, unicode):
705 filenames = [filenames]
707 for filename in filenames:
709 with open(filename, encoding=encoding) as fp:
710 self._read(fp, filename)
713 read_ok.append(filename)
716 def read_file(self, f, source=None):
717 u"""Like read() but the argument must be a file-like object.
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.
727 except AttributeError:
729 self._read(f, source)
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)
736 def read_dict(self, dictionary, source=u'<dict>'):
737 u"""Read configuration from a dictionary.
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.
743 All types held in the dictionary are converted to strings during
744 reading, including section names, option names and keys.
746 Optional second argument is the `source' specifying the name of the
747 dictionary being read.
749 elements_added = set()
750 for section, keys in dictionary.items():
751 section = unicode(section)
753 self.add_section(section)
754 except (DuplicateSectionError, ValueError):
755 if self._strict and section in elements_added:
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)
767 def readfp(self, fp, filename=None):
768 u"""Deprecated, use read_file instead."""
770 u"This method will be removed in future versions. "
771 u"Use 'parser.read_file()' instead.",
772 DeprecationWarning, stacklevel=2
774 self.read_file(fp, source=filename)
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']
781 if 'raw' in _3to2kwargs: raw = _3to2kwargs['raw']; del _3to2kwargs['raw']
783 u"""Get an option value for a given section.
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.
790 If interpolation is enabled and the optional argument `raw' is False,
791 all interpolations are expanded in the return values.
793 Arguments `raw', `vars', and `fallback' are keyword only.
795 The section DEFAULT is special.
798 d = self._unify_values(section, vars)
799 except NoSectionError:
800 if fallback is _UNSET:
804 option = self.optionxform(option)
808 if fallback is _UNSET:
809 raise NoOptionError(option, section)
813 if raw or value is None:
816 return self._interpolation.before_get(self, section, option, value,
819 def _get(self, section, conv, option, **kwargs):
820 return conv(self.get(section, option, **kwargs))
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']
827 if 'raw' in _3to2kwargs: raw = _3to2kwargs['raw']; del _3to2kwargs['raw']
830 return self._get(section, int, option, raw=raw, vars=vars)
831 except (NoSectionError, NoOptionError):
832 if fallback is _UNSET:
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']
842 if 'raw' in _3to2kwargs: raw = _3to2kwargs['raw']; del _3to2kwargs['raw']
845 return self._get(section, float, option, raw=raw, vars=vars)
846 except (NoSectionError, NoOptionError):
847 if fallback is _UNSET:
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']
857 if 'raw' in _3to2kwargs: raw = _3to2kwargs['raw']; del _3to2kwargs['raw']
860 return self._get(section, self._convert_to_boolean, option,
862 except (NoSectionError, NoOptionError):
863 if fallback is _UNSET:
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.
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.
877 The section DEFAULT is special.
879 if section is _UNSET:
880 return super(RawConfigParser, self).items()
881 d = self._defaults.copy()
883 d.update(self._sections[section])
885 if section != self.default_section:
886 raise NoSectionError(section)
887 # Update with the entry specific variables
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)
894 value_getter = lambda option: d[option]
895 return [(option, value_getter(option)) for option in d.keys()]
897 def optionxform(self, optionstr):
898 return optionstr.lower()
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:
910 option = self.optionxform(option)
911 return (option in self._sections[section]
912 or option in self._defaults)
914 def set(self, section, option, value=None):
915 u"""Set an option."""
917 value = self._interpolation.before_set(self, section, option,
919 if not section or section == self.default_section:
920 sectdict = self._defaults
923 sectdict = self._sections[section]
925 raise NoSectionError(section)
926 sectdict[self.optionxform(option)] = value
928 def write(self, fp, space_around_delimiters=True):
929 u"""Write an .ini-format representation of the configuration state.
931 If `space_around_delimiters' is True (the default), delimiters
932 between keys and values are surrounded by spaces.
934 if space_around_delimiters:
935 d = u" {0} ".format(self._delimiters[0])
937 d = self._delimiters[0]
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)
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,
951 if value is not None or not self._allow_no_value:
952 value = delimiter + unicode(value).replace(u'\n', u'\n\t')
955 fp.write(u"{0}{1}\n".format(key, value))
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
964 sectdict = self._sections[section]
966 raise NoSectionError(section)
967 option = self.optionxform(option)
968 existed = option in sectdict
973 def remove_section(self, section):
974 u"""Remove a file section."""
975 existed = section in self._sections
977 del self._sections[section]
978 del self._proxies[section]
981 def __getitem__(self, key):
982 if key != self.default_section and not self.has_section(key):
984 return self._proxies[key]
986 def __setitem__(self, key, value):
987 # To conform with the mapping protocol, overwrites existing values in
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})
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):
1000 self.remove_section(key)
1002 def __contains__(self, key):
1003 return key == self.default_section or self.has_section(key)
1006 return len(self._sections) + 1 # the default section
1009 # XXX does it break when underlying container state changed?
1010 return itertools.chain((self.default_section,), self._sections.keys())
1012 def _read(self, fp, fpname):
1013 u"""Parse a sectioned configuration file.
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
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.
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
1029 elements_added = set()
1030 cursect = None # None, or a dictionary
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
1044 # strip full line comments
1045 for prefix in self._comment_prefixes:
1046 if line.strip().startswith(prefix):
1049 value = line[:comment_start].strip()
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
1057 cursect[optname] is not None):
1058 cursect[optname].append(u'') # newlines added at join
1060 # empty line marks end of value
1061 indent_level = sys.maxsize
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?
1071 indent_level = cur_indent_level
1072 # is it a section header?
1073 mo = self.SECTCRE.match(value)
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,
1080 cursect = self._sections[sectname]
1081 elements_added.add(sectname)
1082 elif sectname == self.default_section:
1083 cursect = self._defaults
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
1091 # no section header in the file?
1092 elif cursect is None:
1093 raise MissingSectionHeaderError(fpname, lineno, line)
1096 mo = self._optcre.match(value)
1098 optname, vi, optval = mo.group(u'option', u'vi', u'value')
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,
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]
1113 # valueless option handling
1114 cursect[optname] = None
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
1124 self._join_multiline_values()
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,
1138 def _handle_error(self, exc, fpname, lineno, line):
1140 exc = ParsingError(fpname)
1141 exc.append(lineno, repr(line))
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.
1151 sectiondict = self._sections[section]
1153 if section != self.default_section:
1154 raise NoSectionError(section)
1155 # Update with the entry specific variables
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)
1164 def _convert_to_boolean(self, value):
1165 u"""Return a boolean value translating from other types if necessary.
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()]
1171 def _validate_value_types(self, **_3to2kwargs):
1172 if 'value' in _3to2kwargs: value = _3to2kwargs['value']; del _3to2kwargs['value']
1174 if 'option' in _3to2kwargs: option = _3to2kwargs['option']; del _3to2kwargs['option']
1176 if 'section' in _3to2kwargs: section = _3to2kwargs['section']; del _3to2kwargs['section']
1178 u"""Raises a TypeError for non-string values.
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
1183 - we do not allow valueless options, or
1184 - we allow valueless options but the value is not None
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().
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)))
1201 class ConfigParser(RawConfigParser):
1202 u"""ConfigParser implementing interpolation."""
1204 _DEFAULT_INTERPOLATION = BasicInterpolation()
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)
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
1216 section, _, _ = self._validate_value_types(section=section)
1217 super(ConfigParser, self).add_section(section)
1220 class SafeConfigParser(ConfigParser):
1221 u"""ConfigParser alias for backwards compatibility purposes."""
1223 def __init__(self, *args, **kwargs):
1224 super(SafeConfigParser, self).__init__(*args, **kwargs)
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
1233 class SectionProxy(MutableMapping):
1234 u"""A proxy for a single section from a parser."""
1236 def __init__(self, parser, name):
1237 u"""Creates a view on a section of the specified `name` in `parser`."""
1238 self._parser = parser
1242 return u'<Section: {0}>'.format(self._name)
1244 def __getitem__(self, key):
1245 if not self._parser.has_option(self._name, key):
1247 return self._parser.get(self._name, key)
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)
1253 def __delitem__(self, key):
1254 if not (self._parser.has_option(self._name, key) and
1255 self._parser.remove_option(self._name, key)):
1258 def __contains__(self, key):
1259 return self._parser.has_option(self._name, key)
1262 return len(self._options())
1265 return self._options().__iter__()
1268 if self._name != self._parser.default_section:
1269 return self._parser.options(self._name)
1271 return self._parser.defaults()
1273 def get(self, option, fallback=None, **_3to2kwargs):
1274 if 'vars' in _3to2kwargs: vars = _3to2kwargs['vars']; del _3to2kwargs['vars']
1276 if 'raw' in _3to2kwargs: raw = _3to2kwargs['raw']; del _3to2kwargs['raw']
1278 return self._parser.get(self._name, option, raw=raw, vars=vars,
1281 def getint(self, option, fallback=None, **_3to2kwargs):
1282 if 'vars' in _3to2kwargs: vars = _3to2kwargs['vars']; del _3to2kwargs['vars']
1284 if 'raw' in _3to2kwargs: raw = _3to2kwargs['raw']; del _3to2kwargs['raw']
1286 return self._parser.getint(self._name, option, raw=raw, vars=vars,
1289 def getfloat(self, option, fallback=None, **_3to2kwargs):
1290 if 'vars' in _3to2kwargs: vars = _3to2kwargs['vars']; del _3to2kwargs['vars']
1292 if 'raw' in _3to2kwargs: raw = _3to2kwargs['raw']; del _3to2kwargs['raw']
1294 return self._parser.getfloat(self._name, option, raw=raw, vars=vars,
1297 def getboolean(self, option, fallback=None, **_3to2kwargs):
1298 if 'vars' in _3to2kwargs: vars = _3to2kwargs['vars']; del _3to2kwargs['vars']
1300 if 'raw' in _3to2kwargs: raw = _3to2kwargs['raw']; del _3to2kwargs['raw']
1302 return self._parser.getboolean(self._name, option, raw=raw, vars=vars,
1307 # The parser object of the proxy is read-only.
1312 # The name of the section on a proxy is read-only.