Type-checking an object graph
-----------------------------

Once you've gone to the trouble of defining your object schema by
documenting your instance attributes, creating a project description
file, and running gen_schema, it's quite simple to ensure that a
collection of objects conforms to your schema.  I'm going to assume
you've followed the steps at the end of the "schema.txt" document, and
created a schema for the "things" project in things_schema.pkl.  Once
you have a schema, you can type-check a saved object graph.  First, we
have to create an object graph using the make_things application.

This requires a bit more setup than running gen_schema, since now we
have to be able to import the 'thing' and 'animal' modules.  The easiest
way to do that is to switch into the "examples" subdirectory and force
Python to search it for modules:

  cd examples
  export PYTHONPATH=.

(That last line is for Bourne-like shells under Unix.  For csh-like
shells, say "setenv PYTHONPATH .".  For other operating systems, you're
on your own.)

Now run make_things:

  python make_things

You should now see the file "things.pkl" in the current directory.

Note that make_things has a (deliberate) type error in it, which means
the object graph captured in things.pkl is inconsistent with the object
schema in things_schema.pkl.  We're going to use the check_data script
to find the type error in the data.

(See if you can spot the error by reading the make_things script.  It
would be easy to modify the underlying class -- Animal, in this case --
to catch this particular error.  However, there's no limit to the number
of type errors you can make in Python code, and hardening your
underlying classes to catch every single one of them is a lot of work.
Thus, Grouch exists to catch such errors after-the-fact.  That is, Grouch
doesn't tell you immediately when a type error is made -- it only
detects it in data that has been saved to a persistent store.  I suspect
the Grouch machinery could be used for run-time type-checking, but that
would probably impose a pretty severe performance penalty, so I haven't
experimented in that direction... yet.)

Obviously, in order to load your pickled object graph, Grouch needs to be
able to import the 'thing' and 'animal' modules.  Since you already ran
make_things, that precondition is satisfied, so we can go ahead and run
check_data:

  check_data -f pickle things_schema.pkl things.pkl

The "-f" option tells check_data what format your object graph is stored
in.  (Currently, the only other option is "zodb", which is further
modified by the "-s" (storage) option.)  The first filename,
things_schema.pkl, is the file containing the object schema for this
project.  This is *always* a pickle, regardless of "-f".  The second
argument is the location of the data to be checked -- in this case, the
object graph created by make_things.

The one type error in the make_things script corresponds to one type
error in things.pkl, reported by check_data as:

  root.things['Tyrannosaurus rex'].num_legs:
    expected int, got string ('2 big, 2 small')

If you were unable to track down the error message by reading the code
earlier, this error message should help a lot.  ;-)


$Id: checking.txt 20229 2003-01-16 21:29:07Z akuchlin $