Fix mypy typing issues and achieve 100% test coverage for pagination

- Add TYPE_CHECKING for proper handling of circular imports
- Fix return type annotations in BaseResource
- Remove unreachable code in BaseResource methods
- Add comprehensive tests for pagination edge cases
- Move imports to top of files following best practices
- Update pagination documentation with implementation details
- Configure test coverage to exclude TYPE_CHECKING blocks

Author: jpstroop

.gitignore

@@ -46,10 +46,6 @@ htmlcov/
 .mypy_cache/
 *,cover
 
-# Mac
-.DS_Store
-*,cover
-
 # Mac
 .DS_Store
 

docs/PAGINATION.md

@@ -2,7 +2,7 @@
 
 Some Fitbit API endpoints return potentially large result sets and support
 pagination. This library provides an easy way to work with these paginated
-endpoints.
+endpoints through a robust and type-safe implementation.
 
 ## Supported Endpoints
 
@@ -87,3 +87,23 @@ Each paginated endpoint has specific constraints:
 
 - Max limit: 10 entries per page
 - Only supports `offset=0`
+
+## Implementation Details
+
+The pagination implementation uses the following approach:
+
+### Pagination Iterator
+
+- Uses the `PaginatedIterator` class that implements the Python `Iterator` protocol
+- Automatically handles fetching the next page when needed using the `next` URL from pagination metadata
+- Properly handles edge cases like invalid responses, missing pagination data, and API errors
+
+### Type Safety
+
+- Uses `TYPE_CHECKING` from the typing module to avoid circular imports at runtime
+- Maintains complete type safety and mypy compatibility
+- All pagination-related code has 100% test coverage
+
+### Resource Integration
+
+Each endpoint that supports pagination has an `as_iterator` parameter that, when set to `True`, returns a `PaginatedIterator` instead of the raw API response. This makes it easy to iterate through all pages of results without manually handling pagination.

fitbit_client/resources/activity.py

@@ -5,6 +5,7 @@
 from typing import Dict
 from typing import Never
 from typing import Optional
+from typing import TYPE_CHECKING
 from typing import Union
 from typing import cast
 
@@ -15,12 +16,21 @@
 from fitbit_client.resources.constants import ActivityGoalPeriod
 from fitbit_client.resources.constants import ActivityGoalType
 from fitbit_client.resources.constants import SortDirection
+from fitbit_client.resources.pagination import create_paginated_iterator
 from fitbit_client.utils.date_validation import validate_date_param
 from fitbit_client.utils.pagination_validation import validate_pagination_params
 from fitbit_client.utils.types import JSONDict
 from fitbit_client.utils.types import JSONList
 from fitbit_client.utils.types import ParamDict
 
+# We use TYPE_CHECKING to avoid circular imports at runtime.
+# PaginatedIterator is only needed for type annotations, not for runtime code.
+# This pattern is recommended by the Python typing documentation:
+# https://docs.python.org/3/library/typing.html#typing.TYPE_CHECKING
+if TYPE_CHECKING:
+    # Local imports - only imported during type checking
+    from fitbit_client.resources.pagination import PaginatedIterator
+
 
 class ActivityResource(BaseResource):
     """Provides access to Fitbit Activity API for managing user activities and goals.
@@ -253,9 +263,7 @@ def get_activity_log_list(
             params["afterDate"] = after_date
 
         endpoint = "activities/list.json"
-        result = self._make_request(
-            endpoint, params=params, user_id=user_id, debug=debug
-        )
+        result = self._make_request(endpoint, params=params, user_id=user_id, debug=debug)
 
         # If debug mode is enabled, result will be None
         if debug or result is None:
@@ -264,15 +272,12 @@ def get_activity_log_list(
         # Return as iterator if requested
         # We use string literal type annotation 'PaginatedIterator' to avoid circular imports
         if as_iterator:
-            # Local imports
-            from fitbit_client.resources.pagination import create_paginated_iterator
-
             return create_paginated_iterator(
-                response=cast(JSONDict, result), 
-                resource=self, 
+                response=cast(JSONDict, result),
+                resource=self,
                 endpoint=endpoint,
                 method_params=params,
-                debug=debug
+                debug=debug,
             )
 
         return cast(JSONDict, result)

fitbit_client/resources/base.py

@@ -552,10 +552,7 @@ def _make_request(
                 )
                 raise
 
-            # If we successfully made a request and got a valid response, break the loop
-            break
-
-    def _make_direct_request(self, path: str, debug: bool = False) -> JSONDict:
+    def _make_direct_request(self, path: str, debug: bool = False) -> JSONType:
         """Makes a request directly to the specified path.
 
         This method is used internally for pagination to follow "next" URLs.
