33
33
straightforward programmer's interface and a simple syntax for config files.
34
34
It has lots of other features though :
36
.. sidebar:: ConfigObj in Bazaar
38
**ConfigObj** is now used as the config file parser for `Bazaar <http://bazaar-vcs.org>`_.
40
Bazaar is *the* Python distributed {acro;VCS;Version Control System}.
41
ConfigObj is used to read ``bazaar.conf`` and ``branches.conf``.
43
Other projects that use **ConfigObj** include :
45
* `Planet Plus <http://planetplus.python-hosting.com/>`_
47
A new web application version of `Planet <http://www.planetplanet.org/>`_,
50
* `NeuroImaging in Python <http://projects.scipy.org/neuroimaging/ni/wiki>`_
52
BrainSTAT is a project with the ultimate goal to produce a
53
platform-independent python environment for the analysis of brain
56
* `Gruik <http://www.tracos.org/gruik/wiki>`_
58
Gruik is a free software network packet sniffer.
36
60
* Nested sections (subsections), to any level
38
62
* Multiple line values
39
63
* String interpolation (substitution)
40
64
* Integrated with a powerful validation system
42
* including automatic type checking/conversion
44
* and allowing default values
66
- including automatic type checking/conversion
68
- and allowing default values
46
70
* All comments in the file are preserved
47
71
* The order of keys/sections is preserved
48
72
* No external dependencies
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`_.
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.
73
* Full unicode support.
75
ConfigObj 4 is a complete rewrite of ConfigObj. ConfigObj now has a barrage [#]_
76
of doctests built into it, testing almost every feature. Run ``python configobj.py -v``
77
to see them in action. Despite the tests, ConfigObj 4 is smaller than version 3
78
and has no external dependencies.
58
80
For support and bug reports please use the ConfigObj `Mailing List`_.
62
There is an article on using `ConfigObj for Data Persistence`_.
84
ConfigObj provides a convenient API for storing all sorts of data, not just
85
config files. There is an article on using `ConfigObj for Data Persistence`_.
64
87
The code from that article is available as ConfigPersist.py_.
66
89
.. _ConfigObj for Data Persistence: http://www.voidspace.org.uk/python/articles/configobj_for_data_persistence.shtml
67
90
.. _ConfigPersist.py: http://www.voidspace.org.uk/python/configpersist.html
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 [#]_.
96
The current version is **4.2.0**, dated 16th February 2006. ConfigObj 4 is
97
now stable. We still expect to pick up a few bugs along the way though [#]_.
76
100
You can get ConfigObj in the following ways :
291
317
the options_ ``file_error`` and ``create_empty``. The filename will be
292
318
preserved as the ``filename`` attribute. This can be changed at any time.
294
* A list of lines. Any trailing ``\n`` will be removed from the lines. The
320
* A list of lines. Any trailing newlines will be removed from the lines. The
295
321
``filename`` attribute of your ConfigObj will be ``None``.
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.
323
* A ``StringIO`` instance or file object, or any object with a ``read`` method.
324
The ``filename`` attribute of your ConfigObj will be ``None`` [#]_.
303
326
* A dictionary. You can initialise a ConfigObj from a dictionary [#]_. The
304
327
``filename`` attribute of your ConfigObj will be ``None``. All keys must be
402
429
If this option *is* specified, the option value is used in the output
403
430
config, overriding the type of indentation in the input config (if any).
432
* 'encoding': ``None``
434
By default **ConfigObj** does not decode the file/strings you pass it into
435
Unicode [#]_. If you want your config file as Unicode (keys and members)
436
you need to provide an encoding to decode the file with. This encoding will
437
also be used to encode the config file when writing.
439
You can change the encoding attribute at any time.
441
Any characters in your strings that can't be encoded with the specified
442
encoding will raise a ``UnicodeEncodeError``.
446
``UTF16`` encoded files will automatically be detected and decoded,
447
even if ``encoding`` is ``None``.
449
This is because it is a 16-bit encoding, and ConfigObj will mangle it
450
(split characters on byte boundaries) if it parses it without decoding.
452
* 'default_encoding': ``None``
454
When using the ``write`` method, **ConfigObj** uses the ``encoding``
455
attribute to encode the Unicode strings. If any members (or keys) have
456
been set as byte strings instead of Unicode, these must first be decoded
457
to Unicode before outputting in the specified encoding.
459
``default_encoding``, if specified, is the encoding used to decode byte
460
strings in the **ConfigObj** before writing. If this is ``None``, then
461
the Python default encoding (``sys.defaultencoding`` - usually ascii) is
464
For most Western European users, a value of ``latin-1`` is sensible.
466
``default_encoding`` is *only* used if an ``encoding`` is specified.
468
Any characters in byte-strings that can't be decoded using the
469
``default_encoding`` will raise a ``UnicodeDecodeError``.
409
476
subclass of ``dict``, the builtin dictionary type. This means it also has
410
477
**all** the normal dictionary methods.
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.
479
In addition, the following `Section Methods`_ may be useful :
490
Read about Sections_ for details of all the methods.
494
The *merge* method of sections is a recursive update.
496
You can use this to merge sections, or even whole ConfigObjs, into each
499
You would typically use this to create a default ConfigObj and then merge
500
in user settings. This way users only need to specify values that are
501
different from the default.
416
504
The public methods available on ConfigObj are :
424
This method takes no arguments [#]_. It writes the current ConfigObj. What that
425
means depends on the ``filename`` attribute of the ConfigObj.
428
ConfigObj will write the configuration to file.
514
write(file_object=None)
516
This method writes the current ConfigObj and takes a single, optional argument
519
If you pass in a file like object to the ``write`` method, the config file will
520
be written to this. (The only method of this object that is used is its
521
``write`` method, so a ``StringIO`` instance, or any other file like object
524
Otherwise, the behaviour of this method depends on the ``filename`` attribute
528
ConfigObj will write the configuration to the file specified.
431
531
``write`` returns a list of lines. (Not ``'\n'`` terminated)
434
If ``filename`` is an object with a seek attribute, then the config file is
435
written to that object.
437
533
First the 'initial_comment' is written, then the config file, followed by the
438
534
'final_comment'. Comment lines and inline comments are written with each
484
588
See `ConfigObj for Data Persistence`_.
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
594
By default, the validate method either returns ``True`` (everything passed)
595
or a dictionary of ``True``/``False`` representing pass/fail. The dictionary
596
follows the structure of the ConfigObj.
493
598
If a whole section passes then it is replaced with the value ``True``. If a
494
599
whole section fails, then it is replaced with the value ``False``.
496
601
If a value is missing, and there is no default in the check, then the check
497
602
automatically fails.
604
The ``validate`` method takes an optional keyword argument ``preserve_errors``.
605
If you set this to ``True``, instead of getting ``False`` for failed checks you
606
get the actual error object from the **validate** module. This usually contains
607
useful information about why the check failed.
609
See the `flatten_errors`_ function for how to turn your results dictionary into
610
a useful list of error messages.
612
Even if ``preserve_errors`` is ``True``, missing keys or sections will still be
613
represented by a ``False`` in the results dictionary.
499
616
Mentioning Default Values
500
617
#########################
625
751
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``.
629
If it is set, then it is written out by the ``write`` method.
752
slightly incorrectly as the {acro;BOM;Byte Order Mark}), or the UTF16 BOM, then
753
this attribute is set to ``True``. Otherwise it is ``False``.
755
If it is set to ``True`` when ``write`` is called then, if ``encoding`` is set
756
to ``None`` *or* to ``utf_8`` (and variants) a UTF BOM will be written.
758
For UTF16 encodings, a BOM is *always* written.
649
778
The ``write`` method puts these lines after it finishes writing out the
784
This attribute is ``True`` or ``False``. If set to ``False`` then values are
785
not parsed for list values. In addition single line values are not unquoted.
787
This allows you to do your own parsing of values. It exists primarily to
788
support the reading of the configspec_ - but has other use cases.
790
For example you could use the ``LineParser`` from the
791
`listquote module <http://www.voidspace.org.uk/python/listquote.html#lineparser>`_
792
to read values for nested lists.
794
Single line values aren't quoted when writing - but multiline values are
799
Because values aren't quoted, leading or trailing whitespace can be
802
This behaviour was changed in version 4.0.1.
804
Prior to this, single line values might have been quoted; even with
805
``list_values=False``. This means that files written by **ConfigObj**
806
*could* now be incompatible - and need the quotes removing by hand.
811
This is the encoding used to encode the output, when you call ``write``. It
812
must be a valid encoding `recognised by Python <http://docs.python.org/lib/standard-encodings.html>`_.
814
If this value is ``None`` then no encoding is done when ``write`` is called.
820
If encoding is set, any byte-strings in your ConfigObj instance (keys or
821
members) will first be decoded to unicode using the encoding specified by the
822
``default_encoding`` attribute. This ensures that the output is in the encoding
825
If this value is ``None`` then ``sys.defaultencoding`` is used instead.
652
827
The Config File Format
653
828
======================
958
1133
It is mainly implemented for the ``encode`` and ``decode`` methods, which
959
1134
provide some Unicode support.
1140
This method is a *recursive update* method. It allows you to merge two
1141
config files together.
1143
You would typically use this to create a default ConfigObj and then merge
1144
in user settings. This way users only need to specify values that are
1145
different from the default.
1153
# def_cfg contains your default config settings
1154
# user_cfg contains the user settings
1155
cfg = ConfigObj(def_cfg)
1156
usr = ConfigObj(user_cfg)
1161
cfg now contains a combination of the default settings and the user
1164
The user settings will have overwritten any of the default ones.
963
1171
This method can be used to transform values and names. See `walking a
964
1172
section`_ for examples and explanation.
968
1176
``decode(encoding)``
970
1178
This method decodes names and values into Unicode objects, using the
971
1179
supplied encoding.
973
Because of the way ConfigObj reads files, config files should be in an
974
ASCII compatible encoding. See encodings_ for more details.
978
1183
``encode(encoding)``
982
1187
It encodes names and values using the supplied encoding. If any of your
983
1188
names/values are strings rather than Unicode, Python will have to do an
984
implicit decode first.
986
See encodings_ for more details.
1189
implicit decode first. (This method uses ``sys.defaultencoding`` for
1196
Returns ``True`` if the key contains a string that represents ``True``, or
1197
is the ``True`` object.
1199
Returns ``False`` if the key contains a string that represents ``False``,
1200
or is the ``False`` object.
1202
Raises a ``ValueError`` if the key contains anything else.
1204
Strings that represent ``True`` are (not case sensitive) : ::
1208
Strings that represent ``False`` are : ::
1214
In ConfigObj 4.1.0, this method was called ``istrue``. That method is
1215
now deprecated and will issue a warning when used. It will go away
1216
in the next release.
1222
This returns the value contained in the specified key as an integer.
1224
It raises a ``ValueError`` if the conversion can't be done.
1230
This returns the value contained in the specified key as a float.
1232
It raises a ``ValueError`` if the conversion can't be done.
988
1234
Walking a Section
989
1235
-----------------
1371
Here's a simple example of using ``walk`` to transform names and values. One
1372
usecase of this would be to create a *standard* config file with placeholders
1373
for section and keynames. You can then use walk to create new config files
1374
and change values and member names :
1380
# We use 'XXXX' as a placeholder
1382
XXXXkey1 = XXXXvalue1
1383
XXXXkey2 = XXXXvalue2
1384
XXXXkey3 = XXXXvalue3
1386
XXXXkey1 = XXXXvalue1
1387
XXXXkey2 = XXXXvalue2
1388
XXXXkey3 = XXXXvalue3
1390
XXXXkey1 = XXXXvalue1
1391
XXXXkey2 = XXXXvalue2
1392
XXXXkey3 = XXXXvalue3
1394
XXXXkey1 = XXXXvalue1
1395
XXXXkey2 = XXXXvalue2
1396
XXXXkey3 = XXXXvalue3
1398
cfg = ConfigObj(config)
1400
def transform(section, key):
1402
newkey = key.replace('XXXX', 'CLIENT1')
1403
section.rename(key, newkey)
1404
if isinstance(val, (tuple, list, dict)):
1407
val = val.replace('XXXX', 'CLIENT1')
1408
section[newkey] = val
1410
cfg.walk(transform, call_on_sections=True)
1412
{'CLIENT1key1': 'CLIENT1value1', 'CLIENT1key2': 'CLIENT1value2',
1413
'CLIENT1key3': 'CLIENT1value3',
1414
'CLIENT1section1': {'CLIENT1key1': 'CLIENT1value1',
1415
'CLIENT1key2': 'CLIENT1value2', 'CLIENT1key3': 'CLIENT1value3'},
1416
'CLIENT1section2': {'CLIENT1key1': 'CLIENT1value1',
1417
'CLIENT1key2': 'CLIENT1value2', 'CLIENT1key3': 'CLIENT1value3',
1418
'CLIENT1section1': {'CLIENT1key1': 'CLIENT1value1',
1419
'CLIENT1key2': 'CLIENT1value2', 'CLIENT1key3': 'CLIENT1value3'}}}
1460
1791
These comments are all written back out by the ``write`` method.
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.
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``.
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.
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.
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
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.
1799
flatten_errors(cfg, res)
1801
Validation_ is a powerful way of checking that the values supplied by the user
1804
The validate_ method returns a results dictionary that represents pass or fail
1805
for each value. This doesn't give you any information about *why* the check
1808
``flatten_errors`` is an example function that turns a results dictionary into
1809
a flat list, that only contains vaues that *failed*.
1811
``cfg`` is the ConfigObj instance being checked, ``res`` is the results
1812
dictionary returned by ``validate``.
1814
It returns a list of keys that failed. Each member of the list is a tuple : ::
1816
([list of sections...], key, result)
1818
If ``validate`` was called with ``preserve_errors=False`` (the default)
1819
then ``result`` will always be ``False``.
1821
*list of sections* is a flattened list of sections that the key was found
1824
If the section was missing then key will be ``None``.
1826
If the value (or section) was missing then ``result`` will be ``False``.
1828
If ``validate`` was called with ``preserve_errors=True`` and a value
1829
was present, but failed the check, then ``result`` will be the exception
1830
object returned. You can use this as a string that describes the failure.
1834
*The value "3" is of the wrong type*.
1840
The output from ``flatten_errors`` is a list of tuples.
1842
Here is an example of how you could present this information to the user.
1848
vtor = validate.Validator()
1849
# ini is your config file - cs is the configspec
1850
cfg = ConfigObj(ini, configspec=cs)
1851
res = cfg.validate(vtor, preserve_errors=True)
1852
for entry in flatten_errors(cfg, res):
1853
# each entry is a tuple
1854
section_list, key, error = entry
1856
section_list.append(key)
1858
section_list.append('[missing section]')
1859
section_string = ', '.join(section_list)
1861
error = 'Missing value or section.'
1862
print section_string, ' = ', error
1493
1866
Backwards Compatibility
1494
1867
=======================
1670
2044
parent*: this means that checking the 'DEFAULT' sub-section in the *current
1671
2045
section* is not necessarily logical ?
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.
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.
1686
2047
Does it matter that we don't support the ':' divider, which is supported by
1687
2048
``ConfigParser`` ?
1689
Following error with "list_values=False" : ::
1691
>>> a = ["a='hello', 'goodbye'"]
1693
>>> c(a, list_values=False)
1694
{'a': "hello', 'goodbye"}
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
1704
2050
String interpolation and validation don't play well together. See
1705
2051
`Validation and Interpolation`_.
2053
Validation is no longer done on the 'DEFAULT' section (on the root level). This
2054
allows interpolation from within your configspec - but also prevents you
2055
validating the 'DEFAULT' section.
1711
2062
From version 4 it lists all releases and changes. *More* data on individual
1712
2063
changes may be found in the source code.
2065
2006/02/16 - Version 4.2.0
2066
--------------------------
2068
Removed ``BOM_UTF8`` from ``__all__``.
2070
The ``BOM`` attribute has become a boolean. (Defaults to ``False``.) It is
2071
*only* ``True`` for the ``UTF16`` encoding.
2073
File like objects no longer need a ``seek`` attribute.
2075
Full unicode support added. New options/attributes ``encoding``,
2076
``default_encoding``.
2078
ConfigObj no longer keeps a reference to file like objects. Instead the
2079
``write`` method takes a file like object as an optional argument. (Which
2080
will be used in preference of the ``filename`` attribute if that exists as
2083
utf16 files decoded to unicode.
2085
If ``BOM`` is ``True``, but no encoding specified, then the utf8 BOM is
2086
written out at the start of the file. (It will normally only be ``True`` if
2087
the utf8 BOM was found when the file was read.)
2089
File paths are *not* converted to absolute paths, relative paths will
2090
remain relative as the ``filename`` attribute.
2092
Fixed bug where ``final_comment`` wasn't returned if ``write`` is returning
2095
Deprecated ``istrue``, replaced it with ``as_bool``.
2097
Added ``as_int`` and ``as_float``.
2099
2005/12/14 - Version 4.1.0
2100
--------------------------
2102
Added ``merge``, a recursive update.
2104
Added ``preserve_errors`` to ``validate`` and the ``flatten_errors``
2107
Thanks to Matthew Brett for suggestions and helping me iron out bugs.
2109
Fixed bug where a config file is *all* comment, the comment will now be
2110
``initial_comment`` rather than ``final_comment``.
2112
Validation no longer done on the 'DEFAULT' section (only in the root level).
2113
This allows interpolation in configspecs.
2115
Also use the new list syntax in validate_ 0.2.1. (For configspecs).
2117
2005/12/02 - Version 4.0.2
2118
--------------------------
2120
Fixed bug in ``create_empty``. Thanks to Paul Jimenez for the report.
2123
2005/11/05 - Version 4.0.1
2124
--------------------------
2126
Fixed bug in ``Section.walk`` when transforming names as well as values.
2128
Added the ``istrue`` method. (Fetches the boolean equivalent of a string
2131
Fixed ``list_values=False`` - they are now only quoted/unquoted if they
2132
are multiline values.
2134
List values are written as ``item, item`` rather than ``item,item``.
1714
2137
2005/10/17 - Version 4.0.0
1715
2138
--------------------------
1881
.. [#] The core parser is now based on regular expressions, so it's a lot
1884
.. [#] 134 of them, at the time of writing.
2304
.. [#] 253 of them, at the time of writing.
1886
2306
.. [#] And if you discover any bugs, let us know. We'll fix them quickly.
1888
2308
.. [#] If you specify a filename that doesn't exist, ConfigObj will assume you
1889
2309
are creating a new one. See the *create_empty* and *file_error* options_.
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.
2311
.. [#] They can be byte strings ('ordinary' strings) or Unicode.
2313
.. [#] This is a change in ConfigObj 4.2.0. Note that ConfigObj doesn't call
2314
the seek method of any file like object you pass in. You may want to call
2315
``file_object.seek(0)`` yourself, first.
1895
2317
.. [#] Except we don't support the RFC822 style line continuations, nor ':' as
1902
2324
.. [#] A side effect of this is that it enables you to copy a ConfigObj :
1908
# only copies members
1909
# not attributes/comments
1910
config2 = ConfigObj(config1)
2330
# only copies members
2331
# not attributes/comments
2332
config2 = ConfigObj(config1)
1916
2336
The order of values and sections will not be preserved, though.
2338
.. [#] The exception is if it detects a ``UTF16`` encoded file which it
2339
must decode before parsing.
1918
2341
.. [#] Other than lists of strings.
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.
2343
.. [#] The method signature in the API docs will show that this method takes
2344
two arguments. The second is the section to be written. This is because the
2345
``write`` method is called recursively.
1925
2347
.. [#] The dict method doesn't actually use the deepcopy mechanism. This means
1926
2348
if you add nested lists (etc) to your ConfigObj, then the dictionary
added
removed
bzrlib/util/configobj/docs/configobj.txt
