← 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

  • Committer: Martin Pool
  • Date: 2005-08-18 05:44:39 UTC
  • Revision ID: mbp@sourcefrog.net-20050818054439-ba0873b87a8c1671
- add code to run weave utility under profiler

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-vcs.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