Introduction
============

Clio is one of the muses of Greek mythology, the muse of history. This
library is named Clio as it allows one to trace the history of
database record: from their creation to their publication, and onwards
into an archived state.

Clio builds on SQLAlchemy, and in particular with its ORM (object
relational mapper). When Clio is used, ORM-mapped objects will have a
number of properties and methods to do with workflow. In fact, these
objects now stand for *versions* of an abstract notion of an object
that encompasses all its versions.

The workflow scenario that Clio handles in particular is that of
publication and archiving. The goal is of Clio to allow a single
database to contain both information that is made public as well as
information that is not public yet, but instead is being created or is
a version of published information that is currently being edited. In
addition the database should retain information about old versions of
particular records that were previously published.

With Clio, a database record can exist in three states:

* published: the record is considered to be available in the database.

* archived: a previously published version of the record. Multiple
  versioned of an archived record may exist at the same time.

* under edit: a record is either new, or is an existing published
  record being edited. The information is only intended to be used by
  an application used to manage and edit the database.

Clio integrates with SQLAlchemy's ORM (object relational
mapper). ORM-backed objects managed by Clio have methods that allow a
programmer to drive the workflow, as well as workflow-related
properties.
