[Python-checkins] CVS: python/nondist/sandbox/typecheck README,NONE,1.1

[Paul Prescod]

Update of /cvsroot/python/python/nondist/sandbox/typecheck
In directory usw-pr-cvs1:/tmp/cvs-serv29621

Added Files:
	README 
Log Message:
First drop of experimental type checker.


--- NEW FILE: README ---
    Abstract

This code implements error checking for Python code. 

    Goals

 * calling into a Python components (especially the
standard library) should be as error-resistent as calling into a
C-extension. 

 * documentation tools should be able to know what types to expect for
arguments based on the same declarations used to drive type checking.

 * there should be sufficient information in the declarations to allow
conversion into "static language glue" such as IDL, WSDL, COM Type
Libraries and C header files.

 * the information should be available as hints to optimizers and
compilers.

    Warnings

Only use this package is you are a relatively sophisticated Python
user. If I have bugs in it, I will render your Python installation
inoperable. It is absolutely easy to fix this if you are knowledgable
but if you aren't, don't blame me!


    Basic Usage

Read the warnings above!

This package depends upon the "compiler" module. It must be in your
PYTHONPATH or otherwise accessible. The "typecheck.py" module must
also be accessible at runtime. For example:

>set PYTHONPATH=C:\pysrc\python\dist\src\Tools\compiler;C:\pysrc\python\nondist\sandbox\typecheck\src
>python test\testall.py


If the package messes something up, delete the ".pyc" files from your
lib directory. It hasn't had any Unix testing so I wouldn't be
surprised if it messes something up in the "os" module. Patches are
welcome.

    Advanced Usage

Type declarations may be put inline in code but they are best done
out-of-line during the experimental period. Declarations are done in
python files with an extension ".pyt" for "Python types". These sit
alongside the .py files that the describe.

When you direct the "addchecks" program at the ".py" file, it finds an
associated ".pyt" and merges them into one logical file in memory.
Then it generates Python bytecode into the standard ".pyc" file. The
generated bytecode has type checks for incoming arguments and
returned values based on declarations in the ".pyt" file.

You can go back to the old-untyped Python behavior by merely deleting
the genertaed ".pyc" file(s). Be careful not to delete the ".pyt"!
This is the fix if you screw up or if one of my declarations is messed
up (which is very likely at this point!). Just delete the effected
.pyc file and fix the bug.

Another way to get the old behavior is to run "python -O". Python -O
runs from .pyo files, not .pyc files.

Future versions of Python will of course make it easier to switch back
and forth between type checking (for safety) and the lack of type
checking (for performance).

    Implementation

Addchecks.py adds type checks to the "top and bottom" of each function
(to the entry point and every return statement). These checks ensure
that the input and output data is correct. At runtime, typecheck.py
does the actual checks. The "type model" I am using is defined in
typecheck.py. It should make for informative reading.