Grouch 0.1
----------

Grouch is a system for describing and enforcing a Python object schema.
That is, it provides you with a language for describing the intended
type signatures of your objects (collectively, the "object schema"), and
tools to walk an object graph, checking that every value found matches
your object schema.

In the current version, your object schema is described in
specially-formatted class docstrings.  (I have vague plans for a
standalone schema language but don't really have a need for it myself,
so haven't done any work in that direction.)  The gen_schema script
walks a directory tree looking for Python modules, parses any class
docstrings it finds, and writes the resulting (pickled) object schema to
a file.

The second phase is to type-check some existing data -- i.e. make sure
that every value in an object graph conforms to the object schema
extracted from your class docstrings.  This is done with the check_data
script, which knows about a couple of popular Python persistence
mechanisms (just ZODB and pickle so far).  If you just want to check an
object graph in memory, you'll have to write a few lines of code to take
the place of running check_data on a persistent object store (this is
not yet covered by the documentation).


REQUIREMENTS
------------

Grouch requires Python 2.0 or greater, with Jeremy Hylton's "compiler"
package installed.  At least in Python 2.0 .. 2.1.1, this package is
included in Python's source distribution, but not installed as part of
the standard library.  To find out if the compiler is installed, run
  python -c "import compiler"

If this runs with no errors, you're ready to install Grouch.

If you need to install the compiler, go back to the source directory
where you built Python.  (If you didn't build Python, or don't have the
source distribution around anymore, just download a source distribution
of whatever version of Python you're running, unpack it, and follow the
rest of these directions.  The compiler is pure Python, so there
shouldn't be any problems building or installing it.)

Switch to the Tools/compiler directory of your Python source
distribution and install the compiler:
  cd Tools/compiler
  python setup.py install

Grouch also utilizes the SPARK parser framework by John Aycock; for your
convenience, a copy is included with Grouch.


INSTALLATION
------------

Installation is straightforward and uses the Python Distutils:

  python setup.py install

This adds the "grouch" package to your Python library, and installs the
gen_schema and check_data scripts to the usual place for scripts (which
depends on your platform, your Python installation, and how the
Distutils have been locally customized).


DOCUMENTATION
-------------

The gory details are in the documents in the doc/ subdirectory:

  * type-system.txt explains Grouch's type system and the syntax
    for specifying types

  * schema.txt explains how to describe an object schema in
    specially-formatted class docstrings, and how to use the
    gen_schema tool to extract a full schema from your source code

  * checking.txt explains how to check a persistent object store
    to ensure that every scrap of data in it conforms to your
    object schema

For details on the implementation, consult the source code in lib/*.py.

For instant gratification, see below.


INSTANT GRATIFICATION
---------------------

To see Grouch in action without having to read all the documentation, try
the following incantation (which is just a distillation of the full
examples in doc/schema.txt and doc/checking.txt).  This is for
Bourne-like shells under Unix; adjust to taste for other shells or
operating systems.  Grouch should work on any operating system that
Python works on, but it's only been tested under Linux.

First, make sure Grouch is accessible to Python by installing it, or
(yuck) by perpetrating some hack with PYTHONPATH and symbolic links.

Next, switch into the "examples" subdirectory and make sure Python can
import the two modules there:

  cd examples
  export PYTHONPATH=$PYTHONPATH:.

Use the gen_schema script to extract an object schema covering the four
classes defined in the modules here (this assumes gen_schema is in your
shell's PATH; adjust accordingly if not):

  gen_schema -p things.proj -o things_schema.pkl -t things_schema.osc

Inspect things_schema.osc if you're curious what an Grouch schema
looks like in human-readable form.

Now run a toy application that creates a persistent object graph (in
things.pkl) with one type error in it:

  python make_things

Finally, run check_data to discover and report the type error in this
object graph:

  check_data -f pickle things_schema.pkl things.pkl


AUTHOR, COPYRIGHT, LICENSE, AVAILABILITY
----------------------------------------

Grouch was written by Greg Ward <gward@mems-exchange.org>.  Includes
code (lib/spark.py) written by John Aycock, which is licensed
separately.

Copyright (c) 2001 Corporation for National Research Initiatives.
All Rights Reserved.

See LICENSE.txt for license information.

For the latest version, visit
  http://www.mems-exchange.org/software/grouch/


$Id: README.txt,v 1.7 2001/09/05 14:45:08 gward Exp $
