Accept name as parameter in call to microgrid.battery_pool()

And explicitly create a new source_id for every new instance of
BatteryPoolWrapper.

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

Author: shsms

src/frequenz/sdk/actor/_power_managing/_base_classes.py

@@ -78,10 +78,29 @@ class Proposal:
     """A proposal for a battery to be charged or discharged."""
 
     source_id: str
+    """The source ID of the actor sending the request."""
+
     preferred_power: Power | None
+    """The preferred power to be distributed to the batteries.
+
+    If `None`, the preferred power of higher priority actors will get precedence.
+    """
+
     bounds: timeseries.Bounds[Power | None]
+    """The power bounds for the proposal.
+
+    These bounds will apply to actors with a lower priority, and can be overridden by
+    bounds from actors with a higher priority.  If None, the power bounds will be set to
+    the maximum power of the batteries in the pool.  This is currently and experimental
+    feature.
+    """
+
     battery_ids: frozenset[int]
+    """The battery IDs to distribute the power to."""
+
     priority: int
+    """The priority of the actor sending the proposal."""
+
     request_timeout: datetime.timedelta = datetime.timedelta(seconds=5.0)
     """The maximum amount of time to wait for the request to be fulfilled."""
 

src/frequenz/sdk/microgrid/_data_pipeline.py

@@ -186,7 +186,7 @@ def ev_charger_pool(
     def battery_pool(
         self,
         battery_ids: abc.Set[int] | None = None,
-        source_id: str | None = None,
+        name: str | None = None,
         priority: int = -sys.maxsize - 1,
     ) -> BatteryPoolWrapper:
         """Return the corresponding BatteryPool instance for the given ids.
@@ -199,7 +199,8 @@ def battery_pool(
         Args:
             battery_ids: Optional set of IDs of batteries to be managed by the
                 BatteryPool.
-            source_id: The source ID to use for the requests made with this instance.
+            name: An optional name used to identify this instance of the pool or a
+                corresponding actor in the logs.
             priority: The priority of the actor making the call.
 
         Returns:
@@ -232,7 +233,7 @@ def battery_pool(
                 batteries_id=battery_ids,
             )
 
-        return BatteryPoolWrapper(self._battery_pools[key], source_id, priority)
+        return BatteryPoolWrapper(self._battery_pools[key], name, priority)
 
     def _start_power_managing_actor(self) -> None:
         """Start the power managing actor if it is not already running."""
@@ -424,27 +425,27 @@ def ev_charger_pool(ev_charger_ids: set[int] | None = None) -> EVChargerPool:
 
 def battery_pool(
     battery_ids: abc.Set[int] | None = None,
-    source_id: str | None = None,
+    name: str | None = None,
     priority: int = -sys.maxsize - 1,
 ) -> BatteryPoolWrapper:
     """Return the corresponding BatteryPool instance for the given ids.
 
-    If a BatteryPool instance for the given ids doesn't exist, a new one is
-    created and returned.
+    If a BatteryPool instance for the given ids doesn't exist, a new one is created and
+    returned.
 
     The BatteryPool is wrapped in a new `BatteryPoolWrapper` instance each time.
 
     Args:
-        battery_ids: Optional set of IDs of batteries to be managed by the
-            BatteryPool.  If not specified, all batteries available in the
-            component graph are used.
-        source_id: The source ID to use for the requests made with this instance.
+        battery_ids: Optional set of IDs of batteries to be managed by the BatteryPool.
+            If not specified, all batteries available in the component graph are used.
+        name: An optional name used to identify this instance of the pool or a
+            corresponding actor in the logs.
         priority: The priority of the actor making the call.
 
     Returns:
         A BatteryPool instance.
     """
-    return _get().battery_pool(battery_ids, source_id, priority)
+    return _get().battery_pool(battery_ids, name, priority)
 
 
 def _get() -> _DataPipeline:

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

@@ -44,17 +44,17 @@ class BatteryPoolWrapper:
     same set of batteries.
     """
 
-    def __init__(self, battery_pool: BatteryPool, source_id: str | None, priority: int):
+    def __init__(self, battery_pool: BatteryPool, name: str | None, priority: int):
         """Create a BatteryPoolWrapper instance.
 
         Args:
             battery_pool: The battery pool to wrap.
-            source_id: The source ID to use for the requests made by this wrapper.
+            name: The source ID to use for the requests made by this wrapper.
             priority: The priority of the actor using this wrapper.
         """
         self._battery_pool = battery_pool
         unique_id = str(uuid.uuid4())
-        self._source_id = unique_id if source_id is None else f"{source_id}-{unique_id}"
+        self._source_id = unique_id if name is None else f"{name}-{unique_id}"
         self._priority = priority
 
     async def propose_power(