[Configobj-develop] ConfigObj New Features

[<fuz...@vo...>]

{ran_emo} A new version of `ConfigObj <http://www.voidspace.org.uk/python/configobj.html>`_ is now available. As well as a few bugfixes (and the file size shrinking 40% due to the separation of the tests and changelog), there are several important new features.

Despite being relatively easy to code, these greatly extend the capabilities of **ConfigObj**. These extracts from the docs summarise what is new.

* *Empty Values* are now valid syntax, with a new option to write them
* *Copy Mode* allows the creation of default config files from a configspec, including comments
* *unrepr mode* allows for the storing and retrieving of basic Python datatypes

.. raw:: html

    {title;Empty values}

From `Empty Values <http://www.voidspace.org.uk/python/configobj.html#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
    {'key': '', 'key2': ''}
    
    config.write_empty_values = True
    for line in config.write():
        print line
    
    key = 
    key2 =     # a comment
    {-coloring}


.. raw:: html

    {title;Copy Mode}

From `Copy Mode <http://www.voidspace.org.uk/python/configobj.html#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}

.. hint::

   There are functions to assist in the *automatic* creation of a configspec, in the `ConfigPersist Module <http://www.voidspace.org.uk/python/configpersist.html>`_.

.. raw:: html

    {title;unrepr mode}

From `unrepr mode <http://www.voidspace.org.uk/python/configobj.html#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.

So **ConfigObj** can now be used for simple (as in easy) data persistence. Move over `YAML <http://pyyaml.org/wiki/PySyck>`_. {sm;:wink:}