
Overview of Dulcinea
====================

Dulcinea contains a number of different things.

   * A set of modules that simplify using the ZODB.

   * Some useful classes for use with Quixote.

   * Various miscellaneous modules that we've found to be useful.


ZODB-related modules
--------------------


  * ``base.py`` contains useful ``DulcineaBase`` and ``DulcineaPersistent``
    base classes.

  * ``database.py`` contains an ``ObjectDatabase`` class that handles 
    initializing and accessing a ZODB containing a set of database
    roots.

  * ``extent.py``, for keeping track of all the instances of each class.

  * ``persistent_list.py``, a type that behaves like Python lists 
    but automatically sets _p_changed when the list is mutated.
    Current versions of the ZODB come with a ``ZODB.PersistentList``
    module that you should use instead.


Quixote-related modules
-----------------------

  * ``persistent_session.py`` provides ZODB-backed versions of
    Quixote's session management classes.

  * ``user.py`` and ``group.py`` contain basic ``User`` and
    ``PrivilegeGroup`` classes.  ``user_database.py`` contains a 
    basic class for storing and retrieving users and groups.

  
Miscellaneous modules
---------------------

Some of the miscellaneous utility modules in Dulcinea are:

  * ``category.py`` provides a ``Category`` class.  Categories
    are nodes in a partially-ordered tree.

  * ``child_process.py``, for starting and communicating with subprocesses.

  * ``country.py`` maps 2-letter ISO country codes to country names.

  * ``dumper.py``, for printing Python data structures in an easy-to-read
    form.

  * ``history.py`` contains a ``History`` class to be used to keep 
    lists of history events attached to an object.  For example, 
    the history for a bug might contain events for its creation 
    and for every time it's re-assigned to someone.

  * ``immutable_list.py`` contains an ``ImmutableList`` class
    that can be concatenated with other lists but can't be mutated
    in-place.  This can be used to declare list constants that will
    truly remain constant and won't be inadvertantly modified by other
    code.

  * ``indented_file.py`` contains a file-like object that adds
    indentation to each line of output.

  * ``script_util.py`` has various utility functions for writing
    command-line scripts.  Requires Optik (http://optik.sf.net).

  * ``sort.py`` contains various functions for sorting sequences.

  * ``spec.py``, for checking that values match a type specification.

  * ``specification.py`` adds stronger type checking.  Classes 
    can subclass the ``Specified`` class and set various class attributes.
    The ``.set()`` method should then be used to set attribute values
    which will be type-checked.

  * ``typed_list.py`` provides a list-like type that also keeps a name for 
    each element, and allows lookups by name.

Consult the module docstrings and source code for more information.
