{"id":9241,"library":"pystructurizr","title":"A Python DSL inspired by Structurizr, intended for generating C4 diagrams","description":"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.","status":"active","version":"0.1.3","language":"en","source_language":"en","source_url":"https://github.com/nielsvanspauwen/pystructurizr","tags":["c4-model","architecture-as-code","diagrams-as-code","dsl","structurizr","python-dsl"],"install":[{"cmd":"pip install pystructurizr","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"Core DSL components like Workspace, Person, SoftwareSystem, Container, etc., are located in the `pystructurizr.dsl` submodule, not directly under `pystructurizr`.","wrong":"from pystructurizr import Workspace","symbol":"Workspace","correct":"from pystructurizr.dsl import Workspace"}],"quickstart":{"code":"from pystructurizr.dsl import Workspace\n\nwith Workspace(name=\"MyArchitecture\") as workspace:\n    with workspace.Model(name=\"model\") as model:\n        user = model.Person(\"User\", description=\"A human user.\")\n        \n        with model.SoftwareSystem(\"Software System\", description=\"My awesome software system.\") as software_system:\n            webapp = software_system.Container(\"Web Application\", description=\"Serves the user interface.\")\n            db = software_system.Container(\"Database\", technology=\"PostgreSQL\", description=\"Stores data.\")\n\n        user.uses(webapp, \"Uses\")\n        webapp.uses(db, \"Reads from and writes to\")\n    \n    # Create a view onto the model\n    workspace.ContainerView(\n        software_system,\n        \"My Container View\",\n        \"The container view of our simple software system.\"\n    )\n\n    # To save the workspace as Structurizr DSL (requires Structurizr CLI or compatible tool to render)\n    # workspace.save(format='dsl', path='./output') \n    # To save as SVG (requires an internet connection for Kroki.io)\n    # workspace.save(format='svg', path='./output')\n    \n    print(\"Workspace 'MyArchitecture' created successfully. You can extend it or use the CLI to save/generate diagrams.\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade to `pystructurizr>=0.1.3` using `pip install --upgrade pystructurizr`.","message":"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).","severity":"breaking","affected_versions":"< 0.1.3"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions with CLI SVG generation"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Correct the import statement to target the `dsl` submodule: `from pystructurizr.dsl import 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.","error":"ModuleNotFoundError: No module named 'pystructurizr.Workspace'"},{"fix":"Upgrade `pystructurizr` to the latest version: `pip install --upgrade pystructurizr`.","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.","error":"AttributeError: 'Model' object has no attribute 'Group' or SyntaxError: invalid syntax (related to `with Group(...)`)"},{"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.","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.","error":"Rendering tool complains about unsupported format or invalid input when trying to display diagrams from pystructurizr output."}]}