← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/util/configobj/docs/configobj.txt

(mbp) merge bzr.dev to 0.8, prepare for release

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/util/configobj/docs/configobj.txt
 
1
==================================
 
2
 Reading and Writing Config Files
 
3
==================================
 
4
 
 
5
----------------------------------------
 
6
 ConfigObj 4 Introduction and Reference
 
7
----------------------------------------
 
8
 
 
9
:Authors: Michael Foord, Nicola Larosa
 
10
:Version: ConfigObj 4.2.0
 
11
:Date: 2006/02/16
 
12
:Homepage: `ConfigObj Homepage`_
 
13
:Sourceforge: Sourceforge_
 
14
:License: `BSD License`_
 
15
:Support: `Mailing List`_
 
16
 
 
17
.. _Mailing List: http://lists.sourceforge.net/lists/listinfo/configobj-develop
 
18
 
 
19
.. meta::
 
20
   :description: ConfigObj - a Python module for easy reading and writing of 
 
21
                 config files.
 
22
   :keywords: python, script, module, config, configuration, data, persistence,
 
23
              developer, configparser
 
24
 
 
25
.. contents:: ConfigObj Manual
 
26
.. sectnum::
 
27
 
 
28
Introduction
 
29
============
 
30
 
 
31
**ConfigObj** is a simple but powerful config file reader and writer: an *ini
 
32
file round tripper*. Its main feature is that it is very easy to use, with a
 
33
straightforward programmer's interface and a simple syntax for config files.
 
34
It has lots of other features though :
 
35
 
 
36
.. sidebar:: ConfigObj in Bazaar
 
37
 
 
38
    **ConfigObj** is now used as the config file parser for `Bazaar <http://bazaar-ng.org>`_.
 
39
    
 
40
    Bazaar is *the* Python  distributed {acro;VCS;Version Control System}. 
 
41
    ConfigObj is used to read ``bazaar.conf`` and ``branches.conf``.
 
42
    
 
43
    Other projects that use **ConfigObj** include :
 
44
    
 
45
    * `Planet Plus <http://planetplus.python-hosting.com/>`_
 
46
    
 
47
        A new web application version of `Planet <http://www.planetplanet.org/>`_, 
 
48
        the web aggregator.
 
49
        
 
50
    * `NeuroImaging in Python <http://projects.scipy.org/neuroimaging/ni/wiki>`_
 
51
    
 
52
        BrainSTAT is a project with the ultimate goal to produce a
 
53
        platform-independent python environment for the analysis of brain
 
54
        imaging data.
 
55
        
 
56
    * `Gruik <http://www.tracos.org/gruik/wiki>`_
 
57
    
 
58
        Gruik is a free software network packet sniffer.
 
59
 
 
60
* Nested sections (subsections), to any level
 
61
* List values
 
62
* Multiple line values
 
63
* String interpolation (substitution)
 
64
* Integrated with a powerful validation system
 
65
 
 
66
    - including automatic type checking/conversion
 
67
    - repeated sections
 
68
    - and allowing default values
 
69
 
 
70
* All comments in the file are preserved
 
71
* The order of keys/sections is preserved
 
72
* No external dependencies
 
73
* Full unicode support.
 
