~bzr-pqm/bzr/bzr.dev

:Version: ConfigObj 4.5.2

:Date: 2008/02/24

:Development: `SVN Repository`_

.. _SVN Repository: http://svn.pythonutils.python-hosting.com

 

 

    

* When writing out config files, ConfigObj preserves all comments and the order of members and sections

* Many useful methods and options for working with configuration files (like the 'reload' method)

* Full Unicode support

The current version is **4.5.2**, dated 24th February 2008. ConfigObj 4 is

    This also contains validate.py_  and `this document`_.

*configobj.zip* also contains `this document`_.

 

* You can view `this document`_ online at the `ConfigObj Homepage`_.

 

 

Development Version

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

 

It is sometimes possible to get the latest *development version* of ConfigObj

from the `Subversion Repository <http://svn.pythonutils.python-hosting.com/trunk/pythonutils/>`_.

 

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

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

 

 

 

ConfigObj in the Real World

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

    

**ConfigObj** is widely used. Projects using it include:

 

* `Bazaar <http://bazaar-ng.org>`_.

 

    Bazaar is a Python distributed {acro;VCS;Version Control System}.

    ConfigObj is used to read ``bazaar.conf`` and ``branches.conf``.

 

* `Turbogears <http://www.turbogears.org/>`_

 

    Turbogears is a web application framework.

 

* `Chandler <http://chandler.osafoundation.org/>`_

 

   A Python and `wxPython <http://www.wxpython.org>`_ 

   {acro;PIM;Personal Information Manager}, being developed by the 

   `OSAFoundation <http://www.osafoundation.org/>`_.

 

* `matplotlib <http://matplotlib.sourceforge.net/>`_

 

        A 2D plotting library.

 

* `IPython <http://ipython.scipy.org/moin/>`_

 

    IPython is an enhanced interactive Python shell. IPython uses ConfigObj in a module called 'TConfig' that combines it with enthought `Traits <http://code.enthought.com/traits/>`_: `tconfig <http://ipython.scipy.org/ipython/ipython/browser/ipython/branches/saw/sandbox/tconfig>`_.

    

* `Elisa - the Fluendo Mediacenter <http://elisa.fluendo.com/>`_    

    

    Elisa is an open source cross-platform media center solution designed to be simple for people not particularly familiar with computers.

 

 

 

 

 

        unquoted when reading and writing.

    when values are fetched. See the `String Interpolation`_ section for more details.

* 'indent_type': ``'    '``

    Indentation is not significant; it can however be present in the input and

    output config. Any combination of tabs and spaces may be used: the string

    will be repeated for each level of indentation. Typical values are: ``''``

    (no indentation), ``'    '`` (indentation with four spaces, the default),

    ``'\t'`` (indentation with one tab).

    four spaces.

    the Python default encoding (``sys.defaultencoding`` - usually ASCII) is

* 'unrepr': ``False``

 

    The ``unrepr`` option reads and writes files in a different mode. This

    allows you to store and retrieve the basic Python data-types using config

    files.

    

    This uses Python syntax for lists and quoting. See `unrepr mode`_ for the

    full details.

 

* 'write_empty_values': ``False`` 

 

    If ``write_empty_values`` is ``True``, empty strings are written as

    empty values. See `Empty Values`_ for more details.

 

* 'restore_default'

* 'restore_defaults'

* 'walk'

* 'merge'

* 'dict'

* 'as_bool'

* 'as_float'

* 'as_int'

    different from the default. You can use configspecs and validation to

    achieve the same thing of course.

* 'reset'

* 'reload'

 

 

    validate(validator, preserve_errors=False, copy=False)

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

    The system of configspecs can seem confusing at first, but is actually

    quite simple and powerful. For a concrete example of how to use it, you may

    find this blog entry helpful :

    `Transforming Values with ConfigObj <http://www.voidspace.org.uk/python/weblog/arch_d7_2006_03_04.shtml#e257>`_.

 

 

The ``copy`` parameter fills in missing values from the configspec (default

values), *without* marking the values as defaults. It also causes comments to

be copied from the configspec into the config file. This allows you to use a

