calatrava

calatrava is a Python code architecture analyzer, i.e. it builds UML diagrams (or something similar) for a given class, module, subpackage, or package.

It relies on findimports (to parse import information), xlizard (an adaptation of lizard with a more powerful Python parser; to parse information about object definition), and graphviz do draw diagrams.

Installation

calatrava is not available in PyPI yet (due to its imaturity). 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

For most of the available commands (classes, modules, subpackages, package) the input takes the following form:

calatrava <command> <package_name> <package_dir> <args> -o <filename>

<args> depends on the particular command and can be can be single or multiple):

classes/modules/subpackages: class(es)/module(s)/subpackage(s) import path(s)
package: not applicable

To get more information about the expected parameters for a given command, do:

calatrava <command> --help

Examples

Let's examplify calatrava usage by exploring geomstats.

Classes

The following command:

calatrava classes $(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 classes $(GEOMSTATS_DIR) geomstats.geometry.spd_matrices.SPDMatrices geomstats.geometry.spd_matrices.SPDMetricAffine

Modules

calatrava modules geomstats $(GEOMSTATS_DIR) geomstats.geometry.spd_matrices

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

Subpackages

calatrava subpackages geomstats $(GEOMSTATS_DIR) geomstats.geometry

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

Package

calatrava package geomstats $(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).
Trees are built bottom-up, meaning we start with a desired class (e.g. the one specified with classes command) 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.
(For now) properties are treated as methods.
Attributes or methods that are inherited are prefixed by -.
Attributes or methods that are overriden or defined for the first time are prefixed by +.

ninamiolane / calatrava