Skip to content

Commit 46cb78e

Browse files
shsmsshsms
authored
Rename microgrid.*_pool constructors to new_*_pool (#979)
This makes it explicit that each call to these functions create a new instance of the `*Pool` class, which would hopefully encourage users to hold on to references to the created objects, rather than create and discard after each use.
2 parents 4087414 + abb4f52 commit 46cb78e

File tree

21 files changed

+83
-74
lines changed

21 files changed

+83
-74
lines changed

‎RELEASE_NOTES.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,10 @@
66

77
## Upgrading
88

9-
<!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with -->
9+
- The `frequenz.sdk.microgrid.*_pool` methods has been renamed to `new_*_pool`, to make it explicit that they create new instances of the pool classes.
10+
+ `battery_pool` -> `new_battery_pool`
11+
+ `ev_charger_pool` -> `new_ev_charger_pool`
12+
+ `pv_pool` -> `new_pv_pool`
1013

1114
## New Features
1215

‎benchmarks/power_distribution/power_distributor.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ async def send_requests(batteries: set[int], request_num: int) -> list[Result]:
5050
Returns:
5151
List of the results from the PowerDistributingActor.
5252
"""
53-
battery_pool = microgrid.battery_pool(priority=5, component_ids=batteries)
53+
battery_pool = microgrid.new_battery_pool(priority=5, component_ids=batteries)
5454
results_rx = battery_pool.power_status.new_receiver()
5555
result: list[Any] = []
5656
for _ in range(request_num):

‎examples/battery_pool.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ async def main() -> None:
3030
resampler_config=ResamplerConfig(resampling_period=timedelta(seconds=1.0)),
3131
)
3232

33-
battery_pool = microgrid.battery_pool(priority=5)
33+
battery_pool = microgrid.new_battery_pool(priority=5)
3434
receivers = [
3535
battery_pool.soc.new_receiver(limit=1),
3636
battery_pool.capacity.new_receiver(limit=1),

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -171,20 +171,20 @@ def _add_system_bounds_tracker(self, component_ids: frozenset[int]) -> None:
171171
bounds_receiver: Receiver[SystemBounds]
172172
# pylint: disable=protected-access
173173
if self._component_category is ComponentCategory.BATTERY:
174-
battery_pool = microgrid.battery_pool(
174+
battery_pool = microgrid.new_battery_pool(
175175
priority=-sys.maxsize - 1, component_ids=component_ids
176176
)
177177
bounds_receiver = battery_pool._system_power_bounds.new_receiver()
178178
elif self._component_category is ComponentCategory.EV_CHARGER:
179-
ev_charger_pool = microgrid.ev_charger_pool(
179+
ev_charger_pool = microgrid.new_ev_charger_pool(
180180
priority=-sys.maxsize - 1, component_ids=component_ids
181181
)
182182
bounds_receiver = ev_charger_pool._system_power_bounds.new_receiver()
183183
elif (
184184
self._component_category is ComponentCategory.INVERTER
185185
and self._component_type is InverterType.SOLAR
186186
):
187-
pv_pool = microgrid.pv_pool(
187+
pv_pool = microgrid.new_pv_pool(
188188
priority=-sys.maxsize - 1, component_ids=component_ids
189189
)
190190
bounds_receiver = pv_pool._system_power_bounds.new_receiver()

‎src/frequenz/sdk/microgrid/__init__.py‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,7 @@
8585
## PV Arrays
8686
8787
The total PV power production is available through
88-
[`pv_pool`][frequenz.sdk.microgrid.pv_pool]'s
88+
[`pv_pool`][frequenz.sdk.microgrid.new_pv_pool]'s
8989
[`power`][frequenz.sdk.timeseries.pv_pool.PVPool.power]. The PV pool by default uses
9090
all PV inverters available at a location, but PV pool instances can be created for
9191
subsets of PV inverters if necessary, by specifying the inverter ids.
@@ -101,8 +101,8 @@
101101
102102
## Batteries
103103
104-
The total Battery power is available through
105-
[`battery_pool`][frequenz.sdk.microgrid.battery_pool]'s
104+
The total Battery power is available through the
105+
[`battery_pool`][frequenz.sdk.microgrid.new_battery_pool]'s
106106
[`power`][frequenz.sdk.timeseries.battery_pool.BatteryPool.power]. The battery pool by
107107
default uses all batteries available at a location, but battery pool instances can be
108108
created for subsets of batteries if necessary, by specifying the battery ids.
@@ -123,7 +123,7 @@
123123
124124
## EV Chargers
125125
126-
The [`ev_charger_pool`][frequenz.sdk.microgrid.ev_charger_pool] offers a
126+
The [`ev_charger_pool`][frequenz.sdk.microgrid.new_ev_charger_pool] offers a
127127
[`power`][frequenz.sdk.timeseries.ev_charger_pool.EVChargerPool.power] method that
128128
streams the total power measured for all the {{glossary("ev-charger", "EV Chargers")}}
129129
at a site.
@@ -143,9 +143,9 @@
143143
The SDK provides a unified interface for interacting with sets of Batteries, EV
144144
chargers and PV arrays, through their corresponding `Pool`s.
145145
146-
* [Battery pool][frequenz.sdk.microgrid.battery_pool]
147-
* [EV charger pool][frequenz.sdk.microgrid.ev_charger_pool]
148-
* [PV pool][frequenz.sdk.microgrid.pv_pool]
146+
* [Battery pool][frequenz.sdk.microgrid.new_battery_pool]
147+
* [EV charger pool][frequenz.sdk.microgrid.new_ev_charger_pool]
148+
* [PV pool][frequenz.sdk.microgrid.new_pv_pool]
149149
150150
All of them provide support for streaming aggregated data and for setting the
151151
power values of the components.
@@ -226,14 +226,14 @@
226226
from ..actor import ResamplerConfig
227227
from . import _data_pipeline, connection_manager
228228
from ._data_pipeline import (
229-
battery_pool,
230229
consumer,
231-
ev_charger_pool,
232230
frequency,
233231
grid,
234232
logical_meter,
233+
new_battery_pool,
234+
new_ev_charger_pool,
235+
new_pv_pool,
235236
producer,
236-
pv_pool,
237237
voltage,
238238
)
239239

@@ -256,12 +256,12 @@ async def initialize(server_url: str, resampler_config: ResamplerConfig) -> None
256256
__all__ = [
257257
"initialize",
258258
"consumer",
259-
"battery_pool",
260-
"ev_charger_pool",
261259
"grid",
262260
"frequency",
263261
"logical_meter",
262+
"new_battery_pool",
263+
"new_ev_charger_pool",
264+
"new_pv_pool",
264265
"producer",
265-
"pv_pool",
266266
"voltage",
267267
]

‎src/frequenz/sdk/microgrid/_data_pipeline.py‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -193,7 +193,7 @@ def grid(self) -> Grid:
193193

194194
return self._grid
195195

196-
def ev_charger_pool(
196+
def new_ev_charger_pool(
197197
self,
198198
*,
199199
priority: int,
@@ -270,7 +270,7 @@ def ev_charger_pool(
270270
set_operating_point=set_operating_point,
271271
)
272272

273-
def pv_pool(
273+
def new_pv_pool(
274274
self,
275275
*,
276276
priority: int,
@@ -344,7 +344,7 @@ def pv_pool(
344344
set_operating_point=set_operating_point,
345345
)
346346

347-
def battery_pool(
347+
def new_battery_pool(
348348
self,
349349
*,
350350
priority: int,
@@ -526,7 +526,7 @@ def producer() -> Producer:
526526
return _get().producer()
527527

528528

529-
def ev_charger_pool(
529+
def new_ev_charger_pool(
530530
*,
531531
priority: int,
532532
component_ids: abc.Set[int] | None = None,
@@ -563,15 +563,15 @@ def ev_charger_pool(
563563
Returns:
564564
An `EVChargerPool` instance.
565565
"""
566-
return _get().ev_charger_pool(
566+
return _get().new_ev_charger_pool(
567567
priority=priority,
568568
component_ids=component_ids,
569569
name=name,
570570
set_operating_point=set_operating_point,
571571
)
572572

573573

574-
def battery_pool(
574+
def new_battery_pool(
575575
*,
576576
priority: int,
577577
component_ids: abc.Set[int] | None = None,
@@ -608,15 +608,15 @@ def battery_pool(
608608
Returns:
609609
A `BatteryPool` instance.
610610
"""
611-
return _get().battery_pool(
611+
return _get().new_battery_pool(
612612
priority=priority,
613613
component_ids=component_ids,
614614
name=name,
615615
set_operating_point=set_operating_point,
616616
)
617617

618618

619-
def pv_pool(
619+
def new_pv_pool(
620620
*,
621621
priority: int,
622622
component_ids: abc.Set[int] | None = None,
@@ -653,7 +653,7 @@ def pv_pool(
653653
Returns:
654654
A `PVPool` instance.
655655
"""
656-
return _get().pv_pool(
656+
return _get().new_pv_pool(
657657
priority=priority,
658658
component_ids=component_ids,
659659
name=name,

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -65,8 +65,8 @@ def __init__(
6565
6666
!!! note
6767
`BatteryPool` instances are not meant to be created directly by users. Use
68-
the [`microgrid.battery_pool`][frequenz.sdk.microgrid.battery_pool] method
69-
for creating `BatteryPool` instances.
68+
the [`microgrid.new_battery_pool`][frequenz.sdk.microgrid.new_battery_pool]
69+
method for creating `BatteryPool` instances.
7070
7171
Args:
7272
pool_ref_store: The battery pool reference store instance.

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,7 @@ def adjust_to_bounds(self, power: Power) -> tuple[Power | None, Power | None]:
6666
```python
6767
from frequenz.sdk import microgrid
6868
69-
power_status_rx = microgrid.battery_pool(
69+
power_status_rx = microgrid.new_battery_pool(
7070
priority=5,
7171
).power_status.new_receiver()
7272
power_status = await power_status_rx.receive()

‎src/frequenz/sdk/timeseries/ev_charger_pool/_ev_charger_pool.py‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,8 +50,10 @@ def __init__( # pylint: disable=too-many-arguments
5050
"""Create an `EVChargerPool` instance.
5151
5252
!!! note
53+
5354
`EVChargerPool` instances are not meant to be created directly by users. Use
54-
the [`microgrid.ev_charger_pool`][frequenz.sdk.microgrid.ev_charger_pool]
55+
the
56+
[`microgrid.new_ev_charger_pool`][frequenz.sdk.microgrid.new_ev_charger_pool]
5557
method for creating `EVChargerPool` instances.
5658
5759
Args:

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

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -253,7 +253,7 @@ class FormulaEngine(
253253
```python
254254
from frequenz.sdk import microgrid
255255
256-
battery_pool = microgrid.battery_pool(priority=5)
256+
battery_pool = microgrid.new_battery_pool(priority=5)
257257
258258
async for power in battery_pool.power.new_receiver():
259259
print(f"{power=}")
@@ -266,8 +266,8 @@ class FormulaEngine(
266266
267267
For example, if you're interested in a particular composite metric that can be
268268
calculated by subtracting
269-
[`battery_pool().power`][frequenz.sdk.timeseries.battery_pool.BatteryPool.power] and
270-
[`ev_charger_pool().power`][frequenz.sdk.timeseries.ev_charger_pool.EVChargerPool]
269+
[`new_battery_pool().power`][frequenz.sdk.timeseries.battery_pool.BatteryPool.power] and
270+
[`new_ev_charger_pool().power`][frequenz.sdk.timeseries.ev_charger_pool.EVChargerPool]
271271
from the
272272
[`grid().power`][frequenz.sdk.timeseries.grid.Grid.power],
273273
we can build a `FormulaEngine` that provides a stream of this calculated metric as
@@ -277,8 +277,8 @@ class FormulaEngine(
277277
from frequenz.sdk import microgrid
278278
279279
logical_meter = microgrid.logical_meter()
280-
battery_pool = microgrid.battery_pool(priority=5)
281-
ev_charger_pool = microgrid.ev_charger_pool(priority=5)
280+
battery_pool = microgrid.new_battery_pool(priority=5)
281+
ev_charger_pool = microgrid.new_ev_charger_pool(priority=5)
282282
grid = microgrid.grid()
283283
284284
# apply operations on formula engines to create a formula engine that would
@@ -459,7 +459,7 @@ class FormulaEngine3Phase(
459459
```python
460460
from frequenz.sdk import microgrid
461461
462-
ev_charger_pool = microgrid.ev_charger_pool(priority=5)
462+
ev_charger_pool = microgrid.new_ev_charger_pool(priority=5)
463463
464464
async for sample in ev_charger_pool.current.new_receiver():
465465
print(f"Current: {sample}")
@@ -474,7 +474,7 @@ class FormulaEngine3Phase(
474474
from frequenz.sdk import microgrid
475475
476476
logical_meter = microgrid.logical_meter()
477-
ev_charger_pool = microgrid.ev_charger_pool(priority=5)
477+
ev_charger_pool = microgrid.new_ev_charger_pool(priority=5)
478478
grid = microgrid.grid()
479479
480480
# Calculate grid consumption current that's not used by the EV chargers

0 commit comments

Comments
 (0)