buildzr 0.0.1__py3-none-any.whl

buildzr/dsl/explorer.py

@@ -0,0 +1,67 @@
+from buildzr.dsl.dsl import (
+    Person,
+    SoftwareSystem,
+    Container,
+    Component,
+)
+
+from buildzr.dsl.relations import (
+    _Relationship,
+    _UsesData,
+)
+
+from typing import (
+    Union,
+    Generator,
+    Iterable,
+)
+
+from buildzr.dsl.dsl import (
+    Workspace,
+)
+
+class Explorer:
+
+    def __init__(self, workspace_or_element: Union[Workspace, Person, SoftwareSystem, Container, Component]):
+        self._workspace_or_element = workspace_or_element
+
+    def walk_elements(self) -> Generator[Union[Person, SoftwareSystem, Container, Component], None, None]:
+        if self._workspace_or_element.children:
+            for child in self._workspace_or_element.children:
+                explorer = Explorer(child).walk_elements()
+                yield child
+                yield from explorer
+
+    def walk_relationships(self) -> Generator[_Relationship, None, None]:
+        import buildzr
+        from buildzr.dsl.factory.gen_id import GenerateId
+
+        if self._workspace_or_element.children:
+            for child in self._workspace_or_element.children:
+                # Relationships aren't materialized in the `Workspace` or in any
+                # of the `DslElement`s. As such, we need to recreate the `_Relationship` objects
+                # from the Structurizr model.
+
+                if child.model.relationships and child.destinations:
+                    for relationship, destination in zip(child.model.relationships, child.destinations):
+                        fake_relationship = _Relationship(
+                            _UsesData(
+                                relationship=buildzr.models.Relationship(
+                                    id=relationship.id,
+                                    description=relationship.description,
+                                    properties=relationship.properties,
+                                    technology=relationship.technology,
+                                    tags=relationship.tags,
+                                    sourceId=relationship.sourceId,
+                                ),
+                                source=child,
+                            ),
+                            destination=destination,
+                            _include_in_model=False,
+                        )
+                        fake_relationship._tags = set(relationship.tags.split(','))
+
+                        yield fake_relationship
+
+                explorer = Explorer(child).walk_relationships()
+                yield from explorer

buildzr/dsl/expression.py

