Refactor pagination.proto

This commit refactors `pagination.proto` to move the `PaginationParams`
and `PaginationInfo` messages to their own files, in a new directory
`pagination`.

This sets package name of this proto file to its parent directory name,
which seems to be a standard practice.

Signed-off-by: Tiyash Basu <[email protected]>

Author: tiyash-basu-frequenz

RELEASE_NOTES.md

@@ -59,6 +59,8 @@
 
 - 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 -->

proto/frequenz/api/common/v1/pagination.proto renamed to 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

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;
+}

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."""

pytests/test_common.py

@@ -179,3 +179,31 @@ def test_module_import_location() -> None:
     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