From 07c70e4589507d40ceda88bc459e725439bc65ee Mon Sep 17 00:00:00 2001 From: Richard Sandoval Date: Fri, 17 Oct 2025 13:56:24 +0200 Subject: [PATCH 1/2] feat(gridpool): add gridpool definition to v1alpha8 Introduce Gridpool message with id and name fields. A gridpool represents an assigned group of microgrids for the purpose of energy trading. Signed-off-by: Richard Sandoval --- RELEASE_NOTES.md | 32 ++----------------- .../common/v1alpha8/gridpool/gridpool.proto | 22 +++++++++++++ py/frequenz/api/common/v1alpha8/__init__.py | 2 +- .../api/common/v1alpha8/gridpool/__init__.py | 4 +++ 4 files changed, 29 insertions(+), 31 deletions(-) create mode 100644 proto/frequenz/api/common/v1alpha8/gridpool/gridpool.proto create mode 100644 py/frequenz/api/common/v1alpha8/gridpool/__init__.py diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 46415071..ac435234 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -2,34 +2,6 @@ ## Summary -This release introduces the new `v1alpha8` version of the API, which includes several breaking changes compared to `v1alpha7`. The changes focus on improving consistency and clarity by renaming several symbols and removing unused components. +## Features -## Upgrading - -- A new package `frequenz.api.common.v1alpha8` has been introduced, containing the following breaking changes from `v1alpha7`. - -- Removed: - - + `electrical_components.Fuse` - + `InverterType.INVERTER_TYPE_WIND_TURBINE` - -- Renamed several symbols to increase consistency and clarity: - - + `microgrid`: - - * `MicrogridComponentIds` to `MicrogridElectricalComponentIds` - * `MicrogridComponentIDs.component_ids` to `MicrogridElectricalComponentIds.electrical_component_ids` - - + `electrical_components`: - - * `ElectricalComponentConnections.source_component_id` to `ElectricalComponentConnections.source_electrical_component_id` - * `ElectricalComponentConnections.destination_component_id` to `ElectricalComponentConnections.destination_electrical_component_id` - * `ElectricalComponentStateSnapshot.component_id` to `ElectricalComponentStateSnapshot.electrical_component_id` - * Transformer-related terms are renamed to align them with power transformers, which are more commonly used in electrical engineering: - * `electrical_components.VoltageTransformer` to `electrical_components.PowerTransformer` - * `ElectricalComponentCategorySpecificInfo.kind.voltage_transformer` to `ElectricalComponentCategorySpecificInfo.kind.power_transformer` - * `ElectricalComponentCategory.ELECTRICAL_COMPONENT_CATEGORY_VOLTAGE_TRANSFORMER` to `ElectricalComponentCategory.ELECTRICAL_COMPONENT_CATEGORY_POWER_TRANSFORMER` - - + `types`: - - * The whole package has been renamed to `types` to avoid using reserved keywords in programming languages. +- Add `gridpool.Gridpool` message type to `v1alpha8`, defining a gridpool as an assigned group of microgrids for the purpose of energy trading. diff --git a/proto/frequenz/api/common/v1alpha8/gridpool/gridpool.proto b/proto/frequenz/api/common/v1alpha8/gridpool/gridpool.proto new file mode 100644 index 00000000..32cb00bb --- /dev/null +++ b/proto/frequenz/api/common/v1alpha8/gridpool/gridpool.proto @@ -0,0 +1,22 @@ +// protolint:disable MAX_LINE_LENGTH +// Frequenz gridpool definition. +// +// Copyright 2025 Frequenz Energy-as-a-Service GmbH +// +// Licensed under the MIT License (the "License"); +// you may not use this file except in compliance with the License. + +syntax = "proto3"; + +package frequenz.api.common.v1alpha8.gridpool; + + +// Gridpool contains details of a specific gridpool. +// A gridpool is an assigned group of microgrids for the purpose of energy trading. +message Gridpool { + // A unique identifier for the gridpool. + uint64 id = 1; + + // The name of the gridpool. + string name = 2; +} diff --git a/py/frequenz/api/common/v1alpha8/__init__.py b/py/frequenz/api/common/v1alpha8/__init__.py index 79fee0df..1c10ab0c 100644 --- a/py/frequenz/api/common/v1alpha8/__init__.py +++ b/py/frequenz/api/common/v1alpha8/__init__.py @@ -1,4 +1,4 @@ # License: MIT # Copyright © 2025 Frequenz Energy-as-a-Service GmbH -"""Frequenz common gRPC API and bindings for v1alpha7.""" +"""Frequenz common gRPC API and bindings for v1alpha8.""" diff --git a/py/frequenz/api/common/v1alpha8/gridpool/__init__.py b/py/frequenz/api/common/v1alpha8/gridpool/__init__.py new file mode 100644 index 00000000..9e84cb8c --- /dev/null +++ b/py/frequenz/api/common/v1alpha8/gridpool/__init__.py @@ -0,0 +1,4 @@ +# License: MIT +# Copyright © 2025 Frequenz Energy-as-a-Service GmbH + +"""Gridpool bindings for Frequenz common gRPC API.""" From 3f65150b4c5398cf529f0e0d9b3efd89045cf520 Mon Sep 17 00:00:00 2001 From: Richard Sandoval Date: Fri, 17 Oct 2025 14:37:15 +0200 Subject: [PATCH 2/2] chore: Enhance CONTRIBUTING.md with guidelines for adding new proto files Added a section detailing the requirement to create corresponding `__init__.py` files in the `/py/*` directory when new proto files are added to the `/proto/*` directory. This ensures proper package recognition in Python and includes examples and rationale for the requirement. Signed-off-by: Richard Sandoval --- CONTRIBUTING.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fd7060fa..7a1444cb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -45,6 +45,42 @@ etc.) in one go too: python -m pip install -e .[dev] ``` +### Adding new proto files + +When you create a new directory or add proto files in the `/proto/*` directory +structure, you **must** create a corresponding `__init__.py` file in the +matching `/py/*` directory path. + +For example, if you add a new proto file at: +``` +proto/frequenz/api/common/v1/new_module/example.proto +``` + +You need to create: +``` +py/frequenz/api/common/v1/new_module/__init__.py +``` + +**Why is this required?** + +Python requires `__init__.py` files to treat directories as packages. Without +these files: +- The generated Python code from your proto files won't be importable +- The package hierarchy won't be recognized by Python +- Import statements will fail when trying to use the generated protobuf bindings + +The `__init__.py` file should include: +- A license header (see existing files for the template) +- A docstring describing the module's purpose + +**Example `__init__.py` content:** +```python +# License: MIT +# Copyright © 2025 Frequenz Energy-as-a-Service GmbH + +"""Description of what this module provides.""" +``` + If you don't want to install all the dependencies, you can also use `nox` to run the tests and other checks creating its own virtual environments: