buildzr 0.0.1__tar.gz

buildzr-0.0.1/.gitignore

@@ -0,0 +1,18 @@
+# Environment variables.
+.env
+
+# Python artefacts and caches.
+**/__pycache__
+*.egg-info
+
+# Temporary files are stored here -- used by scripts during development.
+*.tmp
+
+# Tests artefacts
+tests/samples/.tests.**.json
+tests/samples/*.puml
+tests/structurizr_dsl_samples
+
+# Build artefacts.
+build
+dist

buildzr-0.0.1/CONTRIBUTING.md

@@ -0,0 +1,158 @@
+# Contributing to buildzr
+
+Thank you for considering contributing to buildzr! Your help is greatly appreciated. Below are some guidelines to help you get started.
+
+_Happy Hacking 👩‍💻!_
+
+## Getting Started
+
+### Codespaces
+
+I recommend using GitHub Codespaces for development. Codespaces provides a consistent development environment and simplifies the setup process.
+
+You can quickly set up and start contributing to our project using GitHub Codespaces via GitHub CLI. Follow these steps:
+
+1. Install the GitHub CLI if you haven't already. Visit https://cli.github.com/.
+
+2. Authenticate with your GitHub account by running:
+
+    ```bash
+    gh auth login
+    ```
+
+3. Create a new codespace for this repository using the following command:
+
+    ```bash
+    gh codespace create -r amirulmenjeni/buildzr -b feature/my-aweseome-contrib
+    ```
+
+4. Once the codespace is created, you can [connect to it via VS Code](https://docs.github.com/en/codespaces/developing-in-a-codespace/using-github-codespaces-in-visual-studio-code#opening-a-codespace-in-vs-code) or `ssh`
+   into it:
+
+    ```bash
+    gh codespace ssh
+    ```
+
+5. Inside the workspace, setup and activate the Python environment:
+
+    ```bash
+    conda env create -f environment.yml
+    ```
+
+    To activate:
+
+    ```bash
+    conda activate buildzr-dev
+    ```
+
+The codespace environment also includes useful tools developed by the Structurizr team such as [Structurizr CLI](https://docs.structurizr.com/cli) and [Structurizr Lite](https://docs.structurizr.com/lite) to view diagrams defined in [Structurizr DSL](https://docs.structurizr.com/dsl) or [JSON](https://structurizr.com/json). They're mostly helpful during development to validate the [Structurizr JSON schema](https://github.com/structurizr/json) generated by `buildzr`.
+
+### Running Tests
+
+All tests are located in the `tests` folder. To run the tests, use the following command:
+```sh
+pytest --mypy tests
+```
+
+### Testing `buildzr` Samples
+
+Sometimes it is valuable to manually check the output of the Structurizr workspace generated by `buildzr` visually. For this reason, you can create `buildzr` samples in the [`tests/samples`](https://github.com/amirulmenjeni/buildzr/tree/master/tests/samples) directory.
+
+Here's an example of the [`GroupSample`](https://github.com/amirulmenjeni/buildzr/blob/master/tests/samples/groups.py), to showcase the [group](https://docs.structurizr.com/dsl/cookbook/groups/) feature in Structurizr DSL used for grouping elements together:
+
+```python
+import buildzr
+from buildzr.dsl import *
+from ..abstract_builder import AbstractBuilder
+
+class GroupsSample(AbstractBuilder):
+
+    def build(self) -> buildzr.models.Workspace:
+
+        w = Workspace("w", scope=None)\
+            .contains(
+                Group(
+                    "Company 1",
+                    SoftwareSystem("A")\
+                    .contains(
+                        Container("a1"),
+                        Container("a2"),
+                    )
+                ),
+                Group(
+                    "Company 2",
+                    SoftwareSystem("B")\
+                    .contains(
+                        Container("b1"),
+                        Container("b2")
+                        .contains(
+                            Component("c1"),
+                        )
+                    )
+                ),
+                SoftwareSystem("C"),
+            )\
+            .where(lambda w: [
+                w.software_system().a >> "Uses" >> w.software_system().b,
+                w.software_system().a.container().a1 >> "Uses" >> w.software_system().b.container().b1,
+                w.software_system().a >> "Uses" >> w.software_system().c,
+            ])\
+            .with_views(
+                SystemLandscapeView(
+                    key='groups-sample',
+                    description="Groups Sample"
+                ),
+                SystemContextView(
+                    key='groups-sample-a',
+                    software_system_selector=lambda w: cast(SoftwareSystem, w.a),
+                    description="Groups Sample - Software System A"
+                ),
+                SystemContextView(
+                    key='groups-sample-b',
+                    software_system_selector=lambda w: cast(SoftwareSystem, w.b),
+                    description="Groups Sample - Software System B"
+                ),
+                ContainerView(
+                    key='groups-sample-b2',
+                    software_system_selector=lambda w: w.software_system().b,
+                    description="Groups Sample - Container B2"
+                ),
+            )\
+            .get_workspace()
+
+        return w.model
+```
+
+By running `pytest tests/test_workspaces.py`, all the sample workspaces would be built, creating the corresponding JSON file with Structurizr schema. In the case of the `GroupSample` class, for example, the resulting output file path would be `tests/samples/.tests.samples.groups.json` -- named after the name of the Python file that contains the `GroupSample` class.
+
+Note that the sample class must inherit the `AbstractBuilder` class.
+
+### Working with the `.json` files
+
+What can you do with the generated `.json` files?
+
+As mentioned, the `.json` file, if successfully and correctly generated using
+`buildzr`, should follow the Structurizr JSON schema. Thus you can make use of existing and mature Structurizr tools such as the [Structurizr CLI](https://docs.structurizr.com/cli) and [Structurizr Lite](https://docs.structurizr.com/lite).
+
+If you use codespaces (_highly recommended_), these tools are already pre-installed in the devcontainer image.
+
+For example, to export the `tests/samples/.tests.samples.groups.json` to other format (say, [PlantUML](https://plantuml.com/)):
+
+```bash
+structurizr.sh \
+    export \
+    --format plantuml \
+    --workspace tests/samples/.tests.samples.groups.json \
+    --output tests/samples/.tests.samples.groups.puml
+```
+
+To view the rendering of `tests/samples/.tests.samples.groups.json` in the
+browser at http://localhost:8080:
+
+```bash
+structurizr-lite.sh tests/samples/.tests.samples.groups.json
+```
+
+## Submitting Changes
+
+As usual, just fork the repo, make changes, and submit PRs!

buildzr-0.0.1/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Amirul Menjeni
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

buildzr-0.0.1/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.3
+Name: buildzr
+Version: 0.0.1
+Summary: Structurizr for the `buildzr`s 🧱⚒️
+Project-URL: homepage, https://github.com/amirulmenjeni/buildzr
+Project-URL: issues, https://github.com/amirulmenjeni/buildzr/issues
+Author-email: Amirul Menjeni <amirulmenjeni@pm.me>
+License-File: LICENSE.md
+Keywords: architecture,buildzr,c4model,design,diagram,structurizr
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Requires-Dist: pyhumps==3.8.0
+Requires-Dist: pytest>=8.3.3
+Provides-Extra: dev
+Requires-Dist: datamodel-code-generator==0.26.2; extra == 'dev'
+Requires-Dist: jsondiff==2.0.0; extra == 'dev'
+Requires-Dist: mypy-extensions==1.0.0; extra == 'dev'
+Requires-Dist: mypy==1.11.2; extra == 'dev'
+Requires-Dist: pytest-mypy==0.10.3; extra == 'dev'
+Requires-Dist: yq==3.4.3; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Structurizr for the `buildzr`s 🧱⚒️
+
+`buildzr` is a [Structurizr](https://structurizr.com/) authoring tool for Python programmers.
+
+If you're not familiar with Structurizr, it is both an open standard (see [Structurizr JSON schema](https://github.com/structurizr/json)) and a [set of tools](https://docs.structurizr.com/usage) for building software architecture diagrams as code. Structurizr derive its architecture modeling paradigm based on the [C4 model](https://c4model.com/), the modeling language for visualizing software architecture.
+
+`buildzr` offers flexible and fluent APIs to write software architecture models based on the C4 model, leveraging the standard Structurizr JSON schema for interoperability with various rendering and authoring tools.
+
+# Quick Start 🚀
+
+## Installation
+
+_TODO_
+
+## Creating a workspace
+
+The module `buildzr.dsl` contains all the classes you need to create a workspace containing all the architecture models.
+
+Below is an example, where we:
+1. Create the models (`Person`, `SoftwareSystem`s, the `Container`s inside the `SoftwareSystem`, and the relationships between them)
+2. Define multiple views using the models we've created before.
+
+```python
+import os
+import json
+
+from buildzr.encoders import JsonEncoder
+
+from buildzr.dsl import (
+    Workspace,
+    SoftwareSystem,
+    Person,
+    Container,
+    SystemContextView,
+    ContainerView,
+    desc,
+    Group,
+)
+
+w = Workspace('w')\
+    .contains(
+        Group(
+            "My Company",
+            Person('Web Application User').labeled('u'),
+            SoftwareSystem('Corporate Web App').labeled('webapp')
+            .contains(
+                Container('database'),
+                Container('api'),
+            )\
+            .where(lambda s: [
+                s.api >> "Reads and writes data from/to" >> s.database,
+            ])
+        ),
+        Group(
+            "Microsoft",
+            SoftwareSystem('Microsoft 365').labeled('email_system'),
+        )
+    )\
+    .where(lambda w: [
+        w.person().u >> [
+            desc("Reads and writes email using") >> w.software_system().email_system,
+            desc("Create work order using") >> w.software_system().webapp,
+        ],
+        w.software_system().webapp >> "sends notification using" >> w.software_system().email_system,
+    ])\
+    .with_views(
+        SystemContextView(
+            lambda w: w.software_system().webapp,
+            key='web_app_system_context_00',
+            description="Web App System Context",
+            auto_layout='lr',
+            exclude_elements=[
+                lambda w, e: w.person().user == e,
+            ]
+        ),
+        ContainerView(
+            lambda w: w.software_system().webapp,
+            key='web_app_container_view_00',
+            auto_layout='lr',
+            description="Web App Container View",
+        )
+    )\
+    .get_workspace()
+
+# Writes the Workspace model to a JSON file.
+with open(os.path.join(os.path.curdir, f"{__file__.split('.')[0]}.json"), 'w', encoding='utf-8') as f:
+    json.dump(w.model, f, ensure_ascii=False, indent=4, cls=JsonEncoder)
+```
+
+That's it 😊!
+
+The JSON output can be found [here](examples/system_context_and_container_view.json). You can also try out https://structurizr.com/json to see how this workspace will be rendered.
+
+# Why use `buildzr`?
+
+✅ Uses fluent APIs to help you create C4 model architecture diagrams in Python concisely.
+
+✅ Write Structurizr diagrams more securely with extensive type hints and [mypy](https://mypy-lang.org) support.
+
+✅ Stays true to the [Structurizr JSON schema](https://mypy-lang.org/) standards. `buildzr` uses the [datamodel-code-generator](https://github.com/koxudaxi/datamodel-code-generator) to automatically generate the "low-level" [representation](buildzr/models/models.py) of the Workspace model. This reduces deprecancy between `buildzr` and the Structurizr JSON schema.
+
+✅ Writing architecture diagrams in Python allows you to integrate programmability and automation into your software architecture diagramming and documentation workflow.
+
+✅ Uses the familiar Python programming language to write predicates for including/excluding elements and relationships in views.
+
+# Contributing
+
+Interested in contributing to `buildzr`?
+
+Please visit [CONTRIBUTING.md](CONTRIBUTING.md).

buildzr-0.0.1/README.md

@@ -0,0 +1,110 @@
+# Structurizr for the `buildzr`s 🧱⚒️
+
+`buildzr` is a [Structurizr](https://structurizr.com/) authoring tool for Python programmers.
+
+If you're not familiar with Structurizr, it is both an open standard (see [Structurizr JSON schema](https://github.com/structurizr/json)) and a [set of tools](https://docs.structurizr.com/usage) for building software architecture diagrams as code. Structurizr derive its architecture modeling paradigm based on the [C4 model](https://c4model.com/), the modeling language for visualizing software architecture.
+
+`buildzr` offers flexible and fluent APIs to write software architecture models based on the C4 model, leveraging the standard Structurizr JSON schema for interoperability with various rendering and authoring tools.
+
+# Quick Start 🚀
+
+## Installation
+
+_TODO_
+
+## Creating a workspace
+
+The module `buildzr.dsl` contains all the classes you need to create a workspace containing all the architecture models.
+
+Below is an example, where we:
+1. Create the models (`Person`, `SoftwareSystem`s, the `Container`s inside the `SoftwareSystem`, and the relationships between them)
+2. Define multiple views using the models we've created before.
+
+```python
+import os
+import json
+
+from buildzr.encoders import JsonEncoder
+
+from buildzr.dsl import (
+    Workspace,
+    SoftwareSystem,
+    Person,
+    Container,
+    SystemContextView,
+    ContainerView,
+    desc,
+    Group,
+)
+
+w = Workspace('w')\
+    .contains(
+        Group(
+            "My Company",
+            Person('Web Application User').labeled('u'),
+            SoftwareSystem('Corporate Web App').labeled('webapp')
+            .contains(
+                Container('database'),
+                Container('api'),
+            )\
+            .where(lambda s: [
+                s.api >> "Reads and writes data from/to" >> s.database,
+            ])
+        ),
+        Group(
+            "Microsoft",
+            SoftwareSystem('Microsoft 365').labeled('email_system'),
+        )
+    )\
+    .where(lambda w: [
+        w.person().u >> [
+            desc("Reads and writes email using") >> w.software_system().email_system,
+            desc("Create work order using") >> w.software_system().webapp,
+        ],
+        w.software_system().webapp >> "sends notification using" >> w.software_system().email_system,
+    ])\
+    .with_views(
+        SystemContextView(
+            lambda w: w.software_system().webapp,
+            key='web_app_system_context_00',
+            description="Web App System Context",
+            auto_layout='lr',
+            exclude_elements=[
+                lambda w, e: w.person().user == e,
+            ]
+        ),
+        ContainerView(
+            lambda w: w.software_system().webapp,
+            key='web_app_container_view_00',
+            auto_layout='lr',
+            description="Web App Container View",
+        )
+    )\
+    .get_workspace()
+
+# Writes the Workspace model to a JSON file.
+with open(os.path.join(os.path.curdir, f"{__file__.split('.')[0]}.json"), 'w', encoding='utf-8') as f:
+    json.dump(w.model, f, ensure_ascii=False, indent=4, cls=JsonEncoder)
+```
+
+That's it 😊!
+
+The JSON output can be found [here](examples/system_context_and_container_view.json). You can also try out https://structurizr.com/json to see how this workspace will be rendered.
+
+# Why use `buildzr`?
+
+✅ Uses fluent APIs to help you create C4 model architecture diagrams in Python concisely.
+
+✅ Write Structurizr diagrams more securely with extensive type hints and [mypy](https://mypy-lang.org) support.
+
+✅ Stays true to the [Structurizr JSON schema](https://mypy-lang.org/) standards. `buildzr` uses the [datamodel-code-generator](https://github.com/koxudaxi/datamodel-code-generator) to automatically generate the "low-level" [representation](buildzr/models/models.py) of the Workspace model. This reduces deprecancy between `buildzr` and the Structurizr JSON schema.
+
+✅ Writing architecture diagrams in Python allows you to integrate programmability and automation into your software architecture diagramming and documentation workflow.
+
+✅ Uses the familiar Python programming language to write predicates for including/excluding elements and relationships in views.
+
+# Contributing
+
+Interested in contributing to `buildzr`?
+
+Please visit [CONTRIBUTING.md](CONTRIBUTING.md).

buildzr-0.0.1/buildzr/__about__.py

@@ -0,0 +1 @@
+VERSION = "0.0.1"

buildzr-0.0.1/buildzr/__init__.py

@@ -0,0 +1,4 @@
+from . import models
+from . import encoders
+from .dsl import interfaces
+from .dsl import expression

buildzr-0.0.1/buildzr/dsl/__init__.py

@@ -0,0 +1,18 @@
+from .dsl import (
+    Workspace,
+    SoftwareSystem,
+    Person,
+    Container,
+    Component,
+    Group,
+    SystemLandscapeView,
+    SystemContextView,
+    ContainerView,
+    ComponentView,
+)
+from .relations import (
+    desc,
+    With,
+)
+from .explorer import Explorer
+from .expression import Expression