@@ -0,0 +1,208 @@
+from buildzr.dsl.interfaces import (
+    DslWorkspaceElement,
+    DslElement,
+    DslRelationship,
+)
+
+from buildzr.dsl.dsl import (
+    Workspace,
+    Person,
+    SoftwareSystem,
+    Container,
+    Component,
+    _Relationship,
+)
+
+import buildzr
+from typing import Set, Union, Optional, List, Dict, Any, Callable, Tuple, Sequence, Iterable, cast, Type
+from typing_extensions import TypeIs
+
+def _has_technology_attribute(obj: DslElement) -> TypeIs[Union[Container, Component]]:
+    if isinstance(obj, (Person, SoftwareSystem, Workspace)):
+        return False
+    return True
+
+class FlattenElement:
+
+    def __init__(self, elements: Iterable[DslElement]):
+        self._elements = elements
+
+    @property
+    def ids(self) -> Set[Union[str]]:
+        # Note that the `element.model` can also be a `Workspace`, whose `id` is
+        # of type `int`. But since we know that these are all `DslElements` (`id` of type `str`),
+        # we can safely cast all the `id`s as `str` for the type checker to be happy.
+        return set([str(element.model.id) for element in self._elements])
+
+    @property
+    def names(self) -> Set[Union[str]]:
+        return set([str(element.model.name) for element in self._elements])
+
+    @property
+    def tags(self) -> Set[Union[str]]:
+        all_tags: Set[str] = set()
+        for element in self._elements:
+            tags = element.tags
+            all_tags = all_tags.union(tags)
+        return all_tags
+
+class Element:
+
+    def __init__(self, element: DslElement):
+        self._element = element
+
+    # TODO: Make a test for this in `tests/test_expression.py`
+    @property
+    def id(self) -> str:
+        return cast(str, self._element.model.id)
+
+    @property
+    def type(self) -> Type:
+        return type(self._element)
+
+    @property
+    def tags(self) -> Set[str]:
+        return self._element.tags
+
+    @property
+    def technology(self) -> Optional[str]:
+        if _has_technology_attribute(self._element):
+            return self._element.model.technology
+        return None
+
+    # TODO: Make a test for this in `tests/test_expression.py`
+    @property
+    def parent(self) -> Optional[Union[DslWorkspaceElement, DslElement]]:
+        return self._element.parent
+
+    @property
+    def sources(self) -> FlattenElement:
+        return FlattenElement(self._element.sources)
+
+    @property
+    def destinations(self) -> FlattenElement:
+        return FlattenElement(self._element.destinations)
+
+    @property
+    def properties(self) -> Dict[str, Any]:
+        return self._element.model.properties
+
+    def __eq__(self, element: object) -> bool:
+        return isinstance(element, type(self._element)) and\
+               element.model.id == self._element.model.id
+
+class Relationship:
+
+    def __init__(self, relationship: _Relationship):
+        self._relationship = relationship
+
+    # TODO: Make a test for this in `tests/test_expression.py`
+    @property
+    def id(self) -> str:
+        return cast(str, self._relationship.model.id)
+
+    @property
+    def tags(self) -> Set[str]:
+        return self._relationship.tags
+
+    @property
+    def technology(self) -> Optional[str]:
+        return self._relationship.model.technology
+
+    @property
+    def source(self) -> Element:
+        return Element(self._relationship.source)
+
+    @property
+    def destination(self) -> Element:
+        return Element(self._relationship.destination)
+
+    @property
+    def properties(self) -> Dict[str, Any]:
+        if self._relationship.model.properties is not None:
+            return self._relationship.model.properties
+        return dict()
+
+class Expression:
+
+    """
+    A class used to filter the elements and the relationships in the workspace.
+    To be used when defining views.
+
+    In the Structurizr DSL, these are called "Expressions". See the Structurizr docs here:
+    https://docs.structurizr.com/dsl/expressions
+    """
+
+    def __init__(
+        self,
+        include_elements: Iterable[Callable[[Workspace, Element], bool]]=[lambda w, e: True],
+        exclude_elements: Iterable[Callable[[Workspace, Element], bool]]=[],
+        include_relationships: Iterable[Callable[[Workspace, Relationship], bool]]=[lambda w, e: True],
+        exclude_relationships: Iterable[Callable[[Workspace, Relationship], bool]]=[],
+    ) -> 'None':
+        self._include_elements = include_elements
+        self._exclude_elements = exclude_elements
+        self._include_relationships = include_relationships
+        self._exclude_relationships = exclude_relationships
+
+    def elements(
+        self,
+        workspace: Workspace,
+    ) -> List[DslElement]:
+
+        filtered_elements: List[DslElement] = []
+
+        workspace_elements = buildzr.dsl.Explorer(workspace).walk_elements()
+        for element in workspace_elements:
+            any_includes = any([f(workspace, Element(element)) for f in self._include_elements])
+            any_excludes = any([f(workspace, Element(element)) for f in self._exclude_elements])
+            if any_includes and not any_excludes:
+                filtered_elements.append(element)
+
+        return filtered_elements
+
+    def relationships(
+        self,
+        workspace: Workspace
+    ) -> List[DslRelationship]:
+
+        """
+        Returns the relationships that are included as defined in
+        `include_relationships` and excludes those that are defined in
+        `exclude_relationships`. Any relationships that directly works on
+        elements that are excluded as defined in `exclude_elements` will also be
+        excluded.
+        """
+
+        filtered_relationships: List[DslRelationship] = []
+
+        def _is_relationship_of_excluded_elements(
+            workspace: Workspace,
+            relationship: Relationship,
+            exclude_element_predicates: Iterable[Callable[[Workspace, Element], bool]],
+        ) -> bool:
+            return any([
+                f(workspace, relationship.source) for f in exclude_element_predicates
+            ] + [
+                f(workspace, relationship.destination) for f in exclude_element_predicates
+            ])
+
+        workspace_relationships = buildzr.dsl.Explorer(workspace).walk_relationships()
+        for relationship in workspace_relationships:
+            any_includes = any([f(workspace, Relationship(relationship)) for f in self._include_relationships])
+
+            # Also exclude relationships whose source or destination elements are excluded.
+            any_excludes = any([
+                f(workspace, Relationship(relationship))
+                for f in self._exclude_relationships
+            ] + [
+                _is_relationship_of_excluded_elements(
+                    workspace,
+                    Relationship(relationship),
+                    self._exclude_elements,
+                )
+            ])
+            if any_includes and not any_excludes:
+                filtered_relationships.append(relationship)
+
+        return filtered_relationships

