Add v1alpha8 variant of pagination structs

Signed-off-by: Mathias L. Baumann <[email protected]>

Author: Marenz

RELEASE_NOTES.md

@@ -5,13 +5,15 @@
 
 ## Upgrading
 
-<!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with -->
+- The `pagination.Params` and `pagination.Info` classes have been deprecated in favor of `pagination.PaginationParams` and `pagination.PaginationInfo` respectively.
 
 ## New Features
 
 - Mapping for the new `Event` message has been added.
 - Add new common API enums for `ElectricalComponent` (previously `Components`).
 
+- Added `v1alpha8` variants of the pagination data structures.
+
 ## Bug Fixes
 
 - Updated display of protobuf version warnings

src/frequenz/client/common/pagination/__init__.py

@@ -8,13 +8,28 @@
 from dataclasses import dataclass
 from typing import Self
 
+from typing_extensions import deprecated
+
 # pylint: disable=no-name-in-module
-from frequenz.api.common.v1.pagination.pagination_info_pb2 import PaginationInfo
-from frequenz.api.common.v1.pagination.pagination_params_pb2 import PaginationParams
+from frequenz.api.common.v1.pagination.pagination_info_pb2 import (
+    PaginationInfo as PBPaginationInfo,
+)
+from frequenz.api.common.v1.pagination.pagination_params_pb2 import (
+    PaginationParams as PBPaginationParams,
+)
+from frequenz.api.common.v1alpha8.pagination.pagination_info_pb2 import (
+    PaginationInfo as PBPaginationInfoAlpha8,
+)
+from frequenz.api.common.v1alpha8.pagination.pagination_params_pb2 import (
+    PaginationParams as PBPaginationParamsAlpha8,
+)
 
 # pylint: enable=no-name-in-module
 
 
+@deprecated(
+    "Params is deprecated, use PaginationParams instead.",
+)
 @dataclass(frozen=True, kw_only=True)
 class Params:
     """Parameters for paginating list requests."""
@@ -26,7 +41,7 @@ class Params:
     """The token identifying a specific page of the list results."""
 
     @classmethod
-    def from_proto(cls, pagination_params: PaginationParams) -> Self:
+    def from_proto(cls, pagination_params: PBPaginationParams) -> Self:
         """Convert a protobuf Params to PaginationParams object.
 
         Args:
@@ -39,18 +54,21 @@ def from_proto(cls, pagination_params: PaginationParams) -> Self:
             page_token=pagination_params.page_token,
         )
 
-    def to_proto(self) -> PaginationParams:
+    def to_proto(self) -> PBPaginationParams:
         """Convert a Params object to protobuf PaginationParams.
 
         Returns:
             Protobuf message corresponding to the Params object.
         """
-        return PaginationParams(
+        return PBPaginationParams(
             page_size=self.page_size,
             page_token=self.page_token,
         )
 
 
+@deprecated(
+    "Info is deprecated, use PaginationInfo instead.",
+)
 @dataclass(frozen=True, kw_only=True)
 class Info:
     """Information about the pagination of a list request."""
@@ -62,7 +80,79 @@ class Info:
     """The token identifying the next page of results."""
 
     @classmethod
-    def from_proto(cls, pagination_info: PaginationInfo) -> Self:
+    def from_proto(cls, pagination_info: PBPaginationInfo) -> Self:
+        """Convert a protobuf PBPaginationInfo to Info object.
+
+        Args:
+            pagination_info: Info to convert.
+        Returns:
+            Info object corresponding to the protobuf message.
+        """
+        return cls(
+            total_items=pagination_info.total_items,
+            next_page_token=pagination_info.next_page_token,
+        )
+
+    def to_proto(self) -> PBPaginationInfo:
+        """Convert a Info object to protobuf PBPaginationInfo.
+
+        Returns:
+            Protobuf message corresponding to the Info object.
+        """
+        return PBPaginationInfo(
+            total_items=self.total_items,
+            next_page_token=self.next_page_token,
+        )
+
+
+@dataclass(frozen=True, kw_only=True)
+class PaginationParams:
+    """Parameters for paginating list requests."""
+
+    page_size: int
+    """The maximum number of results to be returned per request."""
+
+    page_token: str
+    """The token identifying a specific page of the list results."""
+
+    @classmethod
+    def from_proto(cls, pagination_params: PBPaginationParamsAlpha8) -> Self:
+        """Convert a protobuf PaginationParams to python PaginationParams object.
+
+        Args:
+            pagination_params: Params to convert.
+        Returns:
+            Params object corresponding to the protobuf message.
+        """
+        return cls(
+            page_size=pagination_params.page_size,
+            page_token=pagination_params.page_token,
+        )
+
+    def to_proto(self) -> PBPaginationParamsAlpha8:
+        """Convert a Params object to protobuf PaginationParams.
+
+        Returns:
+            Protobuf message corresponding to the Params object.
+        """
+        return PBPaginationParamsAlpha8(
+            page_size=self.page_size,
+            page_token=self.page_token,
+        )
+
+
+@dataclass(frozen=True, kw_only=True)
+class PaginationInfo:
+    """Information about the pagination of a list request."""
+
+    total_items: int
+    """The total number of items that match the request."""
+
+    next_page_token: str | None = None
+    """The token identifying the next page of results."""
+
+    @classmethod
+    def from_proto(cls, pagination_info: PBPaginationInfoAlpha8) -> Self:
         """Convert a protobuf PBPaginationInfo to Info object.
 
         Args:
@@ -75,13 +165,13 @@ def from_proto(cls, pagination_info: PaginationInfo) -> Self:
             next_page_token=pagination_info.next_page_token,
         )
 
-    def to_proto(self) -> PaginationInfo:
+    def to_proto(self) -> PBPaginationInfoAlpha8:
         """Convert a Info object to protobuf PBPaginationInfo.
 
         Returns:
             Protobuf message corresponding to the Info object.
         """
-        return PaginationInfo(
+        return PBPaginationInfoAlpha8(
             total_items=self.total_items,
             next_page_token=self.next_page_token,
         )