TODO
====
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).
ISSUES
======
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 'DEFAULT' subsection of the current
section, next it checks the 'DEFAULT' section of the parent section,
last it checks the 'DEFAULT' section of the main section.
Logically a 'DEFAULT' section should apply to all subsections of the *same
parent* - this means that checking the 'DEFAULT' subsection 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. 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.
CHANGELOG
=========
2006/06/04
----------
Changed error handling, if parsing finds a single error then that error will
be re-raised. That error will still have an ``errors`` and a ``config``
attribute.
2006/05/21
----------
Fixed bug where '\n' terminated files could be truncated.
Bugfix in ``unrepr`` mode, it couldn't handle '#' in strings. (Thanks to
Philippe Normand for the report.)
As a consequence of this fix, ConfigObj doesn't now keep inline comments in
``unrepr`` mode. This is because the parser in the `compiler package <http://docs.python.org/lib/compiler.html>`_
doesn't keep comments. {sm;:-)}
Error messages are now more useful. They tell you the number of parsing errors
and the line number of the first error.
Line numbers in exceptions now start at 1, not 0.
Errors in ``unrepr`` mode are now handled the same way as in the normal mode.
The errors stored will be an ``UnreprError``.
2006/04/24
----------
Preserve tuples when calling the ``dict`` method. (Thanks to Gustavo Niemeyer.)
2006/04/23
----------
Changed ``__repr__`` to return a string that contains ``ConfigObj({ ... })``.
Change so that an options dictionary isn't modified by passing it to ConfigObj.
(Thanks to Artarious.)
Added ability to handle negative integers in ``unrepr``. (Thanks to Kevin
Dangoor.)
2006/03/24
----------
Moved the tests and the CHANGELOG (etc) into a separate file. This has reduced
the size of ``configobj.py`` by about 40%.
Added the ``unrepr`` mode to reading and writing config files.
2006/03/20
----------
Empty values are now valid syntax. They are read as an empty string ``''``.
(``key =``, or ``key = # comment``.)
``validate`` now honours the order of the configspec.
Added the ``copy`` mode to validate. Thanks to Louis Cordier for this
suggestion.
Fixed bug where files written on windows could be given '\r\r\n' line
terminators.
Fixed bug where last occuring comment line could be interpreted as the
final comment if the last line isn't terminated.
Fixed bug where nested list values would be flattened when ``write`` is
called. Now sub-lists have a string representation written instead.
Deprecated ``encode`` and ``decode`` methods instead.
You can now pass in a ConfigObj instance as a configspec (remember to read
the file using ``list_values=False``).
2006/02/04
----------
Removed ``BOM_UTF8`` from ``__all__``.
The ``BOM`` attribute has become a boolean. (Defaults to ``False``.) It can
be ``True`` for the ``UTF16/UTF8`` encodings.
File like objects no longer need a ``seek`` attribute.
ConfigObj no longer keeps a reference to file like objects. Instead the
``write`` method takes a file like object as an optional argument. (Which
will be used in preference of the ``filename`` attribute if htat exists as
well.)
Full unicode support added. New options/attributes ``encoding``,
``default_encoding``.
utf16 files decoded to unicode.
If ``BOM`` is ``True``, but no encoding specified, then the utf8 BOM is
written out at the start of the file. (It will normally only be ``True`` if
the utf8 BOM was found when the file was read.)
Thanks to Aaron Bentley for help and testing on the unicode issues.
File paths are *not* converted to absolute paths, relative paths will
remain relative as the ``filename`` attribute.
Fixed bug where ``final_comment`` wasn't returned if ``write`` is returning
a list of lines.
2006/01/31
----------
Added ``True``, ``False``, and ``enumerate`` if they are not defined.
(``True`` and ``False`` are needed for *early* versions of Python 2.2,
``enumerate`` is needed for all versions ofPython 2.2)
Deprecated ``istrue``, replaced it with ``as_bool``.
Added ``as_int`` and ``as_float``.
utf8 and utf16 BOM handled in an endian agnostic way.
2005/12/14
----------
Validation no longer done on the 'DEFAULT' section (only in the root
level). This allows interpolation in configspecs.
Change in validation syntax implemented in validate 0.2.1
4.1.0
2005/12/10
----------
Added ``merge``, a recursive update.
Added ``preserve_errors`` to ``validate`` and the ``flatten_errors``
example function.
Thanks to Matthew Brett for suggestions and helping me iron out bugs.
Fixed bug where a config file is *all* comment, the comment will now be
``initial_comment`` rather than ``final_comment``.
2005/12/02
----------
Fixed bug in ``create_empty``. Thanks to Paul Jimenez for the report.
2005/11/04
----------
Fixed bug in ``Section.walk`` when transforming names as well as values.
Added the ``istrue`` method. (Fetches the boolean equivalent of a string
value).
Fixed ``list_values=False`` - they are now only quoted/unquoted if they
are multiline values.
List values are written as ``item, item`` rather than ``item,item``.
4.0.1
2005/10/09
----------
Fixed typo in ``write`` method. (Testing for the wrong value when resetting
``interpolation``).
4.0.0 Final
2005/09/16
----------
Fixed bug in ``setdefault`` - creating a new section *wouldn't* return
a reference to the new section.
2005/09/09
----------
Removed ``PositionError``.
Allowed quotes around keys as documented.
Fixed bug with commas in comments. (matched as a list value)
Beta 5
2005/09/07
----------
Fixed bug in initialising ConfigObj from a ConfigObj.
Changed the mailing list address.
Beta 4
2005/09/03
----------
Fixed bug in ``Section.__delitem__`` oops.
2005/08/28
----------
Interpolation is switched off before writing out files.
Fixed bug in handling ``StringIO`` instances. (Thanks to report from
"Gustavo Niemeyer" <gustavo@niemeyer.net>)
Moved the doctests from the ``__init__`` method to a separate function.
(For the sake of IDE calltips).
Beta 3
2005/08/26
----------
String values unchanged by validation *aren't* reset. This preserves
interpolation in string values.
2005/08/18
----------
None from a default is turned to '' if stringify is off - because setting
a value to None raises an error.
Version 4.0.0-beta2
2005/08/16
----------
By Nicola Larosa
Actually added the RepeatSectionError class ;-)
2005/08/15
----------
If ``stringify`` is off - list values are preserved by the ``validate``
method. (Bugfix)
2005/08/14
----------
By Michael Foord
Fixed ``simpleVal``.
Added ``RepeatSectionError`` error if you have additional sections in a
section with a ``__many__`` (repeated) section.
By Nicola Larosa
Reworked the ConfigObj._parse, _handle_error and _multiline methods:
mutated the self._infile, self._index and self._maxline attributes into
local variables and method parameters
Reshaped the ConfigObj._multiline method to better reflect its semantics
Changed the "default_test" test in ConfigObj.validate to check the fix for
the bug in validate.Validator.check
2005/08/13
----------
By Nicola Larosa
Updated comments at top
2005/08/11
----------
By Michael Foord
Implemented repeated sections.
By Nicola Larosa
Added test for interpreter version: raises RuntimeError if earlier than
2.2
2005/08/10
----------
By Michael Foord
Implemented default values in configspecs.
By Nicola Larosa
Fixed naked except: clause in validate that was silencing the fact
that Python2.2 does not have dict.pop
2005/08/08
----------
By Michael Foord
Bug fix causing error if file didn't exist.
2005/08/07
----------
By Nicola Larosa
Adjusted doctests for Python 2.2.3 compatibility
2005/08/04
----------
By Michael Foord
Added the inline_comments attribute
We now preserve and rewrite all comments in the config file
configspec is now a section attribute
The validate method changes values in place
Added InterpolationError
The errors now have line number, line, and message attributes. This
simplifies error handling
Added __docformat__
2005/08/03
----------
By Michael Foord
Fixed bug in Section.pop (now doesn't raise KeyError if a default value
is specified)
Replaced ``basestring`` with ``types.StringTypes``
Removed the ``writein`` method
Added __version__
2005/07/29
----------
By Nicola Larosa
Indentation in config file is not significant anymore, subsections are
designated by repeating square brackets
Adapted all tests and docs to the new format
2005/07/28
----------
By Nicola Larosa
Added more tests
2005/07/23
----------
By Nicola Larosa
Reformatted final docstring in ReST format, indented it for easier folding
Code tests converted to doctest format, and scattered them around
in various docstrings
Walk method rewritten using scalars and sections attributes
2005/07/22
----------
By Nicola Larosa
Changed Validator and SimpleVal "test" methods to "check"
More code cleanup
2005/07/21
----------
Changed Section.sequence to Section.scalars and Section.sections
Added Section.configspec
Sections in the root section now have no extra indentation
Comments now better supported in Section and preserved by ConfigObj
Comments also written out
Implemented initial_comment and final_comment
A scalar value after a section will now raise an error
2005/07/20
----------
Fixed a couple of bugs
Can now pass a tuple instead of a list
Simplified dict and walk methods
Added __str__ to Section
2005/07/10
----------
By Nicola Larosa
More code cleanup
2005/07/08
----------
The stringify option implemented. On by default.
2005/07/07
----------
Renamed private attributes with a single underscore prefix.
Changes to interpolation - exceeding recursion depth, or specifying a
missing value, now raise errors.
Changes for Python 2.2 compatibility. (changed boolean tests - removed
``is True`` and ``is False``)
Added test for duplicate section and member (and fixed bug)
2005/07/06
----------
By Nicola Larosa
Code cleanup
2005/07/02
----------
Version 0.1.0
Now properly handles values including comments and lists.
Better error handling.
String interpolation.
Some options implemented.
You can pass a Section a dictionary to initialise it.
Setting a Section member to a dictionary will create a Section instance.
2005/06/26
----------
Version 0.0.1
Experimental reader.
A reasonably elegant implementation - a basic reader in 160 lines of code.
*A programming language is a medium of expression.* - Paul Graham