zepben.ewb 1.0.0__py3-none-any.whl

zepben/ewb/streaming/exceptions.py

@@ -0,0 +1,14 @@
+#  Copyright 2024 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/.
+
+__all__ = ["GrpcConnectionException", "UnsupportedOperationException"]
+
+
+class GrpcConnectionException(IOError):
+    pass
+
+
+class UnsupportedOperationException(Exception):
+    pass

zepben/ewb/streaming/get/__init__.py

@@ -0,0 +1,4 @@
+#  Copyright 2024 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/.

zepben/ewb/streaming/get/consumer.py

@@ -0,0 +1,209 @@
+#  Copyright 2024 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__ = ["CimConsumerClient", "MultiObjectResult"]
+
+from abc import abstractmethod
+from typing import Iterable, Dict, Set, TypeVar, Generic, Tuple, Optional, AsyncGenerator, Type, Generator
+
+from zepben.protobuf.metadata.metadata_requests_pb2 import GetMetadataRequest
+from zepben.protobuf.metadata.metadata_responses_pb2 import GetMetadataResponse
+
+from zepben.ewb import BaseService, IdentifiedObject, UnsupportedOperationException, ServiceInfo
+from zepben.ewb.dataclassy import dataclass
+from zepben.ewb.services.common.meta.metadata_translations import service_info_from_pb
+from zepben.ewb.streaming.grpc.grpc import GrpcClient, GrpcResult
+
+T = TypeVar('T', bound=IdentifiedObject)
+
+
+@dataclass()
+class MultiObjectResult(object):
+    objects: Dict[str, T] = dict()
+    failed: Set[str] = set()
+
+
+ServiceType = TypeVar('ServiceType', bound=BaseService)
+PBIdentifiedObject = TypeVar('PBIdentifiedObject')
+GrpcRequest = TypeVar('GrpcRequest')
+
+
+class CimConsumerClient(GrpcClient, Generic[ServiceType]):
+    """
+    Base class that defines some helpful functions when producer clients are sending to the server.
+
+    ## WARNING ##
+        The :class:`MultiObjectResult` operations below are not atomic upon a :class:`BaseService`, and thus if processing fails partway through, any
+        previously successful additions will have been processed by the service, and thus you may have an incomplete service. Also note that adding to the
+        service may not occur for an object if another object with the same mRID is already present in service. `MultiObjectResult.failed` can be used to
+        check for mRIDs that were not found or retrieved but not added to service (this should not be the case unless you are processing things concurrently).
+
+    Parameters
+        T: The base service to send objects from.
+    """
+
+    __service_info: Optional[ServiceInfo]
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self.__service_info = None
+
+    @property
+    @abstractmethod
+    def service(self) -> ServiceType:
+        """
+        The service to store all retrieved objects in.
+        """
+        raise NotImplementedError()
+
+    async def get_identified_object(self, mrid: str) -> GrpcResult[IdentifiedObject]:
+        """
+        Retrieve the object with the given `mRID` and store the result in the `service`.
+
+        Exceptions that occur during sending will be caught and passed to all error handlers that have been registered by `addErrorHandler`.
+
+        Returns a :class:`GrpcResult` with a result of one of the following:
+            - When `GrpcResult.wasSuccessful`, the item found, accessible via `GrpcResult.value`.
+            - When `GrpcResult.wasFailure`, the error that occurred retrieving or processing the object, accessible via `GrpcResult.thrown`. One of:
+                - :class:`NoSuchElementException` if the object could not be found.
+                - The gRPC error that occurred while retrieving the object
+        """
+        return await self._get_identified_object(mrid)
+
+    async def get_identified_objects(self, mrids: Iterable[str]) -> GrpcResult[MultiObjectResult]:
+        """
+        Retrieve the objects with the given `mRIDs` and store the results in the `service`.
+
+        Exceptions that occur during processing will be caught and passed to all error handlers that have been registered by `addErrorHandler`.
+
+        @return A :class:`GrpcResult` with a result of one of the following:
+            - When `GrpcResult.wasSuccessful`, a map containing the retrieved objects keyed by mRID, accessible via `GrpcResult.value`. If an item was not
+              found, or couldn't be added to `service`, it will be excluded from the map and its mRID will be present in `MultiObjectResult.failed`
+              (see `BaseService.add`).
+            - When `GrpcResult.wasFailure`, the error that occurred retrieving or processing the object, accessible via `GrpcResult.thrown`.
+
+        Note the :class:`CimConsumerClient` warning in this case.
+        """
+        return await self._get_identified_objects(mrids)
+
+    async def _get_identified_object(self, mrid: str) -> GrpcResult[Optional[IdentifiedObject]]:
+        async def rpc():
+            async for io, _ in self._process_identified_objects([mrid]):
+                return io
+            else:
+                raise ValueError(f"No object with mRID {mrid} could be found.")
+
+        return await self.try_rpc(rpc)
+
+    async def _get_identified_objects(self, mrids: Iterable[str]) -> GrpcResult[MultiObjectResult]:
+        async def rpc():
+            return await self._process_extract_results(mrids, self._process_identified_objects(set(mrids)))
+
+        return await self.try_rpc(rpc)
+
+    @abstractmethod
+    async def _process_identified_objects(self, mrids: Iterable[str]) -> AsyncGenerator[Tuple[Optional[IdentifiedObject], str], None]:
+        #
+        # NOTE: this is a stupid test that is meant to fail to make sure we never yield, but we need to have the yield to make it return the generator.
+        #
+        if self is None:
+            yield
+        raise NotImplementedError()
+
+    CIM_TYPE = TypeVar("CIM_TYPE", bound=IdentifiedObject)
+
+    def _extract_identified_object(self,
+                                   desc: str,
+                                   pb_io: PBIdentifiedObject,
+                                   pb_type_to_cim: Dict[str, Type[CIM_TYPE]],
+                                   check_presence: bool = True) -> Tuple[Optional[IdentifiedObject], str]:
+        """
+        Add a :class:`CustomerIdentifiedObject` to the service. Will convert from protobuf to CIM type.
+
+        Parameters
+            - `pb_io` - The wrapped identified object returned by the server.
+            - `pb_type_to_cim` - The mapping of wrapped identified object types to CIM objects.
+            - `check_presence` - Whether to check if `cio` already exists in the service and skip if it does.
+
+        Raises :class:`UnsupportedOperationException` if `pb_io` was invalid/unset.
+        """
+        io_type = pb_io.WhichOneof("identifiedObject")
+        if io_type:
+            cim_type = pb_type_to_cim.get(io_type, None)
+            if cim_type is None:
+                raise UnsupportedOperationException(f"Identified object type '{io_type}' is not supported by the {desc} service")
+
+            pb = getattr(pb_io, io_type)
+            if check_presence:
+                try:
+                    cim = self.service.get(pb.mrid(), cim_type, default=None)
+                    if cim is not None:
+                        return cim, cim.mrid
+                except KeyError:
+                    raise KeyError(f"Invalid Protobuf message received with an empty mRID - message was: {pb_io}")
+
+            # noinspection PyUnresolvedReferences
+            return self.service.add_from_pb(pb), pb.mrid()
+        else:
+            raise UnsupportedOperationException(f"Received a {desc} identified object where no field was set")
+
+    @staticmethod
+    async def _process_extract_results(mrids: Optional[Iterable[str]],
+                                       extracted: AsyncGenerator[Tuple[Optional[IdentifiedObject], str], None]) -> MultiObjectResult:
+        results = {}
+        if mrids is None:
+            failed = set()
+        else:
+            failed = set(mrids)
+
+        async for result in extracted:
+            if result[0] is not None:
+                results[result[0].mrid] = result[0]
+                try:
+                    failed.remove(result[0].mrid)
+                except KeyError:
+                    pass
+            else:
+                failed.add(result[1])
+
+        return MultiObjectResult(results, failed)
+
+    @staticmethod
+    def _batch_send(request: GrpcRequest, mrids: Iterable[str]) -> Generator[GrpcRequest, None, None]:
+        count = 0
+        for mrid in mrids:
+            count += 1
+            if count % 1000 == 0:
+                yield request
+                del request.mrids[:]
+            request.mrids.append(mrid)
+
+        if request.mrids:
+            yield request
+
+    @abstractmethod
+    async def _run_get_metadata(self, request: GetMetadataRequest) -> GetMetadataResponse:
+        raise NotImplementedError()
+
+    async def _handle_metadata(self):
+        response: GetMetadataResponse = await self._run_get_metadata(GetMetadataRequest())
+        self.__service_info = service_info_from_pb(response.serviceInfo)
+        return self.__service_info
+
+    async def _get_metadata(self) -> GrpcResult[ServiceInfo]:
+        if self.__service_info:
+            # noinspection PyArgumentList
+            return GrpcResult(self.__service_info)
+        return await self.try_rpc(lambda: self._handle_metadata())
+
+    async def get_metadata(self) -> GrpcResult[ServiceInfo]:
+        """
+        Retrieve metadata related to this `Service`
+
+        Returns service metadata.
+        """
+        return await self._get_metadata()

