1 Usage

miniconf provides data persistence of a subset of Python built-in objects as plain text. Objects are loaded from, and dumped to valid Python source composed of assignment statements of the form identifier = value. Supported objects are:

Arbitrarily complex objects composed of these types can be handled. miniconf is restricted to these types because they can be easily reconstructed from literal representation in Python, entirely known at byte-compilation, without the need to execute the code.

miniconf aims at providing an easy, elegant way to store (dump) and retrieve (load) configurations1 and other simple datasets in a human-readable, familiar pythonic notation, while preventing unwanted injection of external code.

Basically, miniconf exposes two important functions, load and dump, a derivated, specialized loader, unrepr, as well as one helper function, format_header:

load( buf[, pedantic=False])
Load configuration from string buf. If pedantic is True, un-loadable elements will raise TypeError exceptions instead of being silently dropped. On success, return a dictionary containing the parsed built-in objects, indexed by assignment names. On error, raise a SyntaxError, TypeError or ValueError exception.

dump( data[, comments={}, pedantic=True, ...])
Dump configuration from dictionary data, prepending string comments from corresponding values (i.e. associated to the matching keys in data) in comments. If pedantic is True, a TypeError exception will be raised if some value in data is a derivate class of an otherwise supported type. Return the formatted string on success, or raise a TypeError or ValueError on error. data dictionary is dumped in identifiers' alphabetical order. Valid keywords are optional arguments to the low-level PrettyPrinter object (see the pformat function from the pprint module).

If every lines in a comment string are already starting with a pound sign thus making the string an already valid Python comment, such string is preserved untouched in the output. If not, the comment string will be formatted using format_header, using the same width used by the PrettyPrinter. Basically, this means you are free to either have comments automatically formatted and wrapped as a single paragraph, or use your own layout if you want, as long as the whole string keeps being a valid Python comment.

Values associated with special '--top--' and '--bottom--' keys, if they exist in comments, will be respectively included at the beginning and end of the return string; same formatting rules apply to them.

unrepr( buf[, pedantic=False])
Return an object from its canonical string representation buf. This is a specialized version of load operating on the canonical representation of a single value instead than on a sequence of assignment statements. This should never fail on any possible values of data when data only includes supported types (see above):

>>> assert(data == unrepr(repr(data)))

The pedantic argument has the same meaning than for load. On error, it can raise a SyntaxError, TypeError or ValueError exception.

format_header( header[, width=80])
Turn header into a valid Python comment by prepending a pound sing followed by a space to each line, and wrap it to the given width. Return the result as a single, potentially multi-lines string.



Footnotes

... configurations1
Hence the name, miniconf. See ConfigParser for a different but more thorough, higher-level implementation of configuration file handlers.