~bzr-pqm/bzr/bzr.dev

----------------------------------------

 

:Authors: Michael Foord, Nicola Larosa

:Homepage: `ConfigObj Homepage`_

:Sourceforge: Sourceforge_

:License: `BSD License`_

straightforward programmer's interface and a simple syntax for config files.

It has lots of other features though :

 

* Nested sections (subsections), to any level

* List values

* Multiple line values

* String interpolation (substitution)

* Integrated with a powerful validation system

 

 

* All comments in the file are preserved

* The order of keys/sections is preserved

* No external dependencies

 

For support and bug reports please use the ConfigObj `Mailing List`_.

 

.. hint::

 

    

    The code from that article is available as ConfigPersist.py_.

 

.. _ConfigObj for Data Persistence: http://www.voidspace.org.uk/python/articles/configobj_for_data_persistence.shtml

.. _ConfigPersist.py: http://www.voidspace.org.uk/python/configpersist.html

 

Downloading

===========

 

{sm;:-)}

 

You can get ConfigObj in the following ways :

Projects`_.

 

.. _configobj.py: http://www.voidspace.org.uk/cgi-bin/voidspace/downman.py?file=configobj.py

.. _validate.py: http://www.voidspace.org.uk/cgi-bin/voidspace/downman.py?file=validate.py

.. _API Docs: http://www.voidspace.org.uk/python/configobj-api/

.. _this document:

.. _pythonutils: http://www.voidspace.org.uk/python/pythonutils.html

.. _Voidspace Python Projects: http://www.voidspace.org.uk/python

 

Getting Started

===============

 

    # The 'final_comment'

    # Which also may be several lines

 

ConfigObj specifications

========================

 

  the options_ ``file_error`` and ``create_empty``. The filename will be

  preserved as the ``filename`` attribute. This can be changed at any time.

 

  ``filename`` attribute of your ConfigObj will be ``None``.

 

 

* A dictionary. You can initialise a ConfigObj from a dictionary [#]_. The

  ``filename`` attribute of your ConfigObj will be ``None``. All keys must be

 

    If ``True`` (the default) then list values are possible. If ``False``, the

    values are not parsed for lists.

 

 

* 'create_empty': ``False``

 

    If this option *is* specified, the option value is used in the output

    config, overriding the type of indentation in the input config (if any).

 

Methods

-------

 

subclass of ``dict``, the builtin dictionary type. This means it also has

**all** the normal dictionary methods.

 

 

The public methods available on ConfigObj are :

 

write

~~~~~

 

 

``None``

    ``write`` returns a list of lines. (Not ``'\n'`` terminated)

 

First the 'initial_comment' is written, then the config file, followed by the

'final_comment'. Comment lines and inline comments are written with each

key/value.

validate

~~~~~~~~

 

.. raw:: html

 

    {+coloring}

 

    {-coloring}

 

This method validates the ConfigObj against the configspec. By doing type

conversion as well, it can abstract away the config file altogether and present

the config *data* to your application (in the types it expects it to be).

    

    See `ConfigObj for Data Persistence`_.

 

Return Value

############

 

 

If a whole section passes then it is replaced with the value ``True``. If a 

whole section fails, then it is replaced with the value ``False``.

If a value is missing, and there is no default in the check, then the check 

automatically fails.

 

Mentioning Default Values

#########################

 

    ``None``. This is because setting a value to a non-string raises an error

    if stringify is unset.

 

Mentioning Repeated Sections

############################

 

 

See `Repeated Sections`_ for examples.

 

Mentioning SimpleVal

####################

 

 

    {-coloring}

 

Attributes

----------

 

* BOM

* initial_comment

* final_comment

 

.. note::

 

* raise_errors

* create_empty

* file_error

 

interpolate

~~~~~~~~~~~

~~~

 

If the initial config file *started* with the UTF8 Unicode signature (known

 

initial_comment

~~~~~~~~~~~~~~~

The ``write`` method puts these lines after it finishes writing out the

members.

 

The Config File Format

======================

 

Section Methods

---------------

 

 

    This method takes no arguments. It returns a deep copy of the section as a

    dictionary. All subsections will also be dictionaries, and list values will

    be copies, rather than references to the original [#]_.

 

 

    ``rename(oldkey, newkey)``

 

    It is mainly implemented for the ``encode`` and ``decode`` methods, which

    provide some Unicode support.

 

 

    This method can be used to transform values and names. See `walking a

    section`_ for examples and explanation.

 

 

    ``decode(encoding)``

 

    This method decodes names and values into Unicode objects, using the

    supplied encoding.

 

 

    ``encode(encoding)``

 

 

    It encodes names and values using the supplied encoding. If any of your

    names/values are strings rather than Unicode, Python will have to do an

Walking a Section

-----------------

 

If you are using the return value from ``walk`` *and* ``call_on_sections``,

note that walk discards the return value when it calls your function.

 

Examples

--------

 

 

You can use this for transforming all values in your ConfigObj. For example

you might like the nested lists from ConfigObj 3. This was provided by the

(``list_values=False``) and use listquote to parse every value.

 

Another thing you might want to do is use the Python escape codes in your

 

    {-coloring}

 

Exceptions

==========

 

    raised.

 

2) If you try to set a non-string key, or a non string value when

 

3) A badly built config file will cause parsing errors.

 

    list of all the lines that caused errors may not be as useful as it sounds.

    {sm;:-(}.

 

Validation

==========

 

For full details on writing configspecs, please refer to the `validate.py

