zepben.ewb 1.0.0b1__py3-none-any.whl

zepben/ewb/services/network/tracing/networktrace/operators/equipment_container_state_operators.py

@@ -0,0 +1,264 @@
+#  Copyright 2025 Zeppelin Bend Pty Ltd
+#  This Source Code Form is subject to the terms of the Mozilla Public
+#  License, v. 2.0. If a copy of the MPL was not distributed with this
+#  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+from __future__ import annotations
+
+__all__ = ['EquipmentContainerStateOperators', 'NormalEquipmentContainerStateOperators', 'CurrentEquipmentContainerStateOperators']
+
+from abc import abstractmethod
+from typing import Generator, TYPE_CHECKING
+
+from zepben.ewb.model.cim.extensions.iec61970.base.feeder.lv_feeder import LvFeeder
+from zepben.ewb.model.cim.iec61970.base.core.equipment_container import EquipmentContainer
+from zepben.ewb.model.cim.iec61970.base.core.feeder import Feeder
+from zepben.ewb.services.network.tracing.networktrace.operators import StateOperator
+
+if TYPE_CHECKING:
+    from zepben.ewb.model.cim.iec61970.base.core.equipment import Equipment
+
+
+class EquipmentContainerStateOperators(StateOperator):
+    """
+    Defines operations for managing relationships between [Equipment] and [EquipmentContainer].
+    """
+
+    @staticmethod
+    @abstractmethod
+    def get_equipment(container: EquipmentContainer) -> Generator[Equipment, None, None]:
+        """
+        Get the collection of equipment associated with the given container.
+
+        `container` The container for which to get the associated equipment.
+        Returns A collection of equipment in the specified container.
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def get_containers(equipment: Equipment) -> Generator[EquipmentContainer, None, None]:
+        """
+        Retrieves a collection of containers associated with the given equipment.
+
+        `equipment` The equipment for which to get the associated containers.
+        Returns A collection of containers that contain the specified equipment.
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def get_energizing_feeders(lv_feeder: LvFeeder) -> Generator[Feeder, None, None]:
+        """
+        Retrieves a collection of feeders that energize the given LV feeder.
+
+        `lvFeeder` The LV feeder for which to get the energizing feeders.
+        Returns A collection of feeders that energize the given LV feeder.
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def get_energized_lv_feeders(feeder: Feeder) -> Generator[LvFeeder, None, None]:
+        """
+        Retrieves a collection of LV feeders energized by the given feeder.
+
+        `feeder` The feeder for which to get the energized LV feeders.
+        Returns A collection of LV feeders energized by the given feeder.
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def add_equipment_to_container(equipment: Equipment, container: EquipmentContainer):
+        """
+         Adds the specified equipment to the given container.
+
+         `equipment` The equipment to add to the container.
+         `container` The container to which the equipment will be added.
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def add_container_to_equipment(container: EquipmentContainer, equipment: Equipment):
+        """
+        Adds the specified container to the given equipment.
+
+        `container` The container to add to the equipment.
+        `equipment` The equipment to which the container will be added.
+        """
+        pass
+
+    @classmethod
+    def associate_equipment_and_container(cls, equipment: Equipment, container: EquipmentContainer):
+        """
+        Establishes a bidirectional association between the specified equipment and container.
+
+        `equipment` The equipment to associate with the container.
+        `container` The container to associate with the equipment.
+        """
+        cls.add_equipment_to_container(equipment, container)
+        cls.add_container_to_equipment(container, equipment)
+
+    @staticmethod
+    @abstractmethod
+    def remove_equipment_from_container(equipment: Equipment, container: EquipmentContainer):
+        """
+        Removes the specified equipment from the given container.
+
+        `equipment` The equipment to remove from the container.
+        `container` The container from which the equipment will be removed.
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def remove_container_from_equipment(container: EquipmentContainer, equipment: Equipment):
+        """
+        Removes the specified container from the given equipment.
+
+        `container` The container to remove from the equipment.
+        `equipment` The equipment from which the container will be removed.
+        """
+        pass
+
+    @classmethod
+    def disassociate_equipment_and_container(cls, equipment: Equipment, container: EquipmentContainer):
+        """
+        Remove a bidirectional association between the specified equipment and container.
+
+        `equipment` The equipment to disassociate with the container.
+        `container` The container to disassociate with the equipment.
+        """
+        cls.remove_equipment_from_container(equipment, container)
+        cls.remove_container_from_equipment(container, equipment)
+
+    @staticmethod
+    @abstractmethod
+    def add_energizing_feeder_to_lv_feeder(feeder: Feeder, lv_feeder: LvFeeder):
+        """
+        Adds the specified energizing feeder to the given lvFeeder.
+
+        `feeder` The energizing feeder to add to the lvFeeder.
+        `lvFeeder` The lvFeeder to which the feeder will be added.
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def add_energizing_lv_feeder_to_feeder(lv_feeder: LvFeeder, feeder: Feeder):
+        """
+        Adds the specified energized lvFeeder to the given feeder.
+
+        `lvFeeder` The energized lvFeeder to add to the feeder.
+        `feeder` The feeder to which the lvFeeder will be added.
+        """
+        pass
+
+    @classmethod
+    def associate_energizing_feeder(cls, feeder: Feeder, lv_feeder: LvFeeder):
+        """
+        Establishes a bidirectional association between the specified feeder and LV feeder.
+
+        `feeder` The feeder energizing the lv feeder.
+        `lvFeeder` The lv feeder energized by the feeder.
+        """
+        cls.add_energizing_feeder_to_lv_feeder(feeder, lv_feeder)
+        cls.add_energizing_lv_feeder_to_feeder(lv_feeder, feeder)
+
+
+class NormalEquipmentContainerStateOperators(EquipmentContainerStateOperators):
+    """
+    Operates on the normal network state equipment-container relationships
+    """
+
+    @staticmethod
+    def get_equipment(container: EquipmentContainer) -> Generator[Equipment, None, None]:
+        return container.equipment
+
+    @staticmethod
+    def get_containers(equipment: Equipment) -> Generator[EquipmentContainer, None, None]:
+        return equipment.containers
+
+    @staticmethod
+    def get_energizing_feeders(lv_feeder: LvFeeder) -> Generator[Feeder, None, None]:
+        return lv_feeder.normal_energizing_feeders
+
+    @staticmethod
+    def get_energized_lv_feeders(feeder: Feeder) -> Generator[LvFeeder, None, None]:
+        return feeder.normal_energized_lv_feeders
+
+    @staticmethod
+    def add_equipment_to_container(equipment: Equipment, container: EquipmentContainer):
+        container.add_equipment(equipment)
+
+    @staticmethod
+    def add_container_to_equipment(container: EquipmentContainer, equipment: Equipment):
+        equipment.add_container(container)
+
+    @staticmethod
+    def remove_equipment_from_container(equipment: Equipment, container: EquipmentContainer):
+        container.remove_equipment(equipment)
+
+    @staticmethod
+    def remove_container_from_equipment(container: EquipmentContainer, equipment: Equipment):
+        equipment.remove_container(container)
+
+    @staticmethod
+    def add_energizing_feeder_to_lv_feeder(feeder: Feeder, lv_feeder: LvFeeder):
+        lv_feeder.add_normal_energizing_feeder(feeder)
+
+    @staticmethod
+    def add_energizing_lv_feeder_to_feeder(lv_feeder: LvFeeder, feeder: Feeder):
+        feeder.add_normal_energized_lv_feeder(lv_feeder)
+
+
+class CurrentEquipmentContainerStateOperators(EquipmentContainerStateOperators):
+    """
+    Operates on the current network state equipment-container relationships
+    """
+
+    @staticmethod
+    def get_equipment(container: EquipmentContainer) -> Generator[Equipment, None, None]:
+        return container.current_equipment
+
+    @staticmethod
+    def get_containers(equipment: Equipment) -> Generator[EquipmentContainer, None, None]:
+        return equipment.current_containers
+
+    @staticmethod
+    def get_energizing_feeders(lv_feeder: LvFeeder) -> Generator[Feeder, None, None]:
+        return lv_feeder.current_energizing_feeders
+
+    @staticmethod
+    def get_energized_lv_feeders(feeder: Feeder) -> Generator[LvFeeder, None, None]:
+        return feeder.current_energized_lv_feeders
+
+    @staticmethod
+    def add_equipment_to_container(equipment: Equipment, container: EquipmentContainer):
+        container.add_current_equipment(equipment)
+
+    @staticmethod
+    def add_container_to_equipment(container: EquipmentContainer, equipment: Equipment):
+        equipment.add_current_container(container)
+
+    @staticmethod
+    def remove_equipment_from_container(equipment: Equipment, container: EquipmentContainer):
+        container.remove_current_equipment(equipment)
+
+    @staticmethod
+    def remove_container_from_equipment(container: EquipmentContainer, equipment: Equipment):
+        equipment.remove_current_container(container)
+
+    @staticmethod
+    def add_energizing_feeder_to_lv_feeder(feeder: Feeder, lv_feeder: LvFeeder):
+        lv_feeder.add_current_energizing_feeder(feeder)
+
+    @staticmethod
+    def add_energizing_lv_feeder_to_feeder(lv_feeder: LvFeeder, feeder: Feeder):
+        feeder.add_current_energized_lv_feeder(lv_feeder)
+
+
+EquipmentContainerStateOperators.NORMAL = NormalEquipmentContainerStateOperators
+EquipmentContainerStateOperators.CURRENT = CurrentEquipmentContainerStateOperators

zepben/ewb/services/network/tracing/networktrace/operators/feeder_direction_state_operations.py

@@ -0,0 +1,181 @@
+#  Copyright 2025 Zeppelin Bend Pty Ltd
+#  This Source Code Form is subject to the terms of the Mozilla Public
+#  License, v. 2.0. If a copy of the MPL was not distributed with this
+#  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+from __future__ import annotations
+
+__all__ = ['FeederDirectionStateOperations', 'NormalFeederDirectionStateOperations', 'CurrentFeederDirectionStateOperations']
+
+from abc import abstractmethod
+from typing import TYPE_CHECKING, TypeVar
+
+from zepben.ewb.services.network.tracing.feeder.feeder_direction import FeederDirection
+
+if TYPE_CHECKING:
+    from zepben.ewb.model.cim.iec61970.base.core.terminal import Terminal
+    from zepben.ewb.services.network.tracing.networktrace.conditions.network_trace_queue_condition import NetworkTraceQueueCondition
+
+from zepben.ewb.services.network.tracing.networktrace.conditions.direction_condition import DirectionCondition
+from zepben.ewb.services.network.tracing.networktrace.operators import StateOperator
+
+T = TypeVar('T')
+
+
+class FeederDirectionStateOperations(StateOperator):
+    """
+    Interface for accessing and managing the [FeederDirection] associated with [Terminal]s.
+    """
+
+    @staticmethod
+    @abstractmethod
+    def get_direction(terminal: Terminal) -> FeederDirection:
+        """
+        Retrieves the feeder direction for the specified terminal.
+
+        :param terminal: The terminal for which to retrieve the feeder direction.
+
+        :return: The current feeder direction associated with the specified terminal.
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def set_direction(terminal: Terminal, direction: FeederDirection) -> bool:
+        """
+        Sets the feeder direction for the specified terminal.
+
+        :param terminal: The terminal for which to set the feeder direction.
+        :param direction: The new feeder direction to assign to the terminal.
+
+        :return: `True` if the direction was changed; `false` if the direction was already set to the specified value.
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def add_direction(terminal: Terminal, direction: FeederDirection) -> bool:
+        """
+        Adds the specified feeder direction to the terminal, preserving existing directions.
+
+        :param terminal: The terminal for which to add the feeder direction.
+        :param direction: The feeder direction to add.
+
+        :return: `True` if the direction was added successfully; `false` if the direction was already present.
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def remove_direction(terminal: Terminal, direction: FeederDirection) -> bool:
+        """
+        Removes the specified feeder direction from the terminal.
+
+        :param terminal: The terminal for which to remove the feeder direction.
+        :param direction: The feeder direction to remove.
+
+        :return: `true` if the direction was removed; `false` if the direction was not present.
+        """
+        pass
+
+    @classmethod
+    def upstream(cls) -> NetworkTraceQueueCondition[T]:
+        """
+        Creates a [NetworkTrace] condition that will cause tracing a feeder upstream (towards the head terminal).
+        This uses [FeederDirectionStateOperations.get_direction] receiver instance method within the condition.
+
+        :return: [NetworkTraceQueueCondition] that results in upstream tracing.
+        """
+        return cls.with_direction(FeederDirection.UPSTREAM)
+
+    @classmethod
+    def downstream(cls) -> NetworkTraceQueueCondition[T]:
+        """
+        Creates a [NetworkTrace] condition that will cause tracing a feeder downstream (away from the head terminal).
+        This uses [FeederDirectionStateOperations.get_direction] receiver instance method within the condition.
+
+        :return: [NetworkTraceQueueCondition] that results in downstream tracing.
+        """
+        return cls.with_direction(FeederDirection.DOWNSTREAM)
+
+    @classmethod
+    def with_direction(cls, direction: FeederDirection) -> NetworkTraceQueueCondition[T]:
+        """
+        Creates a [NetworkTrace] condition that will cause tracing only terminals with directions that match [direction].
+        This uses [FeederDirectionStateOperations.get_direction] receiver instance method within the condition.
+
+        :return: [NetworkTraceQueueCondition] that results in upstream tracing.
+        """
+        return DirectionCondition(direction, cls)
+
+
+class NormalFeederDirectionStateOperations(FeederDirectionStateOperations):
+    @staticmethod
+    def get_direction(terminal: Terminal) -> FeederDirection:
+        return terminal.normal_feeder_direction
+
+    @staticmethod
+    def set_direction(terminal: Terminal, direction: FeederDirection) -> bool:
+        if terminal.normal_feeder_direction == direction:
+            return False
+
+        terminal.normal_feeder_direction = direction
+        return True
+
+    @staticmethod
+    def add_direction(terminal: Terminal, direction: FeederDirection) -> bool:
+        previous = terminal.normal_feeder_direction
+        new = previous + direction
+        if new == previous:
+            return False
+
+        terminal.normal_feeder_direction = new
+        return True
+
+    @staticmethod
+    def remove_direction(terminal: Terminal, direction: FeederDirection) -> bool:
+        previous = terminal.normal_feeder_direction
+        new = previous - direction
+        if new == previous:
+            return False
+
+        terminal.normal_feeder_direction = new
+        return True
+
+
+class CurrentFeederDirectionStateOperations(FeederDirectionStateOperations):
+    @staticmethod
+    def get_direction(terminal: Terminal) -> FeederDirection:
+        return terminal.current_feeder_direction
+
+    @staticmethod
+    def set_direction(terminal: Terminal, direction: FeederDirection) -> bool:
+        if terminal.current_feeder_direction == direction:
+            return False
+
+        terminal.current_feeder_direction = direction
+        return True
+
+    @staticmethod
+    def add_direction(terminal: Terminal, direction: FeederDirection) -> bool:
+        previous = terminal.current_feeder_direction
+        new = previous + direction
+        if new == previous:
+            return False
+
+        terminal.current_feeder_direction = new
+        return True
+
+    @staticmethod
+    def remove_direction(terminal: Terminal, direction: FeederDirection) -> bool:
+        previous = terminal.current_feeder_direction
+        new = previous - direction
+        if new == previous:
+            return False
+
+        terminal.current_feeder_direction = new
+        return True
+
+
+FeederDirectionStateOperations.NORMAL = NormalFeederDirectionStateOperations
+FeederDirectionStateOperations.CURRENT = CurrentFeederDirectionStateOperations