@@ -639,6 +636,3 @@ def _make_direct_request(self, path: str, debug: bool = False) -> JSONDict:
                     error_type="request",
                     status_code=500,
                 )
-
-            # If we successfully made a request and got a valid response, break the loop
-            break

fitbit_client/resources/electrocardiogram.py

@@ -4,17 +4,23 @@
 from typing import Any
 from typing import Dict
 from typing import Optional
+from typing import TYPE_CHECKING
 from typing import Union
 from typing import cast
 
 # Local imports
 from fitbit_client.resources.base import BaseResource
 from fitbit_client.resources.constants import SortDirection
+from fitbit_client.resources.pagination import create_paginated_iterator
 from fitbit_client.utils.date_validation import validate_date_param
 from fitbit_client.utils.pagination_validation import validate_pagination_params
 from fitbit_client.utils.types import JSONDict
 from fitbit_client.utils.types import ParamDict
 
+if TYPE_CHECKING:
+    # Local imports
+    from fitbit_client.resources.pagination import PaginatedIterator
+
 
 class ElectrocardiogramResource(BaseResource):
     """Provides access to Fitbit Electrocardiogram (ECG) API for retrieving heart rhythm assessments.
@@ -122,17 +128,14 @@ def get_ecg_log_list(
             return cast(JSONDict, result)
 
         # Return as iterator if requested
-        # We use string literal type annotation 'PaginatedIterator' to avoid circular imports
+        # We use TYPE_CHECKING for PaginatedIterator type to avoid circular imports
         if as_iterator:
-            # Local imports
-            from fitbit_client.resources.pagination import create_paginated_iterator
-
             return create_paginated_iterator(
-                response=cast(JSONDict, result), 
-                resource=self, 
+                response=cast(JSONDict, result),
+                resource=self,
                 endpoint=endpoint,
                 method_params=params,
-                debug=debug
+                debug=debug,
             )
 
         return cast(JSONDict, result)

fitbit_client/resources/irregular_rhythm_notifications.py

@@ -2,17 +2,23 @@
 
 # Standard library imports
 from typing import Optional
+from typing import TYPE_CHECKING
 from typing import Union
 from typing import cast
 
 # Local imports
 from fitbit_client.resources.base import BaseResource
 from fitbit_client.resources.constants import SortDirection
+from fitbit_client.resources.pagination import create_paginated_iterator
 from fitbit_client.utils.date_validation import validate_date_param
 from fitbit_client.utils.pagination_validation import validate_pagination_params
 from fitbit_client.utils.types import JSONDict
 from fitbit_client.utils.types import ParamDict
 
+if TYPE_CHECKING:
+    # Local imports
+    from fitbit_client.resources.pagination import PaginatedIterator
+
 
 class IrregularRhythmNotificationsResource(BaseResource):
     """Provides access to Fitbit Irregular Rhythm Notifications (IRN) API for heart rhythm monitoring.
@@ -116,26 +122,21 @@ def get_irn_alerts_list(
             params["afterDate"] = after_date
 
         endpoint = "irn/alerts/list.json"
-        result = self._make_request(
-            endpoint, params=params, user_id=user_id, debug=debug
-        )
+        result = self._make_request(endpoint, params=params, user_id=user_id, debug=debug)
 
         # If debug mode is enabled, result will be None
         if debug or result is None:
             return cast(JSONDict, result)
 
         # Return as iterator if requested
-        # We use string literal type annotation 'PaginatedIterator' to avoid circular imports
+        # We use TYPE_CHECKING for PaginatedIterator type to avoid circular imports
         if as_iterator:
-            # Local imports
-            from fitbit_client.resources.pagination import create_paginated_iterator
-
             return create_paginated_iterator(
-                response=cast(JSONDict, result), 
-                resource=self, 
+                response=cast(JSONDict, result),
+                resource=self,
                 endpoint=endpoint,
                 method_params=params,
-                debug=debug
+                debug=debug,
             )
 
         return cast(JSONDict, result)