feat: add FilterView

Author: yt-ms

CHANGELOG.rst

@@ -5,6 +5,7 @@ History
 Next Release
 ------------
 * Feat: Add ``DynamicView`` (#77)
+* Feat: Add ``FilteredView`` (#81)
 * Breaking change: View.find_element_view and find_relationship_view parameter changes.
 
 0.5.0 (2021-05-03)

src/structurizr/view/filtered_view.py

@@ -0,0 +1,97 @@
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+"""Provide a filtered view."""
+
+from enum import Enum
+from typing import Iterable, List, Optional
+
+from pydantic import Field
+
+from .abstract_view import AbstractView, AbstractViewIO
+from .static_view import StaticView
+
+
+__all__ = ("FilteredView", "FilteredViewIO")
+
+
+class FilterMode(Enum):
+    Include = "Include"
+    Exclude = "Exclude"
+
+
+class FilteredViewIO(AbstractViewIO):
+    """
+    Represent the FilteredView from the C4 model.
+
+    Attributes:
+        base_view_key: The key of the view on which this filtered view is based.
+        mode: Whether elements/relationships are being included or excluded based
+              upon the set of tag
+        tags: The set of tags to include/exclude elements/relationships when rendering
+              this filtered view.
+    """
+
+    base_view_key: str = Field(alias="baseViewKey")
+    mode: FilterMode
+    tags: List[str]
+
+
+class FilteredView(AbstractView):
+    """
+    Represent the filtered view from the C4 model.
+
+    A FilteredView is a view that is based on another view, but adding or removing
+    specific elements specified by tags.
+
+    Attributes:
+        view: the view which this FilteredView is based on
+        base_view_key: The key of the view on which this filtered view is based.
+        mode: Whether elements/relationships are being included or excluded based
+              upon the set of tag
+        tags: The set of tags to include/exclude elements/relationships when rendering
+              this filtered view.
+    """
+
+    def __init__(
+        self,
+        mode: FilterMode,
+        tags: Iterable[str],
+        view: Optional[StaticView] = None,
+        base_view_key: Optional[str] = None,
+        **kwargs
+    ) -> None:
+        """Initialize a filtered view."""
+        super().__init__(**kwargs)
+        self._base_view_key = base_view_key
+        self.view = view
+        self.mode = mode
+        self.tags = set(tags)
+
+    @property
+    def base_view_key(self) -> str:
+        """Return the key of the base view."""
+        return self.view.key if self.view else self._base_view_key
+
+    @classmethod
+    def hydrate(
+        cls,
+        view_io: FilteredViewIO,
+    ) -> "FilteredView":
+        """Hydrate a new FilteredView instance from its IO."""
+        return cls(
+            **cls.hydrate_arguments(view_io),
+            base_view_key=view_io.base_view_key,
+            mode=view_io.mode,
+            tags=view_io.tags
+        )

src/structurizr/view/view.py

@@ -20,8 +20,8 @@
 
 from pydantic import Field
 
-from .abstract_view import AbstractView, AbstractViewIO
 from ..model import Element, Model, Relationship, SoftwareSystem
+from .abstract_view import AbstractView, AbstractViewIO
 from .automatic_layout import AutomaticLayout, AutomaticLayoutIO
 from .element_view import ElementView, ElementViewIO
 from .paper_size import PaperSize

src/structurizr/view/view_set.py

@@ -23,11 +23,13 @@
 from ..abstract_base import AbstractBase
 from ..base_model import BaseModel
 from ..mixin import ModelRefMixin
+from .abstract_view import AbstractView
 from .component_view import ComponentView, ComponentViewIO
 from .configuration import Configuration, ConfigurationIO
 from .container_view import ContainerView, ContainerViewIO
 from .deployment_view import DeploymentView, DeploymentViewIO
 from .dynamic_view import DynamicView, DynamicViewIO
+from .filtered_view import FilteredView, FilteredViewIO
 from .system_context_view import SystemContextView, SystemContextViewIO
 from .system_landscape_view import SystemLandscapeView, SystemLandscapeViewIO
 from .view import View
@@ -60,9 +62,7 @@ class ViewSetIO(BaseModel):
         default=(), alias="deploymentViews"
     )
     dynamic_views: List[DynamicViewIO] = Field(default=(), alias="dynamicViews")
-
-    # TODO:
-    # filtered_views: List[FilteredView] = Field(set(), alias="filteredViews")
+    filtered_views: List[FilteredViewIO] = Field(default=(), alias="filteredViews")
 
 
 class ViewSet(ModelRefMixin, AbstractBase):
@@ -83,9 +83,10 @@ def __init__(
         container_views: Iterable[ContainerView] = (),
         component_views: Iterable[ComponentView] = (),
         deployment_views: Iterable[DeploymentView] = (),
+        filtered_views: Iterable[FilteredView] = (),
         dynamic_views: Iterable[DynamicView] = (),
         configuration: Optional[Configuration] = None,
-        **kwargs
+        **kwargs,
     ) -> None:
         """Initialize a view set."""
         super().__init__(**kwargs)
@@ -98,6 +99,7 @@ def __init__(
         self.component_views: Set[ComponentView] = set(component_views)
         self.deployment_views: Set[DeploymentView] = set(deployment_views)
         self.dynamic_views: Set[DynamicView] = set(dynamic_views)
+        self.filtered_views: Set[FilteredView] = set(filtered_views)
         self.configuration = Configuration() if configuration is None else configuration
         self.set_model(model)
 
@@ -150,7 +152,12 @@ def hydrate(cls, views: ViewSetIO, model: "Model") -> "ViewSet":
             cls._hydrate_view(view, model=model)
             dynamic_views.append(view)
 
-        return cls(
+        filtered_views = []
+        for view_io in views.filtered_views:
+            view = FilteredView.hydrate(view_io)
+            filtered_views.append(view)
+
+        result = cls(
             model=model,
             # TODO:
             # enterprise_context_views: Iterable[EnterpriseContextView] = (),
@@ -160,9 +167,17 @@ def hydrate(cls, views: ViewSetIO, model: "Model") -> "ViewSet":
             component_views=component_views,
             deployment_views=deployment_views,
             dynamic_views=dynamic_views,
+            filtered_views=filtered_views,
             configuration=Configuration.hydrate(views.configuration),
         )
 
+        # Patch up filtered views
+        for filtered_view in result.filtered_views:
+            base_view = result[filtered_view.base_view_key]
+            filtered_view.view = base_view
+
+        return result
+
     @classmethod
     def _hydrate_view(cls, view: View, model: "Model") -> None:
         for element_view in view.element_views:
@@ -287,6 +302,40 @@ def create_dynamic_view(self, **kwargs) -> DynamicView:
         self.dynamic_views.add(dynamic_view)
         return dynamic_view
 
+    def create_filtered_view(self, **kwargs) -> FilteredView:
+        """
+        Add a new FilteredView to the ViewSet.
+
+        Args:
+            **kwargs: Provide keyword arguments for instantiating a `FilteredView`.
+        """
+        # TODO:
+        # AssertThatTheViewKeyIsUnique(key);
+        filtered_view = FilteredView(**kwargs)
+        filtered_view.set_viewset(self)
+        self.filtered_views.add(filtered_view)
+        return filtered_view
+
+    def get_view(self, key: str) -> Optional[AbstractView]:
+        """Return the view with the given key, or None."""
+        all_views = (
+            self.system_landscape_views
+            | self.system_context_views
+            | self.container_views
+            | self.component_views
+            | self.deployment_views
+            | self.dynamic_views
+            | self.filtered_views
+        )
+        return next((view for view in all_views if view.key == key), None)
+
+    def __getitem__(self, key: str) -> AbstractView:
+        """Return the view with the given key or raise a KeyError."""
+        result = self.get_view(key)
+        if not result:
+            raise KeyError(f"No view with key '{key}' in ViewSet")
+        return result
+
     def copy_layout_information_from(self, source: "ViewSet") -> None:
         """Copy all the layout information from a source ViewSet."""
         for source_view in source.system_landscape_views:

tests/unit/view/test_filtered_view.py

@@ -0,0 +1,49 @@
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+"""Ensure the expected behaviour of FilteredView."""
+
+
+from structurizr.view.container_view import ContainerView
+from structurizr.view.filtered_view import FilteredView, FilteredViewIO, FilterMode
+
+
+def test_uses_view_key_if_view_specified():
+    """Test the logic around base_view_key."""
+    filtered_view = FilteredView(
+        base_view_key="key1", description="test", mode=FilterMode.Exclude, tags=[]
+    )
+    assert filtered_view.base_view_key == "key1"
+
+    filtered_view.view = ContainerView(key="static_key", description="container")
+    assert filtered_view.base_view_key == "static_key"
+
+
+def test_serialisation():
+    """Test serialisation and deserialisation works."""
+    container_view = ContainerView(key="static_key", description="container")
+    filtered_view = FilteredView(
+        key="filter1",
+        view=container_view,
+        description="test",
+        mode=FilterMode.Exclude,
+        tags=["v1"],
+    )
+    io = FilteredViewIO.from_orm(filtered_view)
+    view2 = FilteredView.hydrate(io)
+
+    assert view2.base_view_key == "static_key"
+    assert view2.key == "filter1"
+    assert view2.description == "test"
+    assert view2.mode == FilterMode.Exclude
+    assert view2.tags == {"v1"}

tests/unit/view/test_view_set.py

@@ -15,6 +15,8 @@
 import pytest
 
 from structurizr.model.model import Model
+from structurizr.view.container_view import ContainerView
+from structurizr.view.filtered_view import FilterMode
 from structurizr.view.paper_size import PaperSize
 from structurizr.view.view_set import ViewSet, ViewSetIO
 
@@ -84,3 +86,42 @@ def test_copying_dynamic_view_layout(empty_viewset):
 def test_copying_layout(empty_model):
     """Check copying layout from other view types."""
     assert 1 == 0  # TODO
+
+
+def test_filtered_view_hydrated(empty_viewset):
+    """Check dynamic views hydrated properly."""
+    viewset = empty_viewset
+    system1 = viewset.model.add_software_system(name="sys1")
+    container_view = viewset.create_container_view(
+        key="container1", description="container", software_system=system1
+    )
+    viewset.create_filtered_view(
+        key="filter1",
+        view=container_view,
+        description="filtered",
+        mode=FilterMode.Include,
+        tags=["v2"],
+    )
+    io = ViewSetIO.from_orm(viewset)
+
+    new_viewset = ViewSet.hydrate(io, viewset.model)
+    assert len(new_viewset.filtered_views) == 1
+    view = list(new_viewset.filtered_views)[0]
+    assert view.description == "filtered"
+    assert isinstance(view.view, ContainerView)
+    assert view.view.key == "container1"
+
+
+def test_getting_view_by_key(empty_viewset):
+    """Check retrieving views by key from the ViewSet."""
+    viewset = empty_viewset
+    system1 = viewset.model.add_software_system(name="sys1")
+    container_view = viewset.create_container_view(
+        key="container1", description="container", software_system=system1
+    )
+
+    assert viewset.get_view("container1") is container_view
+    assert viewset.get_view("bogus") is None
+    assert viewset["container1"] is container_view
+    with pytest.raises(KeyError, match="No view with key"):
+        viewset["bogus"]