refactor: add child_elements property to Element

Author: yt-ms

src/structurizr/model/container.py

@@ -107,6 +107,11 @@ def components(self) -> Iterable[Component]:
         """Return read-only list of child components."""
         return list(self._components)
 
+    @property
+    def child_elements(self) -> Iterable[Component]:
+        """Return child elements (from `Element.children`)."""
+        return self.components
+
     @classmethod
     def hydrate(
         cls,

src/structurizr/model/deployment_node.py

@@ -22,6 +22,7 @@
 from .container import Container
 from .container_instance import ContainerInstance, ContainerInstanceIO
 from .deployment_element import DeploymentElement, DeploymentElementIO
+from .element import Element
 from .infrastructure_node import InfrastructureNode, InfrastructureNodeIO
 from .software_system import SoftwareSystem
 from .software_system_instance import SoftwareSystemInstance, SoftwareSystemInstanceIO
@@ -118,6 +119,16 @@ def children(self) -> Iterable["DeploymentNode"]:
         """Return read-only list of child nodes."""
         return list(self._children)
 
+    @property
+    def child_elements(self) -> Iterable[Element]:
+        """Return child elements (from `Element.children`)."""
+        return (
+            self.children
+            + self.container_instances
+            + self.software_system_instances
+            + self.infrastructure_nodes
+        )
+
     @property
     def container_instances(self) -> Iterable[ContainerInstance]:
         """Return read-only list of container instances."""

src/structurizr/model/element.py

@@ -82,6 +82,14 @@ def __repr__(self):
         """Return a string representation of this instance."""
         return f"{type(self).__name__}(id={self.id}, name={self.name})"
 
+    @property
+    def child_elements(self) -> Iterable["Element"]:
+        """Return the elements that are children of this one.
+
+        Subclasses should override this to provide their specific children.
+        """
+        return []
+
     def get_relationships(self) -> Iterator[Relationship]:
         """Return a Iterator over all relationships involving this element."""
         return (

src/structurizr/model/software_system.py

@@ -79,6 +79,11 @@ def containers(self) -> Iterable[Container]:
         """Return read-only list of child containers."""
         return list(self._containers)
 
+    @property
+    def child_elements(self) -> Iterable[Container]:
+        """Return child elements (from `Element.children`)."""
+        return self.containers
+
     def add_container(
         self, name: str, description: str = "", technology: str = "", **kwargs
     ) -> Container:

tests/unit/model/test_container.py

@@ -67,6 +67,13 @@ def test_container_add_component_adds_to_component_list(
     assert component.parent is empty_container
 
 
+def test_container_child_elements_property(model_with_container: MockModel):
+    """Verify children property works."""
+    empty_container = model_with_container.empty_container
+    component = empty_container.add_component(name="Component")
+    assert component in empty_container.child_elements
+
+
 def test_container_add_constructed_component(model_with_container: MockModel):
     """Verify behaviour when adding a newly constructed Container."""
     empty_container = model_with_container.empty_container

tests/unit/model/test_deployment_node.py

@@ -158,15 +158,19 @@ def test_deployment_node_add_with_iadd(model_with_node: MockModel):
 
     node += child_node
     assert child_node in node.children
+    assert child_node in node.child_elements
 
     node += system
     assert node.software_system_instances[0].software_system is system
+    assert node.software_system_instances[0] in node.child_elements
 
     child_node += container
     assert child_node.container_instances[0].container is container
+    assert child_node.container_instances[0] in child_node.child_elements
 
     child_node += infra_node
     assert infra_node in child_node.infrastructure_nodes
+    assert child_node.infrastructure_nodes[0] in child_node.child_elements
 
 
 def test_deployment_node_serialising_container(model_with_node):

tests/unit/model/test_element.py

@@ -57,6 +57,12 @@ def test_model_reference():
     assert element.get_model() is model
 
 
+def test_element_child_elements_default():
+    """Ensure that by default, element has no children."""
+    element = ConcreteElement(name="Element")
+    assert element.child_elements == []
+
+
 def test_element_can_only_add_relationship_to_source():
     """Make sure that nothing adds a relationship to the wrong element."""
     element1 = ConcreteElement(name="elt1")

tests/unit/model/test_software_system.py

@@ -84,6 +84,15 @@ def test_software_system_add_container_adds_to_container_list(
     assert container.parent is empty_system
 
 
+def test_software_system_child_elements_property(
+    model_with_system: MockModel,
+):
+    """Ensure that children propery returns containers."""
+    empty_system = model_with_system.empty_system
+    container = empty_system.add_container(name="Container", description="Description")
+    assert container in empty_system.child_elements
+
+
 def test_software_system_add_constructed_container(model_with_system: MockModel):
     """Verify behaviour when adding a newly constructed Container."""
     empty_system = model_with_system.empty_system