constantize sort direction and DRY up pagination validation

Author: jpstroop

TODO.md

@@ -2,22 +2,22 @@
 
 ## TODO
 
-\_ [ ] Complete coverage
-
-- [ ] need constants for sort "desc"/"asc"
+- [ ] Complete coverage
 
 - [ ] Confront MyPy. See https://stackoverflow.com/a/51294709 for json help
 
-- [ ] add a note about typing, method naming semantics, aliases, and interns.
-
 - [ ] When typing resource, wrap the actual response type around the JSONType,,
   e.g. List[JSONType], Dict[str, JSONType], so that the user can actually know
   what to expect (or None, of course)
 
+- [ ] add a note about typing, method naming semantics, aliases, and interns.
+
 - [ ] Test that all methods have an alias in `Client` and that the signatures
   match
 
-- [ ] validate:
+- [ ] Rationalize `ClientValidationException` subclass inheritance
+
+- [ ] validate Calories From Fat:
   `fitbit_client.exceptions.ValidationException: Calories From Fat must be a valid non-negative number. Currently it is "146.79".`
   It needs to be a positive int!
 

fitbit_client/exceptions.py

@@ -165,6 +165,19 @@ def __init__(
         self.resource_name = resource_name
 
 
+class PaginationException(ClientValidationException):
+    """Raised when pagination-related parameters are invalid"""
+
+    def __init__(self, message: str, field_name: Optional[str] = None):
+        """Initialize pagination validation exception
+
+        Args:
+            message: Error message describing the validation failure
+            field_name: Optional name of the invalid field
+        """
+        super().__init__(message=message, error_type="pagination", field_name=field_name)
+
+
 class IntradayValidationException(ClientValidationException):
     """Raised when intraday request parameters are invalid"""
 

fitbit_client/resources/activity.py

@@ -10,8 +10,9 @@
 from fitbit_client.resources.base import BaseResource
 from fitbit_client.resources.constants import ActivityGoalPeriod
 from fitbit_client.resources.constants import ActivityGoalType
-from fitbit_client.utils.date_validation import validate_date_format
+from fitbit_client.resources.constants import SortDirection
 from fitbit_client.utils.date_validation import validate_date_param
+from fitbit_client.utils.pagination_validation import validate_pagination_params
 
 
 class ActivityResource(BaseResource):
@@ -136,11 +137,14 @@ def create_activity_log(
             "activities.json", params=params, user_id=user_id, http_method="POST", debug=debug
         )
 
+    @validate_date_param(field_name="before_date")
+    @validate_date_param(field_name="after_date")
+    @validate_pagination_params(max_limit=100)
     def get_activity_log_list(
         self,
         before_date: Optional[str] = None,
         after_date: Optional[str] = None,
-        sort: str = "desc",
+        sort: SortDirection = SortDirection.DESCENDING,
         limit: int = 100,
         offset: int = 0,
         user_id: str = "-",
@@ -154,42 +158,25 @@ def get_activity_log_list(
         Args:
             before_date: Get entries before this date (YYYY-MM-DD)
             after_date: Get entries after this date (YYYY-MM-DD)
-            sort: Sort order ('asc' or 'desc')
+            sort: Sort order - use 'asc' with after_date, 'desc' with before_date
             limit: Number of records to return (max 100)
             offset: Offset for pagination
             user_id: Optional user ID, defaults to current user
             debug: If True, a prints a curl command to stdout to help with debugging (default: False)
 
+        Note:
+            Either before_date or after_date must be specified.
+            The offset parameter only supports 0 and using other values may break your application.
+            Use the pagination links in the response to iterate through results.
+
         Returns:
             Dict containing activity logs matching the criteria
 
         Raises:
             ValidationException: If limit exceeds 100 or sort order is invalid
             InvalidDateException: If date format is invalid
         """
-        if limit > 100:
-            raise ValidationException(
-                message="Maximum limit is 100 records",
-                status_code=400,
-                error_type="validation",
-                field_name="limit",
-            )
-
-        if sort not in ("asc", "desc"):
-            raise ValidationException(
-                message="Sort must be either 'asc' or 'desc'",
-                status_code=400,
-                error_type="validation",
-                field_name="sort",
-            )
-
-        # Validate dates if provided
-        if before_date:
-            validate_date_format(before_date, "before_date")
-        if after_date:
-            validate_date_format(after_date, "after_date")
-
-        params = {"sort": sort, "limit": limit, "offset": offset}
+        params = {"sort": sort.value, "limit": limit, "offset": offset}
         if before_date:
             params["beforeDate"] = before_date
         if after_date:

fitbit_client/resources/constants.py

@@ -257,3 +257,10 @@ class IntradayDetailLevel(str, Enum):
     ONE_MINUTE = "1min"
     FIVE_MINUTES = "5min"
     FIFTEEN_MINUTES = "15min"
+
+
+class SortDirection(str, Enum):
+    """Sort directions for lists"""
+
+    ASCENDING = "asc"
+    DESCENDING = "desc"

fitbit_client/resources/electrocardiogram.py

@@ -7,7 +7,9 @@
 
 # Local imports
 from fitbit_client.resources.base import BaseResource
+from fitbit_client.resources.constants import SortDirection
 from fitbit_client.utils.date_validation import validate_date_param
+from fitbit_client.utils.pagination_validation import validate_pagination_params
 
 
 class ElectrocardiogramResource(BaseResource):
@@ -23,11 +25,12 @@ class ElectrocardiogramResource(BaseResource):
 
     @validate_date_param(field_name="before_date")
     @validate_date_param(field_name="after_date")
+    @validate_pagination_params(max_limit=10)
     def get_ecg_log_list(
         self,
         before_date: Optional[str] = None,
         after_date: Optional[str] = None,
-        sort: str = "desc",
+        sort: SortDirection = SortDirection.DESCENDING,
         limit: int = 10,
         offset: int = 0,
         user_id: str = "-",
@@ -43,7 +46,7 @@ def get_ecg_log_list(
                         only YYYY-MM-dd is required
             after_date: Return entries after this date (YYYY-MM-ddTHH:mm:ss),
                        only YYYY-MM-dd is required
-            sort: Sort order by date - use 'asc' with after_date, 'desc' with before_date
+            sort: Sort order - use 'asc' with after_date, 'desc' with before_date
             limit: Number of entries to return (max 10)
             offset: Only 0 is supported
             user_id: Optional user ID, defaults to current user
@@ -59,32 +62,14 @@ def get_ecg_log_list(
             start time, average heart rate, waveform samples, result classification, etc.
 
         Raises:
-            ValueError: If neither before_date nor after_date is provided
-            ValueError: If offset is not 0
-            ValueError: If limit is greater than 10
+            PaginatonError: If neither before_date nor after_date is specified
+            PaginatonError: If offset is not 0
+            PaginatonError: If limit exceeds 10
+            PaginatonError: If sort is not 'asc' or 'desc'
+            PaginatonError: If sort direction doesn't match date parameter
             InvalidDateException: If date format is invalid
         """
-        if not before_date and not after_date:
-            raise ValueError("Either before_date or after_date must be specified")
-
-        if offset != 0:
-            raise ValueError(
-                "Only offset=0 is supported. To paginate, use the next and previous links in the response."
-            )
-
-        if limit > 10:
-            raise ValueError("Maximum limit is 10")
-
-        if sort not in ("asc", "desc"):
-            raise ValueError("Sort must be either 'asc' or 'desc'")
-
-        # Validate sort direction matches date parameter
-        if before_date and sort != "desc":
-            raise ValueError("Must use sort='desc' with before_date")
-        if after_date and sort != "asc":
-            raise ValueError("Must use sort='asc' with after_date")
-
-        params = {"sort": sort, "limit": limit, "offset": offset}
+        params = {"sort": sort.value, "limit": limit, "offset": offset}
 
         if before_date:
             params["beforeDate"] = before_date

fitbit_client/resources/irregular_rhythm_notifications.py

@@ -7,7 +7,9 @@
 
 # Local imports
 from fitbit_client.resources.base import BaseResource
+from fitbit_client.resources.constants import SortDirection
 from fitbit_client.utils.date_validation import validate_date_param
+from fitbit_client.utils.pagination_validation import validate_pagination_params
 
 
 class IrregularRhythmNotificationsResource(BaseResource):
@@ -31,13 +33,14 @@ class IrregularRhythmNotificationsResource(BaseResource):
 
     @validate_date_param(field_name="before_date")
     @validate_date_param(field_name="after_date")
+    @validate_pagination_params(max_limit=10)
     def get_irn_alerts_list(
         self,
-        sort: str,
-        limit: int = 10,
-        offset: int = 0,
         before_date: Optional[str] = None,
         after_date: Optional[str] = None,
+        sort: SortDirection = SortDirection.DESCENDING,
+        limit: int = 10,
+        offset: int = 0,
         user_id: str = "-",
         debug: bool = False,
     ) -> Dict[str, Any]:
@@ -47,49 +50,36 @@ def get_irn_alerts_list(
         API Reference: https://dev.fitbit.com/build/reference/web-api/irregular-rhythm-notifications/get-irn-alerts-list/
 
         Args:
-            sort: Sort order of entries by date. Use 'asc' with after_date, 'desc' with before_date
-            limit: Number of entries to return (max 10)
-            offset: Pagination offset (only 0 is supported)
             before_date: Date in yyyy-MM-ddTHH:mm:ss format (at least yyyy-MM-dd required)
             after_date: Date in yyyy-MM-ddTHH:mm:ss format (at least yyyy-MM-dd required)
+            sort: Sort order - use 'asc' with after_date, 'desc' with before_date
+            limit: Number of entries to return (max 10)
+            offset: Pagination offset (only 0 is supported)
             user_id: The encoded ID of the user. Use "-" (dash) for current logged-in user.
             debug: If True, a prints a curl command to stdout to help with debugging (default: False)
 
+        Note:
+            Either before_date or after_date must be specified.
+            The offset parameter only supports 0 and using other values may break your application.
+            Use the pagination links in the response to iterate through results.
+
         Returns:
             Dictionary containing:
             - alerts: List of IRN alerts with detection times and heart rate data
             - pagination: Information for retrieving next/previous pages
 
         Raises:
-            ValueError: If neither before_date nor after_date is specified
-            ValueError: If offset is not 0
-            ValueError: If limit exceeds 10
-            ValueError: If sort is not 'asc' or 'desc'
-            ValueError: If sort direction doesn't match date parameter
+            PaginatonError: If neither before_date nor after_date is specified
+            PaginatonError: If offset is not 0
+            PaginatonError: If limit exceeds 10
+            PaginatonError: If sort is not 'asc' or 'desc'
+            PaginatonError: If sort direction doesn't match date parameter
             InvalidDateException: If date format is invalid
 
         Note:
             Either before_date or after_date must be specified.
         """
-        if offset != 0:
-            raise ValueError("Only offset=0 is supported for IRN alerts pagination")
-
-        if limit > 10:
-            raise ValueError("Maximum limit is 10 entries")
-
-        if not before_date and not after_date:
-            raise ValueError("Either before_date or after_date must be specified")
-
-        if sort not in ["asc", "desc"]:
-            raise ValueError("Sort must be either 'asc' or 'desc'")
-
-        if sort == "asc" and not after_date:
-            raise ValueError("Must use after_date with ascending sort")
-
-        if sort == "desc" and not before_date:
-            raise ValueError("Must use before_date with descending sort")
-
-        params = {"sort": sort, "limit": limit, "offset": offset}
+        params = {"sort": sort.value, "limit": limit, "offset": offset}
 
         if before_date:
             params["beforeDate"] = before_date

fitbit_client/resources/sleep.py

@@ -7,8 +7,10 @@
 
 # Local imports
 from fitbit_client.resources.base import BaseResource
+from fitbit_client.resources.constants import SortDirection
 from fitbit_client.utils.date_validation import validate_date_param
 from fitbit_client.utils.date_validation import validate_date_range_params
+from fitbit_client.utils.pagination_validation import validate_pagination_params
 
 
 class SleepResource(BaseResource):
@@ -212,11 +214,12 @@ def get_sleep_log_by_date_range(
 
     @validate_date_param(field_name="before_date")
     @validate_date_param(field_name="after_date")
+    @validate_pagination_params(max_limit=100)
     def get_sleep_log_list(
         self,
         before_date: Optional[str] = None,
         after_date: Optional[str] = None,
-        sort: str = "desc",
+        sort: SortDirection = SortDirection.DESCENDING,
         limit: int = 100,
         offset: int = 0,
         user_id: str = "-",
@@ -239,35 +242,21 @@ def get_sleep_log_list(
         Returns:
             Paginated list of sleep logs
 
+        Note:
+            Either before_date or after_date must be specified.
+            The offset parameter only supports 0 and using other values may break your application.
+            Use the pagination links in the response to iterate through results.
+
         Raises:
-            ValueError: If neither before_date nor after_date is specified
-            ValueError: If limit > 100
-            ValueError: If sort is not 'asc' or 'desc'
-            ValueError: If sort direction doesn't match date parameter
+            PaginatonError: If neither before_date nor after_date is specified
+            PaginatonError: If offset is not 0
+            PaginatonError: If limit exceeds 10
+            PaginatonError: If sort is not 'asc' or 'desc'
+            PaginatonError: If sort direction doesn't match date parameter
             InvalidDateException: If date format is invalid
 
-        Note:
-            - Either before_date or after_date must be specified
-            - Use sort='desc' with before_date and sort='asc' with after_date
-            - For pagination, use the next/previous links in the pagination response
-              object rather than manually specifying offset
         """
-        if not before_date and not after_date:
-            raise ValueError("Must specify either before_date or after_date")
-
-        if limit > 100:
-            raise ValueError("Maximum limit is 100")
-
-        if sort not in ("asc", "desc"):
-            raise ValueError("Sort must be either 'asc' or 'desc'")
-
-        # Validate sort direction matches date parameter
-        if before_date and sort != "desc":
-            raise ValueError("Must use sort='desc' with before_date")
-        if after_date and sort != "asc":
-            raise ValueError("Must use sort='asc' with after_date")
-
-        params = {"sort": sort, "limit": limit, "offset": offset}
+        params = {"sort": sort.value, "limit": limit, "offset": offset}
         if before_date:
             params["beforeDate"] = before_date
         if after_date: