Refactor curl debug functionality into CurlDebugMixin

Extract curl command generation functionality from BaseResource to a dedicated mixin in utils/curl_debug_mixin.py. This improves code organization by:

1. Moving a single-purpose feature into its own module
2. Simplifying the BaseResource class
3. Making the debug functionality more reusable

Also updated tests to maintain 100% coverage.

Author: jpstroop

TODO.md

@@ -10,8 +10,7 @@
 
   - 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.
+  - ✅ Move the methods for building `curl` commands into a mixin.
   - 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,
@@ -24,26 +23,10 @@
   - 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:
-
-```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)
-```
+- CI:
 
-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

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,11 @@
 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 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 +46,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 +66,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:
@@ -189,69 +194,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:

fitbit_client/utils/curl_debug_mixin.py

@@ -0,0 +1,87 @@
+# fitbit_client/utils/curl_debug_mixin.py
+
+"""
+Mixin for generating curl commands for API debugging.
+"""
+
+# Standard library imports
+from json import dumps
+from typing import Any
+from typing import Dict
+from typing import Optional
+from urllib.parse import urlencode
+
+
+class CurlDebugMixin:
+    """Mixin that provides curl command generation for debugging API requests.
+
+    This mixin can be used with API client classes to add the ability to generate
+    equivalent curl commands for debugging purposes. It helps with:
+    - Testing API endpoints directly
+    - Debugging authentication/scope issues
+    - Verifying request structure
+    - Troubleshooting permission problems
+    """
+
+    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)

tests/resources/test_base.py

@@ -247,38 +247,10 @@ def test_log_response_for_error_without_content(base_resource, mock_logger):
 
 
 # -----------------------------------------------------------------------------
-# 6. Debug Curl Command Generation
+# 6. Debug Mode Testing
 # -----------------------------------------------------------------------------
 
-
-def test_build_curl_command_with_json_data(base_resource):
-    """Test generating curl command with JSON data"""
-    # This tests lines 217-218 in base.py
-    base_resource.oauth.token = {"access_token": "test_token"}
-
-    json_data = {"name": "Test Activity", "type": "run", "duration": 3600}
-    result = base_resource._build_curl_command(
-        url="https://api.fitbit.com/1/user/-/activities.json", http_method="POST", json=json_data
-    )
-
-    # Assert command contains JSON data and correct header
-    assert '-d \'{"name": "Test Activity", "type": "run", "duration": 3600}\'' in result
-    assert '-H "Content-Type: application/json"' in result
-
-
-def test_build_curl_command_with_form_data(base_resource):
-    """Test generating curl command with form data"""
-    # This tests lines 220-221 in base.py
-    base_resource.oauth.token = {"access_token": "test_token"}
-
-    form_data = {"date": "2023-01-01", "foodId": "12345", "amount": "1", "mealTypeId": "1"}
-    result = base_resource._build_curl_command(
-        url="https://api.fitbit.com/1/user/-/foods/log.json", http_method="POST", data=form_data
-    )
-
-    # Assert command contains form data and correct header
-    assert "-d 'date=2023-01-01&foodId=12345&amount=1&mealTypeId=1'" in result
-    assert '-H "Content-Type: application/x-www-form-urlencoded"' in result
+# Debug mode tests are now in tests/utils/test_curl_debug_mixin.py
 
 
 # -----------------------------------------------------------------------------

tests/utils/test_curl_debug_mixin.py

