[Zope-CVS] CVS: ZODB4/Doc - user.txt:1.1

Jeremy Hylton jeremy@zope.com
Fri, 2 Aug 2002 19:10:11 -0400


Update of /cvs-repository/ZODB4/Doc
In directory cvs.zope.org:/tmp/cvs-serv29898

Added Files:
	user.txt 
Log Message:
Beginnings of some user documentation for ZODB4.

Using the new-fangled RST markup.


=== Added File ZODB4/Doc/user.txt ===
ZODB User Guide
===============

The Zope Object Database (ZODB) is an extension to Python_ that allows
objects to outline a single program execution and to be shared among
multiple programs.  The database stores objects on disk, automatically
loading and storing them as needed by the application program.  

ZODB achieves a high degree of transparency.  Few changes are required
to make an existing Python program work with ZODB.  ZODB provides
orthogonal persistence [AM95]_, although it makes some distinction
between persistent and non-persistent object.

This document describes how to use ZODB: how to write programs that
use the database and how to manage the database itself.  It also
touches on implementation issues that may help programmers make the
most effective use of ZODB.  The _`Appendix` describes how to download
and install ZODB.

This document describes ZODB version 4, which is currently being
developed.  The interfaces, implementation, and documentation may
change significantly before the ZODB 4.0 final release.

    Historically, ZODB has not had a clear version numbering
    scheme.  Early versions of ZODB were released only as part of Zope_.
    Fulton's paper [Ful00]_ describes an early version of ZODB 3, and
    Kuchling's programmers guide [Kuc01]_ describes a later version.
    The StandaloneZODB_ 1.0 contains a mature version of the ZODB 3
    codebase.

There are a few key concepts that are important for understanding and
using ZODB.  First, ZODB provides persistence by *reachability.*  The
database provides a distinguished root object.  Any object reachable
from the root will be saved by the database.  Second, ZODB uses
transactions to coordinate updates to objects.  An application must
commit a transaction to make its changes visible to other programs and
have them stored permanent in the database.

The ZODB system encompasses several cooperating components.  In the
source distribution, these are represented as separate Python
packages. The `Persistence` package tracks changes to persistent
objects.  The `Transaction` package controls when changes are stored.
The `ZODB` package moves objects back and forth between disk and
memory; it can be configured to use any one of several ZODB *storages*
for permanent storage.

Persistence
-----------

The database will store any object reachable from its root.  The root
is a dictionary-like object.  Typically, applications store data in
the root using application-defined string keys.  Any key or value in
the root will be stored.  The database follows object references from
the root, so any object reachable from a key or value will also be
stored.

ZODB uses Python's pickle mechanism to store objects.  As a result,
objects that are stored in the database must be picklable.  If an
unpicklable object, like a file or socket, is reachable, the database
will raise a `TypeError`.

ZODB distinguishes between persistent and non-persistent objects.
Persistent objects inherit from the ``Persistent`` base class, and are
treated specially by ZODB.  Other objects, like Python's
builtin types, are still stored by the database, but are not
full-fledged persistent objects.

ZODB automatically tracks changes to persistent objects.  When an
attribute is set or deleted, the object is marked as modified.  When
the current transaction commits, all the modified objects will be
written to the storage.

Transactions
------------

XXX

Resource management
-------------------

XXX

A simple example
================

References
==========

.. [AM95] Malcolm Atkinson and Ronald Morrison.  Orthogonally 
   Persistent Object Systems.  *VLDB Journal* 4(3):319-401, 1995.
   http://www.vldb.org/journal/VLDBJ4/P319.pdf

.. [Ful00] Jim Fulton.  Introduction to the Zope Object Database.
   In *Proceedings of the 8th International Python Conference*,
   pp. 35-44, Jan. 2000. 
   http://www.python.org/workshops/2000-01/proceedings/papers/fulton/zodb3.html

.. [Kuc01] \A. M. Kuchling.  ZODB/ZEO Programming Guide.  Web page
   available at http://www.amk.ca/zodb/guide/zodb.html.  Last update
   Dec. 5, 2001.

Appendix
========

ZODB 4 is available from the `CVS repository`_ at cvs.zope.org.
Follow the instructions there to do a CVS checkout of ``ZODB4``.

.. _CVS repository: http://cvs.zope.org/

ZODB 4 requires Python 2.2.1 or higher.  Some of the code -- notably
the support for persistence of class objects -- requires bug fixes
that will be released with Python 2.2.2.

The ``ZODB4`` directory will contain two scripts, one to build C
extensions and the other to run the test suite::

  localhost:~/src/ZODB4> python build.py
  Building extensions in /home/jeremy/src/ZODB4/Persistence
  running build_ext

  Building extensions in /home/jeremy/src/ZODB4/ZODB
  running build_ext

  localhost:~/src/ZODB4> python test.py
  ----------------------------------------------------------------------
  Ran 754 tests in 82.240s

  OK

You can install the ZODB packages by running ``python setup.py install``.

The script ``test.py`` can be run with many different options,
including ``-v`` to print dots as tests are run and ``-vv`` to print
the name of each test as its run.  Use ``-h`` to print the full list
of options.

Note that the current version of ZODB4 does not contain the ZEO
package.  It will be added before the first release.  A version of ZEO
that is compatible with ZODB4 is currently available on the 
``ZODB4-ZEO-branch``.

 
.. The rest of the file contains some definitions for links.

.. _Python: http://www.python.org/
.. _Zope: http://www.zope.org/
.. _StandaloneZODB: http://www.zope.org/Products/StandaloneZODB