configspec to create default config files. (Normally default values aren't

written out by the ``write`` method.)

 

As of ConfigObj 4.3.0 you can also pass in a ConfigObj instance as your

configspec. This is especially useful if you need to specify the encoding of

your configspec file. When you read your configspec file, you *must* specify

``list_values=False``.

 

.. raw:: html

 

    {+coloring}

    from configobj import ConfigObj

    configspec = ConfigObj(configspecfilename, encoding='UTF8',

                           list_values=False)

    config = ConfigObj(filename, configspec=configspec)

    {-coloring}

 

 

Mentioning copy Mode

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

 

As discussed in `Mentioning Default Values`_, you can use a configspec to

supply default values. These are marked in the ConfigObj instance as defaults,

and *not* written out by the ``write`` mode. This means that your users only

need to supply values that are different from the defaults.

 

This can be inconvenient if you *do* want to write out the default values,

for example to write out a default config file.

 

If you set ``copy=True`` when you call validate, then no values are marked as

defaults. In addition, all comments from the configspec are copied into

your ConfigObj instance. You can then call ``write`` to create your config

file.

There is a limitation with this. In order to allow `String Interpolation`_ to work

within configspecs, ``DEFAULT`` sections are not processed by

validation; even in copy mode.

 

 

reload

~~~~~~

 

If a ConfigObj instance was loaded from the filesystem, then this method will reload it. It

will also reuse any configspec you supplied at instantiation (including reloading it from

the filesystem if you passed it in as a filename).

 

If the ConfigObj does not have a filename attribute pointing to a file, then a ``ReloadError`` 

will be raised.

 

 

reset

~~~~~

 

This method takes no arguments and doesn't return anything. It restores a ConfigObj

instance to a freshly created state.

 

 

* unrepr

* write_empty_values

* newlines

 

interpolation

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

``ConfigParser``. See the `String Interpolation`_ section for full details.

If ``interpolation`` is set to ``False``, then interpolation is *not* done when

 

 

 

 

 

 

members) will first be decoded to Unicode using the encoding specified by the

 

unrepr

~~~~~~

 

Another boolean value. If this is set, then ``repr(value)`` is used to write

values. This writes values in a slightly different way to the normal ConfigObj

file syntax.

 

This preserves basic Python data-types when read back in. See `unrepr mode`_

for more details.

 

 

write_empty_values

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

 

Also boolean. If set, values that are an empty string (``''``) are written as

empty values. See `Empty Values`_ for more details.

 

 

newlines

~~~~~~~~

 

When a config file is read, ConfigObj records the type of newline separators in the

file and uses this separator when writing. It defaults to ``None``, and ConfigObj

uses the system default (``os.sep``) if write is called without newlines having

been set.

 

 

    ConfigObj({

    })

.. note::

 

    In ConfigObj 4.3.0 *empty values* became valid syntax. They are read as the

    empty string. There is also an option/attribute (``write_empty_values``) to

    allow the writing of these.

    

    This is mainly to support 'legacy' config files, written from other

    applications. This is documented under `Empty Values`_.

    

    `unrepr mode`_ introduces *another* syntax variation, used for storing

    basic Python datatypes in config files. {sm;:-)}

 

 

 

* default_values

 

    This attribute is a dictionary mapping keys to the default values for the

    keys. By default it is an empty dictionary and is populated when you

    validate the ConfigObj.

 

 

        in a future release.

* **restore_default**

 

    ``restore_default(key)``

    

    Restore (and return) the default value for the specified key.

    

    This method will only work for a ConfigObj that was created

    with a configspec and has been validated.

    

    If there is no default value for this key, ``KeyError`` is raised.

 

* **restore_defaults**

    

    ``restore_defaults()``

 

    Recursively restore default values to all members

    that have them.

    

    This method will only work for a ConfigObj that was created

    with a configspec and has been validated.

    

    It doesn't delete or modify entries without default values.

 

 

    ConfigObj({'CLIENT1key1': 'CLIENT1value1', 'CLIENT1key2': 'CLIENT1value2', 

            'CLIENT1key2': 'CLIENT1value2', 'CLIENT1key3': 'CLIENT1value3'}}})

    in `String Interpolation`_.

    An error occurred whilst parsing a configspec.

 

