calatrava

calatrava is a Python code architecture analyzer, i.e. it builds UML diagrams (or something similar) for classes, modules, subpackages, packages, or any combination of the former.

It relies on its own parser implementation (built on top of ast) to parse information about object definitions, and graphviz to draw diagrams. It is meant to be modular, so it should be relatively straightforward to plug-in different parsers and/or diagram creators.

Installation

calatrava is not available in PyPI yet (it will be soon). Therefore, install it with

pip install git+https://github.com/lpereira95/calatrava.git@master

If you also want to install requirements, do

pip install git+https://github.com/lpereira95/calatrava.git@master#egg=calatrava

Usage

The most straighforward way to use calatrava is as a CLI tool (click handles this). To check the available commands do:

calatrava --help

To get more detailed information for a given command do:

calatrava <command> --help

calatrava uml

A basic usage of calatrava uml is:

calatrava uml <args> --config <config_file>

<args> is a variadic input argument that must contain package(s) location(s) (package name may be enough for installed packages). Additionally, valid import expressions may be passed: this tells calatrava to look uniquely to the specified import (being it a class, module, or subpackage).

<config_file> is a json configuration file that specifies the record creator (controls the looks of the output diagram) and filters. Filters remove (or keep) specific classes. There's plenty of filters already defined, but you can also define your owns. If a configuration file is not specified, then the global configuration file is used (must be stored in ~/.calatrava/config.json). If it does not exist, then default values are used.

Examples

There's plenty of examples available here.

Still, let's examplify calatrava usage by exploring geomstats.

Classes

The following command:

calatrava uml $GEOMSTATS_DIR geomstats.geometry.spd_matrices.SPDMatrices

creates

Note: do export GEOMSTATS_DIR=<dirpath> or replace $GEOMSTATS_DIR with a valid path.

To draw more classes, just add the corresponding import:

calatrava uml $GEOMSTATS_DIR geomstats.geometry.spd_matrices.SPDMatrices geomstats.geometry.spd_matrices.SPDMetricAffine

Modules

calatrava uml $GEOMSTATS_DIR geomstats.geometry.spd_matrices

(Follow the same procedure as above for several modules.)

Subpackages

calatrava uml $GEOMSTATS_DIR geomstats.geometry

(Follow the same procedure as above for several subpackages.)

Package

calatrava uml $GEOMSTATS_DIR

(For sanity, the generated diagram will not be displayed. Try it out yourself!)

Which information is conveyed in a diagram?

calatrava builds inheritance trees. (Composition information is not easy to gather in a dynamic language and is therefore ignored.) Some (hopefully) useful information:

• Arrows represent inheritance.
• Inheritance coming from external packages is ignored (e.g. if your class derives from sklearn.base.Estimator, this relationship will be ignored), unless the path to the external package is explicitly given.
• Trees are built bottom-up, meaning we start with a desired class (e.g. the one specified with an import) and create records for all the classes from which it inherits directly or from which parents (and grandparents, and...) inherit from.
• Each record is split into two boxes: the first contains attributes, the second contains methods. Other options may split it in four (also class attributes and properties).
• Attributes or methods that are inherited are prefixed by -.
• Attributes or methods that are overriden or defined for the first time are prefixed by +.