buildzr/dsl/factory/__init__.py

@@ -0,0 +1 @@
+from .gen_id import GenerateId

buildzr/dsl/factory/gen_id.py

@@ -0,0 +1,23 @@
+from typing import Dict
+
+class GenerateId:
+
+    _data: Dict[int, int] = {
+        0: 0,
+        1: 0,
+    }
+
+    @staticmethod
+    def for_workspace() -> int:
+        GenerateId._data[0] = GenerateId._data[0] + 1
+        return GenerateId._data[0]
+
+    @staticmethod
+    def for_element() -> str:
+        GenerateId._data[1] = GenerateId._data[1] + 1
+        return str(GenerateId._data[1])
+
+    @staticmethod
+    def for_relationship() -> str:
+        GenerateId._data[1] = GenerateId._data[1] + 1
+        return str(GenerateId._data[1])

buildzr/dsl/interfaces/__init__.py

@@ -0,0 +1,14 @@
+from .interfaces import (
+    DslElement,
+    DslFluentRelationship,
+    DslRelationship,
+    DslWorkspaceElement,
+    DslViewsElement,
+    BindLeft,
+    BindRight,
+    BindLeftLate,
+    TSrc,
+    TDst,
+    TParent,
+    TChild,
+)

buildzr/dsl/interfaces/interfaces.py

