v1.0.0-rc2001

Frequenz Python SDK Release Notes

Bug Fixes

• Fix TypeError raised by BatteryManager when distributing power

What's Changed

• Reset release notes by @ela-kotulska-frequenz in #1225
• Bump types-protobuf from 5.29.1.20250403 to 6.30.2.20250516 by @dependabot in #1229
• Bump the patch group with 6 updates by @dependabot in #1226
• Bug fix: Print Power as str instead of decimal by @ela-kotulska-frequenz in #1232

Full Changelog: v1.0.0-rc2000...v1.0.0-rc2001

v1.0.0-rc2000

Frequenz Python SDK Release Notes

New Features

• The SDK now officially support Python 3.13.

Bug Fixes

• Fixed issue where actors would restart instead of stopping when exceptions occurred during cancellation. Actors now properly stop and surface the unhandled exception.

What's Changed

• Clear release notes by @shsms in #1220
• Update tests to support latest time-machine by @shsms in #1221
• Add missing PV and EV components to datapipeline's stop method by @shsms in #1222
• Add support for Python 3.13 by @llucax in #1219
• Fix issue with actor restarting instead of stopping by @ela-kotulska-frequenz in #1223
• Update release notes by @ela-kotulska-frequenz in #1224

Full Changelog: v1.0.0-rc1900...v1.0.0-rc2000

v1.0.0-rc1900

Frequenz Python SDK Release Notes

Summary

This release introduces a number of breaking changes in the config manager, the new ComponentId/MicrogridId types and the numpy version update. It also includes bug-fixes to the component graph and power management.

Upgrading

• Includes a major update of the numpy dependency to v2.x.

• The logging configuration was changed, and now the logger name needs to be specified explicitly (the configuration key was used as the name before). This is to be compatible with configuration generated by the UI, which doesn't quote sub-key properly.

  • Before:

    [logging.loggers."frequenz.sdk.config"]
    level = "DEBUG"

  • Now:

    [logging.loggers.frequenz_config]
    name = "frequenz.sdk.config"
    level = "DEBUG"

• The logging configuration now uses a separate class for the root logger configuration: RootLoggerConfig.

  • Before:

    LoggingConfig(root_logger=LoggerConfig(level="ERROR"))

  • Now:

    LoggingConfig(root_logger=RootLoggerConfig(level="ERROR"))

• The SDK now depends on the frequenz-client-microgrid v0.7.x series. The main change is now all component and microgrid IDs need to be passed using the wrapper classes ComponentId/MicrogridId instead of int.

Bug Fixes

• The power manager used to just forgot components when all proposals to them are withdrawn, leaving them at their last set power values. This has been fixed by getting the power manager to set the components to their default powers, based on the component category (according to the table below), as the last step.

  component category	default power
  Battery	0.0
  PV	Minimum power (aka max production power)
  EV Chargers	Maximum power (aka max consumption power)

• PV Pool instances can now be created in sites without any PV. This allows for writing generic code that works for all locations, that depends on the PV power formula, for example.

• Success/PartialFailure results from PVPool.power_distribution_results now report correct succeeded_power values.

• The find_first_descendant_component method in the component graph was allowing non-root components to be used as the root component during traversal. This was leading to confusing behaviour when the root component couldn't be identified deterministically. For example, if the root category was specified as a meter, it could start traversing from a different meter each time. It is no-longer possible to specify a root category anymore and it always traverses from the GRID component.

What's Changed

• Clear release notes by @shsms in #1203
• Bump setuptools from 78.1.0 to 80.1.0 by @dependabot in #1209
• Update marshmallow requirement from <4,>=3.19.0 to >=3.19.0,<5 by @dependabot in #1210
• Bump types-setuptools from 78.1.0.20250329 to 80.0.0.20250429 by @dependabot in #1211
• Bump the patch group with 3 updates by @dependabot in #1206
• Bump pydoclint from 0.6.5 to 0.6.6 by @dependabot in #1208
• Reset components to default power when all proposals are withdrawn by @shsms in #1212
• Bump the minor group across 1 directory with 7 updates by @dependabot in #1213
• Update numpy dependency to v2 by @cwasicki in #1160
• Update the logging config actor configuration format by @llucax in #1204
• Allow create PVPool instances in locations without PV by @shsms in #1215
• Use Power instead of float in PowerDistributor's battery manager by @shsms in #1214
• Ensure root component is as close as possible to the grid component by @shsms in #1216
• Upgrade to microgrid client v0.7 by @llucax in #1182
• Fix succeeded_power calculation in PV power distribution by @shsms in #1217
• Prepare for v1.0.0-rc1900 by @shsms in #1218

Full Changelog: v1.0.0-rc1802...v1.0.0-rc1900

v1.0.0-rc1802

Frequenz Python SDK Release Notes

Bug Fixes

