base.py refactor (#13)

 * Extract curl command generation functionality from BaseResource to a dedicated mixin in utils/curl_debug_mixin.py. 
 * Replace generic Optional[Dict[str, Any]] with specialized type aliases throughout the codebase:
 * Standardize _make_request call formatting

Author: jpstroop

.gitignore

@@ -44,6 +44,7 @@ coverage.xml
 htmlcov/
 .pytest_cache/
 .mypy_cache/
+*,cover
 
 # Mac
 .DS_Store

TODO.md

@@ -1,49 +1,31 @@
 # Project TODO and Notes
 
-## Refactoring TODOs
+## TODOs:
 
-- Typing
+- PyPi deployment
 
-  - Try to get rid of `Optional[Dict[str, Any]]` args
+- For all `create_...`methods, add the ID from the response to logs and maybe
+  something human readable, like the first n characters of the name??. Right
+  now:
+
+```log
+[2025-02-05 06:09:34,828] INFO [fitbit_client.NutritionResource] create_food_log succeeded for foods/log.json (status 201)
+```
 
 - base.py: reorganize and see what we can move out.
 
   - Rename to `_base`? Files it first, makes it clearer that everything in it is
     private
-  - Move the methods for building `curl` commands into a mixin? It's a lot of
-    code for an isolated and tightly scoped feature.
-  - refactor `_make_request`.
-    - do we need both `data` and `json`? Also, could we simplify a lot of typing
-      if we separated GET, POST, and DELETE methods? Maybe even a separate,
-      second non-auth GET? Could use `@overload`
-    - we had to makee a `ParamDict` type in `nutrition.py`. Use this everywhere?
-    - start by looking at how many methods use which params
 
 - client.py:
 
   - Creat and Test that all methods have an alias in `Client` and that the
     signatures match
 
-```python
-if not food_id and not (food_name and calories):
-    raise ClientValidationException(
-        "Must provide either food_id or (food_name and calories)"
-    )
-```
-
-- nutrition.py:
-- It doesn't seem like this should be passing tests when CALORIES is not an int:
+- CI:
 
-```python
-        # Handle both enum and string nutritional values
-       for key, value in nutritional_values.items():
-           if isinstance(key, NutritionalValue):
-               params[key.value] = float(value)
-           else:
-               params[str(key)] = float(value)
-```
-
-see: test_create_food_calories_from_fat_must_be_integer(nutrition_resource)
+* Read and implement:
+  https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning#configuring-advanced-setup-for-code-scanning-with-codeql
 
 - exceptions.py Consider:
   - Add automatic token refresh for ExpiredTokenException
@@ -77,14 +59,6 @@ see: test_create_food_calories_from_fat_must_be_integer(nutrition_resource)
     be reused.
   - We may need a public version of a generic `make_request` method.
 
-- For all `create_...`methods, add the ID from the response to logs and maybe
-  something human readable, like the first n characters of the name??. Right
-  now:
-
-```log
-[2025-02-05 06:09:34,828] INFO [fitbit_client.NutritionResource] create_food_log succeeded for foods/log.json (status 201)
-```
-
 - Form to change scopes are part of OAuth flow? Maybe get rid of the cut and
   paste method altogether? It's less to test...
 
@@ -101,19 +75,4 @@ see: test_create_food_calories_from_fat_must_be_integer(nutrition_resource)
     one. (there might be several of these that make sense--just take an ID and
     then the signature of the "create" method).
 
-- PyPI deployment
-
 - Enum for units? (it'll be big, maybe just common ones?)
-
-## CI/CD/Linting
-
-- GitHub Actions Setup
-
-  - Linting
-    - black
-    - isort
-    - mdformat
-    - mypy
-  - Test running (TBD)
-  - Coverage reporting (TBD)
-  - Automated PyPI deployment

fitbit_client/exceptions.py

@@ -6,6 +6,9 @@
 from typing import List
 from typing import Optional
 
+# Local imports
+from fitbit_client.utils.types import JSONDict
+
 
 class FitbitAPIException(Exception):
     """Base exception for all Fitbit API errors"""
@@ -15,7 +18,7 @@ def __init__(
         message: str,
         error_type: str,
         status_code: Optional[int] = None,
-        raw_response: Optional[Dict[str, Any]] = None,
+        raw_response: Optional[JSONDict] = None,
         field_name: Optional[str] = None,
     ):
         self.message = message

fitbit_client/resources/activity.py

@@ -18,6 +18,7 @@
 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
 
 
 class ActivityResource(BaseResource):
@@ -88,7 +89,7 @@ def create_activity_goals(
                 field_name="value",
             )
 
-        params = {"type": type.value, "value": value}
+        params: ParamDict = {"type": type.value, "value": value}
         result = self._make_request(
             f"activities/goals/{period.value}.json",
             params=params,
@@ -152,24 +153,26 @@ def create_activity_log(
             - Start time should be in 24-hour format (e.g., "14:30" for 2:30 PM)
         """
         if activity_id:
-            params = {
+            activity_params: ParamDict = {
                 "activityId": activity_id,
                 "startTime": start_time,
                 "durationMillis": duration_millis,
                 "date": date,
             }
             if distance is not None:
-                params["distance"] = distance
+                activity_params["distance"] = distance
                 if distance_unit:
-                    params["distanceUnit"] = distance_unit
+                    activity_params["distanceUnit"] = distance_unit
+            params = activity_params
         elif activity_name and manual_calories:
-            params = {
+            name_params: ParamDict = {
                 "activityName": activity_name,
                 "manualCalories": manual_calories,
                 "startTime": start_time,
                 "durationMillis": duration_millis,
                 "date": date,
             }
+            params = name_params
         else:
             raise MissingParameterException(
                 message="Must provide either activity_id or (activity_name and manual_calories)",
@@ -229,7 +232,7 @@ def get_activity_log_list(
             - The source field indicates whether the activity was logged manually by the user
               or automatically by a Fitbit device
         """
-        params = {"sort": sort.value, "limit": limit, "offset": offset}
+        params: ParamDict = {"sort": sort.value, "limit": limit, "offset": offset}
         if before_date:
             params["beforeDate"] = before_date
         if after_date:
@@ -651,7 +654,9 @@ def get_activity_tcx(
             - Not all activities have TCX data available (e.g., manually logged activities)
             - To check if an activity has GPS data, look for hasGps=True in the activity log
         """
-        params = {"includePartialTCX": include_partial_tcx} if include_partial_tcx else None
+        params: Optional[ParamDict] = (
+            {"includePartialTCX": include_partial_tcx} if include_partial_tcx else None
+        )
         result = self._make_request(
             f"activities/{log_id}.tcx", params=params, user_id=user_id, debug=debug
         )

fitbit_client/resources/base.py

@@ -11,6 +11,7 @@
 from typing import Optional
 from typing import Set
 from typing import cast
+from typing import overload
 from urllib.parse import urlencode
 
 # Third party imports
@@ -21,7 +22,12 @@
 from fitbit_client.exceptions import ERROR_TYPE_EXCEPTIONS
 from fitbit_client.exceptions import FitbitAPIException
 from fitbit_client.exceptions import STATUS_CODE_EXCEPTIONS
+from fitbit_client.utils.curl_debug_mixin import CurlDebugMixin
+from fitbit_client.utils.types import FormDataDict
+from fitbit_client.utils.types import JSONDict
+from fitbit_client.utils.types import JSONList
 from fitbit_client.utils.types import JSONType
+from fitbit_client.utils.types import ParamDict
 
 # Constants for important fields to track in logging
 IMPORTANT_RESPONSE_FIELDS: Set[str] = {
@@ -41,7 +47,7 @@
 }
 
 
-class BaseResource:
+class BaseResource(CurlDebugMixin):
     """Provides foundational functionality for all Fitbit API resource classes.
 
     The BaseResource class implements core functionality that all specific resource
@@ -61,7 +67,7 @@ class BaseResource:
      - Request handling with comprehensive error management
      - Response parsing with type safety
      - Detailed logging of requests, responses, and errors
-     - Debug capabilities for API troubleshooting
+     - Debug capabilities for API troubleshooting (via CurlDebugMixin)
      - OAuth2 authentication management
 
     Note:
@@ -134,7 +140,7 @@ def _build_url(
             return f"{self.API_BASE}/{api_version}/user/{user_id}/{endpoint}"
         return f"{self.API_BASE}/{api_version}/{endpoint}"
 
-    def _extract_important_fields(self, data: Dict[str, JSONType]) -> Dict[str, int | str]:
+    def _extract_important_fields(self, data: JSONDict) -> Dict[str, JSONType]:
         """
         Extract important fields from response data for logging.
 
@@ -150,7 +156,7 @@ def _extract_important_fields(self, data: Dict[str, JSONType]) -> Dict[str, int
         """
         extracted = {}
 
-        def extract_recursive(d: Dict[str, Any], prefix: str = "") -> None:
+        def extract_recursive(d: JSONDict, prefix: str = "") -> None:
             for key, value in d.items():
                 full_key = f"{prefix}.{key}" if prefix else key
 
@@ -189,69 +195,6 @@ def _get_calling_method(self) -> str:
             frame = frame.f_back
         return "unknown"
 
-    def _build_curl_command(
-        self,
-        url: str,
-        http_method: str,
-        data: Optional[Dict[str, Any]] = None,
-        json: Optional[Dict[str, Any]] = None,
-        params: Optional[Dict[str, Any]] = None,
-    ) -> str:
-        """
-        Build a curl command string for debugging API requests.
-        
-        Args:
-            url: Full API URL
-            http_method: HTTP method (GET, POST, DELETE)
-            data: Optional form data for POST requests
-            json: Optional JSON data for POST requests
-            params: Optional query parameters for GET requests
-            
-        Returns:
-            Complete curl command as a multi-line string
-
-        The generated command includes:
-        - The HTTP method (for non-GET requests)
-        - Authorization header with OAuth token
-        - Request body (if data or json is provided)
-        - Query parameters (if provided)
-        
-        The command is formatted with line continuations for readability and
-        can be copied directly into a terminal for testing.
-
-        Example output:
-            curl \\
-              -X POST \\
-              -H "Authorization: Bearer <token>" \\
-              -H "Content-Type: application/json" \\
-              -d '{"name": "value"}' \\
-              'https://api.fitbit.com/1/user/-/foods/log.json'
-        """
-        # Start with base command
-        cmd_parts = ["curl -v"]
-
-        # Add method
-        if http_method != "GET":
-            cmd_parts.append(f"-X {http_method}")
-
-        # Add auth header
-        cmd_parts.append(f'-H "Authorization: Bearer {self.oauth.token["access_token"]}"')
-
-        # Add data if present
-        if json:
-            cmd_parts.append(f"-d '{dumps(json)}'")
-            cmd_parts.append('-H "Content-Type: application/json"')
-        elif data:
-            cmd_parts.append(f"-d '{urlencode(data)}'")
-            cmd_parts.append('-H "Content-Type: application/x-www-form-urlencoded"')
-
-        # Add URL with parameters if present
-        if params:
-            url = f"{url}?{urlencode(params)}"
-        cmd_parts.append(f"'{url}'")
-
-        return " \\\n  ".join(cmd_parts)
-
     def _log_response(
         self, calling_method: str, endpoint: str, response: Response, content: Optional[Dict] = None
     ) -> None:
@@ -391,10 +334,10 @@ def _handle_error_response(self, response: Response) -> None:
     def _make_request(
         self,
         endpoint: str,
-        data: Optional[Dict[str, Any]] = None,
-        json: Optional[Dict[str, Any]] = None,
-        params: Optional[Dict[str, Any]] = None,
-        headers: Dict[str, Any] = {},
+        data: Optional[FormDataDict] = None,
+        json: Optional[JSONDict] = None,
+        params: Optional[ParamDict] = None,
+        headers: Dict[str, str] = {},
         user_id: str = "-",
         requires_user_id: bool = True,
         http_method: str = "GET",
@@ -421,7 +364,7 @@ def _make_request(
 
         Returns:
             JSONType: The API response in one of these formats:
-                - Dict[str, Any]: For most JSON object responses
+                - JSONDict: For most JSON object responses
                 - List[Any]: For endpoints that return JSON arrays
                 - str: For XML/TCX responses
                 - None: For successful DELETE operations or debug mode

fitbit_client/resources/body.py

@@ -9,6 +9,7 @@
 from fitbit_client.resources.constants import BodyGoalType
 from fitbit_client.utils.date_validation import validate_date_param
 from fitbit_client.utils.types import JSONDict
+from fitbit_client.utils.types import ParamDict
 
 
 class BodyResource(BaseResource):
@@ -101,7 +102,7 @@ def create_bodyfat_log(
             The 'source' field will be set to "API" for entries created through this endpoint.
             Multiple entries can be logged for the same day with different timestamps.
         """
-        params = {"fat": fat, "date": date}
+        params: ParamDict = {"fat": fat, "date": date}
         if time:
             params["time"] = time
         result = self._make_request(
@@ -151,7 +152,7 @@ def create_weight_goal(
             - If target > start: "GAIN"
             - If target = start: "MAINTAIN"
         """
-        params = {"startDate": start_date, "startWeight": start_weight}
+        params: ParamDict = {"startDate": start_date, "startWeight": start_weight}
         if weight is not None:
             params["weight"] = weight
         result = self._make_request(
@@ -208,7 +209,7 @@ def create_weight_log(
             The 'source' field will be set to "API" for entries created through this endpoint.
             Multiple weight entries can be logged for the same day with different timestamps.
         """
-        params = {"weight": weight, "date": date}
+        params: ParamDict = {"weight": weight, "date": date}
         if time:
             params["time"] = time
         result = self._make_request(