Introduction
------------

H5pom is an object mapper for keeping a python object hierarchy
synchronized with an HDF5 data file.  Think of this as an ORM for HDF5 based
storage.  Under the hood H5pom uses h5py for communicating with the data
store, but this dependency is intended to be entirely abstracted away by the
the object mapper layer.

The requirements to save and restore objects from an HDF5 data file using
H5pom are modest and in keeping with the usual requirements for using
another ORM like Sqlalchemy and Django.  The only needs are to derive your
domain specific classes from h5pom.Object and declare your attributes as
class attributes.  Here is an example usage:

  >>> import h5pom
  >>> class Person(h5pom.Object):
  ...     name = h5pom.Scalar()
  ...     age = h5pom.Scalar()
  ...
  >>> f = h5pom.open(h5pom.IN_MEMORY, [Person])
  >>> p = Person(name='Joe', age=25)
  >>> f['joe'] = p
  >>> assert f['joe'].name == 'Joe'
  >>> p.age = 23
  >>> assert f['joe'].age == 23
  >>> f.close()

In that example, there is no file made on disk due to the use of
h5pom.IN_MEMORY used as the file name, but the code is representative and
complete for the simple notion of saving Person objects to an HDF5 file.

Goals of H5pom
--------------

H5pom aims to make it easy to store and synchronize python object graphs
which may or may not have numeric array data in an HDF5 file.  For array types
of known numpy dtype H5pom aims to expose the full performance of HDF5
and h5py as appropriate.

H5pom does not aim to have the full generality of reading arbitrary HDF5
files.  The h5py project already has an excellent pythonic API for accessing
groups, subgroups and attributes.  H5pom will tend to emphasize a schema
where the schema is a list of class types which may appear in the HDF5 file and
the attributes on those objects are known at the point of writing the python
model implementation.

Object Mapping Basics
---------------------

H5pom heavily utilizes the group and attribute notions in HDF5.  The
following general correspondences illustrate the design:

- python objects <-> groups
- scalar attributes of python objects <-> group attributes
- object references of python objects <-> subgroup with-in parent object group
- array type as attribute of python object <-> dataset with-in parent object
  group
- python list as attribute of python object <-> family of attributes with
  prefixed names with-in parent object group

TODO
----

- SubObjectDict saves dictionaries mapping alphanumeric names to Objects, but
  there is no persistent dictionaries mapping alphanumeric names to Scalars.
  Consider adding this.
