Minor improvements and cleanups (#1293)

This PR focuses on improving test resilience and code maintainability
through refactoring, better logging, timeout additions, and various
cleanups. The changes enhance test reliability by adding timeout
mechanisms to prevent hanging tests and improve code readability through
better imports, simplified logic, and consistent parameter ordering.

**Key changes:**
- Added timeout mechanisms (10 seconds) to test report receiving
operations to prevent hanging tests
- Refactored test fixtures to use shared `stop()` methods for cleaner
cleanup
- Improved type hints for NetworkX graphs and added type stubs to mypy
configuration
- Standardized parameter ordering (positional before keyword-only) in
component status trackers

Author: llucax

docs/user-guide/glossary.md

@@ -58,8 +58,8 @@ article](https://en.wikipedia.org/wiki/State_of_charge) for more details.
 
 A local electrical grid that connects a set of different [types of
 components](#component-category) together. It can be connected to the public
-[grid](#grid), or be completely isolated, in which case it is known as an
-island.
+[grid](#grid) (through a [grid connection point](#grid-connection-point)), or be completely isolated, in which case
+it is known as an island.
 
 Components can be grouped into [assets](#assets) and [devices](#devices).
 Assets are core components like generators or storage systems that are crucial from a business perspective,
@@ -105,6 +105,15 @@ A station for charging [EVs](#ev).
 
 A device that converts water into hydrogen and oxygen.
 
+#### Grid Connection Point
+
+The point where the local [microgrid](#microgrid) is connected to the public
+electricity [grid](#grid).
+
+#### GCP
+
+[Grid connection point](#grid-connection-point).
+
 #### Grid
 
 A point where the local [microgrid](#microgrid) is connected to the public

pyproject.toml

@@ -71,6 +71,7 @@ dev-mypy = [
   "types-Markdown == 3.9.0.20250906",
   "types-protobuf == 6.32.1.20250918",
   "types-setuptools == 80.9.0.20250822",
+  "types-networkx == 3.5.0.20251106",
   # For checking the noxfile, docs/ script, and tests
   "frequenz-sdk[dev-mkdocs,dev-noxfile,dev-pytest]",
 ]
@@ -204,13 +205,7 @@ files = ["src", "tests", "examples", "benchmarks", "docs", "noxfile.py"]
 strict = true
 
 [[tool.mypy.overrides]]
-module = [
-  "async_solipsism",
-  "mkdocs_macros.*",
-  # The available stubs packages are outdated or incomplete (WIP/experimental):
-  # https://github.com/frequenz-floss/frequenz-sdk-python/issues/430
-  "networkx",
-]
+module = ["async_solipsism", "mkdocs_macros.*"]
 ignore_missing_imports = true
 
 [tool.setuptools_scm]

src/frequenz/sdk/microgrid/__init__.py

@@ -32,7 +32,7 @@
 
 subgraph Left[Measurements only]
 direction LR
-  grid["Grid Connection"]
+  grid["Grid Connection Point"]
   consumer["Consumer"]
   pv["PV Arrays"]
   chp["CHP"]
@@ -57,12 +57,12 @@
 
 ## Grid
 
-This refers to a microgrid's connection to the external Grid.  The power flowing through
-this connection can be streamed through
+This refers to a microgrid's {{glossary("grid-connection-point")}}.  The power flowing
+through this connection can be streamed through
 [`grid_power`][frequenz.sdk.timeseries.grid.Grid.power].
 
-In locations without a grid connection, this method remains accessible, and streams zero
-values.
+In locations without a grid connection point, this method remains accessible, and
+streams zero values.
 
 ## Consumer
 

src/frequenz/sdk/microgrid/_power_distributing/_component_managers/_battery_manager.py

@@ -609,7 +609,7 @@ def _get_power_distribution(
         for inverter_ids in [
             self._bat_invs_map[battery_id_set] for battery_id_set in unavailable_bat_ids
         ]:
-            unavailable_inv_ids = unavailable_inv_ids.union(inverter_ids)
+            unavailable_inv_ids = unavailable_inv_ids | inverter_ids
 
         result = self._distribution_algorithm.distribute_power(
             request.power, inv_bat_pairs

src/frequenz/sdk/microgrid/_power_distributing/_component_status/_battery_status_tracker.py

@@ -100,25 +100,25 @@ class BatteryStatusTracker(ComponentStatusTracker, BackgroundService):
     @override
     def __init__(  # pylint: disable=too-many-arguments
         self,
-        *,
         component_id: ComponentId,
-        max_data_age: timedelta,
-        max_blocking_duration: timedelta,
         status_sender: Sender[ComponentStatus],
         set_power_result_receiver: Receiver[SetPowerResult],
+        *,
+        max_data_age: timedelta,
+        max_blocking_duration: timedelta,
     ) -> None:
         """Create class instance.
 
         Args:
             component_id: Id of this battery
+            status_sender: Channel to send status updates.
+            set_power_result_receiver: Channel to receive results of the requests to the
+                components.
             max_data_age: If component stopped sending data, then this is the maximum
                 time when its last message should be considered as valid. After that
                 time, component won't be used until it starts sending data.
             max_blocking_duration: This value tell what should be the maximum
                 timeout used for blocking failing component.
-            status_sender: Channel to send status updates.
-            set_power_result_receiver: Channel to receive results of the requests to the
-                components.
 
         Raises:
             RuntimeError: If battery has no adjacent inverter.

src/frequenz/sdk/microgrid/_power_distributing/_component_status/_component_status.py

@@ -88,23 +88,23 @@ class ComponentStatusTracker(BackgroundService, ABC):
     @abstractmethod
     def __init__(  # pylint: disable=too-many-arguments,super-init-not-called
         self,
-        *,
         component_id: ComponentId,
-        max_data_age: timedelta,
-        max_blocking_duration: timedelta,
         status_sender: Sender[ComponentStatus],
         set_power_result_receiver: Receiver[SetPowerResult],
+        *,
+        max_data_age: timedelta,
+        max_blocking_duration: timedelta,
     ) -> None:
         """Create class instance.
 
         Args:
             component_id: Id of this component
+            status_sender: Channel to send status updates.
+            set_power_result_receiver: Channel to receive results of the requests to the
+                components.
             max_data_age: If component stopped sending data, then this is the maximum
                 time when its last message should be considered as valid. After that
                 time, component won't be used until it starts sending data.
             max_blocking_duration: This value tell what should be the maximum
                 timeout used for blocking failing component.
-            status_sender: Channel to send status updates.
-            set_power_result_receiver: Channel to receive results of the requests to the
-                components.
         """

src/frequenz/sdk/microgrid/_power_distributing/_component_status/_ev_charger_status_tracker.py

@@ -44,25 +44,25 @@ class EVChargerStatusTracker(ComponentStatusTracker, BackgroundService):
     @override
     def __init__(  # pylint: disable=too-many-arguments
         self,
-        *,
         component_id: ComponentId,
-        max_data_age: timedelta,
-        max_blocking_duration: timedelta,
         status_sender: Sender[ComponentStatus],
         set_power_result_receiver: Receiver[SetPowerResult],
+        *,
+        max_data_age: timedelta,
+        max_blocking_duration: timedelta,
     ) -> None:
         """Initialize this instance.
 
         Args:
             component_id: ID of the EV charger to monitor the status of.
-            max_data_age: max duration to wait for, before marking a component as
-                NOT_WORKING, unless new data arrives.
-            max_blocking_duration: duration for which the component status should be
-                UNCERTAIN if a request to the component failed unexpectedly.
             status_sender: Channel sender to send status updates to.
             set_power_result_receiver: Receiver to fetch PowerDistributor responses
                 from, to get the status of the most recent request made for an EV
                 Charger.
+            max_data_age: max duration to wait for, before marking a component as
+                NOT_WORKING, unless new data arrives.
+            max_blocking_duration: duration for which the component status should be
+                UNCERTAIN if a request to the component failed unexpectedly.
         """
         self._component_id = component_id
         self._max_data_age = max_data_age

src/frequenz/sdk/microgrid/component_graph.py

@@ -369,7 +369,7 @@ def __init__(
             InvalidGraphError: If `components` and `connections` are not both `None`
                 and either of them is either `None` or empty.
         """
-        self._graph: nx.DiGraph = nx.DiGraph()
+        self._graph: nx.DiGraph[ComponentId] = nx.DiGraph()
 
         if components is None and connections is None:
             return
@@ -437,6 +437,7 @@ def connections(
         """
         matching_sources = _comp_ids_to_iter(matching_sources)
         matching_destinations = _comp_ids_to_iter(matching_destinations)
+        selection: Iterable[tuple[ComponentId, ComponentId]]
 
         match (matching_sources, matching_destinations):
             case (None, None):
@@ -536,7 +537,7 @@ def refresh_from(
         if issues:
             raise InvalidGraphError(f"Invalid component data: {', '.join(issues)}")
 
-        new_graph = nx.DiGraph()
+        new_graph: nx.DiGraph[ComponentId] = nx.DiGraph()
         new_graph.add_nodes_from(
             (component.id, {_DATA_KEY: component}) for component in components
         )
@@ -1120,6 +1121,11 @@ def _validate_leaf_components(self) -> None:
                 f"Leaf components with graph successors: {with_successors}"
             )
 
+    @override
+    def __repr__(self) -> str:
+        """Return a string representation of the component graph."""
+        return f"ComponentGraph({self._graph!r})"
+
 
 def _comp_ids_to_iter(
     ids: Iterable[ComponentId] | ComponentId | None,

src/frequenz/sdk/microgrid/connection_manager.py

@@ -46,7 +46,7 @@ def api_client(self) -> MicrogridApiClient:
         """Get the MicrogridApiClient.
 
         Returns:
-            api client
+            The microgrid API client used by this connection manager.
         """
 
     @property
@@ -172,28 +172,23 @@ async def initialize(server_url: str) -> None:
             where the port should be an int between `0` and `65535` (defaulting to
             `9090`) and ssl should be a boolean (defaulting to false). For example:
             `grpc://localhost:1090?ssl=true`.
-
-    Raises:
-        AssertionError: If method was called more then once.
     """
     # From Doc: pylint just try to discourage this usage.
     # That doesn't mean you cannot use it.
     global _CONNECTION_MANAGER  # pylint: disable=global-statement
 
-    if _CONNECTION_MANAGER is not None:
-        raise AssertionError("MicrogridApi was already initialized.")
+    assert _CONNECTION_MANAGER is None, "MicrogridApi was already initialized."
 
     _logger.info("Connecting to microgrid at %s", server_url)
 
-    microgrid_api = _InsecureConnectionManager(server_url)
-    await microgrid_api._initialize()  # pylint: disable=protected-access
+    connection_manager = _InsecureConnectionManager(server_url)
+    await connection_manager._initialize()  # pylint: disable=protected-access
 
     # Check again that _MICROGRID_API is None in case somebody had the great idea of
     # calling initialize() twice and in parallel.
-    if _CONNECTION_MANAGER is not None:
-        raise AssertionError("MicrogridApi was already initialized.")
+    assert _CONNECTION_MANAGER is None, "MicrogridApi was already initialized."
 
-    _CONNECTION_MANAGER = microgrid_api
+    _CONNECTION_MANAGER = connection_manager
 
 
 def get() -> ConnectionManager:

src/frequenz/sdk/timeseries/battery_pool/_methods.py

@@ -252,11 +252,8 @@ async def _send_on_update(self, min_update_interval: timedelta) -> None:
                 latest_calculation_result = result
                 await sender.send(result)
 
-                if result is None:
-                    sleep_for = min_update_interval.total_seconds()
-                else:
-                    # Sleep for the rest of the time.
-                    # Then we won't send update more frequently then min_update_interval
-                    time_diff = datetime.now(tz=timezone.utc) - result.timestamp
-                    sleep_for = (min_update_interval - time_diff).total_seconds()
+                # Sleep for the rest of the time.
+                # Then we won't send update more frequently than min_update_interval
+                time_diff = datetime.now(tz=timezone.utc) - result.timestamp
+                sleep_for = (min_update_interval - time_diff).total_seconds()
                 await asyncio.sleep(sleep_for)