zepben/ewb/streaming/get/customer_consumer.py

@@ -0,0 +1,111 @@
+#  Copyright 2024 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__ = ["CustomerConsumerClient", "SyncCustomerConsumerClient"]
+
+from asyncio import get_event_loop
+from typing import Optional, Iterable, AsyncGenerator, List, Callable, Tuple
+
+from zepben.protobuf.cc.cc_pb2_grpc import CustomerConsumerStub
+from zepben.protobuf.cc.cc_requests_pb2 import GetIdentifiedObjectsRequest, GetCustomersForContainerRequest
+from zepben.protobuf.metadata.metadata_requests_pb2 import GetMetadataRequest
+from zepben.protobuf.metadata.metadata_responses_pb2 import GetMetadataResponse
+
+from zepben.ewb import CustomerService, IdentifiedObject, Organisation, Customer, CustomerAgreement, PricingStructure, Tariff, ServiceInfo
+from zepben.ewb.streaming.get.consumer import CimConsumerClient, MultiObjectResult
+from zepben.ewb.streaming.grpc.grpc import GrpcResult
+
+
+class CustomerConsumerClient(CimConsumerClient[CustomerService]):
+    """
+    Consumer client for a :class:`CustomerService`.
+
+    ## WARNING ##
+        The :class:`MultiObjectResult` operations below are not atomic upon a :class:`CustomerService`, and thus if processing fails partway through, any
+        previously successful additions will have been processed by the service, and thus you may have an incomplete service. Also note that adding to the
+        service may not occur for an object if another object with the same mRID is already present in service. `MultiObjectResult.failed` can be used to
+        check for mRIDs that were not found or retrieved but not added to service (this should not be the case unless you are processing things concurrently).
+    """
+
+    __service: CustomerService
+
+    @property
+    def service(self) -> CustomerService:
+        return self.__service
+
+    _stub: CustomerConsumerStub = None
+
+    def __init__(self, channel=None, stub: CustomerConsumerStub = None, error_handlers: List[Callable[[Exception], bool]] = None, timeout: int = 60):
+        super().__init__(error_handlers=error_handlers, timeout=timeout)
+        if channel is None and stub is None:
+            raise ValueError("Must provide either a channel or a stub")
+        if stub is not None:
+            self._stub = stub
+        else:
+            self._stub = CustomerConsumerStub(channel)
+
+        self.__service = CustomerService()
+
+    async def get_customers_for_container(self, mrid: str) -> GrpcResult[MultiObjectResult]:
+        return await self._get_customers_for_containers({mrid})
+
+    async def get_customers_for_containers(self, mrids: Iterable[str]) -> GrpcResult[MultiObjectResult]:
+        return await self._get_customers_for_containers(mrids)
+
+    async def _run_get_metadata(self, request: GetMetadataRequest) -> GetMetadataResponse:
+        return await self._stub.getMetadata(request, timeout=self.timeout)
+
+    async def _get_customers_for_containers(self, mrids: Iterable[str]) -> GrpcResult[MultiObjectResult]:
+        async def rpc():
+            return await self._process_extract_results(None, self._process_customers_for_containers(mrids))
+
+        return await self.try_rpc(rpc)
+
+    async def _process_customers_for_containers(self, mrids: Iterable[str]) -> AsyncGenerator[Tuple[Optional[IdentifiedObject], str], None]:
+        if not mrids:
+            return
+
+        responses = self._stub.getCustomersForContainer(self._batch_send(GetCustomersForContainerRequest(), mrids), timeout=self.timeout)
+        async for response in responses:
+            for cio in response.identifiedObjects:
+                yield self._extract_identified_object("customer", cio, _cio_type_to_cim)
+
+    async def _process_identified_objects(self, mrids: Iterable[str]) -> AsyncGenerator[Tuple[Optional[IdentifiedObject], str], None]:
+        if not mrids:
+            return
+
+        responses = self._stub.getIdentifiedObjects(self._batch_send(GetIdentifiedObjectsRequest(), mrids), timeout=self.timeout)
+        async for response in responses:
+            for cio in response.identifiedObjects:
+                yield self._extract_identified_object("customer", cio, _cio_type_to_cim)
+
+
+class SyncCustomerConsumerClient(CustomerConsumerClient):
+
+    def get_identified_object(self, mrid: str) -> GrpcResult[Optional[IdentifiedObject]]:
+        return get_event_loop().run_until_complete(super()._get_identified_objects(mrid))
+
+    def get_identified_objects(self, mrids: Iterable[str]) -> GrpcResult[MultiObjectResult]:
+        return get_event_loop().run_until_complete(super()._get_identified_objects(mrids))
+
+    def get_customers_for_container(self, mrid: str) -> GrpcResult[MultiObjectResult]:
+        return get_event_loop().run_until_complete(super()._get_customers_for_containers({mrid}))
+
+    def get_customers_for_containers(self, mrids: Iterable[str]) -> GrpcResult[MultiObjectResult]:
+        return get_event_loop().run_until_complete(super()._get_customers_for_containers(mrids))
+
+    def get_metadata(self) -> GrpcResult[ServiceInfo]:
+        return get_event_loop().run_until_complete(super().get_metadata())
+
+
+_cio_type_to_cim = {
+    "organisation": Organisation,
+    "customer": Customer,
+    "customerAgreement": CustomerAgreement,
+    "pricingStructure": PricingStructure,
+    "tariff": Tariff
+}