• The additive ShiftingMatryoshka algorithm was made for batteries, but got set as the default algorithm for PV and EV chargers. This is now reversed and PV and EV chargers are back to using the original Matryoshka algorithm.

What's Changed

• Clear release notes by @shsms in #1201
• Use the additive ShiftingMatryoshka algorithm only for batteries by @shsms in #1202

Full Changelog: v1.0.0-rc1801...v1.0.0-rc1802

v1.0.0-rc1801

Frequenz Python SDK Release Notes

Bug Fixes

• Fixes a bug where battery pool metrics would stop for one actor when another actor managing the same components stops its pool.

What's Changed

• Clear release notes by @shsms in #1198
• Don't stop pools by @shsms in #1199
• Prepare for release v1.0.0-rc1801 by @shsms in #1200

Full Changelog: v1.0.0-rc1800...v1.0.0-rc1801

v1.0.0-rc1800

Frequenz Python SDK Release Notes

Upgrading

• The microgrid.new_*_pool methods no longer accept a set_operating_point parameter.
• The power manager now uses a new algorithm described here.

Bug Fixes

• Fix MetricFetcher leaks when a requested metric fetcher already existed.

What's Changed

• Bump nox from 2024.10.9 to 2025.2.9 by @dependabot in #1173
• Bump types-protobuf from 5.29.1.20241207 to 5.29.1.20250208 by @dependabot in #1174
• Update build status badge by @llucax in #1171
• Avoid creating dangling MetricFetchers by @llucax in #1179
• Fix ordering issues with sets of ints by @llucax in #1177
• Improve docs and tests and fix minor issues by @llucax in #1178
• Clear release notes by @shsms in #1181
• Implement the ShiftingMatryoshka algorithm for the PowerManager by @shsms in #1146
• Update to repo-config v0.13 by @llucax in #1186
• Bump the patch group with 5 updates by @dependabot in #1187
• Bump the minor group with 4 updates by @dependabot in #1188
• Bump pydoclint from 0.6.0 to 0.6.5 by @dependabot in #1189
• Bump types-setuptools from 75.8.0.20250110 to 78.1.0.20250329 by @dependabot in #1191
• Bump pytest-asyncio from 0.25.3 to 0.26.0 by @dependabot in #1192
• Bump types-markdown from 3.7.0.20241204 to 3.7.0.20250322 by @dependabot in #1190
• Bump setuptools from 75.8.0 to 78.1.0 by @dependabot in #1193
• Bump types-protobuf from 5.29.1.20250208 to 5.29.1.20250403 by @dependabot in #1194
• Log power allocations per actor in the PowerManager by @shsms in #1196
• Prepare for release v1.0.0-rc1800 by @shsms in #1197

Full Changelog: v1.0.0-rc1700...v1.0.0-rc1800

v1.0.0-rc1700

Frequenz Python SDK Release Notes

Summary

New Features

• Add a stop() method to the FormulaEngine. Now it is possible to stop custom formulas.

• Stop fallback formulas when primary formula starts working again.

Bug Fixes

• Fixed a bug with formulas raising exception when stopped.

• Fixed a bug that raised CancelledError when actor was started with frequenz.sdk.actor.run and stopped.

• Stop catching BaseException in frequenz.sdk.actor.run. Only CancelledError and Exception are caught now.

What's Changed

• Stop formula engine by @ela-kotulska-frequenz in #1165
• Clear release notes by @shsms in #1167
• Stop raising CancelledError when actor is cancelled by @ela-kotulska-frequenz in #1166
• mypy: Check all files by default by @llucax in #1164
• Prepare release notes for rc1700 by @llucax in #1170

Full Changelog: v1.0.0-rc1600...v1.0.0-rc1700

v1.0.0-rc1600

Frequenz Python SDK Release Notes

New Features

• The MovingWindow now has an async wait_for_samples method that waits for a given number of samples to become available in the moving window and then returns.

Bug Fixes

• Fixed a bug that was preventing power proposals to go through if there once existed some proposals with overlapping component IDs, even if the old proposals have expired.

• Fixed a bug that was causing formulas to fallback to CHPs, when the CHP meters didn't have data. CHPs are not supported in the data sourcing actor and in the client, so we can't fallback to CHPs.

What's Changed

• Clear release notes by @llucax in #1154
• Drop empty Matryoshka buckets by @shsms in #1155
• Rewrite CI: use reusable actions, native arm and faster PR testing by @llucax in #1153
• Bump black from 24.10.0 to 25.1.0 by @dependabot in #1158
• Bump the required group with 7 updates by @dependabot in #1156
• Bump isort from 5.13.2 to 6.0.0 by @dependabot in #1157
• Add a wait_for_samples method to the MovingWindow by @shsms in #1159
• Don't fallback to CHPs by @shsms in #1161
• Prepare release notes for rc1600 by @llucax in #1163

