Rename BatteryPoolWrapper -> BatteryPool

Also improve its public facing documentation.

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

Author: shsms

src/frequenz/sdk/microgrid/_data_pipeline.py

@@ -38,7 +38,7 @@
         Request,
         Result,
     )
-    from ..timeseries.battery_pool import BatteryPoolWrapper
+    from ..timeseries.battery_pool import BatteryPool
     from ..timeseries.battery_pool._battery_pool_reference_store import (
         BatteryPoolReferenceStore,
     )
@@ -191,13 +191,11 @@ def battery_pool(
         battery_ids: abc.Set[int] | None = None,
         name: str | None = None,
         priority: int = -sys.maxsize - 1,
-    ) -> BatteryPoolWrapper:
-        """Return the corresponding BatteryPool instance for the given ids.
+    ) -> BatteryPool:
+        """Return a new BatteryPool instance for the given ids.
 
-        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.
+        If a BatteryPoolReferenceStore instance for the given battery ids doesn't exist,
+        a new one is created and used for creating the BatteryPool.
 
         Args:
             battery_ids: Optional set of IDs of batteries to be managed by the
@@ -207,9 +205,10 @@ def battery_pool(
             priority: The priority of the actor making the call.
 
         Returns:
-            A BatteryPoolWrapper instance.
+            A BatteryPool instance.
+
         """
-        from ..timeseries.battery_pool import BatteryPoolWrapper
+        from ..timeseries.battery_pool import BatteryPool
         from ..timeseries.battery_pool._battery_pool_reference_store import (
             BatteryPoolReferenceStore,
         )
@@ -239,7 +238,7 @@ def battery_pool(
                 batteries_id=battery_ids,
             )
 
-        return BatteryPoolWrapper(self._battery_pools[key], name, priority)
+        return BatteryPool(self._battery_pools[key], name, priority)
 
     def _start_power_managing_actor(self) -> None:
         """Start the power managing actor if it is not already running."""
@@ -433,11 +432,8 @@ def battery_pool(
     battery_ids: abc.Set[int] | 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.
+) -> BatteryPool:
+    """Return a new BatteryPool instance for the given parameters.
 
     The priority value is used to resolve conflicts when multiple actors are trying to
     propose different power values for the same set of batteries.
@@ -446,8 +442,6 @@ def battery_pool(
         When specifying priority, bigger values indicate higher priority. The default
         priority is the lowest possible value.
 
-    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.

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

@@ -3,10 +3,10 @@
 
 """Manage a pool of batteries."""
 
-from ._battery_pool_wrapper import BatteryPoolWrapper
+from ._battery_pool import BatteryPool
 from ._result_types import PowerMetrics
 
 __all__ = [
-    "BatteryPoolWrapper",
+    "BatteryPool",
     "PowerMetrics",
 ]

…es/battery_pool/_battery_pool_wrapper.py …timeseries/battery_pool/_battery_pool.pysrc/frequenz/sdk/timeseries/battery_pool/_battery_pool_wrapper.py renamed to src/frequenz/sdk/timeseries/battery_pool/_battery_pool.py src/frequenz/sdk/timeseries/battery_pool/_battery_pool_wrapper.py renamed to src/frequenz/sdk/timeseries/battery_pool/_battery_pool.py

@@ -36,12 +36,23 @@
 # pylint: disable=protected-access
 
 
-class BatteryPoolWrapper:
-    """The BatteryPoolWrapper is the external interface for the BatteryPool.
-
-    BatteryPoolReferenceStore instances are unique to a set of batteries.  The
-    BatteryPoolWrapper provides an abstraction over actor priorities when multiple
-    actors want to use the same set of batteries.
+class BatteryPool:
+    """An interface for interaction with pools of batteries.
+
+    Use the [microgrid.battery_pool][frequenz.sdk.microgrid.battery_pool] method for
+    creating `BatteryPool` instances.
+
+    Provides:
+      - properties for fetching reporting streams of instantaneous
+        [power][frequenz.sdk.timeseries.battery_pool.BatteryPool.power],
+        [soc][frequenz.sdk.timeseries.battery_pool.BatteryPool.soc],
+        [capacity][frequenz.sdk.timeseries.battery_pool.BatteryPool.capacity] values and
+        available power bounds and other status through
+        [power_status][frequenz.sdk.timeseries.battery_pool.BatteryPool.power_status].
+      - control methods for proposing power values, namely:
+        [propose_power][frequenz.sdk.timeseries.battery_pool.BatteryPool.propose_power],
+        [propose_charge][frequenz.sdk.timeseries.battery_pool.BatteryPool.propose_charge] and
+        [propose_discharge][frequenz.sdk.timeseries.battery_pool.BatteryPool.propose_discharge].
     """
 
     def __init__(
@@ -50,7 +61,7 @@ def __init__(
         name: str | None,
         priority: int,
     ):
-        """Create a BatteryPoolWrapper instance.
+        """Create a BatteryPool instance.
 
         Args:
             battery_pool_ref: The battery pool reference store instance.

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

@@ -31,7 +31,7 @@ class BatteryPoolReferenceStore:  # pylint: disable=too-many-instance-attributes
     These are independent of the priority of the actors, and can be shared between
     multiple users of the same set of batteries.
 
-    They are exposed through the BatteryPoolWrapper class.
+    They are exposed through the BatteryPool class.
     """
 
     def __init__(  # pylint: disable=too-many-arguments

tests/timeseries/_battery_pool/test_battery_pool.py

@@ -36,7 +36,7 @@
     Sample,
     Temperature,
 )
-from frequenz.sdk.timeseries.battery_pool import BatteryPoolWrapper, PowerMetrics
+from frequenz.sdk.timeseries.battery_pool import BatteryPool, PowerMetrics
 from frequenz.sdk.timeseries.battery_pool._metric_calculator import (
     battery_inverter_mapping,
 )
@@ -90,7 +90,7 @@ def get_components(
 class SetupArgs:
     """Setup arguments needed to run tests."""
 
-    battery_pool: BatteryPoolWrapper
+    battery_pool: BatteryPool
     """Battery pool that should be tested."""
 
     min_update_interval: float