buildzr 0.0.4__tar.gz → 0.0.6__tar.gz

{buildzr-0.0.4 → buildzr-0.0.6}/PKG-INFO

@@ -1,11 +1,10 @@
 Metadata-Version: 2.3
 Name: buildzr
-Version: 0.0.4
+Version: 0.0.6
 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
@@ -118,15 +117,15 @@ w = Workspace('w')\
     )\
     .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)
+# Save workspace to a JSON file following the Structurizr JSON schema.
+w.to_json('workspace.json')
 ```
 
 Here's a short breakdown on what's happening:
 - In `Workspace(...).contains(...)` method, we define the _static_ C4 models (i.e., `Person`, `SoftwareSystem`, and the `Container`s in the software system).
 - In the `Workspace(...).contains(...).where(...)`, we define the relationships between the C4 models in the workspace. We access the models via the `w` parameter in the `lambda` function, and create the relationships using the `>>` operators.
-- Finally, once we have all the models and their relationships defined, we use (and re-use!) the static models to create multiple views to tell different stories and show various narrative to help document your software architecture.
+- Once we have all the models and their relationships defined, we use (and re-use!) the static models to create multiple views to tell different stories and show various narrative to help document your software architecture.
+- Finally, we write the workspace definitions into a JSON file, which can be consumed by rendering tools, or used for further processing.
 
 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.
 

{buildzr-0.0.4 → buildzr-0.0.6}/README.md

@@ -88,15 +88,15 @@ w = Workspace('w')\
     )\
     .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)
+# Save workspace to a JSON file following the Structurizr JSON schema.
+w.to_json('workspace.json')
 ```
 
 Here's a short breakdown on what's happening:
 - In `Workspace(...).contains(...)` method, we define the _static_ C4 models (i.e., `Person`, `SoftwareSystem`, and the `Container`s in the software system).
 - In the `Workspace(...).contains(...).where(...)`, we define the relationships between the C4 models in the workspace. We access the models via the `w` parameter in the `lambda` function, and create the relationships using the `>>` operators.
-- Finally, once we have all the models and their relationships defined, we use (and re-use!) the static models to create multiple views to tell different stories and show various narrative to help document your software architecture.
+- Once we have all the models and their relationships defined, we use (and re-use!) the static models to create multiple views to tell different stories and show various narrative to help document your software architecture.
+- Finally, we write the workspace definitions into a JSON file, which can be consumed by rendering tools, or used for further processing.
 
 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.
 

buildzr-0.0.6/buildzr/__about__.py

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

{buildzr-0.0.4 → buildzr-0.0.6}/buildzr/dsl/dsl.py

@@ -26,10 +26,14 @@ from typing import (
     Type,
 )
 
+from buildzr.sinks.interfaces import Sink
+
 from buildzr.dsl.interfaces import (
     DslWorkspaceElement,
     DslElement,
+    DslViewElement,
     DslViewsElement,
+    DslFluentSink,
     TSrc, TDst,
     TParent, TChild,
 )
@@ -45,20 +49,6 @@ from buildzr.dsl.relations import (
 def _child_name_transform(name: str) -> str:
     return name.lower().replace(' ', '_')
 
-# TODO: Remove, not used.
-# def _create_linked_relationship_from(
-#     relationship: '_Relationship[TSrc, TDst]') -> buildzr.models.Relationship:
-
-#     src = relationship.source
-#     dst = relationship.destination
-
-#     return buildzr.models.Relationship(
-#         id=GenerateId.for_relationship(),
-#         sourceId=str(src.model.id),
-#         destinationId=str(dst.parent.model.id),
-#         linkedRelationshipId=relationship.model.id,
-#     )
-
 TypedModel = TypeVar('TypedModel')
 class TypedDynamicAttribute(Generic[TypedModel]):
 
@@ -197,7 +187,7 @@ class Workspace(DslWorkspaceElement):
             'ContainerView',
             'ComponentView',
         ]
-    ) -> 'Views':
+    ) -> '_FluentSink':
         return Views(self).contains(*views)
 
     def __getattr__(self, name: str) -> Union['Person', 'SoftwareSystem']:
@@ -487,6 +477,16 @@ class Group:
         self._name = name
         self._elements = elements
 