@@ -0,0 +1,118 @@
+# tests/utils/test_curl_debug_mixin.py
+
+"""Tests for CurlDebugMixin"""
+
+# Standard library imports
+from unittest.mock import Mock
+from unittest.mock import patch
+
+# Third party imports
+from pytest import fixture
+
+# Local imports
+from fitbit_client.utils.curl_debug_mixin import CurlDebugMixin
+
+
+# Create a test class that uses the mixin for debug testing
+class TestResource(CurlDebugMixin):
+    """Test class that uses CurlDebugMixin"""
+
+    def __init__(self):
+        self.oauth = Mock()
+        self.oauth.token = {"access_token": "test_token"}
+
+    def make_debug_request(self, debug=False):
+        """Test method that simulates _make_request with debug mode"""
+        url = "https://api.fitbit.com/1/user/-/test/endpoint"
+
+        if debug:
+            curl_command = self._build_curl_command(
+                url=url, http_method="GET", params={"param1": "value1"}
+            )
+            print(f"\n# Debug curl command:")
+            print(curl_command)
+            print()
+            return None
+
+        return {"success": True}
+
+
+@fixture
+def curl_debug_mixin():
+    """Fixture for CurlDebugMixin with mocked OAuth session"""
+    mixin = CurlDebugMixin()
+    mixin.oauth = Mock()
+    mixin.oauth.token = {"access_token": "test_token"}
+    return mixin
+
+
+def test_build_curl_command_with_json_data(curl_debug_mixin):
+    """Test generating curl command with JSON data"""
+    json_data = {"name": "Test Activity", "type": "run", "duration": 3600}
+    result = curl_debug_mixin._build_curl_command(
+        url="https://api.fitbit.com/1/user/-/activities.json", http_method="POST", json=json_data
+    )
+
+    # Assert command contains JSON data and correct header
+    assert '-d \'{"name": "Test Activity", "type": "run", "duration": 3600}\'' in result
+    assert '-H "Content-Type: application/json"' in result
+    assert "-X POST" in result
+    assert "curl -v" in result
+    assert '-H "Authorization: Bearer test_token"' in result
+    assert "'https://api.fitbit.com/1/user/-/activities.json'" in result
+
+
+def test_build_curl_command_with_form_data(curl_debug_mixin):
+    """Test generating curl command with form data"""
+    form_data = {"date": "2023-01-01", "foodId": "12345", "amount": "1", "mealTypeId": "1"}
+    result = curl_debug_mixin._build_curl_command(
+        url="https://api.fitbit.com/1/user/-/foods/log.json", http_method="POST", data=form_data
+    )
+
+    # Assert command contains form data and correct header
+    assert "-d 'date=2023-01-01&foodId=12345&amount=1&mealTypeId=1'" in result
+    assert '-H "Content-Type: application/x-www-form-urlencoded"' in result
+    assert "-X POST" in result
+
+
+def test_build_curl_command_with_get_params(curl_debug_mixin):
+    """Test generating curl command with GET parameters"""
+    params = {"date": "2023-01-01", "offset": "0", "limit": "10"}
+    result = curl_debug_mixin._build_curl_command(
+        url="https://api.fitbit.com/1/user/-/activities/list.json", http_method="GET", params=params
+    )
+
+    # Assert command doesn't have -X GET but has parameters in URL
+    assert "-X GET" not in result
+    assert "?date=2023-01-01&offset=0&limit=10" in result
+
+
+def test_build_curl_command_with_delete(curl_debug_mixin):
+    """Test generating curl command for DELETE request"""
+    result = curl_debug_mixin._build_curl_command(
+        url="https://api.fitbit.com/1/user/-/foods/log/123456.json", http_method="DELETE"
+    )
+
+    # Assert command has DELETE method
+    assert "-X DELETE" in result
+    assert "curl -v" in result
+    assert '-H "Authorization: Bearer test_token"' in result
+
+
+def test_debug_mode_integration(capsys):
+    """Test debug mode integration with a resource class"""
+    # Create test resource
+    resource = TestResource()
+
+    # Call make_debug_request with debug=True
+    result = resource.make_debug_request(debug=True)
+
+    # Capture stdout
+    captured = capsys.readouterr()
+
+    # Verify results
+    assert result is None
+    assert "curl" in captured.out
+    assert "test/endpoint" in captured.out
+    assert "param1=value1" in captured.out
+    assert "test_token" in captured.out