Rename microgrid.battery_pool → microgrid.new_battery_pool

This makes it explicit that each call to this function creates a new
instance of the BatteryPool class, which would hopefully encourage
them to hold on to references to the created objects, rather than
create and discard after each use.

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

Author: shsms

benchmarks/power_distribution/power_distributor.py

@@ -50,7 +50,7 @@ async def send_requests(batteries: set[int], request_num: int) -> list[Result]:
     Returns:
         List of the results from the PowerDistributingActor.
     """
-    battery_pool = microgrid.battery_pool(priority=5, component_ids=batteries)
+    battery_pool = microgrid.new_battery_pool(priority=5, component_ids=batteries)
     results_rx = battery_pool.power_status.new_receiver()
     result: list[Any] = []
     for _ in range(request_num):

examples/battery_pool.py

@@ -30,7 +30,7 @@ async def main() -> None:
         resampler_config=ResamplerConfig(resampling_period=timedelta(seconds=1.0)),
     )
 
-    battery_pool = microgrid.battery_pool(priority=5)
+    battery_pool = microgrid.new_battery_pool(priority=5)
     receivers = [
         battery_pool.soc.new_receiver(limit=1),
         battery_pool.capacity.new_receiver(limit=1),

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

@@ -171,7 +171,7 @@ def _add_system_bounds_tracker(self, component_ids: frozenset[int]) -> None:
         bounds_receiver: Receiver[SystemBounds]
         # pylint: disable=protected-access
         if self._component_category is ComponentCategory.BATTERY:
-            battery_pool = microgrid.battery_pool(
+            battery_pool = microgrid.new_battery_pool(
                 priority=-sys.maxsize - 1, component_ids=component_ids
             )
             bounds_receiver = battery_pool._system_power_bounds.new_receiver()

src/frequenz/sdk/microgrid/__init__.py

@@ -101,8 +101,8 @@
 
 ## Batteries
 
-The total Battery power is available through
-[`battery_pool`][frequenz.sdk.microgrid.battery_pool]'s
+The total Battery power is available through the
+[`battery_pool`][frequenz.sdk.microgrid.new_battery_pool]'s
 [`power`][frequenz.sdk.timeseries.battery_pool.BatteryPool.power].  The battery pool by
 default uses all batteries available at a location, but battery pool instances can be
 created for subsets of batteries if necessary, by specifying the battery ids.
@@ -143,9 +143,9 @@
 The SDK provides a unified interface for interacting with sets of Batteries, EV
 chargers and PV arrays, through their corresponding `Pool`s.
 
-* [Battery pool][frequenz.sdk.microgrid.battery_pool]
 * [EV charger pool][frequenz.sdk.microgrid.ev_charger_pool]
 * [PV pool][frequenz.sdk.microgrid.pv_pool]
+* [Battery pool][frequenz.sdk.microgrid.new_battery_pool]
 
 All of them provide support for streaming aggregated data and for setting the
 power values of the components.
@@ -226,12 +226,12 @@
 from ..actor import ResamplerConfig
 from . import _data_pipeline, connection_manager
 from ._data_pipeline import (
-    battery_pool,
     consumer,
     ev_charger_pool,
     frequency,
     grid,
     logical_meter,
+    new_battery_pool,
     producer,
     pv_pool,
     voltage,
@@ -256,11 +256,11 @@ async def initialize(server_url: str, resampler_config: ResamplerConfig) -> None
 __all__ = [
     "initialize",
     "consumer",
-    "battery_pool",
     "ev_charger_pool",
     "grid",
     "frequency",
     "logical_meter",
+    "new_battery_pool",
     "producer",
     "pv_pool",
     "voltage",

src/frequenz/sdk/microgrid/_data_pipeline.py

@@ -344,7 +344,7 @@ def pv_pool(
             set_operating_point=set_operating_point,
         )
 
-    def battery_pool(
+    def new_battery_pool(
         self,
         *,
         priority: int,
@@ -571,7 +571,7 @@ def ev_charger_pool(
     )
 
 
-def battery_pool(
+def new_battery_pool(
     *,
     priority: int,
     component_ids: abc.Set[int] | None = None,
@@ -608,7 +608,7 @@ def battery_pool(
     Returns:
         A `BatteryPool` instance.
     """
