Grouch ------ 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.2, 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.txt Inspect things_schema.txt 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 . 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/