frequenz-api-common 0.6.2__tar.gz → 0.6.3__tar.gz

{frequenz-api-common-0.6.2 → frequenz-api-common-0.6.3}/MANIFEST.in

@@ -6,7 +6,7 @@ exclude CODEOWNERS
 exclude CONTRIBUTING.md
 exclude mkdocs.yml
 exclude noxfile.py
-exclude src/conftest.py
+exclude py/frequenz/api/common/conftest.py
 recursive-exclude .github *
 recursive-exclude benchmarks *
 recursive-exclude docs *

{frequenz-api-common-0.6.2/py/frequenz_api_common.egg-info → frequenz-api-common-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: frequenz-api-common
-Version: 0.6.2
+Version: 0.6.3
 Summary: Frequenz common gRPC API and bindings
 Author-email: Frequenz Energy-as-a-Service GmbH <floss@frequenz.com>
 License: MIT

frequenz-api-common-0.6.3/RELEASE_NOTES.md

@@ -0,0 +1,22 @@
+# Frequenz Common API Release Notes
+
+Update of the `PaginationParams` struct.
+
+## Upgrading
+
+- `PaginationParams` has been changed so that the `page_size` and `page_token`
+  fields are now mutually exclusive.
+
+- A new component category `COMPONENT_CATEGORY_HVAC` has been added to the API
+  to represent HVAC (Heating, Ventilation, and Air Conditioning) systems.
+
+- Additional information for energy metric
+
+- Generalize Energy message documentation for broader market use
+
+- Add Power message to represent Power in MW
+
+## Bug Fixes
+
+- Fix a dependency issue by pinning the `grpcio` version and related libraries.
+- Fixed a wrong documentation comment for `COMPONENT_CATEGORY_UNSPECIFIED`.

{frequenz-api-common-0.6.2 → frequenz-api-common-0.6.3}/proto/frequenz/api/common/v1/market/energy.proto

@@ -1,4 +1,4 @@
-// Frequenz definitions of energy for electricity trading.
+// Frequenz definitions of energy.
 //
 // Copyright 2023 Frequenz Energy-as-a-Service GmbH
 //
@@ -14,11 +14,11 @@ import "frequenz/api/common/v1/types/decimal.proto";
 // Represents a single unit of electricity.
 //
 // !!! note
-//     In these trading orders, the unit of energy is denominated in MWh
-//     (Megawatt-hours) as opposed to MW (Megawatts).  MWh is a unit of energy
-//     representing total output over a period, while MW is a unit of power that
-//     represents the rate of energy production or consumption.
+//     The unit of energy is denominated in MWh, which is a unit of energy
+//     representing total output over a period.(Megawatt-hours). This differs
+//     from MW (Megawatts), a unit of power representing the rate of energy
+//     production or consumption.
 message Energy {
-  // Represents energy unit in Megawatthours (MWh).
+  // Energy unit in Megawatthours (MWh).
   frequenz.api.common.v1.types.Decimal mwh = 1;
 }

frequenz-api-common-0.6.3/proto/frequenz/api/common/v1/market/power.proto

@@ -0,0 +1,30 @@
+// Frequenz definitions of power.
+//
+// Copyright 2024 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.v1.market;
+
+import "frequenz/api/common/v1/types/decimal.proto";
+
+// Represents a single unit of power.
+//
+// !!! note
+//     The power unit is denominated in MW (Megawatts), which is a unit of
+//     power representing the rate of energy production or consumption at any
+//     given moment. This differs from MWh (Megawatt-hours), which measures
+//     the total amount of energy delivered or consumed over a period.
+//
+// Example:
+//     A power plant running at 10 MW for 1 hour generates 10 MWh of energy.
+//
+// This message standardizes the representation of power in MW across all
+// market applications.
+message Power {
+  // Power amount in Megawatts (MW).
+  frequenz.api.common.v1.types.Decimal mw = 1;
+}

{frequenz-api-common-0.6.2 → frequenz-api-common-0.6.3}/proto/frequenz/api/common/v1/metrics/metric_sample.proto

@@ -63,6 +63,20 @@ message MetricValueVariant {
 }
 
 // List of supported metrics.
+//
+// !!! note
+// AC energy metrics information:
+//
+// * This energy metric is reported directly from the component, and not a
+//  result of aggregations in our systems. If a component does not have this
+//  metric, this field cannot be populated.
+//
+//  * Components that provide energy metrics reset this metric from time to
+//  time. This behaviour is specific to each component model. E.g., some
+//  components reset it on UTC 00:00:00.
+//
+//  * This energy metric does not specify the timestamp since when the energy
+//  was being accumulated, and therefore can be inconsistent.
 enum Metric {
   // Default value.
   METRIC_UNSPECIFIED = 0;

{frequenz-api-common-0.6.2 → frequenz-api-common-0.6.3}/proto/frequenz/api/common/v1/microgrid/components/components.proto

@@ -24,8 +24,7 @@ import "google/protobuf/timestamp.proto";
 
 // Enumrated component categories.
 enum ComponentCategory {
-  // An unknown component categories, useful for error handling, and marking
-  // unknown components in a list of components with otherwise known categories.
+  // The component category is unspecified. This should not be used.
   COMPONENT_CATEGORY_UNSPECIFIED = 0;
 
   // The point where the local microgrid is connected to the grid.

frequenz-api-common-0.6.3/proto/frequenz/api/common/v1/microgrid/lifetime.proto

@@ -0,0 +1,41 @@
+// Frequenz definition of entity lifetimes, based upon start and end timestamps.
+//
+// Copyright 2023 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.v1.microgrid;
+
+import "google/protobuf/timestamp.proto";
+
+// Lifetime captures the timestamps indicating the active operational period of
+// a microgrid asset, such as a component, connection, sensor, or any other
+// entity with a limited operational lifetime.
+//
+// It is normally used to track the historical evolution of assets, and it
+// determines the validity period for the asset's data.
+//
+// If the `start_timestamp` is not set, the asset is considered to be in
+// operation since the beginning of the system's operational history.
+//
+// If the `end_timestamp` is not set, the asset is considered to be in
+// operation indefinitely into the future.
+//
+// If the Lifetime message is completely missing, it means both timestamps are
+// not set, which means the asset is considered to be in operation since the
+// beginning of the system's operational history and indefinitely into the
+// future.
+message Lifetime {
+  // The timestamp when the asset became operationally active.
+  // If not set, the asset is considered to be in operation since the beginning
+  // of the system's operational history.
+  google.protobuf.Timestamp start_timestamp = 1;
+
+  // Optional timestamp when the asset's operational activity ceased.
+  // If not set, the asset is considered to be in operation indefinitely into
+  // the future.
+  google.protobuf.Timestamp end_timestamp = 2;
+}

{frequenz-api-common-0.6.2 → frequenz-api-common-0.6.3}/proto/frequenz/api/common/v1/microgrid/microgrid.proto

@@ -51,9 +51,15 @@ message Microgrid {
 
   // The delivery area where the microgrid is located, as identified by a
   // specific code.
+  //
+  // If a microgrid is not connected to the grid (it is an island) it does not
+  // belong to any delivery area and this field will be missing, but it could
+  // be missing for other reasons as well.
   frequenz.api.common.v1.grid.DeliveryArea delivery_area = 4;
 
   // Physical location of the microgrid, in geographical co-ordinates.
+  //
+  // If the location is not known, this field will be missing.
   frequenz.api.common.v1.Location location = 5;
 
   // The current status of the microgrid.

frequenz-api-common-0.6.3/proto/frequenz/api/common/v1/pagination/pagination_params.proto

@@ -0,0 +1,31 @@
+// Parameters for pagination.
+//
+// Copyright 2023 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.v1.pagination;
+
+// A message defining parameters for paginating list requests.
+// It can be appended to a request message to specify the desired page of
+// results and the maximum number of results per page.
+message PaginationParams {
+  oneof params {
+    // The maximum number of results to return in a single page. The service may
+    // return fewer results than requested. If unspecified, the service may
+    // choose a reasonable default.
+    // May only be specified in the first request.
+    uint32 page_size = 1;
+
+    // A token identifying a page of results to return. This should be the value
+    // of the `next_page_token` field in the previous response's PaginationInfo.
+    // For the first request, this field should be omitted.
+    //
+    // To avoid keeping remembering the page_size across requests, service
+    // implementations may choose to encode the page_size in the page_token.
+    string page_token = 2;
+  }
+}

{frequenz-api-common-0.6.2 → frequenz-api-common-0.6.3/py/frequenz_api_common.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: frequenz-api-common
-Version: 0.6.2
+Version: 0.6.3
 Summary: Frequenz common gRPC API and bindings
 Author-email: Frequenz Energy-as-a-Service GmbH <floss@frequenz.com>
 License: MIT

{frequenz-api-common-0.6.2 → frequenz-api-common-0.6.3}/py/frequenz_api_common.egg-info/SOURCES.txt

@@ -11,6 +11,7 @@ proto/frequenz/api/common/v1/location.proto
 proto/frequenz/api/common/v1/grid/delivery_area.proto
 proto/frequenz/api/common/v1/grid/delivery_duration.proto
 proto/frequenz/api/common/v1/market/energy.proto
+proto/frequenz/api/common/v1/market/power.proto
 proto/frequenz/api/common/v1/market/price.proto
 proto/frequenz/api/common/v1/metrics/bounds.proto
 proto/frequenz/api/common/v1/metrics/metric_sample.proto
@@ -27,7 +28,6 @@ proto/frequenz/api/common/v1/microgrid/sensors/sensors.proto
 proto/frequenz/api/common/v1/pagination/pagination_info.proto
 proto/frequenz/api/common/v1/pagination/pagination_params.proto
 proto/frequenz/api/common/v1/types/decimal.proto
-py/conftest.py
 py/frequenz/api/common/__init__.py
 py/frequenz/api/common/py.typed
 py/frequenz/api/common/metrics/__init__.py

{frequenz-api-common-0.6.2 → frequenz-api-common-0.6.3}/py/frequenz_api_common.egg-info/requires.txt

@@ -1,41 +1,41 @@
-protobuf<6,>=4.25.3
-grpcio<2,>=1.51.1
+protobuf<7,>=5.28.0
+grpcio<2,>=1.66.1
 
 [dev]
 frequenz-api-common[dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]
 
 [dev-flake8]
-flake8==7.0.0
+flake8==7.1.1
 flake8-docstrings==1.7.0
 flake8-pyproject==1.2.3
-pydoclint==0.4.1
+pydoclint==0.5.9
 pydocstyle==6.3.0
 
 [dev-formatting]
-black==24.4.2
+black==24.8.0
 isort==5.13.2
 
 [dev-mkdocs]
 mike==1.1.2
 mkdocs-gen-files==0.5.0
 mkdocs-literate-nav==0.6.1
-mkdocs-material==9.5.21
-mkdocstrings[python]==0.25.1
-frequenz-repo-config[api]==0.9.2
+mkdocs-material==9.5.39
+mkdocstrings[python]==0.26.1
+frequenz-repo-config[api]==0.10.0
 
 [dev-mypy]
-mypy==1.10.0
+mypy==1.11.2
 grpc-stubs==1.53.0.5
 frequenz-api-common[dev-mkdocs,dev-noxfile,dev-pytest]
 
 [dev-noxfile]
 nox==2024.4.15
-frequenz-repo-config[api]==0.9.2
+frequenz-repo-config[api]==0.10.0
 
 [dev-pylint]
-pylint==3.1.0
+pylint==3.3.1
 frequenz-api-common[dev-mkdocs,dev-noxfile,dev-pytest]
 
 [dev-pytest]
-pytest==8.2.0
-frequenz-repo-config[extra-lint-examples]==0.9.2
+pytest==8.3.3
+frequenz-repo-config[extra-lint-examples]==0.10.0

{frequenz-api-common-0.6.2 → frequenz-api-common-0.6.3}/py/frequenz_api_common.egg-info/top_level.txt

@@ -1,2 +1 @@
-conftest
 frequenz

{frequenz-api-common-0.6.2 → frequenz-api-common-0.6.3}/pyproject.toml

@@ -5,14 +5,14 @@
 requires = [
   "setuptools == 68.1.0",
   "setuptools_scm[toml] == 7.1.0",
-  "frequenz-repo-config[api] == 0.9.2",
+  "frequenz-repo-config[api] == 0.10.0",
   # We need to pin the protobuf, grpcio and  grpcio-tools dependencies to make
   # sure the code is generated using the minimum supported versions, as older
   # versions can't work with code that was generated with newer versions.
   # https://protobuf.dev/support/cross-version-runtime-guarantee/#backwards
-  "protobuf == 4.25.3",
-  "grpcio-tools == 1.51.1",
-  "grpcio == 1.51.1",
+  "protobuf == 5.28.0",
+  "grpcio-tools == 1.66.1",
+  "grpcio == 1.66.1",
 ]
 build-backend = "setuptools.build_meta"
 
@@ -33,13 +33,14 @@ classifiers = [
 ]
 requires-python = ">= 3.11, < 4"
 dependencies = [
-  # We can't widen beyond 6 because of protobuf cross-version runtime guarantees
+  # We can't widen beyond the current value unless we bump the minimum
+  # requirements too because of protobuf cross-version runtime guarantees:
   # https://protobuf.dev/support/cross-version-runtime-guarantee/#major
-  "protobuf >= 4.25.3, < 6", # Do not widen beyond 6!
+  "protobuf >= 5.28.0, < 7", # Do not widen beyond 7!
   # We couldn't find any document with a spec about the cross-version runtime
   # guarantee for grpcio, so unless we find one in the future, we'll assume
   # major version jumps are not compatible
-  "grpcio >= 1.51.1, < 2", # Do not widen beyond 2!
+  "grpcio >= 1.66.1, < 2", # Do not widen beyond 2!
 ]
 dynamic = ["version"]
 
@@ -49,36 +50,36 @@ email = "floss@frequenz.com"
 
 [project.optional-dependencies]
 dev-flake8 = [
-  "flake8 == 7.0.0",
+  "flake8 == 7.1.1",
   "flake8-docstrings == 1.7.0",
   "flake8-pyproject == 1.2.3",  # For reading the flake8 config from pyproject.toml
-  "pydoclint == 0.4.1",
+  "pydoclint == 0.5.9",
   "pydocstyle == 6.3.0",
 ]
-dev-formatting = ["black == 24.4.2", "isort == 5.13.2"]
+dev-formatting = ["black == 24.8.0", "isort == 5.13.2"]
 dev-mkdocs = [
   "mike == 1.1.2",
   "mkdocs-gen-files == 0.5.0",
   "mkdocs-literate-nav == 0.6.1",
-  "mkdocs-material == 9.5.21",
-  "mkdocstrings[python] == 0.25.1",
-  "frequenz-repo-config[api] == 0.9.2",
+  "mkdocs-material == 9.5.39",
+  "mkdocstrings[python] == 0.26.1",
+  "frequenz-repo-config[api] == 0.10.0",
 ]
 dev-mypy = [
-  "mypy == 1.10.0",
+  "mypy == 1.11.2",
   "grpc-stubs == 1.53.0.5",
   # For checking the noxfile, docs/ script, and tests
   "frequenz-api-common[dev-mkdocs,dev-noxfile,dev-pytest]",
 ]
-dev-noxfile = ["nox == 2024.4.15", "frequenz-repo-config[api] == 0.9.2"]
+dev-noxfile = ["nox == 2024.4.15", "frequenz-repo-config[api] == 0.10.0"]
 dev-pylint = [
-  "pylint == 3.1.0",
+  "pylint == 3.3.1",
   # For checking the noxfile, docs/ script, and tests
   "frequenz-api-common[dev-mkdocs,dev-noxfile,dev-pytest]",
 ]
 dev-pytest = [
-  "pytest == 8.2.0",
-  "frequenz-repo-config[extra-lint-examples] == 0.9.2",
+  "pytest == 8.3.3",
+  "frequenz-repo-config[extra-lint-examples] == 0.10.0",
 ]
 dev = [
   "frequenz-api-common[dev-mkdocs,dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]",

frequenz-api-common-0.6.2/RELEASE_NOTES.md

@@ -1,5 +0,0 @@
-# Frequenz Common API Release Notes
-
-## Bug Fixes
-
-- Fix a dependency issue by pinning the `grpcio` version and related libraries.

frequenz-api-common-0.6.2/proto/frequenz/api/common/v1/microgrid/lifetime.proto

@@ -1,28 +0,0 @@
-// Frequenz definition of entity lifetimes, based upon start and end timestamps.
-//
-// Copyright 2023 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.v1.microgrid;
-
-import "google/protobuf/timestamp.proto";
-
-// Lifetime captures the timestamps indicating the active operational period of
-// a microgrid asset, such as a component, connection, sensor, or any other
-// entity with a limited operational lifetime.
-//
-// !!! warning "Permanent Deletion"
-//     The `end_timestamp` indicates that the asset has been permanently removed
-//     from the system.
-//
-message Lifetime {
-  // The timestamp when the asset became operationally active.
-  google.protobuf.Timestamp start_timestamp = 1;
-
-  // Optional timestamp when the asset's operational activity ceased.
-  google.protobuf.Timestamp end_timestamp = 2;
-}

frequenz-api-common-0.6.2/proto/frequenz/api/common/v1/pagination/pagination_params.proto

@@ -1,26 +0,0 @@
-// Parameters for pagination.
-//
-// Copyright 2023 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.v1.pagination;
-
-// A message defining parameters for paginating list requests.
-// It can be appended to a request message to specify the desired page of
-// results and the maximum number of results per page. For initial requests
-// (requesting the first page), the page_token should not be provided. For
-// subsequent requests (requesting any page after the first), the
-// next_page_token from the previous responses PaginationInfo must be supplied.
-// The page_size should only be specified in the initial request and will be
-// disregarded in subsequent requests.
-message PaginationParams {
-  // The maximum number of results to be returned per request.
-  optional uint32 page_size = 1;
-
-  // The token identifying a specific page of the list results.
-  optional string page_token = 2;
-}

frequenz-api-common-0.6.2/py/conftest.py

@@ -1,13 +0,0 @@
-# License: MIT
-# Copyright © 2023 Frequenz Energy-as-a-Service GmbH
-
-"""Validate docstring code examples.
-
-Code examples are often wrapped in triple backticks (```) within docstrings.
-This plugin extracts these code examples and validates them using pylint.
-"""
-
-from frequenz.repo.config.pytest import examples
-from sybil import Sybil
-
-pytest_collect_file = Sybil(**examples.get_sybil_arguments()).pytest()