489
def __newobj__(cls, *args):
491
return cls.__new__(cls, *args)
495
493
class Section(dict):
497
495
A dictionary-like object that represents a section in a config file.
499
497
It does string interpolation if the 'interpolation' attribute
500
498
of the 'main' object is set to True.
502
500
Interpolation is tried first from this object, then from the 'DEFAULT'
503
501
section of this object, next from the parent and its 'DEFAULT' section,
504
502
and so on until the main object is reached.
506
504
A Section will behave like an ordered dictionary - following the
507
505
order of the ``scalars`` and ``sections`` attributes.
508
506
You can use this to change the order of members.
510
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)
513
521
def __init__(self, parent, depth, main, indict=None, name=None):
515
523
* parent is the section above
590
593
def __setitem__(self, key, value, unrepr=False):
592
595
Correctly set a value.
594
597
Making dictionary values Section instances.
595
598
(We have to special case 'Section' instances - which are also dicts)
597
600
Keys must be strings.
598
601
Values need only be strings (or lists of strings) if
599
602
``main.stringify`` is set.
601
`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
602
605
creating a new sub-section.
604
if not isinstance(key, StringTypes):
607
if not isinstance(key, basestring):
605
608
raise ValueError('The key "%s" is not a string.' % key)
607
610
# add the comment
608
if not self.comments.has_key(key):
611
if key not in self.comments:
609
612
self.comments[key] = []
610
613
self.inline_comments[key] = ''
611
614
# remove the entry from defaults
860
863
call_on_sections=False, **keywargs):
862
865
Walk every member and call a function on the keyword and value.
864
867
Return a dictionary of the return values
866
869
If the function raises an exception, raise the errror
867
870
unless ``raise_errors=False``, in which case set the return value to
870
873
Any unrecognised keyword arguments you pass to walk, will be pased on
871
874
to the function you pass in.
873
876
Note: if ``call_on_sections`` is ``True`` then - on encountering a
874
877
subsection, *first* the function is called for the *whole* subsection,
875
878
and then recurses into it's members. This means your function must be
876
879
able to handle strings, dictionaries and lists. This allows you
877
880
to change the key of subsections as well as for ordinary members. The
878
881
return value when called on the whole subsection has to be discarded.
880
883
See the encode and decode methods for examples, including functions.
885
.. admonition:: caution
884
887
You can use ``walk`` to transform the names of members of a section
885
888
but you mustn't add or delete members.
887
890
>>> config = '''[XXXXsection]
888
891
... XXXXkey = XXXXvalue'''.splitlines()
889
892
>>> cfg = ConfigObj(config)
891
{'XXXXsection': {'XXXXkey': 'XXXXvalue'}}
894
ConfigObj({'XXXXsection': {'XXXXkey': 'XXXXvalue'}})
892
895
>>> def transform(section, key):
893
896
... val = section[key]
894
897
... newkey = key.replace('XXXX', 'CLIENT1')
944
def decode(self, encoding):
946
Decode all strings and values to unicode, using the specified encoding.
948
Works with subsections and list values.
950
Uses the ``walk`` method.
952
Testing ``encode`` and ``decode``.
954
>>> m.decode('ascii')
955
>>> def testuni(val):
956
... for entry in val:
957
... if not isinstance(entry, unicode):
958
... print >> sys.stderr, type(entry)
959
... raise AssertionError, 'decode failed.'
960
... if isinstance(val[entry], dict):
961
... testuni(val[entry])
962
... elif not isinstance(val[entry], unicode):
963
... raise AssertionError, 'decode failed.'
965
>>> m.encode('ascii')
969
warn('use of ``decode`` is deprecated.', DeprecationWarning)
970
def decode(section, key, encoding=encoding, warn=True):
973
if isinstance(val, (list, tuple)):
976
newval.append(entry.decode(encoding))
977
elif isinstance(val, dict):
980
newval = val.decode(encoding)
981
newkey = key.decode(encoding)
982
section.rename(key, newkey)
983
section[newkey] = newval
984
# using ``call_on_sections`` allows us to modify section names
985
self.walk(decode, call_on_sections=True)
988
def encode(self, encoding):
990
Encode all strings and values from unicode,
991
using the specified encoding.
993
Works with subsections and list values.
994
Uses the ``walk`` method.
996
warn('use of ``encode`` is deprecated.', DeprecationWarning)
997
def encode(section, key, encoding=encoding):
1000
if isinstance(val, (list, tuple)):
1003
newval.append(entry.encode(encoding))
1004
elif isinstance(val, dict):
1007
newval = val.encode(encoding)
1008
newkey = key.encode(encoding)
1009
section.rename(key, newkey)
1010
section[newkey] = newval
1011
self.walk(encode, call_on_sections=True)
1014
def istrue(self, key):
1015
"""A deprecated version of ``as_bool``."""
1016
warn('use of ``istrue`` is deprecated. Use ``as_bool`` method '
1017
'instead.', DeprecationWarning)
1018
return self.as_bool(key)
1021
947
def as_bool(self, key):
1023
949
Accepts a key as input. The corresponding value must be a string or
1024
950
the objects (``True`` or 1) or (``False`` or 0). We allow 0 and 1 to
1025
951
retain compatibility with Python 2.2.
1027
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
1030
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
1033
959
``as_bool`` is not case sensitive.
1035
961
Any other input will raise a ``ValueError``.
1037
963
>>> a = ConfigObj()
1038
964
>>> a['a'] = 'fish'
1039
965
>>> a.as_bool('a')
1246
def __init__(self, infile=None, options=None, **kwargs):
1194
def __init__(self, infile=None, options=None, _inspec=False, **kwargs):
1248
1196
Parse a config file or create a config file object.
1250
1198
``ConfigObj(infile=None, options=None, **kwargs)``
1200
self._inspec = _inspec
1252
1201
# init the superclass
1253
1202
Section.__init__(self, self, 0, self)
1260
options = dict(options)
1204
infile = infile or []
1205
options = dict(options or {})
1262
1207
# keyword arguments take precedence over an options dictionary
1263
1208
options.update(kwargs)
1210
options['list_values'] = False
1265
1212
defaults = OPTION_DEFAULTS.copy()
1266
1213
# TODO: check the values too.
1267
1214
for entry in options:
1268
1215
if entry not in defaults:
1269
1216
raise TypeError('Unrecognised option "%s".' % entry)
1271
1218
# Add any explicit options to the defaults
1272
1219
defaults.update(options)
1273
1220
self._initialise(defaults)
1274
1221
configspec = defaults['configspec']
1275
1222
self._original_configspec = configspec
1276
1223
self._load(infile, configspec)
1279
1226
def _load(self, infile, configspec):
1280
if isinstance(infile, StringTypes):
1227
if isinstance(infile, basestring):
1281
1228
self.filename = infile
1282
1229
if os.path.isfile(infile):
1283
1230
h = open(infile, 'rb')
1299
1246
elif isinstance(infile, (list, tuple)):
1300
1247
infile = list(infile)
1302
1249
elif isinstance(infile, dict):
1303
1250
# initialise self
1304
1251
# the Section class handles creating subsections
1305
1252
if isinstance(infile, ConfigObj):
1306
1253
# get a copy of our ConfigObj
1307
1254
infile = infile.dict()
1309
1256
for entry in infile:
1310
1257
self[entry] = infile[entry]
1311
1258
del self._errors
1313
1260
if configspec is not None:
1314
1261
self._handle_configspec(configspec)
1316
1263
self.configspec = None
1319
elif getattr(infile, 'read', None) is not None:
1266
elif getattr(infile, 'read', MISSING) is not MISSING:
1320
1267
# This supports file like objects
1321
1268
infile = infile.read() or []
1322
1269
# needs splitting into lines - but needs doing *after* decoding
1323
1270
# in case it's not an 8 bit encoding
1325
1272
raise TypeError('infile must be a filename, file like object, or list of lines.')
1328
1275
# don't do it for the empty ConfigObj
1329
1276
infile = self._handle_bom(infile)
1386
1333
self.newlines = None
1387
1334
self.write_empty_values = options['write_empty_values']
1388
1335
self.unrepr = options['unrepr']
1390
1337
self.initial_comment = []
1391
1338
self.final_comment = []
1392
self.configspec = {}
1339
self.configspec = None
1342
self.list_values = False
1394
1344
# Clear section attributes as well
1395
1345
Section._initialise(self)
1398
1348
def __repr__(self):
1399
return ('ConfigObj({%s})' %
1400
', '.join([('%s: %s' % (repr(key), repr(self[key])))
1349
return ('ConfigObj({%s})' %
1350
', '.join([('%s: %s' % (repr(key), repr(self[key])))
1401
1351
for key in (self.scalars + self.sections)]))
1404
1354
def _handle_bom(self, infile):
1406
1356
Handle any BOM, and decode if necessary.
1408
1358
If an encoding is specified, that *must* be used - but the BOM should
1409
1359
still be removed (and the BOM attribute set).
1411
1361
(If the encoding is wrongly specified, then a BOM for an alternative
1412
1362
encoding won't be discovered or removed.)
1414
1364
If an encoding is not specified, UTF8 or UTF16 BOM will be detected and
1415
1365
removed. The BOM attribute will be set. UTF16 will be decoded to
1418
1368
NOTE: This method must not be called with an empty ``infile``.
1420
1370
Specifying the *wrong* encoding is likely to cause a
1421
1371
``UnicodeDecodeError``.
1423
1373
``infile`` must always be returned as a list of lines, but may be
1424
1374
passed in as a single string.
1765
1715
def _quote(self, value, multiline=True):
1767
1717
Return a safely quoted version of a value.
1769
1719
Raise a ConfigObjError if the value cannot be safely quoted.
1770
1720
If multiline is ``True`` (default) then use triple quotes
1773
Don't quote values that don't need it.
1774
Recursively quote members of a list and return a comma joined list.
1775
Multiline is ``False`` for lists.
1776
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.
1778
1728
If ``list_values=False`` then the value is only quoted if it contains
1779
a ``\n`` (is multiline) or '#'.
1729
a ``\\n`` (is multiline) or '#'.
1781
1731
If ``write_empty_values`` is set, and the value is an empty string, it
1782
1732
won't be quoted.
1935
1888
def _handle_configspec(self, configspec):
1936
1889
"""Parse the configspec."""
1937
# FIXME: Should we check that the configspec was created with the
1890
# FIXME: Should we check that the configspec was created with the
1938
1891
# correct settings ? (i.e. ``list_values=False``)
1939
1892
if not isinstance(configspec, ConfigObj):
1941
1894
configspec = ConfigObj(configspec,
1942
1895
raise_errors=True,
1943
1896
file_error=True,
1945
1898
except ConfigObjError, e:
1946
1899
# FIXME: Should these errors have a reference
1947
1900
# to the already parsed ConfigObj ?
1948
1901
raise ConfigspecError('Parsing configspec failed: %s' % e)
1949
1902
except IOError, e:
1950
1903
raise IOError('Reading configspec failed: %s' % e)
1952
self._set_configspec_value(configspec, self)
1955
def _set_configspec_value(self, configspec, section):
1956
"""Used to recursively set configspec values."""
1957
if '__many__' in configspec.sections:
1958
section.configspec['__many__'] = configspec['__many__']
1959
if len(configspec.sections) > 1:
1960
# FIXME: can we supply any useful information here ?
1961
raise RepeatSectionError()
1963
if getattr(configspec, 'initial_comment', None) is not None:
1964
section._configspec_initial_comment = configspec.initial_comment
1965
section._configspec_final_comment = configspec.final_comment
1966
section._configspec_encoding = configspec.encoding
1967
section._configspec_BOM = configspec.BOM
1968
section._configspec_newlines = configspec.newlines
1969
section._configspec_indent_type = configspec.indent_type
1971
for entry in configspec.scalars:
1972
section._configspec_comments[entry] = configspec.comments[entry]
1973
section._configspec_inline_comments[entry] = configspec.inline_comments[entry]
1974
section.configspec[entry] = configspec[entry]
1975
section._order.append(entry)
1905
self.configspec = configspec
1909
def _set_configspec(self, section, copy):
1911
Called by validate. Handles setting the configspec on subsections
1912
including sections to be validated by __many__
1914
configspec = section.configspec
1915
many = configspec.get('__many__')
1916
if isinstance(many, dict):
1917
for entry in section.sections:
1918
if entry not in configspec:
1919
section[entry].configspec = many
1977
1921
for entry in configspec.sections:
1978
1922
if entry == '__many__':
1981
section._cs_section_comments[entry] = configspec.comments[entry]
1982
section._cs_section_inline_comments[entry] = configspec.inline_comments[entry]
1983
if not section.has_key(entry):
1985
self._set_configspec_value(configspec[entry], section[entry])
1988
def _handle_repeat(self, section, configspec):
1989
"""Dynamically assign configspec for repeated section."""
1991
section_keys = configspec.sections
1992
scalar_keys = configspec.scalars
1993
except AttributeError:
1994
section_keys = [entry for entry in configspec
1995
if isinstance(configspec[entry], dict)]
1996
scalar_keys = [entry for entry in configspec
1997
if not isinstance(configspec[entry], dict)]
1999
if '__many__' in section_keys and len(section_keys) > 1:
2000
# FIXME: can we supply any useful information here ?
2001
raise RepeatSectionError()
2005
for entry in scalar_keys:
2006
val = configspec[entry]
2007
scalars[entry] = val
2008
for entry in section_keys:
2009
val = configspec[entry]
2010
if entry == '__many__':
2011
scalars[entry] = val
2013
sections[entry] = val
2015
section.configspec = scalars
2016
for entry in sections:
2017
if not section.has_key(entry):
2019
self._handle_repeat(section[entry], sections[entry])
1924
if entry not in section:
1928
section.comments[entry] = configspec.comments.get(entry, [])
1929
section.inline_comments[entry] = configspec.inline_comments.get(entry, '')
1931
# Could be a scalar when we expect a section
1932
if isinstance(section[entry], Section):
1933
section[entry].configspec = configspec[entry]
2022
1936
def _write_line(self, indent_string, entry, this_entry, comment):
2164
2078
Test the ConfigObj against a configspec.
2166
2080
It uses the ``validator`` object from *validate.py*.
2168
2082
To run ``validate`` on the current ConfigObj, call: ::
2170
2084
test = config.validate(validator)
2172
2086
(Normally having previously passed in the configspec when the ConfigObj
2173
2087
was created - you can dynamically assign a dictionary of checks to the
2174
2088
``configspec`` attribute of a section though).
2176
2090
It returns ``True`` if everything passes, or a dictionary of
2177
2091
pass/fails (True/False). If every member of a subsection passes, it
2178
2092
will just have the value ``True``. (It also returns ``False`` if all
2181
2095
In addition, it converts the values from strings to their native
2182
2096
types if their checks pass (and ``stringify`` is set).
2184
2098
If ``preserve_errors`` is ``True`` (``False`` is default) then instead
2185
2099
of a marking a fail with a ``False``, it will preserve the actual
2186
2100
exception object. This can contain info about the reason for failure.
2187
2101
For example the ``VdtValueTooSmallError`` indicates that the value
2188
2102
supplied was too small. If a value (or section) is missing it will
2189
2103
still be marked as ``False``.
2191
2105
You must have the validate module to use ``preserve_errors=True``.
2193
2107
You can then use the ``flatten_errors`` function to turn your nested
2194
2108
results dictionary into a flattened list of failures - useful for
2195
2109
displaying meaningful error messages.
2202
2116
# Which makes importing configobj faster
2203
2117
from validate import VdtMissingValue
2204
2118
self._vdtMissingValue = VdtMissingValue
2207
spec_section = section.configspec
2208
if copy and getattr(section, '_configspec_initial_comment', None) is not None:
2209
section.initial_comment = section._configspec_initial_comment
2210
section.final_comment = section._configspec_final_comment
2211
section.encoding = section._configspec_encoding
2212
section.BOM = section._configspec_BOM
2213
section.newlines = section._configspec_newlines
2214
section.indent_type = section._configspec_indent_type
2216
if '__many__' in section.configspec:
2217
many = spec_section['__many__']
2218
# dynamically assign the configspecs
2219
# for the sections below
2220
for entry in section.sections:
2221
self._handle_repeat(section[entry], many)
2226
order = [k for k in section._order if k in spec_section]
2227
order += [k for k in spec_section if k not in order]
2229
if entry == '__many__':
2231
if (not entry in section.scalars) or (entry in section.defaults):
2233
# or entries from defaults
2236
if copy and not entry in section.scalars:
2238
section.comments[entry] = (
2239
section._configspec_comments.get(entry, []))
2240
section.inline_comments[entry] = (
2241
section._configspec_inline_comments.get(entry, ''))
2245
val = section[entry]
2123
section.initial_comment = section.configspec.initial_comment
2124
section.final_comment = section.configspec.final_comment
2125
section.encoding = section.configspec.encoding
2126
section.BOM = section.configspec.BOM
2127
section.newlines = section.configspec.newlines
2128
section.indent_type = section.configspec.indent_type
2131
configspec = section.configspec
2132
self._set_configspec(section, copy)
2134
def validate_entry(entry, spec, val, missing, ret_true, ret_false):
2247
check = validator.check(spec_section[entry],
2136
check = validator.check(spec,
2249
2138
missing=missing
2291
2179
section[entry] = check
2292
2180
if not copy and missing and entry not in section.defaults:
2293
2181
section.defaults.append(entry)
2182
return ret_true, ret_false
2189
unvalidated = [k for k in section.scalars if k not in configspec]
2190
incorrect_sections = [k for k in configspec.sections if k in section.scalars]
2191
incorrect_scalars = [k for k in configspec.scalars if k in section.sections]
2193
for entry in configspec.scalars:
2194
if entry in ('__many__', '___many___'):
2198
if (not entry in section.scalars) or (entry in section.defaults):
2200
# or entries from defaults
2203
if copy and not entry in section.scalars:
2205
section.comments[entry] = (
2206
configspec.comments.get(entry, []))
2207
section.inline_comments[entry] = (
2208
configspec.inline_comments.get(entry, ''))
2212
val = section[entry]
2214
ret_true, ret_false = validate_entry(entry, configspec[entry], val,
2215
missing, ret_true, ret_false)
2218
if '__many__' in configspec.scalars:
2219
many = configspec['__many__']
2220
elif '___many___' in configspec.scalars:
2221
many = configspec['___many___']
2223
if many is not None:
2224
for entry in unvalidated:
2225
val = section[entry]
2226
ret_true, ret_false = validate_entry(entry, many, val, False,
2227
ret_true, ret_false)
2229
for entry in incorrect_scalars:
2231
if not preserve_errors:
2235
msg = 'Value %r was provided as a section' % entry
2236
out[entry] = validator.baseErrorClass(msg)
2237
for entry in incorrect_sections:
2239
if not preserve_errors:
2243
msg = 'Section %r was provided as a single value' % entry
2244
out[entry] = validator.baseErrorClass(msg)
2294
2246
# Missing sections will have been created as empty ones when the
2295
2247
# configspec was read.
2296
2248
for entry in section.sections:
2297
2249
# FIXME: this means DEFAULT is not copied in copy mode
2298
2250
if section is self and entry == 'DEFAULT':
2252
if section[entry].configspec is None:
2301
section.comments[entry] = section._cs_section_comments[entry]
2302
section.inline_comments[entry] = (
2303
section._cs_section_inline_comments[entry])
2304
check = self.validate(validator, preserve_errors=preserve_errors,
2305
copy=copy, section=section[entry])
2255
section.comments[entry] = configspec.comments.get(entry, [])
2256
section.inline_comments[entry] = configspec.inline_comments.get(entry, '')
2257
check = self.validate(validator, preserve_errors=preserve_errors, copy=copy, section=section[entry])
2306
2258
out[entry] = check
2307
2259
if check == False:
2308
2260
ret_true = False
2346
2298
if entry == 'configspec':
2348
2300
current_options[entry] = getattr(self, entry)
2350
2302
configspec = self._original_configspec
2351
2303
current_options['configspec'] = configspec
2354
2306
self._initialise(current_options)
2355
2307
self._load(filename, configspec)
2359
2311
class SimpleVal(object):
2361
2313
A simple validator.
2362
2314
Can be used to check that all members expected are present.
2364
2316
To use it, provide a configspec with all your members in (the value given
2365
2317
will be ignored). Pass an instance of ``SimpleVal`` to the ``validate``
2366
2318
method of your ``ConfigObj``. ``validate`` will return ``True`` if all
2367
2319
members are present, or a dictionary with True/False meaning
2368
2320
present/missing. (Whole missing sections will be replaced with ``False``)
2371
2323
def __init__(self):
2372
2324
self.baseErrorClass = ConfigObjError
2374
2326
def check(self, check, member, missing=False):
2375
2327
"""A dummy check method, always returns the value unchanged."""
2384
2336
An example function that will turn a nested dictionary of results
2385
2337
(as returned by ``ConfigObj.validate``) into a flat list.
2387
2339
``cfg`` is the ConfigObj instance being checked, ``res`` is the results
2388
2340
dictionary returned by ``validate``.
2390
2342
(This is a recursive function, so you shouldn't use the ``levels`` or
2391
``results`` arguments - they are used by the function.
2343
``results`` arguments - they are used by the function.)
2393
2345
Returns a list of keys that failed. Each member of the list is a tuple :
2396
2349
([list of sections...], key, result)
2398
2351
If ``validate`` was called with ``preserve_errors=False`` (the default)
2399
2352
then ``result`` will always be ``False``.
2401
2354
*list of sections* is a flattened list of sections that the key was found
2404
If the section was missing then key will be ``None``.
2357
If the section was missing (or a section was expected and a scalar provided
2358
- or vice-versa) then key will be ``None``.
2406
2360
If the value (or section) was missing then ``result`` will be ``False``.
2408
2362
If ``validate`` was called with ``preserve_errors=True`` and a value
2409
2363
was present, but failed the check, then ``result`` will be the exception
2410
2364
object returned. You can use this as a string that describes the failure.
2412
2366
For example *The value "3" is of the wrong type*.
2414
2368
>>> import validate
2415
2369
>>> vtor = validate.Validator()
2416
2370
>>> my_ini = '''
added
removed
bzrlib/util/configobj/configobj.py
