~bzr-pqm/bzr/bzr.dev

:Version: ConfigObj 4.5.2

:Date: 2008/02/24

 

 

* 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)

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`_.

 

 

.. _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** is widely used. Projects using it include:

 

* `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.

 

 

 

 

 

 

* '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'

 

 

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

                           list_values=False)

    

 

 

 

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.

 

 

* newlines

 

 

 

 

 

 

 

 

 

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.

 

 

 

* 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.

 

 

* **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.

 

 

    

* ``ReloadError``

 

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

    filename attribute.

 

 

 

 

 

 

 

===========

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

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

From version 4 it lists all releases and changes.

 

 

2008/02/05 - Version 4.5.2

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

 

Distribution updated to include version 0.3.2 of validate_. This means that

``None`` as a default value win configspecs works.

 

 

2008/02/05 - Version 4.5.1

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

 

Distribution updated to include version 0.3.1 of validate_. This means that

Unicode configspecs now work.

 

 

2008/02/05 - Version 4.5.0

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

 

ConfigObj will now guarantee that files will be written terminated with a

newline.

 

ConfigObj will no longer attempt to import the ``validate`` module, until/unless 

you call ``ConfigObj.validate`` with ``preserve_errors=True``. This makes it 

faster to import.

 

New methods ``restore_default`` and ``restore_defaults``. ``restore_default``

resets an entry to its default value (and returns that value). ``restore_defaults``

resets all entries to their default value. It doesn't modify entries without a 

default value. You must have validated a ConfigObj (which populates the

``default_values`` dictionary) before calling these methods.

 

BUGFIX: Proper quoting of keys, values and list values that contain hashes 

(when writing).  When ``list_values=False``, values containing hashes are 

triple quoted.

 

Added the ``reload`` method. This reloads a ConfigObj from file. If the filename

attribute is not set then a ``ReloadError`` (a new exception inheriting from

``IOError``) is raised.

 

BUGFIX: Files are read in with 'rb' mode, so that native/non-native line endings work!

 

Minor efficiency improvement in ``unrepr`` mode.

 

Added missing docstrings for some overidden dictionary methods.

 

Added the ``reset`` method. This restores a ConfigObj to a freshly created state.

 

Removed old CHANGELOG file.

Fixed bug where '\\n' terminated files could be truncated.

 

 

 

 

 

Gustavo Niemeyer.)

 

First public release.

 

Plus lots of other improvements. {sm;:grin:}

 

 

using it anyway.

This new version is much more 'classy'. {sm;:wink:}

 

 

 

.. [#] The method signature shows that this method takes

 

.. _Michael Foord: http://www.voidspace.org.uk/python/weblog/index.shtml