.. module:: stdnet.odm

The object-data mapper (ODM) is the core of the library. It defines an API for mapping data in the backend key-value store to objects in Python. Its name is closely related to object relational Mapping (ORM), a programming technique for converting data between incompatible type systems in traditional relational databases and object-oriented programming languages.

The object data mapper presents a method of associating user-defined Python classes, referred as models, with data in a :class:`stdnet.BackendDataServer`. These python classes are subclasses of :class:`stdnet.odm.StdModel`.

.. autoclass:: StdModel
   :members:
   :member-order: bysource

.. autoclass:: Model
   :members:
   :member-order: bysource

.. autofunction:: create_model

.. autoclass:: ModelMeta
   :members:
   :member-order: bysource

.. autoclass:: ModelState
   :members:
   :member-order: bysource

.. autoclass:: autoincrement
   :members:
   :member-order: bysource

.. autoclass:: Q
   :members:
   :member-order: bysource

.. autoclass:: Query
   :members:
   :member-order: bysource

   .. automethod:: __init__

.. autoclass:: QueryElement
   :members:
   :member-order: bysource

.. autoclass:: SearchEngine
   :members:
   :member-order: bysource

Data structures are subclasses of :class:`Structure`, which in term is a subclass of :class:`Model`. They are rarely used in stand alone mode, instead they form the back-end of :ref:`data structure fields <model-field-structure>`.

There are five of them:

• :class:`List`, implemented as a doubly-linked sequence.
• :class:`Set`, a container of unique values.
• :class:`HashTable`, unique associative container.
• :class:`Zset`, an ordered container of unique values.
• :class:`TS`, a time-series implemented as a ordered unique associative container.

An additional structure is provided in the :mod:`stdnet.apps.columnts` module

• :class:`stdnet.apps.columnts.ColumnTS` a numeric multivariate time-series structure (useful for modelling financial data for example).

Creating the five structures available in stdnet is accomplished in the following way:

from stdnet import odm

models = odm.Router('redis://localhost:6379')
li = models.register(odm.List())

At this point the li instance is registered with a :class:`Router` and the session API can be used:

with models.session().begin() as t:
    t.add(li)
    li.push_back('bla')
    li.push_back('foo')

If no id is specified, stdnet will create one for you:

>>> l.id
'2d0cbac9'

.. autoclass:: Structure
   :members:
   :member-order: bysource

.. autoclass:: Sequence
   :members:
   :member-order: bysource

.. autoclass:: PairMixin
   :members:
   :member-order: bysource

.. autoclass:: KeyValueMixin
   :members:
   :member-order: bysource

.. autoclass:: OrderedMixin
   :members:
   :member-order: bysource

.. autoclass:: StructureCache
   :members:
   :member-order: bysource

.. autoclass:: List
   :members:
   :member-order: bysource

.. autoclass:: Set
   :members:
   :member-order: bysource

.. autoclass:: Zset
   :members:
   :member-order: bysource

.. autoclass:: HashTable
   :members:
   :member-order: bysource

.. autoclass:: TS
   :members:
   :member-order: bysource

A :class:`Session` is the middleware between a :class:`Manager` and a :class:`stdnet.BackendDataServer`. It is obtained from either the :meth:`Router.session` or, equivalently, from the :meth:`Manager.session`. A :class:`Session` is an holding zone for :class:`SessionModel` and it communicates with the :class:`stdnet.BackendDataServer` via :class:`Transaction`.

.. autoclass:: Session
   :members:
   :member-order: bysource

.. autoclass:: SessionModel
   :members:
   :member-order: bysource

.. autoclass:: Transaction
   :members:
   :member-order: bysource

.. autoclass:: Manager
   :members:
   :member-order: bysource

.. autoclass:: stdnet.odm.related.RelatedManager
   :members:
   :member-order: bysource

.. autoclass:: stdnet.odm.related.One2ManyRelatedManager
   :members:
   :member-order: bysource

.. autoclass:: stdnet.odm.related.Many2ManyRelatedManager
   :members:
   :member-order: bysource

.. autoclass:: LazyProxy
   :members:
   :member-order: bysource

To interact with a :class:`stdnet.BackendDataServer`, Models must registered. Registration is obtained via a :class:`Router` which has two methods for registering models. The first one is the :meth:`Router.register` method which is used to register a model and, possibly, all its related models. The second method is the :meth:`Router.register_applications` which registers all :class:`Model` from a list of python dotted paths or python modules.

Check the :ref:`registering models tutorial <tutorial-registration>` for further explanation and examples.

.. autoclass:: stdnet.odm.Router
   :members:
   :member-order: bysource