← 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-04-26 05:51:17 UTC
  • Revision ID: mbp@sourcefrog.net-20050426055116-e4bede04e549e4f6
- update doc upload scripts

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