-    return _get().battery_pool(
+    return _get().new_battery_pool(
         priority=priority,
         component_ids=component_ids,
         name=name,

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

@@ -65,8 +65,8 @@ def __init__(
 
         !!! note
             `BatteryPool` instances are not meant to be created directly by users.  Use
-            the [`microgrid.battery_pool`][frequenz.sdk.microgrid.battery_pool] method
-            for creating `BatteryPool` instances.
+            the [`microgrid.new_battery_pool`][frequenz.sdk.microgrid.new_battery_pool]
+            method for creating `BatteryPool` instances.
 
         Args:
             pool_ref_store: The battery pool reference store instance.

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

@@ -66,7 +66,7 @@ def adjust_to_bounds(self, power: Power) -> tuple[Power | None, Power | None]:
             ```python
             from frequenz.sdk import microgrid
 
-            power_status_rx = microgrid.battery_pool(
+            power_status_rx = microgrid.new_battery_pool(
                 priority=5,
             ).power_status.new_receiver()
             power_status = await power_status_rx.receive()

src/frequenz/sdk/timeseries/formula_engine/_formula_engine.py

@@ -253,7 +253,7 @@ class FormulaEngine(
     ```python
     from frequenz.sdk import microgrid
 
-    battery_pool = microgrid.battery_pool(priority=5)
+    battery_pool = microgrid.new_battery_pool(priority=5)
 
     async for power in battery_pool.power.new_receiver():
         print(f"{power=}")
@@ -277,8 +277,8 @@ class FormulaEngine(
     from frequenz.sdk import microgrid
 
     logical_meter = microgrid.logical_meter()
-    battery_pool = microgrid.battery_pool(priority=5)
     ev_charger_pool = microgrid.ev_charger_pool(priority=5)
+    battery_pool = microgrid.new_battery_pool(priority=5)
     grid = microgrid.grid()
 
     # apply operations on formula engines to create a formula engine that would

tests/microgrid/test_datapipeline.py

@@ -68,7 +68,7 @@ async def test_actors_started(
     )
     mock_client.initialize(mocker)
 
-    datapipeline.battery_pool(priority=5)
+    datapipeline.new_battery_pool(priority=5)
 
     assert datapipeline._battery_power_wrapper._power_distributing_actor is not None
     await asyncio.sleep(1)

tests/timeseries/_battery_pool/test_battery_pool.py

@@ -151,7 +151,7 @@ async def setup_all_batteries(mocker: MockerFixture) -> AsyncIterator[SetupArgs]
     # the scope of this tests. This tests should cover BatteryPool only.
     # We use our own battery status channel, where we easily control set of working
     # batteries.
-    battery_pool = microgrid.battery_pool(priority=5)
+    battery_pool = microgrid.new_battery_pool(priority=5)
 
     dp = microgrid._data_pipeline._DATA_PIPELINE
     assert dp is not None
@@ -205,7 +205,7 @@ async def setup_batteries_pool(mocker: MockerFixture) -> AsyncIterator[SetupArgs
     # batteries.
     all_batteries = list(get_components(mock_microgrid, ComponentCategory.BATTERY))
 
-    battery_pool = microgrid.battery_pool(
+    battery_pool = microgrid.new_battery_pool(
         priority=5, component_ids=set(all_batteries[:2])
     )
 
@@ -543,7 +543,7 @@ async def test_batter_pool_power_no_batteries(mocker: MockerFixture) -> None:
         )
     )
     await mockgrid.start(mocker)
-    battery_pool = microgrid.battery_pool(priority=5)
+    battery_pool = microgrid.new_battery_pool(priority=5)
     power_receiver = battery_pool.power.new_receiver()
 
     await mockgrid.mock_resampler.send_non_existing_component_value()
@@ -560,7 +560,7 @@ async def test_battery_pool_power_with_no_inverters(mocker: MockerFixture) -> No
     await mockgrid.start(mocker)
 
     with pytest.raises(RuntimeError):
-        microgrid.battery_pool(priority=5)
+        microgrid.new_battery_pool(priority=5)
 
 
 async def test_battery_pool_power_incomplete_bat_request(mocker: MockerFixture) -> None:
@@ -582,7 +582,7 @@ async def test_battery_pool_power_incomplete_bat_request(mocker: MockerFixture)
 
     with pytest.raises(FormulaGenerationError):
         # Request only two of the three batteries behind the inverters
-        battery_pool = microgrid.battery_pool(
+        battery_pool = microgrid.new_battery_pool(
             priority=5, component_ids=set([bats[1].component_id, bats[0].component_id])
         )
         power_receiver = battery_pool.power.new_receiver()
@@ -592,7 +592,7 @@ async def test_battery_pool_power_incomplete_bat_request(mocker: MockerFixture)
 
 async def _test_battery_pool_power(mockgrid: MockMicrogrid) -> None:
     async with mockgrid:
-        battery_pool = microgrid.battery_pool(priority=5)
+        battery_pool = microgrid.new_battery_pool(priority=5)
         power_receiver = battery_pool.power.new_receiver()
 
         await mockgrid.mock_resampler.send_bat_inverter_power([2.0, 3.0])