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