Introduction
************

Built on top of standard language libraries for JSON and XML encodings, this library reduces
the complexities of storing and recovering application objects to a few simple operations. Assuming
that ``ServerConfiguration`` is a suitably defined data class:

.. code-block:: python

   f = ansar.File('configuration', ServerConfiguration)

   configuration, _ = f.recover()

This will read a valid instance of ``ServerConfiguration`` from the ``configuration.json`` file
in the current folder, and assign it to the ``configuration`` variable. At any point during the
subsequent operation of the application, the latest values can be saved back into the same file with
this call:

.. code-block:: python

   f.store(configuration)

The library presents an interface based on application types. Details relating to serialization and
marshalling are managed behind that interface. Members of the ``ServerConfiguration`` class can
be any mixture of:

    * basic language types such as ``int``, ``float`` and ``str``,
    * language collections such as ``set``, ``dict`` and ``deque``,
    * fixed-length arrays,
    * nested objects, object graphs and more.

Generated files contain only standard conformant encodings (e.g. JSON). Known security vulnerabilities
are addressed in the library - such as the `billion laughs` and `quadratic expansion` vulnerabilities
of the XML encoding. The library brings built-in version support for seamless software updates.

The documentation is arranged as a series of tutorials, followed by a collection of reference sections.
The tutorials provide enough information to satisfy most application requirements.

* :ref:`a-quick-tour`, object declaration, storage and recovery with complete code examples,
* :ref:`a-folder-of-jobs`, folder hierarchies and collections of files in folders,
* :ref:`more-about-types`, more advanced types including sequences and collections,
* :ref:`really-complicated-documents`, storing and recovering graphs
* :ref:`versions-upgrading-and-migration`, operation in the presence of old files