Clio Models
===========

The next step is to define Clio models. A Clio model is a class that
is going to be mapped to a table by the SQLAlchemy ORM. A Clio model
also has a number of special methods that can be used to drive the
workflow process and that will be described later.

It is easy to create a Clio-based model, just subclass from
``clio.Model``::

  import clio

  class Address(clio.Model):
      pass

In many cases, a ``clio.Model`` needs to define its own
``__init__``. This looks like this::

  class Address(clio.Model):
      def __init__(self, code, street, city, country):
          super(Address, self).__init__(code)
          self.street = street
          self.city = city
          self.country = country

Note that it is required to call the superclass and pass it the
``code``.

Mapping
-------

After definining the tables and the model classes, we use the normal
SQLAlchemy object relational mapper to map the classes to the tables::

  from sqlalchemy.orm import mapper

  mapper(Address, address_table)

This is standard SQLAlchemy, and we have seen everything needed to
create a Clio-managed model. The situation becomes a bit more involved
when we want to create relations between models.

Workflow properties
-------------------

The Clio table columns described earlier will exist on the mapped
instances. The following properties are available::

``id`` 
  An integer attribute uniquely identifying the record underlying
  the instance. Will be automatically set by the system.

``code``
  An integer that uniquely identifies the actual information managed
  this object. Other versions of this object in other workflow states
  will have the same ``code``, but not the same ``id``.

``status``
  An integer that indicates the workflow status that the particular
  version is in.

``workflow_timestamp``
  The moment this version last underwent a workflow transition.

``creation_timestamp``
  The moment this object was created.