* ``UnreprError``

 

    An error occurred when parsing a value in `unrepr mode`_.

    

* ``ReloadError``

 

    ``reload`` was called on a ConfigObj instance that doesn't have a valid 

    filename attribute.

Behaviour when parsing a config file depends on the option ``raise_errors``.

If ``raise_errors`` is False and multiple errors are found a ``ConfigObjError``

is raised. The error raised has a ``config`` attribute, which is the parts of

the ConfigObj that parsed successfully. It also has an attribute ``errors``,

which is a list of *all* the errors raised. Each entry in the list is an

instance of the appropriate error type. Each one has the following attributes

(useful for delivering a sensible error message to your user) :

If only one error is found, then that error is re-raised. The error still has

the ``config`` and ``errors`` attributes. This means that your error handling

code can be the same whether one error is raised in parsing , or several.

 

It also means that in the most common case (a single error) a useful error

message will be raised.

 

.. hint::

 

    The system of configspecs can seem confusing at first, but is actually

    quite simple and powerful. For a concrete example of how to use it, you may

    find this blog entry helpful :

    `Transforming Values with ConfigObj <http://www.voidspace.org.uk/python/weblog/arch_d7_2006_03_04.shtml#e257>`_.

 

 

If you need to specify the encoding of your configspec, then you can pass in a

ConfigObj instance as your configspec. When you read your configspec file, you

*must* specify ``list_values=False``.

 

.. raw:: html

 

    {+coloring}

    from configobj import ConfigObj

    configspec = ConfigObj(configspecfilename, encoding='UTF8',

        list_values=False)

    config = ConfigObj(filename, configspec=configspec)

    {-coloring}

 

 

 

Copy Mode

---------

 

Because you can specify default values in your configspec, you can use

ConfigObj to write out default config files for your application.

 

However, normally values supplied from a default in a configspec are *not*

written out by the ``write`` method.

 

To do this, you need to specify ``copy=True`` when you call validate. As well

as not marking values as default, all the comments in the configspec file

will be copied into your ConfigObj instance.

 

.. raw:: html

 

    {+coloring}

    from configobj import ConfigObj

    from validate import Validator

    vdt = Validator()

    config = ConfigObj(configspec='default.ini')

    config.filename = 'new_default.ini'

    config.validate(vdt, copy=True)

    config.write()

    {-coloring}

 

 

 

Empty values

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

 

Many config files from other applications allow empty values. As of version

4.3.0, ConfigObj will read these as an empty string.

 

A new option/attribute has been added (``write_empty_values``) to allow

ConfigObj to write empty strings as empty values.

 

.. raw:: html

 

    {+coloring}

    from configobj import ConfigObj

    cfg = '''

        key =

        key2 = # a comment

    '''.splitlines()

    config = ConfigObj(cfg)

    print config

    ConfigObj({'key': '', 'key2': ''})

    

    config.write_empty_values = True

    for line in config.write():

        print line

    

    key = 

    key2 =     # a comment

    {-coloring}

 

 

unrepr mode

===========

 

The ``unrepr`` option allows you to store and retrieve the basic Python

data-types using config files. It has to use a slightly different syntax to

normal ConfigObj files. Unsurprisingly it uses Python syntax.

 

This means that lists are different (they are surrounded by square brackets),

and strings *must* be quoted.

 

The types that ``unrepr`` can work with are :

 

    | strings, lists tuples

    | None, True, False

    | dictionaries, integers, floats

    | longs and complex numbers

    

You can't store classes, types or instances.

 

``unrepr`` uses ``repr(object)`` to write out values, so it currently *doesn't*

check that you are writing valid objects. If you attempt to read an unsupported

value, ConfigObj will raise a ``configobj.UnknownType`` exception.

 

Values that are triple quoted cased. The triple quotes are removed *before*

converting. This means that you can use triple quotes to write dictionaries

over several lines in your config files. They won't be written like this

though.

 

