buildzr 0.0.15__tar.gz → 0.0.17__tar.gz

{buildzr-0.0.15 → buildzr-0.0.17}/CONTRIBUTING.md

@@ -58,74 +58,80 @@ pytest --mypy tests
 
 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:
+Here's an example of a simple workspace 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
+from buildzr.dsl import (
+    Workspace,
+    SoftwareSystem,
+    Container,
+    Component,
+    Group,
+    SystemLandscapeView,
+    SystemContextView,
+    ContainerView,
+)
+
+with Workspace("w") as w:
+    with Group("Company 1"):
+        system_a = SoftwareSystem("A")
+        with system_a:
+            a1 = Container("a1")
+            a2 = Container("a2")
+
+    with Group("Company 2"):
+        system_b = SoftwareSystem("B")
+        with system_b:
+            b1 = Container("b1")
+            b2 = Container("b2")
+            with b2:
+                c1 = Component("c1")
+
+    system_c = SoftwareSystem("C")
+
+    # Define relationships
+    system_a >> "Uses" >> system_b
+    a1 >> "Uses" >> b1
+    system_a >> "Uses" >> system_c
+
+    # Create views
+    SystemLandscapeView(
+        key='groups-sample',
+        description="Groups Sample"
+    )
+
+    SystemContextView(
+        software_system_selector=system_a,
+        key='groups-sample-a',
+        description="Groups Sample - Software System A"
+    )
+
+    SystemContextView(
+        software_system_selector=system_b,
+        key='groups-sample-b',
+        description="Groups Sample - Software System B"
+    )
+
+    ContainerView(
+        software_system_selector=system_b,
+        key='groups-sample-b2',
+        description="Groups Sample - Container B2"
+    )
+
+    # Export to JSON
+    w.to_json('groups-sample.json')
 ```
 
-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.
+The example above demonstrates the current `buildzr` API using context managers (`with` statements) for a cleaner, more Pythonic syntax. Key features shown:
 
-Note that the sample class must inherit the `AbstractBuilder` class.
+- Use `with Workspace("name") as w:` to create a workspace context
+- Use `with Group("name"):` to group elements together
+- Use `with software_system:` or `with container:` to nest containers and components
+- Define relationships using the `>>` operator
+- Views and styles are created within the workspace context
+- Export using `w.to_json('filename.json')`
+
+You can run this code directly or create sample files in the `tests/samples` directory for testing purposes.
 
 ### Working with the `.json` files
 

{buildzr-0.0.15 → buildzr-0.0.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: buildzr
-Version: 0.0.15
+Version: 0.0.17
 Summary: Structurizr for the `buildzr`s 🧱⚒️
 Project-URL: homepage, https://github.com/amirulmenjeni/buildzr
 Project-URL: issues, https://github.com/amirulmenjeni/buildzr/issues
@@ -34,6 +34,9 @@ If you're not familiar with Structurizr, it is both an open standard (see [Struc
 
 In Structurizr, you define architecture models and their relationships first. And then, you can re-use the models to present multiple perspectives, views, and stories about your architecture.
 
+Head over to [ROADMAP.md](./ROADMAP.md) to get a good high-level sense of what has been implemented in `buildzr`.
+
+
 # Quick Start 🚀
 
 ## Installation

{buildzr-0.0.15 → buildzr-0.0.17}/README.md

@@ -6,6 +6,9 @@ If you're not familiar with Structurizr, it is both an open standard (see [Struc
 
 In Structurizr, you define architecture models and their relationships first. And then, you can re-use the models to present multiple perspectives, views, and stories about your architecture.
 
+Head over to [ROADMAP.md](./ROADMAP.md) to get a good high-level sense of what has been implemented in `buildzr`.
+
+
 # Quick Start 🚀
 
 ## Installation

buildzr-0.0.17/buildzr/__about__.py

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

{buildzr-0.0.15 → buildzr-0.0.17}/buildzr/dsl/dsl.py

@@ -133,12 +133,21 @@ class Workspace(DslWorkspaceElement):
         self,
     ) -> None:
 
+        """
+        Process implied relationships:
+        If we have relationship s >> do >> a.b, then create s >> do >> a.
+        If we have relationship s.ss >> do >> a.b.c, then create s.ss >> do >> a.b and s.ss >> do >> a.
+        And so on...
+
+        This process is idempotent, which means this can be called multiple times
+        without duplicating similar relationships.
+        """
+
+        if not self._use_implied_relationships:
+            return
+
         from buildzr.dsl.explorer import Explorer
 
-        # Process implied relationships:
-        # If we have relationship s >> do >> a.b, then create s >> do >> a.
-        # If we have relationship s.ss >> do >> a.b.c, then create s.ss >> do >> a.b and s.ss >> do >> a.
-        # And so on...
         explorer = Explorer(self)
         relationships = list(explorer.walk_relationships())
         for relationship in relationships:
@@ -201,8 +210,7 @@ class Workspace(DslWorkspaceElement):
         else:
             raise ValueError('Invalid element type: Trying to add an element of type {} to a workspace.'.format(type(model)))
 
-    def apply_view(
-        self,
+    def apply_view( self,
         view: Union[
             'SystemLandscapeView',
             'SystemContextView',
@@ -212,6 +220,8 @@ class Workspace(DslWorkspaceElement):
         ]
     ) -> None:
 
+        self._imply_relationships()
+
         view._on_added(self)
 
         if not self.model.views:
@@ -269,10 +279,14 @@ class Workspace(DslWorkspaceElement):
             else:
                 self.model.views.configuration.styles.relationships = style.model
 
-    def to_json(self, path: str) -> None:
+    def to_json(self, path: str, pretty: bool=False) -> None:
+
+        self._imply_relationships()
+
         from buildzr.sinks.json_sink import JsonSink, JsonSinkConfig
         sink = JsonSink()
-        sink.write(workspace=self.model, config=JsonSinkConfig(path=path))
+        sink.write(workspace=self.model, config=JsonSinkConfig(path=path, pretty=pretty))
+
 
     def _add_dynamic_attr(self, name: str, model: Union['Person', 'SoftwareSystem']) -> None:
         if isinstance(model, Person):

{buildzr-0.0.15 → buildzr-0.0.17}/buildzr/sinks/json_sink.py

@@ -9,13 +9,15 @@ from buildzr.sinks.interfaces import Sink
 @dataclass
 class JsonSinkConfig:
     path: str
+    pretty: bool = False
 
 class JsonSink(Sink[JsonSinkConfig]):
 
     def write(self, workspace: Workspace, config: Optional[JsonSinkConfig]=None) -> None:
         if config is not None:
+            indent = 2 if config.pretty else None
             with open(config.path, 'w') as file:
-                file.write(JsonEncoder().encode(workspace))
+                file.write(JsonEncoder(indent=indent).encode(workspace))
         else:
             import os
             workspace_name = workspace.name.replace(' ', '_').lower()

{buildzr-0.0.15 → buildzr-0.0.17}/tests/test_dsl.py

@@ -336,7 +336,10 @@ def test_implied_relationship() -> Optional[None]:
     # relationship. For example, u -> s.database doesn't explicitly create a u
     # -> s relationship in the workspace JSON.
 
-    # TODO: Add a way to enable/disable implied relationships in the DSL.
+    # Conditions to take into account:
+    # 1. The implied relationships method be must idempotent (e.g., if it is
+    #    called in `to_json` twice, or in other methods like `apply_view`, it
+    #    doesn't create duplicates)
 
     with Workspace("w", implied_relationships=True) as w:
         u = Person('u')
@@ -354,18 +357,42 @@ def test_implied_relationship() -> Optional[None]:
 
         u >> "Runs SQL queries" >> s.db # `u >> "Runs SQL queries" >> s`` should be implied
 
