~bzr-pqm/bzr/bzr.dev
» Revision
1185.12.38
(compared to revision 1185.46.2)
: bzrlib/util/configobj/configobj.py
« back to all changes in this revision
Viewing changes to bzrlib/util/configobj/configobj.py
- browse files at revision 1185.12.38
- compare with another revision
- download diff
- download tarball
- view history from revision 1185.12.38
- Committer: abentley
- Date: 2005-10-14 03:50:50 UTC
- mto: (1185.25.1)
- mto: This revision was merged to the branch mainline in revision 1460.
- Revision ID: abentley@lappy-20051014035050-d779472ccb599a51
semi-broke merge
- files added:
- bzrlib/mdiff.py
- files removed:
- INSTALL
- bzrlib/export
- bzrlib/tests/blackbox
- bzrlib/util/configobj
- bzrlib/util/configobj/docs
- files renamed:
- bzr_man.py => bzr-man.py
- bzrlib/conflicts.py => bzrlib/plugins/conflicts.py
- bzrlib/tests/ => bzrlib/selftest/
- bzrlib/tests/blackbox/__init__.py => bzrlib/selftest/blackbox.py
- bzrlib/tests/test_plugins.py => bzrlib/selftest/plugins.py
- bzrlib/tests/test_branch.py => bzrlib/selftest/testbranch.py
- bzrlib/tests/test_config.py => bzrlib/selftest/testconfig.py
- bzrlib/tests/test_diff.py => bzrlib/selftest/testdiff.py
- bzrlib/tests/test_fetch.py => bzrlib/selftest/testfetch.py
- bzrlib/tests/test_graph.py => bzrlib/selftest/testgraph.py
- bzrlib/tests/test_hashcache.py => bzrlib/selftest/testhashcache.py
- bzrlib/tests/test_identitymap.py => bzrlib/selftest/testidentitymap.py
- bzrlib/tests/test_inv.py => bzrlib/selftest/testinv.py
- bzrlib/tests/test_log.py => bzrlib/selftest/testlog.py
- bzrlib/tests/test_merge.py => bzrlib/selftest/testmerge.py
- bzrlib/tests/test_merge3.py => bzrlib/selftest/testmerge3.py
- bzrlib/tests/test_revision.py => bzrlib/selftest/testrevision.py
- bzrlib/tests/test_revisionnamespaces.py => bzrlib/selftest/testrevisionnamespaces.py
- bzrlib/tests/test_sampler.py => bzrlib/selftest/testsampler.py
- bzrlib/tests/test_status.py => bzrlib/selftest/teststatus.py
- bzrlib/tests/test_store.py => bzrlib/selftest/teststore.py
- bzrlib/tests/test_transactions.py => bzrlib/selftest/testtransactions.py
- bzrlib/tests/test_transport.py => bzrlib/selftest/testtransport.py
- bzrlib/tests/test_workingtree.py => bzrlib/selftest/testworkingtree.py
- bzrlib/tests/blackbox/versioning.py => bzrlib/selftest/versioning.py
- bzrlib/tests/test_whitebox.py => bzrlib/selftest/whitebox.py
- files modified:
- .bzrignore
- 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
9
# Released subject to the BSD License
10
# Please see http://www.voidspace.org.uk/documents/BSD-LICENSE.txt
11
12
# Scripts maintained at http://www.voidspace.org.uk/python/index.shtml
13
# For information about bugfixes, updates and support, please join the
14
# ConfigObj mailing list:
15
# http://lists.sourceforge.net/lists/listinfo/configobj-develop
16
# Comments, suggestions and bug reports welcome.
17
18
"""
19
>>> z = ConfigObj()
20
>>> z['a'] = 'a'
21
>>> z['sect'] = {
22
... 'subsect': {
23
... 'a': 'fish',
24
... 'b': 'wobble',
25
... },
26
... 'member': 'value',
27
... }
28
>>> x = ConfigObj(z.write())
29
>>> z == x
30
1
31
"""
32
33
import sys
34
INTP_VER = sys.version_info[:2]
35
if INTP_VER < (2, 2):
36
raise RuntimeError("Python v.2.2 or later needed")
37
38
import os, re
39
from types import StringTypes
40
41
# the UTF8 BOM - from codecs module
42
BOM_UTF8 = '\xef\xbb\xbf'
43
44
__version__ = '4.0.0'
45
46
__revision__ = '$Id: configobj.py 135 2005-10-12 14:52:28Z fuzzyman $'
47
48
__docformat__ = "restructuredtext en"
49
50
__all__ = (
51
'__version__',
52
'BOM_UTF8',
53
'DEFAULT_INDENT_TYPE',
54
'NUM_INDENT_SPACES',
55
'MAX_INTERPOL_DEPTH',
56
'ConfigObjError',
57
'NestingError',
58
'ParseError',
59
'DuplicateError',
60
'ConfigspecError',
61
'ConfigObj',
62
'SimpleVal',
63
'InterpolationError',
64
'InterpolationDepthError',
65
'MissingInterpolationOption',
66
'RepeatSectionError',
67
'__docformat__',
68
)
69
70
DEFAULT_INDENT_TYPE = ' '
71
NUM_INDENT_SPACES = 4
72
MAX_INTERPOL_DEPTH = 10
73
74
OPTION_DEFAULTS = {
75
'interpolation': True,
76
'raise_errors': False,
77
'list_values': True,
78
'create_empty': False,
79
'file_error': False,
80
'configspec': None,
81
'stringify': True,
82
# option may be set to one of ('', ' ', '\t')
83
'indent_type': None,
84
}
85
86
class ConfigObjError(SyntaxError):
87
"""
88
This is the base class for all errors that ConfigObj raises.
89
It is a subclass of SyntaxError.
90
91
>>> raise ConfigObjError
92
Traceback (most recent call last):
93
ConfigObjError
94
"""
95
def __init__(self, message='', line_number=None, line=''):
96
self.line = line
97
self.line_number = line_number
98
self.message = message
99
SyntaxError.__init__(self, message)
100
101
class NestingError(ConfigObjError):
102
"""
103
This error indicates a level of nesting that doesn't match.
104
105
>>> raise NestingError
106
Traceback (most recent call last):
107
NestingError
108
"""
109
110
class ParseError(ConfigObjError):
111
"""
112
This error indicates that a line is badly written.
113
It is neither a valid ``key = value`` line,
114
nor a valid section marker line.
115
116
>>> raise ParseError
117
Traceback (most recent call last):
118
ParseError
119
"""
120
121
class DuplicateError(ConfigObjError):
122
"""
123
The keyword or section specified already exists.
124
125
>>> raise DuplicateError
126
Traceback (most recent call last):
127
DuplicateError
128
"""
129
130
class ConfigspecError(ConfigObjError):
131
"""
132
An error occured whilst parsing a configspec.
133
134
>>> raise ConfigspecError
135
Traceback (most recent call last):
136
ConfigspecError
137
"""
138
139
class InterpolationError(ConfigObjError):
140
"""Base class for the two interpolation errors."""
141
142
class InterpolationDepthError(InterpolationError):
143
"""Maximum interpolation depth exceeded in string interpolation."""
144
145
def __init__(self, option):
146
"""
147
>>> raise InterpolationDepthError('yoda')
148
Traceback (most recent call last):
149
InterpolationDepthError: max interpolation depth exceeded in value "yoda".
150
"""
151
InterpolationError.__init__(
152
self,
153
'max interpolation depth exceeded in value "%s".' % option)
154
155
class RepeatSectionError(ConfigObjError):
156
"""
157
This error indicates additional sections in a section with a
158
``__many__`` (repeated) section.
159
160
>>> raise RepeatSectionError
161
Traceback (most recent call last):
162
RepeatSectionError
163
"""
164
165
class MissingInterpolationOption(InterpolationError):
166
"""A value specified for interpolation was missing."""
167
168
def __init__(self, option):
169
"""
170
>>> raise MissingInterpolationOption('yoda')
171
Traceback (most recent call last):
172
MissingInterpolationOption: missing option "yoda" in interpolation.
173
"""
174
InterpolationError.__init__(
175
self,
176
'missing option "%s" in interpolation.' % option)
177
178
class Section(dict):
179
"""
180
A dictionary-like object that represents a section in a config file.
181
182
It does string interpolation if the 'interpolate' attribute
183
of the 'main' object is set to True.
184
185
Interpolation is tried first from the 'DEFAULT' section of this object,
186
next from the 'DEFAULT' section of the parent, lastly the main object.
187
188
A Section will behave like an ordered dictionary - following the
189
order of the ``scalars`` and ``sections`` attributes.
190
You can use this to change the order of members.
191
192
Iteration follows the order: scalars, then sections.
193
"""
194
195
_KEYCRE = re.compile(r"%\(([^)]*)\)s|.")
196
197
def __init__(self, parent, depth, main, indict=None, name=None):
198
"""
199
parent is the section above
200
depth is the depth level of this section
201
main is the main ConfigObj
202
indict is a dictionary to initialise the section with
203
"""
204
if indict is None:
205
indict = {}
206
dict.__init__(self)
207
# used for nesting level *and* interpolation
208
self.parent = parent
209
# used for the interpolation attribute
210
self.main = main
211
# level of nesting depth of this Section
212
self.depth = depth
213
# the sequence of scalar values in this Section
214
self.scalars = []
215
# the sequence of sections in this Section
216
self.sections = []
217
# purely for information
218
self.name = name
219
# for comments :-)
220
self.comments = {}
221
self.inline_comments = {}
222
# for the configspec
223
self.configspec = {}
224
# for defaults
225
self.defaults = []
226
#
227
# we do this explicitly so that __setitem__ is used properly
228
# (rather than just passing to ``dict.__init__``)
229
for entry in indict:
230
self[entry] = indict[entry]
231
232
def _interpolate(self, value):
233
"""Nicked from ConfigParser."""
234
depth = MAX_INTERPOL_DEPTH
235
# loop through this until it's done
236
while depth:
237
depth -= 1
238
if value.find("%(") != -1:
239
value = self._KEYCRE.sub(self._interpolation_replace, value)
240
else:
241
break
242
else:
243
raise InterpolationDepthError(value)
244
return value
245
246
def _interpolation_replace(self, match):
247
""" """
248
s = match.group(1)
249
if s is None:
250
return match.group()
251
else:
252
# switch off interpolation before we try and fetch anything !
253
self.main.interpolation = False
254
# try the 'DEFAULT' member of *this section* first
255
val = self.get('DEFAULT', {}).get(s)
256
# try the 'DEFAULT' member of the *parent section* next
257
if val is None:
258
val = self.parent.get('DEFAULT', {}).get(s)
259
# last, try the 'DEFAULT' member of the *main section*
260
if val is None:
261
val = self.main.get('DEFAULT', {}).get(s)
262
self.main.interpolation = True
263
if val is None:
264
raise MissingInterpolationOption(s)
265
return val
266
267
def __getitem__(self, key):
268
"""Fetch the item and do string interpolation."""
269
val = dict.__getitem__(self, key)
270
if self.main.interpolation and isinstance(val, StringTypes):
271
return self._interpolate(val)
272
return val
273
274
def __setitem__(self, key, value):
275
"""
276
Correctly set a value.
277
278
Making dictionary values Section instances.
279
(We have to special case 'Section' instances - which are also dicts)
280
281
Keys must be strings.
282
Values need only be strings (or lists of strings) if
283
``main.stringify`` is set.
284
"""
285
if not isinstance(key, StringTypes):
286
raise ValueError, 'The key "%s" is not a string.' % key
287
## if self.depth is None:
288
## self.depth = 0
289
# add the comment
290
if not self.comments.has_key(key):
291
self.comments[key] = []
292
self.inline_comments[key] = ''
293
# remove the entry from defaults
294
if key in self.defaults:
295
self.defaults.remove(key)
296
#
297
if isinstance(value, Section):
298
if not self.has_key(key):
299
self.sections.append(key)
300
dict.__setitem__(self, key, value)
301
elif isinstance(value, dict):
302
# First create the new depth level,
303
# then create the section
304
if not self.has_key(key):
305
self.sections.append(key)
306
new_depth = self.depth + 1
307
dict.__setitem__(
308
self,
309
key,
310
Section(
311
self,
312
new_depth,
313
self.main,
314
indict=value,
315
name=key))
316
else:
317
if not self.has_key(key):
318
self.scalars.append(key)
319
if not self.main.stringify:
320
if isinstance(value, StringTypes):
321
pass
322
elif isinstance(value, (list, tuple)):
323
for entry in value:
324
if not isinstance(entry, StringTypes):
325
raise TypeError, (
326
'Value is not a string "%s".' % entry)
327
else:
328
raise TypeError, 'Value is not a string "%s".' % value
329
dict.__setitem__(self, key, value)
330
331
def __delitem__(self, key):
332
"""Remove items from the sequence when deleting."""
333
dict. __delitem__(self, key)
334
if key in self.scalars:
335
self.scalars.remove(key)
336
else:
337
self.sections.remove(key)
338
del self.comments[key]
339
del self.inline_comments[key]
340
341
def get(self, key, default=None):
342
"""A version of ``get`` that doesn't bypass string interpolation."""
343
try:
344
return self[key]
345
except KeyError:
346
return default
347
348
def update(self, indict):
349
"""A version of update that uses our ``__setitem__``."""
350
for entry in indict:
351
self[entry] = indict[entry]
352
353
def pop(self, key, *args):
354
""" """
355
val = dict.pop(self, key, *args)
356
if key in self.scalars:
357
del self.comments[key]
358
del self.inline_comments[key]
359
self.scalars.remove(key)
360
elif key in self.sections:
361
del self.comments[key]
362
del self.inline_comments[key]
363
self.sections.remove(key)
364
if self.main.interpolation and isinstance(val, StringTypes):
365
return self._interpolate(val)
366
return val
367
368
def popitem(self):
369
"""Pops the first (key,val)"""
370
sequence = (self.scalars + self.sections)
371
if not sequence:
372
raise KeyError, ": 'popitem(): dictionary is empty'"
373
key = sequence[0]
374
val = self[key]
375
del self[key]
376
return key, val
377
378
def clear(self):
379
"""
380
A version of clear that also affects scalars/sections
381
Also clears comments and configspec.
382
383
Leaves other attributes alone :
384
depth/main/parent are not affected
385
"""
386
dict.clear(self)
387
self.scalars = []
388
self.sections = []
389
self.comments = {}
390
self.inline_comments = {}
391
self.configspec = {}
392
393
def setdefault(self, key, default=None):
394
"""A version of setdefault that sets sequence if appropriate."""
395
try:
396
return self[key]
397
except KeyError:
398
self[key] = default
399
return self[key]
400
401
def items(self):
402
""" """
403
return zip((self.scalars + self.sections), self.values())
404
405
def keys(self):
406
""" """
407
return (self.scalars + self.sections)
408
409
def values(self):
410
""" """
411
return [self[key] for key in (self.scalars + self.sections)]
412
413
def iteritems(self):
414
""" """
415
return iter(self.items())
416
417
def iterkeys(self):
418
""" """
419
return iter((self.scalars + self.sections))
420
421
__iter__ = iterkeys
422
423
def itervalues(self):
424
""" """
425
return iter(self.values())
426
427
def __repr__(self):
428
return '{%s}' % ', '.join([('%s: %s' % (repr(key), repr(self[key])))
429
for key in (self.scalars + self.sections)])
430
431
__str__ = __repr__
432
433
# Extra methods - not in a normal dictionary
434
435
def dict(self):
436
"""
437
Return a deepcopy of self as a dictionary.
438
439
All members that are ``Section`` instances are recursively turned to
440
ordinary dictionaries - by calling their ``dict`` method.
441
442
>>> n = a.dict()
443
>>> n == a
444
1
445
>>> n is a
446
0
447
"""
448
newdict = {}
449
for entry in self:
450
this_entry = self[entry]
451
if isinstance(this_entry, Section):
452
this_entry = this_entry.dict()
453
elif isinstance(this_entry, (list, tuple)):
454
# create a copy rather than a reference
455
this_entry = list(this_entry)
456
newdict[entry] = this_entry
457
return newdict
458
459
def rename(self, oldkey, newkey):
460
"""
461
Change a keyname to another, without changing position in sequence.
462
463
Implemented so that transformations can be made on keys,
464
as well as on values. (used by encode and decode)
465
466
Also renames comments.
467
"""
468
if oldkey in self.scalars:
469
the_list = self.scalars
470
elif oldkey in self.sections:
471
the_list = self.sections
472
else:
473
raise KeyError, 'Key "%s" not found.' % oldkey
474
pos = the_list.index(oldkey)
475
#
476
val = self[oldkey]
477
dict.__delitem__(self, oldkey)
478
dict.__setitem__(self, newkey, val)
479
the_list.remove(oldkey)
480
the_list.insert(pos, newkey)
481
comm = self.comments[oldkey]
482
inline_comment = self.inline_comments[oldkey]
483
del self.comments[oldkey]
484
del self.inline_comments[oldkey]
485
self.comments[newkey] = comm
486
self.inline_comments[newkey] = inline_comment
487
488
def walk(self, function, raise_errors=True,
489
call_on_sections=False, **keywargs):
490
"""
491
Walk every member and call a function on the keyword and value.
492
493
Return a dictionary of the return values
494
495
If the function raises an exception, raise the errror
496
unless ``raise_errors=False``, in which case set the return value to
497
``False``.
498
499
Any unrecognised keyword arguments you pass to walk, will be pased on
500
to the function you pass in.
501
502
Note: if ``call_on_sections`` is ``True`` then - on encountering a
503
subsection, *first* the function is called for the *whole* subsection,
504
and then recurses into it's members. This means your function must be
505
able to handle strings, dictionaries and lists. This allows you
506
to change the key of subsections as well as for ordinary members. The
507
return value when called on the whole subsection has to be discarded.
508
509
See the encode and decode methods for examples, including functions.
510
"""
511
out = {}
512
# scalars first
513
for entry in self.scalars[:]:
514
try:
515
out[entry] = function(self, entry, **keywargs)
516
except Exception:
517
if raise_errors:
518
raise
519
else:
520
out[entry] = False
521
# then sections
522
for entry in self.sections[:]:
523
if call_on_sections:
524
try:
525
function(self, entry, **keywargs)
526
except Exception:
527
if raise_errors:
528
raise
529
else:
530
out[entry] = False
531
# previous result is discarded
532
out[entry] = self[entry].walk(
533
function,
534
raise_errors=raise_errors,
535
call_on_sections=call_on_sections,
536
**keywargs)
537
return out
538
539
def decode(self, encoding):
540
"""
541
Decode all strings and values to unicode, using the specified encoding.
542
543
Works with subsections and list values.
544
545
Uses the ``walk`` method.
546
547
Testing ``encode`` and ``decode``.
548
>>> m = ConfigObj(a)
549
>>> m.decode('ascii')
550
>>> def testuni(val):
551
... for entry in val:
552
... if not isinstance(entry, unicode):
553
... print >> sys.stderr, type(entry)
554
... raise AssertionError, 'decode failed.'
555
... if isinstance(val[entry], dict):
556
... testuni(val[entry])
557
... elif not isinstance(val[entry], unicode):
558
... raise AssertionError, 'decode failed.'
559
>>> testuni(m)
560
>>> m.encode('ascii')
561
>>> a == m
562
1
563
"""
564
def decode(section, key, encoding=encoding):
565
""" """
566
val = section[key]
567
if isinstance(val, (list, tuple)):
568
newval = []
569
for entry in val:
570
newval.append(entry.decode(encoding))
571
elif isinstance(val, dict):
572
newval = val
573
else:
574
newval = val.decode(encoding)
575
newkey = key.decode(encoding)
576
section.rename(key, newkey)
577
section[newkey] = newval
578
# using ``call_on_sections`` allows us to modify section names
579
self.walk(decode, call_on_sections=True)
580
581
def encode(self, encoding):
582
"""
583
Encode all strings and values from unicode,
584
using the specified encoding.
585
586
Works with subsections and list values.
587
Uses the ``walk`` method.
588
"""
589
def encode(section, key, encoding=encoding):
590
""" """
591
val = section[key]
592
if isinstance(val, (list, tuple)):
593
newval = []
594
for entry in val:
595
newval.append(entry.encode(encoding))
596
elif isinstance(val, dict):
597
newval = val
598
else:
599
newval = val.encode(encoding)
600
newkey = key.encode(encoding)
601
section.rename(key, newkey)
602
section[newkey] = newval
603
self.walk(encode, call_on_sections=True)
604
605
class ConfigObj(Section):
606
"""
607
An object to read, create, and write config files.
608
609
Testing with duplicate keys and sections.
610
611
>>> c = '''
612
... [hello]
613
... member = value
614
... [hello again]
615
... member = value
616
... [ "hello" ]
617
... member = value
618
... '''
619
>>> ConfigObj(c.split('\\n'), raise_errors = True)
620
Traceback (most recent call last):
621
DuplicateError: Duplicate section name at line 5.
622
623
>>> d = '''
624
... [hello]
625
... member = value
626
... [hello again]
627
... member1 = value
628
... member2 = value
629
... 'member1' = value
630
... [ "and again" ]
631
... member = value
632
... '''
633
>>> ConfigObj(d.split('\\n'), raise_errors = True)
634
Traceback (most recent call last):
635
DuplicateError: Duplicate keyword name at line 6.
636
"""
637
638
_keyword = re.compile(r'''^ # line start
639
(\s*) # indentation
640
( # keyword
641
(?:".*?")| # double quotes
642
(?:'.*?')| # single quotes
643
(?:[^'"=].*?) # no quotes
644
)
645
\s*=\s* # divider
646
(.*) # value (including list values and comments)
647
$ # line end
648
''',
649
re.VERBOSE)
650
651
_sectionmarker = re.compile(r'''^
652
(\s*) # 1: indentation
653
((?:\[\s*)+) # 2: section marker open
654
( # 3: section name open
655
(?:"\s*\S.*?\s*")| # at least one non-space with double quotes
656
(?:'\s*\S.*?\s*')| # at least one non-space with single quotes
657
(?:[^'"\s].*?) # at least one non-space unquoted
658
) # section name close
659
((?:\s*\])+) # 4: section marker close
660
\s*(\#.*)? # 5: optional comment
661
$''',
662
re.VERBOSE)
663
664
# this regexp pulls list values out as a single string
665
# or single values and comments
666
_valueexp = re.compile(r'''^
667
(?:
668
(?:
669
(
670
(?:
671
(?:
672
(?:".*?")| # double quotes
673
(?:'.*?')| # single quotes
674
(?:[^'",\#][^,\#]*?) # unquoted
675
)
676
\s*,\s* # comma
677
)* # match all list items ending in a comma (if any)
678
)
679
(
680
(?:".*?")| # double quotes
681
(?:'.*?')| # single quotes
682
(?:[^'",\#\s][^,]*?) # unquoted
683
)? # last item in a list - or string value
684
)|
685
(,) # alternatively a single comma - empty list
686
)
687
\s*(\#.*)? # optional comment
688
$''',
689
re.VERBOSE)
690
691
# use findall to get the members of a list value
692
_listvalueexp = re.compile(r'''
693
(
694
(?:".*?")| # double quotes
695
(?:'.*?')| # single quotes
696
(?:[^'",\#].*?) # unquoted
697
)
698
\s*,\s* # comma
699
''',
700
re.VERBOSE)
701
702
# this regexp is used for the value
703
# when lists are switched off
704
_nolistvalue = re.compile(r'''^
705
(
706
(?:".*?")| # double quotes
707
(?:'.*?')| # single quotes
708
(?:[^'"\#].*?) # unquoted
709
)
710
\s*(\#.*)? # optional comment
711
$''',
712
re.VERBOSE)
713
714
# regexes for finding triple quoted values on one line
715
_single_line_single = re.compile(r"^'''(.*?)'''\s*(#.*)?$")
716
_single_line_double = re.compile(r'^"""(.*?)"""\s*(#.*)?$')
717
_multi_line_single = re.compile(r"^(.*?)'''\s*(#.*)?$")
718
_multi_line_double = re.compile(r'^(.*?)"""\s*(#.*)?$')
719
720
_triple_quote = {
721
"'''": (_single_line_single, _multi_line_single),
722
'"""': (_single_line_double, _multi_line_double),
723
}
724
725
def __init__(self, infile=None, options=None, **kwargs):
726
"""
727
Parse or create a config file object.
728
729
``ConfigObj(infile=None, options=None, **kwargs)``
730
"""
731
if infile is None:
732
infile = []
733
if options is None:
734
options = {}
735
# keyword arguments take precedence over an options dictionary
736
options.update(kwargs)
737
# init the superclass
738
Section.__init__(self, self, 0, self)
739
#
740
defaults = OPTION_DEFAULTS.copy()
741
for entry in options.keys():
742
if entry not in defaults.keys():
743
raise TypeError, 'Unrecognised option "%s".' % entry
744
# TODO: check the values too
745
# add the explicit options to the defaults
746
defaults.update(options)
747
#
748
# initialise a few variables
749
self._errors = []
750
self.raise_errors = defaults['raise_errors']
751
self.interpolation = defaults['interpolation']
752
self.list_values = defaults['list_values']
753
self.create_empty = defaults['create_empty']
754
self.file_error = defaults['file_error']
755
self.stringify = defaults['stringify']
756
self.indent_type = defaults['indent_type']
757
# used by the write method
758
self.BOM = None
759
#
760
self.initial_comment = []
761
self.final_comment = []
762
#
763
if isinstance(infile, StringTypes):
764
self.filename = os.path.abspath(infile)
765
if os.path.isfile(self.filename):
766
infile = open(self.filename).readlines()
767
elif self.file_error:
768
# raise an error if the file doesn't exist
769
raise IOError, 'Config file not found: "%s".' % self.filename
770
else:
771
# file doesn't already exist
772
if self.create_empty:
773
# this is a good test that the filename specified
774
# isn't impossible - like on a non existent device
775
h = open(self.filename)
776
h.write('')
777
h.close()
778
infile = []
779
elif isinstance(infile, (list, tuple)):
780
self.filename = None
781
elif isinstance(infile, dict):
782
# initialise self
783
# the Section class handles creating subsections
784
if isinstance(infile, ConfigObj):
785
# get a copy of our ConfigObj
786
infile = infile.dict()
787
for entry in infile:
788
self[entry] = infile[entry]
789
self.filename = None
790
del self._errors
791
if defaults['configspec'] is not None:
792
self._handle_configspec(defaults['configspec'])
793
else:
794
self.configspec = None
795
return
796
elif hasattr(infile, 'seek'):
797
# this supports StringIO instances and even file objects
798
self.filename = infile
799
infile.seek(0)
800
infile = infile.readlines()
801
self.filename.seek(0)
802
else:
803
raise TypeError, ('infile must be a filename,'
804
' StringIO instance, or a file as a list.')
805
#
806
# strip trailing '\n' from lines
807
infile = [line.rstrip('\n') for line in infile]
808
#
809
# remove the UTF8 BOM if it is there
810
# FIXME: support other BOM
811
if infile and infile[0].startswith(BOM_UTF8):
812
infile[0] = infile[0][3:]
813
self.BOM = BOM_UTF8
814
else:
815
self.BOM = None
816
#
817
self._parse(infile)
818
# if we had any errors, now is the time to raise them
819
if self._errors:
820
error = ConfigObjError("Parsing failed.")
821
# set the errors attribute; it's a list of tuples:
822
# (error_type, message, line_number)
823
error.errors = self._errors
824
# set the config attribute
825
error.config = self
826
raise error
827
# delete private attributes
828
del self._errors
829
#
830
if defaults['configspec'] is None:
831
self.configspec = None
832
else:
833
self._handle_configspec(defaults['configspec'])
834
835
def _parse(self, infile):
836
"""
837
Actually parse the config file
838
839
Testing Interpolation
840
841
>>> c = ConfigObj()
842
>>> c['DEFAULT'] = {
843
... 'b': 'goodbye',
844
... 'userdir': 'c:\\\\home',
845
... 'c': '%(d)s',
846
... 'd': '%(c)s'
847
... }
848
>>> c['section'] = {
849
... 'a': '%(datadir)s\\\\some path\\\\file.py',
850
... 'b': '%(userdir)s\\\\some path\\\\file.py',
851
... 'c': 'Yo %(a)s',
852
... 'd': '%(not_here)s',
853
... 'e': '%(c)s',
854
... }
855
>>> c['section']['DEFAULT'] = {
856
... 'datadir': 'c:\\\\silly_test',
857
... 'a': 'hello - %(b)s',
858
... }
859
>>> c['section']['a'] == 'c:\\\\silly_test\\\\some path\\\\file.py'
860
1
861
>>> c['section']['b'] == 'c:\\\\home\\\\some path\\\\file.py'
862
1
863
>>> c['section']['c'] == 'Yo hello - goodbye'
864
1
865
866
Switching Interpolation Off
867
868
>>> c.interpolation = False
869
>>> c['section']['a'] == '%(datadir)s\\\\some path\\\\file.py'
870
1
871
>>> c['section']['b'] == '%(userdir)s\\\\some path\\\\file.py'
872
1
873
>>> c['section']['c'] == 'Yo %(a)s'
874
1
875
876
Testing the interpolation errors.
877
878
>>> c.interpolation = True
879
>>> c['section']['d']
880
Traceback (most recent call last):
881
MissingInterpolationOption: missing option "not_here" in interpolation.
882
>>> c['section']['e']
883
Traceback (most recent call last):
884
InterpolationDepthError: max interpolation depth exceeded in value "%(c)s".
885
886
Testing our quoting.
887
888
>>> i._quote('\"""\'\'\'')
889
Traceback (most recent call last):
890
SyntaxError: EOF while scanning triple-quoted string
891
>>> try:
892
... i._quote('\\n', multiline=False)
893
... except ConfigObjError, e:
894
... e.msg
895
'Value "\\n" cannot be safely quoted.'
896
>>> k._quote(' "\' ', multiline=False)
897
Traceback (most recent call last):
898
SyntaxError: EOL while scanning single-quoted string
899
900
Testing with "stringify" off.
901
>>> c.stringify = False
902
>>> c['test'] = 1
903
Traceback (most recent call last):
904
TypeError: Value is not a string "1".
905
"""
906
comment_list = []
907
done_start = False
908
this_section = self
909
maxline = len(infile) - 1
910
cur_index = -1
911
reset_comment = False
912
while cur_index < maxline:
913
if reset_comment:
914
comment_list = []
915
cur_index += 1
916
line = infile[cur_index]
917
sline = line.strip()
918
# do we have anything on the line ?
919
if not sline or sline.startswith('#'):
920
reset_comment = False
921
comment_list.append(line)
922
continue
923
if not done_start:
924
# preserve initial comment
925
self.initial_comment = comment_list
926
comment_list = []
927
done_start = True
928
reset_comment = True
929
# first we check if it's a section marker
930
mat = self._sectionmarker.match(line)
931
## print >> sys.stderr, sline, mat
932
if mat is not None:
933
# is a section line
934
(indent, sect_open, sect_name, sect_close, comment) = (
935
mat.groups())
936
if indent and (self.indent_type is None):
937
self.indent_type = indent[0]
938
cur_depth = sect_open.count('[')
939
if cur_depth != sect_close.count(']'):
940
self._handle_error(
941
"Cannot compute the section depth at line %s.",
942
NestingError, infile, cur_index)
943
continue
944
if cur_depth < this_section.depth:
945
# the new section is dropping back to a previous level
946
try:
947
parent = self._match_depth(
948
this_section,
949
cur_depth).parent
950
except SyntaxError:
951
self._handle_error(
952
"Cannot compute nesting level at line %s.",
953
NestingError, infile, cur_index)
954
continue
955
elif cur_depth == this_section.depth:
956
# the new section is a sibling of the current section
957
parent = this_section.parent
958
elif cur_depth == this_section.depth + 1:
959
# the new section is a child the current section
960
parent = this_section
961
else:
962
self._handle_error(
963
"Section too nested at line %s.",
964
NestingError, infile, cur_index)
965
#
966
sect_name = self._unquote(sect_name)
967
if parent.has_key(sect_name):
968
## print >> sys.stderr, sect_name
969
self._handle_error(
970
'Duplicate section name at line %s.',
971
DuplicateError, infile, cur_index)
972
continue
973
# create the new section
974
this_section = Section(
975
parent,
976
cur_depth,
977
self,
978
name=sect_name)
979
parent[sect_name] = this_section
980
parent.inline_comments[sect_name] = comment
981
parent.comments[sect_name] = comment_list
982
## print >> sys.stderr, parent[sect_name] is this_section
983
continue
984
#
985
# it's not a section marker,
986
# so it should be a valid ``key = value`` line
987
mat = self._keyword.match(line)
988
## print >> sys.stderr, sline, mat
989
if mat is not None:
990
# is a keyword value
991
# value will include any inline comment
992
(indent, key, value) = mat.groups()
993
if indent and (self.indent_type is None):
994
self.indent_type = indent[0]
995
# check for a multiline value
996
if value[:3] in ['"""', "'''"]:
997
try:
998
(value, comment, cur_index) = self._multiline(
999
value, infile, cur_index, maxline)
1000
except SyntaxError:
1001
self._handle_error(
1002
'Parse error in value at line %s.',
1003
ParseError, infile, cur_index)
1004
continue
1005
else:
1006
# extract comment and lists
1007
try:
1008
(value, comment) = self._handle_value(value)
1009
except SyntaxError:
1010
self._handle_error(
1011
'Parse error in value at line %s.',
1012
ParseError, infile, cur_index)
1013
continue
1014
#
1015
## print >> sys.stderr, sline
1016
key = self._unquote(key)
1017
if this_section.has_key(key):
1018
self._handle_error(
1019
'Duplicate keyword name at line %s.',
1020
DuplicateError, infile, cur_index)
1021
continue
1022
# add the key
1023
## print >> sys.stderr, this_section.name
1024
this_section[key] = value
1025
this_section.inline_comments[key] = comment
1026
this_section.comments[key] = comment_list
1027
## print >> sys.stderr, key, this_section[key]
1028
## if this_section.name is not None:
1029
## print >> sys.stderr, this_section
1030
## print >> sys.stderr, this_section.parent
1031
## print >> sys.stderr, this_section.parent[this_section.name]
1032
continue
1033
#
1034
# it neither matched as a keyword
1035
# or a section marker
1036
self._handle_error(
1037
'Invalid line at line "%s".',
1038
ParseError, infile, cur_index)
1039
if self.indent_type is None:
1040
# no indentation used, set the type accordingly
1041
self.indent_type = ''
1042
# preserve the final comment
1043
self.final_comment = comment_list
1044
1045
def _match_depth(self, sect, depth):
1046
"""
1047
Given a section and a depth level, walk back through the sections
1048
parents to see if the depth level matches a previous section.
1049
1050
Return a reference to the right section,
1051
or raise a SyntaxError.
1052
"""
1053
while depth < sect.depth:
1054
if sect is sect.parent:
1055
# we've reached the top level already
1056
raise SyntaxError
1057
sect = sect.parent
1058
if sect.depth == depth:
1059
return sect
1060
# shouldn't get here
1061
raise SyntaxError
1062
1063
def _handle_error(self, text, ErrorClass, infile, cur_index):
1064
"""
1065
Handle an error according to the error settings.
1066
1067
Either raise the error or store it.
1068
The error will have occured at ``cur_index``
1069
"""
1070
line = infile[cur_index]
1071
message = text % cur_index
1072
error = ErrorClass(message, cur_index, line)
1073
if self.raise_errors:
1074
# raise the error - parsing stops here
1075
raise error
1076
# store the error
1077
# reraise when parsing has finished
1078
self._errors.append(error)
1079
1080
def _unquote(self, value):
1081
"""Return an unquoted version of a value"""
1082
if (value[0] == value[-1]) and (value[0] in ('"', "'")):
1083
value = value[1:-1]
1084
return value
1085
1086
def _quote(self, value, multiline=True):
1087
"""
1088
Return a safely quoted version of a value.
1089
1090
Raise a ConfigObjError if the value cannot be safely quoted.
1091
If multiline is ``True`` (default) then use triple quotes
1092
if necessary.
1093
1094
Don't quote values that don't need it.
1095
Recursively quote members of a list and return a comma joined list.
1096
Multiline is ``False`` for lists.
1097
Obey list syntax for empty and single member lists.
1098
"""
1099
if isinstance(value, (list, tuple)):
1100
if not value:
1101
return ','
1102
elif len(value) == 1:
1103
return self._quote(value[0], multiline=False) + ','
1104
return ','.join([self._quote(val, multiline=False)
1105
for val in value])
1106
if not isinstance(value, StringTypes):
1107
if self.stringify:
1108
value = str(value)
1109
else:
1110
raise TypeError, 'Value "%s" is not a string.' % value
1111
squot = "'%s'"
1112
dquot = '"%s"'
1113
noquot = "%s"
1114
wspace_plus = ' \r\t\n\v\t\'"'
1115
tsquot = '"""%s"""'
1116
tdquot = "'''%s'''"
1117
if not value:
1118
return '""'
1119
if not (multiline and
1120
((("'" in value) and ('"' in value)) or ('\n' in value))):
1121
# for normal values either single or double quotes will do
1122
if '\n' in value:
1123
raise ConfigObjError, ('Value "%s" cannot be safely quoted.' %
1124
value)
1125
if ((value[0] not in wspace_plus) and
1126
(value[-1] not in wspace_plus) and
1127
(',' not in value)):
1128
quot = noquot
1129
else:
1130
if ("'" in value) and ('"' in value):
1131
raise ConfigObjError, (
1132
'Value "%s" cannot be safely quoted.' % value)
1133
elif '"' in value:
1134
quot = squot
1135
else:
1136
quot = dquot
1137
else:
1138
# if value has '\n' or "'" *and* '"', it will need triple quotes
1139
if (value.find('"""') != -1) and (value.find("'''") != -1):
1140
raise ConfigObjError, (
1141
'Value "%s" cannot be safely quoted.' % value)
1142
if value.find('"""') == -1:
1143
quot = tdquot
1144
else:
1145
quot = tsquot
1146
return quot % value
1147
1148
def _handle_value(self, value):
1149
"""
1150
Given a value string, unquote, remove comment,
1151
handle lists. (including empty and single member lists)
1152
1153
Testing list values.
1154
1155
>>> testconfig3 = '''
1156
... a = ,
1157
... b = test,
1158
... c = test1, test2 , test3
1159
... d = test1, test2, test3,
1160
... '''
1161
>>> d = ConfigObj(testconfig3.split('\\n'), raise_errors=True)
1162
>>> d['a'] == []
1163
1
1164
>>> d['b'] == ['test']
1165
1
1166
>>> d['c'] == ['test1', 'test2', 'test3']
1167
1
1168
>>> d['d'] == ['test1', 'test2', 'test3']
1169
1
1170
1171
Testing with list values off.
1172
1173
>>> e = ConfigObj(
1174
... testconfig3.split('\\n'),
1175
... raise_errors=True,
1176
... list_values=False)
1177
>>> e['a'] == ','
1178
1
1179
>>> e['b'] == 'test,'
1180
1
1181
>>> e['c'] == 'test1, test2 , test3'
1182
1
1183
>>> e['d'] == 'test1, test2, test3,'
1184
1
1185
1186
Testing creating from a dictionary.
1187
1188
>>> f = {
1189
... 'key1': 'val1',
1190
... 'key2': 'val2',
1191
... 'section 1': {
1192
... 'key1': 'val1',
1193
... 'key2': 'val2',
1194
... 'section 1b': {
1195
... 'key1': 'val1',
1196
... 'key2': 'val2',
1197
... },
1198
... },
1199
... 'section 2': {
1200
... 'key1': 'val1',
1201
... 'key2': 'val2',
1202
... 'section 2b': {
1203
... 'key1': 'val1',
1204
... 'key2': 'val2',
1205
... },
1206
... },
1207
... 'key3': 'val3',
1208
... }
1209
>>> g = ConfigObj(f)
1210
>>> f == g
1211
1
1212
1213
Testing we correctly detect badly built list values (4 of them).
1214
1215
>>> testconfig4 = '''
1216
... config = 3,4,,
1217
... test = 3,,4
1218
... fish = ,,
1219
... dummy = ,,hello, goodbye
1220
... '''
1221
>>> try:
1222
... ConfigObj(testconfig4.split('\\n'))
1223
... except ConfigObjError, e:
1224
... len(e.errors)
1225
4
1226
1227
Testing we correctly detect badly quoted values (4 of them).
1228
1229
>>> testconfig5 = '''
1230
... config = "hello # comment
1231
... test = 'goodbye
1232
... fish = 'goodbye # comment
1233
... dummy = "hello again
1234
... '''
1235
>>> try:
1236
... ConfigObj(testconfig5.split('\\n'))
1237
... except ConfigObjError, e:
1238
... len(e.errors)
1239
4
1240
"""
1241
# do we look for lists in values ?
1242
if not self.list_values:
1243
mat = self._nolistvalue.match(value)
1244
if mat is None:
1245
raise SyntaxError
1246
(value, comment) = mat.groups()
1247
# FIXME: unquoting here can be a source of error
1248
return (self._unquote(value), comment)
1249
mat = self._valueexp.match(value)
1250
if mat is None:
1251
# the value is badly constructed, probably badly quoted,
1252
# or an invalid list
1253
raise SyntaxError
1254
(list_values, single, empty_list, comment) = mat.groups()
1255
if (list_values == '') and (single is None):
1256
# change this if you want to accept empty values
1257
raise SyntaxError
1258
# NOTE: note there is no error handling from here if the regex
1259
# is wrong: then incorrect values will slip through
1260
if empty_list is not None:
1261
# the single comma - meaning an empty list
1262
return ([], comment)
1263
if single is not None:
1264
single = self._unquote(single)
1265
if list_values == '':
1266
# not a list value
1267
return (single, comment)
1268
the_list = self._listvalueexp.findall(list_values)
1269
the_list = [self._unquote(val) for val in the_list]
1270
if single is not None:
1271
the_list += [single]
1272
return (the_list, comment)
1273
1274
def _multiline(self, value, infile, cur_index, maxline):
1275
"""
1276
Extract the value, where we are in a multiline situation
1277
1278
Testing multiline values.
1279
1280
>>> i == {
1281
... 'name4': ' another single line value ',
1282
... 'multi section': {
1283
... 'name4': '\\n Well, this is a\\n multiline '
1284
... 'value\\n ',
1285
... 'name2': '\\n Well, this is a\\n multiline '
1286
... 'value\\n ',
1287
... 'name3': '\\n Well, this is a\\n multiline '
1288
... 'value\\n ',
1289
... 'name1': '\\n Well, this is a\\n multiline '
1290
... 'value\\n ',
1291
... },
1292
... 'name2': ' another single line value ',
1293
... 'name3': ' a single line value ',
1294
... 'name1': ' a single line value ',
1295
... }
1296
1
1297
"""
1298
quot = value[:3]
1299
newvalue = value[3:]
1300
single_line = self._triple_quote[quot][0]
1301
multi_line = self._triple_quote[quot][1]
1302
mat = single_line.match(value)
1303
if mat is not None:
1304
retval = list(mat.groups())
1305
retval.append(cur_index)
1306
return retval
1307
elif newvalue.find(quot) != -1:
1308
# somehow the triple quote is missing
1309
raise SyntaxError
1310
#
1311
while cur_index < maxline:
1312
cur_index += 1
1313
newvalue += '\n'
1314
line = infile[cur_index]
1315
if line.find(quot) == -1:
1316
newvalue += line
1317
else:
1318
# end of multiline, process it
1319
break
1320
else:
1321
# we've got to the end of the config, oops...
1322
raise SyntaxError
1323
mat = multi_line.match(line)
1324
if mat is None:
1325
# a badly formed line
1326
raise SyntaxError
1327
(value, comment) = mat.groups()
1328
return (newvalue + value, comment, cur_index)
1329
1330
def _handle_configspec(self, configspec):
1331
"""Parse the configspec."""
1332
try:
1333
configspec = ConfigObj(
1334
configspec,
1335
raise_errors=True,
1336
file_error=True,
1337
list_values=False)
1338
except ConfigObjError, e:
1339
# FIXME: Should these errors have a reference
1340
# to the already parsed ConfigObj ?
1341
raise ConfigspecError('Parsing configspec failed: %s' % e)
1342
except IOError, e:
1343
raise IOError('Reading configspec failed: %s' % e)
1344
self._set_configspec_value(configspec, self)
1345
1346
def _set_configspec_value(self, configspec, section):
1347
"""Used to recursively set configspec values."""
1348
if '__many__' in configspec.sections:
1349
section.configspec['__many__'] = configspec['__many__']
1350
if len(configspec.sections) > 1:
1351
# FIXME: can we supply any useful information here ?
1352
raise RepeatSectionError
1353
for entry in configspec.scalars:
1354
section.configspec[entry] = configspec[entry]
1355
for entry in configspec.sections:
1356
if entry == '__many__':
1357
continue
1358
if not section.has_key(entry):
1359
section[entry] = {}
1360
self._set_configspec_value(configspec[entry], section[entry])
1361
1362
def _handle_repeat(self, section, configspec):
1363
"""Dynamically assign configspec for repeated section."""
1364
try:
1365
section_keys = configspec.sections
1366
scalar_keys = configspec.scalars
1367
except AttributeError:
1368
section_keys = [entry for entry in configspec
1369
if isinstance(configspec[entry], dict)]
1370
scalar_keys = [entry for entry in configspec
1371
if not isinstance(configspec[entry], dict)]
1372
if '__many__' in section_keys and len(section_keys) > 1:
1373
# FIXME: can we supply any useful information here ?
1374
raise RepeatSectionError
1375
scalars = {}
1376
sections = {}
1377
for entry in scalar_keys:
1378
val = configspec[entry]
1379
scalars[entry] = val
1380
for entry in section_keys:
1381
val = configspec[entry]
1382
if entry == '__many__':
1383
scalars[entry] = val
1384
continue
1385
sections[entry] = val
1386
#
1387
section.configspec = scalars
1388
for entry in sections:
1389
if not section.has_key(entry):
1390
section[entry] = {}
1391
self._handle_repeat(section[entry], sections[entry])
1392
1393
def _write_line(self, indent_string, entry, this_entry, comment):
1394
"""Write an individual line, for the write method"""
1395
return '%s%s = %s%s' % (
1396
indent_string,
1397
self._quote(entry, multiline=False),
1398
self._quote(this_entry),
1399
comment)
1400
1401
def _write_marker(self, indent_string, depth, entry, comment):
1402
"""Write a section marker line"""
1403
return '%s%s%s%s%s' % (
1404
indent_string,
1405
'[' * depth,
1406
self._quote(entry, multiline=False),
1407
']' * depth,
1408
comment)
1409
1410
def _handle_comment(self, comment):
1411
"""
1412
Deal with a comment.
1413
1414
>>> filename = a.filename
1415
>>> a.filename = None
1416
>>> values = a.write()
1417
>>> index = 0
1418
>>> while index < 23:
1419
... index += 1
1420
... line = values[index-1]
1421
... assert line.endswith('# comment ' + str(index))
1422
>>> a.filename = filename
1423
1424
>>> start_comment = ['# Initial Comment', '', '#']
1425
>>> end_comment = ['', '#', '# Final Comment']
1426
>>> newconfig = start_comment + testconfig1.split('\\n') + end_comment
1427
>>> nc = ConfigObj(newconfig)
1428
>>> nc.initial_comment
1429
['# Initial Comment', '', '#']
1430
>>> nc.final_comment
1431
['', '#', '# Final Comment']
1432
>>> nc.initial_comment == start_comment
1433
1
1434
>>> nc.final_comment == end_comment
1435
1
1436
"""
1437
if not comment:
1438
return ''
1439
if self.indent_type == '\t':
1440
start = '\t'
1441
else:
1442
start = ' ' * NUM_INDENT_SPACES
1443
if not comment.startswith('#'):
1444
start += '# '
1445
return (start + comment)
1446
1447
def _compute_indent_string(self, depth):
1448
"""
1449
Compute the indent string, according to current indent_type and depth
1450
"""
1451
if self.indent_type == '':
1452
# no indentation at all
1453
return ''
1454
if self.indent_type == '\t':
1455
return '\t' * depth
1456
if self.indent_type == ' ':
1457
return ' ' * NUM_INDENT_SPACES * depth
1458
raise SyntaxError
1459
1460
# Public methods
1461
1462
def write(self, section=None):
1463
"""
1464
Write the current ConfigObj as a file
1465
1466
tekNico: FIXME: use StringIO instead of real files
1467
1468
>>> filename = a.filename
1469
>>> a.filename = 'test.ini'
1470
>>> a.write()
1471
>>> a.filename = filename
1472
>>> a == ConfigObj('test.ini', raise_errors=True)
1473
1
1474
>>> os.remove('test.ini')
1475
>>> b.filename = 'test.ini'
1476
>>> b.write()
1477
>>> b == ConfigObj('test.ini', raise_errors=True)
1478
1
1479
>>> os.remove('test.ini')
1480
>>> i.filename = 'test.ini'
1481
>>> i.write()
1482
>>> i == ConfigObj('test.ini', raise_errors=True)
1483
1
1484
>>> os.remove('test.ini')
1485
>>> a = ConfigObj()
1486
>>> a['DEFAULT'] = {'a' : 'fish'}
1487
>>> a['a'] = '%(a)s'
1488
>>> a.write()
1489
['a = %(a)s', '[DEFAULT]', 'a = fish']
1490
"""
1491
int_val = 'test'
1492
if self.indent_type is None:
1493
# this can be true if initialised from a dictionary
1494
self.indent_type = DEFAULT_INDENT_TYPE
1495
#
1496
out = []
1497
return_list = True
1498
if section is None:
1499
int_val = self.interpolation
1500
self.interpolation = False
1501
section = self
1502
return_list = False
1503
for line in self.initial_comment:
1504
stripped_line = line.strip()
1505
if stripped_line and not stripped_line.startswith('#'):
1506
line = '# ' + line
1507
out.append(line)
1508
#
1509
indent_string = self._compute_indent_string(section.depth)
1510
for entry in (section.scalars + section.sections):
1511
if entry in section.defaults:
1512
# don't write out default values
1513
continue
1514
for comment_line in section.comments[entry]:
1515
comment_line = comment_line.lstrip()
1516
if comment_line and not comment_line.startswith('#'):
1517
comment_line = '#' + comment_line
1518
out.append(indent_string + comment_line)
1519
this_entry = section[entry]
1520
comment = self._handle_comment(section.inline_comments[entry])
1521
#
1522
if isinstance(this_entry, dict):
1523
# a section
1524
out.append(self._write_marker(
1525
indent_string,
1526
this_entry.depth,
1527
entry,
1528
comment))
1529
out.extend(self.write(this_entry))
1530
else:
1531
out.append(self._write_line(
1532
indent_string,
1533
entry,
1534
this_entry,
1535
comment))
1536
#
1537
if not return_list:
1538
for line in self.final_comment:
1539
stripped_line = line.strip()
1540
if stripped_line and not stripped_line.startswith('#'):
1541
line = '# ' + line
1542
out.append(line)
1543
#
1544
if int_val != 'test':
1545
self.interpolation = int_val
1546
#
1547
if (return_list) or (self.filename is None):
1548
return out
1549
#
1550
if isinstance(self.filename, StringTypes):
1551
h = open(self.filename, 'w')
1552
h.write(self.BOM or '')
1553
h.write('\n'.join(out))
1554
h.close()
1555
else:
1556
self.filename.seek(0)
1557
self.filename.write(self.BOM or '')
1558
self.filename.write('\n'.join(out))
1559
# if we have a stored file object (or StringIO)
1560
# we *don't* close it
1561
1562
def validate(self, validator, section=None):
1563
"""
1564
Test the ConfigObj against a configspec.
1565
1566
It uses the ``validator`` object from *validate.py*.
1567
1568
To run ``validate`` on the current ConfigObj, call: ::
1569
1570
test = config.validate(validator)
1571
1572
(Normally having previously passed in the configspec when the ConfigObj
1573
was created - you can dynamically assign a dictionary of checks to the
1574
``configspec`` attribute of a section though).
1575
1576
It returns ``True`` if everything passes, or a dictionary of
1577
pass/fails (True/False). If every member of a subsection passes, it
1578
will just have the value ``True``. (It also returns ``False`` if all
1579
members fail).
1580
1581
In addition, it converts the values from strings to their native
1582
types if their checks pass (and ``stringify`` is set).
1583
1584
>>> try:
1585
... from validate import Validator
1586
... except ImportError:
1587
... print >> sys.stderr, 'Cannot import the Validator object, skipping the realted tests'
1588
... else:
1589
... config = '''
1590
... test1=40
1591
... test2=hello
1592
... test3=3
1593
... test4=5.0
1594
... [section]
1595
... test1=40
1596
... test2=hello
1597
... test3=3
1598
... test4=5.0
1599
... [[sub section]]
1600
... test1=40
1601
... test2=hello
1602
... test3=3
1603
... test4=5.0
1604
... '''.split('\\n')
1605
... configspec = '''
1606
... test1='integer(30,50)'
1607
... test2='string'
1608
... test3='integer'
1609
... test4='float(6.0)'
1610
... [section ]
1611
... test1='integer(30,50)'
1612
... test2='string'
1613
... test3='integer'
1614
... test4='float(6.0)'
1615
... [[sub section]]
1616
... test1='integer(30,50)'
1617
... test2='string'
1618
... test3='integer'
1619
... test4='float(6.0)'
1620
... '''.split('\\n')
1621
... val = Validator()
1622
... c1 = ConfigObj(config, configspec=configspec)
1623
... test = c1.validate(val)
1624
... test == {
1625
... 'test1': True,
1626
... 'test2': True,
1627
... 'test3': True,
1628
... 'test4': False,
1629
... 'section': {
1630
... 'test1': True,
1631
... 'test2': True,
1632
... 'test3': True,
1633
... 'test4': False,
1634
... 'sub section': {
1635
... 'test1': True,
1636
... 'test2': True,
1637
... 'test3': True,
1638
... 'test4': False,
1639
... },
1640
... },
1641
... }
1642
1
1643
>>> val.check(c1.configspec['test4'], c1['test4'])
1644
Traceback (most recent call last):
1645
VdtValueTooSmallError: the value "5.0" is too small.
1646
1647
>>> val_test_config = '''
1648
... key = 0
1649
... key2 = 1.1
1650
... [section]
1651
... key = some text
1652
... key2 = 1.1, 3.0, 17, 6.8
1653
... [[sub-section]]
1654
... key = option1
1655
... key2 = True'''.split('\\n')
1656
>>> val_test_configspec = '''
1657
... key = integer
1658
... key2 = float
1659
... [section]
1660
... key = string
1661
... key2 = float_list(4)
1662
... [[sub-section]]
1663
... key = option(option1, option2)
1664
... key2 = boolean'''.split('\\n')
1665
>>> val_test = ConfigObj(val_test_config, configspec=val_test_configspec)
1666
>>> val_test.validate(val)
1667
1
1668
>>> val_test['key'] = 'text not a digit'
1669
>>> val_res = val_test.validate(val)
1670
>>> val_res == {'key2': True, 'section': True, 'key': False}
1671
1
1672
>>> configspec = '''
1673
... test1='integer(30,50, default=40)'
1674
... test2='string(default="hello")'
1675
... test3='integer(default=3)'
1676
... test4='float(6.0, default=6.0)'
1677
... [section ]
1678
... test1='integer(30,50, default=40)'
1679
... test2='string(default="hello")'
1680
... test3='integer(default=3)'
1681
... test4='float(6.0, default=6.0)'
1682
... [[sub section]]
1683
... test1='integer(30,50, default=40)'
1684
... test2='string(default="hello")'
1685
... test3='integer(default=3)'
1686
... test4='float(6.0, default=6.0)'
1687
... '''.split('\\n')
1688
>>> default_test = ConfigObj(['test1=30'], configspec=configspec)
1689
>>> default_test
1690
{'test1': '30', 'section': {'sub section': {}}}
1691
>>> default_test.validate(val)
1692
1
1693
>>> default_test == {
1694
... 'test1': 30,
1695
... 'test2': 'hello',
1696
... 'test3': 3,
1697
... 'test4': 6.0,
1698
... 'section': {
1699
... 'test1': 40,
1700
... 'test2': 'hello',
1701
... 'test3': 3,
1702
... 'test4': 6.0,
1703
... 'sub section': {
1704
... 'test1': 40,
1705
... 'test3': 3,
1706
... 'test2': 'hello',
1707
... 'test4': 6.0,
1708
... },
1709
... },
1710
... }
1711
1
1712
1713
Now testing with repeated sections : BIG TEST
1714
1715
>>> repeated_1 = '''
1716
... [dogs]
1717
... [[__many__]] # spec for a dog
1718
... fleas = boolean(default=True)
1719
... tail = option(long, short, default=long)
1720
... name = string(default=rover)
1721
... [[[__many__]]] # spec for a puppy
1722
... name = string(default="son of rover")
1723
... age = float(default=0.0)
1724
... [cats]
1725
... [[__many__]] # spec for a cat
1726
... fleas = boolean(default=True)
1727
... tail = option(long, short, default=short)
1728
... name = string(default=pussy)
1729
... [[[__many__]]] # spec for a kitten
1730
... name = string(default="son of pussy")
1731
... age = float(default=0.0)
1732
... '''.split('\\n')
1733
>>> repeated_2 = '''
1734
... [dogs]
1735
...
1736
... # blank dogs with puppies
1737
... # should be filled in by the configspec
1738
... [[dog1]]
1739
... [[[puppy1]]]
1740
... [[[puppy2]]]
1741
... [[[puppy3]]]
1742
... [[dog2]]
1743
... [[[puppy1]]]
1744
... [[[puppy2]]]
1745
... [[[puppy3]]]
1746
... [[dog3]]
1747
... [[[puppy1]]]
1748
... [[[puppy2]]]
1749
... [[[puppy3]]]
1750
... [cats]
1751
...
1752
... # blank cats with kittens
1753
... # should be filled in by the configspec
1754
... [[cat1]]
1755
... [[[kitten1]]]
1756
... [[[kitten2]]]
1757
... [[[kitten3]]]
1758
... [[cat2]]
1759
... [[[kitten1]]]
1760
... [[[kitten2]]]
1761
... [[[kitten3]]]
1762
... [[cat3]]
1763
... [[[kitten1]]]
1764
... [[[kitten2]]]
1765
... [[[kitten3]]]
1766
... '''.split('\\n')
1767
>>> repeated_3 = '''
1768
... [dogs]
1769
...
1770
... [[dog1]]
1771
... [[dog2]]
1772
... [[dog3]]
1773
... [cats]
1774
...
1775
... [[cat1]]
1776
... [[cat2]]
1777
... [[cat3]]
1778
... '''.split('\\n')
1779
>>> repeated_4 = '''
1780
... [__many__]
1781
...
1782
... name = string(default=Michael)
1783
... age = float(default=0.0)
1784
... sex = option(m, f, default=m)
1785
... '''.split('\\n')
1786
>>> repeated_5 = '''
1787
... [cats]
1788
... [[__many__]]
1789
... fleas = boolean(default=True)
1790
... tail = option(long, short, default=short)
1791
... name = string(default=pussy)
1792
... [[[description]]]
1793
... height = float(default=3.3)
1794
... weight = float(default=6)
1795
... [[[[coat]]]]
1796
... fur = option(black, grey, brown, "tortoise shell", default=black)
1797
... condition = integer(0,10, default=5)
1798
... '''.split('\\n')
1799
>>> from validate import Validator
1800
>>> val= Validator()
1801
>>> repeater = ConfigObj(repeated_2, configspec=repeated_1)
1802
>>> repeater.validate(val)
1803
1
1804
>>> repeater == {
1805
... 'dogs': {
1806
... 'dog1': {
1807
... 'fleas': True,
1808
... 'tail': 'long',
1809
... 'name': 'rover',
1810
... 'puppy1': {'name': 'son of rover', 'age': 0.0},
1811
... 'puppy2': {'name': 'son of rover', 'age': 0.0},
1812
... 'puppy3': {'name': 'son of rover', 'age': 0.0},
1813
... },
1814
... 'dog2': {
1815
... 'fleas': True,
1816
... 'tail': 'long',
1817
... 'name': 'rover',
1818
... 'puppy1': {'name': 'son of rover', 'age': 0.0},
1819
... 'puppy2': {'name': 'son of rover', 'age': 0.0},
1820
... 'puppy3': {'name': 'son of rover', 'age': 0.0},
1821
... },
1822
... 'dog3': {
1823
... 'fleas': True,
1824
... 'tail': 'long',
1825
... 'name': 'rover',
1826
... 'puppy1': {'name': 'son of rover', 'age': 0.0},
1827
... 'puppy2': {'name': 'son of rover', 'age': 0.0},
1828
... 'puppy3': {'name': 'son of rover', 'age': 0.0},
1829
... },
1830
... },
1831
... 'cats': {
1832
... 'cat1': {
1833
... 'fleas': True,
1834
... 'tail': 'short',
1835
... 'name': 'pussy',
1836
... 'kitten1': {'name': 'son of pussy', 'age': 0.0},
1837
... 'kitten2': {'name': 'son of pussy', 'age': 0.0},
1838
... 'kitten3': {'name': 'son of pussy', 'age': 0.0},
1839
... },
1840
... 'cat2': {
1841
... 'fleas': True,
1842
... 'tail': 'short',
1843
... 'name': 'pussy',
1844
... 'kitten1': {'name': 'son of pussy', 'age': 0.0},
1845
... 'kitten2': {'name': 'son of pussy', 'age': 0.0},
1846
... 'kitten3': {'name': 'son of pussy', 'age': 0.0},
1847
... },
1848
... 'cat3': {
1849
... 'fleas': True,
1850
... 'tail': 'short',
1851
... 'name': 'pussy',
1852
... 'kitten1': {'name': 'son of pussy', 'age': 0.0},
1853
... 'kitten2': {'name': 'son of pussy', 'age': 0.0},
1854
... 'kitten3': {'name': 'son of pussy', 'age': 0.0},
1855
... },
1856
... },
1857
... }
1858
1
1859
>>> repeater = ConfigObj(repeated_3, configspec=repeated_1)
1860
>>> repeater.validate(val)
1861
1
1862
>>> repeater == {
1863
... 'cats': {
1864
... 'cat1': {'fleas': True, 'tail': 'short', 'name': 'pussy'},
1865
... 'cat2': {'fleas': True, 'tail': 'short', 'name': 'pussy'},
1866
... 'cat3': {'fleas': True, 'tail': 'short', 'name': 'pussy'},
1867
... },
1868
... 'dogs': {
1869
... 'dog1': {'fleas': True, 'tail': 'long', 'name': 'rover'},
1870
... 'dog2': {'fleas': True, 'tail': 'long', 'name': 'rover'},
1871
... 'dog3': {'fleas': True, 'tail': 'long', 'name': 'rover'},
1872
... },
1873
... }
1874
1
1875
>>> repeater = ConfigObj(configspec=repeated_4)
1876
>>> repeater['Michael'] = {}
1877
>>> repeater.validate(val)
1878
1
1879
>>> repeater == {
1880
... 'Michael': {'age': 0.0, 'name': 'Michael', 'sex': 'm'},
1881
... }
1882
1
1883
>>> repeater = ConfigObj(repeated_3, configspec=repeated_5)
1884
>>> repeater == {
1885
... 'dogs': {'dog1': {}, 'dog2': {}, 'dog3': {}},
1886
... 'cats': {'cat1': {}, 'cat2': {}, 'cat3': {}},
1887
... }
1888
1
1889
>>> repeater.validate(val)
1890
1
1891
>>> repeater == {
1892
... 'dogs': {'dog1': {}, 'dog2': {}, 'dog3': {}},
1893
... 'cats': {
1894
... 'cat1': {
1895
... 'fleas': True,
1896
... 'tail': 'short',
1897
... 'name': 'pussy',
1898
... 'description': {
1899
... 'weight': 6.0,
1900
... 'height': 3.2999999999999998,
1901
... 'coat': {'fur': 'black', 'condition': 5},
1902
... },
1903
... },
1904
... 'cat2': {
1905
... 'fleas': True,
1906
... 'tail': 'short',
1907
... 'name': 'pussy',
1908
... 'description': {
1909
... 'weight': 6.0,
1910
... 'height': 3.2999999999999998,
1911
... 'coat': {'fur': 'black', 'condition': 5},
1912
... },
1913
... },
1914
... 'cat3': {
1915
... 'fleas': True,
1916
... 'tail': 'short',
1917
... 'name': 'pussy',
1918
... 'description': {
1919
... 'weight': 6.0,
1920
... 'height': 3.2999999999999998,
1921
... 'coat': {'fur': 'black', 'condition': 5},
1922
... },
1923
... },
1924
... },
1925
... }
1926
1
1927
1928
Test that interpolation is preserved for validated string values.
1929
>>> t = ConfigObj()
1930
>>> t['DEFAULT'] = {}
1931
>>> t['DEFAULT']['test'] = 'a'
1932
>>> t['test'] = '%(test)s'
1933
>>> t['test']
1934
'a'
1935
>>> v = Validator()
1936
>>> t.configspec = {'test': 'string'}
1937
>>> t.validate(v)
1938
1
1939
>>> t.interpolation = False
1940
>>> t
1941
{'test': '%(test)s', 'DEFAULT': {'test': 'a'}}
1942
1943
FIXME: Above tests will fail if we couldn't import Validator (the ones
1944
that don't raise errors will produce different output and still fail as
1945
tests)
1946
"""
1947
if section is None:
1948
if self.configspec is None:
1949
raise ValueError, 'No configspec supplied.'
1950
section = self
1951
#
1952
spec_section = section.configspec
1953
if '__many__' in section.configspec:
1954
many = spec_section['__many__']
1955
# dynamically assign the configspecs
1956
# for the sections below
1957
for entry in section.sections:
1958
self._handle_repeat(section[entry], many)
1959
#
1960
out = {}
1961
ret_true = True
1962
ret_false = True
1963
for entry in spec_section:
1964
if entry == '__many__':
1965
continue
1966
if (not entry in section.scalars) or (entry in section.defaults):
1967
# missing entries
1968
# or entries from defaults
1969
missing = True
1970
val = None
1971
else:
1972
missing = False
1973
val = section[entry]
1974
try:
1975
check = validator.check(spec_section[entry],
1976
val,
1977
missing=missing)
1978
except validator.baseErrorClass:
1979
out[entry] = False
1980
ret_true = False
1981
# MIKE: we want to raise all other exceptions, not just print ?
1982
## except Exception, err:
1983
## print err
1984
else:
1985
ret_false = False
1986
out[entry] = True
1987
if self.stringify or missing:
1988
# if we are doing type conversion
1989
# or the value is a supplied default
1990
if not self.stringify:
1991
if isinstance(check, (list, tuple)):
1992
# preserve lists
1993
check = [str(item) for item in check]
1994
elif missing and check is None:
1995
# convert the None from a default to a ''
1996
check = ''
1997
else:
1998
check = str(check)
1999
if (check != val) or missing:
2000
section[entry] = check
2001
if missing and entry not in section.defaults:
2002
section.defaults.append(entry)
2003
#
2004
for entry in section.sections:
2005
check = self.validate(validator, section[entry])
2006
out[entry] = check
2007
if check == False:
2008
ret_true = False
2009
elif check == True:
2010
ret_false = False
2011
else:
2012
ret_true = False
2013
ret_false = False
2014
#
2015
if ret_true:
2016
return True
2017
elif ret_false:
2018
return False
2019
else:
2020
return out
2021
2022
class SimpleVal(object):
2023
"""
2024
A simple validator.
2025
Can be used to check that all members expected are present.
2026
2027
To use it, provide a configspec with all your members in (the value given
2028
will be ignored). Pass an instance of ``SimpleVal`` to the ``validate``
2029
method of your ``ConfigObj``. ``validate`` will return ``True`` if all
2030
members are present, or a dictionary with True/False meaning
2031
present/missing. (Whole missing sections will be replaced with ``False``)
2032
2033
>>> val = SimpleVal()
2034
>>> config = '''
2035
... test1=40
2036
... test2=hello
2037
... test3=3
2038
... test4=5.0
2039
... [section]
2040
... test1=40
2041
... test2=hello
2042
... test3=3
2043
... test4=5.0
2044
... [[sub section]]
2045
... test1=40
2046
... test2=hello
2047
... test3=3
2048
... test4=5.0
2049
... '''.split('\\n')
2050
>>> configspec = '''
2051
... test1=''
2052
... test2=''
2053
... test3=''
2054
... test4=''
2055
... [section]
2056
... test1=''
2057
... test2=''
2058
... test3=''
2059
... test4=''
2060
... [[sub section]]
2061
... test1=''
2062
... test2=''
2063
... test3=''
2064
... test4=''
2065
... '''.split('\\n')
2066
>>> o = ConfigObj(config, configspec=configspec)
2067
>>> o.validate(val)
2068
1
2069
>>> o = ConfigObj(configspec=configspec)
2070
>>> o.validate(val)
2071
0
2072
"""
2073
2074
def __init__(self):
2075
self.baseErrorClass = ConfigObjError
2076
2077
def check(self, check, member, missing=False):
2078
"""A dummy check method, always returns the value unchanged."""
2079
if missing:
2080
raise self.baseErrorClass
2081
return member
2082
2083
# FIXME: test error code for badly built multiline values
2084
# FIXME: test handling of StringIO
2085
# FIXME: test interpolation with writing
2086
2087
def _doctest():
2088
"""
2089
Dummy function to hold some of the doctests.
2090
2091
>>> a.depth
2092
0
2093
>>> a == {
2094
... 'key2': 'val',
2095
... 'key1': 'val',
2096
... 'lev1c': {
2097
... 'lev2c': {
2098
... 'lev3c': {
2099
... 'key1': 'val',
2100
... },
2101
... },
2102
... },
2103
... 'lev1b': {
2104
... 'key2': 'val',
2105
... 'key1': 'val',
2106
... 'lev2ba': {
2107
... 'key1': 'val',
2108
... },
2109
... 'lev2bb': {
2110
... 'key1': 'val',
2111
... },
2112
... },
2113
... 'lev1a': {
2114
... 'key2': 'val',
2115
... 'key1': 'val',
2116
... },
2117
... }
2118
1
2119
>>> b.depth
2120
0
2121
>>> b == {
2122
... 'key3': 'val3',
2123
... 'key2': 'val2',
2124
... 'key1': 'val1',
2125
... 'section 1': {
2126
... 'keys11': 'val1',
2127
... 'keys13': 'val3',
2128
... 'keys12': 'val2',
2129
... },
2130
... 'section 2': {
2131
... 'section 2 sub 1': {
2132
... 'fish': '3',
2133
... },
2134
... 'keys21': 'val1',
2135
... 'keys22': 'val2',
2136
... 'keys23': 'val3',
2137
... },
2138
... }
2139
1
2140
>>> t = '''
2141
... 'a' = b # !"$%^&*(),::;'@~#= 33
2142
... "b" = b #= 6, 33
2143
... ''' .split('\\n')
2144
>>> t2 = ConfigObj(t)
2145
>>> assert t2 == {'a': 'b', 'b': 'b'}
2146
>>> t2.inline_comments['b'] = ''
2147
>>> del t2['a']
2148
>>> assert t2.write() == ['','b = b', '']
2149
"""
2150
2151
if __name__ == '__main__':
2152
# run the code tests in doctest format
2153
#
2154
testconfig1 = """\
2155
key1= val # comment 1
2156
key2= val # comment 2
2157
# comment 3
2158
[lev1a] # comment 4
2159
key1= val # comment 5
2160
key2= val # comment 6
2161
# comment 7
2162
[lev1b] # comment 8
2163
key1= val # comment 9
2164
key2= val # comment 10
2165
# comment 11
2166
[[lev2ba]] # comment 12
2167
key1= val # comment 13
2168
# comment 14
2169
[[lev2bb]] # comment 15
2170
key1= val # comment 16
2171
# comment 17
2172
[lev1c] # comment 18
2173
# comment 19
2174
[[lev2c]] # comment 20
2175
# comment 21
2176
[[[lev3c]]] # comment 22
2177
key1 = val # comment 23"""
2178
#
2179
testconfig2 = """\
2180
key1 = 'val1'
2181
key2 = "val2"
2182
key3 = val3
2183
["section 1"] # comment
2184
keys11 = val1
2185
keys12 = val2
2186
keys13 = val3
2187
[section 2]
2188
keys21 = val1
2189
keys22 = val2
2190
keys23 = val3
2191
2192
[['section 2 sub 1']]
2193
fish = 3
2194
"""
2195
#
2196
testconfig6 = '''
2197
name1 = """ a single line value """ # comment
2198
name2 = \''' another single line value \''' # comment
2199
name3 = """ a single line value """
2200
name4 = \''' another single line value \'''
2201
[ "multi section" ]
2202
name1 = """
2203
Well, this is a
2204
multiline value
2205
"""
2206
name2 = \'''
2207
Well, this is a
2208
multiline value
2209
\'''
2210
name3 = """
2211
Well, this is a
2212
multiline value
2213
""" # a comment
2214
name4 = \'''
2215
Well, this is a
2216
multiline value
2217
\''' # I guess this is a comment too
2218
'''
2219
#
2220
import doctest
2221
m = sys.modules.get('__main__')
2222
globs = m.__dict__.copy()
2223
a = ConfigObj(testconfig1.split('\n'), raise_errors=True)
2224
b = ConfigObj(testconfig2.split('\n'), raise_errors=True)
2225
i = ConfigObj(testconfig6.split('\n'), raise_errors=True)
2226
globs.update({
2227
'INTP_VER': INTP_VER,
2228
'a': a,
2229
'b': b,
2230
'i': i,
2231
})
2232
doctest.testmod(m, globs=globs)
2233
2234
"""
2235
BUGS
2236
====
2237
2238
With list values off, ConfigObj can incorrectly unquote values. (This makes
2239
it impossible to use listquote to handle your list values for you - for
2240
nested lists. Not handling quotes at all would be better for this)
2241
2242
TODO
2243
====
2244
2245
A method to optionally remove uniform indentation from multiline values.
2246
(do as an example of using ``walk`` - along with string-escape)
2247
2248
INCOMPATIBLE CHANGES
2249
====================
2250
2251
(I have removed a lot of needless complications - this list is probably not
2252
conclusive, many option/attribute/method names have changed)
2253
2254
Case sensitive
2255
2256
The only valid divider is '='
2257
2258
We've removed line continuations with '\'
2259
2260
No recursive lists in values
2261
2262
No empty section
2263
2264
No distinction between flatfiles and non flatfiles
2265
2266
Change in list syntax - use commas to indicate list, not parentheses
2267
(square brackets and parentheses are no longer recognised as lists)
2268
2269
';' is no longer valid for comments and no multiline comments
2270
2271
No attribute access
2272
2273
We don't allow empty values - have to use '' or ""
2274
2275
In ConfigObj 3 - setting a non-flatfile member to ``None`` would
2276
initialise it as an empty section.
2277
2278
The escape entities '&mjf-lf;' and '&mjf-quot;' have gone
2279
replaced by triple quote, multiple line values.
2280
2281
The ``newline``, ``force_return``, and ``default`` options have gone
2282
2283
The ``encoding`` and ``backup_encoding`` methods have gone - replaced
2284
with the ``encode`` and ``decode`` methods.
2285
2286
``fileerror`` and ``createempty`` options have become ``file_error`` and
2287
``create_empty``
2288
2289
Partial configspecs (for specifying the order members should be written
2290
out and which should be present) have gone. The configspec is no longer
2291
used to specify order for the ``write`` method.
2292
2293
Exceeding the maximum depth of recursion in string interpolation now
2294
raises an error ``InterpolationDepthError``.
2295
2296
Specifying a value for interpolation which doesn't exist now raises an
2297
error ``MissingInterpolationOption`` (instead of merely being ignored).
2298
2299
The ``writein`` method has been removed.
2300
2301
The comments attribute is now a list (``inline_comments`` equates to the
2302
old comments attribute)
2303
2304
ISSUES
2305
======
2306
2307
You can't have a keyword with the same name as a section (in the same
2308
section). They are both dictionary keys - so they would overlap.
2309
2310
Interpolation checks first the 'DEFAULT' subsection of the current
2311
section, next it checks the 'DEFAULT' section of the parent section,
2312
last it checks the 'DEFAULT' section of the main section.
2313
2314
Logically a 'DEFAULT' section should apply to all subsections of the *same
2315
parent* - this means that checking the 'DEFAULT' subsection in the
2316
*current section* is not necessarily logical ?
2317
2318
In order to simplify unicode support (which is possibly of limited value
2319
in a config file) I have removed automatic support and added the
2320
``encode`` and ``decode methods, which can be used to transform keys and
2321
entries. Because the regex looks for specific values on inital parsing
2322
(i.e. the quotes and the equals signs) it can only read ascii compatible
2323
encodings. For unicode use ``UTF8``, which is ASCII compatible.
2324
2325
Does it matter that we don't support the ':' divider, which is supported
2326
by ``ConfigParser`` ?
2327
2328
Following error with "list_values=False" : ::
2329
2330
>>> a = ["a='hello', 'goodbye'"]
2331
>>>
2332
>>> c(a, list_values=False)
2333
{'a': "hello', 'goodbye"}
2334
2335
The regular expression correctly removes the value -
2336
``"'hello', 'goodbye'"`` and then unquote just removes the front and
2337
back quotes (called from ``_handle_value``). What should we do ??
2338
(*ought* to raise exception because it's an invalid value if lists are
2339
off *sigh*. This is not what you want if you want to do your own list
2340
processing - would be *better* in this case not to unquote.)
2341
2342
String interpolation and validation don't play well together. When
2343
validation changes type it sets the value. This will correctly fetch the
2344
value using interpolation - but then overwrite the interpolation reference.
2345
If the value is unchanged by validation (it's a string) - but other types
2346
will be.
2347
2348
List Value Syntax
2349
=================
2350
2351
List values allow you to specify multiple values for a keyword. This
2352
maps to a list as the resulting Python object when parsed.
2353
2354
The syntax for lists is easy. A list is a comma separated set of values.
2355
If these values contain quotes, the hash mark, or commas, then the values
2356
can be surrounded by quotes. e.g. : ::
2357
2358
keyword = value1, 'value 2', "value 3"
2359
2360
If a value needs to be a list, but only has one member, then you indicate
2361
this with a trailing comma. e.g. : ::
2362
2363
keyword = "single value",
2364
2365
If a value needs to be a list, but it has no members, then you indicate
2366
this with a single comma. e.g. : ::
2367
2368
keyword = , # an empty list
2369
2370
Using triple quotes it will be possible for single values to contain
2371
newlines and *both* single quotes and double quotes. Triple quotes aren't
2372
allowed in list values. This means that the members of list values can't
2373
contain carriage returns (or line feeds :-) or both quote values.
2374
2375
CHANGELOG
2376
=========
2377
2378
2005/10/09
2379
----------
2380
2381
Fixed typo in ``write`` method. (Testing for the wrong value when resetting
2382
``interpolation``).
2383
2384
2005/09/16
2385
----------
2386
2387
Fixed bug in ``setdefault`` - creating a new section *wouldn't* return
2388
a reference to the new section.
2389
2390
2005/09/09
2391
----------
2392
2393
Removed ``PositionError``.
2394
2395
Allowed quotes around keys as documented.
2396
2397
Fixed bug with commas in comments. (matched as a list value)
2398
2399
Beta 5
2400
2401
2005/09/07
2402
----------
2403
2404
Fixed bug in initialising ConfigObj from a ConfigObj.
2405
2406
Changed the mailing list address.
2407
2408
Beta 4
2409
2410
2005/09/03
2411
----------
2412
2413
Fixed bug in ``Section__delitem__`` oops.
2414
2415
2005/08/28
2416
----------
2417
2418
Interpolation is switched off before writing out files.
2419
2420
Fixed bug in handling ``StringIO`` instances. (Thanks to report from
2421
"Gustavo Niemeyer" <gustavo@niemeyer.net>)
2422
2423
Moved the doctests from the ``__init__`` method to a separate function.
2424
(For the sake of IDE calltips).
2425
2426
Beta 3
2427
2428
2005/08/26
2429
----------
2430
2431
String values unchanged by validation *aren't* reset. This preserves
2432
interpolation in string values.
2433
2434
2005/08/18
2435
----------
2436
2437
None from a default is turned to '' if stringify is off - because setting
2438
a value to None raises an error.
2439
2440
Version 4.0.0-beta2
2441
2442
2005/08/16
2443
----------
2444
2445
By Nicola Larosa
2446
2447
Actually added the RepeatSectionError class ;-)
2448
2449
2005/08/15
2450
----------
2451
2452
If ``stringify`` is off - list values are preserved by the ``validate``
2453
method. (Bugfix)
2454
2455
2005/08/14
2456
----------
2457
2458
By Michael Foord
2459
2460
Fixed ``simpleVal``.
2461
2462
Added ``RepeatSectionError`` error if you have additional sections in a
2463
section with a ``__many__`` (repeated) section.
2464
2465
By Nicola Larosa
2466
2467
Reworked the ConfigObj._parse, _handle_error and _multiline methods:
2468
mutated the self._infile, self._index and self._maxline attributes into
2469
local variables and method parameters
2470
2471
Reshaped the ConfigObj._multiline method to better reflect its semantics
2472
2473
Changed the "default_test" test in ConfigObj.validate to check the fix for
2474
the bug in validate.Validator.check
2475
2476
2005/08/13
2477
----------
2478
2479
By Nicola Larosa
2480
2481
Updated comments at top
2482
2483
2005/08/11
2484
----------
2485
2486
By Michael Foord
2487
2488
Implemented repeated sections.
2489
2490
By Nicola Larosa
2491
2492
Added test for interpreter version: raises RuntimeError if earlier than
2493
2.2
2494
2495
2005/08/10
2496
----------
2497
2498
By Michael Foord
2499
2500
Implemented default values in configspecs.
2501
2502
By Nicola Larosa
2503
2504
Fixed naked except: clause in validate that was silencing the fact
2505
that Python2.2 does not have dict.pop
2506
2507
2005/08/08
2508
----------
2509
2510
By Michael Foord
2511
2512
Bug fix causing error if file didn't exist.
2513
2514
2005/08/07
2515
----------
2516
2517
By Nicola Larosa
2518
2519
Adjusted doctests for Python 2.2.3 compatibility
2520
2521
2005/08/04
2522
----------
2523
2524
By Michael Foord
2525
2526
Added the inline_comments attribute
2527
2528
We now preserve and rewrite all comments in the config file
2529
2530
configspec is now a section attribute
2531
2532
The validate method changes values in place
2533
2534
Added InterpolationError
2535
2536
The errors now have line number, line, and message attributes. This
2537
simplifies error handling
2538
2539
Added __docformat__
2540
2541
2005/08/03
2542
----------
2543
2544
By Michael Foord
2545
2546
Fixed bug in Section.pop (now doesn't raise KeyError if a default value
2547
is specified)
2548
2549
Replaced ``basestring`` with ``types.StringTypes``
2550
2551
Removed the ``writein`` method
2552
2553
Added __version__
2554
2555
2005/07/29
2556
----------
2557
2558
By Nicola Larosa
2559
2560
Indentation in config file is not significant anymore, subsections are
2561
designated by repeating square brackets
2562
2563
Adapted all tests and docs to the new format
2564
2565
2005/07/28
2566
----------
2567
2568
By Nicola Larosa
2569
2570
Added more tests
2571
2572
2005/07/23
2573
----------
2574
2575
By Nicola Larosa
2576
2577
Reformatted final docstring in ReST format, indented it for easier folding
2578
2579
Code tests converted to doctest format, and scattered them around
2580
in various docstrings
2581
2582
Walk method rewritten using scalars and sections attributes
2583
2584
2005/07/22
2585
----------
2586
2587
By Nicola Larosa
2588
2589
Changed Validator and SimpleVal "test" methods to "check"
2590
2591
More code cleanup
2592
2593
2005/07/21
2594
----------
2595
2596
Changed Section.sequence to Section.scalars and Section.sections
2597
2598
Added Section.configspec
2599
2600
Sections in the root section now have no extra indentation
2601
2602
Comments now better supported in Section and preserved by ConfigObj
2603
2604
Comments also written out
2605
2606
Implemented initial_comment and final_comment
2607
2608
A scalar value after a section will now raise an error
2609
2610
2005/07/20
2611
----------
2612
2613
Fixed a couple of bugs
2614
2615
Can now pass a tuple instead of a list
2616
2617
Simplified dict and walk methods
2618
2619
Added __str__ to Section
2620
2621
2005/07/10
2622
----------
2623
2624
By Nicola Larosa
2625
2626
More code cleanup
2627
2628
2005/07/08
2629
----------
2630
2631
The stringify option implemented. On by default.
2632
2633
2005/07/07
2634
----------
2635
2636
Renamed private attributes with a single underscore prefix.
2637
2638
Changes to interpolation - exceeding recursion depth, or specifying a
2639
missing value, now raise errors.
2640
2641
Changes for Python 2.2 compatibility. (changed boolean tests - removed
2642
``is True`` and ``is False``)
2643
2644
Added test for duplicate section and member (and fixed bug)
2645
2646
2005/07/06
2647
----------
2648
2649
By Nicola Larosa
2650
2651
Code cleanup
2652
2653
2005/07/02
2654
----------
2655
2656
Version 0.1.0
2657
2658
Now properly handles values including comments and lists.
2659
2660
Better error handling.
2661
2662
String interpolation.
2663
2664
Some options implemented.
2665
2666
You can pass a Section a dictionary to initialise it.
2667
2668
Setting a Section member to a dictionary will create a Section instance.
2669
2670
2005/06/26
2671
----------
2672
2673
Version 0.0.1
2674
2675
Experimental reader.
2676
2677
A reasonably elegant implementation - a basic reader in 160 lines of code.
2678
2679
*A programming language is a medium of expression.* - Paul Graham
2680
"""
2681
Loggerhead is a web-based interface for Breezy
Version: 2.0.1