74
 
 
75
ConfigObj 4 is a complete rewrite of ConfigObj. ConfigObj now has a barrage [#]_
 
76
of doctests built into it, testing almost every feature. Run ``python configobj.py -v``
 
77
to see them in action. Despite the tests, ConfigObj 4 is smaller than version 3
 
78
and has no external dependencies.
 
79
 
 
80
For support and bug reports please use the ConfigObj `Mailing List`_.
 
81
 
 
82
.. hint::
 
83
 
 
84
    ConfigObj provides a convenient API for storing all sorts of data, not just
 
85
    config files. There is an article on using `ConfigObj for Data Persistence`_.
 
86
    
 
87
    The code from that article is available as ConfigPersist.py_.
 
88
 
 
89
.. _ConfigObj for Data Persistence: http://www.voidspace.org.uk/python/articles/configobj_for_data_persistence.shtml
 
90
.. _ConfigPersist.py: http://www.voidspace.org.uk/python/configpersist.html
 
91
 
 
92
 
 
93
Downloading
 
94
===========
 
95
 
 
96
The current version is **4.2.0**, dated 16th February 2006. ConfigObj 4 is
 
97
now stable. We still expect to pick up a few bugs along the way though [#]_.
 
98
{sm;:-)}
 
99
 
 
100
You can get ConfigObj in the following ways :
 
101
 
 
102
Files
 
103
-----
 
104
 
 
105
* configobj.py_ from Voidspace
 
106
 
 
107
    ConfigObj has no external dependencies. This file is sufficient to access
 
108
    all the functionality except Validation_.
 
109
 
 
110
* configobj.zip_ from Voidspace
 
111
 
 
112
    This also contains validate.py_ , the `API Docs`_ and `this document`_.
 
113
 
 
114
* The latest development version can be obtained from the `Subversion
 
115
  Repository`_.
 
116
 
 
117
* validate.py_ from Voidspace
 
118
 
 
119
* You can also download *configobj.zip* from Sourceforge_
 
120
 
 
121
Documentation
 
122
-------------
 
123
 
 
124
*configobj.zip* contains `this document`_ and full `API Docs`_, generated by
 
125
the EpyDoc_ program.
 
126
 
 
127
* You can view `this document`_ online as the `ConfigObj Homepage`_.
 
128
 
 
129
* You can also browse the `API Docs`_ online.
 
130
 
 
131
Pythonutils
 
132
-----------
 
133
 
 
134
ConfigObj is also part of the Pythonutils_ set of modules. This contains
 
135
various other useful modules, and is required by many of the `Voidspace Python
 
136
Projects`_.
 
137
 
 
138
.. _configobj.py: http://www.voidspace.org.uk/cgi-bin/voidspace/downman.py?file=configobj.py
 
139
.. _configobj.zip: http://www.voidspace.org.uk/cgi-bin/voidspace/downman.py?file=configobj-4.2.0.zip
 
140
.. _validate.py: http://www.voidspace.org.uk/cgi-bin/voidspace/downman.py?file=validate.py
 
141
.. _API Docs: http://www.voidspace.org.uk/python/configobj-api/
 
142
.. _this document:
 
143
.. _configobj homepage: http://www.voidspace.org.uk/python/configobj.html
 
144
.. _Subversion Repository: http://svn.rest2web.python-hosting.com/branches/configobj4
 
145
.. _Sourceforge: http://sourceforge.net/projects/configobj
 
146
.. _EpyDoc: http://epydoc.sourceforge.net
 
147
.. _pythonutils: http://www.voidspace.org.uk/python/pythonutils.html
 
148
.. _Voidspace Python Projects: http://www.voidspace.org.uk/python
 
149
 
 
150
 
 
151
Getting Started
 
152
===============
 
153
 
 
154
The outstanding feature of using ConfigObj is simplicity. Most functions can be
 
155
performed with single line commands.
 
156
 
 
157
Reading a Config File
 
158
---------------------
 
159
 
 
160
The normal way to read a config file, is to give ConfigObj the filename :
 
161
 
 
162
.. raw:: html
 
163
 
 
164
    {+coloring}
 
165
 
 
166
    from configobj import ConfigObj
 
167
    config = ConfigObj(filename)
 
168
 
 
169
    {-coloring}
 
170
 
 
171
You can also pass the config file in as a list of lines, or a ``StringIO``
 
172
instance, so it doesn't matter where your config data comes from.
 
173
 
 
174
You can then access members of your config file as a dictionary. Subsections
 
175
will also be dictionaries.
 
176
 
 
177
.. raw:: html
 
178
 
 
179
    {+coloring}
 
180
 
 
181
    from configobj import ConfigObj
 
182
    config = ConfigObj(filename)
 
183
    #
 
184
    value1 = config['keyword1']
 
185
    value2 = config['keyword2']
 
186
    #
 
187
    section1 = config['section1']
 
188
    value3 = section1['keyword3']
 
189
    value4 = section1['keyword4']
 
190
    #
 
191
    # you could also write
 
192
    value3 = config['section1']['keyword3']
 
193
    value4 = config['section1']['keyword4']
 
194
 
 
195
    {-coloring}
 
196
 
 
197
Writing a Config File
 
198
---------------------
 
199
 
 
200
Creating a new config file is just as easy as reading one. You can specify a
 
201
filename when you create the ConfigObj, or do it later [#]_.
 
202
 
 
203
If you *don't* set a filename, then the ``write`` method will return a list of
 
204
lines instead of writing to file. See the write_ method for more details.
 
205
 
 
206
Here we show creating an empty ConfigObj, setting a filename and some values,
 
207
and then writing to file :
 
208
 
 
209
.. raw:: html
 
210
 
 
211
    {+coloring}
 
212
 
 
213
    from configobj import ConfigObj
 
214
    config = ConfigObj()
 
215
    config.filename = filename
 
216
    #
 
217
    config['keyword1'] = value1
 
218
    config['keyword2'] = value2
 
219
    #
 
220
    config['section1'] = {}
 
221
    config['section1']['keyword3'] = value3
 
222
    config['section1']['keyword4'] = value4
 
223
    #
 
224
    section2 = {
 
225
        'keyword5': value5,
 
226
        'keyword6': value6,
 
227
        'sub-section': {
 
228
            'keyword7': value7
 
229
            }
 
230
    }
 
231
    config['section2'] = section2
 
232
    #
 
233
    config['section3'] = {}
 
234
    config['section3']['keyword 8'] = [value8, value9, value10]
 
235
    config['section3']['keyword 9'] = [value11, value12, value13]
 
236
    #
 
237
    config.write()
 
238
 
 
239
    {-coloring}
 
240
 
 
241
.. caution::
 
242
 
 
243
    Keywords and section names can only be strings [#]_. Attempting to set
 
244
    anything else will raise a ``ValueError``.
 
245
 
 
246
Config Files
 
247
------------
 
248
 
 
249
The config files that ConfigObj will read and write are based on the 'INI'
 
250
format. This means it will read and write files created for ``ConfigParser``
 
251
[#]_.
 
252
 
 
253
Keywords and values are separated by an ``'='``, and section markers are
 
254
between square brackets. Keywords, values, and section names can be surrounded
 
255
by single or double quotes. Indentation is not significant, but can be
 
256
preserved.
 
257
 
 
258
Subsections are indicated by repeating the square brackets in the section
 
259
marker. You nest levels by using more brackets.
 
260
 
 
261
You can have list values by separating items with a comma, and values spanning
 
262
multiple lines by using triple quotes (single or double).
 
263
 
 
264
For full details on all these see `the config file format`_. Here's an example
 
265
to illustrate : ::
 
266
 
 
267
    # This is the 'initial_comment'
 
268
    # Which may be several lines
 
269
    keyword1 = value1
 
270
    'keyword 2' = 'value 2'
 
271
 
 
272
    [ "section 1" ]
 
273
    # This comment goes with keyword 3
 
274
    keyword 3 = value 3
 
275
    'keyword 4' = value4, value 5, 'value 6'
 
276
 
 
277
        [[ sub-section ]]    # an inline comment
 
278
        # sub-section is inside "section 1"
 
279
        'keyword 5' = 'value 7'
 
280
        'keyword 6' = '''A multiline value,
 
281
    that spans more than one line :-)
 
282
    The line breaks are included in the value.'''
 
283
 
 
284
            [[[ sub-sub-section ]]]
 
285
            # sub-sub-section is *in* 'sub-section'
 
286
            # which is in 'section 1'
 
287
            'keyword 7' = 'value 8'
 
288
 
 
289
    [section 2]    # an inline comment
 
290
    keyword8 = "value 9"
 
291
    keyword9 = value10     # an inline comment
 
292
    # The 'final_comment'
 
293
    # Which also may be several lines
 
294
 
 
295
 
 
296
ConfigObj specifications
 
297
========================
 
298
 
 
299
.. raw:: html
 
300
 
 
301
    {+coloring}
 
302
 
 
303
    config = ConfigObj(infile=None, options=None, **keywargs)
 
304
 
 
305
    {-coloring}
 
306
 
 
307
infile
 
308
------
 
309
 
 
310
You don't need to specify an infile. If you omit it, an empty ConfigObj will be
 
311
created. ``infile`` *can* be :
 
312
 
 
313
* Nothing. In which case the ``filename`` attribute of your ConfigObj will be
 
314
  ``None``. You can set a filename at any time.
 
315
 
 
316
* A filename. What happens if the file doesn't already exist is determined by
 
317
  the options_ ``file_error`` and ``create_empty``. The filename will be
 
318
  preserved as the ``filename`` attribute. This can be changed at any time.
 
319
 
 
320
* A list of lines. Any trailing newlines will be removed from the lines. The
 
321
  ``filename`` attribute of your ConfigObj will be ``None``.
 
322
 
 
323
* A ``StringIO`` instance or file object, or any object with a ``read`` method.
 
324
  The ``filename`` attribute of your ConfigObj will be ``None`` [#]_.
 
325
 
 
326
* A dictionary. You can initialise a ConfigObj from a dictionary [#]_. The
 
327
  ``filename`` attribute of your ConfigObj will be ``None``. All keys must be
 
328
  strings. In this case, the order of values and sections is arbitrary.
 
329
 
 
330
options
 
331
-------
 
332
 
 
333
There are various options that control the way ConfigObj behaves. They can be
 
334
passed in as a dictionary of options, or as keyword arguments. Explicit keyword
 
335
arguments override the dictionary.
 
336
 
 
337
All of the options are available as attributes after the config file has been
 
338
parsed.
 
339
 
 
340
ConfigObj has the following options (with the default values shown) :
 
341
 
 
342
* 'raise_errors': ``False``
 
343
 
 
344
    When parsing, it is possible that the config file will be badly formed. The
 
345
    default is to parse the whole file and raise a single error at the end. You
 
346
    can set ``raise_errors = True`` to have errors raised immediately. See the
 
347
    exceptions_ section for more details.
 
348
 
 
349
    Altering this value after initial parsing has no effect.
 
350
 
 
351
* 'list_values': ``True``
 
352
 
 
353
    If ``True`` (the default) then list values are possible. If ``False``, the
 
354
    values are not parsed for lists.
 
355
        
 
356
        If ``list_values = False`` then single line values are not quoted or
 
357
        unqouted when reading and writing.
 
358
 
 
359
    Changing this value affects whether single line values will be quoted or 
 
360
    not when writing.
 
361
 
 
362
* 'create_empty': ``False``
 
363
 
 
364
    If this value is ``True`` and the file specified by ``infile`` doesn't
 
365
    exist, ConfigObj will create an empty file. This can be a useful test that
 
366
    the filename makes sense: an impossible filename will cause an error.
 
367
 
 
368
    Altering this value after initial parsing has no effect.
 
369
 
 
370
* 'file_error': ``False``
 
371
 
 
372
    If this value is ``True`` and the file specified by ``infile`` doesn't
 
373
    exist, ConfigObj will raise an ``IOError``.
 
374
 
 
375
    Altering this value after initial parsing has no effect.
 
376
 
 
377
* 'interpolation': ``True``
 
378
 
 
379
    Whether string interpolation is switched on or not. It is on (``True``) by
 
380
    default.
 
381
 
 
382
    You can set this attribute to change whether string interpolation is done
 
383
    when values are fetched. See the interpolation_ section for more details.
 
384
 
 
385
* 'configspec': ``None``
 
386
 
 
387
    If you want to use the validation system, you supply a configspec. This is
 
388
    effectively a type of config file that specifies a check for each member.
 
389
    This check can be used to do type conversion as well as check that the
 
390
    value is within your required parameters.
 
391
 
 
392
    You provide a configspec in the same way as you do the initial file: a
 
393
    filename, or list of lines, etc. See the validation_ section for full
 
394
    details on how to use the system.
 
395
 
 
396
    When parsed, every section has a ``configspec`` with a dictionary of
 
397
    configspec checks for *that section*.
 
398
 
 
399
* 'stringify': ``True``
 
400
 
 
401
    If you use the validation scheme, it can do type checking *and* conversion
 
402
    for you. This means you may want to set members to integers, or other
 
403
    non-string values.
 
404
 
 
405
    If 'stringify' is set to ``True`` (default) then non-string values will
 
406
    be converted to strings when you write the config file. The validation_
 
407
    process converts values from strings to the required type.
 
408
 
 
409
    If 'stringify' is set to ``False``, attempting to set a member to a
 
410
    non-string value [#]_ will raise a ``TypeError`` (no type conversion is
 
411
    done by validation).
 
412
 
 
413
* 'indent_type': ``' '``
 
414
 
 
415
    Indentation is not significant; it can however be present in the output
 
416
    config. Allowable values are: ``''`` (no indentation), ``' '`` (indentation
 
417
    with spaces, fixed at four per level), or ``'\t'`` (indentation with tabs,
 
418
    one tab per level).
 
419
 
 
420
    If this option is not specified, and the ConfigObj is initialised with a
 
421
    dictionary, the indentation used in the output is the default one, that is,
 
422
    spaces.
 
423
 
 
424
    If this option is not specified, and the ConfigObj is initialised with a
 
425
    list of lines or a file, the indentation used in the first indented line is
 
426
    selected and used in all output lines. If no input line is indented, no
 
427
    output line will be either.
 
428
 
 
429
    If this option *is* specified, the option value is used in the output
 
430
    config, overriding the type of indentation in the input config (if any).
 
431
 
 
432
* 'encoding': ``None``
 
433
 
 
434
    By default **ConfigObj** does not decode the file/strings you pass it into
 
435
    Unicode [#]_. If you want your config file as Unicode (keys and members)
 
436
    you need to provide an encoding to decode the file with. This encoding will
 
437
    also be used to encode the config file when writing.
 
438
    
 
439
    You can change the encoding attribute at any time.
 
440
    
 
441
    Any characters in your strings that can't be encoded with the specified
 
442
    encoding will raise a ``UnicodeEncodeError``.
 
443
    
 
444
    .. note::
 
445
    
 
446
        ``UTF16`` encoded files will automatically be detected and decoded,
 
447
        even if ``encoding`` is ``None``.
 
448
        
 
449
        This is because it is a 16-bit encoding, and ConfigObj will mangle it
 
450
        (split characters on byte boundaries) if it parses it without decoding.
 
451
 
 
452
* 'default_encoding': ``None``
 
453
 
 
454
    When using the ``write`` method, **ConfigObj** uses the ``encoding``
 
455
    attribute to encode the Unicode strings. If any members (or keys) have
 
456
    been set as byte strings instead of Unicode, these must first be decoded
 
457
    to Unicode before outputting in the specified encoding.
 
458
 
 
459
    ``default_encoding``, if specified, is the encoding used to decode byte
 
460
    strings in the **ConfigObj** before writing. If this is ``None``, then
 
461
    the Python default encoding (``sys.defaultencoding`` - usually ascii) is
 
462
    used.
 
463
    
 
464
    For most Western European users, a value of ``latin-1`` is sensible.
 
465
    
 
466
    ``default_encoding`` is *only* used if an ``encoding`` is specified.
 
467
    
 
468
    Any characters in byte-strings that can't be decoded using the
 
469
    ``default_encoding`` will raise a ``UnicodeDecodeError``.
 
470
 
 
471
 
 
472
Methods
 
473
-------
 
474
 
 
475
The ConfigObj is a subclass of an object called ``Section``, which is itself a
 
476
subclass of ``dict``, the builtin dictionary type. This means it also has
 
477
**all** the normal dictionary methods.
 
478
 
 
479
In addition, the following `Section Methods`_ may be useful :
 
480
 
 
481
* *encode*
 
482
* *decode*
 
483
* *walk*
 
484
* *merge*
 
485
* *dict* 
 
486
* *as_bool*
 
487
* *as_float*
 
488
* *as_int*
 
489
 
 
490
Read about Sections_ for details of all the methods.
 
491
 
 
492
.. hint::
 
493
 
 
494
    The *merge* method of sections is a recursive update.
 
495
    
 
496
    You can use this to merge sections, or even whole ConfigObjs, into each
 
497
    other.
 
498
    
 
499
    You would typically use this to create a default ConfigObj and then merge
 
500
    in user settings. This way users only need to specify values that are
 
501
    different from the default.
 
502
    
 
503
 
 
504
The public methods available on ConfigObj are :
 
505
 
 
506
* 'write'
 
507
* 'validate'
 
508
 
 
509
write
 
510
~~~~~
 
511
 
 
512
::
 
513
 
 
514
    write(file_object=None)
 
515
 
 
516
This method writes the current ConfigObj and takes a single, optional argument
 
517
[#]_.
 
518
 
 
519
If you pass in a file like object to the ``write`` method, the config file will
 
520
be written to this. (The only method of this object that is used is its
 
521
``write`` method, so a ``StringIO`` instance, or any other file like object
 
522
will work.)
 
523
 
 
524
Otherwise, the behaviour of this method depends on the ``filename`` attribute
 
525
of the ConfigObj.
 
526
 
 
527
``filename``
 
528
    ConfigObj will write the configuration to the file specified.
 
529
 
 
530
``None``
 
531
    ``write`` returns a list of lines. (Not ``'\n'`` terminated)
 
532
 
 
533
First the 'initial_comment' is written, then the config file, followed by the
 
534
'final_comment'. Comment lines and inline comments are written with each
 
535
key/value.
 
536
 
 
537
validate
 
538
~~~~~~~~
 
539
 
 
540
::
 
541
 
 
542
    validate(validator, preserve_errors=False)
 
543
 
 
544
.. raw:: html
 
545
 
 
546
    {+coloring}
 
547
 
 
548
    # filename is the config file
 
549
    # filename2 is the configspec
 
550
    # (which could also be hardcoded into your program)
 
551
    config = ConfigObj(filename, configspec=filename2)
 
552
    #
 
553
    from validate import Validator
 
554
    val = Validator()
 
555
    test = config.validate(val)
 
556
    if test == True:
 
557
        print 'Succeeded.'
 
558
 
 
559
    {-coloring}
 
560
 
 
561
The validate method uses the `validate 
 
562
<http://www.voidspace.org.uk/python/validate.html>`__ module to do the
 
563
validation.
 
564
    
 
565
This method validates the ConfigObj against the configspec. By doing type
 
566
conversion as well, it can abstract away the config file altogether and present
 
567
the config *data* to your application (in the types it expects it to be).
 
568
 
 
569
If the ``configspec`` attribute of the ConfigObj is ``None``, it raises a
 
570
``ValueError``.
 
571
 
 
572
If the stringify_ attribute is set, this process will convert values to the
 
573
type defined in the configspec.
 
574
 
 
575
The validate method uses checks specified in the configspec and defined in the
 
576
``Validator`` object. It is very easy to extend.
 
577
 
 
578
The configspec looks like the config file, but instead of the value, you
 
579
specify the check (and any default value). See the validation_ section for
 
580
details.
 
581
 
 
582
.. hint::
 
583
 
 
584
    If your ConfigObj is only comprised of basic data types, then you can use
 
585
    a function from the ConfigPersist.py_ module to auto-generate your
 
586
    configspec.
 
587
    
 
588
    See `ConfigObj for Data Persistence`_.
 
589
 
 
590
 
 
591
Return Value
 
592
############
 
593
 
 
594
By default, the validate method either returns ``True`` (everything passed) 
 
595
or a dictionary of ``True``/``False`` representing pass/fail. The dictionary 
 
596
follows the structure of the ConfigObj.
 
597
 
 
598
If a whole section passes then it is replaced with the value ``True``. If a 
 
599
whole section fails, then it is replaced with the value ``False``.
 
600
 
 
601
If a value is missing, and there is no default in the check, then the check 
 
602
automatically fails.
 
603
 
 
604
The ``validate`` method takes an optional keyword argument ``preserve_errors``.
 
605
If you set this to ``True``, instead of getting ``False`` for failed checks you
 
606
get the actual error object from the **validate** module. This usually contains
 
607
useful information about why the check failed.
 
608
 
 
609
See the `flatten_errors`_ function for how to turn your results dictionary into
 
610
a useful list of error messages.
 
611
 
 
612
Even if ``preserve_errors`` is ``True``, missing keys or sections will still be
 
613
represented by a ``False`` in the results dictionary.
 
614
 
 
615
 
 
616
Mentioning Default Values
 
617
#########################
 
618
 
 
619
In the check in your configspec, you can specify a default to be used - by 
 
620
using the ``default`` keyword. E.g. ::
 
621
 
 
622
    key1 = integer(0, 30, default=15)
 
623
    key2 = integer(default=15)
 
624
    key3 = boolean(default=True)
 
625
    key4 = option('Hello', 'Goodbye', 'Not Today', default='Not Today')
 
626
 
 
627
If the configspec check supplies a default and the value is missing in the
 
628
config, then the default will be set in your ConfigObj. (It is still passed to
 
629
the ``Validator`` so that type conversion can be done: this means the default
 
630
value must still pass the check.)
 
631
 
 
632
ConfigObj keeps a record of which values come from defaults, using the
 
633
``defaults`` attribute of sections_. Any key in this list isn't written out by
 
634
the ``write`` method. If a key is set from outside (even to the same value)
 
635
then it is removed from the ``defaults`` list.
 
636
 
 
637
.. note:
 
638
 
 
639
    Even if all the keys in a section are in the defaults list, the section
 
640
    marker is still written out.
 
641
 
 
642
There is additionally a special case default value of ``None``. If you set the
 
643
default value to ``None`` and the value is missing, the value will always be
 
644
set to ``None``. As the other checks don't return ``None`` (unless you
 
645
implement your own that do), you can tell that this value came from a default
 
646
value (and was missing from the config file). It allows an easy way of
 
647
implementing optional values. Simply check (and ignore) members that are set
 
648
to ``None``.
 
649
 
 
650
.. note::
 
651
 
 
652
    If stringify_ is ``False`` then ``default=None`` returns ``''`` instead of
 
653
    ``None``. This is because setting a value to a non-string raises an error
 
654
    if stringify is unset.
 
655
 
 
656
The default value can be a list. See `List Values`_ for the way to do this.
 
657
 
 
658
Writing invalid default values is a *guaranteed* way of confusing your users.
 
659
Default values **must** pass the check.
 
660
 
 
661
Mentioning Repeated Sections
 
662
############################
 
663
 
 
664
In the configspec it is possible to cause *every* sub-section in a section to
 
665
be validated using the same configspec. You do this with a section in the
 
666
configspec  called ``__many__``. Every sub-section in that section has the
 
667
``__many__`` configspec applied to it (without you having to explicitly name
 
668
them in advance).
 
669
 
 
670
If you define a ``__many__`` type section it must the only sub-section in that
 
671
section. Having a ``__many__`` *and* other sub-sections defined in the same
 
672
section will raise a ``RepeatSectionError``.
 
673
 
 
674
Your ``__many__`` section can have nested subsections, which can also include
 
675
``__many__`` type sections.
 
676
 
 
677
See `Repeated Sections`_ for examples.
 
678
 
 
679
 
 
680
Mentioning SimpleVal
 
681
####################
 
682
 
 
683
If you just want to check if all members are present, then you can use the
 
684
``SimpleVal`` object that comes with ConfigObj. It only fails members if they
 
685
are missing.
 
686
 
 
687
Write a configspec that has all the members you want to check for, but set
 
688
every section to ``''``.
 
689
 
 
690
.. raw:: html
 
691
 
 
692
    {+coloring}
 
693
 
 
694
    val = SimpleVal()
 
695
    test = config.validate(val)
 
696
    if test is True:
 
697
        print 'Succeeded.'
 
698
 
 
699
    {-coloring}
 
700
 
 
701
    
 
702
Attributes
 
703
----------
 
704
 
 
705
A ConfigObj has the following attributes :
 
706
 
 
707
* indent_type
 
708
* interpolate
 
709
* stringify
 
710
* BOM
 
711
* initial_comment
 
712
* final_comment
 
713
* list_values
 
714
* encoding
 
715
* default_encoding
 
716
 
 
717
.. note::
 
718
 
 
719
    This doesn't include *comments*, *inline_comments*, *defaults*, or
 
720
    *configspec*. These are actually attributes of Sections_.
 
721
 
 
722
It also has the following attributes as a result of parsing. They correspond to
 
723
options_ when the ConfigObj was created, but changing them has no effect.
 
724
 
 
725
* raise_errors
 
726
* create_empty
 
727
* file_error
 
728
 
 
729
interpolate
 
730
~~~~~~~~~~~
 
731
 
 
732
ConfigObj can perform string interpolation in a *similar* way to
 
733
``ConfigParser``. See the interpolation_ section for full details.
 
734
 
 
735
If ``interpolate`` is set to ``False``, then interpolation is *not* done when
 
736
you fetch values.
 
737
 
 
738
stringify
 
739
~~~~~~~~~
 
740
 
 
741
If this attribute is set (``True``) then the validate_ method changes the
 
742
values in the ConfigObj. These are turned back into strings when write_ is
 
743
called.
 
744
 
 
745
If stringify is unset (``False``) then attempting to set a value to a non
 
746
string (or a list of strings) will raise a ``TypeError``.
 
747
 
 
748
BOM
 
749
~~~
 
750
 
 
751
If the initial config file *started* with the UTF8 Unicode signature (known
 
752
slightly incorrectly as the {acro;BOM;Byte Order Mark}), or the UTF16 BOM, then
 
753
this attribute is set to ``True``. Otherwise it is ``False``.
 
754
 
 
755
If it is set to ``True`` when ``write`` is called then, if ``encoding`` is set
 
756
to ``None`` *or* to ``utf_8`` (and variants) a UTF BOM will be written.
 
757
 
 
758
For UTF16 encodings, a BOM is *always* written.
 
759
 
 
760
initial_comment
 
761
~~~~~~~~~~~~~~~
 
762
 
 
763
This is a list of lines. If the ConfigObj is created from an existing file, it
 
764
will contain any lines of comments before the start of the members.
 
765
 
 
766
If you create a new ConfigObj, this will be an empty list.
 
767
 
 
768
The write method puts these lines before it starts writing out the members.
 
769
 
 
770
final_comment
 
771
~~~~~~~~~~~~~
 
772
 
 
773
This is a list of lines. If the ConfigObj is created from an existing file, it
 
774
will contain any lines of comments after the last member.
 
775
 
 
776
If you create a new ConfigObj, this will be an empty list.
 
777
 
 
778
The ``write`` method puts these lines after it finishes writing out the
 
779
members.
 
780
 
 
781
list_values
 
782
~~~~~~~~~~~
 
783
 
 
784
This attribute is ``True`` or ``False``. If set to ``False`` then values are
 
785
not parsed for list values. In addition single line values are not unquoted.
 
786
 
 
787
This allows you to do your own parsing of values. It exists primarily to
 
788
support the reading of the configspec_ - but has other use cases.
 
789
 
 
790
For example you could use the ``LineParser`` from the
 
791
`listquote module <http://www.voidspace.org.uk/python/listquote.html#lineparser>`_ 
 
792
to read values for nested lists.
 
793
 
 
794
Single line values aren't quoted when writing - but multiline values are
 
795
handled as normal.
 
796
 
 
797
.. caution::
 
798
 
 
799
    Because values aren't quoted, leading or trailing whitespace can be
 
800
        lost.
 
801
 
 
802
    This behaviour was changed in version 4.0.1.
 
803
        
 
804
        Prior to this, single line values might have been quoted; even with
 
805
        ``list_values=False``. This means that files written by **ConfigObj**
 
806
        *could* now be incompatible - and need the quotes removing by hand.
 
807
 
 
808
encoding
 
809
~~~~~~~~
 
810
 
 
811
This is the encoding used to encode the output, when you call ``write``. It
 
812
must be a valid encoding `recognised by Python <http://docs.python.org/lib/standard-encodings.html>`_.
 
813
 
 
814
If this value is ``None`` then no encoding is done when ``write`` is called.
 
815
 
 
816
 
 
817
default_encoding
 
818
~~~~~~~~~~~~~~~~
 
819
 
 
820
If encoding is set, any byte-strings in your ConfigObj instance (keys or
 
821
members) will first be decoded to unicode using the encoding specified by the
 
822
``default_encoding`` attribute. This ensures that the output is in the encoding
 
823
specified.
 
824
 
 
825
If this value is ``None`` then ``sys.defaultencoding`` is used instead.
 
826
 
 
827
The Config File Format
 
828
======================
 
829
 
 
830
You saw an example config file in the `Config Files`_ section. Here is a fuller
 
831
specification of the config files used and created by ConfigObj.
 
832
 
 
833
The basic pattern for keywords is : ::
 
834
 
 
835
    # comment line
 
836
    # comment line
 
837
    keyword = value # inline comment
 
838
 
 
839
Both keyword and value can optionally be surrounded in quotes. The equals sign
 
840
is the only valid divider.
 
841
 
 
842
Values can have comments on the lines above them, and an inline comment after
 
843
them. This, of course, is optional. See the comments_ section for details.
 
844
 
 
845
If a keyword or value starts or ends with whitespace, or contains a quote mark
 
846
or comma, then it should be surrounded by quotes. Quotes are not necessary if
 
847
whitespace is surrounded by non-whitespace.
 
848
 
 
849
Values can also be lists. Lists are comma separated. You indicate a single
 
850
member list by a trailing comma. An empty list is shown by a single comma : ::
 
851
 
 
852
    keyword1 = value1, value2, value3
 
853
    keyword2 = value1, # a single member list
 
854
    keyword3 = , # an empty list
 
855
 
 
856
Values that contain line breaks (multi-line values) can be surrounded by triple
 
857
quotes. These can also be used if a value contains both types of quotes. List
 
858
members cannot be surrounded by triple quotes : ::
 
859
 
 
860
    keyword1 = ''' A multi line value
 
861
    on several
 
862
    lines'''     # with a comment
 
863
    keyword2 = '''I won't be "afraid".'''
 
864
    #
 
865
    keyword3 = """ A multi line value
 
866
    on several
 
867
    lines"""     # with a comment
 
868
    keyword4 = """I won't be "afraid"."""
 
869
 
 
870
.. warning::
 
871
 
 
872
    There is no way of safely quoting values that contain both types of triple
 
873
    quotes.
 
874
 
 
875
A line that starts with a '#', possibly preceded by whitespace, is a comment.
 
876
 
 
877
New sections are indicated by a section marker line. That is the section name
 
878
in square brackets. Whitespace around the section name is ignored. The name can
 
879
be quoted with single or double quotes. The marker can have comments before it
 
880
and an inline comment after it : ::
 
881
 
 
882
    # The First Section
 
883
    [ section name 1 ] # first section
 
884
    keyword1 = value1
 
885
 
 
886
    # The Second Section
 
887
    [ "section name 2" ] # second section
 
888
    keyword2 = value2
 
889
 
 
890
Any subsections (sections that are *inside* the current section) are
 
891
designated by repeating the square brackets before and after the section name.
 
892
The number of square brackets represents the nesting level of the sub-section.
 
893
Square brackets may be separated by whitespace; such whitespace, however, will
 
894
not be present in the output config written by the ``write`` method.
 
895
 
 
896
Indentation is not significant, but can be preserved. See the description of
 
897
the ``indent_type`` option, in the `ConfigObj specifications`_ chapter, for the
 
898
details.
 
899
 
 
900
A *NestingError* will be raised if the number of the opening and the closing
 
901
brackets in a section marker is not the same, or if a sub-section's nesting
 
902
level is greater than the nesting level of it parent plus one.
 
903
 
 
904
In the outer section, single values can only appear before any sub-section.
 
905
Otherwise they will belong to the sub-section immediately before them. ::
 
906
 
 
907
    # initial comment
 
908
    keyword1 = value1
 
909
    keyword2 = value2
 
910
 
 
911
    [section 1]
 
912
    keyword1 = value1
 
913
    keyword2 = value2
 
914
 
 
915
        [[sub-section]]
 
916
        # this is in section 1
 
917
        keyword1 = value1
 
918
        keyword2 = value2
 
919
 
 
920
            [[[nested section]]]
 
921
            # this is in sub section
 
922
            keyword1 = value1
 
923
            keyword2 = value2
 
924
 
 
925
        [[sub-section2]]
 
926
        # this is in section 1 again
 
927
        keyword1 = value1
 
928
        keyword2 = value2
 
929
 
 
930
    [[sub-section3]]
 
931
    # this is also in section 1, indentation is misleading here
 
932
    keyword1 = value1
 
933
    keyword2 = value2
 
934
 
 
935
    # final comment
 
936
 
 
937
When parsed, the above config file produces the following data structure :
 
938
 
 
939
.. raw:: html
 
940
 
 
941
    {+coloring}
 
942
 
 
943
    {
 
944
        'keyword1': 'value1',
 
945
        'keyword2': 'value2',
 
946
        'section 1': {
 
947
            'keyword1': 'value1',
 
948
            'keyword2': 'value2',
 
949
            'sub-section': {
 
950
                'keyword1': 'value1',
 
951
                'keyword2': 'value2',
 
952
                'nested section': {
 
953
                    'keyword1': 'value1',
 
954
                    'keyword2': 'value2',
 
955
                },
 
956
            },
 
957
            'sub-section2': {
 
958
                'keyword1': 'value1',
 
959
                'keyword2': 'value2',
 
960
            },
 
961
            'sub-section3': {
 
962
                'keyword1': 'value1',
 
963
                'keyword2': 'value2',
 
964
            },
 
965
        },
 
966
    }
 
967
 
 
968
    {-coloring}
 
969
 
 
970
Sections are ordered: note how the structure of the resulting ConfigObj is in
 
971
the same order as the original file.
 
972
 
 
973
Sections
 
974
========
 
975
 
 
976
Every section in a ConfigObj has certain properties. The ConfigObj itself also
 
977
has these properties, because it too is a section (sometimes called the *root
 
978
section*).
 
979
 
 
980
``Section`` is a subclass of the standard new-class dictionary, therefore it
 
981
has **all** the methods of a normal dictionary. This means you can ``update``
 
982
and ``clear`` sections.
 
983
 
 
984
.. note::
 
985
 
 
986
    You create a new section by assigning a member to be a dictionary.
 
987
    
 
988
    The new ``Section`` is created *from* the dictionary, but isn't the same
 
989
    thing as the dictionary. (So references to the dictionary you use to create
 
990
    the section *aren't* references to the new section).
 
991
    
 
992
    Note the following.
 
993
 
 
994
    .. raw:: html
 
995
    
 
996
        {+coloring}
 
997
        
 
998
        config = ConfigObj()
 
999
        vals = {'key1': 'value 1', 
 
1000
                'key2': 'value 2'
 
1001
               }
 
1002
        config['vals'] = vals
 
1003
        config['vals'] == vals
 
1004
        True
 
1005
        config['vals'] is vals
 
1006
        False
 
1007
        
 
1008
        {-coloring}
 
1009
     
 
1010
    If you now change ``vals``, the changes won't be reflected in ``config['vals']``.
 
1011
 
 
1012
A section is ordered, following its ``scalars`` and ``sections``
 
1013
attributes documented below. This means that the following dictionary
 
1014
attributes return their results in order.
 
1015
 
 
1016
* '__iter__'
 
1017
 
 
1018
    More commonly known as ``for member in section:``.
 
1019
 
 
1020
* '__repr__' and '__str__'
 
1021
 
 
1022
    Any time you print or display the ConfigObj.
 
1023
 
 
1024
* 'items'
 
1025
 
 
1026
* 'iteritems'
 
1027
 
 
1028
* 'iterkeys'
 
1029
 
 
1030
* 'itervalues'
 
1031
 
 
1032
* 'keys'
 
1033
 
 
1034
* 'popitem'
 
1035
 
 
1036
* 'values'
 
1037
 
 
1038
Section Attributes
 
1039
------------------
 
1040
 
 
1041
* main
 
1042
 
 
1043
    A reference to the main ConfigObj.
 
1044
 
 
1045
* parent
 
1046
 
 
1047
    A reference to the 'parent' section, the section that this section is a
 
1048
    member of.
 
1049
 
 
1050
    On the ConfigObj this attribute is a reference to itself. You can use this
 
1051
    to walk up the sections, stopping when ``section.parent is section``.
 
1052
 
 
1053
* depth
 
1054
 
 
1055
    The nesting level of the current section.
 
1056
 
 
1057
    If you create a new ConfigObj and add sections, 1 will be added to the
 
1058
    depth level between sections.
 
1059
 
 
1060
* defaults
 
1061
 
 
1062
    This attribute is a list of scalars that came from default values. Values
 
1063
    that came from defaults aren't written out by the ``write`` method.
 
1064
    Setting any of these values in the section removes them from the defaults
 
1065
    list.
 
1066
 
 
1067
* scalars, sections
 
1068
 
 
1069
    These attributes are normal lists, representing the order that members,
 
1070
    single values and subsections appear in the section. The order will either
 
1071
    be the order of the original config file, *or* the order that you added
 
1072
    members.
 
1073
 
 
1074
    The order of members in this lists is the order that ``write`` creates in
 
1075
    the config file. The ``scalars`` list is output before the ``sections``
 
1076
    list.
 
1077
 
 
1078
    Adding or removing members also alters these lists. You can manipulate the
 
1079
    lists directly to alter the order of members.
 
1080
 
 
1081
    .. warning::
 
1082
 
 
1083
        If you alter the ``scalars``, ``sections``, or ``defaults`` attributes
 
1084
        so that they no longer reflect the contents of the section, you will
 
1085
        break your ConfigObj.
 
1086
 
 
1087
    See also the ``rename`` method.
 
1088
 
 
1089
* comments
 
1090
 
 
1091
    This is a dictionary of comments associated with each member. Each entry is
 
1092
    a list of lines. These lines are written out before the member.
 
1093
 
 
1094
* inline_comments
 
1095
 
 
1096
    This is *another* dictionary of comments associated with each member. Each
 
1097
    entry is a string that is put inline with the member.
 
1098
 
 
1099
* configspec
 
1100
 
 
1101
    The configspec attribute is a dictionary mapping scalars to *checks*. A
 
1102
    check defines the expected type and possibly the allowed values for a
 
1103
    member.
 
1104
 
 
1105
    The configspec has the same format as a config file, but instead of values
 
1106
    it has a specification for the value (which may include a default value).
 
1107
    The validate_ method uses it to check the config file makes sense. If a
 
1108
    configspec is passed in when the ConfigObj is created, then it is parsed
 
1109
    and broken up to become the ``configspec`` attribute of each section.
 
1110
 
 
1111
    If you didn't pass in a configspec, this attribute will be ``None`` on the
 
1112
    root section (the main ConfigObj).
 
1113
 
 
1114
    You can set the configspec attribute directly on a section.
 
1115
 
 
1116
    See the validation_ section for full details of how to write configspecs.
 
1117
 
 
1118
Section Methods
 
1119
---------------
 
1120
 
 
1121
* **dict**
 
1122
 
 
1123
    This method takes no arguments. It returns a deep copy of the section as a
 
1124
    dictionary. All subsections will also be dictionaries, and list values will
 
1125
    be copies, rather than references to the original [#]_.
 
1126
 
 
1127
* **rename**
 
1128
 
 
1129
    ``rename(oldkey, newkey)``
 
1130
 
 
1131
    This method renames a key, without affecting its position in the sequence.
 
1132
 
 
1133
    It is mainly implemented for the ``encode`` and ``decode`` methods, which
 
1134
    provide some Unicode support.
 
1135
 
 
1136
* **merge**
 
1137
 
 
1138
    ``merge(indict)``
 
1139
    
 
1140
    This method is a *recursive update* method. It allows you to merge two
 
1141
    config files together.
 
1142
    
 
1143
    You would typically use this to create a default ConfigObj and then merge
 
1144
    in user settings. This way users only need to specify values that are
 
1145
    different from the default.
 
1146
    
 
1147
    For example :
 
1148
    
 
1149
    .. raw:: html
 
1150
    
 
1151
        {+coloring}
 
1152
        
 
1153
        # def_cfg contains your default config settings
 
1154
        # user_cfg contains the user settings
 
1155
        cfg = ConfigObj(def_cfg)
 
1156
        usr = ConfigObj(user_cfg)
 
1157
        #
 
1158
        cfg.merge(usr)
 
1159
        
 
1160
        """
 
1161
        cfg now contains a combination of the default settings and the user
 
1162
        settings.
 
1163
        
 
1164
        The user settings will have overwritten any of the default ones.
 
1165
        """
 
1166
    
 
1167
        {-coloring}
 
1168
    
 
1169
* **walk**
 
1170
 
 
1171
    This method can be used to transform values and names. See `walking a
 
1172
    section`_ for examples and explanation.
 
1173
 
 
1174
* **decode**
 
1175
 
 
1176
    ``decode(encoding)``
 
1177
 
 
1178
    This method decodes names and values into Unicode objects, using the
 
1179
    supplied encoding.
 
1180
 
 
1181
* **encode**
 
1182
 
 
1183
    ``encode(encoding)``
 
1184
 
 
1185
    This method is the opposite of ``decode`` {sm;:!:}.
 
1186
 
 
1187
    It encodes names and values using the supplied encoding. If any of your
 
1188
    names/values are strings rather than Unicode, Python will have to do an
 
1189
    implicit decode first. (This method uses ``sys.defaultencoding`` for
 
1190
    implicit decodes.)
 
1191
 
 
1192
* **as_bool**
 
1193
 
 
1194
    ``as_bool(key)``
 
1195
    
 
1196
    Returns ``True`` if the key contains a string that represents ``True``, or
 
1197
    is the ``True`` object.
 
1198
    
 
1199
    Returns ``False`` if the key contains a string that represents ``False``, 
 
1200
    or is the ``False`` object. 
 
1201
 
 
1202
    Raises a ``ValueError`` if the key contains anything else.
 
1203
    
 
1204
    Strings that represent ``True`` are (not case sensitive) : ::
 
1205
    
 
1206
        true, yes, on, 1
 
1207
        
 
1208
    Strings that represent ``False`` are : ::
 
1209
    
 
1210
        false, no, off, 0
 
1211
    
 
1212
    .. note::
 
1213
    
 
1214
        In ConfigObj 4.1.0, this method was called ``istrue``. That method is
 
1215
        now deprecated and will issue a warning when used. It will go away
 
1216
        in the next release.
 
1217
        
 
1218
* **as_int**
 
1219
 
 
1220
    ``as_int(key)``
 
1221
    
 
1222
    This returns the value contained in the specified key as an integer.
 
1223
    
 
1224
    It raises a ``ValueError`` if the conversion can't be done.
 
1225
 
 
1226
* **as_float**
 
1227
 
 
1228
    ``as_float(key)``
 
1229
    
 
1230
    This returns the value contained in the specified key as a float.
 
1231
    
 
1232
    It raises a ``ValueError`` if the conversion can't be done.
 
1233
    
 
1234
Walking a Section
 
1235
-----------------
 
1236
 
 
1237
.. note::
 
1238
 
 
1239
    The walk method allows you to call a function on every member/name.
 
1240
 
 
1241
.. raw:: html
 
1242
 
 
1243
    {+coloring}
 
1244
 
 
1245
        walk(function, raise_errors=True,
 
1246
            call_on_sections=False, **keywargs):
 
1247
 
 
1248
    {-coloring}
 
1249
 
 
1250
``walk`` is a method of the ``Section`` object. This means it is also a method
 
1251
of ConfigObj.
 
1252
 
 
1253
It walks through every member and calls a function on the keyword and value. It
 
1254
walks recursively through subsections.
 
1255
 
 
1256
It returns a dictionary of all the computed values.
 
1257
 
 
1258
If the function raises an exception, the default is to propagate the error, and
 
1259
stop. If ``raise_errors=False`` then it sets the return value for that keyword
 
1260
to ``False`` instead, and continues. This is similar to the way validation_
 
1261
works.
 
1262
 
 
1263
Your function receives the arguments ``(section, key)``. The current value is
 
1264
then ``section[key]`` [#]_. Any unrecognised keyword arguments you pass to
 
1265
walk, are passed on to the function.
 
1266
 
 
1267
Normally ``walk`` just recurses into subsections. If you are transforming (or
 
1268
checking) names as well as values, then you want to be able to change the names
 
1269
of sections. In this case set ``call_on_sections`` to ``True``. Now, on
 
1270
encountering a sub-section, *first* the function is called for the *whole*
 
1271
sub-section, and *then* it recurses into it's members. This means your function
 
1272
must be able to handle receiving dictionaries as well as strings and lists.
 
1273
 
 
1274
If you are using the return value from ``walk`` *and* ``call_on_sections``,
 
1275
note that walk discards the return value when it calls your function.
 
1276
 
 
1277
.. caution::
 
1278
 
 
1279
    You can use ``walk`` to transform the names of members of a section
 
1280
    but you mustn't add or delete members.
 
1281
 
 
1282
 
 
1283
Examples
 
1284
--------
 
1285
 
 
1286
Examples that use the walk method are the ``encode`` and ``decode`` methods.
 
1287
They both define a function and pass it to walk. Because these functions
 
1288
transform names as well as values (from byte strings to Unicode) they set
 
1289
``call_on_sections=True``.
 
1290
 
 
1291
To see how they do it, *read the source Luke* {sm;:cool:}.
 
1292
 
 
1293
You can use this for transforming all values in your ConfigObj. For example
 
1294
you might like the nested lists from ConfigObj 3. This was provided by the
 
1295
listquote_ module. You could switch off the parsing for list values
 
1296
(``list_values=False``) and use listquote to parse every value.
 
1297
 
 
1298
Another thing you might want to do is use the Python escape codes in your
 
1299
values. You might be *used* to using ``\n`` for line feed and ``\t`` for tab.
 
1300
Obviously we'd need to decode strings that come from the config file (using the
 
1301
escape codes). Before writing out we'll need to put the escape codes back in
 
1302
encode.
 
1303
 
 
1304
As an example we'll write a function to use with walk, that encodes or decodes
 
1305
values using the ``string-escape`` codec.
 
1306
 
 
1307
The function has to take each value and set the new value. As a bonus we'll
 
1308
create one function that will do decode *or* encode depending on a keyword
 
1309
argument.
 
1310
 
 
1311
We don't want to work with section names, we're only transforming values, so
 
1312
we can leave ``call_on_sections`` as ``False``. This means the two datatypes we
 
1313
have to handle are strings and lists, we can ignore everything else. (We'll
 
1314
treat tuples as lists as well).
 
1315
 
 
1316
We're not using the return values, so it doesn't need to return anything, just
 
1317
change the values if appropriate.
 
1318
 
 
1319
.. raw:: html
 
1320
 
 
1321
    {+coloring}
 
1322
 
 
1323
    def string_escape(section, key, encode=False):
 
1324
        """
 
1325
        A function to encode or decode using the 'string-escape' codec.
 
1326
        To be passed to the walk method of a ConfigObj.
 
1327
        By default it decodes.
 
1328
        To encode, pass in the keyword argument ``encode=True``.
 
1329
        """
 
1330
        val = section[key]
 
1331
        # is it a type we can work with
 
1332
        # NOTE: for platforms where Python > 2.2
 
1333
        # you can use basestring instead of (str, unicode)
 
1334
        if not isinstance(val, (str, unicode, list, tuple)):
 
1335
            # no !
 
1336
            return
 
1337
        elif isinstance(val, (str, unicode)):
 
1338
            # it's a string !
 
1339
            if not encode:
 
1340
                section[key] = val.decode('string-escape')
 
1341
            else:
 
1342
                section[key] = val.encode('string-escape')
 
1343
        else:
 
1344
            # it must be a list or tuple!
 
1345
            # we'll be lazy and create a new list
 
1346
            newval = []
 
1347
            # we'll check every member of the list
 
1348
            for entry in val:
 
1349
                if isinstance(entry, (str, unicode)):
 
1350
                    if not encode:
 
1351
                        newval.append(entry.decode('string-escape'))
 
1352
                    else:
 
1353
                       newval.append(entry.encode('string-escape'))
 
1354
                else:
 
1355
                    newval.append(entry)
 
1356
            # done !
 
1357
            section[key] =  newval
 
1358
 
 
1359
    # assume we have a ConfigObj called ``config``
 
1360
    #
 
1361
    # To decode
 
1362
    config.walk(string_escape)
 
1363
    #
 
1364
    # To encode.
 
1365
    # Because ``walk`` doesn't recognise the ``encode`` argument
 
1366
    # it passes it to our function.
 
1367
    config.walk(string_escape, encode=True)
 
1368
 
 
1369
    {-coloring}
 
1370
 
 
1371
Here's a simple example of using ``walk`` to transform names and values. One
 
1372
usecase of this would be to create a *standard* config file with placeholders
 
1373
for section and keynames. You can then use walk to create new config files
 
1374
and change values and member names :
 
1375
 
 
1376
.. raw:: html
 
1377
 
 
1378
    {+coloring}
 
1379
 
 
1380
    # We use 'XXXX' as a placeholder
 
1381
    config = '''
 
1382
    XXXXkey1 = XXXXvalue1
 
1383
    XXXXkey2 = XXXXvalue2
 
1384
    XXXXkey3 = XXXXvalue3
 
1385
    [XXXXsection1]
 
1386
    XXXXkey1 = XXXXvalue1
 
1387
    XXXXkey2 = XXXXvalue2
 
1388
    XXXXkey3 = XXXXvalue3
 
1389
    [XXXXsection2]
 
1390
    XXXXkey1 = XXXXvalue1
 
1391
    XXXXkey2 = XXXXvalue2
 
1392
    XXXXkey3 = XXXXvalue3
 
1393
        [[XXXXsection1]]
 
1394
        XXXXkey1 = XXXXvalue1
 
1395
        XXXXkey2 = XXXXvalue2
 
1396
        XXXXkey3 = XXXXvalue3
 
1397
    '''.splitlines()
 
1398
    cfg = ConfigObj(config)
 
1399
    #
 
1400
    def transform(section, key):
 
1401
        val = section[key]
 
1402
        newkey = key.replace('XXXX', 'CLIENT1')
 
1403
        section.rename(key, newkey)
 
1404
        if isinstance(val, (tuple, list, dict)):
 
1405
            pass
 
1406
        else:
 
1407
            val = val.replace('XXXX', 'CLIENT1')
 
1408
            section[newkey] = val
 
1409
    #
 
1410
    cfg.walk(transform, call_on_sections=True)
 
1411
    print cfg
 
1412
    {'CLIENT1key1': 'CLIENT1value1', 'CLIENT1key2': 'CLIENT1value2', 
 
1413
    'CLIENT1key3': 'CLIENT1value3', 
 
1414
    'CLIENT1section1': {'CLIENT1key1': 'CLIENT1value1', 
 
1415
        'CLIENT1key2': 'CLIENT1value2', 'CLIENT1key3': 'CLIENT1value3'}, 
 
1416
    'CLIENT1section2': {'CLIENT1key1': 'CLIENT1value1', 
 
1417
        'CLIENT1key2': 'CLIENT1value2', 'CLIENT1key3': 'CLIENT1value3', 
 
1418
        'CLIENT1section1': {'CLIENT1key1': 'CLIENT1value1', 
 
1419
            'CLIENT1key2': 'CLIENT1value2', 'CLIENT1key3': 'CLIENT1value3'}}}
 
1420
            
 
1421
    {-coloring}
 
1422
 
 
1423
 
 
1424
Exceptions
 
1425
==========
 
1426
 
 
1427
There are several places where ConfigObj may raise exceptions (other than
 
1428
because of bugs).
 
1429
 
 
1430
1) If a configspec filename you pass in doesn't exist, or a config file
 
1431
    filename doesn't exist *and* ``file_error=True``, an ``IOError`` will be
 
1432
    raised.
 
1433
 
 
1434
2) If you try to set a non-string key, or a non string value when
 
1435
    ``stringify=False``, a ``TypeError`` will be raised.
 
1436
 
 
1437
3) A badly built config file will cause parsing errors.
 
1438
 
 
1439
4) A parsing error can also occur when reading a configspec.
 
1440
 
 
1441
5) In string interpolation you can specify a value that doesn't exist, or
 
1442
    create circular references (recursion).
 
1443
 
 
1444
6) If you have a ``__many__`` repeated section with other section definitions
 
1445
    (in a configspec), a ``RepeatSectionError`` will be raised.
 
1446
 
 
1447
Number 5 (which is actually two different types of exceptions) is documented
 
1448
    in interpolation_.
 
1449
 
 
1450
Number 6 is explained in the validation_ section.
 
1451
 
 
1452
*This* section is about errors raised during parsing.
 
1453
 
 
1454
The base error class is ``ConfigObjError``. This is a subclass of
 
1455
``SyntaxError``, so you can trap for ``SyntaxError`` without needing to
 
1456
directly import any of the ConfigObj exceptions.
 
1457
 
 
1458
The following other exceptions are defined (all deriving from
 
1459
``ConfigObjError``) :
 
1460
 
 
1461
* ``NestingError``
 
1462
 
 
1463
    This error indicates either a mismatch in the brackets in a section marker,
 
1464
    or an excessive level of nesting.
 
1465
 
 
1466
* ``ParseError``
 
1467
 
 
1468
    This error indicates that a line is badly written. It is neither a valid
 
1469
    ``key = value`` line, nor a valid section marker line, nor a comment line.
 
1470
 
 
1471
* ``DuplicateError``
 
1472
 
 
1473
    The keyword or section specified already exists.
 
1474
 
 
1475
* ``ConfigspecError``
 
1476
 
 
1477
    An error occured whilst parsing a configspec.
 
1478
 
 
1479
When parsing a configspec, ConfigObj will stop on the first error it
 
1480
encounters.  It will raise a ``ConfigspecError``. This will have an ``error``
 
1481
attribute, which is the actual error that was raised.
 
1482
 
 
1483
Behavior when parsing a config file depends on the option ``raise_errors``.
 
1484
If ConfigObj encounters an error while parsing a config file:
 
1485
 
 
1486
    If ``raise_errors=True`` then ConfigObj will raise the appropriate error
 
1487
    and parsing will stop.
 
1488
 
 
1489
    If ``raise_errors=False`` (the default) then parsing will continue to the
 
1490
    end and *all* errors will be collected.
 
1491
 
 
1492
In the second case a ``ConfigObjError`` is raised after parsing has stopped.
 
1493
The error raised has a ``config`` attribute, which is the parts of the
 
1494
ConfigObj that parsed successfully. It also has an attribute ``errors``, which
 
1495
is a list of *all* the errors raised. Each entry in the list is an instance of
 
1496
the appropriate error type. Each one has the following attributes (useful for
 
1497
delivering a sensible error message to your user) :
 
1498
 
 
1499
* ``line``: the original line that caused the error.
 
1500
 
 
1501
* ``line_number``: its number in the config file.
 
1502
 
 
1503
* ``message``: the error message that accompanied the error.
 
1504
 
 
1505
.. note::
 
1506
 
 
1507
    One wrongly written line could break the basic structure of your config
 
1508
    file. This could cause every line after it to flag an error, so having a
 
1509
    list of all the lines that caused errors may not be as useful as it sounds.
 
1510
    {sm;:-(}.
 
1511
 
 
1512
 
 
1513
Validation
 
1514
==========
 
1515
 
 
1516
Validation is done through a combination of the configspec_ and a ``Validator``
 
1517
object. For this you need *validate.py* [#]_. See downloading_ if you don't
 
1518
have a copy.
 
1519
 
 
1520
Validation can perform two different operations :
 
1521
 
 
1522
1) Check that a value meets a specification. For example, check that a value
 
1523
    is an integer between one and six, or is a choice from a specific set of
 
1524
    options.
 
1525
 
 
1526
2) It can convert the value into the type required. For example, if one of
 
1527
    your values is a port number, validation will turn it into an integer for
 
1528
    you.
 
1529
 
 
1530
So validation can act as a transparent layer between the datatypes of your
 
1531
application configuration (boolean, integers, floats, etc) and the text format
 
1532
of your config file.
 
1533
 
 
1534
configspec
 
1535
----------
 
1536
 
 
1537
The ``validate`` method checks members against an entry in the configspec. Your
 
1538
configspec therefore resembles your config file, with a check for every member.
 
1539
 
 
1540
In order to perform validation you need a ``Validator`` object. This has
 
1541
several useful built-in check functions. You can also create your own custom
 
1542
functions and register them with your Validator object.
 
1543
 
 
1544
Each check is the name of one of these functions, including any parameters and
 
1545
keyword arguments. The configspecs look like function calls, and they map to
 
1546
function calls.
 
1547
 
 
1548
The basic datatypes that an un-extended Validator can test for are :
 
1549
 
 
1550
* boolean values (True and False)
 
1551
* integers (including minimum and maximum values)
 
1552
* floats (including min and max)
 
1553
* strings (including min and max length)
 
1554
* IP addresses (v4 only)
 
1555
 
 
1556
It can also handle lists of these types and restrict a value to being one from
 
1557
a set of options.
 
1558
 
 
1559
An example configspec is going to look something like : ::
 
1560
 
 
1561
    port = integer(0, 100)
 
1562
    user = string(max=25)
 
1563
    mode = option('quiet', 'loud', 'silent')
 
1564
 
 
1565
You can specify default values, and also have the same configspec applied to
 
1566
several sections. This is called `repeated sections`_.
 
1567
 
 
1568
For full details on writing configspecs, please refer to the `validate.py
 
1569
documentation`_.
 
1570
 
 
1571
.. important::
 
1572
 
 
1573
    Your configspec is read by ConfigObj in the same way as a config file.
 
1574
    
 
1575
    That means you can do interpolation *within* your configspec.
 
1576
    
 
1577
    In order to allow this, checks in the 'DEFAULT' section (of the root level
 
1578
    of your configspec) are *not* used.
 
1579
 
 
1580
.. _validate.py documentation: http://www.voidspace.org.uk/python/validate.html
 
1581
 
 
1582
Type Conversion
 
1583
---------------
 
1584
 
 
1585
By default, validation does type conversion. This means that if you specify
 
1586
``integer`` as the check, then calling validate_ will actually change the value
 
1587
to an integer (so long as the check succeeds).
 
1588
 
 
1589
It also means that when you call the write_ method, the value will be converted
 
1590
back into a string using the ``str`` function.
 
1591
 
 
1592
To switch this off, and leave values as strings after validation, you need to
 
1593
set the stringify_ attribute to ``False``. If this is the case, attempting to
 
1594
set a value to a non-string will raise an error.
 
1595
 
 
1596
Default Values
 
1597
--------------
 
1598
 
 
1599
You can set a default value in your check. If the value is missing from the
 
1600
config file then this value will be used instead. This means that your user
 
1601
only has to supply values that differ from the defaults.
 
1602
 
 
1603
If you *don't* supply a default then for a value to be missing is an error,
 
1604
and this will show in the `return value`_ from validate.
 
1605
 
 
1606
Additionally you can set the default to be ``None``. This means the value will
 
1607
be set to ``None`` (the object) *whichever check is used*. (It will be set to
 
1608
``''`` rather than ``None`` if stringify_ is ``False``). You can use this
 
1609
to easily implement optional values in your config files. ::
 
1610
 
 
1611
    port = integer(0, 100, default=80)
 
1612
    user = string(max=25, default=0)
 
1613
    mode = option('quiet', 'loud', 'silent', default='loud')
 
1614
    nick = string(default=None)
 
1615
 
 
1616
.. note::
 
1617
 
 
1618
    Because the default goes through type conversion, it also has to pass the
 
1619
    check.
 
1620
 
 
1621
    Note that ``default=None`` is case sensitive.
 
1622
 
 
1623
 
 
1624
List Values
 
1625
~~~~~~~~~~~
 
1626
 
 
1627
It's possible that you will want to specify a list as a default value. To avoid
 
1628
confusing syntax with commas and quotes you use a list constructor to specify 
 
1629
that keyword arguments are lists. This includes the ``default`` value. This 
 
1630
makes checks look something like : ::
 
1631
 
 
1632
    checkname(default=list('val1', 'val2', 'val3'))
 
1633
 
 
1634
This works with all keyword arguments, but is most useful for default values.
 
1635
 
 
1636
 
 
1637
Repeated Sections
 
1638
-----------------
 
1639
 
 
1640
Repeated sections are a way of specifying a configspec for a section that
 
1641
should be applied to *all* subsections in the same section.
 
1642
 
 
1643
The easiest way of explaining this is to give an example. Suppose you have a
 
1644
config file that describes a dog. That dog has various attributes, but it can
 
1645
also have many fleas. You don't know in advance how many fleas there will be,
 
1646
or what they will be called, but you want each flea validated against the same
 
1647
configspec.
 
1648
 
 
1649
We can define a section called *fleas*. We want every flea in that section
 
1650
(every sub-section) to have the same configspec applied to it. We do this by
 
1651
defining a single section called ``__many__``. ::
 
1652
 
 
1653
    [dog]
 
1654
    name = string(default=Rover)
 
1655
    age = float(0, 99, default=0)
 
1656
 
 
1657
        [[fleas]]
 
1658
 
 
1659
            [[[__many__]]]
 
1660
            bloodsucker = boolean(default=True)
 
1661
            children = integer(default=10000)
 
1662
            size = option(small, tiny, micro, default=tiny)
 
1663
 
 
1664
Every flea on our dog will now be validated using the ``__many__`` configspec.
 
1665
 
 
1666
If you define another sub-section in a section *as well as* a ``__many__`` then
 
1667
you will get an error.
 
1668
 
 
1669
``__many__`` sections can have sub-sections, including their own ``__many__``
 
1670
sub-sections. Defaults work in the normal way in repeated sections.
 
1671
 
 
1672
 
 
1673
Validation and Interpolation
 
1674
----------------------------
 
1675
 
 
1676
String interpolation and validation don't play well together. When validation
 
1677
changes type it sets the value. If the value uses interpolation, then the 
 
1678
interpolation reference would normally be overwritten. Calling ``write`` would
 
1679
then use the absolute value and the interpolation reference would be lost.
 
1680
 
 
1681
As a compromise - if the value is unchanged by validation then it is not reset.
 
1682
This means strings that pass through validation unmodified will not be 
 
1683
overwritten. If validation changes type - the value has to be overwritten, and
 
1684
any interpolation references are lost {sm;:-(}.
 
1685
 
 
1686
SimpleVal
 
1687
---------
 
1688
 
 
1689
You may not need a full validation process, but still want to check if all the
 
1690
expected values are present.
 
1691
 
 
1692
Provided as part of the ConfigObj module is the ``SimpleVal`` object. This has
 
1693
a dummy ``test`` method that always passes.
 
1694
 
 
1695
The only reason a test will fail is if the value is missing. The return value
 
1696
from ``validate`` will either be ``True``, meaning all present, or a dictionary
 
1697
with ``False`` for all missing values/sections.
 
1698
 
 
1699
To use it, you still need to pass in a valid configspec when you create the
 
1700
ConfigObj, but just set all the values to ``''``. Then create an instance of
 
1701
``SimpleVal`` and pass it to the ``validate`` method.
 
1702
 
 
1703
As a trivial example if you had the following config file : ::
 
1704
 
 
1705
    # config file for an application
 
1706
    port = 80
 
1707
    protocol = http
 
1708
    domain = voidspace
 
1709
    top_level_domain = org.uk
 
1710
 
 
1711
You would write the following configspec : ::
 
1712
 
 
1713
    port = ''
 
1714
    protocol = ''
 
1715
    domain = ''
 
1716
    top_level_domain = ''
 
1717
 
 
1718
.. raw:: html
 
1719
 
 
1720
    {+coloring}
 
1721
 
 
1722
    config = Configobj(filename, configspec=configspec)
 
1723
    val = SimpleVal()
 
1724
    test = config.validate(val)
 
1725
    if test == True:
 
1726
        print 'All values present.'
 
1727
    elif test == False:
 
1728
        print 'No values present!'
 
1729
    else:
 
1730
        for entry in test:
 
1731
            if test[entry] == False:
 
1732
                print '"%s" missing.' % entry
 
1733
 
 
1734
    {-coloring}
 
1735
 
 
1736
 
 
1737
Interpolation
 
1738
=============
 
1739
 
 
1740
ConfigObj allows string interpolation *similar* to the way ``ConfigParser``
 
1741
 
 
1742
You specify a value to be substituted by including ``%(name)s`` in the value.
 
1743
 
 
1744
Interpolation checks first the 'DEFAULT' sub-section of the current section to
 
1745
see if ``name`` is the key to a value. ('name' is case sensitive).
 
1746
 
 
1747
If it doesn't find it, next it checks the 'DEFAULT' section of the parent
 
1748
section, last it checks the 'DEFAULT' section of the main section.
 
1749
 
 
1750
If the value specified isn't found then a ``MissingInterpolationOption`` error
 
1751
is raised (a subclass of ``ConfigObjError``).
 
1752
 
 
1753
If it is found then the returned value is also checked for substitutions. This
 
1754
allows you to make up compound values (for example directory paths) that use
 
1755
more than one default value. It also means it's possible to create circular
 
1756
references. If after ten replacements there are still values to substitute, an
 
1757
``InterpolationDepthError`` is raised.
 
1758
 
 
1759
Both of these errors are subclasses of ``InterpolationError``, which is a
 
1760
subclass of ``ConfigObjError``.
 
1761
 
 
1762
String interpolation and validation don't play well together. This is because 
 
1763
validation overwrites values - and so may erase the interpolation references.
 
1764
See `Validation and Interpolation`_. (This can only happen if validation
 
1765
has to *change* the value).
 
1766
 
 
1767
 
 
1768
Comments
 
1769
========
 
1770
 
 
1771
Any line that starts with a '#', possibly preceded by whitespace, is a comment.
 
1772
 
 
1773
If a config file starts with comments then these are preserved as the
 
1774
initial_comment_.
 
1775
 
 
1776
If a config file ends with comments then these are preserved as the
 
1777
final_comment_.
 
1778
 
 
1779
Every key or section marker may have lines of comments immediately above it.
 
1780
These are saved as the ``comments`` attribute of the section. Each member is a
 
1781
list of lines.
 
1782
 
 
1783
You can also have a comment inline with a value. These are saved as the
 
1784
``inline_comments`` attribute of the section, with one entry per member of the
 
1785
section.
 
1786
 
 
1787
Subsections (section markers in the config file) can also have comments.
 
1788
 
 
1789
See `Section Attributes`_ for more on these attributes.
 
1790
 
 
1791
These comments are all written back out by the ``write`` method.
 
1792
 
 
1793
 
 
1794
flatten_errors
 
1795
==============
 
1796
 
 
1797
::
 
1798
 
 
1799
    flatten_errors(cfg, res)
 
1800
 
 
1801
Validation_ is a powerful way of checking that the values supplied by the user
 
1802
make sense.
 
1803
 
 
1804
The validate_ method returns a results dictionary that represents pass or fail
 
1805
for each value. This doesn't give you any information about *why* the check
 
1806
failed.
 
1807
 
 
1808
``flatten_errors`` is an example function that turns a results dictionary into
 
1809
a flat list, that only contains vaues that *failed*.
 
1810
 
 
1811
``cfg`` is the ConfigObj instance being checked, ``res`` is the results
 
1812
dictionary returned by ``validate``.
 
1813
 
 
1814
It returns a list of keys that failed. Each member of the list is a tuple : ::
 
1815
 
 
1816
    ([list of sections...], key, result)
 
1817
 
 
1818
If ``validate`` was called with ``preserve_errors=False`` (the default)
 
1819
then ``result`` will always be ``False``.
 
1820
 
 
1821
*list of sections* is a flattened list of sections that the key was found
 
1822
in.
 
1823
 
 
1824
If the section was missing then key will be ``None``.
 
1825
 
 
1826
If the value (or section) was missing then ``result`` will be ``False``.
 
1827
 
 
1828
If ``validate`` was called with ``preserve_errors=True`` and a value
 
1829
was present, but failed the check, then ``result`` will be the exception
 
1830
object returned. You can use this as a string that describes the failure.
 
1831
 
 
1832
For example :
 
1833
 
 
1834
    *The value "3" is of the wrong type*.
 
1835
 
 
1836
 
 
1837
Example Usage
 
1838
-------------
 
1839
 
 
1840
The output from ``flatten_errors`` is a list of tuples.
 
1841
 
 
1842
Here is an example of how you could present this information to the user.
 
1843
 
 
1844
.. raw:: html
 
1845
 
 
1846
    {+coloring}
 
1847
    
 
1848
    vtor = validate.Validator()
 
1849
    # ini is your config file - cs is the configspec
 
1850
    cfg = ConfigObj(ini, configspec=cs)
 
1851
    res = cfg.validate(vtor, preserve_errors=True)
 
1852
    for entry in flatten_errors(cfg, res):
 
1853
        # each entry is a tuple
 
1854
        section_list, key, error = entry
 
1855
        if key is not None:
 
1856
           section_list.append(key)
 
1857
        else:
 
1858
            section_list.append('[missing section]')
 
1859
        section_string = ', '.join(section_list)
 
1860
        if error == False:
 
1861
            error = 'Missing value or section.'
 
1862
        print section_string, ' = ', error
 
1863
 
 
1864
    {-coloring}
 
1865
 
 
1866
Backwards Compatibility
 
1867
=======================
 
1868
 
 
1869
There have been a lot of changes since ConfigObj 3. The core parser is now
 
1870
based on regular expressions, and is a lot faster and smaller. There is now no
 
1871
difference in the way we treat flat files and non-flatfiles, that is, no empty
 
1872
sections. This means some of the code can be a lot simpler, less code does
 
1873
more of the work [#]_.
 
1874
 
 
1875
There have been other simplifications: for example we only have eight options
 
1876
instead of seventeen.
 
1877
 
 
1878
Most config files created for ConfigObj 3 will be read with no changes and many
 
1879
programs will work without having to alter code. Some of the changes do break
 
1880
backwards compatibility: for example, code that uses the previous options will
 
1881
now raise an error. It should be very easy to fix these, though.
 
1882
 
 
1883
Below is a list of all the changes that affect backwards compatibility. This
 
1884
doesn't include details of method signatures that have changed, because almost
 
1885
all of them have.
 
1886
 
 
1887
Incompatible Changes
 
1888
--------------------
 
1889
 
 
1890
(I have removed a lot of needless complications: this list is probably not
 
1891
conclusive, many option/attribute/method names have changed.)
 
1892
 
 
1893
Case sensitive.
 
1894
 
 
1895
The only valid divider is '='.
 
1896
 
 
1897
Line continuations with ``\`` removed.
 
1898
 
 
1899
No recursive lists in values.
 
1900
 
 
1901
No empty sections.
 
1902
 
 
1903
No distinction between flatfiles and non flatfiles.
 
1904
 
 
1905
Change in list syntax: use commas to indicate list, not parentheses (square
 
1906
brackets and parentheses are no longer recognised as lists).
 
1907
 
 
1908
';' is no longer valid for comments, and no multiline comments.
 
1909
 
 
1910
No attribute-style access to values.
 
1911
 
 
1912
Empty values not allowed: use '' or "".
 
1913
 
 
1914
In ConfigObj 3, setting a non-flatfile member to ``None`` would initialise it
 
1915
as an empty section.
 
1916
 
 
1917
The escape entities '&mjf-lf;' and '&mjf-quot;' have gone, replaced by triple
 
1918
quote, multiple line values.
 
1919
 
 
1920
The ``newline``, ``force_return``, and ``default`` options have gone.
 
1921
 
 
1922
``fileerror`` and ``createempty`` options have become ``file_error`` and
 
1923
``create_empty``.
 
1924
 
 
1925
Partial configspecs (for specifying the order members should be written out,
 
1926
and which should be present) have gone. The configspec is no longer used to
 
1927
specify order for the ``write`` method.
 
1928
 
 
1929
Exceeding the maximum depth of recursion in string interpolation now raises an
 
1930
error ``InterpolationDepthError``.
 
1931
 
 
1932
Specifying a value for interpolation which doesn't exist now raises a
 
1933
``MissingInterpolationOption`` error (instead of merely being ignored).
 
1934
 
 
1935
The ``writein`` method has been removed.
 
1936
 
 
1937
The comments attribute is now a list (``inline_comments`` equates to the old
 
1938
comments attribute).
 
1939
 
 
1940
ConfigObj 3
 
1941
-----------
 
1942
 
 
1943
ConfigObj 3 is now deprecated in favour of ConfigObj 4. I can fix bugs in
 
1944
ConfigObj 3 if needed, though.
 
1945
 
 
1946
For anyone who still needs it, you can download it here: `ConfigObj 3.3.1`_
 
1947
 
 
1948
You can read the old docs at : `ConfigObj 3 Docs`_
 
1949
 
 
1950
.. _ConfigObj 3.3.1: http://www.voidspace.org.uk/cgi-bin/voidspace/downman.py?file=configobj3.zip
 
1951
.. _ConfigObj 3 Docs: http://www.voidspace.org.uk/python/configobj3.html
 
1952
 
 
1953
 
 
1954
CREDITS
 
1955
=======
 
1956
 
 
1957
ConfigObj 4 is written by (and copyright) `Michael Foord`_ and 
 
1958
`Nicola Larosa`_.
 
1959
 
 
1960
Particularly thanks to Nicola Larosa for help on the config file spec, the
 
1961
validation system and the doctests.
 
1962
 
 
1963
*validate.py* was originally written by Michael Foord and `Mark Andrews`_.
 
1964
 
 
1965
Thanks to others for input and bugfixes.
 
1966
 
 
1967
 
 
1968
LICENSE
 
1969
=======
 
1970
 
 
1971
ConfigObj, and related files, are licensed under the BSD license. This is a
 
1972
very unrestrictive license, but it comes with the usual disclaimer. This is
 
1973
free software: test it, break it, just don't blame us if it eats your data !
 
1974
Of course if it does, let us know and we'll fix the problem so it doesn't
 
1975
happen to anyone else {sm;:-)}. ::
 
1976
 
 
1977
    Copyright (c) 2004 - 2006, Michael Foord & Nicola Larosa
 
1978
    All rights reserved.
 
1979
 
 
1980
    Redistribution and use in source and binary forms, with or without
 
1981
    modification, are permitted provided that the following conditions are
 
1982
    met:
 
1983
 
 
1984
 
 
1985
        * Redistributions of source code must retain the above copyright
 
1986
          notice, this list of conditions and the following disclaimer.
 
1987
 
 
1988
        * Redistributions in binary form must reproduce the above
 
1989
          copyright notice, this list of conditions and the following
 
1990
          disclaimer in the documentation and/or other materials provided
 
1991
          with the distribution.
 
1992
 
 
1993
        * Neither the name of Michael Foord nor Nicola Larosa
 
1994
          may be used to endorse or promote products derived from this
 
1995
          software without specific prior written permission.
 
1996
 
 
1997
    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 
1998
    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 
1999
    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 
2000
    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 
2001
    OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 
2002
    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 
2003
    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 
2004
    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 
2005
    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 
2006
    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 
2007
    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
2008
 
 
2009
You should also be able to find a copy of this license at : `BSD License`_
 
2010
 
 
2011
.. _BSD License: http://www.voidspace.org.uk/python/license.shtml
 
2012
 
 
2013
 
 
2014
TODO
 
2015
====
 
2016
 
 
2017
Fix any bugs (and resolvable issues).
 
2018
 
 
2019
Do an example for the 'walk' which removes uniform indentation in multiline
 
2020
values.
 
2021
 
 
2022
When initialising a section from a ConfigObj *or* an ``OrderedDictionary``
 
2023
we could preserve ordering.
 
2024
 
 
2025
Add an *odict* method which returns an ``OrderedDictionary``.
 
2026
 
 
2027
 
 
2028
ISSUES
 
2029
======
 
2030
 
 
2031
.. note::
 
2032
 
 
2033
    Please file any bug reports to `Michael Foord`_ or the **ConfigObj**
 
2034
    `Mailing List`_.
 
2035
 
 
2036
You can't have a keyword with the same name as a section (in the same section).
 
2037
They are both dictionary keys, so they would overlap.
 
2038
 
 
2039
Interpolation checks first the 'DEFAULT' sub-section of the current section,
 
2040
next it checks the 'DEFAULT' section of the parent section, last it checks the
 
2041
'DEFAULT' section of the main section.
 
2042
 
 
2043
Logically a 'DEFAULT' section should apply to all subsections of the *same
 
2044
parent*: this means that checking the 'DEFAULT' sub-section in the *current
 
2045
section* is not necessarily logical ?
 
2046
 
 
2047
Does it matter that we don't support the ':' divider, which is supported by
 
2048
``ConfigParser`` ?
 
2049
 
 
2050
String interpolation and validation don't play well together. See 
 
2051
`Validation and Interpolation`_.
 
2052
 
 
2053
Validation is no longer done on the 'DEFAULT' section (on the root level). This
 
2054
allows interpolation from within your configspec - but also prevents you
 
2055
validating the 'DEFAULT' section.
 
2056
 
 
2057
 
 
2058
CHANGELOG
 
2059
=========
 
2060
 
 
2061
This is an abbreviated changelog showing the major releases up to version 4.
 
2062
From version 4 it lists all releases and changes. *More* data on individual
 
2063
changes may be found in the source code.
 
2064
 
 
2065
2006/02/16 - Version 4.2.0
 
2066
--------------------------
 
2067
 
 
2068
Removed ``BOM_UTF8`` from ``__all__``.
 
2069
 
 
2070
The ``BOM`` attribute has become a boolean. (Defaults to ``False``.) It is
 
2071
*only* ``True`` for the ``UTF16`` encoding.
 
2072
 
 
2073
File like objects no longer need a ``seek`` attribute.
 
2074
 
 
2075
Full unicode support added. New options/attributes ``encoding``,
 
2076
``default_encoding``.
 
2077
 
 
2078
ConfigObj no longer keeps a reference to file like objects. Instead the
 
2079
``write`` method takes a file like object as an optional argument. (Which
 
2080
will be used in preference of the ``filename`` attribute if that exists as
 
2081
well.)
 
2082
 
 
2083
utf16 files decoded to unicode.
 
2084
 
 
2085
If ``BOM`` is ``True``, but no encoding specified, then the utf8 BOM is
 
2086
written out at the start of the file. (It will normally only be ``True`` if
 
2087
the utf8 BOM was found when the file was read.)
 
2088
 
 
2089
File paths are *not* converted to absolute paths, relative paths will
 
2090
remain relative as the ``filename`` attribute.
 
2091
 
 
2092
Fixed bug where ``final_comment`` wasn't returned if ``write`` is returning
 
2093
a list of lines.
 
2094
 
 
2095
Deprecated ``istrue``, replaced it with ``as_bool``.
 
2096
 
 
2097
Added ``as_int`` and ``as_float``.
 
2098
 
 
2099
2005/12/14 - Version 4.1.0
 
2100
--------------------------
 
2101
 
 
2102
Added ``merge``, a recursive update.
 
2103
 
 
2104
Added ``preserve_errors`` to ``validate`` and the ``flatten_errors``
 
2105
example function.
 
2106
 
 
2107
Thanks to Matthew Brett for suggestions and helping me iron out bugs.
 
2108
    
 
2109
Fixed bug where a config file is *all* comment, the comment will now be
 
2110
``initial_comment`` rather than ``final_comment``.
 
2111
 
 
2112
Validation no longer done on the 'DEFAULT' section (only in the root level).
 
2113
This allows interpolation in configspecs.
 
2114
 
 
2115
Also use the new list syntax in validate_ 0.2.1. (For configspecs).
 
2116
 
 
2117
2005/12/02 - Version 4.0.2
 
2118
--------------------------
 
2119
 
 
2120
Fixed bug in ``create_empty``. Thanks to Paul Jimenez for the report.
 
2121
 
 
2122
 
 
2123
2005/11/05 - Version 4.0.1
 
2124
--------------------------
 
2125
 
 
2126
Fixed bug in ``Section.walk`` when transforming names as well as values.
 
2127
 
 
2128
Added the ``istrue`` method. (Fetches the boolean equivalent of a string
 
2129
value).
 
2130
 
 
2131
Fixed ``list_values=False`` - they are now only quoted/unquoted if they
 
2132
are multiline values.
 
2133
 
 
2134
List values are written as ``item, item`` rather than ``item,item``.
 
2135
 
 
2136
 
 
2137
2005/10/17 - Version 4.0.0
 
2138
--------------------------
 
2139
 
 
2140
**ConfigObj 4.0.0 Final**
 
2141
 
 
2142
Fixed bug in ``setdefault``. When creating a new section with setdefault the
 
2143
reference returned would be to the dictionary passed in *not* to the new 
 
2144
section. Bug fixed and behaviour documented.
 
2145
 
 
2146
Obscure typo/bug fixed in ``write``. Wouldn't have affected anyone though.
 
2147
 
 
2148
2005/09/09 - Version 4.0.0 beta 5
 
2149
---------------------------------
 
2150
 
 
2151
Removed ``PositionError``.
 
2152
 
 
2153
Allowed quotes around keys as documented.
 
2154
 
 
2155
Fixed bug with commas in comments. (matched as a list value)
 
2156
 
 
2157
2005/09/07 - Version 4.0.0 beta 4
 
2158
---------------------------------
 
2159
 
 
2160
Fixed bug in ``__delitem__``. Deleting an item no longer deletes the 
 
2161
``inline_comments`` attribute.
 
2162
 
 
2163
Fixed bug in initialising ConfigObj from a ConfigObj.
 
2164
 
 
2165
Changed the mailing list address.
 
2166
 
 
2167
2005/08/28 - Version 4.0.0 beta 3
 
2168
---------------------------------
 
2169
 
 
2170
Interpolation is switched off before writing out files.
 
2171
 
 
2172
Fixed bug in handling ``StringIO`` instances. (Thanks to report from
 
2173
"Gustavo Niemeyer" <gustavo@niemeyer.net>)
 
2174
 
 
2175
Moved the doctests from the ``__init__`` method to a separate function.
 
2176
(For the sake of IDE calltips).
 
2177
 
 
2178
2005/08/25 - Version 4.0.0 beta 2
 
2179
---------------------------------
 
2180
 
 
2181
Amendments to *validate.py*.
 
2182
 
 
2183
Official release.
 
2184
 
 
2185
2005/08/21 - Version 4.0.0 beta 1
 
2186
---------------------------------
 
2187
 
 
2188
Reads nested subsections to any depth.
 
2189
 
 
2190
Multiline values.
 
2191
 
 
2192
Simplified options and methods.
 
2193
 
 
2194
New list syntax.
 
2195
 
 
2196
Faster, smaller, and better parser.
 
2197
 
 
2198
Validation greatly improved. Includes:
 
2199
 
 
2200
    * type conversion
 
2201
    * default values
 
2202
    * repeated sections
 
2203
 
 
2204
Improved error handling.
 
2205
 
 
2206
Plus lots of other improvements {sm;:grin:}.
 
2207
 
 
2208
2004/05/24 - Version 3.0.0
 
2209
--------------------------
 
2210
 
 
2211
Several incompatible changes: another major overhaul and change. (Lots of
 
2212
improvements though).
 
2213
 
 
2214
Added support for standard config files with sections. This has an entirely
 
2215
new interface: each section is a dictionary of values.
 
2216
 
 
2217
Changed the update method to be called writein: update clashes with a dict
 
2218
method.
 
2219
 
 
2220
Made various attributes keyword arguments, added several.
 
2221
 
 
2222
Configspecs and orderlists have changed a great deal.
 
2223
 
 
2224
Removed support for adding dictionaries: use update instead.
 
2225
 
 
2226
Now subclasses a new class called caselessDict. This should add various
 
2227
dictionary methods that could have caused errors before.
 
2228
 
 
2229
It also preserves the original casing of keywords when writing them back out.
 
2230
 
 
2231
Comments are also saved using a ``caselessDict``.
 
2232
 
 
2233
Using a non-string key will now raise a ``TypeError`` rather than converting 
 
2234
the key.
 
2235
 
 
2236
Added an exceptions keyword for *much* better handling of errors.
 
2237
 
 
2238
Made ``creatempty=False`` the default.
 
2239
 
 
2240
Now checks indict *and* any keyword args. Keyword args take precedence over
 
2241
indict.
 
2242
 
 
2243
``' ', ':', '=', ','`` and ``'\t'`` are now all valid dividers where the 
 
2244
keyword is unquoted.
 
2245
 
 
2246
ConfigObj now does no type checking against configspec when you set items.
 
2247
 
 
2248
delete and add methods removed (they were unnecessary).
 
2249
 
 
2250
Docs rewritten to include all this gumph and more; actually ConfigObj is
 
2251
*really* easy to use.
 
2252
 
 
2253
Support for stdout was removed.
 
2254
 
 
2255
A few new methods added.
 
2256
 
 
2257
Charmap is now incorporated into ConfigObj.
 
2258
 
 
2259
2004/03/14 - Version 2.0.0 beta
 
2260
-------------------------------
 
2261
 
 
2262
Re-written it to subclass dict. My first forays into inheritance and operator
 
2263
overloading.
 
2264
 
 
2265
The config object now behaves like a dictionary.
 
2266
 
 
2267
I've completely broken the interface, but I don't think anyone was really
 
2268
 using it anyway.
 
2269
 
 
2270
This new version is much more 'classy' {sm;:wink:}
 
2271
 
 
2272
It will also read straight from/to a filename and completely parse a config
 
2273
file without you *having* to supply a config spec.
 
2274
 
 
2275
Uses listparse, so can handle nested list items as values.
 
2276
 
 
2277
No longer has getval and setval methods: use normal dictionary methods, or add
 
2278
and delete.
 
2279
 
 
2280
2004/01/29 - Version 1.0.5
 
2281
--------------------------
 
2282
 
 
2283
Version 1.0.5 has a couple of bugfixes as well as a couple of useful additions
 
2284
over previous versions.
 
2285
 
 
2286
Since 1.0.0 the buildconfig function has been moved into this distribution,
 
2287
and the methods reset, verify, getval and setval have been added.
 
2288
 
 
2289
A couple of bugs have been fixed.
 
2290
 
 
2291
Origins
 
2292
-------
 
2293
 
 
2294
ConfigObj originated in a set of functions for reading config files in the
 
2295
atlantibots_ project. The original functions were written by Rob McNeur...
 
2296
 
 
2297
.. _atlantibots: http://www.voidspace.org.uk/atlantibots
 
2298
 
 
2299
----------
 
2300
 
 
2301
Footnotes
 
2302
=========
 
2303
 
 
2304
.. [#] 253 of them, at the time of writing.
 
2305
 
 
2306
.. [#] And if you discover any bugs, let us know. We'll fix them quickly.
 
2307
 
 
2308
.. [#] If you specify a filename that doesn't exist, ConfigObj will assume you
 
2309
    are creating a new one. See the *create_empty* and *file_error* options_.
 
2310
 
 
2311
.. [#] They can be byte strings ('ordinary' strings) or Unicode.
 
2312
 
 
2313
.. [#] This is a change in ConfigObj 4.2.0. Note that ConfigObj doesn't call
 
2314
    the seek method of any file like object you pass in. You may want to call
 
2315
    ``file_object.seek(0)`` yourself, first.
 
2316
 
 
2317
.. [#] Except we don't support the RFC822 style line continuations, nor ':' as
 
2318
    a divider.
 
2319
 
 
2320
.. [#] For a file object that will depend what mode it was opened with. You
 
2321
    can read *and* write to a ``StringIO`` instance, but not always to a
 
2322
    ``cStringIO`` instance.
 
2323
 
 
2324
.. [#] A side effect of this is that it enables you to copy a ConfigObj :
 
2325
 
 
2326
    .. raw:: html
 
2327
    
 
2328
        {+coloring}
 
2329
    
 
2330
        # only copies members
 
2331
        # not attributes/comments
 
2332
        config2 = ConfigObj(config1)
 
2333
    
 
2334
        {-coloring}
 
2335
 
 
2336
    The order of values and sections will not be preserved, though.
 
2337
 
 
2338
.. [#] The exception is if it detects a ``UTF16`` encoded file which it
 
2339
    must decode before parsing.
 
2340
     
 
2341
.. [#] Other than lists of strings.
 
2342
 
 
2343
.. [#] The method signature in the API docs will show that this method takes
 
2344
    two arguments. The second is the section to be written. This is because the
 
2345
    ``write`` method is called recursively.
 
2346
 
 
2347
.. [#] The dict method doesn't actually use the deepcopy mechanism. This means
 
2348
    if you add nested lists (etc) to your ConfigObj, then the dictionary
 
2349
    returned by dict may contain some references. For all *normal* ConfigObjs
 
2350
    it will return a deepcopy.
 
2351
 
 
2352
.. [#] Passing ``(section, key)`` rather than ``(value, key)`` allows you to
 
2353
    change the value by setting ``section[key] = newval``. It also gives you
 
2354
    access to the *rename* method of the section.
 
2355
 
 
2356
.. [#] Minimum required version of *validate.py* 0.2.0 .
 
2357
 
 
2358
.. [#] There's nothing to stop you decoding the whole config file to Unicode
 
2359
    *first*.
 
2360
 
 
2361
.. [#] It also makes ConfigObj a lot simpler to *use*.
 
2362
 
 
2363
.. note::
 
2364
 
 
2365
    Rendering this document with docutils also needs the
 
2366
    textmacros module and the PySrc CSS stuff. See
 
2367
    http://www.voidspace.org.uk/python/firedrop2/textmacros.shtml
 
2368
 
 
2369
.. raw:: html
 
2370
 
 
2371
    <div align="center">
 
2372
        <a href="http://sourceforge.net/donate/index.php?group_id=123265">
 
2373
            <img src="http://images.sourceforge.net/images/project-support.jpg" width="88" height="32" border="0" alt="Support This Project" /> 
 
2374
        </a>
 
2375
        <a href="http://sourceforge.net">
 
2376
            <img src="http://sourceforge.net/sflogo.php?group_id=123265&amp;type=1" width="88" height="31" border="0" alt="SourceForge.net Logo" />
 
2377
        </a>
 
2378
        <br />
 
2379
        <a href="http://www.python.org">
 
2380
            <img src="images/powered_by_python.jpg" width="602" height="186" border="0" />
 
2381
        </a><br /><br />
 
2382
        <a href="http://www.opensource.org">
 
2383
            <img src="images/osi-certified-120x100.gif" width="120" height="100" border="0" />
 
2384
            <br /><strong>Certified Open Source</strong>
 
2385
        </a>
 
2386
        <br /><br />
 
2387
        <script type="text/javascript" language="JavaScript">var site="s16atlantibots"</script>
 
2388
        <script type="text/javascript" language="JavaScript1.2" src="http://s16.sitemeter.com/js/counter.js?site=s16atlantibots"></script>
 
2389
        <noscript>
 
2390
            <a href="http://s16.sitemeter.com/stats.asp?site=s16atlantibots">
 
2391
                <img src="http://s16.sitemeter.com/meter.asp?site=s16atlantibots" alt="Site Meter" border=0 />
 
2392
            </a>
 
2393
        </noscript>
 
2394
    </div>
 
2395
 
 
2396
.. _listquote: http://www.voidspace.org.uk/python/modules.shtml#listquote
 
2397
.. _Michael Foord: http://www.voidspace.org.uk/index2.shtml
 
2398
.. _Nicola Larosa: http://www.teknico.net
 
2399
.. _Mark Andrews: http://www.la-la.com