documentation`_.

 

.. _validate.py documentation: http://www.voidspace.org.uk/python/validate.html

 

Type Conversion

 

    Note that ``default=None`` is case sensitive.

 

Repeated Sections

-----------------

 

 

    {-coloring}

 

Interpolation

=============

 

See `Validation and Interpolation`_. (This can only happen if validation

has to *change* the value).

 

Comments

========

 

 

These comments are all written back out by the ``write`` method.

 

 

Backwards Compatibility

=======================

 

The ``newline``, ``force_return``, and ``default`` options have gone.

 

``fileerror`` and ``createempty`` options have become ``file_error`` and

``create_empty``.

 

.. _ConfigObj 3.3.1: http://www.voidspace.org.uk/cgi-bin/voidspace/downman.py?file=configobj3.zip

.. _ConfigObj 3 Docs: http://www.voidspace.org.uk/python/configobj3.html

 

CREDITS

=======

 

 

Thanks to others for input and bugfixes.

 

LICENSE

=======

 

Of course if it does, let us know and we'll fix the problem so it doesn't

happen to anyone else {sm;:-)}. ::

 

    All rights reserved.

 

    Redistribution and use in source and binary forms, with or without

 

You should also be able to find a copy of this license at : `BSD License`_

 

 

TODO

====

When initialising a section from a ConfigObj *or* an ``OrderedDictionary``

we could preserve ordering.

 

 

ISSUES

======

 

.. note::

 

    `Mailing List`_.

 

You can't have a keyword with the same name as a section (in the same section).

parent*: this means that checking the 'DEFAULT' sub-section in the *current

section* is not necessarily logical ?

 

Does it matter that we don't support the ':' divider, which is supported by

``ConfigParser`` ?

 

String interpolation and validation don't play well together. See 

`Validation and Interpolation`_.

 

CHANGELOG

=========

 

From version 4 it lists all releases and changes. *More* data on individual

changes may be found in the source code.

 

2005/10/17 - Version 4.0.0

--------------------------

 

Footnotes

=========

 

 

.. [#] And if you discover any bugs, let us know. We'll fix them quickly.

 

.. [#] If you specify a filename that doesn't exist, ConfigObj will assume you

    are creating a new one. See the *create_empty* and *file_error* options_.

 

 

.. [#] Except we don't support the RFC822 style line continuations, nor ':' as

    a divider.

 

.. [#] A side effect of this is that it enables you to copy a ConfigObj :

 

 

    The order of values and sections will not be preserved, though.

 

.. [#] Other than lists of strings.

 

 

.. [#] The dict method doesn't actually use the deepcopy mechanism. This means

    if you add nested lists (etc) to your ConfigObj, then the dictionary

    change the value by setting ``section[key] = newval``. It also gives you

    access to the *rename* method of the section.

 

.. [#] Minimum required version of *validate.py* 0.2.0 .

 

.. [#] There's nothing to stop you decoding the whole config file to Unicode

        <br />

        <a href="http://www.python.org">

            <img src="images/powered_by_python.jpg" width="602" height="186" border="0" />

        <a href="http://www.opensource.org">

            <img src="images/osi-certified-120x100.gif" width="120" height="100" border="0" />

            <br /><strong>Certified Open Source</strong>

                <img src="http://s16.sitemeter.com/meter.asp?site=s16atlantibots" alt="Site Meter" border=0 />

            </a>

        </noscript>

    </div>

 

.. _listquote: http://www.voidspace.org.uk/python/modules.shtml#listquote

.. _Nicola Larosa: http://www.teknico.net

.. _Mark Andrews: http://www.la-la.com