← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/util/configobj/configobj.py

  • Committer: Robert Collins
  • Date: 2006-03-11 13:58:48 UTC
  • mto: (1615.1.2 bzr.mbp.integration)
  • mto: This revision was merged to the branch mainline in revision 1616.
  • Revision ID: robertc@robertcollins.net-20060311135848-789fa616b8da4662
Note potential improvements in knit adds.

Show diffs side-by-side

added added

removed removed

Lines of Context:
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