« back to all changes in this revision
Viewing changes to bzrlib/util/configobj/docs/configobj.txt
- browse files at revision 1185.12.49
- compare with another revision
- compare with revision 6216
- download diff
- download tarball
- view history from revision 1185.12.49
- Committer: Aaron Bentley
- Date: 2005-10-18 18:48:27 UTC
- mto: (1185.25.1)
- mto: This revision was merged to the branch mainline in revision 1474.
- Revision ID: abentley@panoramicfeedback.com-20051018184827-2cc69376beb1cdf3
Switched to ConfigObj
- files added:
- bzrlib/util/configobj
- bzrlib/util/configobj/docs
- files modified:
- bzrlib/config.py
added
removed
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&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
Loggerhead is a web-based interface for Breezy
Version: 2.0.1