Add type-hints for the component graph bindings

Signed-off-by: Sahas Subramanian <[email protected]>

Author: shsms

python/frequenz/microgrid_component_graph/__init__.pyi

@@ -0,0 +1,332 @@
+# License: MIT
+# Copyright © 2025 Frequenz Energy-as-a-Service GmbH
+
+# Type hints for the component graph module.
+
+"""A graph representation of the electrical components in a microgrid."""
+
+from collections.abc import Iterable, Set
+from typing import Generic, Protocol, TypeVar
+
+class InvalidGraphError(Exception):
+    """Exception type that will be thrown if graph data is not valid."""
+
+class FormulaGenerationError(Exception):
+    """Encountered during formula generation from the component graph."""
+
+class ComponentGraphConfig:
+    """Configuration for the component graph."""
+
+    def __init__(
+        self,
+        allow_component_validation_failures: bool = False,
+        allow_unconnected_components: bool = False,
+        allow_unspecified_inverters: bool = False,
+        disable_fallback_components: bool = False,
+    ) -> None:
+        """Initialize this instance.
+
+        Args:
+            allow_component_validation_failures: Whether to allow validation errors on
+                components.  When this is `True`, the graph will be built even if there
+                are validation errors on the components.
+            allow_unconnected_components: Whether to allow unconnected components in the
+                graph, that are not reachable from the root.
+            allow_unspecified_inverters: Whether to allow untyped inverters in the
+                graph.  When this is `True`, inverters that have
+                `InverterType::Unspecified` will be assumed to be Battery inverters.
+            disable_fallback_components: Whether to disable fallback components in
+                generated formulas.  When this is `True`, the formulas will not include
+                fallback components.
+        """
+
+class ComponentIdProtocol(Protocol):
+    def __int__(self) -> int:
+        """Get the integer representation of the Component ID."""
+
+class ComponentProtocol(Protocol):
+    @property
+    def id(self) -> ComponentIdProtocol:
+        """The Component ID"""
+
+class ConnectionProtocol(Protocol):
+    @property
+    def source(self) -> ComponentIdProtocol:
+        """The ID of the component at the start of the connection."""
+
+    @property
+    def destination(self) -> ComponentIdProtocol:
+        """The ID of the component at the end of the connection."""
+
+ComponentT = TypeVar("ComponentT", bound=ComponentProtocol)
+ConnectionT = TypeVar("ConnectionT", bound=ConnectionProtocol)
+ComponentIdT = TypeVar("ComponentIdT", bound=ComponentIdProtocol)
+
+class ComponentGraph(Generic[ComponentT, ConnectionT, ComponentIdT]):
+    """A graph representation of the electrical components in a microgrid."""
+
+    def __init__(
+        self,
+        components: Iterable[ComponentT],
+        connections: Iterable[ConnectionT],
+        config: ComponentGraphConfig = ComponentGraphConfig(),
+    ) -> None:
+        """Initialize this instance.
+
+        Args:
+            components: The list of components to build the graph with.
+            connections: The list of connections between the components.
+            config: The configuration for the component graph.
+
+        Raises:
+            InvalidGraphError: if a valid graph cannot be constructed from the given
+                components and connections, based on the given configs.
+        """
+
+    def component(self, component_id: ComponentIdT) -> ComponentT:
+        """Fetch the component with the specified `component_id`.
+
+        Args:
+            component_id: The id of the component to look for.
+
+        Returns:
+            The component with the given id.
+
+        Raises:
+            ValueError: if no component exists with the given ID.
+        """
+
+    def components(
+        self,
+        matching_ids: Iterable[ComponentIdT] | ComponentIdT | None = None,
+        matching_types: Iterable[type[ComponentT]] | type[ComponentT] | None = None,
+    ) -> set[ComponentT]:
+        """Fetch all components in this graph.
+
+        Returns:
+            A set of all components in this graph.
+        """
+
+    def connections(self) -> Set[ConnectionT]:
+        """Fetch all connections in this graph.
+
+        Returns:
+            A set of all connections in this graph.
+        """
+
+    def predecessors(self, component_id: ComponentIdT) -> Set[ComponentT]:
+        """Fetch all predecessors of the specified component ID.
+
+        Args:
+            component_id: ID of the component whose predecessors should be fetched.
+
+        Returns:
+            A set of components that are predecessors of the given component ID.
+
+        Raises:
+            ValueError: if no component exists with the given ID.
+        """
+
+    def successors(self, component_id: ComponentIdT) -> Set[ComponentT]:
+        """Fetch all successors of the specified component ID.
+
+        Args:
+            component_id: ID of the component whose successors should be fetched.
+
+        Returns:
+            A set of components that are successors of the given component ID.
+
+        Raises:
+            ValueError: if no component exists with the given ID.
+        """
+
+    def is_pv_meter(self, component_id: ComponentIdT) -> bool:
+        """Check if the specified component is a PV meter.
+
+        A meter is identified as a PV meter if:
+          - it has at least one successor,
+          - all its successors are PV inverters.
+
+        Args:
+            component_id: ID of the component to check.
+
+        Returns:
+            Whether the specified component is a PV meter.
+
+        Raises:
+            ValueError: if no component exists with the given ID.
+        """
+
+    def is_battery_meter(self, component_id: ComponentIdT) -> bool:
+        """Check if the specified component is a battery meter.
+
+        A meter is identified as a battery meter if:
+          - it has at least one successor,
+          - all its successors are battery inverters.
+
+        Args:
+            component_id: ID of the component to check.
+
+        Returns:
+            Whether the specified component is a battery meter.
+
+        Raises:
+            ValueError: if no component exists with the given ID.
+        """
+
+    def is_ev_charger_meter(self, component_id: ComponentIdT) -> bool:
+        """Check if the specified component is an EV charger meter.
+
+        A meter is identified as an EV charger meter if
+          - it has at least one successor,
+          - all its successors are EV chargers.
+
+        Args:
+            component_id: ID of the component to check.
+
+        Returns:
+            Whether the specified component is an EV charger meter.
+
+        Raises:
+            ValueError: if no component exists with the given ID.
+        """
+
+    def is_chp_meter(self, component_id: ComponentIdT) -> bool:
+        """Check if the specified component is a CHP meter.
+
+        A meter is identified as a CHP meter if
+          - it has at least one successor,
+          - all its successors are CHPs.
+
+        Args:
+            component_id: ID of the component to check.
+
+        Returns:
+            Whether the specified component is a CHP meter.
+
+        Raises:
+            ValueError: if no component exists with the given ID.
+        """
+
+    def consumer_formula(self) -> str:
+        """Generate the consumer formula for this component graph.
+
+        Returns:
+            The consumer formula as a string.
+        """
+
+    def producer_formula(self) -> str:
+        """Generate the producer formula for this component graph.
+
+        Returns:
+            The producer formula as a string.
+        """
+
+    def grid_formula(self) -> str:
+        """Generate the grid formula for this component graph.
+
+        Returns:
+            The grid formula as a string.
+        """
+
+    def pv_formula(self, pv_inverter_ids: Set[ComponentIdT] | None) -> str:
+        """Generate the PV formula for this component graph.
+
+        Args:
+            pv_inverter_ids: The set of PV inverter component IDs to include in
+                the formula.  If `None`, all PV inverters in the graph will be
+                included.
+
+        Returns:
+            The PV formula as a string.
+
+        Raises:
+            FormulaGenerationError: if the given component IDs don't exist or
+                are not PV inverters.
+        """
+
+    def battery_formula(self, battery_ids: Set[ComponentIdT] | None) -> str:
+        """Generate the battery formula for this component graph.
+
+        Args:
+            battery_ids: The set of battery component IDs to include in the
+                formula.  If `None`, all batteries in the graph will be
+                included.
+
+        Returns:
+            The battery formula as a string.
+
+        Raises:
+            FormulaGenerationError: if the given component IDs don't exist or
+                are not batteries.
+        """
+
+    def chp_formula(self, chp_ids: Set[ComponentIdT] | None) -> str:
+        """Generate the CHP formula for this component graph.
+
+        Args:
+            chp_ids: The set of CHP component IDs to include in the formula.  If
+                `None`, all CHPs in the graph will be included.
+
+        Returns:
+            The CHP formula as a string.
+
+        Raises:
+            FormulaGenerationError: if the given component IDs don't exist or
+                are not CHPs.
+        """
+
+    def ev_charger_formula(self, ev_charger_ids: Set[ComponentIdT] | None) -> str:
+        """Generate the EV charger formula for this component graph.
+
+        Args:
+            ev_charger_ids: The set of EV charger component IDs to include in
+                the formula.  If `None`, all EV chargers in the graph will be
+                included.
+
+        Returns:
+            The EV charger formula as a string.
+
+        Raises:
+            FormulaGenerationError: if the given component IDs don't exist or
+                are not EV chargers.
+        """
+
+    def grid_coalesce_formula(self) -> str:
+        """Generate the grid coalesce formula for this component graph.
+
+        Returns:
+            The grid coalesced formula as a string.
+        """
+
+    def battery_coalesce_formula(self, battery_ids: Set[ComponentIdT] | None) -> str:
+        """Generate the battery coalesce formula for this component graph.
+
+        Args:
+            battery_ids: The set of battery inverter component IDs to include in
+                the formula.  If `None`, all battery inverters in the graph will
+                be included.
+
+        Returns:
+            The battery coalesced formula as a string.
+
+        Raises:
+            FormulaGenerationError: if the given component IDs don't exist or
+                are not batteries.
+        """
+
+    def pv_coalesce_formula(self, pv_inverter_ids: Set[ComponentIdT] | None) -> str:
+        """Generate the PV coalesce formula for this component graph.
+
+        Args:
+            pv_inverter_ids: The set of PV inverter component IDs to include in
+                the formula.  If `None`, all PV inverters in the graph will be
+                included.
+
+        Returns:
+            The PV coalesced formula as a string.
+
+        Raises:
+            FormulaGenerationError: if the given component IDs don't exist or
+                are not PV inverters.
+        """