buildzr 0.0.16__tar.gz → 0.0.18__tar.gz

{buildzr-0.0.16 → buildzr-0.0.18}/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.16 → buildzr-0.0.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: buildzr
-Version: 0.0.16
+Version: 0.0.18
 Summary: Structurizr for the `buildzr`s 🧱⚒️
 Project-URL: homepage, https://github.com/amirulmenjeni/buildzr
 Project-URL: issues, https://github.com/amirulmenjeni/buildzr/issues

buildzr-0.0.18/buildzr/__about__.py

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

{buildzr-0.0.16 → buildzr-0.0.18}/buildzr/dsl/dsl.py

@@ -133,12 +133,24 @@ 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...
+
+        Relationships of `SoftwareSystemInstance`s and `ContainerInstance`s are
+        skipped.
+
+        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:
@@ -146,6 +158,10 @@ class Workspace(DslWorkspaceElement):
             destination = relationship.destination
             destination_parent = destination.parent
 
+            if isinstance(source, (SoftwareSystemInstance, ContainerInstance)) or \
+               isinstance(destination, (SoftwareSystemInstance, ContainerInstance)):
+                continue
+
             while destination_parent is not None and \
                 isinstance(source, DslElement) and \
                 not isinstance(source.model, buildzr.models.Workspace) and \
@@ -201,8 +217,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 +227,8 @@ class Workspace(DslWorkspaceElement):
         ]
     ) -> None:
 
+        self._imply_relationships()
+
         view._on_added(self)
 
         if not self.model.views:
@@ -269,10 +286,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.16 → buildzr-0.0.18}/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.16 → buildzr-0.0.18}/tests/test_dsl.py

@@ -15,6 +15,7 @@ from buildzr.dsl import (
     SystemContextView,
     DeploymentEnvironment,
     DeploymentNode,
+    DeploymentView,
     InfrastructureNode,
     DeploymentGroup,
     SoftwareSystemInstance,
@@ -336,7 +337,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 +358,46 @@ 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
+
+    import os
+    os.remove('workspace.test.json')
+    os.remove('workspace2.test.json')
 
 def test_tags_on_elements() -> Optional[None]:
 
@@ -1072,4 +1104,82 @@ def test_json_sink_empty_views() -> Optional[None]:
     assert data
 
     import os
-    os.remove("test.json")
+    os.remove("test.json")
+def test_deployment_instance_relationships_with_implied_relationships() -> Optional[None]:
+    """
+    Test that deployment instance relationships are created correctly when
+    implied_relationships=True, without creating duplicates.
+
+    This test ensures:
+    1. Container relationships automatically create ContainerInstance relationships
+    2. No duplicate instance relationships are created when implied_relationships=True
+    3. Instance relationships are only created once, even with multiple view/export calls
+    """
+
+    with Workspace('deployment-test', implied_relationships=True) as w:
+        # Create containers with relationships
+        ecommerce = SoftwareSystem('E-Commerce System')
+        with ecommerce:
+            api_gateway = Container('API Gateway', technology='Kong')
+            order_svc = Container('Order Service', technology='Node.js')
+            db = Container('Database', technology='MongoDB')
+
+        # Define container relationships
+        api_gateway >> "Routes to" >> order_svc
+        order_svc >> "Stores in" >> db
+
+        # Create deployment with container instances
+        with DeploymentEnvironment('Production') as prod:
+            with DeploymentNode('AWS', technology='Cloud Provider'):
+                api_gw_instance = ContainerInstance(api_gateway)
+                order_instance = ContainerInstance(order_svc)
+                db_instance = ContainerInstance(db)
+
+        # Create views and export (triggers implied relationships multiple times)
+        SystemContextView(
+            software_system_selector=ecommerce,
+            key='test-system-context',
+            description="Test System Context",
+        )
+
+        DeploymentView(
+            environment=prod,
+            key='test-deployment',
+        )
+
+        # Export multiple times to ensure idempotency
+        w.to_json('test_deployment1.json')
+        w.to_json('test_deployment2.json')
+
+    # Verify instance relationships exist
+    assert api_gw_instance.model.relationships is not None
+    assert order_instance.model.relationships is not None
+
+    # Get all instance relationships
+    api_gw_rels = api_gw_instance.model.relationships
+    order_rels = order_instance.model.relationships
+
+    # Should have exactly 1 relationship from api_gw_instance to order_instance
+    api_to_order_rels = [
+        r for r in api_gw_rels
+        if r.destinationId == order_instance.model.id
+    ]
+    assert len(api_to_order_rels) == 1, f"Expected 1 relationship, found {len(api_to_order_rels)}"
+    assert api_to_order_rels[0].description == "Routes to"
+
+    # Should have exactly 1 relationship from order_instance to db_instance
+    order_to_db_rels = [
+        r for r in order_rels
+        if r.destinationId == db_instance.model.id
+    ]
+    assert len(order_to_db_rels) == 1, f"Expected 1 relationship, found {len(order_to_db_rels)}"
+    assert order_to_db_rels[0].description == "Stores in"
+
+    # Verify linkedRelationshipId is set correctly
+    assert api_to_order_rels[0].linkedRelationshipId is not None
+    assert order_to_db_rels[0].linkedRelationshipId is not None
+
+    # Clean up
+    import os
+    os.remove('test_deployment1.json')
+    os.remove('test_deployment2.json')

{buildzr-0.0.16 → buildzr-0.0.18}/tests/test_explorer.py

@@ -90,7 +90,7 @@ def test_walk_relationships(workspace: Workspace) -> Optional[None]:
 
     # 5 explicit relationships.
     # Add one additional implied relationship.
-    # And four additional from container instances for each two container instance (2x2=4 + 2x2=4 more).
+    # And four additional from container instances for each two container instance (2x2=4).
     #
     # Explanation: if we have containers A and B with relationship A >> "Uses" >> B,
     # and container instances ci_A_1, ci_A_2, ci_B_1, ci_B_2, then we have the
@@ -99,7 +99,7 @@ def test_walk_relationships(workspace: Workspace) -> Optional[None]:
     #   ci_A_1 >> "Uses" >> ci_B_2
     #   ci_A_2 >> "Uses" >> ci_B_1
     #   ci_A_2 >> "Uses" >> ci_B_2
-    assert len(relationships) == 14
+    assert len(relationships) == 10
 
     for relationship in relationships:
         relationship_set = (

buildzr-0.0.16/buildzr/__about__.py

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