Add token pagination support for the list sights endpoint

smartsheet/sights.py

@@ -16,8 +16,9 @@
 # under the License.
 
 import logging
+import warnings
 from datetime import datetime
-from typing import Union
+from typing import Optional, Union
 
 from .util import fresh_operation
 from .models import Error, IndexResult, Result, Share, Sight, SightPublish
@@ -33,28 +34,80 @@ def __init__(self, smartsheet_obj):
         self._log = logging.getLogger(__name__)
 
     def list_sights(
-        self, page_size=None, page=None, include_all=None, modified_since=None
+        self,
+        page_size: Optional[int] = None,
+        page: Optional[int] = None,
+        include_all: Optional[bool] = None,
+        last_key: Optional[str] = None,
+        max_items: Optional[int] = None,
+        pagination_type: Optional[str] = None,
+        modified_since: Optional[datetime] = None
     ) -> Union[IndexResult[Sight], Error]:
         """Get the list of all Sights the User has access to, in alphabetical
         order, by name.
 
         Args:
-            page_size (int): The maximum number of items to
-                return per page.
-            page (int): Which page to return.
-            include_all (bool): If true, include all results
-                (i.e. do not paginate).
-            modified_since(datetime): return sights modified since datetime
+            page_size (int, optional): [DEPRECATED] The maximum number of items to
+                return per page. Use pagination_type='token' with max_items instead.
+            page (int, optional): [DEPRECATED] Which page to return.
+                Use pagination_type='token' with last_key instead.
+            include_all (bool, optional): [DEPRECATED] If true, include all results
+                (i.e. do not paginate). Use pagination_type='token' instead.
+            last_key (str, optional): Pagination cursor for next page (token pagination only).
+            max_items (int, optional): Maximum items per page (token pagination only).
+                Must be a positive integer.
+            pagination_type (str, optional): Use 'token' for efficient cursor-based pagination.
+                Defaults to legacy offset-based pagination if not specified.
+            modified_since (datetime, optional): Return sights modified since datetime.
 
         Returns:
             Union[IndexResult[Sight], Error]: The result of the operation, or an Error object if the request fails.
+                When using legacy pagination, contains paginated results with
+                total_count, total_pages, etc.
+
+        Raises:
+            ValueError: If pagination_type is not 'token' or None, or if max_items <= 0
+                when using token pagination.
         """
+        # Parameter validation
+        if pagination_type is not None and pagination_type not in ['token']:
+            raise ValueError("pagination_type must be 'token' or None")
+        if pagination_type == 'token' and max_items is not None and max_items <= 0:
+            raise ValueError("max_items must be a positive integer")
+
         _op = fresh_operation("list_sights")
         _op["method"] = "GET"
         _op["path"] = "/sights"
-        _op["query_params"]["pageSize"] = page_size
-        _op["query_params"]["page"] = page
-        _op["query_params"]["includeAll"] = include_all
+
+        # Issue deprecation warnings for old parameters when used
+        if page_size is not None:
+            warnings.warn(
+                "page_size parameter is deprecated. Use pagination_type='token' with max_items instead.",
+                DeprecationWarning,
+                stacklevel=2
+            )
+        if page is not None:
+            warnings.warn(
+                "page parameter is deprecated. Use pagination_type='token' with last_key instead.",
+                DeprecationWarning,
+                stacklevel=2
+            )
+        if include_all is not None:
+            warnings.warn(
+                "include_all parameter is deprecated. Use pagination_type='token' instead.",
+                DeprecationWarning,
+                stacklevel=2
+            )
+
+        if pagination_type == "token":
+            _op["query_params"]["lastKey"] = last_key
+            _op["query_params"]["maxItems"] = max_items
+            _op["query_params"]["paginationType"] = pagination_type
+        else:
+            _op["query_params"]["pageSize"] = page_size
+            _op["query_params"]["page"] = page
+            _op["query_params"]["includeAll"] = include_all
+
         if isinstance(modified_since, datetime):
             _op["query_params"]["modifiedSince"] = modified_since.isoformat()