# PyStructurizr
PyStructurizr provides a Python DSL inspired by [Structurizr](https://structurizr.com/), and is intended for generating C4 diagrams.
## Overview
[Structurizr](https://structurizr.com/) builds upon "diagrams as code", allowing you to create multiple software architecture diagrams from a single model. A popular way of creating Structurizr workspaces is the Structurizr DSL.
However, Structurizr DSL has some downsides:
1. It's a custom language, with its own syntax rules and limitations
2. It has rather primitive support for splitting your diagram code over multiple files, with only `#include`-like support rather than proper imports. That makes it really hard to maintain C4 models with a team.
PyStructurizr solves that. It implements the same concepts as Structurizr DSL, but now in plain Python. That means you can use the full power and flexibility of Python to define your diagrams!
### Example
Consider the following example (as shown on Structurizr's homepage), in Structurizr DSL:
```
workspace {
model {
user = person "User"
softwareSystem = softwareSystem "Software System" {
webapp = container "Web Application" {
user -> this "Uses"
}
container "Database" {
webapp -> this "Reads from and writes to"
}
}
}
views {
container softwareSystem {
include *
autolayout lr
}
}
}
```
In PyStructurizr, this becomes:
```python
from pystructurizr.dsl import Workspace
# Create the model(s)
workspace = Workspace()
user = workspace.Model("Users").Person("User")
software_system = workspace.Model("System").SoftwareSystem("Software System")
webapp = software_system.Container("Web Application")
db = software_system.Container("Database")
# Define the relationships
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 simply software system."
)
```
For such a simple example, the benefits are not super obvious, but look at the example in this repo for something more realistic.
### CLI
PyStructurizr comes with a DSL that allows to convert your Python code to Structurizr DSL, or to immediately generate SVG versions of the diagrams. You can even upload directly to your favorite cloud storage provider: this is ideal if you want to include diagrams on blogs, wiki's, etc.
Finally, there's a development mode so you can get live preview of the diagram you're working on in your webbrowser.
## Installation
```pip install pystructurizr```
## Usage
### Convert to Structurizr DSL
```pystructurizr dump --view <path_to_view_file>```
### Live preview
```pystructurizr dev --view <path_to_view_file>```
### Convert to SVG and upload to cloud storage
```pystructurizr build --view <path_to_view_file> --gcs-credentials <path_to_credentials_json_file> --bucket-name <string> --object-name <string>```
Note that this command uses kroki.io under the hood to generate your SVG file. The benefit is that you don't need to install any tools that understand Structurizr DSL on your machine. The downside is that your diagram code is sent to an online service.
## License
MIT License
## Acknowledgements
- [Structurizr](https://structurizr.com/)
- [Kroki](https://kroki.io/)
Raw data
{
"_id": null,
"home_page": "https://github.com/nielsvanspauwen/pystructurizr",
"name": "pystructurizr",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Niels Vanspauwen",
"author_email": "niels.vanspauwen@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/45/06/d7fc38dc8a9f7cc79511c8dc53c9941753c23f079ededa2548819807e428/pystructurizr-0.1.2.tar.gz",
"platform": null,
"description": "# PyStructurizr\nPyStructurizr provides a Python DSL inspired by [Structurizr](https://structurizr.com/), and is intended for generating C4 diagrams.\n\n## Overview\n[Structurizr](https://structurizr.com/) builds upon \"diagrams as code\", allowing you to create multiple software architecture diagrams from a single model. A popular way of creating Structurizr workspaces is the Structurizr DSL.\n\nHowever, Structurizr DSL has some downsides:\n\n1. It's a custom language, with its own syntax rules and limitations\n2. It has rather primitive support for splitting your diagram code over multiple files, with only `#include`-like support rather than proper imports. That makes it really hard to maintain C4 models with a team.\n\nPyStructurizr solves that. It implements the same concepts as Structurizr DSL, but now in plain Python. That means you can use the full power and flexibility of Python to define your diagrams!\n\n### Example\nConsider the following example (as shown on Structurizr's homepage), in Structurizr DSL:\n```\nworkspace {\n model {\n user = person \"User\"\n softwareSystem = softwareSystem \"Software System\" {\n webapp = container \"Web Application\" {\n user -> this \"Uses\"\n }\n container \"Database\" {\n webapp -> this \"Reads from and writes to\"\n }\n }\n }\n views {\n container softwareSystem {\n include *\n autolayout lr\n }\n }\n}\n```\n\nIn PyStructurizr, this becomes:\n```python\nfrom pystructurizr.dsl import Workspace\n\n# Create the model(s)\nworkspace = Workspace()\nuser = workspace.Model(\"Users\").Person(\"User\")\nsoftware_system = workspace.Model(\"System\").SoftwareSystem(\"Software System\")\nwebapp = software_system.Container(\"Web Application\")\ndb = software_system.Container(\"Database\")\n\n# Define the relationships\nuser.uses(webapp, \"Uses\")\nwebapp.uses(db, \"Reads from and writes to\")\n\n# Create a view onto the model\nworkspace.ContainerView(\n software_system, \n \"My Container View\",\n \"The container view of our simply software system.\"\n)\n```\n\nFor such a simple example, the benefits are not super obvious, but look at the example in this repo for something more realistic.\n\n### CLI\nPyStructurizr comes with a DSL that allows to convert your Python code to Structurizr DSL, or to immediately generate SVG versions of the diagrams. You can even upload directly to your favorite cloud storage provider: this is ideal if you want to include diagrams on blogs, wiki's, etc.\n\nFinally, there's a development mode so you can get live preview of the diagram you're working on in your webbrowser.\n\n## Installation\n\n```pip install pystructurizr```\n\n## Usage\n\n### Convert to Structurizr DSL\n```pystructurizr dump --view <path_to_view_file>```\n\n### Live preview \n```pystructurizr dev --view <path_to_view_file>```\n\n### Convert to SVG and upload to cloud storage\n```pystructurizr build --view <path_to_view_file> --gcs-credentials <path_to_credentials_json_file> --bucket-name <string> --object-name <string>```\n\nNote that this command uses kroki.io under the hood to generate your SVG file. The benefit is that you don't need to install any tools that understand Structurizr DSL on your machine. The downside is that your diagram code is sent to an online service.\n\n## License\n\nMIT License\n\n## Acknowledgements\n\n- [Structurizr](https://structurizr.com/) \n- [Kroki](https://kroki.io/)\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python DSL inspired by Structurizr, intended for generating C4 diagrams",
"version": "0.1.2",
"project_urls": {
"Homepage": "https://github.com/nielsvanspauwen/pystructurizr"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "daec6ee2d78b5d1a595ebcb9620e84fa30c1d9db392d576fa458595ccd777833",
"md5": "8e2672bb4c01e5d9aacadf0a9ec2bb9b",
"sha256": "64713c45a4c4033a03e0f6b2ad2de1f7262401779899867674274a49d19c5bfe"
},
"downloads": -1,
"filename": "pystructurizr-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8e2672bb4c01e5d9aacadf0a9ec2bb9b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 15886,
"upload_time": "2023-06-23T21:04:08",
"upload_time_iso_8601": "2023-06-23T21:04:08.124861Z",
"url": "https://files.pythonhosted.org/packages/da/ec/6ee2d78b5d1a595ebcb9620e84fa30c1d9db392d576fa458595ccd777833/pystructurizr-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4506d7fc38dc8a9f7cc79511c8dc53c9941753c23f079ededa2548819807e428",
"md5": "a359530e5f7f02bf401173b656697542",
"sha256": "a2110b1f6473a5ed4c5fc8568eb7c26c023f26a6b29b124787c6310585ba341a"
},
"downloads": -1,
"filename": "pystructurizr-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "a359530e5f7f02bf401173b656697542",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 13093,
"upload_time": "2023-06-23T21:04:09",
"upload_time_iso_8601": "2023-06-23T21:04:09.238246Z",
"url": "https://files.pythonhosted.org/packages/45/06/d7fc38dc8a9f7cc79511c8dc53c9941753c23f079ededa2548819807e428/pystructurizr-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-23 21:04:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nielsvanspauwen",
"github_project": "pystructurizr",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "pystructurizr"
}
JSON