@@ -0,0 +1,207 @@
+from abc import ABC, abstractmethod
+from typing import (
+    Any,
+    Optional,
+    Union,
+    TypeVar,
+    Generic,
+    List,
+    Set,
+    Tuple,
+    Callable,
+    overload,
+    Sequence,
+    cast,
+)
+from typing_extensions import (
+    Self
+)
+import buildzr
+
+Model = Union[
+    buildzr.models.Workspace,
+    buildzr.models.Person,
+    buildzr.models.SoftwareSystem,
+    buildzr.models.Container,
+    buildzr.models.Component,
+]
+
+TSrc = TypeVar('TSrc', bound='DslElement', contravariant=True)
+TDst = TypeVar('TDst', bound='DslElement', contravariant=True)
+
+TParent = TypeVar('TParent', bound=Union['DslWorkspaceElement', 'DslElement'], covariant=True)
+TChild = TypeVar('TChild', bound='DslElement', contravariant=True)
+
+class BindLeftLate(ABC, Generic[TDst]):
+
+    @abstractmethod
+    def set_source(self, source: Any) -> None:
+        pass
+
+    @abstractmethod
+    def get_relationship(self) -> 'Optional[DslRelationship[Any, TDst]]':
+        pass
+
+class BindLeft(ABC, Generic[TSrc, TDst]):
+
+    # Note: an abstraction of _UsesFrom
+
+    @abstractmethod
+    def __rshift__(self, destination: TDst) -> 'DslRelationship[TSrc, TDst]':
+        pass
+
+class BindRight(ABC, Generic[TSrc, TDst]):
+
+    @overload
+    @abstractmethod
+    def __rshift__(self, description_and_technology: Tuple[str, str]) -> BindLeft[TSrc, TDst]:
+        ...
+
+    @overload
+    @abstractmethod
+    def __rshift__(self, description: str) -> BindLeft[TSrc, TDst]:
+        ...
+
+    @overload
+    @abstractmethod
+    def __rshift__(self, multiple_destinations: List[BindLeftLate[TDst]]) -> 'List[DslRelationship[TSrc, TDst]]':
+        ...
+
+    @abstractmethod
+    def __rshift__(self, other: Union[str, Tuple[str, str], List[BindLeftLate[TDst]]]) -> Union[BindLeft[TSrc, TDst], 'List[DslRelationship[TSrc, TDst]]']:
+        ...
+
+class DslWorkspaceElement(ABC):
+
+    @property
+    @abstractmethod
+    def model(self) -> buildzr.models.Workspace:
+        pass
+
+    @property
+    @abstractmethod
+    def parent(self) -> None:
+        pass
+
+    @property
+    @abstractmethod
+    def children(self) -> Optional[Sequence['DslElement']]:
+        pass
+
+    def __contains__(self, other: 'DslElement') -> bool:
+        return self.model.id == other.parent.model.id
+
+class DslElement(BindRight[TSrc, TDst]):
+    """An abstract class used to label classes that are part of the buildzr DSL"""
+
+    @property
+    @abstractmethod
+    def model(self) -> Model:
+        """
+        Returns the `dataclass` of the `DslElement` that follows Structurizr's
+        JSON Schema (see https://github.com/structurizr/json)
+        """
+        pass
+
+    @property
+    @abstractmethod
+    def parent(self) -> Union[None, DslWorkspaceElement, 'DslElement']:
+        pass
+
+    @property
+    @abstractmethod
+    def children(self) -> Union[None, Sequence['DslElement']]:
+        pass
+
+    @property
+    @abstractmethod
+    def sources(self) -> List['DslElement']:
+        pass
+
+    @property
+    @abstractmethod
+    def destinations(self) -> List['DslElement']:
+        pass
+
+    @property
+    @abstractmethod
+    def tags(self) -> Set[str]:
+        pass
+
+    def uses(
+        self,
+        other: 'DslElement',
+        description: Optional[str]=None,
+        technology: Optional[str]=None,
+        tags: Set[str]=set()) -> 'DslRelationship[Self, DslElement]':
+        pass
+
+    def __contains__(self, other: 'DslElement') -> bool:
+        return self.model.id == other.parent.model.id
+
+class DslRelationship(ABC, Generic[TSrc, TDst]):
+    """
+    An abstract class specially used to label classes that are part of the
+    relationship definer in the buildzr DSL
+    """
+
+    @property
+    @abstractmethod
+    def model(self) -> buildzr.models.Relationship:
+        pass
+
+    @property
+    @abstractmethod
+    def tags(self) -> Set[str]:
+        pass
+
+    @property
+    @abstractmethod
+    def source(self) -> DslElement:
+        pass
+
+    @property
+    @abstractmethod
+    def destination(self) -> DslElement:
+        pass
+
+    def __contains__(self, other: 'DslElement') -> bool:
+        return self.source.model.id == other.model.id or self.destination.model.id == other.model.id
+
+class DslFluentRelationship(ABC, Generic[TParent]):
+
+    """
+    The abstract class that defines the interface for the fluent relationship
+    definition, where the one or more relationships between elements accessible
+    from the `TParent` element.
+    """
+
+    @abstractmethod
+    def where(
+        self,
+        func: Callable[
+            [TParent],
+            Sequence[
+                Union[
+                    DslRelationship,
+                    Sequence[DslRelationship]
+                ]
+            ]
+        ]) -> TParent:
+        pass
+
+    @abstractmethod
+    def get(self) -> TParent:
+        pass
+
+class DslViewsElement(ABC):
+
+    @property
+    @abstractmethod
+    def model(self) -> buildzr.models.Views:
+        pass
+
+    @property
+    @abstractmethod
+    def parent(self) -> DslWorkspaceElement:
+        pass