zepben/ewb/services/network/tracing/networktrace/operators/in_service_state_operators.py

@@ -0,0 +1,76 @@
+#  Copyright 2025 Zeppelin Bend Pty Ltd
+#  This Source Code Form is subject to the terms of the Mozilla Public
+#  License, v. 2.0. If a copy of the MPL was not distributed with this
+#  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+from __future__ import annotations
+
+__all__ = ['InServiceStateOperators', 'NormalInServiceStateOperators', 'CurrentInServiceStateOperators']
+
+from abc import abstractmethod
+from typing import TYPE_CHECKING
+
+from zepben.ewb.services.network.tracing.networktrace.operators import StateOperator
+
+if TYPE_CHECKING:
+    from zepben.ewb.model.cim.iec61970.base.core.equipment import Equipment
+
+
+class InServiceStateOperators(StateOperator):
+    """
+    Interface for managing the in-service status of equipment.
+    """
+
+    @staticmethod
+    @abstractmethod
+    def is_in_service(equipment: Equipment):
+        """
+        Checks if the specified equipment is in service.
+
+        `equipment` The equipment to check.
+        Returns `true` if the equipment is in service; `false` otherwise.
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def set_in_service(equipment: Equipment, in_service: bool) -> bool:
+        """
+        Sets the in-service status of the specified equipment.
+
+        `equipment` The equipment for which to set the in-service status.
+        `inService` The desired in-service status (`true` for in service, `false` for out of service).
+        """
+        pass
+
+
+class NormalInServiceStateOperators(InServiceStateOperators):
+    """
+    Operates on the normal state of the `equipment`
+    """
+
+    @staticmethod
+    def is_in_service(equipment: Equipment):
+        return equipment.normally_in_service
+
+    @staticmethod
+    def set_in_service(equipment: Equipment, in_service: bool) -> None:
+        equipment.normally_in_service = in_service
+
+
+class CurrentInServiceStateOperators(InServiceStateOperators):
+    """
+    Operates on the current state of the `equipment`
+    """
+
+    @staticmethod
+    def is_in_service(equipment: Equipment):
+        return equipment.in_service
+
+    @staticmethod
+    def set_in_service(equipment: Equipment, in_service: bool) -> None:
+        equipment.in_service = in_service
+
+
+InServiceStateOperators.NORMAL = NormalInServiceStateOperators
+InServiceStateOperators.CURRENT = CurrentInServiceStateOperators

zepben/ewb/services/network/tracing/networktrace/operators/network_state_operators.py

@@ -0,0 +1,120 @@
+#  Copyright 2025 Zeppelin Bend Pty Ltd
+#  This Source Code Form is subject to the terms of the Mozilla Public
+#  License, v. 2.0. If a copy of the MPL was not distributed with this
+#  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+from __future__ import annotations
+
+__all__ = ['NetworkStateOperators', 'NormalNetworkStateOperators', 'CurrentNetworkStateOperators']
+
+from abc import abstractmethod
+from functools import lru_cache
+from typing import Type, Generator, TYPE_CHECKING
+
+from zepben.ewb.services.network.tracing.networktrace.network_trace_step_path_provider import NetworkTraceStepPathProvider
+from zepben.ewb.services.network.tracing.networktrace.operators.equipment_container_state_operators import EquipmentContainerStateOperators, \
+    NormalEquipmentContainerStateOperators, CurrentEquipmentContainerStateOperators
+from zepben.ewb.services.network.tracing.networktrace.operators.feeder_direction_state_operations import FeederDirectionStateOperations, \
+    NormalFeederDirectionStateOperations, CurrentFeederDirectionStateOperations
+from zepben.ewb.services.network.tracing.networktrace.operators.in_service_state_operators import InServiceStateOperators, NormalInServiceStateOperators, \
+    CurrentInServiceStateOperators
+from zepben.ewb.services.network.tracing.networktrace.operators.open_state_operators import OpenStateOperators, NormalOpenStateOperators, \
+    CurrentOpenStateOperators
+from zepben.ewb.services.network.tracing.networktrace.operators.phase_state_operators import PhaseStateOperators, NormalPhaseStateOperators, \
+    CurrentPhaseStateOperators
+from zepben.ewb.util import classproperty
+
+if TYPE_CHECKING:
+    from zepben.ewb.services.network.tracing.networktrace.network_trace_step import NetworkTraceStep
+
+
+# noinspection PyPep8Naming
+class NetworkStateOperators(
+    OpenStateOperators,
+    FeederDirectionStateOperations,
+    EquipmentContainerStateOperators,
+    InServiceStateOperators,
+    PhaseStateOperators
+):
+    """
+    Interface providing access to and operations on specific network state properties and functions for items within a network.
+    This interface consolidates several other state operator interfaces, enabling unified management of operations for a network state.
+    Refer to the individual state operator interfaces for detailed information on each available operation.
+
+    Although this is an open interface allowing for custom implementations, this is generally unnecessary. The standard
+    instances, [NetworkStateOperators.NORMAL] for the normal state and [NetworkStateOperators.CURRENT] for the current state,
+    should suffice for most use cases.
+
+    This interface is primarily utilized by the [NetworkTrace], enabling trace definitions to be reused across different network states.
+    By using this interface, you can apply identical conditions and steps without needing to track which state is active
+    or creating redundant trace implementations for different network states.
+    """
+
+    description: str
+
+    @classproperty
+    def NORMAL(cls) -> Type['NormalNetworkStateOperators']:
+        return NormalNetworkStateOperators
+
+    @classproperty
+    def CURRENT(cls) -> Type['CurrentNetworkStateOperators']:
+        return CurrentNetworkStateOperators
+
+    @classmethod
+    @abstractmethod
+    def next_paths(cls, path: NetworkTraceStep.Path) -> Generator[NetworkTraceStep.Path, None, None]:
+        pass
+
+
+class NormalNetworkStateOperators(
+    NetworkStateOperators,
+    NormalOpenStateOperators,
+    NormalFeederDirectionStateOperations,
+    NormalEquipmentContainerStateOperators,
+    NormalInServiceStateOperators,
+    NormalPhaseStateOperators
+):
+    """
+    Instance that operates on the normal state of network objects.
+    """
+
+    description = 'normal'
+
+    CURRENT = False
+    NORMAL = True
+
+    @classmethod
+    @lru_cache
+    def network_trace_step_path_provider(cls):
+        return NetworkTraceStepPathProvider(cls)
+
+    @classmethod
+    def next_paths(cls, path: NetworkTraceStep.Path) -> Generator[NetworkTraceStep.Path, None, None]:
+        yield from cls.network_trace_step_path_provider().next_paths(path)
+
+
+class CurrentNetworkStateOperators(
+    NetworkStateOperators,
+    CurrentOpenStateOperators,
+    CurrentFeederDirectionStateOperations,
+    CurrentEquipmentContainerStateOperators,
+    CurrentInServiceStateOperators,
+    CurrentPhaseStateOperators
+):
+    """
+    Instance that operates on the current state of network objects.
+    """
+
+    description = 'current'
+
+    CURRENT = True
+    NORMAL = False
+
+    @classmethod
+    @lru_cache
+    def network_trace_step_path_provider(cls):
+        return NetworkTraceStepPathProvider(cls)
+
+    @classmethod
+    def next_paths(cls, path: NetworkTraceStep.Path) -> Generator[NetworkTraceStep.Path, None, None]:
+        yield from cls.network_trace_step_path_provider().next_paths(path)