Introduction
------------

The analysis package provides support for the analysis of Python source code
beyond that provided by the compiler standard library package. When performing
an analysis of a Python module, the software first obtains the abstract syntax
tree using the compiler package; then it annotates the nodes in that package
with information it has deduced from the anticipated behaviour of the program.

Additional modules are provided for code generation, and although these
modules are as yet incomplete, they do provide an insight into the conclusions
drawn in the analysis activity.

Quick Start
-----------

Try running the simple code generator to get code listings in various
languages:

python dump.py tests/fib.py

Try running the test program in interactive mode and examining the module
object 'm' with the 'ldir', 'lref' and 'ltype' functions:

python -i test.py tests/class.py

>>> ldir(m)
[['C', 'B']]
>>> ldir(m, "B")
[['x', '__init__']]
>>> lref(m, "B.x")
[AssAttr(Name('self'), 'x', 'OP_ASSIGN'), AssAttr(Name('self'), 'x',
'OP_ASSIGN'), AssAttr(Getattr(Name('C'), 'b1'), 'x', 'OP_ASSIGN')]
>>> lref(m, "B.x")[0]
AssAttr(Name('self'), 'x', 'OP_ASSIGN')
>>> ltype(lref(m, "B.x")[0])

Documentation about aspects of the package's design and implementation can be
found in the docs directory, with the most useful document being docs/AST.html
- a reference covering the annotation attributes added to abstract syntax tree
nodes during the analysis activity.

Contact, Copyright and Licence Information
------------------------------------------

No Web page has yet been made available for this work, but the author can be
contacted at the following e-mail address:

paul@boddie.org.uk

Copyright and licence information can be found in the docs directory - see
docs/COPYING.txt and docs/LICENCE.txt for more information.

Notes for analysis 0.1
----------------------

  * The tools/6502 directory is not included in this release since it includes
    and/or depends upon tools which are not suitably/explicitly licensed.

Future Work
-----------

Instantiation:
    Consider list.__str__ and list.__repr__:
        The overhead in listing the contents of lists could be considerable
        especially where many different types are put in lists.

Instantiation and specialisation:
    Loss of precision in function signatures/specialisations might need to be
    overcome using an improved scheme for instantiating/identifying
    objects/references during analysis and/or determining suitable signatures
    for specialisations. The docs directory contains some discussion documents
    on this topic.

Code generation:
    Obviously, the code generation for the C programming language could be
    finished. Assembly language generation could also be done, although
    developing suitable runtime libraries is time consuming.

Release Procedures
------------------

Update the analysis/__init__.py __version__ attribute.
Change the version number and package filename/directory in the documentation.
Change code examples in the documentation if appropriate.
Update the release notes (see above).
Check the release information in the PKG-INFO file.
Tag, export (excluding tools/6502 for now).
Archive, upload.
Update PyPI, PythonInfo Wiki, Vaults of Parnassus entries.

Generating the API Documentation
--------------------------------

In order to prepare the API documentation, it is necessary to generate some
Web pages from the Python source code. For this, the epydoc application must
be available on your system. Then, inside the distribution directory, run the
apidocs.sh tool script as follows:

./tools/apidocs.sh

Some warnings may be generated by the script, but the result should be a new
apidocs directory within the distribution directory.
