py2puml 0.3.0

Generate Plantuml diagrams to document your python code

Python to PlantUML

Generate Plantuml diagrams to document your python code

How it works

Features

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)
• fields for classes derived from namedtuples
• composition and inheritance relationships are drawn only between the domain classes (this is designed on purpose, for documentation sake)

Current limitations

• 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] or Dict[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 😀

• 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

If you like tools around 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

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.3.0: handle classes derived from namedtuples (attribute types are any)
• 0.2.0: handle inheritance relationships and enums. Unit tested
• 0.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

• Luc Sorel-Giffo

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):

• cb109/pyplantuml
• deadbok/py-puml-tools
• caballero/genUML