Generate Plantuml diagrams to document your python code
Project description
Generate Plantuml diagrams to document your python code
How it works
From a given path corresponding to a folder containing python code, py2puml
loads each file as a module and generate a class diagram with the PlantUML using:
- inspection to detect the classes to document (see the inspect module)
- annotations (the python type hinting syntax) to detect the attributes and their types (see the typing module)
Current limitations:
- type hinting is optional when writing the code and discarded when it is executed, as mentionned in the official documentation. The quality of the diagram output by
py2puml
depends on the reliability with which the 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 😀 -
composition relationships are detected and drawn. Inheritance relationships are not handled for now
-
py2puml
does not inspect sub-folders recursively, but it is planned -
py2puml
outputs diagrams in PlantUML syntax, which can be saved in text files along your python code and versioned with them. To generate image files, use the PlantUML runtime or a docker image (see think/plantuml) -
py2puml
uses features of python 3 (generators for example) and thus won't work with python 2 runtimes. It relies on native python modules and uses no 3rd-party library, except pytest as a development dependency for running the unit-tests
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
Install from the github repository:
- with
pip
:
pip install py2puml
- with poetry:
poetry add py2puml
- with pipenv:
pipenv install py2puml
Usage
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 PlantUML diagram in the terminal and write it in a file
@startuml
class py2puml.domain.umlclass.UmlAttribute {
name: str
type: str
}
class py2puml.domain.umlclass.UmlClass {
attributes: List[UmlAttribute]
}
class py2puml.domain.umlitem.UmlItem {
name: str
fqdn: str
}
class py2puml.domain.umlenum.Member {
name: str
value: str
}
class py2puml.domain.umlenum.UmlEnum {
members: List[Member]
}
enum py2puml.domain.umlrelation.RelType {
COMPOSITION: *
INHERITANCE: <|
}
class py2puml.domain.umlrelation.UmlRelation {
source_fqdn: str
target_fqdn: 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
Which renders like this:
Tests
python3 -m pytest -v
Changelog
0.2.0
: handle inheritance relationships and enums. Unit tested0.1.3
: first release, handle all module of a folder and compositions of domain classes
Licence
Unless stated otherwise all works are licensed under the MIT license, a copy of which is included here.
Contributions
Pull-requests are welcome and will be processed on a best-effort basis.
Alternatives
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):
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.