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

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: frequenz-api-common
-Version: 0.6.3
+Version: 0.6.4
 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.4/RELEASE_NOTES.md

@@ -0,0 +1,9 @@
+# Frequenz Common API Release Notes
+
+## New Features
+
+- Added message linking microgrid and sensor IDs.
+
+## Bug Fixes
+
+- Fix a dependency issue by pinning the `grpcio` version and related libraries.

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

@@ -1,4 +1,4 @@
-// Frequenz definitions of energy.
+// Frequenz definitions of energy for electricity trading.
 //
 // 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
-//     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.
+//     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.
 message Energy {
-  // Energy unit in Megawatthours (MWh).
+  // Represents energy unit in Megawatthours (MWh).
   frequenz.api.common.v1.types.Decimal mwh = 1;
 }

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

@@ -63,20 +63,6 @@ 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.3 → frequenz-api-common-0.6.4}/proto/frequenz/api/common/v1/microgrid/components/components.proto

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

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

@@ -0,0 +1,28 @@
+// 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.3 → frequenz-api-common-0.6.4}/proto/frequenz/api/common/v1/microgrid/microgrid.proto

@@ -51,15 +51,9 @@ 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.
@@ -77,3 +71,12 @@ message MicrogridComponentIDs {
   // List of component IDs belonging to this microgrid.
   repeated uint64 component_ids = 2;
 }
+
+/// A message to link sensor IDs with their respective microgrid ID.
+message MicrogridSensorIDs {
+  // The ID of the microgrid.
+  uint64 microgrid_id = 1;
+
+  // List of sensor IDs belonging to this microgrid.
+  repeated uint64 sensor_ids = 2;
+}

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

@@ -0,0 +1,26 @@
+// 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.4/py/conftest.py

@@ -0,0 +1,13 @@
+# 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()

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: frequenz-api-common
-Version: 0.6.3
+Version: 0.6.4
 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 → frequenz-api-common-0.6.4}/py/frequenz_api_common.egg-info/SOURCES.txt

@@ -11,7 +11,6 @@ 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
@@ -28,6 +27,7 @@ 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.3 → frequenz-api-common-0.6.4}/py/frequenz_api_common.egg-info/requires.txt

@@ -1,41 +1,41 @@
-protobuf<7,>=5.28.0
-grpcio<2,>=1.66.1
+protobuf<6,>=4.25.3
+grpcio<2,>=1.51.1
 
 [dev]
 frequenz-api-common[dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]
 
 [dev-flake8]
-flake8==7.1.1
+flake8==7.0.0
 flake8-docstrings==1.7.0
 flake8-pyproject==1.2.3
-pydoclint==0.5.9
+pydoclint==0.4.1
 pydocstyle==6.3.0
 
 [dev-formatting]
-black==24.8.0
+black==24.4.2
 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.39
-mkdocstrings[python]==0.26.1
-frequenz-repo-config[api]==0.10.0
+mkdocs-material==9.5.21
+mkdocstrings[python]==0.25.1
+frequenz-repo-config[api]==0.9.2
 
 [dev-mypy]
-mypy==1.11.2
+mypy==1.10.0
 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.10.0
+frequenz-repo-config[api]==0.9.2
 
 [dev-pylint]
-pylint==3.3.1
+pylint==3.1.0
 frequenz-api-common[dev-mkdocs,dev-noxfile,dev-pytest]
 
 [dev-pytest]
-pytest==8.3.3
-frequenz-repo-config[extra-lint-examples]==0.10.0
+pytest==8.2.0
+frequenz-repo-config[extra-lint-examples]==0.9.2

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

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

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

@@ -5,14 +5,14 @@
 requires = [
   "setuptools == 68.1.0",
   "setuptools_scm[toml] == 7.1.0",
-  "frequenz-repo-config[api] == 0.10.0",
+  "frequenz-repo-config[api] == 0.9.2",
   # 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 == 5.28.0",
-  "grpcio-tools == 1.66.1",
-  "grpcio == 1.66.1",
+  "protobuf == 4.25.3",
+  "grpcio-tools == 1.51.1",
+  "grpcio == 1.51.1",
 ]
 build-backend = "setuptools.build_meta"
 
@@ -33,14 +33,13 @@ classifiers = [
 ]
 requires-python = ">= 3.11, < 4"
 dependencies = [
-  # We can't widen beyond the current value unless we bump the minimum
-  # requirements too because of protobuf cross-version runtime guarantees:
+  # We can't widen beyond 6 because of protobuf cross-version runtime guarantees
   # https://protobuf.dev/support/cross-version-runtime-guarantee/#major
-  "protobuf >= 5.28.0, < 7", # Do not widen beyond 7!
+  "protobuf >= 4.25.3, < 6", # Do not widen beyond 6!
   # 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.66.1, < 2", # Do not widen beyond 2!
+  "grpcio >= 1.51.1, < 2", # Do not widen beyond 2!
 ]
 dynamic = ["version"]
 
@@ -50,36 +49,36 @@ email = "floss@frequenz.com"
 
 [project.optional-dependencies]
 dev-flake8 = [
-  "flake8 == 7.1.1",
+  "flake8 == 7.0.0",
   "flake8-docstrings == 1.7.0",
   "flake8-pyproject == 1.2.3",  # For reading the flake8 config from pyproject.toml
-  "pydoclint == 0.5.9",
+  "pydoclint == 0.4.1",
   "pydocstyle == 6.3.0",
 ]
-dev-formatting = ["black == 24.8.0", "isort == 5.13.2"]
+dev-formatting = ["black == 24.4.2", "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.39",
-  "mkdocstrings[python] == 0.26.1",
-  "frequenz-repo-config[api] == 0.10.0",
+  "mkdocs-material == 9.5.21",
+  "mkdocstrings[python] == 0.25.1",
+  "frequenz-repo-config[api] == 0.9.2",
 ]
 dev-mypy = [
-  "mypy == 1.11.2",
+  "mypy == 1.10.0",
   "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.10.0"]
+dev-noxfile = ["nox == 2024.4.15", "frequenz-repo-config[api] == 0.9.2"]
 dev-pylint = [
-  "pylint == 3.3.1",
+  "pylint == 3.1.0",
   # For checking the noxfile, docs/ script, and tests
   "frequenz-api-common[dev-mkdocs,dev-noxfile,dev-pytest]",
 ]
 dev-pytest = [
-  "pytest == 8.3.3",
-  "frequenz-repo-config[extra-lint-examples] == 0.10.0",
+  "pytest == 8.2.0",
+  "frequenz-repo-config[extra-lint-examples] == 0.9.2",
 ]
 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.3/RELEASE_NOTES.md

@@ -1,22 +0,0 @@
-# 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.3/proto/frequenz/api/common/v1/market/power.proto

@@ -1,30 +0,0 @@
-// 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.3/proto/frequenz/api/common/v1/microgrid/lifetime.proto

@@ -1,41 +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.
-//
-// 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.3/proto/frequenz/api/common/v1/pagination/pagination_params.proto

@@ -1,31 +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.
-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;
-  }
-}