diff --git a/smartsheet/sights.py b/smartsheet/sights.py index a942df6..bb05ad3 100644 --- a/smartsheet/sights.py +++ b/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()