Frequenz Python SDK Release Notes
Summary
This release represents 3 months of work so it includes a lot of changes. Most of them are (breaking) API changes, in the hopes to make a more consistent and easier to use SDK 1.0. There are also quite a few bug fixes and a couple of new features.
Upgrading
- The `BatteryPool.power_status` method now streams objects of type `BatteryPoolReport`, replacing the previous `Report` objects.
- `Channels` has been upgraded to version 1.0.0b2, for information on how to upgrade please read [Channels release notes](https://github.com/frequenz-floss/frequenz-channels-python/releases/tag/v1.0.0-beta.2).
- In `BatteryPoolReport.distribution_result`,
* the following fields have been renamed:
+ `Result.succeeded_batteries` → `Result.succeeded_components`
+ `Result.failed_batteries` → `Result.failed_components`
+ `Request.batteries` → `Request.component_ids`
* and the following fields are now type-hinted as `collections.abc.Set`, to clearly indicate that they are read-only:
+ `Result.succeeded_components`
+ `Result.failed_components`
- The `Fuse` class has been moved to the `frequenz.sdk.timeseries` module.
- `microgrid.grid()`
- A `Grid` object is always instantiated now, even if the microgrid is not connected to the grid (islanded microgrids).
- The rated current of the grid fuse is set to `Current.zero()` in case of islanded microgrids.
- The grid fuse is set to `None` when the grid connection component metadata lacks information about the fuse.
- Grid power and current metrics were moved from `microgrid.logical_meter()` to `microgrid.grid()`.
Previously,
python
logical_meter = microgrid.logical_meter()
grid_power_recv = logical_meter.grid_power.new_receiver()
grid_current_recv = logical_meter.grid_current.new_receiver()
Now,
python
grid = microgrid.grid()
grid_power_recv = grid.power.new_receiver()
grid_current_recv = grid.current.new_receiver()
- Consumer and producer power formulas were moved from `microgrid.logical_meter()` to `microgrid.consumer()` and `microgrid.producer()`, respectively.
Previously,
python
logical_meter = microgrid.logical_meter()
consumer_power_recv = logical_meter.consumer_power.new_receiver()
producer_power_recv = logical_meter.producer_power.new_receiver()
Now,
python
consumer_power_recv = microgrid.consumer().power.new_receiver()
producer_power_recv = microgrid.producer().power.new_receiver()
- The `ComponentGraph.components()` parameters `component_id` and `component_category` were renamed to `component_ids` and `component_categories`, respectively.
- The `GridFrequency.component` property was renamed to `GridFrequency.source`
- The `microgrid.frequency()` method no longer supports passing the `component` parameter. Instead the best component is automatically selected.
- The `actor.ChannelRegistry` was rewritten to be type-aware and just a container of channels. You now need to provide the type of message that will be contained by the channel and use the `get_or_create()` method to get a channel and the `stop_and_remove()` method to stop and remove a channel. Once you get a channel you can create new senders and receivers, or set channel options, as usual. Please read the docs for a full description, but in general this:
python
r = registry.new_receiver(name)
s = registry.new_sender(name)
Should be replaced by:
python
r = registry.get_or_create(T, name).new_receiver()
s = registry.get_or_create(T, name).new_sender()
- The `ReceiverFetcher` interface was slightly changed to make `maxsize` a keyword-only argument. This is to make it compatible with the `Broadcast` channel, so it can be considered a `ReceiverFetcher`.
New Features
- A new method `microgrid.voltage()` was added to allow easy access to the phase-to-neutral 3-phase voltage of the microgrid.
- The `actor.ChannelRegistry` is now type-aware.
- A new class method `Quantity.from_string()` has been added to allow the creation of `Quantity` objects from strings.
Bug Fixes
- 0W power requests are now not adjusted to exclusion bounds by the `PowerManager` and `PowerDistributor`, and are sent over to the microgrid API directly.
- `microgrid.frequency()` / `GridFrequency`:
* Fix sent samples to use `Frequency` objects instead of raw `Quantity`.
* Handle `None` values in the received samples properly.
* Convert `nan` values in the received samples to `None`.
- The resampler now properly handles sending zero values.
A bug made the resampler interpret zero values as `None` when generating new samples, so if the result of the resampling is zero, the resampler would just produce `None` values.
- The PowerManager no longer holds on to proposals from dead actors forever. If an actor hasn't sent a new proposal in 60 seconds, the available proposal from that actor is dropped.
- Fix `Quantity.__format__()` sometimes skipping the number for very small values.
- Not strictly a bug fix, but the microgrid API version was bumped to v0.15.3, which indirectly bumps the common API dependency to v0.5.x, so the SDK can be compatible with other APIs using a newer version of the common API.
Downstream projects that require a `frequenz-api-common` v0.5.x and want to ensure proper dependency resolution should update their minimum SDK version to this release.
What's Changed
* Clear release notes by llucax in https://github.com/frequenz-floss/frequenz-sdk-python/pull/777
* Make `PowerManagingActor` more modular and generic by shsms in https://github.com/frequenz-floss/frequenz-sdk-python/pull/773
* Fix type hint errors in microgrid client by daniel-zullo-frequenz in https://github.com/frequenz-floss/frequenz-sdk-python/pull/778
* Use custom loggers for each module by daniel-zullo-frequenz in https://github.com/frequenz-floss/frequenz-sdk-python/pull/780
* Bump types-protobuf from 4.24.0.3 to 4.24.0.4 by dependabot in https://github.com/frequenz-floss/frequenz-sdk-python/pull/749
* Modularize status tracking for pools of components in the power distributing actor by shsms in https://github.com/frequenz-floss/frequenz-sdk-python/pull/779
* Generalize PowerDistributingActor by shsms in https://github.com/frequenz-floss/frequenz-sdk-python/pull/786
* Move Fuse to timeseries module by daniel-zullo-frequenz in https://github.com/frequenz-floss/frequenz-sdk-python/pull/781
* Move grid power and current metrics to Grid by daniel-zullo-frequenz in https://github.com/frequenz-floss/frequenz-sdk-python/pull/758
* Bump frequenz-channels from 0.16 to 1.0.0b2 by christianparpart in https://github.com/frequenz-floss/frequenz-sdk-python/pull/764
* Rename `ComponentGraph.components()` parameters to be plural by Marenz in https://github.com/frequenz-floss/frequenz-sdk-python/pull/791
* Update some tests to use time machine by matthias-wende-frequenz in https://github.com/frequenz-floss/frequenz-sdk-python/pull/798
* Un-Peekable-ification of the PowerDistributingActor by shsms in https://github.com/frequenz-floss/frequenz-sdk-python/pull/800
* Pass through 0W requests to the microgrid API independent of exclusion bounds by shsms in https://github.com/frequenz-floss/frequenz-sdk-python/pull/801
* Update `frequency()` to no longer have parameters by Marenz in https://github.com/frequenz-floss/frequenz-sdk-python/pull/788
* Fix frequency sending `Quantity` by Marenz in https://github.com/frequenz-floss/frequenz-sdk-python/pull/804
* Fix the resampler handling of output zeros by llucax in https://github.com/frequenz-floss/frequenz-sdk-python/pull/811
* Fetch and stream 3-phase voltage by daniel-zullo-frequenz in https://github.com/frequenz-floss/frequenz-sdk-python/pull/815
* Speedup tests by lowering the actors restart delay by llucax in https://github.com/frequenz-floss/frequenz-sdk-python/pull/828
* Bump actions/setup-python from 4 to 5 by dependabot in https://github.com/frequenz-floss/frequenz-sdk-python/pull/834
* Add missing type hints to instance members by llucax in https://github.com/frequenz-floss/frequenz-sdk-python/pull/809
* Fix bug in `GridFrequency` quantity conversion by llucax in https://github.com/frequenz-floss/frequenz-sdk-python/pull/807
* Improve (and fix some) test finalization by llucax in https://github.com/frequenz-floss/frequenz-sdk-python/pull/838
* Make the registry type-aware by llucax in https://github.com/frequenz-floss/frequenz-sdk-python/pull/830
* Improve BatteryPool's SoC accuracy at the edges by shsms in https://github.com/frequenz-floss/frequenz-sdk-python/pull/843
* Some component status cleanup by shsms in https://github.com/frequenz-floss/frequenz-sdk-python/pull/839
* Drop old propsals from the PowerManager by shsms in https://github.com/frequenz-floss/frequenz-sdk-python/pull/845
* Improvements to EVChargerData coming from the microgrid API by shsms in https://github.com/frequenz-floss/frequenz-sdk-python/pull/848
* Use a sentinel in `LatestValueCache` to denote if the cache is empty by shsms in https://github.com/frequenz-floss/frequenz-sdk-python/pull/846
* Move consumer and producer formulas out from logical meter by daniel-zullo-frequenz in https://github.com/frequenz-floss/frequenz-sdk-python/pull/799
* Parse Quantity Strings by Marenz in https://github.com/frequenz-floss/frequenz-sdk-python/pull/824
* Bump frequenz-api-microgrid to 0.15.3 by llucax in https://github.com/frequenz-floss/frequenz-sdk-python/pull/855
* Bump the optional group with 14 updates by dependabot in https://github.com/frequenz-floss/frequenz-sdk-python/pull/837
* Bump types-protobuf from 4.24.0.4 to 4.24.0.20240129 by dependabot in https://github.com/frequenz-floss/frequenz-sdk-python/pull/867
* Bump flake8 from 6.1.0 to 7.0.0 by dependabot in https://github.com/frequenz-floss/frequenz-sdk-python/pull/860
* Bump setuptools related dependencies by dependabot in https://github.com/frequenz-floss/frequenz-sdk-python/pull/863
* Bump actions/cache from 3 to 4 by dependabot in https://github.com/frequenz-floss/frequenz-sdk-python/pull/858
* Bump pylint from 2.17.5 to 3.0.3 by dependabot in https://github.com/frequenz-floss/frequenz-sdk-python/pull/866
* Bump black from 23.12.1 to 24.1.1 by dependabot in https://github.com/frequenz-floss/frequenz-sdk-python/pull/865
* Remove unused type stubs by llucax in https://github.com/frequenz-floss/frequenz-sdk-python/pull/869
* Add release notes summary for the release by llucax in https://github.com/frequenz-floss/frequenz-sdk-python/pull/870
**Full Changelog**: https://github.com/frequenz-floss/frequenz-sdk-python/compare/v1.0.0-rc3...v1.0.0-rc4