Generate UML class diagrams from django models

Overview

To visualize and better understand a project structure we can create UML class diagrams from Django models.

a class diagram in the Unified Modeling Language (UML) is a type of static structure diagram that describes the structure of a system by showing the system's classes, their attributes, operations (or methods), and the relationships among objects.

We will use a special command for this task included in the django-extensions package called: graph_models

Creates a GraphViz dot file for the specified app names based on their models.py. You can pass multiple app names and they will all be combined into a single model. Output is usually directed to a dot file.

Steps

Install django extensions

Considering you already have Django installed (for this example I will use the Wagtail project), then we install django extensions with pip install django-extensions.

$ pip install django-extensions
Collecting django-extensions
  Using cached django_extensions-2.0.6-py2.py3-none-any.whl
Collecting six>=1.2 (from django-extensions)
  Using cached six-1.11.0-py2.py3-none-any.whl
Installing collected packages: six, django-extensions
Successfully installed django-extensions-2.0.6 six-1.11.0

Add to installed apps

To make your Django project aware of the new package, we add it to INSTALLED_APPS in your configuration file <project>/settings.py, in a Wagtail project called mysite this is at mysite/settings/base.py:

INSTALLED_APPS = (
    ...
    'django_extensions',
    ...
)

Install diagrams generators

You have to choose between two diagram generators:

• Graphviz or
• Dotplus

before using the command or you will get:

$ python manage.py graph_models -a -o myapp_models.png
CommandError: Neither pygraphviz nor pydotplus could be found to generate the image

But I prefer to use pydotplus as it easier to install than Graphviz and its dependencies so we use pip install pydotplus generate a dot file and then generate the image with the graphviz package.

$ sudo apt install graphviz
Reading package lists... Done
Building dependency tree       
Reading state information... Done
Suggested packages:
  graphviz-doc
The following NEW packages will be installed:
  graphviz
0 upgraded, 1 newly installed, 0 to remove and 0 not upgraded.
Need to get 590 kB of archives.
After this operation, 3.175 kB of additional disk space will be used.
Get:1 http://uy.archive.ubuntu.com/ubuntu focal/universe amd64 graphviz amd64 2.42.2-3build2 [590 kB]
Fetched 590 kB in 1s (1.078 kB/s)
Selecting previously unselected package graphviz.
(Reading database ... 149692 files and directories currently installed.)
Preparing to unpack .../graphviz_2.42.2-3build2_amd64.deb ...
Unpacking graphviz (2.42.2-3build2) ...
Setting up graphviz (2.42.2-3build2) ...
Processing triggers for man-db (2.9.1-1) ...

Generate diagrams

Now we have everything installed and ready to generate diagrams using the command python manage.py graph_models

$ python manage.py graph_models -a --dot -o myapp_models.dot
$ dot -Tpng myapp_models.dot -omyapp_models.png

This will give use the entire Wagtail class diagram:

Or grouped by application (-g):

$ ./manage.py graph_models -a -g --dot -o my_project_visualized.dot
$ dot -Tpng my_project_visualized.dot -omy_project_visualized.png

Lastly, let’s generate a class diagram for Django (v2.0.3) models:

Conclusion

Besides you probable have done the class diagram before starting the project, it can easily get outdated after a while. This is a useful technique to keep your diagrams in sync with the current status of the project.

Have a look at https://django-extensions.readthedocs.io/en/latest/graph_models.html for a full description of graph-models options.

References

• https://github.com/django-extensions/django-extensions
• https://graphviz.org/