16
16
# http://lists.sourceforge.net/lists/listinfo/configobj-develop
17
17
# Comments, suggestions and bug reports welcome.
19
20
from __future__ import generators
22
INTP_VER = sys.version_info[:2]
24
raise RuntimeError("Python v.2.2 or later needed")
33
from types import StringTypes
34
from warnings import warn
27
# Bzr modification: Disabled import of 'compiler' module
28
# bzr doesn't use the 'unrepr' feature of configobj, so importing compiler just
29
# wastes several milliseconds on every single bzr invocation.
30
# -- Andrew Bennetts, 2008-10-14
36
39
from codecs import BOM_UTF8, BOM_UTF16, BOM_UTF16_BE, BOM_UTF16_LE
37
40
except ImportError:
489
def __newobj__(cls, *args):
491
return cls.__new__(cls, *args)
491
493
class Section(dict):
493
495
A dictionary-like object that represents a section in a config file.
495
497
It does string interpolation if the 'interpolation' attribute
496
498
of the 'main' object is set to True.
498
500
Interpolation is tried first from this object, then from the 'DEFAULT'
499
501
section of this object, next from the parent and its 'DEFAULT' section,
500
502
and so on until the main object is reached.
502
504
A Section will behave like an ordered dictionary - following the
503
505
order of the ``scalars`` and ``sections`` attributes.
504
506
You can use this to change the order of members.
506
508
Iteration follows the order: scalars, then sections.
512
def __setstate__(self, state):
513
dict.update(self, state[0])
514
self.__dict__.update(state[1])
516
def __reduce__(self):
517
state = (dict(self), self.__dict__)
518
return (__newobj__, (self.__class__,), state)
509
521
def __init__(self, parent, depth, main, indict=None, name=None):
511
523
* parent is the section above
586
593
def __setitem__(self, key, value, unrepr=False):
588
595
Correctly set a value.
590
597
Making dictionary values Section instances.
591
598
(We have to special case 'Section' instances - which are also dicts)
593
600
Keys must be strings.
594
601
Values need only be strings (or lists of strings) if
595
602
``main.stringify`` is set.
597
`unrepr`` must be set when setting a value to a dictionary, without
604
``unrepr`` must be set when setting a value to a dictionary, without
598
605
creating a new sub-section.
600
if not isinstance(key, StringTypes):
607
if not isinstance(key, basestring):
601
608
raise ValueError('The key "%s" is not a string.' % key)
603
610
# add the comment
604
if not self.comments.has_key(key):
611
if key not in self.comments:
605
612
self.comments[key] = []
606
613
self.inline_comments[key] = ''
607
614
# remove the entry from defaults
856
863
call_on_sections=False, **keywargs):
858
865
Walk every member and call a function on the keyword and value.
860
867
Return a dictionary of the return values
862
869
If the function raises an exception, raise the errror
863
870
unless ``raise_errors=False``, in which case set the return value to
866
873
Any unrecognised keyword arguments you pass to walk, will be pased on
867
874
to the function you pass in.
869
876
Note: if ``call_on_sections`` is ``True`` then - on encountering a
870
877
subsection, *first* the function is called for the *whole* subsection,
871
878
and then recurses into it's members. This means your function must be
872
879
able to handle strings, dictionaries and lists. This allows you
873
880
to change the key of subsections as well as for ordinary members. The
874
881
return value when called on the whole subsection has to be discarded.
876
883
See the encode and decode methods for examples, including functions.
885
.. admonition:: caution
880
887
You can use ``walk`` to transform the names of members of a section
881
888
but you mustn't add or delete members.
883
890
>>> config = '''[XXXXsection]
884
891
... XXXXkey = XXXXvalue'''.splitlines()
885
892
>>> cfg = ConfigObj(config)
887
{'XXXXsection': {'XXXXkey': 'XXXXvalue'}}
894
ConfigObj({'XXXXsection': {'XXXXkey': 'XXXXvalue'}})
888
895
>>> def transform(section, key):
889
896
... val = section[key]
890
897
... newkey = key.replace('XXXX', 'CLIENT1')
940
def decode(self, encoding):
942
Decode all strings and values to unicode, using the specified encoding.
944
Works with subsections and list values.
946
Uses the ``walk`` method.
948
Testing ``encode`` and ``decode``.
950
>>> m.decode('ascii')
951
>>> def testuni(val):
952
... for entry in val:
953
... if not isinstance(entry, unicode):
954
... print >> sys.stderr, type(entry)
955
... raise AssertionError, 'decode failed.'
956
... if isinstance(val[entry], dict):
957
... testuni(val[entry])
958
... elif not isinstance(val[entry], unicode):
959
... raise AssertionError, 'decode failed.'
961
>>> m.encode('ascii')
965
warn('use of ``decode`` is deprecated.', DeprecationWarning)
966
def decode(section, key, encoding=encoding, warn=True):
969
if isinstance(val, (list, tuple)):
972
newval.append(entry.decode(encoding))
973
elif isinstance(val, dict):
976
newval = val.decode(encoding)
977
newkey = key.decode(encoding)
978
section.rename(key, newkey)
979
section[newkey] = newval
980
# using ``call_on_sections`` allows us to modify section names
981
self.walk(decode, call_on_sections=True)
984
def encode(self, encoding):
986
Encode all strings and values from unicode,
987
using the specified encoding.
989
Works with subsections and list values.
990
Uses the ``walk`` method.
992
warn('use of ``encode`` is deprecated.', DeprecationWarning)
993
def encode(section, key, encoding=encoding):
996
if isinstance(val, (list, tuple)):
999
newval.append(entry.encode(encoding))
1000
elif isinstance(val, dict):
1003
newval = val.encode(encoding)
1004
newkey = key.encode(encoding)
1005
section.rename(key, newkey)
1006
section[newkey] = newval
1007
self.walk(encode, call_on_sections=True)
1010
def istrue(self, key):
1011
"""A deprecated version of ``as_bool``."""
1012
warn('use of ``istrue`` is deprecated. Use ``as_bool`` method '
1013
'instead.', DeprecationWarning)
1014
return self.as_bool(key)
1017
947
def as_bool(self, key):
1019
949
Accepts a key as input. The corresponding value must be a string or
1020
950
the objects (``True`` or 1) or (``False`` or 0). We allow 0 and 1 to
1021
951
retain compatibility with Python 2.2.
1023
If the string is one of ``True``, ``On``, ``Yes``, or ``1`` it returns
953
If the string is one of ``True``, ``On``, ``Yes``, or ``1`` it returns
1026
If the string is one of ``False``, ``Off``, ``No``, or ``0`` it returns
956
If the string is one of ``False``, ``Off``, ``No``, or ``0`` it returns
1029
959
``as_bool`` is not case sensitive.
1031
961
Any other input will raise a ``ValueError``.
1033
963
>>> a = ConfigObj()
1034
964
>>> a['a'] = 'fish'
1035
965
>>> a.as_bool('a')
1242
def __init__(self, infile=None, options=None, **kwargs):
1194
def __init__(self, infile=None, options=None, _inspec=False, **kwargs):
1244
1196
Parse a config file or create a config file object.
1246
1198
``ConfigObj(infile=None, options=None, **kwargs)``
1200
self._inspec = _inspec
1248
1201
# init the superclass
1249
1202
Section.__init__(self, self, 0, self)
1256
options = dict(options)
1204
infile = infile or []
1205
options = dict(options or {})
1258
1207
# keyword arguments take precedence over an options dictionary
1259
1208
options.update(kwargs)
1210
options['list_values'] = False
1261
1212
defaults = OPTION_DEFAULTS.copy()
1262
1213
# TODO: check the values too.
1263
1214
for entry in options:
1264
1215
if entry not in defaults:
1265
1216
raise TypeError('Unrecognised option "%s".' % entry)
1267
1218
# Add any explicit options to the defaults
1268
1219
defaults.update(options)
1269
1220
self._initialise(defaults)
1270
1221
configspec = defaults['configspec']
1271
1222
self._original_configspec = configspec
1272
1223
self._load(infile, configspec)
1275
1226
def _load(self, infile, configspec):
1276
if isinstance(infile, StringTypes):
1227
if isinstance(infile, basestring):
1277
1228
self.filename = infile
1278
1229
if os.path.isfile(infile):
1279
1230
h = open(infile, 'rb')
1295
1246
elif isinstance(infile, (list, tuple)):
1296
1247
infile = list(infile)
1298
1249
elif isinstance(infile, dict):
1299
1250
# initialise self
1300
1251
# the Section class handles creating subsections
1301
1252
if isinstance(infile, ConfigObj):
1302
1253
# get a copy of our ConfigObj
1303
1254
infile = infile.dict()
1305
1256
for entry in infile:
1306
1257
self[entry] = infile[entry]
1307
1258
del self._errors
1309
1260
if configspec is not None:
1310
1261
self._handle_configspec(configspec)
1312
1263
self.configspec = None
1315
elif getattr(infile, 'read', None) is not None:
1266
elif getattr(infile, 'read', MISSING) is not MISSING:
1316
1267
# This supports file like objects
1317
1268
infile = infile.read() or []
1318
1269
# needs splitting into lines - but needs doing *after* decoding
1319
1270
# in case it's not an 8 bit encoding
1321
1272
raise TypeError('infile must be a filename, file like object, or list of lines.')
1324
1275
# don't do it for the empty ConfigObj
1325
1276
infile = self._handle_bom(infile)
1382
1333
self.newlines = None
1383
1334
self.write_empty_values = options['write_empty_values']
1384
1335
self.unrepr = options['unrepr']
1386
1337
self.initial_comment = []
1387
1338
self.final_comment = []
1388
self.configspec = {}
1339
self.configspec = None
1342
self.list_values = False
1390
1344
# Clear section attributes as well
1391
1345
Section._initialise(self)
1394
1348
def __repr__(self):
1395
return ('ConfigObj({%s})' %
1396
', '.join([('%s: %s' % (repr(key), repr(self[key])))
1349
return ('ConfigObj({%s})' %
1350
', '.join([('%s: %s' % (repr(key), repr(self[key])))
1397
1351
for key in (self.scalars + self.sections)]))
1400
1354
def _handle_bom(self, infile):
1402
1356
Handle any BOM, and decode if necessary.
1404
1358
If an encoding is specified, that *must* be used - but the BOM should
1405
1359
still be removed (and the BOM attribute set).
1407
1361
(If the encoding is wrongly specified, then a BOM for an alternative
1408
1362
encoding won't be discovered or removed.)
1410
1364
If an encoding is not specified, UTF8 or UTF16 BOM will be detected and
1411
1365
removed. The BOM attribute will be set. UTF16 will be decoded to
1414
1368
NOTE: This method must not be called with an empty ``infile``.
1416
1370
Specifying the *wrong* encoding is likely to cause a
1417
1371
``UnicodeDecodeError``.
1419
1373
``infile`` must always be returned as a list of lines, but may be
1420
1374
passed in as a single string.
1761
1715
def _quote(self, value, multiline=True):
1763
1717
Return a safely quoted version of a value.
1765
1719
Raise a ConfigObjError if the value cannot be safely quoted.
1766
1720
If multiline is ``True`` (default) then use triple quotes
1769
Don't quote values that don't need it.
1770
Recursively quote members of a list and return a comma joined list.
1771
Multiline is ``False`` for lists.
1772
Obey list syntax for empty and single member lists.
1723
* Don't quote values that don't need it.
1724
* Recursively quote members of a list and return a comma joined list.
1725
* Multiline is ``False`` for lists.
1726
* Obey list syntax for empty and single member lists.
1774
1728
If ``list_values=False`` then the value is only quoted if it contains
1775
a ``\n`` (is multiline) or '#'.
1729
a ``\\n`` (is multiline) or '#'.
1777
1731
If ``write_empty_values`` is set, and the value is an empty string, it
1778
1732
won't be quoted.
1931
1890
def _handle_configspec(self, configspec):
1932
1891
"""Parse the configspec."""
1933
# FIXME: Should we check that the configspec was created with the
1892
# FIXME: Should we check that the configspec was created with the
1934
1893
# correct settings ? (i.e. ``list_values=False``)
1935
1894
if not isinstance(configspec, ConfigObj):
1937
1896
configspec = ConfigObj(configspec,
1938
1897
raise_errors=True,
1939
1898
file_error=True,
1941
1900
except ConfigObjError, e:
1942
1901
# FIXME: Should these errors have a reference
1943
1902
# to the already parsed ConfigObj ?
1944
1903
raise ConfigspecError('Parsing configspec failed: %s' % e)
1945
1904
except IOError, e:
1946
1905
raise IOError('Reading configspec failed: %s' % e)
1948
self._set_configspec_value(configspec, self)
1951
def _set_configspec_value(self, configspec, section):
1952
"""Used to recursively set configspec values."""
1953
if '__many__' in configspec.sections:
1954
section.configspec['__many__'] = configspec['__many__']
1955
if len(configspec.sections) > 1:
1956
# FIXME: can we supply any useful information here ?
1957
raise RepeatSectionError()
1959
if getattr(configspec, 'initial_comment', None) is not None:
1960
section._configspec_initial_comment = configspec.initial_comment
1961
section._configspec_final_comment = configspec.final_comment
1962
section._configspec_encoding = configspec.encoding
1963
section._configspec_BOM = configspec.BOM
1964
section._configspec_newlines = configspec.newlines
1965
section._configspec_indent_type = configspec.indent_type
1967
for entry in configspec.scalars:
1968
section._configspec_comments[entry] = configspec.comments[entry]
1969
section._configspec_inline_comments[entry] = configspec.inline_comments[entry]
1970
section.configspec[entry] = configspec[entry]
1971
section._order.append(entry)
1907
self.configspec = configspec
1911
def _set_configspec(self, section, copy):
1913
Called by validate. Handles setting the configspec on subsections
1914
including sections to be validated by __many__
1916
configspec = section.configspec
1917
many = configspec.get('__many__')
1918
if isinstance(many, dict):
1919
for entry in section.sections:
1920
if entry not in configspec:
1921
section[entry].configspec = many
1973
1923
for entry in configspec.sections:
1974
1924
if entry == '__many__':
1977
section._cs_section_comments[entry] = configspec.comments[entry]
1978
section._cs_section_inline_comments[entry] = configspec.inline_comments[entry]
1979
if not section.has_key(entry):
1981
self._set_configspec_value(configspec[entry], section[entry])
1984
def _handle_repeat(self, section, configspec):
1985
"""Dynamically assign configspec for repeated section."""
1987
section_keys = configspec.sections
1988
scalar_keys = configspec.scalars
1989
except AttributeError:
1990
section_keys = [entry for entry in configspec
1991
if isinstance(configspec[entry], dict)]
1992
scalar_keys = [entry for entry in configspec
1993
if not isinstance(configspec[entry], dict)]
1995
if '__many__' in section_keys and len(section_keys) > 1:
1996
# FIXME: can we supply any useful information here ?
1997
raise RepeatSectionError()
2001
for entry in scalar_keys:
2002
val = configspec[entry]
2003
scalars[entry] = val
2004
for entry in section_keys:
2005
val = configspec[entry]
2006
if entry == '__many__':
2007
scalars[entry] = val
2009
sections[entry] = val
2011
section.configspec = scalars
2012
for entry in sections:
2013
if not section.has_key(entry):
2015
self._handle_repeat(section[entry], sections[entry])
1926
if entry not in section:
1930
section.comments[entry] = configspec.comments.get(entry, [])
1931
section.inline_comments[entry] = configspec.inline_comments.get(entry, '')
1933
# Could be a scalar when we expect a section
1934
if isinstance(section[entry], Section):
1935
section[entry].configspec = configspec[entry]
2018
1938
def _write_line(self, indent_string, entry, this_entry, comment):
2160
2080
Test the ConfigObj against a configspec.
2162
2082
It uses the ``validator`` object from *validate.py*.
2164
2084
To run ``validate`` on the current ConfigObj, call: ::
2166
2086
test = config.validate(validator)
2168
2088
(Normally having previously passed in the configspec when the ConfigObj
2169
2089
was created - you can dynamically assign a dictionary of checks to the
2170
2090
``configspec`` attribute of a section though).
2172
2092
It returns ``True`` if everything passes, or a dictionary of
2173
2093
pass/fails (True/False). If every member of a subsection passes, it
2174
2094
will just have the value ``True``. (It also returns ``False`` if all
2177
2097
In addition, it converts the values from strings to their native
2178
2098
types if their checks pass (and ``stringify`` is set).
2180
2100
If ``preserve_errors`` is ``True`` (``False`` is default) then instead
2181
2101
of a marking a fail with a ``False``, it will preserve the actual
2182
2102
exception object. This can contain info about the reason for failure.
2183
2103
For example the ``VdtValueTooSmallError`` indicates that the value
2184
2104
supplied was too small. If a value (or section) is missing it will
2185
2105
still be marked as ``False``.
2187
2107
You must have the validate module to use ``preserve_errors=True``.
2189
2109
You can then use the ``flatten_errors`` function to turn your nested
2190
2110
results dictionary into a flattened list of failures - useful for
2191
2111
displaying meaningful error messages.
2198
2118
# Which makes importing configobj faster
2199
2119
from validate import VdtMissingValue
2200
2120
self._vdtMissingValue = VdtMissingValue
2203
spec_section = section.configspec
2204
if copy and getattr(section, '_configspec_initial_comment', None) is not None:
2205
section.initial_comment = section._configspec_initial_comment
2206
section.final_comment = section._configspec_final_comment
2207
section.encoding = section._configspec_encoding
2208
section.BOM = section._configspec_BOM
2209
section.newlines = section._configspec_newlines
2210
section.indent_type = section._configspec_indent_type
2212
if '__many__' in section.configspec:
2213
many = spec_section['__many__']
2214
# dynamically assign the configspecs
2215
# for the sections below
2216
for entry in section.sections:
2217
self._handle_repeat(section[entry], many)
2222
order = [k for k in section._order if k in spec_section]
2223
order += [k for k in spec_section if k not in order]
2225
if entry == '__many__':
2227
if (not entry in section.scalars) or (entry in section.defaults):
2229
# or entries from defaults
2232
if copy and not entry in section.scalars:
2234
section.comments[entry] = (
2235
section._configspec_comments.get(entry, []))
2236
section.inline_comments[entry] = (
2237
section._configspec_inline_comments.get(entry, ''))
2241
val = section[entry]
2125
section.initial_comment = section.configspec.initial_comment
2126
section.final_comment = section.configspec.final_comment
2127
section.encoding = section.configspec.encoding
2128
section.BOM = section.configspec.BOM
2129
section.newlines = section.configspec.newlines
2130
section.indent_type = section.configspec.indent_type
2133
configspec = section.configspec
2134
self._set_configspec(section, copy)
2136
def validate_entry(entry, spec, val, missing, ret_true, ret_false):
2243
check = validator.check(spec_section[entry],
2138
check = validator.check(spec,
2245
2140
missing=missing
2287
2181
section[entry] = check
2288
2182
if not copy and missing and entry not in section.defaults:
2289
2183
section.defaults.append(entry)
2184
return ret_true, ret_false
2191
unvalidated = [k for k in section.scalars if k not in configspec]
2192
incorrect_sections = [k for k in configspec.sections if k in section.scalars]
2193
incorrect_scalars = [k for k in configspec.scalars if k in section.sections]
2195
for entry in configspec.scalars:
2196
if entry in ('__many__', '___many___'):
2200
if (not entry in section.scalars) or (entry in section.defaults):
2202
# or entries from defaults
2205
if copy and not entry in section.scalars:
2207
section.comments[entry] = (
2208
configspec.comments.get(entry, []))
2209
section.inline_comments[entry] = (
2210
configspec.inline_comments.get(entry, ''))
2214
val = section[entry]
2216
ret_true, ret_false = validate_entry(entry, configspec[entry], val,
2217
missing, ret_true, ret_false)
2220
if '__many__' in configspec.scalars:
2221
many = configspec['__many__']
2222
elif '___many___' in configspec.scalars:
2223
many = configspec['___many___']
2225
if many is not None:
2226
for entry in unvalidated:
2227
val = section[entry]
2228
ret_true, ret_false = validate_entry(entry, many, val, False,
2229
ret_true, ret_false)
2231
for entry in incorrect_scalars:
2233
if not preserve_errors:
2237
msg = 'Value %r was provided as a section' % entry
2238
out[entry] = validator.baseErrorClass(msg)
2239
for entry in incorrect_sections:
2241
if not preserve_errors:
2245
msg = 'Section %r was provided as a single value' % entry
2246
out[entry] = validator.baseErrorClass(msg)
2290
2248
# Missing sections will have been created as empty ones when the
2291
2249
# configspec was read.
2292
2250
for entry in section.sections:
2293
2251
# FIXME: this means DEFAULT is not copied in copy mode
2294
2252
if section is self and entry == 'DEFAULT':
2254
if section[entry].configspec is None:
2297
section.comments[entry] = section._cs_section_comments[entry]
2298
section.inline_comments[entry] = (
2299
section._cs_section_inline_comments[entry])
2300
check = self.validate(validator, preserve_errors=preserve_errors,
2301
copy=copy, section=section[entry])
2257
section.comments[entry] = configspec.comments.get(entry, [])
2258
section.inline_comments[entry] = configspec.inline_comments.get(entry, '')
2259
check = self.validate(validator, preserve_errors=preserve_errors, copy=copy, section=section[entry])
2302
2260
out[entry] = check
2303
2261
if check == False:
2304
2262
ret_true = False
2342
2300
if entry == 'configspec':
2344
2302
current_options[entry] = getattr(self, entry)
2346
2304
configspec = self._original_configspec
2347
2305
current_options['configspec'] = configspec
2350
2308
self._initialise(current_options)
2351
2309
self._load(filename, configspec)
2355
2313
class SimpleVal(object):
2357
2315
A simple validator.
2358
2316
Can be used to check that all members expected are present.
2360
2318
To use it, provide a configspec with all your members in (the value given
2361
2319
will be ignored). Pass an instance of ``SimpleVal`` to the ``validate``
2362
2320
method of your ``ConfigObj``. ``validate`` will return ``True`` if all
2363
2321
members are present, or a dictionary with True/False meaning
2364
2322
present/missing. (Whole missing sections will be replaced with ``False``)
2367
2325
def __init__(self):
2368
2326
self.baseErrorClass = ConfigObjError
2370
2328
def check(self, check, member, missing=False):
2371
2329
"""A dummy check method, always returns the value unchanged."""
2380
2338
An example function that will turn a nested dictionary of results
2381
2339
(as returned by ``ConfigObj.validate``) into a flat list.
2383
2341
``cfg`` is the ConfigObj instance being checked, ``res`` is the results
2384
2342
dictionary returned by ``validate``.
2386
2344
(This is a recursive function, so you shouldn't use the ``levels`` or
2387
``results`` arguments - they are used by the function.
2345
``results`` arguments - they are used by the function.)
2389
2347
Returns a list of keys that failed. Each member of the list is a tuple :
2392
2351
([list of sections...], key, result)
2394
2353
If ``validate`` was called with ``preserve_errors=False`` (the default)
2395
2354
then ``result`` will always be ``False``.
2397
2356
*list of sections* is a flattened list of sections that the key was found
2400
If the section was missing then key will be ``None``.
2359
If the section was missing (or a section was expected and a scalar provided
2360
- or vice-versa) then key will be ``None``.
2402
2362
If the value (or section) was missing then ``result`` will be ``False``.
2404
2364
If ``validate`` was called with ``preserve_errors=True`` and a value
2405
2365
was present, but failed the check, then ``result`` will be the exception
2406
2366
object returned. You can use this as a string that describes the failure.
2408
2368
For example *The value "3" is of the wrong type*.
2410
2370
>>> import validate
2411
2371
>>> vtor = validate.Validator()
2412
2372
>>> my_ini = '''
added
removed
bzrlib/util/configobj/configobj.py
