PyReverse

Table of Content

Chapter I - First step
1.  What should I expect from PyReverse ?
2.  Download
2.1.  Required
2.2.  Optional
3.  Installation
4.  Feedback
Chapter II - UML diagrams generation with pyreverse
1.  Diagrams definitions file
2.  Example
Chapter III - Command lines tools
1.  Useful tips
2.  Common options
3.  Configuration file
4.  PyArgo
4.1.  Use
5.  PyVcg
6.  Py2tests
6.1.  Use
7.  Py2xmi
7.1.  Use
Chapter I

First step

You'll find in this section an introduction to

<application>PyReverse</application>

followed by a description of the download and installation procedure.

1. What should I expect from

<application>PyReverse</application>

?

currently

<application>PyReverse</application>

build a representation of the source tree with:

<application>PyReverse</application>

provides modules which use this representation for:

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.

2. Download

2.1. Required

To use the

<application>PyReverse</application>

package, you need to install PyXML, Optik and Logilab's common library.

The

<application>PyReverse</application>

package itself can be downloaded from the Logilab ftp site.

2.2. Optional

Optionally, you may want to try the

<application>Argo UML</application>

modeler to get nice UML diagrams. We are using release 0.10.1 of

<application>Argo UML</application>

. We recommend to use a version of

<application>Argo UML</application>

greater than 0.9 since older versions don't implement algorithms to automatically layout objects of the diagram (

<application>pyargo</application>

only generate a minimal PGML file without placing objects)

If you are using

<application>pyargo</application>

to generate diagrams for a big project, it's recommended to install 4Suite 0.12. If 4Suite is available, the 4Suite C Domlette implementation will be used instead of minidom, and so the program'll run faster and consume less memory.

The main advantage of

<application>pyargo</application>

is to produce diagram editable in an UML tool. If you just want to see what an object hierarchy looks like without editing the diagrams latter, you should download and install

<application>VCG</application>

. Both

<application>pyvcg</application>

and

<application>VCG</application>

are much more light-weight tools than

<application>pyargo</application>

and

<application>Argo UML</application>

.

3. Installation

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 :

<application>pyargo</application>

(Section 4 “PyArgo” - Chapter III),

<application>pyvcg</application>

(Section 5 “PyVcg” - Chapter III),

<application>py2tests</application>

(Section 6 “Py2tests” - Chapter III), and

<application>py2xmi</application>

(Section 7 “Py2xmi” - Chapter III).

4. Feedback

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

Chapter II

UML diagrams generation with pyreverse

You'll find here some generality usefull to control the generation of your UML diagram from a

<application>Python</application>

project. You should read this before the sections about

<application>pyargo</application>

and

<application>pyvcg</application>

.

1. Diagrams definitions file

A diagrams definition file is an XML file which permits to control UML diagrams generation with

<application>pyargo</application>

and

<application>pyvcg</application>

. If you don't give a diagrams definitions file to

<application>pyargo</application>

or

<application>pyvcg</application>

, 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.

2. Example

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" [ <!-- This DTD defines all the basic XML elements that are allowed in a file of diagrams definitions given to PyReverse. --><!-- Public Identifier of this DTD is "-//LOGILAB//DTD PyReverse Diagrams Description V1.0//EN" --><!-- DIADEFS This DTD defines all the basic XML elements that are allowed in a diagrams definitions file given to pyreverse --><!-- *********************** --><!-- DIAGRAMS-DEF: root --><!-- *********************** --><!-- CLASS-DIAGRAM: A class diagram content description --><!-- *********************** --><!-- PACKAGE-DIAGRAM: A package diagram content description --><!-- *********************** --><!-- PACKAGE: A package represent a module --><!-- *********************** --><!-- CLASS: A class element references a class (described with the xmi-uml) --><!-- *********************** --><!-- NAME, OWNER and INCLUDE: contain a text child with the corresponding value, designing a class name , a module name or an include rule -->]> <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>
This defines two diagrams. The first is a class diagram which will contain the classes Ancestor, Specialization and Interface. The <owner> node may be added if the class has an ambiguous name. The second is a package diagram with our two modules and the class Interface inside the suppliermodule package.

Chapter III

Command lines tools

1. Useful tips

You should follow the following tips if you want the

<application>PyReverse</application>

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

<application>Python</application>

site packages directory, you have to type:
cd ~/lib/python2.1/site-packages/ pyargo -p PyReverse logilab/pyreverse

See Section 2 “Common options” - Chapter III for a description of options available in most

<application>PyReverse</application>

command line tools.

2. Common options

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

3. Configuration file

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

<application>PyReverse</application>

tools by putting --filter-mode=PUB_ONLY --ignore doc --ignore test in your ".pyreverserc" file.

4. PyArgo

<application>pyargo</application>

is a tool which generates diagrams for

<application>Argo UML</application>

from the

<application>Python</application>

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

<application>pyargo</application>

and then you open the project file (.argo or .zargo according to your

<application>Argo UML</application>

version) with

<application>Argo UML</application>

, 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).

4.1. Use

To run

<application>pyargo</application>

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

<application>pyargo</application>

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,

<application>pyargo</application>

zip all the generated files in a zargo file, used by

<application>Argo UML</application>

> 0.9.

You only have now to open the project file with

<application>Argo UML</application>

(the file which ends with .argo or .zargo according to your

<application>Argo UML</application>

version). Since

<application>pyargo</application>

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

<application>Argo UML</application>

, you can use the automatic layout to dispatch the boxes on the workspace. After moving a few arrows, we obtain the following diagrams:
Figure 1 - Diagram "object hierarchy"
Figure 2 - Diagram "packages dependencies"

5. PyVcg

<application>pyvcg</application>

will generate class diagrams readable by

<application>VCG</application>

. A vcg file 'll be generated for each diagram, which can be displayed using

<application>xvcg</application>

.

<application>pyvcg</application>

shgoud be used it in the same way as

<application>pyargo</application>

. If you follow the same steps as for

<application>pyargo</application>

, you'll obtain the following diagram (package diagram are not yet supported):
Figure 3 - Diagram "object hierarchy" in xvcg
As you can see, this is not really UML but enough similar to be understandable. Attributes appear in blue, methods in green. Interfaces have an ellipse shape and signals (exceptions) appear in red.

6. Py2tests

<application>py2tests</application>

is a tool to generate unit test skeleton from source code, using the unittest module from the

<application>Python</application>

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

<application>PyReverse</application>

test directory)

6.1. Use

If we want to generate unittest for the previous example in a "test" subdirectory, we just have to type py2test --test-dir test *.py

7. Py2xmi

<application>py2xmi</application>

is a subset of

<application>pyargo</application>

since it will generate a file conforming to the XMI-UML DTD for a given package.

7.1. Use

To run

<application>py2xmi</application>

on your project, use py2xmi *.py or py2xmi project_dir/, it will print the correspondant XMI file to the standard output.

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