====================
 :mod:`mmf.objects`
====================

This module provides some objects to simplify some basic operations.
The two main features are :class:`mmf.objects.Archivable` and
:class:`mmf.objects.StateVars` which provides a mechanism for
automatic attribute processing and documentation.

:class:`mmf.objects.Archivable`
===============================
By inheriting from :class:`mmf.objects.Archivable`, users can make
classes that can be archived to a string of executable python code.
This includes all needed imports etc. and is human readable.  Thus, it
may be used like the :mod:`pickle` module.  However, unlike
:mod:`pickle`, the representation is easy to read and edit.  A big
advantage is that by a few simple edits of the import section, one can
change the location of objects and ensure that they are not
irretrievably lost across version changes, module reorganizations etc.

.. note:: Opening archives allows arbitrary code to be executed (like
   :mod:`pickle`) so only open trusted archives.

.. note:: The archive mechanism is likely to be less efficient in terms of
   space and time than :mod:`pickle`.

To allow archiving, objects can:

1) override :meth:`mmf.objects.Archivable.archive_1` to allow a custom
   representation,
2) provide an executable representation string via
   :meth:`mmf.objects.Archivable.__repr__`, or
3) provide an explicit list of items and names to pass to the
   constructor by defining :meth:`mmf.objects.Archivable.items`.

:class:`mmf.objects.StateVars`
===============================
By inheriting from :class:`mmf.objects.StateVars`, an object is setup
with machinery to aid in construction and attribute definition.  The
basic idea is to define the class attributes via a list
:attr:`_state_vars` and then call :func:`mmf.objects.process_vars` which
modifies the class documentation and provides a default constructor
that accepts attributes and automatically assigns them.

The role of :meth:`__init__` changes somewhat.  Instead of just
constructing the object, it be comes the calculator.  One of the
options for attributes defined through :attr:`_state_vars` is
:class:`mmf.objects.Computed`.  These attributes must be computed in
:meth:`__init__`.  To facilitate this role, when properties are
assigned, :meth:`__init__` is called (by
:class:`mmf.objects.StateVars.__setattr__`) with the changed property
included in the keyword arguments.  Thus, the user can streamline the
calculation, only recomputing the required components.  (At first,
just recompute everything, then profile and optimize!)

.. note:: Look at the default code in
  :class:`mmf.objects.StateVars.__init__` and use this as a base for
  your overloaded version.  This include code to properly allow for
  copy-construction for example.




:class:`mmf.objects.Container`
===============================
:class:`mmf.objects.Container` is basically the same as
:class:`mmf.objects.StateVars`, but has the
:attr:`mmf.objects.StateVars._dynamic` set to `True` which allows
attributes to be added dynamically.  Thus, these act as a generic
"container" with nice archival and construction features.