Diagrams as Code with Python

 In my career I have noticed that often organizations are reluctant on providing Engineering teams with licenses for software to draw diagrams. In the best case scenarios MS Visio is usually the only option available, which isn’t the best experience when trying to draw modern software architectures. Several online options are available, but they require to share project details that cannot leave your organization network, so they couldn’t be taken into account often. Also, while treating everything as code, it would be nice to have also diagrams as code. All these needs can be satisfied by adopting Diagrams. It is an Open Source Python package that allows you draw cloud system architecture diagrams programmatically and then put them under version control, (as at the end they are regular Python files). It supports cloud (AWS, Azure, GCP, Alibaba, Oracle) and on-prem system architecture diagrams. The Diagrams nodes include also Kubernetes, programming languages and frameworks.

Diagrams supports Python 3.6+ and requires the Open Source Graphviz visualization software for the rendering. Once Graphviz has been installed, Diagrams can be obtained through PyPI or Anaconda.

Diagrams is intuitive to use and it is based on the following concepts:

  • Diagram: self-explaining :)
  • Node: a single system component object.
  • Cluster: a local cluster context.
  • Edge: a connection between nodes. They come with several additional properties.

The official Diagrams documentation is comprehensive, so I am not going to deep dive into available components, but I am going to show a concrete code example to generate a diagram for a generic AWS serverless data integration hub:

Once this source code has been saved, it can be executed same as any other Python script:


At the end of the execution it produces a PNG image (PNG is the default format if a different one among those (others are JPG, SVG and PDF) supported by Diagrams hasn’t been specified) in the same directory where the script has been executed. The image name is derived from the label specified for the Diagram object. Here is the serverless_data_integration.png generated diagram:

Published on Java Code Geeks with permission by Guglielmo Iozzia, partner at our JCG program. See the original article here: Diagrams as Code with Python

Opinions expressed by Java Code Geeks contributors are their own.

Guglielmo Iozzia

Guglielmo is currenty a Big Data Delivery Lead at Optum Ireland. He has been a software engineer and architect for a variety of Java and Scala applications (Big Data, web, cloud, web services, mobile). Since 2018 he is also a frequent speaker to international conferences. His first technical book is going to be published in December 2018
Notify of

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Inline Feedbacks
View all comments
Back to top button