# 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:

- dictionaries (`dict`)
- lists and tuples (`list` and `tuple`)
- integers and floats (`int` and `float`)
- plain and unicode strings (`str` and `unicode`)
- booleans (`bool`)
- `None`

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.