← 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: Erik Bågfors
  • Date: 2006-02-03 19:50:59 UTC
  • mto: (1185.50.77 bzr-jam-integration)
  • mto: This revision was merged to the branch mainline in revision 1554.
  • Revision ID: erik@bagfors.nu-20060203195059-1cf8ff5aa68de0ea
Support for plugins to register log formatters and set default formatter
Also, change one command line option for "log"

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