1
==================================
2
Reading and Writing Config Files
3
==================================
5
----------------------------------------
6
ConfigObj 4 Introduction and Reference
7
----------------------------------------
9
:Authors: Michael Foord, Nicola Larosa
10
:Version: ConfigObj 4.2.0
12
:Homepage: `ConfigObj Homepage`_
13
:Sourceforge: Sourceforge_
14
:License: `BSD License`_
15
:Support: `Mailing List`_
17
.. _Mailing List: http://lists.sourceforge.net/lists/listinfo/configobj-develop
20
:description: ConfigObj - a Python module for easy reading and writing of
22
:keywords: python, script, module, config, configuration, data, persistence,
23
developer, configparser
25
.. contents:: ConfigObj Manual
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 :
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.
60
* Nested sections (subsections), to any level
62
* Multiple line values
63
* String interpolation (substitution)
64
* Integrated with a powerful validation system
66
- including automatic type checking/conversion
68
- and allowing default values
70
* All comments in the file are preserved
71
* The order of keys/sections is preserved
72
* 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.
80
For support and bug reports please use the ConfigObj `Mailing List`_.
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`_.
87
The code from that article is available as ConfigPersist.py_.
89
.. _ConfigObj for Data Persistence: http://www.voidspace.org.uk/python/articles/configobj_for_data_persistence.shtml
90
.. _ConfigPersist.py: http://www.voidspace.org.uk/python/configpersist.html
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 [#]_.
100
You can get ConfigObj in the following ways :
105
* configobj.py_ from Voidspace
107
ConfigObj has no external dependencies. This file is sufficient to access
108
all the functionality except Validation_.
110
* configobj.zip_ from Voidspace
112
This also contains validate.py_ , the `API Docs`_ and `this document`_.
114
* The latest development version can be obtained from the `Subversion
117
* validate.py_ from Voidspace
119
* You can also download *configobj.zip* from Sourceforge_
124
*configobj.zip* contains `this document`_ and full `API Docs`_, generated by
127
* You can view `this document`_ online as the `ConfigObj Homepage`_.
129
* You can also browse the `API Docs`_ online.
134
ConfigObj is also part of the Pythonutils_ set of modules. This contains
135
various other useful modules, and is required by many of the `Voidspace Python
138
.. _configobj.py: http://www.voidspace.org.uk/cgi-bin/voidspace/downman.py?file=configobj.py
139
.. _configobj.zip: http://www.voidspace.org.uk/cgi-bin/voidspace/downman.py?file=configobj-4.2.0.zip
140
.. _validate.py: http://www.voidspace.org.uk/cgi-bin/voidspace/downman.py?file=validate.py
141
.. _API Docs: http://www.voidspace.org.uk/python/configobj-api/
143
.. _configobj homepage: http://www.voidspace.org.uk/python/configobj.html
144
.. _Subversion Repository: http://svn.rest2web.python-hosting.com/branches/configobj4
145
.. _Sourceforge: http://sourceforge.net/projects/configobj
146
.. _EpyDoc: http://epydoc.sourceforge.net
147
.. _pythonutils: http://www.voidspace.org.uk/python/pythonutils.html
148
.. _Voidspace Python Projects: http://www.voidspace.org.uk/python
154
The outstanding feature of using ConfigObj is simplicity. Most functions can be
155
performed with single line commands.
157
Reading a Config File
158
---------------------
160
The normal way to read a config file, is to give ConfigObj the filename :
166
from configobj import ConfigObj
167
config = ConfigObj(filename)
171
You can also pass the config file in as a list of lines, or a ``StringIO``
172
instance, so it doesn't matter where your config data comes from.
174
You can then access members of your config file as a dictionary. Subsections
175
will also be dictionaries.
181
from configobj import ConfigObj
182
config = ConfigObj(filename)
184
value1 = config['keyword1']
185
value2 = config['keyword2']
187
section1 = config['section1']
188
value3 = section1['keyword3']
189
value4 = section1['keyword4']
191
# you could also write
192
value3 = config['section1']['keyword3']
193
value4 = config['section1']['keyword4']
197
Writing a Config File
198
---------------------
200
Creating a new config file is just as easy as reading one. You can specify a
201
filename when you create the ConfigObj, or do it later [#]_.
203
If you *don't* set a filename, then the ``write`` method will return a list of
204
lines instead of writing to file. See the write_ method for more details.
206
Here we show creating an empty ConfigObj, setting a filename and some values,
207
and then writing to file :
213
from configobj import ConfigObj
215
config.filename = filename
217
config['keyword1'] = value1
218
config['keyword2'] = value2
220
config['section1'] = {}
221
config['section1']['keyword3'] = value3
222
config['section1']['keyword4'] = value4
231
config['section2'] = section2
233
config['section3'] = {}
234
config['section3']['keyword 8'] = [value8, value9, value10]
235
config['section3']['keyword 9'] = [value11, value12, value13]
243
Keywords and section names can only be strings [#]_. Attempting to set
244
anything else will raise a ``ValueError``.
249
The config files that ConfigObj will read and write are based on the 'INI'
250
format. This means it will read and write files created for ``ConfigParser``
253
Keywords and values are separated by an ``'='``, and section markers are
254
between square brackets. Keywords, values, and section names can be surrounded
255
by single or double quotes. Indentation is not significant, but can be
258
Subsections are indicated by repeating the square brackets in the section
259
marker. You nest levels by using more brackets.
261
You can have list values by separating items with a comma, and values spanning
262
multiple lines by using triple quotes (single or double).
264
For full details on all these see `the config file format`_. Here's an example
267
# This is the 'initial_comment'
268
# Which may be several lines
270
'keyword 2' = 'value 2'
273
# This comment goes with keyword 3
275
'keyword 4' = value4, value 5, 'value 6'
277
[[ sub-section ]] # an inline comment
278
# sub-section is inside "section 1"
279
'keyword 5' = 'value 7'
280
'keyword 6' = '''A multiline value,
281
that spans more than one line :-)
282
The line breaks are included in the value.'''
284
[[[ sub-sub-section ]]]
285
# sub-sub-section is *in* 'sub-section'
286
# which is in 'section 1'
287
'keyword 7' = 'value 8'
289
[section 2] # an inline comment
291
keyword9 = value10 # an inline comment
292
# The 'final_comment'
293
# Which also may be several lines
296
ConfigObj specifications
297
========================
303
config = ConfigObj(infile=None, options=None, **keywargs)
310
You don't need to specify an infile. If you omit it, an empty ConfigObj will be
311
created. ``infile`` *can* be :
313
* Nothing. In which case the ``filename`` attribute of your ConfigObj will be
314
``None``. You can set a filename at any time.
316
* A filename. What happens if the file doesn't already exist is determined by
317
the options_ ``file_error`` and ``create_empty``. The filename will be
318
preserved as the ``filename`` attribute. This can be changed at any time.
320
* A list of lines. Any trailing newlines will be removed from the lines. The
321
``filename`` attribute of your ConfigObj will be ``None``.
323
* A ``StringIO`` instance or file object, or any object with a ``read`` method.
324
The ``filename`` attribute of your ConfigObj will be ``None`` [#]_.
326
* A dictionary. You can initialise a ConfigObj from a dictionary [#]_. The
327
``filename`` attribute of your ConfigObj will be ``None``. All keys must be
328
strings. In this case, the order of values and sections is arbitrary.
333
There are various options that control the way ConfigObj behaves. They can be
334
passed in as a dictionary of options, or as keyword arguments. Explicit keyword
335
arguments override the dictionary.
337
All of the options are available as attributes after the config file has been
340
ConfigObj has the following options (with the default values shown) :
342
* 'raise_errors': ``False``
344
When parsing, it is possible that the config file will be badly formed. The
345
default is to parse the whole file and raise a single error at the end. You
346
can set ``raise_errors = True`` to have errors raised immediately. See the
347
exceptions_ section for more details.
349
Altering this value after initial parsing has no effect.
351
* 'list_values': ``True``
353
If ``True`` (the default) then list values are possible. If ``False``, the
354
values are not parsed for lists.
356
If ``list_values = False`` then single line values are not quoted or
357
unqouted when reading and writing.
359
Changing this value affects whether single line values will be quoted or
362
* 'create_empty': ``False``
364
If this value is ``True`` and the file specified by ``infile`` doesn't
365
exist, ConfigObj will create an empty file. This can be a useful test that
366
the filename makes sense: an impossible filename will cause an error.
368
Altering this value after initial parsing has no effect.
370
* 'file_error': ``False``
372
If this value is ``True`` and the file specified by ``infile`` doesn't
373
exist, ConfigObj will raise an ``IOError``.
375
Altering this value after initial parsing has no effect.
377
* 'interpolation': ``True``
379
Whether string interpolation is switched on or not. It is on (``True``) by
382
You can set this attribute to change whether string interpolation is done
383
when values are fetched. See the interpolation_ section for more details.
385
* 'configspec': ``None``
387
If you want to use the validation system, you supply a configspec. This is
388
effectively a type of config file that specifies a check for each member.
389
This check can be used to do type conversion as well as check that the
390
value is within your required parameters.
392
You provide a configspec in the same way as you do the initial file: a
393
filename, or list of lines, etc. See the validation_ section for full
394
details on how to use the system.
396
When parsed, every section has a ``configspec`` with a dictionary of
397
configspec checks for *that section*.
399
* 'stringify': ``True``
401
If you use the validation scheme, it can do type checking *and* conversion
402
for you. This means you may want to set members to integers, or other
405
If 'stringify' is set to ``True`` (default) then non-string values will
406
be converted to strings when you write the config file. The validation_
407
process converts values from strings to the required type.
409
If 'stringify' is set to ``False``, attempting to set a member to a
410
non-string value [#]_ will raise a ``TypeError`` (no type conversion is
413
* 'indent_type': ``' '``
415
Indentation is not significant; it can however be present in the output
416
config. Allowable values are: ``''`` (no indentation), ``' '`` (indentation
417
with spaces, fixed at four per level), or ``'\t'`` (indentation with tabs,
420
If this option is not specified, and the ConfigObj is initialised with a
421
dictionary, the indentation used in the output is the default one, that is,
424
If this option is not specified, and the ConfigObj is initialised with a
425
list of lines or a file, the indentation used in the first indented line is
426
selected and used in all output lines. If no input line is indented, no
427
output line will be either.
429
If this option *is* specified, the option value is used in the output
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``.
475
The ConfigObj is a subclass of an object called ``Section``, which is itself a
476
subclass of ``dict``, the builtin dictionary type. This means it also has
477
**all** the normal dictionary 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.
504
The public methods available on ConfigObj are :
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.
531
``write`` returns a list of lines. (Not ``'\n'`` terminated)
533
First the 'initial_comment' is written, then the config file, followed by the
534
'final_comment'. Comment lines and inline comments are written with each
542
validate(validator, preserve_errors=False)
548
# filename is the config file
549
# filename2 is the configspec
550
# (which could also be hardcoded into your program)
551
config = ConfigObj(filename, configspec=filename2)
553
from validate import Validator
555
test = config.validate(val)
561
The validate method uses the `validate
562
<http://www.voidspace.org.uk/python/validate.html>`__ module to do the
565
This method validates the ConfigObj against the configspec. By doing type
566
conversion as well, it can abstract away the config file altogether and present
567
the config *data* to your application (in the types it expects it to be).
569
If the ``configspec`` attribute of the ConfigObj is ``None``, it raises a
572
If the stringify_ attribute is set, this process will convert values to the
573
type defined in the configspec.
575
The validate method uses checks specified in the configspec and defined in the
576
``Validator`` object. It is very easy to extend.
578
The configspec looks like the config file, but instead of the value, you
579
specify the check (and any default value). See the validation_ section for
584
If your ConfigObj is only comprised of basic data types, then you can use
585
a function from the ConfigPersist.py_ module to auto-generate your
588
See `ConfigObj for Data Persistence`_.
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.
598
If a whole section passes then it is replaced with the value ``True``. If a
599
whole section fails, then it is replaced with the value ``False``.
601
If a value is missing, and there is no default in the check, then the check
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.
616
Mentioning Default Values
617
#########################
619
In the check in your configspec, you can specify a default to be used - by
620
using the ``default`` keyword. E.g. ::
622
key1 = integer(0, 30, default=15)
623
key2 = integer(default=15)
624
key3 = boolean(default=True)
625
key4 = option('Hello', 'Goodbye', 'Not Today', default='Not Today')
627
If the configspec check supplies a default and the value is missing in the
628
config, then the default will be set in your ConfigObj. (It is still passed to
629
the ``Validator`` so that type conversion can be done: this means the default
630
value must still pass the check.)
632
ConfigObj keeps a record of which values come from defaults, using the
633
``defaults`` attribute of sections_. Any key in this list isn't written out by
634
the ``write`` method. If a key is set from outside (even to the same value)
635
then it is removed from the ``defaults`` list.
639
Even if all the keys in a section are in the defaults list, the section
640
marker is still written out.
642
There is additionally a special case default value of ``None``. If you set the
643
default value to ``None`` and the value is missing, the value will always be
644
set to ``None``. As the other checks don't return ``None`` (unless you
645
implement your own that do), you can tell that this value came from a default
646
value (and was missing from the config file). It allows an easy way of
647
implementing optional values. Simply check (and ignore) members that are set
652
If stringify_ is ``False`` then ``default=None`` returns ``''`` instead of
653
``None``. This is because setting a value to a non-string raises an error
654
if stringify is unset.
656
The default value can be a list. See `List Values`_ for the way to do this.
658
Writing invalid default values is a *guaranteed* way of confusing your users.
659
Default values **must** pass the check.
661
Mentioning Repeated Sections
662
############################
664
In the configspec it is possible to cause *every* sub-section in a section to
665
be validated using the same configspec. You do this with a section in the
666
configspec called ``__many__``. Every sub-section in that section has the
667
``__many__`` configspec applied to it (without you having to explicitly name
670
If you define a ``__many__`` type section it must the only sub-section in that
671
section. Having a ``__many__`` *and* other sub-sections defined in the same
672
section will raise a ``RepeatSectionError``.
674
Your ``__many__`` section can have nested subsections, which can also include
675
``__many__`` type sections.
677
See `Repeated Sections`_ for examples.
683
If you just want to check if all members are present, then you can use the
684
``SimpleVal`` object that comes with ConfigObj. It only fails members if they
687
Write a configspec that has all the members you want to check for, but set
688
every section to ``''``.
695
test = config.validate(val)
705
A ConfigObj has the following attributes :
719
This doesn't include *comments*, *inline_comments*, *defaults*, or
720
*configspec*. These are actually attributes of Sections_.
722
It also has the following attributes as a result of parsing. They correspond to
723
options_ when the ConfigObj was created, but changing them has no effect.
732
ConfigObj can perform string interpolation in a *similar* way to
733
``ConfigParser``. See the interpolation_ section for full details.
735
If ``interpolate`` is set to ``False``, then interpolation is *not* done when
741
If this attribute is set (``True``) then the validate_ method changes the
742
values in the ConfigObj. These are turned back into strings when write_ is
745
If stringify is unset (``False``) then attempting to set a value to a non
746
string (or a list of strings) will raise a ``TypeError``.
751
If the initial config file *started* with the UTF8 Unicode signature (known
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.
763
This is a list of lines. If the ConfigObj is created from an existing file, it
764
will contain any lines of comments before the start of the members.
766
If you create a new ConfigObj, this will be an empty list.
768
The write method puts these lines before it starts writing out the members.
773
This is a list of lines. If the ConfigObj is created from an existing file, it
774
will contain any lines of comments after the last member.
776
If you create a new ConfigObj, this will be an empty list.
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.
827
The Config File Format
828
======================
830
You saw an example config file in the `Config Files`_ section. Here is a fuller
831
specification of the config files used and created by ConfigObj.
833
The basic pattern for keywords is : ::
837
keyword = value # inline comment
839
Both keyword and value can optionally be surrounded in quotes. The equals sign
840
is the only valid divider.
842
Values can have comments on the lines above them, and an inline comment after
843
them. This, of course, is optional. See the comments_ section for details.
845
If a keyword or value starts or ends with whitespace, or contains a quote mark
846
or comma, then it should be surrounded by quotes. Quotes are not necessary if
847
whitespace is surrounded by non-whitespace.
849
Values can also be lists. Lists are comma separated. You indicate a single
850
member list by a trailing comma. An empty list is shown by a single comma : ::
852
keyword1 = value1, value2, value3
853
keyword2 = value1, # a single member list
854
keyword3 = , # an empty list
856
Values that contain line breaks (multi-line values) can be surrounded by triple
857
quotes. These can also be used if a value contains both types of quotes. List
858
members cannot be surrounded by triple quotes : ::
860
keyword1 = ''' A multi line value
862
lines''' # with a comment
863
keyword2 = '''I won't be "afraid".'''
865
keyword3 = """ A multi line value
867
lines""" # with a comment
868
keyword4 = """I won't be "afraid"."""
872
There is no way of safely quoting values that contain both types of triple
875
A line that starts with a '#', possibly preceded by whitespace, is a comment.
877
New sections are indicated by a section marker line. That is the section name
878
in square brackets. Whitespace around the section name is ignored. The name can
879
be quoted with single or double quotes. The marker can have comments before it
880
and an inline comment after it : ::
883
[ section name 1 ] # first section
887
[ "section name 2" ] # second section
890
Any subsections (sections that are *inside* the current section) are
891
designated by repeating the square brackets before and after the section name.
892
The number of square brackets represents the nesting level of the sub-section.
893
Square brackets may be separated by whitespace; such whitespace, however, will
894
not be present in the output config written by the ``write`` method.
896
Indentation is not significant, but can be preserved. See the description of
897
the ``indent_type`` option, in the `ConfigObj specifications`_ chapter, for the
900
A *NestingError* will be raised if the number of the opening and the closing
901
brackets in a section marker is not the same, or if a sub-section's nesting
902
level is greater than the nesting level of it parent plus one.
904
In the outer section, single values can only appear before any sub-section.
905
Otherwise they will belong to the sub-section immediately before them. ::
916
# this is in section 1
921
# this is in sub section
926
# this is in section 1 again
931
# this is also in section 1, indentation is misleading here
937
When parsed, the above config file produces the following data structure :
944
'keyword1': 'value1',
945
'keyword2': 'value2',
947
'keyword1': 'value1',
948
'keyword2': 'value2',
950
'keyword1': 'value1',
951
'keyword2': 'value2',
953
'keyword1': 'value1',
954
'keyword2': 'value2',
958
'keyword1': 'value1',
959
'keyword2': 'value2',
962
'keyword1': 'value1',
963
'keyword2': 'value2',
970
Sections are ordered: note how the structure of the resulting ConfigObj is in
971
the same order as the original file.
976
Every section in a ConfigObj has certain properties. The ConfigObj itself also
977
has these properties, because it too is a section (sometimes called the *root
980
``Section`` is a subclass of the standard new-class dictionary, therefore it
981
has **all** the methods of a normal dictionary. This means you can ``update``
982
and ``clear`` sections.
986
You create a new section by assigning a member to be a dictionary.
988
The new ``Section`` is created *from* the dictionary, but isn't the same
989
thing as the dictionary. (So references to the dictionary you use to create
990
the section *aren't* references to the new section).
999
vals = {'key1': 'value 1',
1002
config['vals'] = vals
1003
config['vals'] == vals
1005
config['vals'] is vals
1010
If you now change ``vals``, the changes won't be reflected in ``config['vals']``.
1012
A section is ordered, following its ``scalars`` and ``sections``
1013
attributes documented below. This means that the following dictionary
1014
attributes return their results in order.
1018
More commonly known as ``for member in section:``.
1020
* '__repr__' and '__str__'
1022
Any time you print or display the ConfigObj.
1043
A reference to the main ConfigObj.
1047
A reference to the 'parent' section, the section that this section is a
1050
On the ConfigObj this attribute is a reference to itself. You can use this
1051
to walk up the sections, stopping when ``section.parent is section``.
1055
The nesting level of the current section.
1057
If you create a new ConfigObj and add sections, 1 will be added to the
1058
depth level between sections.
1062
This attribute is a list of scalars that came from default values. Values
1063
that came from defaults aren't written out by the ``write`` method.
1064
Setting any of these values in the section removes them from the defaults
1069
These attributes are normal lists, representing the order that members,
1070
single values and subsections appear in the section. The order will either
1071
be the order of the original config file, *or* the order that you added
1074
The order of members in this lists is the order that ``write`` creates in
1075
the config file. The ``scalars`` list is output before the ``sections``
1078
Adding or removing members also alters these lists. You can manipulate the
1079
lists directly to alter the order of members.
1083
If you alter the ``scalars``, ``sections``, or ``defaults`` attributes
1084
so that they no longer reflect the contents of the section, you will
1085
break your ConfigObj.
1087
See also the ``rename`` method.
1091
This is a dictionary of comments associated with each member. Each entry is
1092
a list of lines. These lines are written out before the member.
1096
This is *another* dictionary of comments associated with each member. Each
1097
entry is a string that is put inline with the member.
1101
The configspec attribute is a dictionary mapping scalars to *checks*. A
1102
check defines the expected type and possibly the allowed values for a
1105
The configspec has the same format as a config file, but instead of values
1106
it has a specification for the value (which may include a default value).
1107
The validate_ method uses it to check the config file makes sense. If a
1108
configspec is passed in when the ConfigObj is created, then it is parsed
1109
and broken up to become the ``configspec`` attribute of each section.
1111
If you didn't pass in a configspec, this attribute will be ``None`` on the
1112
root section (the main ConfigObj).
1114
You can set the configspec attribute directly on a section.
1116
See the validation_ section for full details of how to write configspecs.
1123
This method takes no arguments. It returns a deep copy of the section as a
1124
dictionary. All subsections will also be dictionaries, and list values will
1125
be copies, rather than references to the original [#]_.
1129
``rename(oldkey, newkey)``
1131
This method renames a key, without affecting its position in the sequence.
1133
It is mainly implemented for the ``encode`` and ``decode`` methods, which
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.
1171
This method can be used to transform values and names. See `walking a
1172
section`_ for examples and explanation.
1176
``decode(encoding)``
1178
This method decodes names and values into Unicode objects, using the
1183
``encode(encoding)``
1185
This method is the opposite of ``decode`` {sm;:!:}.
1187
It encodes names and values using the supplied encoding. If any of your
1188
names/values are strings rather than Unicode, Python will have to do an
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.
1239
The walk method allows you to call a function on every member/name.
1245
walk(function, raise_errors=True,
1246
call_on_sections=False, **keywargs):
1250
``walk`` is a method of the ``Section`` object. This means it is also a method
1253
It walks through every member and calls a function on the keyword and value. It
1254
walks recursively through subsections.
1256
It returns a dictionary of all the computed values.
1258
If the function raises an exception, the default is to propagate the error, and
1259
stop. If ``raise_errors=False`` then it sets the return value for that keyword
1260
to ``False`` instead, and continues. This is similar to the way validation_
1263
Your function receives the arguments ``(section, key)``. The current value is
1264
then ``section[key]`` [#]_. Any unrecognised keyword arguments you pass to
1265
walk, are passed on to the function.
1267
Normally ``walk`` just recurses into subsections. If you are transforming (or
1268
checking) names as well as values, then you want to be able to change the names
1269
of sections. In this case set ``call_on_sections`` to ``True``. Now, on
1270
encountering a sub-section, *first* the function is called for the *whole*
1271
sub-section, and *then* it recurses into it's members. This means your function
1272
must be able to handle receiving dictionaries as well as strings and lists.
1274
If you are using the return value from ``walk`` *and* ``call_on_sections``,
1275
note that walk discards the return value when it calls your function.
1279
You can use ``walk`` to transform the names of members of a section
1280
but you mustn't add or delete members.
1286
Examples that use the walk method are the ``encode`` and ``decode`` methods.
1287
They both define a function and pass it to walk. Because these functions
1288
transform names as well as values (from byte strings to Unicode) they set
1289
``call_on_sections=True``.
1291
To see how they do it, *read the source Luke* {sm;:cool:}.
1293
You can use this for transforming all values in your ConfigObj. For example
1294
you might like the nested lists from ConfigObj 3. This was provided by the
1295
listquote_ module. You could switch off the parsing for list values
1296
(``list_values=False``) and use listquote to parse every value.
1298
Another thing you might want to do is use the Python escape codes in your
1299
values. You might be *used* to using ``\n`` for line feed and ``\t`` for tab.
1300
Obviously we'd need to decode strings that come from the config file (using the
1301
escape codes). Before writing out we'll need to put the escape codes back in
1304
As an example we'll write a function to use with walk, that encodes or decodes
1305
values using the ``string-escape`` codec.
1307
The function has to take each value and set the new value. As a bonus we'll
1308
create one function that will do decode *or* encode depending on a keyword
1311
We don't want to work with section names, we're only transforming values, so
1312
we can leave ``call_on_sections`` as ``False``. This means the two datatypes we
1313
have to handle are strings and lists, we can ignore everything else. (We'll
1314
treat tuples as lists as well).
1316
We're not using the return values, so it doesn't need to return anything, just
1317
change the values if appropriate.
1323
def string_escape(section, key, encode=False):
1325
A function to encode or decode using the 'string-escape' codec.
1326
To be passed to the walk method of a ConfigObj.
1327
By default it decodes.
1328
To encode, pass in the keyword argument ``encode=True``.
1331
# is it a type we can work with
1332
# NOTE: for platforms where Python > 2.2
1333
# you can use basestring instead of (str, unicode)
1334
if not isinstance(val, (str, unicode, list, tuple)):
1337
elif isinstance(val, (str, unicode)):
1340
section[key] = val.decode('string-escape')
1342
section[key] = val.encode('string-escape')
1344
# it must be a list or tuple!
1345
# we'll be lazy and create a new list
1347
# we'll check every member of the list
1349
if isinstance(entry, (str, unicode)):
1351
newval.append(entry.decode('string-escape'))
1353
newval.append(entry.encode('string-escape'))
1355
newval.append(entry)
1357
section[key] = newval
1359
# assume we have a ConfigObj called ``config``
1362
config.walk(string_escape)
1365
# Because ``walk`` doesn't recognise the ``encode`` argument
1366
# it passes it to our function.
1367
config.walk(string_escape, encode=True)
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'}}}
1427
There are several places where ConfigObj may raise exceptions (other than
1430
1) If a configspec filename you pass in doesn't exist, or a config file
1431
filename doesn't exist *and* ``file_error=True``, an ``IOError`` will be
1434
2) If you try to set a non-string key, or a non string value when
1435
``stringify=False``, a ``TypeError`` will be raised.
1437
3) A badly built config file will cause parsing errors.
1439
4) A parsing error can also occur when reading a configspec.
1441
5) In string interpolation you can specify a value that doesn't exist, or
1442
create circular references (recursion).
1444
6) If you have a ``__many__`` repeated section with other section definitions
1445
(in a configspec), a ``RepeatSectionError`` will be raised.
1447
Number 5 (which is actually two different types of exceptions) is documented
1450
Number 6 is explained in the validation_ section.
1452
*This* section is about errors raised during parsing.
1454
The base error class is ``ConfigObjError``. This is a subclass of
1455
``SyntaxError``, so you can trap for ``SyntaxError`` without needing to
1456
directly import any of the ConfigObj exceptions.
1458
The following other exceptions are defined (all deriving from
1459
``ConfigObjError``) :
1463
This error indicates either a mismatch in the brackets in a section marker,
1464
or an excessive level of nesting.
1468
This error indicates that a line is badly written. It is neither a valid
1469
``key = value`` line, nor a valid section marker line, nor a comment line.
1471
* ``DuplicateError``
1473
The keyword or section specified already exists.
1475
* ``ConfigspecError``
1477
An error occured whilst parsing a configspec.
1479
When parsing a configspec, ConfigObj will stop on the first error it
1480
encounters. It will raise a ``ConfigspecError``. This will have an ``error``
1481
attribute, which is the actual error that was raised.
1483
Behavior when parsing a config file depends on the option ``raise_errors``.
1484
If ConfigObj encounters an error while parsing a config file:
1486
If ``raise_errors=True`` then ConfigObj will raise the appropriate error
1487
and parsing will stop.
1489
If ``raise_errors=False`` (the default) then parsing will continue to the
1490
end and *all* errors will be collected.
1492
In the second case a ``ConfigObjError`` is raised after parsing has stopped.
1493
The error raised has a ``config`` attribute, which is the parts of the
1494
ConfigObj that parsed successfully. It also has an attribute ``errors``, which
1495
is a list of *all* the errors raised. Each entry in the list is an instance of
1496
the appropriate error type. Each one has the following attributes (useful for
1497
delivering a sensible error message to your user) :
1499
* ``line``: the original line that caused the error.
1501
* ``line_number``: its number in the config file.
1503
* ``message``: the error message that accompanied the error.
1507
One wrongly written line could break the basic structure of your config
1508
file. This could cause every line after it to flag an error, so having a
1509
list of all the lines that caused errors may not be as useful as it sounds.
1516
Validation is done through a combination of the configspec_ and a ``Validator``
1517
object. For this you need *validate.py* [#]_. See downloading_ if you don't
1520
Validation can perform two different operations :
1522
1) Check that a value meets a specification. For example, check that a value
1523
is an integer between one and six, or is a choice from a specific set of
1526
2) It can convert the value into the type required. For example, if one of
1527
your values is a port number, validation will turn it into an integer for
1530
So validation can act as a transparent layer between the datatypes of your
1531
application configuration (boolean, integers, floats, etc) and the text format
1532
of your config file.
1537
The ``validate`` method checks members against an entry in the configspec. Your
1538
configspec therefore resembles your config file, with a check for every member.
1540
In order to perform validation you need a ``Validator`` object. This has
1541
several useful built-in check functions. You can also create your own custom
1542
functions and register them with your Validator object.
1544
Each check is the name of one of these functions, including any parameters and
1545
keyword arguments. The configspecs look like function calls, and they map to
1548
The basic datatypes that an un-extended Validator can test for are :
1550
* boolean values (True and False)
1551
* integers (including minimum and maximum values)
1552
* floats (including min and max)
1553
* strings (including min and max length)
1554
* IP addresses (v4 only)
1556
It can also handle lists of these types and restrict a value to being one from
1559
An example configspec is going to look something like : ::
1561
port = integer(0, 100)
1562
user = string(max=25)
1563
mode = option('quiet', 'loud', 'silent')
1565
You can specify default values, and also have the same configspec applied to
1566
several sections. This is called `repeated sections`_.
1568
For full details on writing configspecs, please refer to the `validate.py
1573
Your configspec is read by ConfigObj in the same way as a config file.
1575
That means you can do interpolation *within* your configspec.
1577
In order to allow this, checks in the 'DEFAULT' section (of the root level
1578
of your configspec) are *not* used.
1580
.. _validate.py documentation: http://www.voidspace.org.uk/python/validate.html
1585
By default, validation does type conversion. This means that if you specify
1586
``integer`` as the check, then calling validate_ will actually change the value
1587
to an integer (so long as the check succeeds).
1589
It also means that when you call the write_ method, the value will be converted
1590
back into a string using the ``str`` function.
1592
To switch this off, and leave values as strings after validation, you need to
1593
set the stringify_ attribute to ``False``. If this is the case, attempting to
1594
set a value to a non-string will raise an error.
1599
You can set a default value in your check. If the value is missing from the
1600
config file then this value will be used instead. This means that your user
1601
only has to supply values that differ from the defaults.
1603
If you *don't* supply a default then for a value to be missing is an error,
1604
and this will show in the `return value`_ from validate.
1606
Additionally you can set the default to be ``None``. This means the value will
1607
be set to ``None`` (the object) *whichever check is used*. (It will be set to
1608
``''`` rather than ``None`` if stringify_ is ``False``). You can use this
1609
to easily implement optional values in your config files. ::
1611
port = integer(0, 100, default=80)
1612
user = string(max=25, default=0)
1613
mode = option('quiet', 'loud', 'silent', default='loud')
1614
nick = string(default=None)
1618
Because the default goes through type conversion, it also has to pass the
1621
Note that ``default=None`` is case sensitive.
1627
It's possible that you will want to specify a list as a default value. To avoid
1628
confusing syntax with commas and quotes you use a list constructor to specify
1629
that keyword arguments are lists. This includes the ``default`` value. This
1630
makes checks look something like : ::
1632
checkname(default=list('val1', 'val2', 'val3'))
1634
This works with all keyword arguments, but is most useful for default values.
1640
Repeated sections are a way of specifying a configspec for a section that
1641
should be applied to *all* subsections in the same section.
1643
The easiest way of explaining this is to give an example. Suppose you have a
1644
config file that describes a dog. That dog has various attributes, but it can
1645
also have many fleas. You don't know in advance how many fleas there will be,
1646
or what they will be called, but you want each flea validated against the same
1649
We can define a section called *fleas*. We want every flea in that section
1650
(every sub-section) to have the same configspec applied to it. We do this by
1651
defining a single section called ``__many__``. ::
1654
name = string(default=Rover)
1655
age = float(0, 99, default=0)
1660
bloodsucker = boolean(default=True)
1661
children = integer(default=10000)
1662
size = option(small, tiny, micro, default=tiny)
1664
Every flea on our dog will now be validated using the ``__many__`` configspec.
1666
If you define another sub-section in a section *as well as* a ``__many__`` then
1667
you will get an error.
1669
``__many__`` sections can have sub-sections, including their own ``__many__``
1670
sub-sections. Defaults work in the normal way in repeated sections.
1673
Validation and Interpolation
1674
----------------------------
1676
String interpolation and validation don't play well together. When validation
1677
changes type it sets the value. If the value uses interpolation, then the
1678
interpolation reference would normally be overwritten. Calling ``write`` would
1679
then use the absolute value and the interpolation reference would be lost.
1681
As a compromise - if the value is unchanged by validation then it is not reset.
1682
This means strings that pass through validation unmodified will not be
1683
overwritten. If validation changes type - the value has to be overwritten, and
1684
any interpolation references are lost {sm;:-(}.
1689
You may not need a full validation process, but still want to check if all the
1690
expected values are present.
1692
Provided as part of the ConfigObj module is the ``SimpleVal`` object. This has
1693
a dummy ``test`` method that always passes.
1695
The only reason a test will fail is if the value is missing. The return value
1696
from ``validate`` will either be ``True``, meaning all present, or a dictionary
1697
with ``False`` for all missing values/sections.
1699
To use it, you still need to pass in a valid configspec when you create the
1700
ConfigObj, but just set all the values to ``''``. Then create an instance of
1701
``SimpleVal`` and pass it to the ``validate`` method.
1703
As a trivial example if you had the following config file : ::
1705
# config file for an application
1709
top_level_domain = org.uk
1711
You would write the following configspec : ::
1716
top_level_domain = ''
1722
config = Configobj(filename, configspec=configspec)
1724
test = config.validate(val)
1726
print 'All values present.'
1728
print 'No values present!'
1731
if test[entry] == False:
1732
print '"%s" missing.' % entry
1740
ConfigObj allows string interpolation *similar* to the way ``ConfigParser``
1742
You specify a value to be substituted by including ``%(name)s`` in the value.
1744
Interpolation checks first the 'DEFAULT' sub-section of the current section to
1745
see if ``name`` is the key to a value. ('name' is case sensitive).
1747
If it doesn't find it, next it checks the 'DEFAULT' section of the parent
1748
section, last it checks the 'DEFAULT' section of the main section.
1750
If the value specified isn't found then a ``MissingInterpolationOption`` error
1751
is raised (a subclass of ``ConfigObjError``).
1753
If it is found then the returned value is also checked for substitutions. This
1754
allows you to make up compound values (for example directory paths) that use
1755
more than one default value. It also means it's possible to create circular
1756
references. If after ten replacements there are still values to substitute, an
1757
``InterpolationDepthError`` is raised.
1759
Both of these errors are subclasses of ``InterpolationError``, which is a
1760
subclass of ``ConfigObjError``.
1762
String interpolation and validation don't play well together. This is because
1763
validation overwrites values - and so may erase the interpolation references.
1764
See `Validation and Interpolation`_. (This can only happen if validation
1765
has to *change* the value).
1771
Any line that starts with a '#', possibly preceded by whitespace, is a comment.
1773
If a config file starts with comments then these are preserved as the
1776
If a config file ends with comments then these are preserved as the
1779
Every key or section marker may have lines of comments immediately above it.
1780
These are saved as the ``comments`` attribute of the section. Each member is a
1783
You can also have a comment inline with a value. These are saved as the
1784
``inline_comments`` attribute of the section, with one entry per member of the
1787
Subsections (section markers in the config file) can also have comments.
1789
See `Section Attributes`_ for more on these attributes.
1791
These comments are all written back out by the ``write`` method.
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
1866
Backwards Compatibility
1867
=======================
1869
There have been a lot of changes since ConfigObj 3. The core parser is now
1870
based on regular expressions, and is a lot faster and smaller. There is now no
1871
difference in the way we treat flat files and non-flatfiles, that is, no empty
1872
sections. This means some of the code can be a lot simpler, less code does
1873
more of the work [#]_.
1875
There have been other simplifications: for example we only have eight options
1876
instead of seventeen.
1878
Most config files created for ConfigObj 3 will be read with no changes and many
1879
programs will work without having to alter code. Some of the changes do break
1880
backwards compatibility: for example, code that uses the previous options will
1881
now raise an error. It should be very easy to fix these, though.
1883
Below is a list of all the changes that affect backwards compatibility. This
1884
doesn't include details of method signatures that have changed, because almost
1887
Incompatible Changes
1888
--------------------
1890
(I have removed a lot of needless complications: this list is probably not
1891
conclusive, many option/attribute/method names have changed.)
1895
The only valid divider is '='.
1897
Line continuations with ``\`` removed.
1899
No recursive lists in values.
1903
No distinction between flatfiles and non flatfiles.
1905
Change in list syntax: use commas to indicate list, not parentheses (square
1906
brackets and parentheses are no longer recognised as lists).
1908
';' is no longer valid for comments, and no multiline comments.
1910
No attribute-style access to values.
1912
Empty values not allowed: use '' or "".
1914
In ConfigObj 3, setting a non-flatfile member to ``None`` would initialise it
1915
as an empty section.
1917
The escape entities '&mjf-lf;' and '&mjf-quot;' have gone, replaced by triple
1918
quote, multiple line values.
1920
The ``newline``, ``force_return``, and ``default`` options have gone.
1922
``fileerror`` and ``createempty`` options have become ``file_error`` and
1925
Partial configspecs (for specifying the order members should be written out,
1926
and which should be present) have gone. The configspec is no longer used to
1927
specify order for the ``write`` method.
1929
Exceeding the maximum depth of recursion in string interpolation now raises an
1930
error ``InterpolationDepthError``.
1932
Specifying a value for interpolation which doesn't exist now raises a
1933
``MissingInterpolationOption`` error (instead of merely being ignored).
1935
The ``writein`` method has been removed.
1937
The comments attribute is now a list (``inline_comments`` equates to the old
1938
comments attribute).
1943
ConfigObj 3 is now deprecated in favour of ConfigObj 4. I can fix bugs in
1944
ConfigObj 3 if needed, though.
1946
For anyone who still needs it, you can download it here: `ConfigObj 3.3.1`_
1948
You can read the old docs at : `ConfigObj 3 Docs`_
1950
.. _ConfigObj 3.3.1: http://www.voidspace.org.uk/cgi-bin/voidspace/downman.py?file=configobj3.zip
1951
.. _ConfigObj 3 Docs: http://www.voidspace.org.uk/python/configobj3.html
1957
ConfigObj 4 is written by (and copyright) `Michael Foord`_ and
1960
Particularly thanks to Nicola Larosa for help on the config file spec, the
1961
validation system and the doctests.
1963
*validate.py* was originally written by Michael Foord and `Mark Andrews`_.
1965
Thanks to others for input and bugfixes.
1971
ConfigObj, and related files, are licensed under the BSD license. This is a
1972
very unrestrictive license, but it comes with the usual disclaimer. This is
1973
free software: test it, break it, just don't blame us if it eats your data !
1974
Of course if it does, let us know and we'll fix the problem so it doesn't
1975
happen to anyone else {sm;:-)}. ::
1977
Copyright (c) 2004 - 2006, Michael Foord & Nicola Larosa
1978
All rights reserved.
1980
Redistribution and use in source and binary forms, with or without
1981
modification, are permitted provided that the following conditions are
1985
* Redistributions of source code must retain the above copyright
1986
notice, this list of conditions and the following disclaimer.
1988
* Redistributions in binary form must reproduce the above
1989
copyright notice, this list of conditions and the following
1990
disclaimer in the documentation and/or other materials provided
1991
with the distribution.
1993
* Neither the name of Michael Foord nor Nicola Larosa
1994
may be used to endorse or promote products derived from this
1995
software without specific prior written permission.
1997
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
1998
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
1999
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
2000
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
2001
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
2002
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
2003
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
2004
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
2005
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
2006
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
2007
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
2009
You should also be able to find a copy of this license at : `BSD License`_
2011
.. _BSD License: http://www.voidspace.org.uk/python/license.shtml
2017
Fix any bugs (and resolvable issues).
2019
Do an example for the 'walk' which removes uniform indentation in multiline
2022
When initialising a section from a ConfigObj *or* an ``OrderedDictionary``
2023
we could preserve ordering.
2025
Add an *odict* method which returns an ``OrderedDictionary``.
2033
Please file any bug reports to `Michael Foord`_ or the **ConfigObj**
2036
You can't have a keyword with the same name as a section (in the same section).
2037
They are both dictionary keys, so they would overlap.
2039
Interpolation checks first the 'DEFAULT' sub-section of the current section,
2040
next it checks the 'DEFAULT' section of the parent section, last it checks the
2041
'DEFAULT' section of the main section.
2043
Logically a 'DEFAULT' section should apply to all subsections of the *same
2044
parent*: this means that checking the 'DEFAULT' sub-section in the *current
2045
section* is not necessarily logical ?
2047
Does it matter that we don't support the ':' divider, which is supported by
2050
String interpolation and validation don't play well together. See
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.
2061
This is an abbreviated changelog showing the major releases up to version 4.
2062
From version 4 it lists all releases and changes. *More* data on individual
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``.
2137
2005/10/17 - Version 4.0.0
2138
--------------------------
2140
**ConfigObj 4.0.0 Final**
2142
Fixed bug in ``setdefault``. When creating a new section with setdefault the
2143
reference returned would be to the dictionary passed in *not* to the new
2144
section. Bug fixed and behaviour documented.
2146
Obscure typo/bug fixed in ``write``. Wouldn't have affected anyone though.
2148
2005/09/09 - Version 4.0.0 beta 5
2149
---------------------------------
2151
Removed ``PositionError``.
2153
Allowed quotes around keys as documented.
2155
Fixed bug with commas in comments. (matched as a list value)
2157
2005/09/07 - Version 4.0.0 beta 4
2158
---------------------------------
2160
Fixed bug in ``__delitem__``. Deleting an item no longer deletes the
2161
``inline_comments`` attribute.
2163
Fixed bug in initialising ConfigObj from a ConfigObj.
2165
Changed the mailing list address.
2167
2005/08/28 - Version 4.0.0 beta 3
2168
---------------------------------
2170
Interpolation is switched off before writing out files.
2172
Fixed bug in handling ``StringIO`` instances. (Thanks to report from
2173
"Gustavo Niemeyer" <gustavo@niemeyer.net>)
2175
Moved the doctests from the ``__init__`` method to a separate function.
2176
(For the sake of IDE calltips).
2178
2005/08/25 - Version 4.0.0 beta 2
2179
---------------------------------
2181
Amendments to *validate.py*.
2185
2005/08/21 - Version 4.0.0 beta 1
2186
---------------------------------
2188
Reads nested subsections to any depth.
2192
Simplified options and methods.
2196
Faster, smaller, and better parser.
2198
Validation greatly improved. Includes:
2204
Improved error handling.
2206
Plus lots of other improvements {sm;:grin:}.
2208
2004/05/24 - Version 3.0.0
2209
--------------------------
2211
Several incompatible changes: another major overhaul and change. (Lots of
2212
improvements though).
2214
Added support for standard config files with sections. This has an entirely
2215
new interface: each section is a dictionary of values.
2217
Changed the update method to be called writein: update clashes with a dict
2220
Made various attributes keyword arguments, added several.
2222
Configspecs and orderlists have changed a great deal.
2224
Removed support for adding dictionaries: use update instead.
2226
Now subclasses a new class called caselessDict. This should add various
2227
dictionary methods that could have caused errors before.
2229
It also preserves the original casing of keywords when writing them back out.
2231
Comments are also saved using a ``caselessDict``.
2233
Using a non-string key will now raise a ``TypeError`` rather than converting
2236
Added an exceptions keyword for *much* better handling of errors.
2238
Made ``creatempty=False`` the default.
2240
Now checks indict *and* any keyword args. Keyword args take precedence over
2243
``' ', ':', '=', ','`` and ``'\t'`` are now all valid dividers where the
2244
keyword is unquoted.
2246
ConfigObj now does no type checking against configspec when you set items.
2248
delete and add methods removed (they were unnecessary).
2250
Docs rewritten to include all this gumph and more; actually ConfigObj is
2251
*really* easy to use.
2253
Support for stdout was removed.
2255
A few new methods added.
2257
Charmap is now incorporated into ConfigObj.
2259
2004/03/14 - Version 2.0.0 beta
2260
-------------------------------
2262
Re-written it to subclass dict. My first forays into inheritance and operator
2265
The config object now behaves like a dictionary.
2267
I've completely broken the interface, but I don't think anyone was really
2270
This new version is much more 'classy' {sm;:wink:}
2272
It will also read straight from/to a filename and completely parse a config
2273
file without you *having* to supply a config spec.
2275
Uses listparse, so can handle nested list items as values.
2277
No longer has getval and setval methods: use normal dictionary methods, or add
2280
2004/01/29 - Version 1.0.5
2281
--------------------------
2283
Version 1.0.5 has a couple of bugfixes as well as a couple of useful additions
2284
over previous versions.
2286
Since 1.0.0 the buildconfig function has been moved into this distribution,
2287
and the methods reset, verify, getval and setval have been added.
2289
A couple of bugs have been fixed.
2294
ConfigObj originated in a set of functions for reading config files in the
2295
atlantibots_ project. The original functions were written by Rob McNeur...
2297
.. _atlantibots: http://www.voidspace.org.uk/atlantibots
2304
.. [#] 253 of them, at the time of writing.
2306
.. [#] And if you discover any bugs, let us know. We'll fix them quickly.
2308
.. [#] If you specify a filename that doesn't exist, ConfigObj will assume you
2309
are creating a new one. See the *create_empty* and *file_error* options_.
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.
2317
.. [#] Except we don't support the RFC822 style line continuations, nor ':' as
2320
.. [#] For a file object that will depend what mode it was opened with. You
2321
can read *and* write to a ``StringIO`` instance, but not always to a
2322
``cStringIO`` instance.
2324
.. [#] A side effect of this is that it enables you to copy a ConfigObj :
2330
# only copies members
2331
# not attributes/comments
2332
config2 = ConfigObj(config1)
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.
2341
.. [#] Other than lists of strings.
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.
2347
.. [#] The dict method doesn't actually use the deepcopy mechanism. This means
2348
if you add nested lists (etc) to your ConfigObj, then the dictionary
2349
returned by dict may contain some references. For all *normal* ConfigObjs
2350
it will return a deepcopy.
2352
.. [#] Passing ``(section, key)`` rather than ``(value, key)`` allows you to
2353
change the value by setting ``section[key] = newval``. It also gives you
2354
access to the *rename* method of the section.
2356
.. [#] Minimum required version of *validate.py* 0.2.0 .
2358
.. [#] There's nothing to stop you decoding the whole config file to Unicode
2361
.. [#] It also makes ConfigObj a lot simpler to *use*.
2365
Rendering this document with docutils also needs the
2366
textmacros module and the PySrc CSS stuff. See
2367
http://www.voidspace.org.uk/python/firedrop2/textmacros.shtml
2371
<div align="center">
2372
<a href="http://sourceforge.net/donate/index.php?group_id=123265">
2373
<img src="http://images.sourceforge.net/images/project-support.jpg" width="88" height="32" border="0" alt="Support This Project" />
2375
<a href="http://sourceforge.net">
2376
<img src="http://sourceforge.net/sflogo.php?group_id=123265&type=1" width="88" height="31" border="0" alt="SourceForge.net Logo" />
2379
<a href="http://www.python.org">
2380
<img src="images/powered_by_python.jpg" width="602" height="186" border="0" />
2382
<a href="http://www.opensource.org">
2383
<img src="images/osi-certified-120x100.gif" width="120" height="100" border="0" />
2384
<br /><strong>Certified Open Source</strong>
2387
<script type="text/javascript" language="JavaScript">var site="s16atlantibots"</script>
2388
<script type="text/javascript" language="JavaScript1.2" src="http://s16.sitemeter.com/js/counter.js?site=s16atlantibots"></script>
2390
<a href="http://s16.sitemeter.com/stats.asp?site=s16atlantibots">
2391
<img src="http://s16.sitemeter.com/meter.asp?site=s16atlantibots" alt="Site Meter" border=0 />
2396
.. _listquote: http://www.voidspace.org.uk/python/modules.shtml#listquote
2397
.. _Michael Foord: http://www.voidspace.org.uk/index2.shtml
2398
.. _Nicola Larosa: http://www.teknico.net
2399
.. _Mark Andrews: http://www.la-la.com
added
removed
bzrlib/util/configobj/docs/configobj.txt
