111
106
various other useful modules, and is required by many of the `Voidspace Python
112
It is sometimes possible to get the latest *development version* of ConfigObj
113
from the `Subversion Repository <http://svn.pythonutils.python-hosting.com/trunk/pythonutils/>`_.
114
115
.. _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
.. _configobj.zip: http://www.voidspace.org.uk/cgi-bin/voidspace/downman.py?file=configobj-4.4.0.zip
116
117
.. _validate.py: http://www.voidspace.org.uk/cgi-bin/voidspace/downman.py?file=validate.py
117
118
.. _API Docs: http://www.voidspace.org.uk/python/configobj-api/
118
119
.. _this document:
119
120
.. _configobj homepage: http://www.voidspace.org.uk/python/configobj.html
120
.. _Subversion Repository: http://svn.rest2web.python-hosting.com/branches/configobj4
121
121
.. _Sourceforge: http://sourceforge.net/projects/configobj
122
122
.. _EpyDoc: http://epydoc.sourceforge.net
123
123
.. _pythonutils: http://www.voidspace.org.uk/python/pythonutils.html
124
124
.. _Voidspace Python Projects: http://www.voidspace.org.uk/python
128
ConfigObj in the Real World
129
===========================
131
Projects that use **ConfigObj** include :
133
* `Bazaar <http://bazaar-ng.org>`_.
135
Bazaar is a Python distributed {acro;VCS;Version Control System}.
136
ConfigObj is used to read ``bazaar.conf`` and ``branches.conf``.
138
* `Turbogears <http://www.turbogears.org/>`_
140
Turbogears is a web application framework.
142
* `Chandler <http://chandler.osafoundation.org/>`_
144
A Python and `wxPython <http://www.wxpython.org>`_
145
{acro;PIM;Personal Information Manager}, being developed by the
146
`OSAFoundation <http://www.osafoundation.org/>`_.
148
* `CryptoBox <https://systemausfall.org/trac/cryptobox/wiki/CryptoBox/en>`_
150
A very interesting looking Debian based Live-CD which supports storing
151
data using an encrypted harddisk; usable even by non technical users.
153
* `Simple64 <http://ubuntuforums.org/showthread.php?t=266290>`_
155
A Ubuntu tool which provides a GUI to install a host of applications.
157
* `Debian-cd-ng <http://wiki.debian.org/debian-cd-ng>`_
159
*Debian-cd-ng* recommends ConfigObj for parsing the Debian-cd configuration files.
161
* `NeuroImaging in Python <http://projects.scipy.org/neuroimaging/ni/wiki>`_
163
BrainSTAT is a project with the ultimate goal to produce a
164
platform-independent python environment for the analysis of brain
167
* `Gruik <http://www.tracos.org/gruik/wiki>`_
169
Gruik is a free software network packet sniffer.
1906
Many config files from other applications allow empty values. As of version
1907
4.3.0, ConfigObj will read these as an empty string.
1909
A new option/attribute has been added (``write_empty_values``) to allow
1910
ConfigObj to write empty strings as empty values.
1915
from configobj import ConfigObj
1920
config = ConfigObj(cfg)
1922
ConfigObj({'key': '', 'key2': ''})
1924
config.write_empty_values = True
1925
for line in config.write():
1935
The ``unrepr`` option allows you to store and retrieve the basic Python
1936
data-types using config files. It has to use a slightly different syntax to
1937
normal ConfigObj files. Unsurprisingly it uses Python syntax.
1939
This means that lists are different (they are surrounded by square brackets),
1940
and strings *must* be quoted.
1942
The types that ``unrepr`` can work with are :
1944
| strings, lists tuples
1946
| dictionaries, integers, floats
1947
| longs and complex numbers
1949
You can't store classes, types or instances.
1951
``unrepr`` uses ``repr(object)`` to write out values, so it currently *doesn't*
1952
check that you are writing valid objects. If you attempt to read an unsupported
1953
value, ConfigObj will raise a ``configobj.UnknownType`` exception.
1955
Values that are triple quoted cased. The triple quotes are removed *before*
1956
converting. This means that you can use triple quotes to write dictionaries
1957
over several lines in your config files. They won't be written like this
1960
If you are writing config files by hand, for use with ``unrepr``, you should
1961
be aware of the following differences from normal ConfigObj syntax :
1963
| List : ``['A List', 'With', 'Strings']``
1964
| Strings : ``"Must be quoted."``
1965
| Backslash : ``"The backslash must be escaped \\"``
1967
These all follow normal Python syntax.
1969
In unrepr mode *inline comments* are not saved. This is because lines are
1970
parsed using the `compiler package <http://docs.python.org/lib/compiler.html>`_
1971
which discards comments.
1973
String Interpolation
1974
====================
1410
1976
ConfigObj allows string interpolation *similar* to the way ``ConfigParser``
1412
You specify a value to be substituted by including ``%(name)s`` in the value.
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).
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.
1420
If the value specified isn't found then a ``MissingInterpolationOption`` error
1421
is raised (a subclass of ``ConfigObjError``).
1977
or ``string.Template`` work. The value of the ``interpolation`` attribute
1978
determines which style of interpolation you want to use. Valid values are
1979
"ConfigParser" or "Template" (case-insensitive, so "configparser" and
1980
"template" will also work). For backwards compatibility reasons, the value
1981
``True`` is also a valid value for the ``interpolation`` attribute, and
1982
will select ``ConfigParser``-style interpolation. At some undetermined point
1983
in the future, that default *may* change to ``Template``-style interpolation.
1985
For ``ConfigParser``-style interpolation, you specify a value to be
1986
substituted by including ``%(name)s`` in the value.
1988
For ``Template``-style interpolation, you specify a value to be substituted
1989
by including ``${cl}name{cr}`` in the value. Alternately, if 'name' is a valid
1990
Python identifier (i.e., is composed of nothing but alphanumeric characters,
1991
plus the underscore character), then the braces are optional and the value
1992
can be written as ``$name``.
1994
Note that ``ConfigParser``-style interpolation and ``Template``-style
1995
interpolation are mutually exclusive; you cannot have a configuration file
1996
that's a mix of one or the other. Pick one and stick to it. ``Template``-style
1997
interpolation is simpler to read and write by hand, and is recommended if
1998
you don't have a particular reason to use ``ConfigParser``-style.
2000
Interpolation checks first the current section to see if ``name`` is the key
2001
to a value. ('name' is case sensitive).
2003
If it doesn't find it, next it checks the 'DEFAULT' sub-section of the current
2006
If it still doesn't find it, it moves on to check the parent section and the
2007
parent section's 'DEFAULT' subsection, and so on all the way up to the main
2010
If the value specified isn't found in any of these locations, then a
2011
``MissingInterpolationOption`` error is raised (a subclass of
2012
``ConfigObjError``).
1423
2014
If it is found then the returned value is also checked for substitutions. This
1424
2015
allows you to make up compound values (for example directory paths) that use
1425
2016
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.
2017
references. If there are any circular references which would cause an infinite
2018
interpolation loop, an ``InterpolationLoopError`` is raised.
1429
2020
Both of these errors are subclasses of ``InterpolationError``, which is a
1430
2021
subclass of ``ConfigObjError``.
1460
2052
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.
2060
flatten_errors(cfg, res)
2062
Validation_ is a powerful way of checking that the values supplied by the user
2065
The validate_ method returns a results dictionary that represents pass or fail
2066
for each value. This doesn't give you any information about *why* the check
2069
``flatten_errors`` is an example function that turns a results dictionary into
2070
a flat list, that only contains values that *failed*.
2072
``cfg`` is the ConfigObj instance being checked, ``res`` is the results
2073
dictionary returned by ``validate``.
2075
It returns a list of keys that failed. Each member of the list is a tuple : ::
2077
([list of sections...], key, result)
2079
If ``validate`` was called with ``preserve_errors=False`` (the default)
2080
then ``result`` will always be ``False``.
2082
*list of sections* is a flattened list of sections that the key was found
2085
If the section was missing then key will be ``None``.
2087
If the value (or section) was missing then ``result`` will be ``False``.
2089
If ``validate`` was called with ``preserve_errors=True`` and a value
2090
was present, but failed the check, then ``result`` will be the exception
2091
object returned. You can use this as a string that describes the failure.
2095
*The value "3" is of the wrong type*.
2101
The output from ``flatten_errors`` is a list of tuples.
2103
Here is an example of how you could present this information to the user.
2109
vtor = validate.Validator()
2110
# ini is your config file - cs is the configspec
2111
cfg = ConfigObj(ini, configspec=cs)
2112
res = cfg.validate(vtor, preserve_errors=True)
2113
for entry in flatten_errors(cfg, res):
2114
# each entry is a tuple
2115
section_list, key, error = entry
2117
section_list.append(key)
2119
section_list.append('[missing section]')
2120
section_string = ', '.join(section_list)
2122
error = 'Missing value or section.'
2123
print section_string, ' = ', error
1493
2127
Backwards Compatibility
1494
2128
=======================
1637
2270
You should also be able to find a copy of this license at : `BSD License`_
1639
.. _BSD License: http://www.voidspace.org.uk/documents/BSD-LICENSE.txt
2272
.. _BSD License: http://www.voidspace.org.uk/python/license.shtml
1644
Fix any bugs (and resolvable issues).
1646
Do an example for the 'walk' which removes uniform indentation in multiline
1649
When initialising a section from a ConfigObj *or* an ``OrderedDictionary``
1650
we could preserve ordering.
1652
Add an *odict* method which returns an `OrderedDictionary``.
2278
Better support for configuration from multiple files, including tracking
2279
*where* the original file came from and writing changes to the correct
2282
Make ``newline`` an option (as well as an attribute) ?
2284
``UTF16`` encoded files, when returned as a list of lines, will have the
2285
BOM at the start of every line. Should this be removed from all but the
2288
Option to set warning type for unicode decode ? (Defaults to strict).
2290
A method to optionally remove uniform indentation from multiline values.
2291
(do as an example of using ``walk`` - along with string-escape)
2293
Should the results dictionary from validate be an ordered dictionary if
2294
`odict <http://www.voidspace.org.uk/python/odict.html>`_ is available ?
2296
Implement some of the sequence methods (which include slicing) from the
2299
Preserve line numbers of values (and possibly the original text of each value).
1659
Please file any bug reports to `Michael Foord`_ or the ConfigObj
2307
Please file any bug reports to `Michael Foord`_ or the **ConfigObj**
1660
2308
`Mailing List`_.
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.
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.
2310
There is currently no way to specify the encoding of a configspec file.
2312
When using ``copy`` mode for validation, it won't copy ``DEFAULT``
2313
sections. This is so that you *can* use interpolation in configspec
2316
``validate`` doesn't report *extra* values or sections.
2318
You can't have a keyword with the same name as a section (in the same
2319
section). They are both dictionary keys - so they would overlap.
2321
ConfigObj doesn't quote and unquote values if ``list_values=False``.
2322
This means that leading or trailing whitespace in values will be lost when
2323
writing. (Unless you manually quote).
2325
Interpolation checks first the current section, then the 'DEFAULT' subsection
2326
of the current section, before moving on to the current section's parent and
1669
2329
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 ?
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
Does it matter that we don't support the ':' divider, which is supported by
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
String interpolation and validation don't play well together. See
1705
`Validation and Interpolation`_.
2330
parent* - this means that checking the 'DEFAULT' subsection in the
2331
*current section* is not necessarily logical ?
2333
Does it matter that we don't support the ':' divider, which is supported
2334
by ``ConfigParser`` ?
2336
String interpolation and validation don't play well together. When
2337
validation changes type it sets the value. This will correctly fetch the
2338
value using interpolation - but then overwrite the interpolation reference.
2339
If the value is unchanged by validation (it's a string) - but other types
1710
2346
This is an abbreviated changelog showing the major releases up to version 4.
1711
2347
From version 4 it lists all releases and changes. *More* data on individual
1712
changes may be found in the source code.
2348
changes may be found in the source code or the CHANGELOG file.
2351
2007/02/04 - Version 4.4.0
2352
--------------------------
2354
Official release of 4.4.0
2357
2006/12/17 - Version 4.3.3-alpha4
2358
---------------------------------
2362
Allowed arbitrary indentation in the ``indent_type`` parameter, removed the
2363
``NUM_INDENT_SPACES`` and ``MAX_INTERPOL_DEPTH`` (a leftover) constants,
2364
added indentation tests (including another docutils workaround, sigh), updated
2369
Made the import of ``compiler`` conditional so that ``ConfigObj`` can be used
2370
with `IronPython <http://www.codeplex.com/IronPython>`_.
2373
2006/12/17 - Version 4.3.3-alpha3
2374
---------------------------------
2378
Added a missing ``self.`` in the _handle_comment method and a related test,
2379
per Sourceforge bug #1523975.
2382
2006/12/09 - Version 4.3.3-alpha2
2383
---------------------------------
2387
Changed interpolation search strategy, based on this patch by Robin Munn:
2388
http://sourceforge.net/mailarchive/message.php?msg_id=17125993
2391
2006/12/09 - Version 4.3.3-alpha1
2392
---------------------------------
2396
Added Template-style interpolation, with tests, based on this patch by
2397
Robin Munn: http://sourceforge.net/mailarchive/message.php?msg_id=17125991
2398
(awful archives, bad Sourceforge, bad).
2401
2006/06/04 - Version 4.3.2
2402
--------------------------
2404
Changed error handling, if parsing finds a single error then that error will
2405
be re-raised. That error will still have an ``errors`` and a ``config``
2408
Fixed bug where '\n' terminated files could be truncated.
2410
Bugfix in ``unrepr`` mode, it couldn't handle '#' in values. (Thanks to
2411
Philippe Normand for the report.)
2413
As a consequence of this fix, ConfigObj doesn't now keep inline comments in
2414
``unrepr`` mode. This is because the parser in the `compiler package`_
2415
doesn't keep comments. {sm;:-)}
2417
Error messages are now more useful. They tell you the number of parsing errors
2418
and the line number of the first error. (In the case of multiple errors.)
2420
Line numbers in exceptions now start at 1, not 0.
2422
Errors in ``unrepr`` mode are now handled the same way as in the normal mode.
2423
The errors stored will be an ``UnreprError``.
2426
2006/04/29 - Version 4.3.1
2427
--------------------------
2429
Added ``validate.py`` back into ``configobj.zip``. (Thanks to Stewart
2432
Updated to `validate.py`_ 0.2.2.
2434
Preserve tuples when calling the ``dict`` method. (Thanks to Gustavo Niemeyer.)
2436
Changed ``__repr__`` to return a string that contains ``ConfigObj({ ... })``.
2438
Change so that an options dictionary isn't modified by passing it to ConfigObj.
2439
(Thanks to Artarious.)
2441
Added ability to handle negative integers in ``unrepr``. (Thanks to Kevin
2445
2006/03/24 - Version 4.3.0
2446
--------------------------
2448
Moved the tests and the CHANGELOG (etc) into a separate file. This has reduced
2449
the size of ``configobj.py`` by about 40%.
2451
Added the ``unrepr`` mode to reading and writing config files. Thanks to Kevin
2452
Dangoor for this suggestion.
2454
Empty values are now valid syntax. They are read as an empty string ``''``.
2455
(``key =``, or ``key = # comment``.)
2457
``validate`` now honours the order of the configspec.
2459
Added the ``copy`` mode to validate. Thanks to Louis Cordier for this
2462
Fixed bug where files written on windows could be given ``'\r\r\n'`` line
2465
Fixed bug where last occurring comment line could be interpreted as the
2466
final comment if the last line isn't terminated.
2468
Fixed bug where nested list values would be flattened when ``write`` is
2469
called. Now sub-lists have a string representation written instead.
2471
Deprecated ``encode`` and ``decode`` methods instead.
2473
You can now pass in a ConfigObj instance as a configspec (remember to read
2474
the configspec file using ``list_values=False``).
2476
Sorted footnotes in the docs.
2479
2006/02/16 - Version 4.2.0
2480
--------------------------
2482
Removed ``BOM_UTF8`` from ``__all__``.
2484
The ``BOM`` attribute has become a boolean. (Defaults to ``False``.) It is
2485
*only* ``True`` for the ``UTF16/UTF8`` encodings.
2487
File like objects no longer need a ``seek`` attribute.
2489
Full unicode support added. New options/attributes ``encoding``,
2490
``default_encoding``.
2492
ConfigObj no longer keeps a reference to file like objects. Instead the
2493
``write`` method takes a file like object as an optional argument. (Which
2494
will be used in preference of the ``filename`` attribute if that exists as
2497
utf16 files decoded to unicode.
2499
If ``BOM`` is ``True``, but no encoding specified, then the utf8 BOM is
2500
written out at the start of the file. (It will normally only be ``True`` if
2501
the utf8 BOM was found when the file was read.)
2503
Thanks to Aaron Bentley for help and testing on the unicode issues.
2505
File paths are *not* converted to absolute paths, relative paths will
2506
remain relative as the ``filename`` attribute.
2508
Fixed bug where ``final_comment`` wasn't returned if ``write`` is returning
2511
Deprecated ``istrue``, replaced it with ``as_bool``.
2513
Added ``as_int`` and ``as_float``.
2515
2005/12/14 - Version 4.1.0
2516
--------------------------
2518
Added ``merge``, a recursive update.
2520
Added ``preserve_errors`` to ``validate`` and the ``flatten_errors``
2523
Thanks to Matthew Brett for suggestions and helping me iron out bugs.
2525
Fixed bug where a config file is *all* comment, the comment will now be
2526
``initial_comment`` rather than ``final_comment``.
2528
Validation no longer done on the 'DEFAULT' section (only in the root level).
2529
This allows interpolation in configspecs.
2531
Also use the new list syntax in validate_ 0.2.1. (For configspecs).
2533
2005/12/02 - Version 4.0.2
2534
--------------------------
2536
Fixed bug in ``create_empty``. Thanks to Paul Jimenez for the report.
2539
2005/11/05 - Version 4.0.1
2540
--------------------------
2542
Fixed bug in ``Section.walk`` when transforming names as well as values.
2544
Added the ``istrue`` method. (Fetches the boolean equivalent of a string
2547
Fixed ``list_values=False`` - they are now only quoted/unquoted if they
2548
are multiline values.
2550
List values are written as ``item, item`` rather than ``item,item``.
1714
2553
2005/10/17 - Version 4.0.0
1715
2554
--------------------------
1871
2710
ConfigObj originated in a set of functions for reading config files in the
1872
atlantibots_ project. The original functions were written by Rob McNeur...
2711
`atlantibots <http://www.voidspace.org.uk/atlantibots/>`_ project. The original
2712
functions were written by Rob McNeur.
1874
.. _atlantibots: http://www.voidspace.org.uk/atlantibots
1881
.. [#] The core parser is now based on regular expressions, so it's a lot
1884
.. [#] 134 of them, at the time of writing.
2720
.. [#] 315 of them, at the time of writing.
1886
2722
.. [#] And if you discover any bugs, let us know. We'll fix them quickly.
1888
2724
.. [#] If you specify a filename that doesn't exist, ConfigObj will assume you
1889
2725
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.
2727
.. [#] They can be byte strings (*ordinary* strings) or Unicode.
1895
2729
.. [#] Except we don't support the RFC822 style line continuations, nor ':' as
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.
2732
.. [#] This is a change in ConfigObj 4.2.0. Note that ConfigObj doesn't call
2733
the seek method of any file like object you pass in. You may want to call
2734
``file_object.seek(0)`` yourself, first.
1902
2736
.. [#] 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)
2742
# only copies members
2743
# not attributes/comments
2744
config2 = ConfigObj(config1)
1916
2748
The order of values and sections will not be preserved, though.
1918
2750
.. [#] 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.
2752
.. [#] The exception is if it detects a ``UTF16`` encoded file which it
2753
must decode before parsing.
2755
.. [#] The method signature in the API docs will show that this method takes
2756
two arguments. The second is the section to be written. This is because the
2757
``write`` method is called recursively.
1925
2759
.. [#] The dict method doesn't actually use the deepcopy mechanism. This means
1926
2760
if you add nested lists (etc) to your ConfigObj, then the dictionary
added
removed
bzrlib/util/configobj/docs/configobj.txt
