Refactor protobuf messages and files to establish a standard packaging scheme (#131)

tiyash-basu-frequenz · web-flow · commit 3ad73be7448a · 2023-11-08T13:10:18.000Z
This change introduces the following packaging norm to the remaining
protobuf files: the package for every protobuf file is it's path inside
the protobuf directory. E.g., the package name for the message
`PaginationInfo` is `frequenz.api.common.v1.pagination`, and the message
lives in the file
`frequenz/api/common/v1/paginaation/pagination_info.proto`.
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -57,6 +57,10 @@
 
 - Added a message `Microgrid` to represent a microgrid.
 
+- Updated the package name of `location.proto` to `frequenz.api.common.v1`.
+
+- Added messages to support pagination in APIs.
+
 ## New Features
 
 <!-- Here goes the main new features and examples or instructions on how to use them -->
diff --git a/proto/frequenz/api/common/v1/location.proto b/proto/frequenz/api/common/v1/location.proto
@@ -7,7 +7,7 @@
 
 syntax = "proto3";
 
-package frequenz.api.common.v1.location;
+package frequenz.api.common.v1;
 
 // A pair of geographical co-ordinates, representing the location of a place.
 message Location {
diff --git a/proto/frequenz/api/common/v1/metrics/bounds.proto b/proto/frequenz/api/common/v1/metrics/bounds.proto
@@ -0,0 +1,23 @@
+// Definitions for bounds.
+//
+// Copyright:
+// Copyright 2023 Frequenz Energy-as-a-Service GmbH
+//
+// License:
+// MIT
+
+syntax = "proto3";
+
+package frequenz.api.common.v1.metrics;
+
+// A set of lower and upper bounds for any metric.
+// The units of the bounds are always the same as the related metric.
+message Bounds {
+  // The lower bound.
+  // If absent, there is no lower bound.
+  optional float lower = 1;
+
+  // The upper bound.
+  // If absent, there is no upper bound.
+  optional float upper = 2;
+}
diff --git a/proto/frequenz/api/common/v1/metrics/electrical.proto b/proto/frequenz/api/common/v1/metrics/electrical.proto
@@ -10,7 +10,7 @@ syntax = "proto3";
 
 package frequenz.api.common.v1.metrics.electrical;
 
-import "frequenz/api/common/v1/metrics.proto";
+import "frequenz/api/common/v1/metrics/metric_sample.proto";
 
 // Metrics of a DC electrical connection.
 message DC {
diff --git a/proto/frequenz/api/common/v1/metrics/metric_sample.proto b/proto/frequenz/api/common/v1/metrics/metric_sample.proto
@@ -1,4 +1,4 @@
-// Metrics & bounds definitions.
+// Metrics definitions.
 //
 // Copyright:
 // Copyright 2023 Frequenz Energy-as-a-Service GmbH
@@ -10,19 +10,9 @@ syntax = "proto3";
 
 package frequenz.api.common.v1.metrics;
 
-import "google/protobuf/timestamp.proto";
-
-// A set of lower and upper bounds for any metric.
-// The units of the bounds are always the same as the related metric.
-message Bounds {
-  // The lower bound.
-  // If absent, there is no lower bound.
-  optional float lower = 1;
+import "frequenz/api/common/v1/metrics/bounds.proto";
 
-  // The upper bound.
-  // If absent, there is no upper bound.
-  optional float upper = 2;
-}
+import "google/protobuf/timestamp.proto";
 
 // Represents a single sample of a specific metric, the value of which is either
 // measured or derived at a particular time.
diff --git a/proto/frequenz/api/common/v1/microgrid/components/components.proto b/proto/frequenz/api/common/v1/microgrid/components/components.proto
@@ -10,7 +10,7 @@ syntax = "proto3";
 
 package frequenz.api.common.v1.microgrid.components;
 
-import "frequenz/api/common/v1/metrics.proto";
+import "frequenz/api/common/v1/metrics/metric_sample.proto";
 import "frequenz/api/common/v1/microgrid/components/battery.proto";
 import "frequenz/api/common/v1/microgrid/components/ev_charger.proto";
 import "frequenz/api/common/v1/microgrid/components/fuse.proto";
diff --git a/proto/frequenz/api/common/v1/microgrid/microgrid.proto b/proto/frequenz/api/common/v1/microgrid/microgrid.proto
@@ -54,7 +54,7 @@ message Microgrid {
   frequenz.api.common.v1.grid.DeliveryArea delivery_area = 4;
 
   // Physical location of the microgrid, in geographical co-ordinates.
-  frequenz.api.common.v1.location.Location location = 5;
+  frequenz.api.common.v1.Location location = 5;
 
   // The current status of the microgrid.
   MicrogridStatus status = 6;
diff --git a/proto/frequenz/api/common/v1/microgrid/sensors/sensors.proto b/proto/frequenz/api/common/v1/microgrid/sensors/sensors.proto
@@ -10,7 +10,7 @@ syntax = "proto3";
 
 package frequenz.api.common.v1.microgrid.sensors;
 
-import "frequenz/api/common/v1/metrics.proto";
+import "frequenz/api/common/v1/metrics/metric_sample.proto";
 import "frequenz/api/common/v1/microgrid/lifetime.proto";
 
 import "google/protobuf/timestamp.proto";
diff --git a/proto/frequenz/api/common/v1/pagination/pagination_info.proto b/proto/frequenz/api/common/v1/pagination/pagination_info.proto
@@ -9,22 +9,6 @@ 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;
-}
-
 // A message providing metadata about paginated list results.
 // The PaginationInfo message delivers metadata concerning the paginated list
 // results and should be appended to the response message of a list request. The
diff --git a/proto/frequenz/api/common/v1/pagination/pagination_params.proto b/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;
+}
diff --git a/py/frequenz/api/common/v1/pagination/__init__.py b/py/frequenz/api/common/v1/pagination/__init__.py
@@ -0,0 +1,4 @@
+# License: MIT
+# Copyright © 2023 Frequenz Energy-as-a-Service GmbH
+
+"""Frequenz common gRPC API and bindings."""
diff --git a/pytests/test_common.py b/pytests/test_common.py
@@ -12,30 +12,30 @@ def test_package_import() -> None:
     assert v1 is not None
 
 
-def test_module_import_metrics() -> None:
+def test_module_import_metrics_electrical() -> None:
     """Test that the modules can be imported."""
     # pylint: disable=import-outside-toplevel
-    from frequenz.api.common.v1 import metrics_pb2
+    from frequenz.api.common.v1.metrics import electrical_pb2
 
-    assert metrics_pb2 is not None
+    assert electrical_pb2 is not None
 
     # pylint: disable=import-outside-toplevel
-    from frequenz.api.common.v1 import metrics_pb2_grpc
+    from frequenz.api.common.v1.metrics import electrical_pb2_grpc
 
-    assert metrics_pb2_grpc is not None
+    assert electrical_pb2_grpc is not None
 
 
-def test_module_import_metrics_electrical() -> None:
+def test_module_import_metrics_bounds() -> None:
     """Test that the modules can be imported."""
     # pylint: disable=import-outside-toplevel
-    from frequenz.api.common.v1.metrics import electrical_pb2
+    from frequenz.api.common.v1.metrics import bounds_pb2
 
-    assert electrical_pb2 is not None
+    assert bounds_pb2 is not None
 
     # pylint: disable=import-outside-toplevel
-    from frequenz.api.common.v1.metrics import electrical_pb2_grpc
+    from frequenz.api.common.v1.metrics import bounds_pb2_grpc
 
-    assert electrical_pb2_grpc is not None
+    assert bounds_pb2_grpc is not None
 
 
 def test_module_import_grid() -> None:
@@ -166,3 +166,44 @@ def test_module_import_microgrid_components() -> None:
     from frequenz.api.common.v1.microgrid.components import transformer_pb2_grpc
 
     assert transformer_pb2_grpc is not None
+
+
+def test_module_import_location() -> None:
+    """Test that the modules can be imported."""
+    # pylint: disable=import-outside-toplevel
+    from frequenz.api.common.v1 import location_pb2
+
+    assert location_pb2 is not None
+
+    # pylint: disable=import-outside-toplevel
+    from frequenz.api.common.v1 import location_pb2_grpc
+
+    assert location_pb2_grpc is not None
+
+
+def test_module_import_pagination() -> None:
+    """Test that the modules can be imported."""
+    # pylint: disable=import-outside-toplevel
+    from frequenz.api.common.v1 import pagination
+
+    assert pagination is not None
+
+    # pylint: disable=import-outside-toplevel
+    from frequenz.api.common.v1.pagination import pagination_info_pb2
+
+    assert pagination_info_pb2 is not None
+
+    # pylint: disable=import-outside-toplevel
+    from frequenz.api.common.v1.pagination import pagination_info_pb2_grpc
+
+    assert pagination_info_pb2_grpc is not None
+
+    # pylint: disable=import-outside-toplevel
+    from frequenz.api.common.v1.pagination import pagination_params_pb2
+
+    assert pagination_params_pb2 is not None
+
+    # pylint: disable=import-outside-toplevel
+    from frequenz.api.common.v1.pagination import pagination_params_pb2_grpc
+
+    assert pagination_params_pb2_grpc is not None