-    assert isinstance(w.u, Person)
-    assert isinstance(w.s, SoftwareSystem)
-    assert len(w.u.model.relationships) == 2 # Should have u >> R >> s and u >> R >> s.database
+        # Invoke imply relationships whenever a view is called.
+        #
+        # The implied relationship ids and related elements
+        # should appear in the view.
+        SystemContextView(
+            software_system_selector=s,
+            key='s_00',
+            description="App system context",
+        )
+
+        # Invoke imply relationships more than once.
+        # Should be no problem.
+        w.to_json('workspace.test.json')
+        w.to_json('workspace2.test.json')
+
+        assert isinstance(w.u, Person)
+        assert isinstance(w.s, SoftwareSystem)
+        assert len(w.u.model.relationships) == 2 # Should have u >> R >> s and u >> R >> s.database
+
+        assert w.u.model.relationships[0].description == "Runs SQL queries"
+        assert w.u.model.relationships[0].sourceId == w.u.model.id
+        assert w.u.model.relationships[0].destinationId == w.s.db.model.id
+
+        assert w.u.model.relationships[1].description == "Runs SQL queries"
+        assert w.u.model.relationships[1].sourceId == w.u.model.relationships[0].sourceId
+        assert w.u.model.relationships[1].destinationId == w.s.model.id
+        assert w.u.model.relationships[1].linkedRelationshipId == w.u.model.relationships[0].id
 
-    assert w.u.model.relationships[0].description == "Runs SQL queries"
-    assert w.u.model.relationships[0].sourceId == w.u.model.id
-    assert w.u.model.relationships[0].destinationId == w.s.db.model.id
+        system_context_view_elements = [x.id for x in w._m.views.systemContextViews[0].elements]
+        assert u.model.id in system_context_view_elements
+        assert s.model.id in system_context_view_elements
 
-    assert w.u.model.relationships[1].description == "Runs SQL queries"
-    assert w.u.model.relationships[1].sourceId == w.u.model.relationships[0].sourceId
-    assert w.u.model.relationships[1].destinationId == w.s.model.id
-    assert w.u.model.relationships[1].linkedRelationshipId == w.u.model.relationships[0].id
+        system_context_view_relationships = [x.id for x in w._m.views.systemContextViews[0].relationships]
+        assert w.u.model.relationships[0].id not in system_context_view_relationships
+        assert w.u.model.relationships[1].id in system_context_view_relationships
+        assert w.u.model.relationships[1].linkedRelationshipId == w.u.model.relationships[0].id
 
 def test_tags_on_elements() -> Optional[None]:
 

buildzr-0.0.15/buildzr/__about__.py

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