~bzr-pqm/bzr/bzr.dev
» Revision
1908.3.9
(compared to revision 334)
: bzrlib/util/configobj/configobj.py
« back to all changes in this revision
Viewing changes to bzrlib/util/configobj/configobj.py
- browse files at revision 1908.3.9
- compare with another revision
- download diff
- download tarball
- view history from revision 1908.3.9
- Committer: holger krekel
- Date: 2006-08-12 15:57:09 UTC
- mto: (1908.3.21 usecases-benchmarks)
- mto: This revision was merged to the branch mainline in revision 2068.
- Revision ID: hpk@merlinux.de-20060812155709-ccda6599fc38cead
Don't use cache by default.
- files added:
- BRANCH.TODO
- bzrlib/benchmarks
- bzrlib/bundle
- bzrlib/bundle/old
- bzrlib/bundle/serializer
- bzrlib/doc
- bzrlib/doc/api
- bzrlib/export
- bzrlib/plugins
- bzrlib/plugins/launchpad
- bzrlib/store
- bzrlib/store/revision
- bzrlib/store/versioned
- bzrlib/tests
- bzrlib/tests/blackbox
- bzrlib/tests/branch_implementations
- bzrlib/tests/bzrdir_implementations
- bzrlib/tests/interrepository_implementations
- bzrlib/tests/intertree_implementations
- bzrlib/tests/interversionedfile_implementations
- bzrlib/tests/repository_implementations
- bzrlib/tests/revisionstore_implementations
- bzrlib/tests/test_patches_data
- bzrlib/tests/tree_implementations
- bzrlib/tests/workingtree_implementations
- bzrlib/transport
- bzrlib/transport/http
- bzrlib/ui
- bzrlib/util
- bzrlib/util/configobj
- bzrlib/util/configobj/docs
- bzrlib/util/effbot
- bzrlib/util/effbot/org
- contrib/emacs
- tools
- tools/doc_generate
- tools/win32
- files removed:
- bzrlib/mdiff.py
- notes
- files renamed:
- bzrlib/store.py => bzrlib/store/__init__.py
- elementtree/ => bzrlib/util/elementtree/
- urlgrabber/ => bzrlib/util/urlgrabber/
- bzrlib/xml.py => bzrlib/xml_serializer.py
- contrib/bash/bzr => contrib/bash/bzr.simple
- bzrlib/newinventory.py => contrib/newinventory.py
- files modified:
- .bzrignore
- bzr *
- setup.py *
added
removed
bzrlib/util/configobj/configobj.py
1
# configobj.py
2
# A config file reader/writer that supports nested sections in config files.
3
# Copyright (C) 2005 Michael Foord, Nicola Larosa
4
# E-mail: fuzzyman AT voidspace DOT org DOT uk
5
# nico AT tekNico DOT net
6
7
# ConfigObj 4
8
# http://www.voidspace.org.uk/python/configobj.html
9
10
# Released subject to the BSD License
11
# Please see http://www.voidspace.org.uk/python/license.shtml
12
13
# Scripts maintained at http://www.voidspace.org.uk/python/index.shtml
14
# For information about bugfixes, updates and support, please join the
15
# ConfigObj mailing list:
16
# http://lists.sourceforge.net/lists/listinfo/configobj-develop
17
# Comments, suggestions and bug reports welcome.
18
19
from __future__ import generators
20
21
"""
22
>>> z = ConfigObj()
23
>>> z['a'] = 'a'
24
>>> z['sect'] = {
25
... 'subsect': {
26
... 'a': 'fish',
27
... 'b': 'wobble',
28
... },
29
... 'member': 'value',
30
... }
31
>>> x = ConfigObj(z.write())
32
>>> z == x
33
1
34
"""
35
36
import sys
37
INTP_VER = sys.version_info[:2]
38
if INTP_VER < (2, 2):
39
raise RuntimeError("Python v.2.2 or later needed")
40
41
import os, re
42
from types import StringTypes
43
from warnings import warn
44
from codecs import BOM_UTF8, BOM_UTF16, BOM_UTF16_BE, BOM_UTF16_LE
45
46
# A dictionary mapping BOM to
47
# the encoding to decode with, and what to set the
48
# encoding attribute to.
49
BOMS = {
50
BOM_UTF8: ('utf_8', None),
51
BOM_UTF16_BE: ('utf16_be', 'utf_16'),
52
BOM_UTF16_LE: ('utf16_le', 'utf_16'),
53
BOM_UTF16: ('utf_16', 'utf_16'),
54
}
55
# All legal variants of the BOM codecs.
56
# TODO: the list of aliases is not meant to be exhaustive, is there a
57
# better way ?
58
BOM_LIST = {
59
'utf_16': 'utf_16',
60
'u16': 'utf_16',
61
'utf16': 'utf_16',
62
'utf-16': 'utf_16',
63
'utf16_be': 'utf16_be',
64
'utf_16_be': 'utf16_be',
65
'utf-16be': 'utf16_be',
66
'utf16_le': 'utf16_le',
67
'utf_16_le': 'utf16_le',
68
'utf-16le': 'utf16_le',
69
'utf_8': 'utf_8',
70
'u8': 'utf_8',
71
'utf': 'utf_8',
72
'utf8': 'utf_8',
73
'utf-8': 'utf_8',
74
}
75
76
# Map of encodings to the BOM to write.
77
BOM_SET = {
78
'utf_8': BOM_UTF8,
79
'utf_16': BOM_UTF16,
80
'utf16_be': BOM_UTF16_BE,
81
'utf16_le': BOM_UTF16_LE,
82
None: BOM_UTF8
83
}
84
85
try:
86
from validate import VdtMissingValue
87
except ImportError:
88
VdtMissingValue = None
89
90
try:
91
enumerate
92
except NameError:
93
def enumerate(obj):
94
"""enumerate for Python 2.2."""
95
i = -1
96
for item in obj:
97
i += 1
98
yield i, item
99
100
try:
101
True, False
102
except NameError:
103
True, False = 1, 0
104
105
106
__version__ = '4.2.0beta2'
107
108
__revision__ = '$Id: configobj.py 156 2006-01-31 14:57:08Z fuzzyman $'
109
110
__docformat__ = "restructuredtext en"
111
112
# NOTE: Does it make sense to have the following in __all__ ?
113
# NOTE: DEFAULT_INDENT_TYPE, NUM_INDENT_SPACES, MAX_INTERPOL_DEPTH
114
# NOTE: If used as from configobj import...
115
# NOTE: They are effectively read only
116
__all__ = (
117
'__version__',
118
'DEFAULT_INDENT_TYPE',
119
'NUM_INDENT_SPACES',
120
'MAX_INTERPOL_DEPTH',
121
'ConfigObjError',
122
'NestingError',
123
'ParseError',
124
'DuplicateError',
125
'ConfigspecError',
126
'ConfigObj',
127
'SimpleVal',
128
'InterpolationError',
129
'InterpolationDepthError',
130
'MissingInterpolationOption',
131
'RepeatSectionError',
132
'__docformat__',
133
'flatten_errors',
134
)
135
136
DEFAULT_INDENT_TYPE = ' '
137
NUM_INDENT_SPACES = 4
138
MAX_INTERPOL_DEPTH = 10
139
140
OPTION_DEFAULTS = {
141
'interpolation': True,
142
'raise_errors': False,
143
'list_values': True,
144
'create_empty': False,
145
'file_error': False,
146
'configspec': None,
147
'stringify': True,
148
# option may be set to one of ('', ' ', '\t')
149
'indent_type': None,
150
'encoding': None,
151
'default_encoding': None,
152
}
153
154
class ConfigObjError(SyntaxError):
155
"""
156
This is the base class for all errors that ConfigObj raises.
157
It is a subclass of SyntaxError.
158
159
>>> raise ConfigObjError
160
Traceback (most recent call last):
161
ConfigObjError
162
"""
163
def __init__(self, message='', line_number=None, line=''):
164
self.line = line
165
self.line_number = line_number
166
self.message = message
167
SyntaxError.__init__(self, message)
168
169
class NestingError(ConfigObjError):
170
"""
171
This error indicates a level of nesting that doesn't match.
172
173
>>> raise NestingError
174
Traceback (most recent call last):
175
NestingError
176
"""
177
178
class ParseError(ConfigObjError):
179
"""
180
This error indicates that a line is badly written.
181
It is neither a valid ``key = value`` line,
182
nor a valid section marker line.
183
184
>>> raise ParseError
185
Traceback (most recent call last):
186
ParseError
187
"""
188
189
class DuplicateError(ConfigObjError):
190
"""
191
The keyword or section specified already exists.
192
193
>>> raise DuplicateError
194
Traceback (most recent call last):
195
DuplicateError
196
"""
197
198
class ConfigspecError(ConfigObjError):
199
"""
200
An error occured whilst parsing a configspec.
201
202
>>> raise ConfigspecError
203
Traceback (most recent call last):
204
ConfigspecError
205
"""
206
207
class InterpolationError(ConfigObjError):
208
"""Base class for the two interpolation errors."""
209
210
class InterpolationDepthError(InterpolationError):
211
"""Maximum interpolation depth exceeded in string interpolation."""
212
213
def __init__(self, option):
214
"""
215
>>> raise InterpolationDepthError('yoda')
216
Traceback (most recent call last):
217
InterpolationDepthError: max interpolation depth exceeded in value "yoda".
218
"""
219
InterpolationError.__init__(
220
self,
221
'max interpolation depth exceeded in value "%s".' % option)
222
223
class RepeatSectionError(ConfigObjError):
224
"""
225
This error indicates additional sections in a section with a
226
``__many__`` (repeated) section.
227
228
>>> raise RepeatSectionError
229
Traceback (most recent call last):
230
RepeatSectionError
231
"""
232
233
class MissingInterpolationOption(InterpolationError):
234
"""A value specified for interpolation was missing."""
235
236
def __init__(self, option):
237
"""
238
>>> raise MissingInterpolationOption('yoda')
239
Traceback (most recent call last):
240
MissingInterpolationOption: missing option "yoda" in interpolation.
241
"""
242
InterpolationError.__init__(
243
self,
244
'missing option "%s" in interpolation.' % option)
245
246
class Section(dict):
247
"""
248
A dictionary-like object that represents a section in a config file.
249
250
It does string interpolation if the 'interpolate' attribute
251
of the 'main' object is set to True.
252
253
Interpolation is tried first from the 'DEFAULT' section of this object,
254
next from the 'DEFAULT' section of the parent, lastly the main object.
255
256
A Section will behave like an ordered dictionary - following the
257
order of the ``scalars`` and ``sections`` attributes.
258
You can use this to change the order of members.
259
260
Iteration follows the order: scalars, then sections.
261
"""
262
263
_KEYCRE = re.compile(r"%\(([^)]*)\)s|.")
264
265
def __init__(self, parent, depth, main, indict=None, name=None):
266
"""
267
* parent is the section above
268
* depth is the depth level of this section
269
* main is the main ConfigObj
270
* indict is a dictionary to initialise the section with
271
"""
272
if indict is None:
273
indict = {}
274
dict.__init__(self)
275
# used for nesting level *and* interpolation
276
self.parent = parent
277
# used for the interpolation attribute
278
self.main = main
279
# level of nesting depth of this Section
280
self.depth = depth
281
# the sequence of scalar values in this Section
282
self.scalars = []
283
# the sequence of sections in this Section
284
self.sections = []
285
# purely for information
286
self.name = name
287
# for comments :-)
288
self.comments = {}
289
self.inline_comments = {}
290
# for the configspec
291
self.configspec = {}
292
# for defaults
293
self.defaults = []
294
#
295
# we do this explicitly so that __setitem__ is used properly
296
# (rather than just passing to ``dict.__init__``)
297
for entry in indict:
298
self[entry] = indict[entry]
299
300
def _interpolate(self, value):
301
"""Nicked from ConfigParser."""
302
depth = MAX_INTERPOL_DEPTH
303
# loop through this until it's done
304
while depth:
305
depth -= 1
306
if value.find("%(") != -1:
307
value = self._KEYCRE.sub(self._interpolation_replace, value)
308
else:
309
break
310
else:
311
raise InterpolationDepthError(value)
312
return value
313
314
def _interpolation_replace(self, match):
315
""" """
316
s = match.group(1)
317
if s is None:
318
return match.group()
319
else:
320
# switch off interpolation before we try and fetch anything !
321
self.main.interpolation = False
322
# try the 'DEFAULT' member of *this section* first
323
val = self.get('DEFAULT', {}).get(s)
324
# try the 'DEFAULT' member of the *parent section* next
325
if val is None:
326
val = self.parent.get('DEFAULT', {}).get(s)
327
# last, try the 'DEFAULT' member of the *main section*
328
if val is None:
329
val = self.main.get('DEFAULT', {}).get(s)
330
self.main.interpolation = True
331
if val is None:
332
raise MissingInterpolationOption(s)
333
return val
334
335
def __getitem__(self, key):
336
"""Fetch the item and do string interpolation."""
337
val = dict.__getitem__(self, key)
338
if self.main.interpolation and isinstance(val, StringTypes):
339
return self._interpolate(val)
340
return val
341
342
def __setitem__(self, key, value):
343
"""
344
Correctly set a value.
345
346
Making dictionary values Section instances.
347
(We have to special case 'Section' instances - which are also dicts)
348
349
Keys must be strings.
350
Values need only be strings (or lists of strings) if
351
``main.stringify`` is set.
352
"""
353
if not isinstance(key, StringTypes):
354
raise ValueError, 'The key "%s" is not a string.' % key
355
# add the comment
356
if not self.comments.has_key(key):
357
self.comments[key] = []
358
self.inline_comments[key] = ''
359
# remove the entry from defaults
360
if key in self.defaults:
361
self.defaults.remove(key)
362
#
363
if isinstance(value, Section):
364
if not self.has_key(key):
365
self.sections.append(key)
366
dict.__setitem__(self, key, value)
367
elif isinstance(value, dict):
368
# First create the new depth level,
369
# then create the section
370
if not self.has_key(key):
371
self.sections.append(key)
372
new_depth = self.depth + 1
373
dict.__setitem__(
374
self,
375
key,
376
Section(
377
self,
378
new_depth,
379
self.main,
380
indict=value,
381
name=key))
382
else:
383
if not self.has_key(key):
384
self.scalars.append(key)
385
if not self.main.stringify:
386
if isinstance(value, StringTypes):
387
pass
388
elif isinstance(value, (list, tuple)):
389
for entry in value:
390
if not isinstance(entry, StringTypes):
391
raise TypeError, (
392
'Value is not a string "%s".' % entry)
393
else:
394
raise TypeError, 'Value is not a string "%s".' % value
395
dict.__setitem__(self, key, value)
396
397
def __delitem__(self, key):
398
"""Remove items from the sequence when deleting."""
399
dict. __delitem__(self, key)
400
if key in self.scalars:
401
self.scalars.remove(key)
402
else:
403
self.sections.remove(key)
404
del self.comments[key]
405
del self.inline_comments[key]
406
407
def get(self, key, default=None):
408
"""A version of ``get`` that doesn't bypass string interpolation."""
409
try:
410
return self[key]
411
except KeyError:
412
return default
413
414
def update(self, indict):
415
"""
416
A version of update that uses our ``__setitem__``.
417
"""
418
for entry in indict:
419
self[entry] = indict[entry]
420
421
422
def pop(self, key, *args):
423
""" """
424
val = dict.pop(self, key, *args)
425
if key in self.scalars:
426
del self.comments[key]
427
del self.inline_comments[key]
428
self.scalars.remove(key)
429
elif key in self.sections:
430
del self.comments[key]
431
del self.inline_comments[key]
432
self.sections.remove(key)
433
if self.main.interpolation and isinstance(val, StringTypes):
434
return self._interpolate(val)
435
return val
436
437
def popitem(self):
438
"""Pops the first (key,val)"""
439
sequence = (self.scalars + self.sections)
440
if not sequence:
441
raise KeyError, ": 'popitem(): dictionary is empty'"
442
key = sequence[0]
443
val = self[key]
444
del self[key]
445
return key, val
446
447
def clear(self):
448
"""
449
A version of clear that also affects scalars/sections
450
Also clears comments and configspec.
451
452
Leaves other attributes alone :
453
depth/main/parent are not affected
454
"""
455
dict.clear(self)
456
self.scalars = []
457
self.sections = []
458
self.comments = {}
459
self.inline_comments = {}
460
self.configspec = {}
461
462
def setdefault(self, key, default=None):
463
"""A version of setdefault that sets sequence if appropriate."""
464
try:
465
return self[key]
466
except KeyError:
467
self[key] = default
468
return self[key]
469
470
def items(self):
471
""" """
472
return zip((self.scalars + self.sections), self.values())
473
474
def keys(self):
475
""" """
476
return (self.scalars + self.sections)
477
478
def values(self):
479
""" """
480
return [self[key] for key in (self.scalars + self.sections)]
481
482
def iteritems(self):
483
""" """
484
return iter(self.items())
485
486
def iterkeys(self):
487
""" """
488
return iter((self.scalars + self.sections))
489
490
__iter__ = iterkeys
491
492
def itervalues(self):
493
""" """
494
return iter(self.values())
495
496
def __repr__(self):
497
return '{%s}' % ', '.join([('%s: %s' % (repr(key), repr(self[key])))
498
for key in (self.scalars + self.sections)])
499
500
__str__ = __repr__
501
502
# Extra methods - not in a normal dictionary
503
504
def dict(self):
505
"""
506
Return a deepcopy of self as a dictionary.
507
508
All members that are ``Section`` instances are recursively turned to
509
ordinary dictionaries - by calling their ``dict`` method.
510
511
>>> n = a.dict()
512
>>> n == a
513
1
514
>>> n is a
515
0
516
"""
517
newdict = {}
518
for entry in self:
519
this_entry = self[entry]
520
if isinstance(this_entry, Section):
521
this_entry = this_entry.dict()
522
elif isinstance(this_entry, (list, tuple)):
523
# create a copy rather than a reference
524
this_entry = list(this_entry)
525
newdict[entry] = this_entry
526
return newdict
527
528
def merge(self, indict):
529
"""
530
A recursive update - useful for merging config files.
531
532
>>> a = '''[section1]
533
... option1 = True
534
... [[subsection]]
535
... more_options = False
536
... # end of file'''.splitlines()
537
>>> b = '''# File is user.ini
538
... [section1]
539
... option1 = False
540
... # end of file'''.splitlines()
541
>>> c1 = ConfigObj(b)
542
>>> c2 = ConfigObj(a)
543
>>> c2.merge(c1)
544
>>> c2
545
{'section1': {'option1': 'False', 'subsection': {'more_options': 'False'}}}
546
"""
547
for key, val in indict.items():
548
if (key in self and isinstance(self[key], dict) and
549
isinstance(val, dict)):
550
self[key].merge(val)
551
else:
552
self[key] = val
553
554
def rename(self, oldkey, newkey):
555
"""
556
Change a keyname to another, without changing position in sequence.
557
558
Implemented so that transformations can be made on keys,
559
as well as on values. (used by encode and decode)
560
561
Also renames comments.
562
"""
563
if oldkey in self.scalars:
564
the_list = self.scalars
565
elif oldkey in self.sections:
566
the_list = self.sections
567
else:
568
raise KeyError, 'Key "%s" not found.' % oldkey
569
pos = the_list.index(oldkey)
570
#
571
val = self[oldkey]
572
dict.__delitem__(self, oldkey)
573
dict.__setitem__(self, newkey, val)
574
the_list.remove(oldkey)
575
the_list.insert(pos, newkey)
576
comm = self.comments[oldkey]
577
inline_comment = self.inline_comments[oldkey]
578
del self.comments[oldkey]
579
del self.inline_comments[oldkey]
580
self.comments[newkey] = comm
581
self.inline_comments[newkey] = inline_comment
582
583
def walk(self, function, raise_errors=True,
584
call_on_sections=False, **keywargs):
585
"""
586
Walk every member and call a function on the keyword and value.
587
588
Return a dictionary of the return values
589
590
If the function raises an exception, raise the errror
591
unless ``raise_errors=False``, in which case set the return value to
592
``False``.
593
594
Any unrecognised keyword arguments you pass to walk, will be pased on
595
to the function you pass in.
596
597
Note: if ``call_on_sections`` is ``True`` then - on encountering a
598
subsection, *first* the function is called for the *whole* subsection,
599
and then recurses into it's members. This means your function must be
600
able to handle strings, dictionaries and lists. This allows you
601
to change the key of subsections as well as for ordinary members. The
602
return value when called on the whole subsection has to be discarded.
603
604
See the encode and decode methods for examples, including functions.
605
606
.. caution::
607
608
You can use ``walk`` to transform the names of members of a section
609
but you mustn't add or delete members.
610
611
>>> config = '''[XXXXsection]
612
... XXXXkey = XXXXvalue'''.splitlines()
613
>>> cfg = ConfigObj(config)
614
>>> cfg
615
{'XXXXsection': {'XXXXkey': 'XXXXvalue'}}
616
>>> def transform(section, key):
617
... val = section[key]
618
... newkey = key.replace('XXXX', 'CLIENT1')
619
... section.rename(key, newkey)
620
... if isinstance(val, (tuple, list, dict)):
621
... pass
622
... else:
623
... val = val.replace('XXXX', 'CLIENT1')
624
... section[newkey] = val
625
>>> cfg.walk(transform, call_on_sections=True)
626
{'CLIENT1section': {'CLIENT1key': None}}
627
>>> cfg
628
{'CLIENT1section': {'CLIENT1key': 'CLIENT1value'}}
629
"""
630
out = {}
631
# scalars first
632
for i in range(len(self.scalars)):
633
entry = self.scalars[i]
634
try:
635
val = function(self, entry, **keywargs)
636
# bound again in case name has changed
637
entry = self.scalars[i]
638
out[entry] = val
639
except Exception:
640
if raise_errors:
641
raise
642
else:
643
entry = self.scalars[i]
644
out[entry] = False
645
# then sections
646
for i in range(len(self.sections)):
647
entry = self.sections[i]
648
if call_on_sections:
649
try:
650
function(self, entry, **keywargs)
651
except Exception:
652
if raise_errors:
653
raise
654
else:
655
entry = self.sections[i]
656
out[entry] = False
657
# bound again in case name has changed
658
entry = self.sections[i]
659
# previous result is discarded
660
out[entry] = self[entry].walk(
661
function,
662
raise_errors=raise_errors,
663
call_on_sections=call_on_sections,
664
**keywargs)
665
return out
666
667
def decode(self, encoding):
668
"""
669
Decode all strings and values to unicode, using the specified encoding.
670
671
Works with subsections and list values.
672
673
Uses the ``walk`` method.
674
675
Testing ``encode`` and ``decode``.
676
>>> m = ConfigObj(a)
677
>>> m.decode('ascii')
678
>>> def testuni(val):
679
... for entry in val:
680
... if not isinstance(entry, unicode):
681
... print >> sys.stderr, type(entry)
682
... raise AssertionError, 'decode failed.'
683
... if isinstance(val[entry], dict):
684
... testuni(val[entry])
685
... elif not isinstance(val[entry], unicode):
686
... raise AssertionError, 'decode failed.'
687
>>> testuni(m)
688
>>> m.encode('ascii')
689
>>> a == m
690
1
691
"""
692
def decode(section, key, encoding=encoding):
693
""" """
694
val = section[key]
695
if isinstance(val, (list, tuple)):
696
newval = []
697
for entry in val:
698
newval.append(entry.decode(encoding))
699
elif isinstance(val, dict):
700
newval = val
701
else:
702
newval = val.decode(encoding)
703
newkey = key.decode(encoding)
704
section.rename(key, newkey)
705
section[newkey] = newval
706
# using ``call_on_sections`` allows us to modify section names
707
self.walk(decode, call_on_sections=True)
708
709
def encode(self, encoding):
710
"""
711
Encode all strings and values from unicode,
712
using the specified encoding.
713
714
Works with subsections and list values.
715
Uses the ``walk`` method.
716
"""
717
def encode(section, key, encoding=encoding):
718
""" """
719
val = section[key]
720
if isinstance(val, (list, tuple)):
721
newval = []
722
for entry in val:
723
newval.append(entry.encode(encoding))
724
elif isinstance(val, dict):
725
newval = val
726
else:
727
newval = val.encode(encoding)
728
newkey = key.encode(encoding)
729
section.rename(key, newkey)
730
section[newkey] = newval
731
self.walk(encode, call_on_sections=True)
732
733
def istrue(self, key):
734
"""A deprecated version of ``as_bool``."""
735
warn('use of ``istrue`` is deprecated. Use ``as_bool`` method '
736
'instead.', DeprecationWarning)
737
return self.as_bool(key)
738
739
def as_bool(self, key):
740
"""
741
Accepts a key as input. The corresponding value must be a string or
742
the objects (``True`` or 1) or (``False`` or 0). We allow 0 and 1 to
743
retain compatibility with Python 2.2.
744
745
If the string is one of ``True``, ``On``, ``Yes``, or ``1`` it returns
746
``True``.
747
748
If the string is one of ``False``, ``Off``, ``No``, or ``0`` it returns
749
``False``.
750
751
``as_bool`` is not case sensitive.
752
753
Any other input will raise a ``ValueError``.
754
755
>>> a = ConfigObj()
756
>>> a['a'] = 'fish'
757
>>> a.as_bool('a')
758
Traceback (most recent call last):
759
ValueError: Value "fish" is neither True nor False
760
>>> a['b'] = 'True'
761
>>> a.as_bool('b')
762
1
763
>>> a['b'] = 'off'
764
>>> a.as_bool('b')
765
0
766
"""
767
val = self[key]
768
if val == True:
769
return True
770
elif val == False:
771
return False
772
else:
773
try:
774
if not isinstance(val, StringTypes):
775
raise KeyError
776
else:
777
return self.main._bools[val.lower()]
778
except KeyError:
779
raise ValueError('Value "%s" is neither True nor False' % val)
780
781
def as_int(self, key):
782
"""
783
A convenience method which coerces the specified value to an integer.
784
785
If the value is an invalid literal for ``int``, a ``ValueError`` will
786
be raised.
787
788
>>> a = ConfigObj()
789
>>> a['a'] = 'fish'
790
>>> a.as_int('a')
791
Traceback (most recent call last):
792
ValueError: invalid literal for int(): fish
793
>>> a['b'] = '1'
794
>>> a.as_int('b')
795
1
796
>>> a['b'] = '3.2'
797
>>> a.as_int('b')
798
Traceback (most recent call last):
799
ValueError: invalid literal for int(): 3.2
800
"""
801
return int(self[key])
802
803
def as_float(self, key):
804
"""
805
A convenience method which coerces the specified value to a float.
806
807
If the value is an invalid literal for ``float``, a ``ValueError`` will
808
be raised.
809
810
>>> a = ConfigObj()
811
>>> a['a'] = 'fish'
812
>>> a.as_float('a')
813
Traceback (most recent call last):
814
ValueError: invalid literal for float(): fish
815
>>> a['b'] = '1'
816
>>> a.as_float('b')
817
1.0
818
>>> a['b'] = '3.2'
819
>>> a.as_float('b')
820
3.2000000000000002
821
"""
822
return float(self[key])
823
824
825
class ConfigObj(Section):
826
"""
827
An object to read, create, and write config files.
828
829
Testing with duplicate keys and sections.
830
831
>>> c = '''
832
... [hello]
833
... member = value
834
... [hello again]
835
... member = value
836
... [ "hello" ]
837
... member = value
838
... '''
839
>>> ConfigObj(c.split('\\n'), raise_errors = True)
840
Traceback (most recent call last):
841
DuplicateError: Duplicate section name at line 5.
842
843
>>> d = '''
844
... [hello]
845
... member = value
846
... [hello again]
847
... member1 = value
848
... member2 = value
849
... 'member1' = value
850
... [ "and again" ]
851
... member = value
852
... '''
853
>>> ConfigObj(d.split('\\n'), raise_errors = True)
854
Traceback (most recent call last):
855
DuplicateError: Duplicate keyword name at line 6.
856
"""
857
858
_keyword = re.compile(r'''^ # line start
859
(\s*) # indentation
860
( # keyword
861
(?:".*?")| # double quotes
862
(?:'.*?')| # single quotes
863
(?:[^'"=].*?) # no quotes
864
)
865
\s*=\s* # divider
866
(.*) # value (including list values and comments)
867
$ # line end
868
''',
869
re.VERBOSE)
870
871
_sectionmarker = re.compile(r'''^
872
(\s*) # 1: indentation
873
((?:\[\s*)+) # 2: section marker open
874
( # 3: section name open
875
(?:"\s*\S.*?\s*")| # at least one non-space with double quotes
876
(?:'\s*\S.*?\s*')| # at least one non-space with single quotes
877
(?:[^'"\s].*?) # at least one non-space unquoted
878
) # section name close
879
((?:\s*\])+) # 4: section marker close
880
\s*(\#.*)? # 5: optional comment
881
$''',
882
re.VERBOSE)
883
884
# this regexp pulls list values out as a single string
885
# or single values and comments
886
_valueexp = re.compile(r'''^
887
(?:
888
(?:
889
(
890
(?:
891
(?:
892
(?:".*?")| # double quotes
893
(?:'.*?')| # single quotes
894
(?:[^'",\#][^,\#]*?) # unquoted
895
)
896
\s*,\s* # comma
897
)* # match all list items ending in a comma (if any)
898
)
899
(
900
(?:".*?")| # double quotes
901
(?:'.*?')| # single quotes
902
(?:[^'",\#\s][^,]*?) # unquoted
903
)? # last item in a list - or string value
904
)|
905
(,) # alternatively a single comma - empty list
906
)
907
\s*(\#.*)? # optional comment
908
$''',
909
re.VERBOSE)
910
911
# use findall to get the members of a list value
912
_listvalueexp = re.compile(r'''
913
(
914
(?:".*?")| # double quotes
915
(?:'.*?')| # single quotes
916
(?:[^'",\#].*?) # unquoted
917
)
918
\s*,\s* # comma
919
''',
920
re.VERBOSE)
921
922
# this regexp is used for the value
923
# when lists are switched off
924
_nolistvalue = re.compile(r'''^
925
(
926
(?:".*?")| # double quotes
927
(?:'.*?')| # single quotes
928
(?:[^'"\#].*?) # unquoted
929
)
930
\s*(\#.*)? # optional comment
931
$''',
932
re.VERBOSE)
933
934
# regexes for finding triple quoted values on one line
935
_single_line_single = re.compile(r"^'''(.*?)'''\s*(#.*)?$")
936
_single_line_double = re.compile(r'^"""(.*?)"""\s*(#.*)?$')
937
_multi_line_single = re.compile(r"^(.*?)'''\s*(#.*)?$")
938
_multi_line_double = re.compile(r'^(.*?)"""\s*(#.*)?$')
939
940
_triple_quote = {
941
"'''": (_single_line_single, _multi_line_single),
942
'"""': (_single_line_double, _multi_line_double),
943
}
944
945
# Used by the ``istrue`` Section method
946
_bools = {
947
'yes': True, 'no': False,
948
'on': True, 'off': False,
949
'1': True, '0': False,
950
'true': True, 'false': False,
951
}
952
953
def __init__(self, infile=None, options=None, **kwargs):
954
"""
955
Parse or create a config file object.
956
957
``ConfigObj(infile=None, options=None, **kwargs)``
958
"""
959
if infile is None:
960
infile = []
961
if options is None:
962
options = {}
963
# keyword arguments take precedence over an options dictionary
964
options.update(kwargs)
965
# init the superclass
966
Section.__init__(self, self, 0, self)
967
#
968
defaults = OPTION_DEFAULTS.copy()
969
for entry in options.keys():
970
if entry not in defaults.keys():
971
raise TypeError, 'Unrecognised option "%s".' % entry
972
# TODO: check the values too.
973
#
974
# Add any explicit options to the defaults
975
defaults.update(options)
976
#
977
# initialise a few variables
978
self.filename = None
979
self._errors = []
980
self.raise_errors = defaults['raise_errors']
981
self.interpolation = defaults['interpolation']
982
self.list_values = defaults['list_values']
983
self.create_empty = defaults['create_empty']
984
self.file_error = defaults['file_error']
985
self.stringify = defaults['stringify']
986
self.indent_type = defaults['indent_type']
987
self.encoding = defaults['encoding']
988
self.default_encoding = defaults['default_encoding']
989
self.BOM = False
990
self.newlines = None
991
#
992
self.initial_comment = []
993
self.final_comment = []
994
#
995
if isinstance(infile, StringTypes):
996
self.filename = infile
997
if os.path.isfile(infile):
998
infile = open(infile).read() or []
999
elif self.file_error:
1000
# raise an error if the file doesn't exist
1001
raise IOError, 'Config file not found: "%s".' % self.filename
1002
else:
1003
# file doesn't already exist
1004
if self.create_empty:
1005
# this is a good test that the filename specified
1006
# isn't impossible - like on a non existent device
1007
h = open(infile, 'w')
1008
h.write('')
1009
h.close()
1010
infile = []
1011
elif isinstance(infile, (list, tuple)):
1012
infile = list(infile)
1013
elif isinstance(infile, dict):
1014
# initialise self
1015
# the Section class handles creating subsections
1016
if isinstance(infile, ConfigObj):
1017
# get a copy of our ConfigObj
1018
infile = infile.dict()
1019
for entry in infile:
1020
self[entry] = infile[entry]
1021
del self._errors
1022
if defaults['configspec'] is not None:
1023
self._handle_configspec(defaults['configspec'])
1024
else:
1025
self.configspec = None
1026
return
1027
elif hasattr(infile, 'read'):
1028
# This supports file like objects
1029
infile = infile.read() or []
1030
# needs splitting into lines - but needs doing *after* decoding
1031
# in case it's not an 8 bit encoding
1032
else:
1033
raise TypeError, ('infile must be a filename,'
1034
' file like object, or list of lines.')
1035
#
1036
if infile:
1037
# don't do it for the empty ConfigObj
1038
infile = self._handle_bom(infile)
1039
# infile is now *always* a list
1040
#
1041
# Set the newlines attribute (first line ending it finds)
1042
# and strip trailing '\n' or '\r' from lines
1043
for line in infile:
1044
if (not line) or (line[-1] not in '\r\n'):
1045
continue
1046
for end in ('\r\n', '\n', '\r'):
1047
if line.endswith(end):
1048
self.newlines = end
1049
break
1050
break
1051
infile = [line.rstrip('\r\n') for line in infile]
1052
#
1053
self._parse(infile)
1054
# if we had any errors, now is the time to raise them
1055
if self._errors:
1056
error = ConfigObjError("Parsing failed.")
1057
# set the errors attribute; it's a list of tuples:
1058
# (error_type, message, line_number)
1059
error.errors = self._errors
1060
# set the config attribute
1061
error.config = self
1062
raise error
1063
# delete private attributes
1064
del self._errors
1065
#
1066
if defaults['configspec'] is None:
1067
self.configspec = None
1068
else:
1069
self._handle_configspec(defaults['configspec'])
1070
1071
def _handle_bom(self, infile):
1072
"""
1073
Handle any BOM, and decode if necessary.
1074
1075
If an encoding is specified, that *must* be used - but the BOM should
1076
still be removed (and the BOM attribute set).
1077
1078
(If the encoding is wrongly specified, then a BOM for an alternative
1079
encoding won't be discovered or removed.)
1080
1081
If an encoding is not specified, UTF8 or UTF16 BOM will be detected and
1082
removed. The BOM attribute will be set. UTF16 will be decoded to
1083
unicode.
1084
1085
NOTE: This method must not be called with an empty ``infile``.
1086
1087
Specifying the *wrong* encoding is likely to cause a
1088
``UnicodeDecodeError``.
1089
1090
``infile`` must always be returned as a list of lines, but may be
1091
passed in as a single string.
1092
"""
1093
if ((self.encoding is not None) and
1094
(self.encoding.lower() not in BOM_LIST)):
1095
# No need to check for a BOM
1096
# encoding specified doesn't have one
1097
# just decode
1098
return self._decode(infile, self.encoding)
1099
#
1100
if isinstance(infile, (list, tuple)):
1101
line = infile[0]
1102
else:
1103
line = infile
1104
if self.encoding is not None:
1105
# encoding explicitly supplied
1106
# And it could have an associated BOM
1107
# TODO: if encoding is just UTF16 - we ought to check for both
1108
# TODO: big endian and little endian versions.
1109
enc = BOM_LIST[self.encoding.lower()]
1110
if enc == 'utf_16':
1111
# For UTF16 we try big endian and little endian
1112
for BOM, (encoding, final_encoding) in BOMS.items():
1113
if not final_encoding:
1114
# skip UTF8
1115
continue
1116
if infile.startswith(BOM):
1117
### BOM discovered
1118
##self.BOM = True
1119
# Don't need to remove BOM
1120
return self._decode(infile, encoding)
1121
#
1122
# If we get this far, will *probably* raise a DecodeError
1123
# As it doesn't appear to start with a BOM
1124
return self._decode(infile, self.encoding)
1125
#
1126
# Must be UTF8
1127
BOM = BOM_SET[enc]
1128
if not line.startswith(BOM):
1129
return self._decode(infile, self.encoding)
1130
#
1131
newline = line[len(BOM):]
1132
#
1133
# BOM removed
1134
if isinstance(infile, (list, tuple)):
1135
infile[0] = newline
1136
else:
1137
infile = newline
1138
self.BOM = True
1139
return self._decode(infile, self.encoding)
1140
#
1141
# No encoding specified - so we need to check for UTF8/UTF16
1142
for BOM, (encoding, final_encoding) in BOMS.items():
1143
if not line.startswith(BOM):
1144
continue
1145
else:
1146
# BOM discovered
1147
self.encoding = final_encoding
1148
if not final_encoding:
1149
self.BOM = True
1150
# UTF8
1151
# remove BOM
1152
newline = line[len(BOM):]
1153
if isinstance(infile, (list, tuple)):
1154
infile[0] = newline
1155
else:
1156
infile = newline
1157
# UTF8 - don't decode
1158
if isinstance(infile, StringTypes):
1159
return infile.splitlines(True)
1160
else:
1161
return infile
1162
# UTF16 - have to decode
1163
return self._decode(infile, encoding)
1164
#
1165
# No BOM discovered and no encoding specified, just return
1166
if isinstance(infile, StringTypes):
1167
# infile read from a file will be a single string
1168
return infile.splitlines(True)
1169
else:
1170
return infile
1171
1172
def _a_to_u(self, string):
1173
"""Decode ascii strings to unicode if a self.encoding is specified."""
1174
if not self.encoding:
1175
return string
1176
else:
1177
return string.decode('ascii')
1178
1179
def _decode(self, infile, encoding):
1180
"""
1181
Decode infile to unicode. Using the specified encoding.
1182
1183
if is a string, it also needs converting to a list.
1184
"""
1185
if isinstance(infile, StringTypes):
1186
# can't be unicode
1187
# NOTE: Could raise a ``UnicodeDecodeError``
1188
return infile.decode(encoding).splitlines(True)
1189
for i, line in enumerate(infile):
1190
if not isinstance(line, unicode):
1191
# NOTE: The isinstance test here handles mixed lists of unicode/string
1192
# NOTE: But the decode will break on any non-string values
1193
# NOTE: Or could raise a ``UnicodeDecodeError``
1194
infile[i] = line.decode(encoding)
1195
return infile
1196
1197
def _decode_element(self, line):
1198
"""Decode element to unicode if necessary."""
1199
if not self.encoding:
1200
return line
1201
if isinstance(line, str) and self.default_encoding:
1202
return line.decode(self.default_encoding)
1203
return line
1204
1205
def _str(self, value):
1206
"""
1207
Used by ``stringify`` within validate, to turn non-string values
1208
into strings.
1209
"""
1210
if not isinstance(value, StringTypes):
1211
return str(value)
1212
else:
1213
return value
1214
1215
def _parse(self, infile):
1216
"""
1217
Actually parse the config file
1218
1219
Testing Interpolation
1220
1221
>>> c = ConfigObj()
1222
>>> c['DEFAULT'] = {
1223
... 'b': 'goodbye',
1224
... 'userdir': 'c:\\\\home',
1225
... 'c': '%(d)s',
1226
... 'd': '%(c)s'
1227
... }
1228
>>> c['section'] = {
1229
... 'a': '%(datadir)s\\\\some path\\\\file.py',
1230
... 'b': '%(userdir)s\\\\some path\\\\file.py',
1231
... 'c': 'Yo %(a)s',
1232
... 'd': '%(not_here)s',
1233
... 'e': '%(c)s',
1234
... }
1235
>>> c['section']['DEFAULT'] = {
1236
... 'datadir': 'c:\\\\silly_test',
1237
... 'a': 'hello - %(b)s',
1238
... }
1239
>>> c['section']['a'] == 'c:\\\\silly_test\\\\some path\\\\file.py'
1240
1
1241
>>> c['section']['b'] == 'c:\\\\home\\\\some path\\\\file.py'
1242
1
1243
>>> c['section']['c'] == 'Yo hello - goodbye'
1244
1
1245
1246
Switching Interpolation Off
1247
1248
>>> c.interpolation = False
1249
>>> c['section']['a'] == '%(datadir)s\\\\some path\\\\file.py'
1250
1
1251
>>> c['section']['b'] == '%(userdir)s\\\\some path\\\\file.py'
1252
1
1253
>>> c['section']['c'] == 'Yo %(a)s'
1254
1
1255
1256
Testing the interpolation errors.
1257
1258
>>> c.interpolation = True
1259
>>> c['section']['d']
1260
Traceback (most recent call last):
1261
MissingInterpolationOption: missing option "not_here" in interpolation.
1262
>>> c['section']['e']
1263
Traceback (most recent call last):
1264
InterpolationDepthError: max interpolation depth exceeded in value "%(c)s".
1265
1266
Testing our quoting.
1267
1268
>>> i._quote('\"""\'\'\'')
1269
Traceback (most recent call last):
1270
SyntaxError: EOF while scanning triple-quoted string
1271
>>> try:
1272
... i._quote('\\n', multiline=False)
1273
... except ConfigObjError, e:
1274
... e.msg
1275
'Value "\\n" cannot be safely quoted.'
1276
>>> k._quote(' "\' ', multiline=False)
1277
Traceback (most recent call last):
1278
SyntaxError: EOL while scanning single-quoted string
1279
1280
Testing with "stringify" off.
1281
>>> c.stringify = False
1282
>>> c['test'] = 1
1283
Traceback (most recent call last):
1284
TypeError: Value is not a string "1".
1285
"""
1286
comment_list = []
1287
done_start = False
1288
this_section = self
1289
maxline = len(infile) - 1
1290
cur_index = -1
1291
reset_comment = False
1292
while cur_index < maxline:
1293
if reset_comment:
1294
comment_list = []
1295
cur_index += 1
1296
line = infile[cur_index]
1297
sline = line.strip()
1298
# do we have anything on the line ?
1299
if not sline or sline.startswith('#'):
1300
reset_comment = False
1301
comment_list.append(line)
1302
continue
1303
if not done_start:
1304
# preserve initial comment
1305
self.initial_comment = comment_list
1306
comment_list = []
1307
done_start = True
1308
reset_comment = True
1309
# first we check if it's a section marker
1310
mat = self._sectionmarker.match(line)
1311
## print >> sys.stderr, sline, mat
1312
if mat is not None:
1313
# is a section line
1314
(indent, sect_open, sect_name, sect_close, comment) = (
1315
mat.groups())
1316
if indent and (self.indent_type is None):
1317
self.indent_type = indent[0]
1318
cur_depth = sect_open.count('[')
1319
if cur_depth != sect_close.count(']'):
1320
self._handle_error(
1321
"Cannot compute the section depth at line %s.",
1322
NestingError, infile, cur_index)
1323
continue
1324
if cur_depth < this_section.depth:
1325
# the new section is dropping back to a previous level
1326
try:
1327
parent = self._match_depth(
1328
this_section,
1329
cur_depth).parent
1330
except SyntaxError:
1331
self._handle_error(
1332
"Cannot compute nesting level at line %s.",
1333
NestingError, infile, cur_index)
1334
continue
1335
elif cur_depth == this_section.depth:
1336
# the new section is a sibling of the current section
1337
parent = this_section.parent
1338
elif cur_depth == this_section.depth + 1:
1339
# the new section is a child the current section
1340
parent = this_section
1341
else:
1342
self._handle_error(
1343
"Section too nested at line %s.",
1344
NestingError, infile, cur_index)
1345
#
1346
sect_name = self._unquote(sect_name)
1347
if parent.has_key(sect_name):
1348
## print >> sys.stderr, sect_name
1349
self._handle_error(
1350
'Duplicate section name at line %s.',
1351
DuplicateError, infile, cur_index)
1352
continue
1353
# create the new section
1354
this_section = Section(
1355
parent,
1356
cur_depth,
1357
self,
1358
name=sect_name)
1359
parent[sect_name] = this_section
1360
parent.inline_comments[sect_name] = comment
1361
parent.comments[sect_name] = comment_list
1362
## print >> sys.stderr, parent[sect_name] is this_section
1363
continue
1364
#
1365
# it's not a section marker,
1366
# so it should be a valid ``key = value`` line
1367
mat = self._keyword.match(line)
1368
## print >> sys.stderr, sline, mat
1369
if mat is not None:
1370
# is a keyword value
1371
# value will include any inline comment
1372
(indent, key, value) = mat.groups()
1373
if indent and (self.indent_type is None):
1374
self.indent_type = indent[0]
1375
# check for a multiline value
1376
if value[:3] in ['"""', "'''"]:
1377
try:
1378
(value, comment, cur_index) = self._multiline(
1379
value, infile, cur_index, maxline)
1380
except SyntaxError:
1381
self._handle_error(
1382
'Parse error in value at line %s.',
1383
ParseError, infile, cur_index)
1384
continue
1385
else:
1386
# extract comment and lists
1387
try:
1388
(value, comment) = self._handle_value(value)
1389
except SyntaxError:
1390
self._handle_error(
1391
'Parse error in value at line %s.',
1392
ParseError, infile, cur_index)
1393
continue
1394
#
1395
## print >> sys.stderr, sline
1396
key = self._unquote(key)
1397
if this_section.has_key(key):
1398
self._handle_error(
1399
'Duplicate keyword name at line %s.',
1400
DuplicateError, infile, cur_index)
1401
continue
1402
# add the key
1403
## print >> sys.stderr, this_section.name
1404
this_section[key] = value
1405
this_section.inline_comments[key] = comment
1406
this_section.comments[key] = comment_list
1407
## print >> sys.stderr, key, this_section[key]
1408
## if this_section.name is not None:
1409
## print >> sys.stderr, this_section
1410
## print >> sys.stderr, this_section.parent
1411
## print >> sys.stderr, this_section.parent[this_section.name]
1412
continue
1413
#
1414
# it neither matched as a keyword
1415
# or a section marker
1416
self._handle_error(
1417
'Invalid line at line "%s".',
1418
ParseError, infile, cur_index)
1419
if self.indent_type is None:
1420
# no indentation used, set the type accordingly
1421
self.indent_type = ''
1422
# preserve the final comment
1423
if not self and not self.initial_comment:
1424
self.initial_comment = comment_list
1425
else:
1426
self.final_comment = comment_list
1427
1428
def _match_depth(self, sect, depth):
1429
"""
1430
Given a section and a depth level, walk back through the sections
1431
parents to see if the depth level matches a previous section.
1432
1433
Return a reference to the right section,
1434
or raise a SyntaxError.
1435
"""
1436
while depth < sect.depth:
1437
if sect is sect.parent:
1438
# we've reached the top level already
1439
raise SyntaxError
1440
sect = sect.parent
1441
if sect.depth == depth:
1442
return sect
1443
# shouldn't get here
1444
raise SyntaxError
1445
1446
def _handle_error(self, text, ErrorClass, infile, cur_index):
1447
"""
1448
Handle an error according to the error settings.
1449
1450
Either raise the error or store it.
1451
The error will have occured at ``cur_index``
1452
"""
1453
line = infile[cur_index]
1454
message = text % cur_index
1455
error = ErrorClass(message, cur_index, line)
1456
if self.raise_errors:
1457
# raise the error - parsing stops here
1458
raise error
1459
# store the error
1460
# reraise when parsing has finished
1461
self._errors.append(error)
1462
1463
def _unquote(self, value):
1464
"""Return an unquoted version of a value"""
1465
if (value[0] == value[-1]) and (value[0] in ('"', "'")):
1466
value = value[1:-1]
1467
return value
1468
1469
def _quote(self, value, multiline=True):
1470
"""
1471
Return a safely quoted version of a value.
1472
1473
Raise a ConfigObjError if the value cannot be safely quoted.
1474
If multiline is ``True`` (default) then use triple quotes
1475
if necessary.
1476
1477
Don't quote values that don't need it.
1478
Recursively quote members of a list and return a comma joined list.
1479
Multiline is ``False`` for lists.
1480
Obey list syntax for empty and single member lists.
1481
1482
If ``list_values=False`` then the value is only quoted if it contains
1483
a ``\n`` (is multiline).
1484
"""
1485
if isinstance(value, (list, tuple)):
1486
if not value:
1487
return ','
1488
elif len(value) == 1:
1489
return self._quote(value[0], multiline=False) + ','
1490
return ', '.join([self._quote(val, multiline=False)
1491
for val in value])
1492
if not isinstance(value, StringTypes):
1493
if self.stringify:
1494
value = str(value)
1495
else:
1496
raise TypeError, 'Value "%s" is not a string.' % value
1497
squot = "'%s'"
1498
dquot = '"%s"'
1499
noquot = "%s"
1500
wspace_plus = ' \r\t\n\v\t\'"'
1501
tsquot = '"""%s"""'
1502
tdquot = "'''%s'''"
1503
if not value:
1504
return '""'
1505
if (not self.list_values and '\n' not in value) or not (multiline and
1506
((("'" in value) and ('"' in value)) or ('\n' in value))):
1507
if not self.list_values:
1508
# we don't quote if ``list_values=False``
1509
quot = noquot
1510
# for normal values either single or double quotes will do
1511
elif '\n' in value:
1512
# will only happen if multiline is off - e.g. '\n' in key
1513
raise ConfigObjError, ('Value "%s" cannot be safely quoted.' %
1514
value)
1515
elif ((value[0] not in wspace_plus) and
1516
(value[-1] not in wspace_plus) and
1517
(',' not in value)):
1518
quot = noquot
1519
else:
1520
if ("'" in value) and ('"' in value):
1521
raise ConfigObjError, (
1522
'Value "%s" cannot be safely quoted.' % value)
1523
elif '"' in value:
1524
quot = squot
1525
else:
1526
quot = dquot
1527
else:
1528
# if value has '\n' or "'" *and* '"', it will need triple quotes
1529
if (value.find('"""') != -1) and (value.find("'''") != -1):
1530
raise ConfigObjError, (
1531
'Value "%s" cannot be safely quoted.' % value)
1532
if value.find('"""') == -1:
1533
quot = tdquot
1534
else:
1535
quot = tsquot
1536
return quot % value
1537
1538
def _handle_value(self, value):
1539
"""
1540
Given a value string, unquote, remove comment,
1541
handle lists. (including empty and single member lists)
1542
1543
Testing list values.
1544
1545
>>> testconfig3 = '''
1546
... a = ,
1547
... b = test,
1548
... c = test1, test2 , test3
1549
... d = test1, test2, test3,
1550
... '''
1551
>>> d = ConfigObj(testconfig3.split('\\n'), raise_errors=True)
1552
>>> d['a'] == []
1553
1
1554
>>> d['b'] == ['test']
1555
1
1556
>>> d['c'] == ['test1', 'test2', 'test3']
1557
1
1558
>>> d['d'] == ['test1', 'test2', 'test3']
1559
1
1560
1561
Testing with list values off.
1562
1563
>>> e = ConfigObj(
1564
... testconfig3.split('\\n'),
1565
... raise_errors=True,
1566
... list_values=False)
1567
>>> e['a'] == ','
1568
1
1569
>>> e['b'] == 'test,'
1570
1
1571
>>> e['c'] == 'test1, test2 , test3'
1572
1
1573
>>> e['d'] == 'test1, test2, test3,'
1574
1
1575
1576
Testing creating from a dictionary.
1577
1578
>>> f = {
1579
... 'key1': 'val1',
1580
... 'key2': 'val2',
1581
... 'section 1': {
1582
... 'key1': 'val1',
1583
... 'key2': 'val2',
1584
... 'section 1b': {
1585
... 'key1': 'val1',
1586
... 'key2': 'val2',
1587
... },
1588
... },
1589
... 'section 2': {
1590
... 'key1': 'val1',
1591
... 'key2': 'val2',
1592
... 'section 2b': {
1593
... 'key1': 'val1',
1594
... 'key2': 'val2',
1595
... },
1596
... },
1597
... 'key3': 'val3',
1598
... }
1599
>>> g = ConfigObj(f)
1600
>>> f == g
1601
1
1602
1603
Testing we correctly detect badly built list values (4 of them).
1604
1605
>>> testconfig4 = '''
1606
... config = 3,4,,
1607
... test = 3,,4
1608
... fish = ,,
1609
... dummy = ,,hello, goodbye
1610
... '''
1611
>>> try:
1612
... ConfigObj(testconfig4.split('\\n'))
1613
... except ConfigObjError, e:
1614
... len(e.errors)
1615
4
1616
1617
Testing we correctly detect badly quoted values (4 of them).
1618
1619
>>> testconfig5 = '''
1620
... config = "hello # comment
1621
... test = 'goodbye
1622
... fish = 'goodbye # comment
1623
... dummy = "hello again
1624
... '''
1625
>>> try:
1626
... ConfigObj(testconfig5.split('\\n'))
1627
... except ConfigObjError, e:
1628
... len(e.errors)
1629
4
1630
"""
1631
# do we look for lists in values ?
1632
if not self.list_values:
1633
mat = self._nolistvalue.match(value)
1634
if mat is None:
1635
raise SyntaxError
1636
(value, comment) = mat.groups()
1637
# NOTE: we don't unquote here
1638
return (value, comment)
1639
mat = self._valueexp.match(value)
1640
if mat is None:
1641
# the value is badly constructed, probably badly quoted,
1642
# or an invalid list
1643
raise SyntaxError
1644
(list_values, single, empty_list, comment) = mat.groups()
1645
if (list_values == '') and (single is None):
1646
# change this if you want to accept empty values
1647
raise SyntaxError
1648
# NOTE: note there is no error handling from here if the regex
1649
# is wrong: then incorrect values will slip through
1650
if empty_list is not None:
1651
# the single comma - meaning an empty list
1652
return ([], comment)
1653
if single is not None:
1654
single = self._unquote(single)
1655
if list_values == '':
1656
# not a list value
1657
return (single, comment)
1658
the_list = self._listvalueexp.findall(list_values)
1659
the_list = [self._unquote(val) for val in the_list]
1660
if single is not None:
1661
the_list += [single]
1662
return (the_list, comment)
1663
1664
def _multiline(self, value, infile, cur_index, maxline):
1665
"""
1666
Extract the value, where we are in a multiline situation
1667
1668
Testing multiline values.
1669
1670
>>> i == {
1671
... 'name4': ' another single line value ',
1672
... 'multi section': {
1673
... 'name4': '\\n Well, this is a\\n multiline '
1674
... 'value\\n ',
1675
... 'name2': '\\n Well, this is a\\n multiline '
1676
... 'value\\n ',
1677
... 'name3': '\\n Well, this is a\\n multiline '
1678
... 'value\\n ',
1679
... 'name1': '\\n Well, this is a\\n multiline '
1680
... 'value\\n ',
1681
... },
1682
... 'name2': ' another single line value ',
1683
... 'name3': ' a single line value ',
1684
... 'name1': ' a single line value ',
1685
... }
1686
1
1687
"""
1688
quot = value[:3]
1689
newvalue = value[3:]
1690
single_line = self._triple_quote[quot][0]
1691
multi_line = self._triple_quote[quot][1]
1692
mat = single_line.match(value)
1693
if mat is not None:
1694
retval = list(mat.groups())
1695
retval.append(cur_index)
1696
return retval
1697
elif newvalue.find(quot) != -1:
1698
# somehow the triple quote is missing
1699
raise SyntaxError
1700
#
1701
while cur_index < maxline:
1702
cur_index += 1
1703
newvalue += '\n'
1704
line = infile[cur_index]
1705
if line.find(quot) == -1:
1706
newvalue += line
1707
else:
1708
# end of multiline, process it
1709
break
1710
else:
1711
# we've got to the end of the config, oops...
1712
raise SyntaxError
1713
mat = multi_line.match(line)
1714
if mat is None:
1715
# a badly formed line
1716
raise SyntaxError
1717
(value, comment) = mat.groups()
1718
return (newvalue + value, comment, cur_index)
1719
1720
def _handle_configspec(self, configspec):
1721
"""Parse the configspec."""
1722
try:
1723
configspec = ConfigObj(
1724
configspec,
1725
raise_errors=True,
1726
file_error=True,
1727
list_values=False)
1728
except ConfigObjError, e:
1729
# FIXME: Should these errors have a reference
1730
# to the already parsed ConfigObj ?
1731
raise ConfigspecError('Parsing configspec failed: %s' % e)
1732
except IOError, e:
1733
raise IOError('Reading configspec failed: %s' % e)
1734
self._set_configspec_value(configspec, self)
1735
1736
def _set_configspec_value(self, configspec, section):
1737
"""Used to recursively set configspec values."""
1738
if '__many__' in configspec.sections:
1739
section.configspec['__many__'] = configspec['__many__']
1740
if len(configspec.sections) > 1:
1741
# FIXME: can we supply any useful information here ?
1742
raise RepeatSectionError
1743
for entry in configspec.scalars:
1744
section.configspec[entry] = configspec[entry]
1745
for entry in configspec.sections:
1746
if entry == '__many__':
1747
continue
1748
if not section.has_key(entry):
1749
section[entry] = {}
1750
self._set_configspec_value(configspec[entry], section[entry])
1751
1752
def _handle_repeat(self, section, configspec):
1753
"""Dynamically assign configspec for repeated section."""
1754
try:
1755
section_keys = configspec.sections
1756
scalar_keys = configspec.scalars
1757
except AttributeError:
1758
section_keys = [entry for entry in configspec
1759
if isinstance(configspec[entry], dict)]
1760
scalar_keys = [entry for entry in configspec
1761
if not isinstance(configspec[entry], dict)]
1762
if '__many__' in section_keys and len(section_keys) > 1:
1763
# FIXME: can we supply any useful information here ?
1764
raise RepeatSectionError
1765
scalars = {}
1766
sections = {}
1767
for entry in scalar_keys:
1768
val = configspec[entry]
1769
scalars[entry] = val
1770
for entry in section_keys:
1771
val = configspec[entry]
1772
if entry == '__many__':
1773
scalars[entry] = val
1774
continue
1775
sections[entry] = val
1776
#
1777
section.configspec = scalars
1778
for entry in sections:
1779
if not section.has_key(entry):
1780
section[entry] = {}
1781
self._handle_repeat(section[entry], sections[entry])
1782
1783
def _write_line(self, indent_string, entry, this_entry, comment):
1784
"""Write an individual line, for the write method"""
1785
# NOTE: the calls to self._quote here handles non-StringType values.
1786
return '%s%s%s%s%s' % (
1787
indent_string,
1788
self._decode_element(self._quote(entry, multiline=False)),
1789
self._a_to_u(' = '),
1790
self._decode_element(self._quote(this_entry)),
1791
self._decode_element(comment))
1792
1793
def _write_marker(self, indent_string, depth, entry, comment):
1794
"""Write a section marker line"""
1795
return '%s%s%s%s%s' % (
1796
indent_string,
1797
self._a_to_u('[' * depth),
1798
self._quote(self._decode_element(entry), multiline=False),
1799
self._a_to_u(']' * depth),
1800
self._decode_element(comment))
1801
1802
def _handle_comment(self, comment):
1803
"""
1804
Deal with a comment.
1805
1806
>>> filename = a.filename
1807
>>> a.filename = None
1808
>>> values = a.write()
1809
>>> index = 0
1810
>>> while index < 23:
1811
... index += 1
1812
... line = values[index-1]
1813
... assert line.endswith('# comment ' + str(index))
1814
>>> a.filename = filename
1815
1816
>>> start_comment = ['# Initial Comment', '', '#']
1817
>>> end_comment = ['', '#', '# Final Comment']
1818
>>> newconfig = start_comment + testconfig1.split('\\n') + end_comment
1819
>>> nc = ConfigObj(newconfig)
1820
>>> nc.initial_comment
1821
['# Initial Comment', '', '#']
1822
>>> nc.final_comment
1823
['', '#', '# Final Comment']
1824
>>> nc.initial_comment == start_comment
1825
1
1826
>>> nc.final_comment == end_comment
1827
1
1828
"""
1829
if not comment:
1830
return ''
1831
if self.indent_type == '\t':
1832
start = self._a_to_u('\t')
1833
else:
1834
start = self._a_to_u(' ' * NUM_INDENT_SPACES)
1835
if not comment.startswith('#'):
1836
start += _a_to_u('# ')
1837
return (start + comment)
1838
1839
def _compute_indent_string(self, depth):
1840
"""
1841
Compute the indent string, according to current indent_type and depth
1842
"""
1843
if self.indent_type == '':
1844
# no indentation at all
1845
return ''
1846
if self.indent_type == '\t':
1847
return '\t' * depth
1848
if self.indent_type == ' ':
1849
return ' ' * NUM_INDENT_SPACES * depth
1850
raise SyntaxError
1851
1852
# Public methods
1853
1854
def write(self, outfile=None, section=None):
1855
"""
1856
Write the current ConfigObj as a file
1857
1858
tekNico: FIXME: use StringIO instead of real files
1859
1860
>>> filename = a.filename
1861
>>> a.filename = 'test.ini'
1862
>>> a.write()
1863
>>> a.filename = filename
1864
>>> a == ConfigObj('test.ini', raise_errors=True)
1865
1
1866
>>> os.remove('test.ini')
1867
>>> b.filename = 'test.ini'
1868
>>> b.write()
1869
>>> b == ConfigObj('test.ini', raise_errors=True)
1870
1
1871
>>> os.remove('test.ini')
1872
>>> i.filename = 'test.ini'
1873
>>> i.write()
1874
>>> i == ConfigObj('test.ini', raise_errors=True)
1875
1
1876
>>> os.remove('test.ini')
1877
>>> a = ConfigObj()
1878
>>> a['DEFAULT'] = {'a' : 'fish'}
1879
>>> a['a'] = '%(a)s'
1880
>>> a.write()
1881
['a = %(a)s', '[DEFAULT]', 'a = fish']
1882
"""
1883
if self.indent_type is None:
1884
# this can be true if initialised from a dictionary
1885
self.indent_type = DEFAULT_INDENT_TYPE
1886
#
1887
out = []
1888
cs = self._a_to_u('#')
1889
csp = self._a_to_u('# ')
1890
if section is None:
1891
int_val = self.interpolation
1892
self.interpolation = False
1893
section = self
1894
for line in self.initial_comment:
1895
line = self._decode_element(line)
1896
stripped_line = line.strip()
1897
if stripped_line and not stripped_line.startswith(cs):
1898
line = csp + line
1899
out.append(line)
1900
#
1901
indent_string = self._a_to_u(
1902
self._compute_indent_string(section.depth))
1903
for entry in (section.scalars + section.sections):
1904
if entry in section.defaults:
1905
# don't write out default values
1906
continue
1907
for comment_line in section.comments[entry]:
1908
comment_line = self._decode_element(comment_line.lstrip())
1909
if comment_line and not comment_line.startswith(cs):
1910
comment_line = csp + comment_line
1911
out.append(indent_string + comment_line)
1912
this_entry = section[entry]
1913
comment = self._handle_comment(section.inline_comments[entry])
1914
#
1915
if isinstance(this_entry, dict):
1916
# a section
1917
out.append(self._write_marker(
1918
indent_string,
1919
this_entry.depth,
1920
entry,
1921
comment))
1922
out.extend(self.write(section=this_entry))
1923
else:
1924
out.append(self._write_line(
1925
indent_string,
1926
entry,
1927
this_entry,
1928
comment))
1929
#
1930
if section is self:
1931
for line in self.final_comment:
1932
line = self._decode_element(line)
1933
stripped_line = line.strip()
1934
if stripped_line and not stripped_line.startswith(cs):
1935
line = csp + line
1936
out.append(line)
1937
self.interpolation = int_val
1938
#
1939
if section is not self:
1940
return out
1941
#
1942
if (self.filename is None) and (outfile is None):
1943
# output a list of lines
1944
# might need to encode
1945
# NOTE: This will *screw* UTF16, each line will start with the BOM
1946
if self.encoding:
1947
out = [l.encode(self.encoding) for l in out]
1948
if (self.BOM and ((self.encoding is None) or
1949
(BOM_LIST.get(self.encoding.lower()) == 'utf_8'))):
1950
# Add the UTF8 BOM
1951
if not out:
1952
out.append('')
1953
out[0] = BOM_UTF8 + out[0]
1954
return out
1955
#
1956
# Turn the list to a string, joined with correct newlines
1957
output = (self._a_to_u(self.newlines or os.linesep)
1958
).join(out)
1959
if self.encoding:
1960
output = output.encode(self.encoding)
1961
if (self.BOM and ((self.encoding is None) or
1962
(BOM_LIST.get(self.encoding.lower()) == 'utf_8'))):
1963
# Add the UTF8 BOM
1964
output = BOM_UTF8 + output
1965
if outfile is not None:
1966
outfile.write(output)
1967
else:
1968
h = open(self.filename, 'w')
1969
h.write(output)
1970
h.close()
1971
1972
def validate(self, validator, preserve_errors=False, section=None):
1973
"""
1974
Test the ConfigObj against a configspec.
1975
1976
It uses the ``validator`` object from *validate.py*.
1977
1978
To run ``validate`` on the current ConfigObj, call: ::
1979
1980
test = config.validate(validator)
1981
1982
(Normally having previously passed in the configspec when the ConfigObj
1983
was created - you can dynamically assign a dictionary of checks to the
1984
``configspec`` attribute of a section though).
1985
1986
It returns ``True`` if everything passes, or a dictionary of
1987
pass/fails (True/False). If every member of a subsection passes, it
1988
will just have the value ``True``. (It also returns ``False`` if all
1989
members fail).
1990
1991
In addition, it converts the values from strings to their native
1992
types if their checks pass (and ``stringify`` is set).
1993
1994
If ``preserve_errors`` is ``True`` (``False`` is default) then instead
1995
of a marking a fail with a ``False``, it will preserve the actual
1996
exception object. This can contain info about the reason for failure.
1997
For example the ``VdtValueTooSmallError`` indeicates that the value
1998
supplied was too small. If a value (or section) is missing it will
1999
still be marked as ``False``.
2000
2001
You must have the validate module to use ``preserve_errors=True``.
2002
2003
You can then use the ``flatten_errors`` function to turn your nested
2004
results dictionary into a flattened list of failures - useful for
2005
displaying meaningful error messages.
2006
2007
>>> try:
2008
... from validate import Validator
2009
... except ImportError:
2010
... print >> sys.stderr, 'Cannot import the Validator object, skipping the related tests'
2011
... else:
2012
... config = '''
2013
... test1=40
2014
... test2=hello
2015
... test3=3
2016
... test4=5.0
2017
... [section]
2018
... test1=40
2019
... test2=hello
2020
... test3=3
2021
... test4=5.0
2022
... [[sub section]]
2023
... test1=40
2024
... test2=hello
2025
... test3=3
2026
... test4=5.0
2027
... '''.split('\\n')
2028
... configspec = '''
2029
... test1= integer(30,50)
2030
... test2= string
2031
... test3=integer
2032
... test4=float(6.0)
2033
... [section ]
2034
... test1=integer(30,50)
2035
... test2=string
2036
... test3=integer
2037
... test4=float(6.0)
2038
... [[sub section]]
2039
... test1=integer(30,50)
2040
... test2=string
2041
... test3=integer
2042
... test4=float(6.0)
2043
... '''.split('\\n')
2044
... val = Validator()
2045
... c1 = ConfigObj(config, configspec=configspec)
2046
... test = c1.validate(val)
2047
... test == {
2048
... 'test1': True,
2049
... 'test2': True,
2050
... 'test3': True,
2051
... 'test4': False,
2052
... 'section': {
2053
... 'test1': True,
2054
... 'test2': True,
2055
... 'test3': True,
2056
... 'test4': False,
2057
... 'sub section': {
2058
... 'test1': True,
2059
... 'test2': True,
2060
... 'test3': True,
2061
... 'test4': False,
2062
... },
2063
... },
2064
... }
2065
1
2066
>>> val.check(c1.configspec['test4'], c1['test4'])
2067
Traceback (most recent call last):
2068
VdtValueTooSmallError: the value "5.0" is too small.
2069
2070
>>> val_test_config = '''
2071
... key = 0
2072
... key2 = 1.1
2073
... [section]
2074
... key = some text
2075
... key2 = 1.1, 3.0, 17, 6.8
2076
... [[sub-section]]
2077
... key = option1
2078
... key2 = True'''.split('\\n')
2079
>>> val_test_configspec = '''
2080
... key = integer
2081
... key2 = float
2082
... [section]
2083
... key = string
2084
... key2 = float_list(4)
2085
... [[sub-section]]
2086
... key = option(option1, option2)
2087
... key2 = boolean'''.split('\\n')
2088
>>> val_test = ConfigObj(val_test_config, configspec=val_test_configspec)
2089
>>> val_test.validate(val)
2090
1
2091
>>> val_test['key'] = 'text not a digit'
2092
>>> val_res = val_test.validate(val)
2093
>>> val_res == {'key2': True, 'section': True, 'key': False}
2094
1
2095
>>> configspec = '''
2096
... test1=integer(30,50, default=40)
2097
... test2=string(default="hello")
2098
... test3=integer(default=3)
2099
... test4=float(6.0, default=6.0)
2100
... [section ]
2101
... test1=integer(30,50, default=40)
2102
... test2=string(default="hello")
2103
... test3=integer(default=3)
2104
... test4=float(6.0, default=6.0)
2105
... [[sub section]]
2106
... test1=integer(30,50, default=40)
2107
... test2=string(default="hello")
2108
... test3=integer(default=3)
2109
... test4=float(6.0, default=6.0)
2110
... '''.split('\\n')
2111
>>> default_test = ConfigObj(['test1=30'], configspec=configspec)
2112
>>> default_test
2113
{'test1': '30', 'section': {'sub section': {}}}
2114
>>> default_test.validate(val)
2115
1
2116
>>> default_test == {
2117
... 'test1': 30,
2118
... 'test2': 'hello',
2119
... 'test3': 3,
2120
... 'test4': 6.0,
2121
... 'section': {
2122
... 'test1': 40,
2123
... 'test2': 'hello',
2124
... 'test3': 3,
2125
... 'test4': 6.0,
2126
... 'sub section': {
2127
... 'test1': 40,
2128
... 'test3': 3,
2129
... 'test2': 'hello',
2130
... 'test4': 6.0,
2131
... },
2132
... },
2133
... }
2134
1
2135
2136
Now testing with repeated sections : BIG TEST
2137
2138
>>> repeated_1 = '''
2139
... [dogs]
2140
... [[__many__]] # spec for a dog
2141
... fleas = boolean(default=True)
2142
... tail = option(long, short, default=long)
2143
... name = string(default=rover)
2144
... [[[__many__]]] # spec for a puppy
2145
... name = string(default="son of rover")
2146
... age = float(default=0.0)
2147
... [cats]
2148
... [[__many__]] # spec for a cat
2149
... fleas = boolean(default=True)
2150
... tail = option(long, short, default=short)
2151
... name = string(default=pussy)
2152
... [[[__many__]]] # spec for a kitten
2153
... name = string(default="son of pussy")
2154
... age = float(default=0.0)
2155
... '''.split('\\n')
2156
>>> repeated_2 = '''
2157
... [dogs]
2158
...
2159
... # blank dogs with puppies
2160
... # should be filled in by the configspec
2161
... [[dog1]]
2162
... [[[puppy1]]]
2163
... [[[puppy2]]]
2164
... [[[puppy3]]]
2165
... [[dog2]]
2166
... [[[puppy1]]]
2167
... [[[puppy2]]]
2168
... [[[puppy3]]]
2169
... [[dog3]]
2170
... [[[puppy1]]]
2171
... [[[puppy2]]]
2172
... [[[puppy3]]]
2173
... [cats]
2174
...
2175
... # blank cats with kittens
2176
... # should be filled in by the configspec
2177
... [[cat1]]
2178
... [[[kitten1]]]
2179
... [[[kitten2]]]
2180
... [[[kitten3]]]
2181
... [[cat2]]
2182
... [[[kitten1]]]
2183
... [[[kitten2]]]
2184
... [[[kitten3]]]
2185
... [[cat3]]
2186
... [[[kitten1]]]
2187
... [[[kitten2]]]
2188
... [[[kitten3]]]
2189
... '''.split('\\n')
2190
>>> repeated_3 = '''
2191
... [dogs]
2192
...
2193
... [[dog1]]
2194
... [[dog2]]
2195
... [[dog3]]
2196
... [cats]
2197
...
2198
... [[cat1]]
2199
... [[cat2]]
2200
... [[cat3]]
2201
... '''.split('\\n')
2202
>>> repeated_4 = '''
2203
... [__many__]
2204
...
2205
... name = string(default=Michael)
2206
... age = float(default=0.0)
2207
... sex = option(m, f, default=m)
2208
... '''.split('\\n')
2209
>>> repeated_5 = '''
2210
... [cats]
2211
... [[__many__]]
2212
... fleas = boolean(default=True)
2213
... tail = option(long, short, default=short)
2214
... name = string(default=pussy)
2215
... [[[description]]]
2216
... height = float(default=3.3)
2217
... weight = float(default=6)
2218
... [[[[coat]]]]
2219
... fur = option(black, grey, brown, "tortoise shell", default=black)
2220
... condition = integer(0,10, default=5)
2221
... '''.split('\\n')
2222
>>> from validate import Validator
2223
>>> val= Validator()
2224
>>> repeater = ConfigObj(repeated_2, configspec=repeated_1)
2225
>>> repeater.validate(val)
2226
1
2227
>>> repeater == {
2228
... 'dogs': {
2229
... 'dog1': {
2230
... 'fleas': True,
2231
... 'tail': 'long',
2232
... 'name': 'rover',
2233
... 'puppy1': {'name': 'son of rover', 'age': 0.0},
2234
... 'puppy2': {'name': 'son of rover', 'age': 0.0},
2235
... 'puppy3': {'name': 'son of rover', 'age': 0.0},
2236
... },
2237
... 'dog2': {
2238
... 'fleas': True,
2239
... 'tail': 'long',
2240
... 'name': 'rover',
2241
... 'puppy1': {'name': 'son of rover', 'age': 0.0},
2242
... 'puppy2': {'name': 'son of rover', 'age': 0.0},
2243
... 'puppy3': {'name': 'son of rover', 'age': 0.0},
2244
... },
2245
... 'dog3': {
2246
... 'fleas': True,
2247
... 'tail': 'long',
2248
... 'name': 'rover',
2249
... 'puppy1': {'name': 'son of rover', 'age': 0.0},
2250
... 'puppy2': {'name': 'son of rover', 'age': 0.0},
2251
... 'puppy3': {'name': 'son of rover', 'age': 0.0},
2252
... },
2253
... },
2254
... 'cats': {
2255
... 'cat1': {
2256
... 'fleas': True,
2257
... 'tail': 'short',
2258
... 'name': 'pussy',
2259
... 'kitten1': {'name': 'son of pussy', 'age': 0.0},
2260
... 'kitten2': {'name': 'son of pussy', 'age': 0.0},
2261
... 'kitten3': {'name': 'son of pussy', 'age': 0.0},
2262
... },
2263
... 'cat2': {
2264
... 'fleas': True,
2265
... 'tail': 'short',
2266
... 'name': 'pussy',
2267
... 'kitten1': {'name': 'son of pussy', 'age': 0.0},
2268
... 'kitten2': {'name': 'son of pussy', 'age': 0.0},
2269
... 'kitten3': {'name': 'son of pussy', 'age': 0.0},
2270
... },
2271
... 'cat3': {
2272
... 'fleas': True,
2273
... 'tail': 'short',
2274
... 'name': 'pussy',
2275
... 'kitten1': {'name': 'son of pussy', 'age': 0.0},
2276
... 'kitten2': {'name': 'son of pussy', 'age': 0.0},
2277
... 'kitten3': {'name': 'son of pussy', 'age': 0.0},
2278
... },
2279
... },
2280
... }
2281
1
2282
>>> repeater = ConfigObj(repeated_3, configspec=repeated_1)
2283
>>> repeater.validate(val)
2284
1
2285
>>> repeater == {
2286
... 'cats': {
2287
... 'cat1': {'fleas': True, 'tail': 'short', 'name': 'pussy'},
2288
... 'cat2': {'fleas': True, 'tail': 'short', 'name': 'pussy'},
2289
... 'cat3': {'fleas': True, 'tail': 'short', 'name': 'pussy'},
2290
... },
2291
... 'dogs': {
2292
... 'dog1': {'fleas': True, 'tail': 'long', 'name': 'rover'},
2293
... 'dog2': {'fleas': True, 'tail': 'long', 'name': 'rover'},
2294
... 'dog3': {'fleas': True, 'tail': 'long', 'name': 'rover'},
2295
... },
2296
... }
2297
1
2298
>>> repeater = ConfigObj(configspec=repeated_4)
2299
>>> repeater['Michael'] = {}
2300
>>> repeater.validate(val)
2301
1
2302
>>> repeater == {
2303
... 'Michael': {'age': 0.0, 'name': 'Michael', 'sex': 'm'},
2304
... }
2305
1
2306
>>> repeater = ConfigObj(repeated_3, configspec=repeated_5)
2307
>>> repeater == {
2308
... 'dogs': {'dog1': {}, 'dog2': {}, 'dog3': {}},
2309
... 'cats': {'cat1': {}, 'cat2': {}, 'cat3': {}},
2310
... }
2311
1
2312
>>> repeater.validate(val)
2313
1
2314
>>> repeater == {
2315
... 'dogs': {'dog1': {}, 'dog2': {}, 'dog3': {}},
2316
... 'cats': {
2317
... 'cat1': {
2318
... 'fleas': True,
2319
... 'tail': 'short',
2320
... 'name': 'pussy',
2321
... 'description': {
2322
... 'weight': 6.0,
2323
... 'height': 3.2999999999999998,
2324
... 'coat': {'fur': 'black', 'condition': 5},
2325
... },
2326
... },
2327
... 'cat2': {
2328
... 'fleas': True,
2329
... 'tail': 'short',
2330
... 'name': 'pussy',
2331
... 'description': {
2332
... 'weight': 6.0,
2333
... 'height': 3.2999999999999998,
2334
... 'coat': {'fur': 'black', 'condition': 5},
2335
... },
2336
... },
2337
... 'cat3': {
2338
... 'fleas': True,
2339
... 'tail': 'short',
2340
... 'name': 'pussy',
2341
... 'description': {
2342
... 'weight': 6.0,
2343
... 'height': 3.2999999999999998,
2344
... 'coat': {'fur': 'black', 'condition': 5},
2345
... },
2346
... },
2347
... },
2348
... }
2349
1
2350
2351
Test that interpolation is preserved for validated string values.
2352
Also check that interpolation works in configspecs.
2353
>>> t = ConfigObj()
2354
>>> t['DEFAULT'] = {}
2355
>>> t['DEFAULT']['test'] = 'a'
2356
>>> t['test'] = '%(test)s'
2357
>>> t['test']
2358
'a'
2359
>>> v = Validator()
2360
>>> t.configspec = {'test': 'string'}
2361
>>> t.validate(v)
2362
1
2363
>>> t.interpolation = False
2364
>>> t
2365
{'test': '%(test)s', 'DEFAULT': {'test': 'a'}}
2366
>>> specs = [
2367
... 'interpolated string = string(default="fuzzy-%(man)s")',
2368
... '[DEFAULT]',
2369
... 'man = wuzzy',
2370
... ]
2371
>>> c = ConfigObj(configspec=specs)
2372
>>> c.validate(v)
2373
1
2374
>>> c['interpolated string']
2375
'fuzzy-wuzzy'
2376
2377
FIXME: Above tests will fail if we couldn't import Validator (the ones
2378
that don't raise errors will produce different output and still fail as
2379
tests)
2380
"""
2381
if section is None:
2382
if self.configspec is None:
2383
raise ValueError, 'No configspec supplied.'
2384
if preserve_errors:
2385
if VdtMissingValue is None:
2386
raise ImportError('Missing validate module.')
2387
section = self
2388
#
2389
spec_section = section.configspec
2390
if '__many__' in section.configspec:
2391
many = spec_section['__many__']
2392
# dynamically assign the configspecs
2393
# for the sections below
2394
for entry in section.sections:
2395
self._handle_repeat(section[entry], many)
2396
#
2397
out = {}
2398
ret_true = True
2399
ret_false = True
2400
for entry in spec_section:
2401
if entry == '__many__':
2402
continue
2403
if (not entry in section.scalars) or (entry in section.defaults):
2404
# missing entries
2405
# or entries from defaults
2406
missing = True
2407
val = None
2408
else:
2409
missing = False
2410
val = section[entry]
2411
try:
2412
check = validator.check(spec_section[entry],
2413
val,
2414
missing=missing
2415
)
2416
except validator.baseErrorClass, e:
2417
if not preserve_errors or isinstance(e, VdtMissingValue):
2418
out[entry] = False
2419
else:
2420
# preserve the error
2421
out[entry] = e
2422
ret_false = False
2423
ret_true = False
2424
else:
2425
ret_false = False
2426
out[entry] = True
2427
if self.stringify or missing:
2428
# if we are doing type conversion
2429
# or the value is a supplied default
2430
if not self.stringify:
2431
if isinstance(check, (list, tuple)):
2432
# preserve lists
2433
check = [self._str(item) for item in check]
2434
elif missing and check is None:
2435
# convert the None from a default to a ''
2436
check = ''
2437
else:
2438
check = self._str(check)
2439
if (check != val) or missing:
2440
section[entry] = check
2441
if missing and entry not in section.defaults:
2442
section.defaults.append(entry)
2443
#
2444
# FIXME: Will this miss missing sections ?
2445
for entry in section.sections:
2446
if section is self and entry == 'DEFAULT':
2447
continue
2448
check = self.validate(validator, preserve_errors=preserve_errors,
2449
section=section[entry])
2450
out[entry] = check
2451
if check == False:
2452
ret_true = False
2453
elif check == True:
2454
ret_false = False
2455
else:
2456
ret_true = False
2457
ret_false = False
2458
#
2459
if ret_true:
2460
return True
2461
elif ret_false:
2462
return False
2463
else:
2464
return out
2465
2466
class SimpleVal(object):
2467
"""
2468
A simple validator.
2469
Can be used to check that all members expected are present.
2470
2471
To use it, provide a configspec with all your members in (the value given
2472
will be ignored). Pass an instance of ``SimpleVal`` to the ``validate``
2473
method of your ``ConfigObj``. ``validate`` will return ``True`` if all
2474
members are present, or a dictionary with True/False meaning
2475
present/missing. (Whole missing sections will be replaced with ``False``)
2476
2477
>>> val = SimpleVal()
2478
>>> config = '''
2479
... test1=40
2480
... test2=hello
2481
... test3=3
2482
... test4=5.0
2483
... [section]
2484
... test1=40
2485
... test2=hello
2486
... test3=3
2487
... test4=5.0
2488
... [[sub section]]
2489
... test1=40
2490
... test2=hello
2491
... test3=3
2492
... test4=5.0
2493
... '''.split('\\n')
2494
>>> configspec = '''
2495
... test1=''
2496
... test2=''
2497
... test3=''
2498
... test4=''
2499
... [section]
2500
... test1=''
2501
... test2=''
2502
... test3=''
2503
... test4=''
2504
... [[sub section]]
2505
... test1=''
2506
... test2=''
2507
... test3=''
2508
... test4=''
2509
... '''.split('\\n')
2510
>>> o = ConfigObj(config, configspec=configspec)
2511
>>> o.validate(val)
2512
1
2513
>>> o = ConfigObj(configspec=configspec)
2514
>>> o.validate(val)
2515
0
2516
"""
2517
2518
def __init__(self):
2519
self.baseErrorClass = ConfigObjError
2520
2521
def check(self, check, member, missing=False):
2522
"""A dummy check method, always returns the value unchanged."""
2523
if missing:
2524
raise self.baseErrorClass
2525
return member
2526
2527
# Check / processing functions for options
2528
def flatten_errors(cfg, res, levels=None, results=None):
2529
"""
2530
An example function that will turn a nested dictionary of results
2531
(as returned by ``ConfigObj.validate``) into a flat list.
2532
2533
``cfg`` is the ConfigObj instance being checked, ``res`` is the results
2534
dictionary returned by ``validate``.
2535
2536
(This is a recursive function, so you shouldn't use the ``levels`` or
2537
``results`` arguments - they are used by the function.
2538
2539
Returns a list of keys that failed. Each member of the list is a tuple :
2540
::
2541
2542
([list of sections...], key, result)
2543
2544
If ``validate`` was called with ``preserve_errors=False`` (the default)
2545
then ``result`` will always be ``False``.
2546
2547
*list of sections* is a flattened list of sections that the key was found
2548
in.
2549
2550
If the section was missing then key will be ``None``.
2551
2552
If the value (or section) was missing then ``result`` will be ``False``.
2553
2554
If ``validate`` was called with ``preserve_errors=True`` and a value
2555
was present, but failed the check, then ``result`` will be the exception
2556
object returned. You can use this as a string that describes the failure.
2557
2558
For example *The value "3" is of the wrong type*.
2559
2560
# FIXME: is the ordering of the output arbitrary ?
2561
>>> import validate
2562
>>> vtor = validate.Validator()
2563
>>> my_ini = '''
2564
... option1 = True
2565
... [section1]
2566
... option1 = True
2567
... [section2]
2568
... another_option = Probably
2569
... [section3]
2570
... another_option = True
2571
... [[section3b]]
2572
... value = 3
2573
... value2 = a
2574
... value3 = 11
2575
... '''
2576
>>> my_cfg = '''
2577
... option1 = boolean()
2578
... option2 = boolean()
2579
... option3 = boolean(default=Bad_value)
2580
... [section1]
2581
... option1 = boolean()
2582
... option2 = boolean()
2583
... option3 = boolean(default=Bad_value)
2584
... [section2]
2585
... another_option = boolean()
2586
... [section3]
2587
... another_option = boolean()
2588
... [[section3b]]
2589
... value = integer
2590
... value2 = integer
2591
... value3 = integer(0, 10)
2592
... [[[section3b-sub]]]
2593
... value = string
2594
... [section4]
2595
... another_option = boolean()
2596
... '''
2597
>>> cs = my_cfg.split('\\n')
2598
>>> ini = my_ini.split('\\n')
2599
>>> cfg = ConfigObj(ini, configspec=cs)
2600
>>> res = cfg.validate(vtor, preserve_errors=True)
2601
>>> errors = []
2602
>>> for entry in flatten_errors(cfg, res):
2603
... section_list, key, error = entry
2604
... section_list.insert(0, '[root]')
2605
... if key is not None:
2606
... section_list.append(key)
2607
... else:
2608
... section_list.append('[missing]')
2609
... section_string = ', '.join(section_list)
2610
... errors.append((section_string, ' = ', error))
2611
>>> errors.sort()
2612
>>> for entry in errors:
2613
... print entry[0], entry[1], (entry[2] or 0)
2614
[root], option2 = 0
2615
[root], option3 = the value "Bad_value" is of the wrong type.
2616
[root], section1, option2 = 0
2617
[root], section1, option3 = the value "Bad_value" is of the wrong type.
2618
[root], section2, another_option = the value "Probably" is of the wrong type.
2619
[root], section3, section3b, section3b-sub, [missing] = 0
2620
[root], section3, section3b, value2 = the value "a" is of the wrong type.
2621
[root], section3, section3b, value3 = the value "11" is too big.
2622
[root], section4, [missing] = 0
2623
"""
2624
if levels is None:
2625
# first time called
2626
levels = []
2627
results = []
2628
if res is True:
2629
return results
2630
if res is False:
2631
results.append((levels[:], None, False))
2632
if levels:
2633
levels.pop()
2634
return results
2635
for (key, val) in res.items():
2636
if val == True:
2637
continue
2638
if isinstance(cfg.get(key), dict):
2639
# Go down one level
2640
levels.append(key)
2641
flatten_errors(cfg[key], val, levels, results)
2642
continue
2643
results.append((levels[:], key, val))
2644
#
2645
# Go up one level
2646
if levels:
2647
levels.pop()
2648
#
2649
return results
2650
2651
2652
# FIXME: test error code for badly built multiline values
2653
# FIXME: test handling of StringIO
2654
# FIXME: test interpolation with writing
2655
2656
def _doctest():
2657
"""
2658
Dummy function to hold some of the doctests.
2659
2660
>>> a.depth
2661
0
2662
>>> a == {
2663
... 'key2': 'val',
2664
... 'key1': 'val',
2665
... 'lev1c': {
2666
... 'lev2c': {
2667
... 'lev3c': {
2668
... 'key1': 'val',
2669
... },
2670
... },
2671
... },
2672
... 'lev1b': {
2673
... 'key2': 'val',
2674
... 'key1': 'val',
2675
... 'lev2ba': {
2676
... 'key1': 'val',
2677
... },
2678
... 'lev2bb': {
2679
... 'key1': 'val',
2680
... },
2681
... },
2682
... 'lev1a': {
2683
... 'key2': 'val',
2684
... 'key1': 'val',
2685
... },
2686
... }
2687
1
2688
>>> b.depth
2689
0
2690
>>> b == {
2691
... 'key3': 'val3',
2692
... 'key2': 'val2',
2693
... 'key1': 'val1',
2694
... 'section 1': {
2695
... 'keys11': 'val1',
2696
... 'keys13': 'val3',
2697
... 'keys12': 'val2',
2698
... },
2699
... 'section 2': {
2700
... 'section 2 sub 1': {
2701
... 'fish': '3',
2702
... },
2703
... 'keys21': 'val1',
2704
... 'keys22': 'val2',
2705
... 'keys23': 'val3',
2706
... },
2707
... }
2708
1
2709
>>> t = '''
2710
... 'a' = b # !"$%^&*(),::;'@~#= 33
2711
... "b" = b #= 6, 33
2712
... ''' .split('\\n')
2713
>>> t2 = ConfigObj(t)
2714
>>> assert t2 == {'a': 'b', 'b': 'b'}
2715
>>> t2.inline_comments['b'] = ''
2716
>>> del t2['a']
2717
>>> assert t2.write() == ['','b = b', '']
2718
2719
# Test ``list_values=False`` stuff
2720
>>> c = '''
2721
... key1 = no quotes
2722
... key2 = 'single quotes'
2723
... key3 = "double quotes"
2724
... key4 = "list", 'with', several, "quotes"
2725
... '''
2726
>>> cfg = ConfigObj(c.splitlines(), list_values=False)
2727
>>> cfg == {'key1': 'no quotes', 'key2': "'single quotes'",
2728
... 'key3': '"double quotes"',
2729
... 'key4': '"list", \\'with\\', several, "quotes"'
2730
... }
2731
1
2732
>>> cfg = ConfigObj(list_values=False)
2733
>>> cfg['key1'] = 'Multiline\\nValue'
2734
>>> cfg['key2'] = '''"Value" with 'quotes' !'''
2735
>>> cfg.write()
2736
["key1 = '''Multiline\\nValue'''", 'key2 = "Value" with \\'quotes\\' !']
2737
>>> cfg.list_values = True
2738
>>> cfg.write() == ["key1 = '''Multiline\\nValue'''",
2739
... 'key2 = \\'\\'\\'"Value" with \\'quotes\\' !\\'\\'\\'']
2740
1
2741
2742
Test flatten_errors:
2743
2744
>>> from validate import Validator, VdtValueTooSmallError
2745
>>> config = '''
2746
... test1=40
2747
... test2=hello
2748
... test3=3
2749
... test4=5.0
2750
... [section]
2751
... test1=40
2752
... test2=hello
2753
... test3=3
2754
... test4=5.0
2755
... [[sub section]]
2756
... test1=40
2757
... test2=hello
2758
... test3=3
2759
... test4=5.0
2760
... '''.split('\\n')
2761
>>> configspec = '''
2762
... test1= integer(30,50)
2763
... test2= string
2764
... test3=integer
2765
... test4=float(6.0)
2766
... [section ]
2767
... test1=integer(30,50)
2768
... test2=string
2769
... test3=integer
2770
... test4=float(6.0)
2771
... [[sub section]]
2772
... test1=integer(30,50)
2773
... test2=string
2774
... test3=integer
2775
... test4=float(6.0)
2776
... '''.split('\\n')
2777
>>> val = Validator()
2778
>>> c1 = ConfigObj(config, configspec=configspec)
2779
>>> res = c1.validate(val)
2780
>>> flatten_errors(c1, res) == [([], 'test4', False), (['section',
2781
... 'sub section'], 'test4', False), (['section'], 'test4', False)]
2782
True
2783
>>> res = c1.validate(val, preserve_errors=True)
2784
>>> check = flatten_errors(c1, res)
2785
>>> check[0][:2]
2786
([], 'test4')
2787
>>> check[1][:2]
2788
(['section', 'sub section'], 'test4')
2789
>>> check[2][:2]
2790
(['section'], 'test4')
2791
>>> for entry in check:
2792
... isinstance(entry[2], VdtValueTooSmallError)
2793
... print str(entry[2])
2794
True
2795
the value "5.0" is too small.
2796
True
2797
the value "5.0" is too small.
2798
True
2799
the value "5.0" is too small.
2800
2801
Test unicode handling, BOM, write witha file like object and line endings :
2802
>>> u_base = '''
2803
... # initial comment
2804
... # inital comment 2
2805
...
2806
... test1 = some value
2807
... # comment
2808
... test2 = another value # inline comment
2809
... # section comment
2810
... [section] # inline comment
2811
... test = test # another inline comment
2812
... test2 = test2
2813
...
2814
... # final comment
2815
... # final comment2
2816
... '''
2817
>>> u = u_base.encode('utf_8').splitlines(True)
2818
>>> u[0] = BOM_UTF8 + u[0]
2819
>>> uc = ConfigObj(u)
2820
>>> uc.encoding = None
2821
>>> uc.BOM == True
2822
1
2823
>>> uc == {'test1': 'some value', 'test2': 'another value',
2824
... 'section': {'test': 'test', 'test2': 'test2'}}
2825
1
2826
>>> uc = ConfigObj(u, encoding='utf_8', default_encoding='latin-1')
2827
>>> uc.BOM
2828
1
2829
>>> isinstance(uc['test1'], unicode)
2830
1
2831
>>> uc.encoding
2832
'utf_8'
2833
>>> uc.newlines
2834
'\\n'
2835
>>> uc['latin1'] = "This costs lot's of "
2836
>>> a_list = uc.write()
2837
>>> len(a_list)
2838
15
2839
>>> isinstance(a_list[0], str)
2840
1
2841
>>> a_list[0].startswith(BOM_UTF8)
2842
1
2843
>>> u = u_base.replace('\\n', '\\r\\n').encode('utf_8').splitlines(True)
2844
>>> uc = ConfigObj(u)
2845
>>> uc.newlines
2846
'\\r\\n'
2847
>>> uc.newlines = '\\r'
2848
>>> from cStringIO import StringIO
2849
>>> file_like = StringIO()
2850
>>> uc.write(file_like)
2851
>>> file_like.seek(0)
2852
>>> uc2 = ConfigObj(file_like)
2853
>>> uc2 == uc
2854
1
2855
>>> uc2.filename == None
2856
1
2857
>>> uc2.newlines == '\\r'
2858
1
2859
"""
2860
2861
if __name__ == '__main__':
2862
# run the code tests in doctest format
2863
#
2864
testconfig1 = """\
2865
key1= val # comment 1
2866
key2= val # comment 2
2867
# comment 3
2868
[lev1a] # comment 4
2869
key1= val # comment 5
2870
key2= val # comment 6
2871
# comment 7
2872
[lev1b] # comment 8
2873
key1= val # comment 9
2874
key2= val # comment 10
2875
# comment 11
2876
[[lev2ba]] # comment 12
2877
key1= val # comment 13
2878
# comment 14
2879
[[lev2bb]] # comment 15
2880
key1= val # comment 16
2881
# comment 17
2882
[lev1c] # comment 18
2883
# comment 19
2884
[[lev2c]] # comment 20
2885
# comment 21
2886
[[[lev3c]]] # comment 22
2887
key1 = val # comment 23"""
2888
#
2889
testconfig2 = """\
2890
key1 = 'val1'
2891
key2 = "val2"
2892
key3 = val3
2893
["section 1"] # comment
2894
keys11 = val1
2895
keys12 = val2
2896
keys13 = val3
2897
[section 2]
2898
keys21 = val1
2899
keys22 = val2
2900
keys23 = val3
2901
2902
[['section 2 sub 1']]
2903
fish = 3
2904
"""
2905
#
2906
testconfig6 = '''
2907
name1 = """ a single line value """ # comment
2908
name2 = \''' another single line value \''' # comment
2909
name3 = """ a single line value """
2910
name4 = \''' another single line value \'''
2911
[ "multi section" ]
2912
name1 = """
2913
Well, this is a
2914
multiline value
2915
"""
2916
name2 = \'''
2917
Well, this is a
2918
multiline value
2919
\'''
2920
name3 = """
2921
Well, this is a
2922
multiline value
2923
""" # a comment
2924
name4 = \'''
2925
Well, this is a
2926
multiline value
2927
\''' # I guess this is a comment too
2928
'''
2929
#
2930
import doctest
2931
m = sys.modules.get('__main__')
2932
globs = m.__dict__.copy()
2933
a = ConfigObj(testconfig1.split('\n'), raise_errors=True)
2934
b = ConfigObj(testconfig2.split('\n'), raise_errors=True)
2935
i = ConfigObj(testconfig6.split('\n'), raise_errors=True)
2936
globs.update({
2937
'INTP_VER': INTP_VER,
2938
'a': a,
2939
'b': b,
2940
'i': i,
2941
})
2942
doctest.testmod(m, globs=globs)
2943
2944
"""
2945
BUGS
2946
====
2947
2948
None known.
2949
2950
TODO
2951
====
2952
2953
Better support for configuration from multiple files, including tracking
2954
*where* the original file came from and writing changes to the correct
2955
file.
2956
2957
2958
Make ``newline`` an option (as well as an attribute) ?
2959
2960
``UTF16`` encoded files, when returned as a list of lines, will have the
2961
BOM at the start of every line. Should this be removed from all but the
2962
first line ?
2963
2964
Option to set warning type for unicode decode ? (Defaults to strict).
2965
2966
A method to optionally remove uniform indentation from multiline values.
2967
(do as an example of using ``walk`` - along with string-escape)
2968
2969
Should the results dictionary from validate be an ordered dictionary if
2970
`odict <http://www.voidspace.org.uk/python/odict.html>`_ is available ?
2971
2972
Implement a better ``__repr__`` ? (``ConfigObj({})``)
2973
2974
Implement some of the sequence methods (which include slicing) from the
2975
newer ``odict`` ?
2976
2977
INCOMPATIBLE CHANGES
2978
====================
2979
2980
(I have removed a lot of needless complications - this list is probably not
2981
conclusive, many option/attribute/method names have changed)
2982
2983
Case sensitive
2984
2985
The only valid divider is '='
2986
2987
We've removed line continuations with '\'
2988
2989
No recursive lists in values
2990
2991
No empty section
2992
2993
No distinction between flatfiles and non flatfiles
2994
2995
Change in list syntax - use commas to indicate list, not parentheses
2996
(square brackets and parentheses are no longer recognised as lists)
2997
2998
';' is no longer valid for comments and no multiline comments
2999
3000
No attribute access
3001
3002
We don't allow empty values - have to use '' or ""
3003
3004
In ConfigObj 3 - setting a non-flatfile member to ``None`` would
3005
initialise it as an empty section.
3006
3007
The escape entities '&mjf-lf;' and '&mjf-quot;' have gone
3008
replaced by triple quote, multiple line values.
3009
3010
The ``newline``, ``force_return``, and ``default`` options have gone
3011
3012
The ``encoding`` and ``backup_encoding`` methods have gone - replaced
3013
with the ``encode`` and ``decode`` methods.
3014
3015
``fileerror`` and ``createempty`` options have become ``file_error`` and
3016
``create_empty``
3017
3018
Partial configspecs (for specifying the order members should be written
3019
out and which should be present) have gone. The configspec is no longer
3020
used to specify order for the ``write`` method.
3021
3022
Exceeding the maximum depth of recursion in string interpolation now
3023
raises an error ``InterpolationDepthError``.
3024
3025
Specifying a value for interpolation which doesn't exist now raises an
3026
error ``MissingInterpolationOption`` (instead of merely being ignored).
3027
3028
The ``writein`` method has been removed.
3029
3030
The comments attribute is now a list (``inline_comments`` equates to the
3031
old comments attribute)
3032
3033
ISSUES
3034
======
3035
3036
``validate`` doesn't report *extra* values or sections.
3037
3038
You can't have a keyword with the same name as a section (in the same
3039
section). They are both dictionary keys - so they would overlap.
3040
3041
ConfigObj doesn't quote and unquote values if ``list_values=False``.
3042
This means that leading or trailing whitespace in values will be lost when
3043
writing. (Unless you manually quote).
3044
3045
Interpolation checks first the 'DEFAULT' subsection of the current
3046
section, next it checks the 'DEFAULT' section of the parent section,
3047
last it checks the 'DEFAULT' section of the main section.
3048
3049
Logically a 'DEFAULT' section should apply to all subsections of the *same
3050
parent* - this means that checking the 'DEFAULT' subsection in the
3051
*current section* is not necessarily logical ?
3052
3053
In order to simplify unicode support (which is possibly of limited value
3054
in a config file) I have removed automatic support and added the
3055
``encode`` and ``decode methods, which can be used to transform keys and
3056
entries. Because the regex looks for specific values on inital parsing
3057
(i.e. the quotes and the equals signs) it can only read ascii compatible
3058
encodings. For unicode use ``UTF8``, which is ASCII compatible.
3059
3060
Does it matter that we don't support the ':' divider, which is supported
3061
by ``ConfigParser`` ?
3062
3063
The regular expression correctly removes the value -
3064
``"'hello', 'goodbye'"`` and then unquote just removes the front and
3065
back quotes (called from ``_handle_value``). What should we do ??
3066
(*ought* to raise exception because it's an invalid value if lists are
3067
off *sigh*. This is not what you want if you want to do your own list
3068
processing - would be *better* in this case not to unquote.)
3069
3070
String interpolation and validation don't play well together. When
3071
validation changes type it sets the value. This will correctly fetch the
3072
value using interpolation - but then overwrite the interpolation reference.
3073
If the value is unchanged by validation (it's a string) - but other types
3074
will be.
3075
3076
3077
List Value Syntax
3078
=================
3079
3080
List values allow you to specify multiple values for a keyword. This
3081
maps to a list as the resulting Python object when parsed.
3082
3083
The syntax for lists is easy. A list is a comma separated set of values.
3084
If these values contain quotes, the hash mark, or commas, then the values
3085
can be surrounded by quotes. e.g. : ::
3086
3087
keyword = value1, 'value 2', "value 3"
3088
3089
If a value needs to be a list, but only has one member, then you indicate
3090
this with a trailing comma. e.g. : ::
3091
3092
keyword = "single value",
3093
3094
If a value needs to be a list, but it has no members, then you indicate
3095
this with a single comma. e.g. : ::
3096
3097
keyword = , # an empty list
3098
3099
Using triple quotes it will be possible for single values to contain
3100
newlines and *both* single quotes and double quotes. Triple quotes aren't
3101
allowed in list values. This means that the members of list values can't
3102
contain carriage returns (or line feeds :-) or both quote values.
3103
3104
CHANGELOG
3105
=========
3106
3107
2006/02/04
3108
----------
3109
3110
Removed ``BOM_UTF8`` from ``__all__``.
3111
3112
The ``BOM`` attribute has become a boolean. (Defaults to ``False``.) It is
3113
*only* ``True`` for the ``UTF16`` encoding.
3114
3115
File like objects no longer need a ``seek`` attribute.
3116
3117
ConfigObj no longer keeps a reference to file like objects. Instead the
3118
``write`` method takes a file like object as an optional argument. (Which
3119
will be used in preference of the ``filename`` attribute if htat exists as
3120
well.)
3121
3122
Full unicode support added. New options/attributes ``encoding``,
3123
``default_encoding``.
3124
3125
utf16 files decoded to unicode.
3126
3127
If ``BOM`` is ``True``, but no encoding specified, then the utf8 BOM is
3128
written out at the start of the file. (It will normally only be ``True`` if
3129
the utf8 BOM was found when the file was read.)
3130
3131
File paths are *not* converted to absolute paths, relative paths will
3132
remain relative as the ``filename`` attribute.
3133
3134
Fixed bug where ``final_comment`` wasn't returned if ``write`` is returning
3135
a list of lines.
3136
3137
2006/01/31
3138
----------
3139
3140
Added ``True``, ``False``, and ``enumerate`` if they are not defined.
3141
(``True`` and ``False`` are needed for *early* versions of Python 2.2,
3142
``enumerate`` is needed for all versions ofPython 2.2)
3143
3144
Deprecated ``istrue``, replaced it with ``as_bool``.
3145
3146
Added ``as_int`` and ``as_float``.
3147
3148
utf8 and utf16 BOM handled in an endian agnostic way.
3149
3150
2005/12/14
3151
----------
3152
3153
Validation no longer done on the 'DEFAULT' section (only in the root
3154
level). This allows interpolation in configspecs.
3155
3156
Change in validation syntax implemented in validate 0.2.1
3157
3158
4.1.0
3159
3160
2005/12/10
3161
----------
3162
3163
Added ``merge``, a recursive update.
3164
3165
Added ``preserve_errors`` to ``validate`` and the ``flatten_errors``
3166
example function.
3167
3168
Thanks to Matthew Brett for suggestions and helping me iron out bugs.
3169
3170
Fixed bug where a config file is *all* comment, the comment will now be
3171
``initial_comment`` rather than ``final_comment``.
3172
3173
2005/12/02
3174
----------
3175
3176
Fixed bug in ``create_empty``. Thanks to Paul Jimenez for the report.
3177
3178
2005/11/04
3179
----------
3180
3181
Fixed bug in ``Section.walk`` when transforming names as well as values.
3182
3183
Added the ``istrue`` method. (Fetches the boolean equivalent of a string
3184
value).
3185
3186
Fixed ``list_values=False`` - they are now only quoted/unquoted if they
3187
are multiline values.
3188
3189
List values are written as ``item, item`` rather than ``item,item``.
3190
3191
4.0.1
3192
3193
2005/10/09
3194
----------
3195
3196
Fixed typo in ``write`` method. (Testing for the wrong value when resetting
3197
``interpolation``).
3198
3199
4.0.0 Final
3200
3201
2005/09/16
3202
----------
3203
3204
Fixed bug in ``setdefault`` - creating a new section *wouldn't* return
3205
a reference to the new section.
3206
3207
2005/09/09
3208
----------
3209
3210
Removed ``PositionError``.
3211
3212
Allowed quotes around keys as documented.
3213
3214
Fixed bug with commas in comments. (matched as a list value)
3215
3216
Beta 5
3217
3218
2005/09/07
3219
----------
3220
3221
Fixed bug in initialising ConfigObj from a ConfigObj.
3222
3223
Changed the mailing list address.
3224
3225
Beta 4
3226
3227
2005/09/03
3228
----------
3229
3230
Fixed bug in ``Section.__delitem__`` oops.
3231
3232
2005/08/28
3233
----------
3234
3235
Interpolation is switched off before writing out files.
3236
3237
Fixed bug in handling ``StringIO`` instances. (Thanks to report from
3238
"Gustavo Niemeyer" <gustavo@niemeyer.net>)
3239
3240
Moved the doctests from the ``__init__`` method to a separate function.
3241
(For the sake of IDE calltips).
3242
3243
Beta 3
3244
3245
2005/08/26
3246
----------
3247
3248
String values unchanged by validation *aren't* reset. This preserves
3249
interpolation in string values.
3250
3251
2005/08/18
3252
----------
3253
3254
None from a default is turned to '' if stringify is off - because setting
3255
a value to None raises an error.
3256
3257
Version 4.0.0-beta2
3258
3259
2005/08/16
3260
----------
3261
3262
By Nicola Larosa
3263
3264
Actually added the RepeatSectionError class ;-)
3265
3266
2005/08/15
3267
----------
3268
3269
If ``stringify`` is off - list values are preserved by the ``validate``
3270
method. (Bugfix)
3271
3272
2005/08/14
3273
----------
3274
3275
By Michael Foord
3276
3277
Fixed ``simpleVal``.
3278
3279
Added ``RepeatSectionError`` error if you have additional sections in a
3280
section with a ``__many__`` (repeated) section.
3281
3282
By Nicola Larosa
3283
3284
Reworked the ConfigObj._parse, _handle_error and _multiline methods:
3285
mutated the self._infile, self._index and self._maxline attributes into
3286
local variables and method parameters
3287
3288
Reshaped the ConfigObj._multiline method to better reflect its semantics
3289
3290
Changed the "default_test" test in ConfigObj.validate to check the fix for
3291
the bug in validate.Validator.check
3292
3293
2005/08/13
3294
----------
3295
3296
By Nicola Larosa
3297
3298
Updated comments at top
3299
3300
2005/08/11
3301
----------
3302
3303
By Michael Foord
3304
3305
Implemented repeated sections.
3306
3307
By Nicola Larosa
3308
3309
Added test for interpreter version: raises RuntimeError if earlier than
3310
2.2
3311
3312
2005/08/10
3313
----------
3314
3315
By Michael Foord
3316
3317
Implemented default values in configspecs.
3318
3319
By Nicola Larosa
3320
3321
Fixed naked except: clause in validate that was silencing the fact
3322
that Python2.2 does not have dict.pop
3323
3324
2005/08/08
3325
----------
3326
3327
By Michael Foord
3328
3329
Bug fix causing error if file didn't exist.
3330
3331
2005/08/07
3332
----------
3333
3334
By Nicola Larosa
3335
3336
Adjusted doctests for Python 2.2.3 compatibility
3337
3338
2005/08/04
3339
----------
3340
3341
By Michael Foord
3342
3343
Added the inline_comments attribute
3344
3345
We now preserve and rewrite all comments in the config file
3346
3347
configspec is now a section attribute
3348
3349
The validate method changes values in place
3350
3351
Added InterpolationError
3352
3353
The errors now have line number, line, and message attributes. This
3354
simplifies error handling
3355
3356
Added __docformat__
3357
3358
2005/08/03
3359
----------
3360
3361
By Michael Foord
3362
3363
Fixed bug in Section.pop (now doesn't raise KeyError if a default value
3364
is specified)
3365
3366
Replaced ``basestring`` with ``types.StringTypes``
3367
3368
Removed the ``writein`` method
3369
3370
Added __version__
3371
3372
2005/07/29
3373
----------
3374
3375
By Nicola Larosa
3376
3377
Indentation in config file is not significant anymore, subsections are
3378
designated by repeating square brackets
3379
3380
Adapted all tests and docs to the new format
3381
3382
2005/07/28
3383
----------
3384
3385
By Nicola Larosa
3386
3387
Added more tests
3388
3389
2005/07/23
3390
----------
3391
3392
By Nicola Larosa
3393
3394
Reformatted final docstring in ReST format, indented it for easier folding
3395
3396
Code tests converted to doctest format, and scattered them around
3397
in various docstrings
3398
3399
Walk method rewritten using scalars and sections attributes
3400
3401
2005/07/22
3402
----------
3403
3404
By Nicola Larosa
3405
3406
Changed Validator and SimpleVal "test" methods to "check"
3407
3408
More code cleanup
3409
3410
2005/07/21
3411
----------
3412
3413
Changed Section.sequence to Section.scalars and Section.sections
3414
3415
Added Section.configspec
3416
3417
Sections in the root section now have no extra indentation
3418
3419
Comments now better supported in Section and preserved by ConfigObj
3420
3421
Comments also written out
3422
3423
Implemented initial_comment and final_comment
3424
3425
A scalar value after a section will now raise an error
3426
3427
2005/07/20
3428
----------
3429
3430
Fixed a couple of bugs
3431
3432
Can now pass a tuple instead of a list
3433
3434
Simplified dict and walk methods
3435
3436
Added __str__ to Section
3437
3438
2005/07/10
3439
----------
3440
3441
By Nicola Larosa
3442
3443
More code cleanup
3444
3445
2005/07/08
3446
----------
3447
3448
The stringify option implemented. On by default.
3449
3450
2005/07/07
3451
----------
3452
3453
Renamed private attributes with a single underscore prefix.
3454
3455
Changes to interpolation - exceeding recursion depth, or specifying a
3456
missing value, now raise errors.
3457
3458
Changes for Python 2.2 compatibility. (changed boolean tests - removed
3459
``is True`` and ``is False``)
3460
3461
Added test for duplicate section and member (and fixed bug)
3462
3463
2005/07/06
3464
----------
3465
3466
By Nicola Larosa
3467
3468
Code cleanup
3469
3470
2005/07/02
3471
----------
3472
3473
Version 0.1.0
3474
3475
Now properly handles values including comments and lists.
3476
3477
Better error handling.
3478
3479
String interpolation.
3480
3481
Some options implemented.
3482
3483
You can pass a Section a dictionary to initialise it.
3484
3485
Setting a Section member to a dictionary will create a Section instance.
3486
3487
2005/06/26
3488
----------
3489
3490
Version 0.0.1
3491
3492
Experimental reader.
3493
3494
A reasonably elegant implementation - a basic reader in 160 lines of code.
3495
3496
*A programming language is a medium of expression.* - Paul Graham
3497
"""
3498
Loggerhead is a web-based interface for Breezy
Version: 2.0.1