+class _FluentSink(DslFluentSink):
+
+    def __init__(self, workspace: Workspace) -> None:
+        self._workspace = workspace
+
+    def to_json(self, path: str) -> None:
+        from buildzr.sinks.json_sink import JsonSink, JsonSinkConfig
+        sink = JsonSink()
+        sink.write(workspace=self._workspace.model, config=JsonSinkConfig(path=path))
+
 _RankDirection = Literal['tb', 'bt', 'lr', 'rl']
 
 _AutoLayout = Optional[
@@ -554,7 +554,7 @@ def _auto_layout_to_model(auto_layout: _AutoLayout) -> buildzr.models.AutomaticL
 
     return model
 
-class SystemLandscapeView:
+class SystemLandscapeView(DslViewElement):
 
     from buildzr.dsl.expression import Expression, Element, Relationship
 
@@ -649,7 +649,7 @@ class SystemLandscapeView:
         for relationship_id in relationship_ids:
             self._m.relationships.append(RelationshipView(id=relationship_id))
 
-class SystemContextView:
+class SystemContextView(DslViewElement):
 
     """
     If no filter is applied, this view includes all elements that have a direct
@@ -700,9 +700,6 @@ class SystemContextView:
         from buildzr.dsl.expression import Expression, Element, Relationship
         from buildzr.models import ElementView, RelationshipView
 
-        # TODO: Refactor below codes. Similar patterns may exists for other views.
-        # Maybe make the views a subclass of some abstract `BaseView` class?
-
         software_system = self._selector(self._parent._parent)
         self._m.softwareSystemId = software_system.model.id
         view_elements_filter: List[Callable[[Workspace, Element], bool]] = [
@@ -711,10 +708,6 @@ class SystemContextView:
             lambda w, e: software_system.model.id in e.destinations.ids,
         ]
 
-        # TODO: (Or, TOTHINK?) The code below includes all sources and all
-        # destinations of the subject software system. What if we want to
-        # exclude a source? Maybe the predicates in `elements` and
-        # `relationships` should be ANDed together afterall?
         view_relationships_filter: List[Callable[[Workspace, Relationship], bool]] = [
             lambda w, r: software_system == r.source,
             lambda w, r: software_system == r.destination,
@@ -747,7 +740,7 @@ class SystemContextView:
         for relationship_id in relationship_ids:
             self._m.relationships.append(RelationshipView(id=relationship_id))
 
-class ContainerView:
+class ContainerView(DslViewElement):
 
     from buildzr.dsl.expression import Expression, Element, Relationship
 
@@ -836,7 +829,7 @@ class ContainerView:
         for relationship_id in relationship_ids:
             self._m.relationships.append(RelationshipView(id=relationship_id))
 
-class ComponentView:
+class ComponentView(DslViewElement):
 
     from buildzr.dsl.expression import Expression, Element, Relationship
 
@@ -945,34 +938,33 @@ class Views(DslViewsElement):
 
     def contains(
         self,
-        *views: Union[
-            SystemLandscapeView,
-            SystemContextView,
-            ContainerView,
-            ComponentView,
-        ]) -> Self:
+        *views: DslViewElement
+    ) -> _FluentSink:
 
         for view in views:
-            view._parent = self
             if isinstance(view, SystemLandscapeView):
+                view._parent = self
                 view._on_added()
                 if self._m.systemLandscapeViews:
                     self._m.systemLandscapeViews.append(view.model)
                 else:
                     self._m.systemLandscapeViews = [view.model]
             elif isinstance(view, SystemContextView):
+                view._parent = self
                 view._on_added()
                 if self._m.systemContextViews:
                     self._m.systemContextViews.append(view.model)
                 else:
                     self._m.systemContextViews = [view.model]
             elif isinstance(view, ContainerView):
+                view._parent = self
                 view._on_added()
                 if self._m.containerViews:
                     self._m.containerViews.append(view.model)
                 else:
                     self._m.containerViews = [view.model]
             elif isinstance(view, ComponentView):
+                view._parent = self
                 view._on_added()
                 if self._m.componentViews:
                     self._m.componentViews.append(view.model)
@@ -981,7 +973,7 @@ class Views(DslViewsElement):
             else:
                 raise NotImplementedError("The view {0} is currently not supported", type(view))
 
-        return self
+        return _FluentSink(self._parent)
 
     def get_workspace(self) -> Workspace:
         """

{buildzr-0.0.4 → buildzr-0.0.6}/buildzr/dsl/interfaces/__init__.py

@@ -1,8 +1,10 @@
 from .interfaces import (
     DslElement,
     DslFluentRelationship,
+    DslFluentSink,
     DslRelationship,
     DslWorkspaceElement,
+    DslViewElement,
     DslViewsElement,
     BindLeft,
     BindRight,

{buildzr-0.0.4 → buildzr-0.0.6}/buildzr/dsl/interfaces/interfaces.py

@@ -199,6 +199,36 @@ class DslFluentRelationship(ABC, Generic[TParent]):
     def get(self) -> TParent:
         pass
 
+class DslFluentSink(ABC):
+
+    @abstractmethod
+    def to_json(self, path: str) -> None:
+        pass
+
+class DslViewElement(ABC):
+
+    ViewModel = Union[
+        buildzr.models.SystemLandscapeView,
+        buildzr.models.SystemContextView,
+        buildzr.models.ContainerView,
+        buildzr.models.ComponentView,
+        buildzr.models.DynamicView,
+        buildzr.models.DeploymentView,
+    ]
+
+    @property
+    @abstractmethod
+    def model(self) -> ViewModel:
+        pass
+
+    @property
+    @abstractmethod
+    def parent(self) -> 'DslViewsElement':
+        pass
+
+    def _on_added(self) -> None:
+        pass
+
 class DslViewsElement(ABC):
 
     @property
@@ -209,4 +239,11 @@ class DslViewsElement(ABC):
     @property
     @abstractmethod
     def parent(self) -> DslWorkspaceElement:
+        pass
+
+    @abstractmethod
+    def contains(
+        self,
+        *views: Union[DslViewElement],
+    ) -> DslFluentSink:
         pass

buildzr-0.0.6/buildzr/sinks/interfaces.py

@@ -0,0 +1,18 @@
+from typing import (
+    Optional,
+    Any,
+    TypedDict,
+    TypeVar,
+    Generic,
+)
+from dataclasses import dataclass
+from abc import ABC, abstractmethod
+from buildzr.models.models import Workspace
+
+TConfig = TypeVar('TConfig')
+
+class Sink(ABC, Generic[TConfig]):
+
+    @abstractmethod
+    def write(self, workspace: Workspace, config: Optional[TConfig]=None) -> None:
+        pass

buildzr-0.0.6/buildzr/sinks/json_sink.py

@@ -0,0 +1,24 @@
+from typing import (
+    Optional,
+)
+from dataclasses import dataclass
+from buildzr.models.models import Workspace
+from buildzr.encoders.encoder import JsonEncoder
+from buildzr.sinks.interfaces import Sink
+
+@dataclass
+class JsonSinkConfig:
+    path: str
+
+class JsonSink(Sink[JsonSinkConfig]):
+
+    def write(self, workspace: Workspace, config: Optional[JsonSinkConfig]=None) -> None:
+        if config is not None:
+            with open(config.path, 'w') as file:
+                file.write(JsonEncoder().encode(workspace))
+        else:
+            import os
+            workspace_name = workspace.name.replace(' ', '_').lower()
+
+            with open(os.path.join(os.curdir, f'{workspace_name}.json'), 'w') as file:
+                file.write(JsonEncoder().encode(workspace))

{buildzr-0.0.4 → buildzr-0.0.6}/tests/test_dsl.py

@@ -843,4 +843,69 @@ def test_dsl_relationship_without_desc_multiple_dest() -> Optional[None]:
     assert not w.person().user.model.relationships[2].technology
     assert w.person().user.model.relationships[0].destinationId == w.software_system().software_1.model.id
     assert w.person().user.model.relationships[1].destinationId == w.software_system().software_2.model.id
-    assert w.person().user.model.relationships[2].destinationId == w.software_system().software_3.model.id
+    assert w.person().user.model.relationships[2].destinationId == w.software_system().software_3.model.id
+
+def test_fluent_json_sink() -> Optional[None]:
+
+    Workspace("w")\
+    .contains(
+        Person("User"),
+        SoftwareSystem("Software 1"),
+        SoftwareSystem("Software 2"),
+    )\
+    .where(lambda w: [
+        w.person().user >> [
+            desc("Uses") >> w.software_system().software_1,
+            desc("Uses") >> w.software_system().software_2,
+        ]
+    ])\
+    .with_views(
+        SystemContextView(
+            key="ss_01",
+            title="System Context",
+            description="A simple system context view for software 1",
+            software_system_selector=lambda w: w.software_system().software_1,
+        ),
+        SystemContextView(
+            key="ss_02",
+            title="System Context",
+            description="A simple system context view for software 2",
+            software_system_selector=lambda w: w.software_system().software_2,
+        ),
+    )\
+    .to_json(path="test.json")
+
+    with open("test.json", "r") as f:
+        data = f.read()
+
+    assert data
+
+    import os
+    os.remove("test.json")
+
+def test_fluent_json_sink_empty_views() -> Optional[None]:
+
+    # No views defined here.
+
+    Workspace("w")\
+    .contains(
+        Person("User"),
+        SoftwareSystem("Software 1"),
+        SoftwareSystem("Software 2"),
+    )\
+    .where(lambda w: [
+        w.person().user >> [
+            desc("Uses") >> w.software_system().software_1,
+            desc("Uses") >> w.software_system().software_2,
+        ]
+    ])\
+    .with_views()\
+    .to_json(path="test.json")
+
+    with open("test.json", "r") as f:
+        data = f.read()
+
+    assert data
+
+    import os
+    os.remove("test.json")

buildzr-0.0.4/buildzr/__about__.py

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