zepben/ewb/streaming/get/diagram_consumer.py

@@ -0,0 +1,107 @@
+#  Copyright 2024 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__ = ["DiagramConsumerClient", "SyncDiagramConsumerClient"]
+
+from asyncio import get_event_loop
+from typing import Optional, Iterable, AsyncGenerator, List, Callable, Tuple, Union
+
+from zepben.protobuf.dc.dc_pb2_grpc import DiagramConsumerStub
+from zepben.protobuf.dc.dc_requests_pb2 import GetIdentifiedObjectsRequest, GetDiagramObjectsRequest
+from zepben.protobuf.metadata.metadata_requests_pb2 import GetMetadataRequest
+from zepben.protobuf.metadata.metadata_responses_pb2 import GetMetadataResponse
+
+from zepben.ewb import DiagramService, IdentifiedObject, ServiceInfo
+from zepben.ewb.model.cim.iec61970.base.diagramlayout.diagram import Diagram
+from zepben.ewb.model.cim.iec61970.base.diagramlayout.diagram_object import DiagramObject
+from zepben.ewb.streaming.get.consumer import CimConsumerClient, MultiObjectResult
+from zepben.ewb.streaming.grpc.grpc import GrpcResult
+
+
+class DiagramConsumerClient(CimConsumerClient[DiagramService]):
+    """
+    Consumer client for a :class:`DiagramService`.
+
+    ## WARNING ##
+        The :class:`MultiObjectResult` operations below are not atomic upon a :class:`DiagramService`, and thus if processing fails partway through, any
+        previously successful additions will have been processed by the service, and thus you may have an incomplete service. Also note that adding to the
+        service may not occur for an object if another object with the same mRID is already present in service. `MultiObjectResult.failed` can be used to
+        check for mRIDs that were not found or retrieved but not added to service (this should not be the case unless you are processing things concurrently).
+    """
+
+    __service: DiagramService
+
+    @property
+    def service(self) -> DiagramService:
+        return self.__service
+
+    _stub: DiagramConsumerStub = None
+
+    def __init__(self, channel=None, stub: DiagramConsumerStub = None, error_handlers: List[Callable[[Exception], bool]] = None, timeout: int = 60):
+        super().__init__(error_handlers=error_handlers, timeout=timeout)
+        if channel is None and stub is None:
+            raise ValueError("Must provide either a channel or a stub")
+        if stub is not None:
+            self._stub = stub
+        else:
+            self._stub = DiagramConsumerStub(channel)
+
+        self.__service = DiagramService()
+
+    async def get_diagram_objects(self, mrids: Union[str, Iterable[str]]) -> GrpcResult[MultiObjectResult]:
+        return await self._get_diagram_objects(mrids)
+
+    async def _run_get_metadata(self, request: GetMetadataRequest) -> GetMetadataResponse:
+        return await self._stub.getMetadata(request, timeout=self.timeout)
+
+    async def _get_diagram_objects(self, mrids: Union[str, Iterable[str]]) -> GrpcResult[MultiObjectResult]:
+        async def rpc():
+            if isinstance(mrids, str):
+                return await self._process_extract_results(None, self._process_diagram_objects({mrids}))
+            else:
+                return await self._process_extract_results(None, self._process_diagram_objects(mrids))
+
+        return await self.try_rpc(rpc)
+
+    async def _process_diagram_objects(self, mrids: Iterable[str]) -> AsyncGenerator[Tuple[Optional[IdentifiedObject], str], None]:
+        if not mrids:
+            return
+
+        responses = self._stub.getDiagramObjects(self._batch_send(GetDiagramObjectsRequest(), mrids), timeout=self.timeout)
+        async for response in responses:
+            for dio in response.identifiedObjects:
+                yield self._extract_identified_object("diagram", dio, _dio_type_to_cim)
+
+    async def _process_identified_objects(self, mrids: Iterable[str]) -> AsyncGenerator[Tuple[Optional[IdentifiedObject], str], None]:
+        if not mrids:
+            return
+
+        responses = self._stub.getIdentifiedObjects(self._batch_send(GetIdentifiedObjectsRequest(), mrids), timeout=self.timeout)
+        async for response in responses:
+            for dio in response.identifiedObjects:
+                yield self._extract_identified_object("diagram", dio, _dio_type_to_cim)
+
+
+class SyncDiagramConsumerClient(DiagramConsumerClient):
+
+    def get_identified_object(self, mrid: str) -> GrpcResult[Optional[IdentifiedObject]]:
+        return get_event_loop().run_until_complete(super()._get_identified_objects(mrid))
+
+    def get_identified_objects(self, mrids: Iterable[str]) -> GrpcResult[MultiObjectResult]:
+        return get_event_loop().run_until_complete(super()._get_identified_objects(mrids))
+
+    def get_diagram_objects(self, mrid: Union[str, Iterable[str]]) -> GrpcResult[MultiObjectResult]:
+        return get_event_loop().run_until_complete(super()._get_diagram_objects(mrid))
+
+    def get_metadata(self) -> GrpcResult[ServiceInfo]:
+        return get_event_loop().run_until_complete(super().get_metadata())
+
+
+_dio_type_to_cim = {
+    "diagram": Diagram,
+    "diagramObject": DiagramObject
+}