If you are writing config files by hand, for use with ``unrepr``, you should

be aware of the following differences from normal ConfigObj syntax :

 

    | List : ``['A List', 'With', 'Strings']``

    | Strings : ``"Must be quoted."``

    | Backslash : ``"The backslash must be escaped \\"``

 

These all follow normal Python syntax.

 

In unrepr mode *inline comments* are not saved. This is because lines are

parsed using the `compiler package <http://docs.python.org/lib/compiler.html>`_

which discards comments.

 

 

String Interpolation

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

or ``string.Template`` work. The value of the ``interpolation`` attribute

determines which style of interpolation you want to use. Valid values are

"ConfigParser" or "Template" (case-insensitive, so "configparser" and

"template" will also work). For backwards compatibility reasons, the value

``True`` is also a valid value for the ``interpolation`` attribute, and

will select ``ConfigParser``-style interpolation. At some undetermined point

in the future, that default *may* change to ``Template``-style interpolation.

 

For ``ConfigParser``-style interpolation, you specify a value to be

substituted by including ``%(name)s`` in the value.

 

For ``Template``-style interpolation, you specify a value to be substituted

by including ``${cl}name{cr}`` in the value. Alternately, if 'name' is a valid

Python identifier (i.e., is composed of nothing but alphanumeric characters,

plus the underscore character), then the braces are optional and the value

can be written as ``$name``.

 

Note that ``ConfigParser``-style interpolation and ``Template``-style

interpolation are mutually exclusive; you cannot have a configuration file

that's a mix of one or the other. Pick one and stick to it. ``Template``-style

interpolation is simpler to read and write by hand, and is recommended if

you don't have a particular reason to use ``ConfigParser``-style.

 

Interpolation checks first the current section to see if ``name`` is the key

to a value. ('name' is case sensitive).

 

If it doesn't find it, next it checks the 'DEFAULT' sub-section of the current

section.

 

If it still doesn't find it, it moves on to check the parent section and the

parent section's 'DEFAULT' subsection, and so on all the way up to the main

section.

 

If the value specified isn't found in any of these locations, then a

``MissingInterpolationOption`` error is raised (a subclass of

``ConfigObjError``).

references. If there are any circular references which would cause an infinite

interpolation loop, an ``InterpolationLoopError`` is raised.

a flat list, that only contains values that *failed*.

===========

*validate.py* was originally written by Michael Foord and Mark Andrews.

    Copyright (c) 2004 - 2008, Michael Foord & Nicola Larosa

Better support for configuration from multiple files, including tracking

*where* the original file came from and writing changes to the correct

file.

 

Make ``newline`` an option (as well as an attribute) ?

 

``UTF16`` encoded files, when returned as a list of lines, will have the

BOM at the start of every line. Should this be removed from all but the

first line ?

 

Option to set warning type for unicode decode ? (Defaults to strict).

 

A method to optionally remove uniform indentation from multiline values.

(do as an example of using ``walk`` - along with string-escape)

 

Should the results dictionary from validate be an ordered dictionary if

`odict <http://www.voidspace.org.uk/python/odict.html>`_ is available ?

 

Implement some of the sequence methods (which include slicing) from the

newer ``odict`` ?

 

Preserve line numbers of values (and possibly the original text of each value).

There is currently no way to specify the encoding of a configspec file.

 

When using ``copy`` mode for validation, it won't copy ``DEFAULT``

sections. This is so that you *can* use interpolation in configspec

files.

 

``validate`` doesn't report *extra* values or sections.

 

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

section). They are both dictionary keys - so they would overlap.

 

ConfigObj doesn't quote and unquote values if ``list_values=False``.

This means that leading or trailing whitespace in values will be lost when

writing. (Unless you manually quote).

 

Interpolation checks first the current section, then the 'DEFAULT' subsection

of the current section, before moving on to the current section's parent and

so on up the tree.

 

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

by ``ConfigParser`` ?

 

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

validation changes type it sets the value. This will correctly fetch the

value using interpolation - but then overwrite the interpolation reference.

If the value is unchanged by validation (it's a string) - but other types

will be.