A Python DSL inspired by Structurizr, intended for generating C4 diagrams

0.1.3 · active · verified Thu Apr 16

PyStructurizr provides a Python DSL (Domain Specific Language) inspired by Structurizr, specifically designed for generating C4 diagrams. It aims to overcome limitations of the Structurizr DSL by leveraging Python's full power and flexibility for defining architectural models. The library also includes a CLI for converting Python code to Structurizr DSL, generating SVG diagrams (via Kroki.io), or uploading to cloud storage. Its latest version is 0.1.3, released in July 2023, and it maintains a somewhat active but not rapid release cadence.

Common errors

```
ModuleNotFoundError: No module named 'pystructurizr.Workspace'
```
cause Attempting to import core DSL classes (like `Workspace`, `Person`, `SoftwareSystem`, etc.) directly from the top-level `pystructurizr` package instead of its `dsl` submodule.

fix Correct the import statement to target the `dsl` submodule: `from pystructurizr.dsl import Workspace`.
```
AttributeError: 'Model' object has no attribute 'Group' or SyntaxError: invalid syntax (related to `with Group(...)`)
```
cause Using features like `Group` elements or the `with` syntax for hierarchical definitions, which were introduced in `pystructurizr v0.1.3`, with an older version of the library.

fix Upgrade `pystructurizr` to the latest version: `pip install --upgrade pystructurizr`.
```
Rendering tool complains about unsupported format or invalid input when trying to display diagrams from pystructurizr output.
```
cause The output of `pystructurizr` is Structurizr DSL, which might not be directly compatible with all Structurizr rendering tools, especially those expecting the Structurizr JSON format.

fix Verify that your chosen rendering tool explicitly supports Structurizr DSL. If not, you may need to use an official Structurizr tool to convert the DSL to JSON, or use the `pystructurizr` CLI's built-in SVG export which leverages `kroki.io` for DSL rendering.

Warnings

breaking The `Group` functionality and the `with` syntax for defining nested elements were introduced in version `0.1.3`. Code written with these features will not run on earlier versions (v0.1.2 and below).
Fix: Upgrade to `pystructurizr>=0.1.3` using `pip install --upgrade pystructurizr`.
gotcha PyStructurizr primarily outputs in Structurizr DSL format, not directly in Structurizr JSON schema. Some newer Structurizr rendering tools or integrations might expect the JSON format, leading to potential compatibility issues.
Fix: If direct JSON output is required, the generated DSL might need to be converted using official Structurizr tools, or alternative Python libraries that output JSON directly should be considered. Ensure your rendering tools are compatible with Structurizr DSL.
gotcha When using the `pystructurizr` CLI to generate SVG diagrams (e.g., `workspace.save(format='svg')`), the diagram code is sent to an external online service (`kroki.io`) for rendering. Be aware of potential privacy implications if your architectural diagrams contain sensitive information.
Fix: For sensitive diagrams, consider using offline Structurizr rendering tools after generating the DSL, or review `kroki.io`'s privacy policy. The `pystructurizr` README mentions this behavior.

Install

pip install pystructurizr Install latest version

Imports

Workspace
wrong:
```
from pystructurizr import Workspace
```
correct:
```
from pystructurizr.dsl import Workspace
```
Core DSL components like Workspace, Person, SoftwareSystem, Container, etc., are located in the `pystructurizr.dsl` submodule, not directly under `pystructurizr`.

Quickstart

This quickstart demonstrates how to define a basic C4 model with a software system, containers, and relationships using PyStructurizr's DSL. It includes a basic `Workspace`, `Model`, `Person`, `SoftwareSystem`, `Container`, and `ContainerView`. The `with` syntax is used for hierarchical structuring.

from pystructurizr.dsl import Workspace

with Workspace(name="MyArchitecture") as workspace:
    with workspace.Model(name="model") as model:
        user = model.Person("User", description="A human user.")
        
        with model.SoftwareSystem("Software System", description="My awesome software system.") as software_system:
            webapp = software_system.Container("Web Application", description="Serves the user interface.")
            db = software_system.Container("Database", technology="PostgreSQL", description="Stores data.")

        user.uses(webapp, "Uses")
        webapp.uses(db, "Reads from and writes to")
    
    # Create a view onto the model
    workspace.ContainerView(
        software_system,
        "My Container View",
        "The container view of our simple software system."
    )

    # To save the workspace as Structurizr DSL (requires Structurizr CLI or compatible tool to render)
    # workspace.save(format='dsl', path='./output') 
    # To save as SVG (requires an internet connection for Kroki.io)
    # workspace.save(format='svg', path='./output')
    
    print("Workspace 'MyArchitecture' created successfully. You can extend it or use the CLI to save/generate diagrams.")

view raw JSON →