Full Changelog: v1.0.0-rc1500...v1.0.0-rc1600

v1.0.0-rc1500

Frequenz Python SDK Release Notes

Summary

This release includes a new ConfigManager class to simplify managing the configuration, and ships other improvements and fixes to the config system in general.

Upgrading

• frequenz.sdk.config

  • LoggingConfigUpdater

    • Renamed to LoggingConfigUpdatingActor to follow the actor naming convention.
    • The actor must now be constructed using a ConfigManager instead of a receiver.
    • Make all arguments to the constructor keyword-only, except for the config_manager argument.
    • If the configuration is removed, the actor will now load back the default configuration.

  • LoggingConfig

    • The load() method was removed. Please use frequenz.sdk.config.load_config() instead.
    • The class is now a standard dataclass instead of a marshmallow_dataclass.
    • The class is now immutable.
    • The constructor now accepts only keyword arguments.

  • LoggerConfig

    • The class is now a standard dataclass instead of a marshmallow_dataclass.
    • The class is now immutable.
    • The constructor now accepts only keyword arguments.

  • load_config():

    • The base_schema argument is now keyword-only and defaults to BaseConfigSchema (and because of this, it uses unknown=EXCLUDE by default).
    • The arguments forwarded to marshmallow.Schema.load() now must be passed explicitly via the marshmallow_load_kwargs argument, as a dict, to improve the type-checking.
    • Will now raise a ValueError if unknown is set to INCLUDE in marshmallow_load_kwargs.

  • ConfigManagingActor: Raise a ValueError if the config_files argument an empty sequence.

New Features

• frequenz.sdk.config

  • Logging was improved in general.

  • Added documentation and user guide.

  • LoggingConfigUpdatingActor

    • Added a new name argument to the constructor to be able to override the actor's name.

  • ConfigManager: Added a class to simplify managing the configuration. It takes care of instantiating the config actors and provides a convenient method for creating receivers with a lot of common functionality.

  • BaseConfigSchema: Added a marshmallow base Schema that includes custom fields for frequenz-quantities. In the futute more commonly used fields might be added.

  • wait_for_first(): Added a function to make it easy to wait for the first configuration to be received with a timeout.

  • ConfigManagingActor: Allow passing a single configuration file.

Bug Fixes

• Fix a bug in BackgroundService where it won't try to self.cancel() and await self.wait() if there are no internal tasks. This prevented to properly implement custom stop logic without having to redefine the stop() method too.

• Fix a bug where if a string was passed to the ConfigManagingActor it would be interpreted as a sequence of 1 character strings.

• Remove a confusing log message in the power distributing actor.

• Close all receivers owned by a *pool when stopping the pool.

What's Changed

• Bump the required group with 4 updates by @dependabot in #1123
• Clear release notes by @llucax in #1122
• Reorganize the config module by @llucax in #1126
• Improve the logging config actor by @llucax in #1127
• Make LoggerConfig and LoggingConfig frozen and keyword-only by @llucax in #1128
• Add load_shedding example by @Marenz in #1131
• Improve logging and API of the config module by @llucax in #1133
• Fix cross-arch CI tests by @llucax in #1141
• Bump types-markdown from 3.7.0.20240822 to 3.7.0.20241204 by @dependabot in #1138
• Bump types-setuptools from 75.6.0.20241126 to 75.6.0.20241223 by @dependabot in #1139
• Don't allow checking if None is within the bounds by @llucax in #1140
• Revamp config management by @llucax in #1134
• Bump the required group across 1 directory with 8 updates by @dependabot in #1143
• Move default unknown=EXCLUDE to BaseConfigSchema by @llucax in #1149
• Remove "Checking battery" log message by @shsms in #1151
• Disable warn on overflow in config channel receivers by @llucax in #1152
• Close all *pool's receivers when stopping the pool by @shsms in #1150

Full Changelog: v1.0.0-rc1400...v1.0.0-rc1500

v1.0.0-rc1400

Frequenz Python SDK Release Notes

Summary

This is a minor release with just a few bug fixes but also one breaking change in the ConfigManagingActor.

Upgrading

• The ConfigManagingActor now only reacts to CREATE and MODIFY events. DELETE is not supported anymore and are ignored.
• Remove the event_types argument from the ConfigManagingActor constructor.

Bug Fixes

• Fix bugs with ConfigManagingActor:
  • Raising unhandled exceptions when any file in config directory was deleted.
  • Raising unhandled exception if not all config files exist.
  • Eliminate recursive actor crashes when all config files were missing.

What's Changed

• Fix ConfigManagingActor raising unhandled exceptions when file doesn't exist by @ela-kotulska-frequenz in #1116
• Prepare release notes for v1.0.0-rc1400 by @llucax in #1121

Full Changelog: v1.0.0-rc1302...v1.0.0-rc1400