Generate PlantUML class diagrams to document your Python application.
py2puml
produces a class diagram PlantUML script representing classes properties (static and instance attributes) and their relations (composition and inheritance relationships).
py2puml
internally uses code inspection (also called reflexion in other programming languages) and abstract tree parsing to retrieve relevant information.
Some parsing features are available only since Python 3.8 (like ast.get_source_segment).
From a given path corresponding to a folder containing Python code, py2puml
processes each file as a module and generates a PlantUML script of its classe-like definitions using:
-
inspection and type annotations to detect:
- static class attributes and dataclass fields
- fields of namedtuples
- members of enumerations
- composition and inheritance relationships (between your domain classes only, for documentation sake). The detection of composition relationships relies on type annotations only, assigned values or expressions are never evaluated to prevent unwanted side-effects
-
parsing abstract syntax trees to detect the instance attributes defined in
__init__
constructors
py2puml
outputs diagrams in PlantUML syntax, which can be:
- versioned along your code with a unit-test ensuring its consistency (see the test_py2puml.py's test_py2puml_model_on_py2uml_domain example)
- generated and hosted along other code documentation (better option: generated documentation should not be versioned with the codebase)
To generate image files, use the PlantUML runtime, a docker image of the runtime (see think/plantuml) or of a server (see the CLI documentation below)
If you like tools related with PlantUML, you may also be interested in this lucsorel/plantuml-file-loader project: a webpack loader which converts PlantUML files into images during the webpack processing (useful to include PlantUML diagrams in your slides with RevealJS or RemarkJS).
Install from PyPI:
- with
pip
:
pip install py2puml
- with poetry:
poetry add py2puml
- with pipenv:
pipenv install py2puml
Once py2puml
is installed at the system level, an eponymous command is available in your environment shell.
For example, to create the diagram of the classes used by py2puml
, run:
py2puml py2puml/domain py2puml.domain
This outputs the following PlantUML script:
@startuml
class py2puml.domain.umlclass.UmlAttribute {
name: str
type: str
static: bool
}
class py2puml.domain.umlclass.UmlClass {
attributes: List[UmlAttribute]
}
class py2puml.domain.umlitem.UmlItem {
name: str
fqn: str
}
class py2puml.domain.umlenum.Member {
name: str
value: str
}
class py2puml.domain.umlenum.UmlEnum {
members: List[Member]
}
enum py2puml.domain.umlrelation.RelType {
COMPOSITION: * {static}
INHERITANCE: <| {static}
}
class py2puml.domain.umlrelation.UmlRelation {
source_fqn: str
target_fqn: str
type: RelType
}
py2puml.domain.umlclass.UmlClass *-- py2puml.domain.umlclass.UmlAttribute
py2puml.domain.umlitem.UmlItem <|-- py2puml.domain.umlclass.UmlClass
py2puml.domain.umlenum.UmlEnum *-- py2puml.domain.umlenum.Member
py2puml.domain.umlitem.UmlItem <|-- py2puml.domain.umlenum.UmlEnum
py2puml.domain.umlrelation.UmlRelation *-- py2puml.domain.umlrelation.RelType
@enduml
Using PlantUML, this script renders this diagram:
For a full overview of the CLI, run:
py2puml --help
The CLI can also be launched as a python module:
python -m py2puml py2puml/domain py2puml.domain
Pipe the result of the CLI with a PlantUML server for instantaneous documentation (rendered by ImageMagick):
# runs a local PlantUML server from a docker container:
docker run -d --rm -p 1234:8080 --name plantumlserver plantuml/plantuml-server:jetty
py2puml py2puml/domain py2puml.domain | curl -X POST --data-binary @- http://localhost:1234/svg/ --output - | display
# stops the container when you don't need it anymore, restarts it later
docker stop plantumlserver
docker start plantumlserver
For example, to create the diagram of the classes used by py2puml
:
- import the py2puml function in your script (see py2puml/example.py):
from py2puml.py2puml import py2puml
# outputs the PlantUML content in the terminal
print(''.join(py2puml('py2puml/domain', 'py2puml.domain')))
# writes the PlantUML content in a file
with open('py2puml/domain.puml', 'w') as puml_file:
puml_file.writelines(py2puml('py2puml/domain', 'py2puml.domain'))
- running it (
python3 -m py2puml.example
) will output the previous PlantUML diagram in the terminal and write it in a file.
# directly with poetry
poetry run python -m pytest -v
# in a virtual environment
python3 -m pytest -v
Code coverage (with missed branch statements):
poetry run python -m pytest -v --cov=py2puml --cov-branch --cov-report term-missing --cov-fail-under 90
0.5.4
: fixed the packaging so that the contribution guide is included in the published package0.5.3
: handle constructors decorated by wrapping decorators (decorators making uses offunctools.wrap
)0.5.2
: specify in pyproject.toml that py2puml requires python 3.8+ (ast.get_source_segment
was introduced in 3.8)0.5.1
: prevent from parsing inherited constructors0.5.0
: handle instance attributes in class constructors, add code coverage of unit tests0.4.0
: add a simple CLI0.3.1
: inspect sub-folders recursively0.3.0
: handle classes derived from namedtuples (attribute types areAny
)0.2.0
: handle inheritance relationships and enums0.1.3
: first release, handle all modules of a folder and compositions of domain classes
Unless stated otherwise all works are licensed under the MIT license, a copy of which is included here.
Pull-requests are welcome and will be processed on a best-effort basis. Follow the contributing guide.
-
regarding inspection
- type hinting is optional when writing Python code and discarded when it is executed, as mentionned in the typing official documentation. The quality of the diagram output by
py2puml
depends on the reliability with which the type annotations were written
The Python runtime does not enforce function and variable type annotations. They can be used by third party tools such as type checkers, IDEs, linters, etc.
- complex type hints with more than one level of genericity are not properly handled for the moment:
List[MyClass]
orDict[str, MyClass]
are handled properly,Dict[str, List[MyClass]]
is not. If your domain classes (also called business objects or DTOs) have attributes with complex type hints, it may be a code smell indicating that you should write a class which would better represent the business logic. But I may improve this part of the library as well 😀
- type hinting is optional when writing Python code and discarded when it is executed, as mentionned in the typing official documentation. The quality of the diagram output by
-
regarding the detection of instance attributes with AST parsing:
- only constructors are visited, attributes assigned in other functions won't be documented
- attribute types are inferred from type annotations:
- of the attribute itself
- of the variable assigned to the attribute: a signature parameter or a locale variable
- to avoid side-effects, no code is executed nor interpreted
If py2puml
does not meet your needs (suggestions and pull-requests are welcome), you can have a look at these projects which follow other approaches (AST, linting, modeling):