[Configobj-develop] ConfigObj 4.3.0alpha

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

{emo;ir_scope} The `Pythonutils SVN Repository <http://svn.pythonutils.python-hosting.com/trunk/pythonutils/>`_ now contains an alpha version of `ConfigObj <http://www.voidspace.org.uk/python/configobj.html>`_. This will become **ConfigObj 4.3.0**.

I hadn't intended to move so quickly from 4.2.0 to 4.3.0, but some interesting discussions on the `configobj-develop list <http://sourceforge.net/mail/?group_id=123265>`_ have led to some fairly major feature enhancements.

These are all implemented and tested, but they do raise a couple of issues and as usual I'd like to see people kicking the code before I do a new release.

The new features include :

* Support for a ``copy`` mode in validation, allowing you to create a default config file *with comments* from your configspec.
* Support for reading empty values (``key =`` and ``key = # comment``) as an empty string.
* A new ``write_empty_values`` option/attribute that will write the empty string as empty values.
* A new ``unrepr`` mode. Explained below.

I have also discovered and fixed three bugs [#]_ :

* Line terminators were incorrectly written on windoze. {sm;:oops:}
* Last occurring comment line could be interpreted as the final comment if the last line wasn't terminated.
* Nested list values would be flattened when ``write`` was called. Now sub-lists have a string representation written instead.

Finally the ``encode`` and ``decode`` methods have been deprecated. I *didn't* deprecate ``rename`` as it should be used with ``walk`` to transform key and section names. ``encode`` and ``decode`` are still good examples of this by the way. [#]_

.. raw:: html

    {title;copy mode for validate}

Thanks to *Louis Cordier* for this suggestion. When you supply a configspec you can specify default values to use for any that are missing from the config file.

Normally when you call the `validate method <http://www.voidspace.org.uk/python/configobj.html#validate>`_ it marks any missing values as having been supplied from the default. If you then call ``write`` it *doesn't* write out any values supplied from defaults (unless you change them). This allows you to keep a config file with *only* values that are different from the defaults.

The ``validate`` method now takes an optional ``copy`` keyword argument. If this is ``True``, then none of the values are marked as default. In addition all the comments are copied across from the configspec, as are the indentation and encoding settings.

A call to ``write`` will then write out a new config file with all the default values specified in the configspec. {sm;:-)}

This does however lead to me realise that there is currently no way to specify the encoding of a configspec file. {sm;:???:}

.. admonition:: Update

    ConfigObj 4.3.0 alpha 2 now allows you to pass in a ConfigObj instance as your configspec. This is not a total solution, but does allow you to read the configspec using ConfigObj, and specify the encoding when you do that.

    In order to read a configspec file, you *must* use the option ``list_values=False``.


.. raw:: html

    {title;unrepr mode}

This was suggested by *Kevin Dangoor* the lead developer of `Turbogears <http://www.turbogears.org/>`_ [#]_. It mimics the ``unrepr`` mode of the `CherryPy Config Module <http://www.cherrypy.org/wiki/ConfigSystem21>`_, and in fact uses the code from `cptools.py <http://www.cherrypy.org/file/trunk/cherrypy/lib/cptools.py>`_.

If you pass in the ``unrepr=True`` keyword when you create your ConfigObj instance, every value is parsed using ``unrepr``. This allows you to have the following types as values :

    integers, strings, True, False, None, floats, complex numbers, lists, dictionaries, tuples

You *can* use multiline values with ``unrepr``. {sm;:-)}

When writing in unrepr mode, the built in function ``repr`` is used to turn every value into a string.

Note that in ``unrepr`` mode :

   | *The value 3.0 is a float*
   | *The value "3.0" is a string*

Quote marks take on the same significance as they have in Python syntax, which is different from normal ConfigObj syntax.

.. [#] But no longer useful since full unicode support was added.
.. [#] ``validate`` also now honours the *order* of your configspec. Before copy mode, this didn't really matter though.
.. [#] Looks like ConfigObj won't be used in Turbogears until version 1.1 when a lot of things change.