zepben/ewb/streaming/get/hierarchy/__init__.py

@@ -0,0 +1,4 @@
+#  Copyright 2024 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/.

zepben/ewb/streaming/get/hierarchy/data.py

@@ -0,0 +1,27 @@
+#  Copyright 2024 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__ = ["NetworkHierarchy"]
+
+from typing import Dict
+
+from zepben.ewb import Circuit, Loop, Substation
+from zepben.ewb.dataclassy import dataclass
+from zepben.ewb.model.cim.iec61970.base.core.feeder import Feeder
+from zepben.ewb.model.cim.iec61970.base.core.geographical_region import GeographicalRegion
+from zepben.ewb.model.cim.iec61970.base.core.sub_geographical_region import SubGeographicalRegion
+
+
+@dataclass(slots=True)
+class NetworkHierarchy(object):
+    """Container for simplified network hierarchy objects"""
+    geographical_regions: Dict[str, GeographicalRegion]
+    sub_geographical_regions: Dict[str, SubGeographicalRegion]
+    substations: Dict[str, Substation]
+    feeders: Dict[str, Feeder]
+    circuits: Dict[str, Circuit]
+    loops: Dict[str, Loop]

zepben/ewb/streaming/get/included_energized_containers.py

@@ -0,0 +1,36 @@
+#  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/.
+
+__all__ = ["IncludedEnergizedContainers"]
+
+from enum import Enum
+
+from zepben.ewb import unique
+
+
+@unique
+class IncludedEnergizedContainers(Enum):
+    """
+    Indicates which energized contains should be included when fetching a container.
+    """
+
+    NONE = 0
+    """
+    All energized containers should be excluded.
+    """
+
+    FEEDERS = 1
+    """
+    Energized HV feeders should be included.
+    """
+
+    LV_FEEDERS = 2
+    """
+    Energized HV feeders and LV feeders should be included.
+    """
+
+    @property
+    def short_name(self):
+        return str(self)[28:]

zepben/ewb/streaming/get/included_energizing_containers.py

@@ -0,0 +1,36 @@
+#  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/.
+
+__all__ = ["IncludedEnergizingContainers"]
+
+from enum import Enum
+
+from zepben.ewb.util import unique
+
+
+@unique
+class IncludedEnergizingContainers(Enum):
+    """
+    Indicates which energizing contains should be included when fetching a container.
+    """
+
+    NONE = 0
+    """
+    All energizing containers should be excluded.
+    """
+
+    FEEDERS = 1
+    """
+    Energizing feeders should be included.
+    """
+
+    SUBSTATIONS = 2
+    """
+    Energizing feeders and substations should be included.
+    """
+
+    @property
+    def short_name(self):
+        return str(self)[29:]