currently PyReverse build a representation of the source tree with:

Notice that the representation of the project files is a classes hierarchy that can be used to do many others things than generate UML diagrams.

To install the package if you have downloaded the tarball version, just unpack the tarball and run python setup.py install. In the others cases follow the usual procedure of your package management system or instructions of the Windows installer.

This will install the libraries and five executable scripts, pystats (???), pyargo (???), pyvcg (???), py2tests (???), and py2xmi (???), .

Please send any comment, patch or question to the xml-logilab mailing-list.

A diagrams definition file is an XML file which permits to control UML diagrams generation with pyargo and pyvcg. If you don't give a diagrams definitions file to pyargo or pyvcg, a default representation 'll be generated with two diagrams: one with all the classes of your project and another with each package (if there is more than one package).

See the DTD in the "dtd" directory of the distribution for a description of all available constructs.

Well, a little example is still the best way to a quick understanding... Let's see how to generate useful diagrams for the following code:

""" file clientmodule.py """
from suppliermodule import Interface

class Ancestor(Interface):
    def __init__(self, value):
        self.attribute = ''
        local_variable = 0
        self.__value = value

    def get_value(self):
        return self.__value

    def set_value(self, value):
        self.__value = value

class Specialization(Ancestor):

    def __init__(self, value, id):
        Ancestor.__init__(self, value)
        self._id = _id

    def _get_value(self):
        pass

    def do_something(self):
        return
  

""" file suppliermodule.py """

class NotImplemented(Exception):
    pass

class Interface:
    def get_value(self):
        raise NotImplemented()

    def set_value(self, value):
        raise NotImplemented()
  

First, we have to write the diagrams definitions file, which enumerates for each diagram we want to obtain the classes and packages of the project it should contains. Here is simple definition which takes care to give a good overview:

<!DOCTYPE diagrams-def SYSTEM "../dtd/diadefs.dtd" [
]>
<diagrams-def>

 <class-diagram>
   <name>object hierarchy</name>
   <class>
     <name>Ancestor</name>
     <owner>clientmodule</owner>
   </class>
   <class><name>Specialization</name></class>
   <class><name>Interface</name></class>
 </class-diagram>

 <package-diagram>
   <name>packages dependencies</name>
   <package>
     <name>suppliermodule</name>
     <class><name>Interface</name></class>
   </package>
   <package>
     <name>clientmodule</name>
   </package>
 </package-diagram>

</diagrams-def>

You should follow the following tips if you want the PyReverse command line tools to work correctly...

In order to be able to resolve imports correctly, you have to place yourself in the correct directory, the root of the package directory. For instance, to document the package "logilab.pyreverse" in the Python site packages directory, you have to type:

	   cd ~/lib/python2.1/site-packages/
	   pyargo -p PyReverse logilab/pyreverse 
  

The name imported in source files with 'from module import *' won't resolved. You can use pystats to see which modules use this kind of statement.

See ??? for a description of options available in most PyReverse command line tools.

This section describes the options common to most of the programs described below.

You can put any of the options listed above in the file ".pyreverserc" in your home directory. Each tool'll try to read this configuration file on launch.

For instance, imagine you have a standard package hierarchy where you put all documentation in a "doc" directory and all tests in a "test" directory. Moreover, you usually want to see only the public attributes/methods in your diagrams. You can give this behaviour to all PyReverse tools by putting --filter-mode=PUB_ONLY --ignore doc --ignore test in your ".pyreverserc" file.

pystats is essentially useful for it's dependencies analysis, it does not replace a tool such as PyChecker.

pyargo is a tool which generates diagrams for Argo UML from the Python code. It uses a diagram definitions file to generate diagrams with the appropriate classes or/and packages. If you don't give a diagrams definitions file to pyargo and then you open the project file (.argo or .zargo according to your Argo UML version) with Argo UML, you will have all your classes (XMI side) and the default diagrams : one with all the classes of your project and another with each package (if there is more than one package).

III.5.1. Use

To run pyargo on your project, use pyargo -d diadefs.xml *.py or pyargo -d diadefs.xml project_dir/.

pyargo -h display the list of all the available options.

For example, using the diagrams definition seen in the previous section, we can launch pyargo with pyargo -p "Test PyArgo" -z -d diadefs.xml suppliermodule.py clientmodule.py (this supposed we saved the diagrams definitions in "diadefs.xml"). With the -z option, pyargo zip all the generated files in a zargo file, used by Argo UML > 0.9.

You only have now to open the project file with Argo UML (the file which ends with .argo or .zargo according to your Argo UML version). Since pyargo generates only minimal PGML files, the first time you will open a diagram you'll see a heap of boxes. With a recent version of Argo UML, you can use the automatic layout to dispatch the boxes on the workspace. After moving a few arrows, we obtain the following diagrams:

Figure III.1. Diagram "object hierarchy"

Figure III.2. Diagram "packages dependencies"

pyvcg will generate class diagrams readable by VCG. A vcg file 'll be generated for each diagram, which can be displayed using xvcg.

pyvcg shgoud be used it in the same way as pyargo. If you follow the same steps as for pyargo, you'll obtain the following diagram (package diagram are not yet supported):

Figure III.3. Diagram "object hierarchy" in xvcg

py2tests is a tool to generate unit test skeleton from source code, using the unittest module from the Python standard library. I hope this functionnality will evolve soon to do the most annoying part of the job. Comments and ideas are welcome !

For the moment, here is what'll be generated: it will generate one test file for each module. A test class is generated for each class

Moreover a standard function to run tests from the command line is available (look at the file runtests.py in the PyReverse test directory)

py2xmi is a subset of pyargo since it will generate a file conforming to the XMI-UML DTD for a given package.