fix: cleanup

Author: SoulPancake

README.md

@@ -1263,7 +1263,7 @@ response = await fga_client.write_assertions(body, options)
 
 ### Calling Other Endpoints
 
-In certain cases you may want to call other APIs not yet wrapped by the SDK. You can do so by using the `execute_api_request` method available on the `OpenFgaClient`. The `execute_api_request` method allows you to make raw HTTP calls to any OpenFGA endpoint by specifying the HTTP method, path, body, query parameters, and path parameters, while still honoring the client configuration (authentication, telemetry, retries, and error handling).
+In certain cases you may want to call other APIs not yet wrapped by the SDK. You can do so by using the `execute_api_request` method available on the `OpenFgaClient`. It allows you to make raw HTTP calls to any OpenFGA endpoint by specifying the HTTP method, path, body, query parameters, and path parameters, while still honoring the client configuration (authentication, telemetry, retries, and error handling).
 
 For streaming endpoints, use `execute_streamed_api_request` instead.
 
@@ -1272,35 +1272,7 @@ This is useful when:
 - You are using an earlier version of the SDK that doesn't yet support a particular endpoint
 - You have a custom endpoint deployed that extends the OpenFGA API
 
-In all cases, you initialize the SDK the same way as usual, and then call `execute_api_request` on the `fga_client` instance.
-
-```python
-from openfga_sdk import ClientConfiguration, OpenFgaClient
-
-configuration = ClientConfiguration(
-    api_url=FGA_API_URL,
-    store_id=FGA_STORE_ID,
-)
-
-async with OpenFgaClient(configuration) as fga_client:
-    request_body = {
-        "user": "user:bob",
-        "action": "custom_action",
-        "resource": "resource:123",
-    }
-    
-    response = await fga_client.execute_api_request(
-        operation_name="CustomEndpoint",
-        method="POST",
-        path="/stores/{store_id}/custom-endpoint",
-        path_params={"store_id": FGA_STORE_ID},
-        query_params={"page_size": "20"},
-        body=request_body,
-        headers={"X-Experimental-Feature": "enabled"},
-    )
-```
-
-#### Example: Calling a custom endpoint with POST
+#### Example: Calling a Custom Endpoint with POST
 
 ```python
 # Call a custom endpoint using path parameters

openfga_sdk/client/client.py

@@ -1126,28 +1126,19 @@ async def execute_api_request(
         """
         Execute an arbitrary HTTP request to any OpenFGA API endpoint.
 
-        Useful when you need to call a new or experimental API that doesn't
-        yet have a built-in method in the SDK. You still get the benefits of
-        the SDK: authentication, configuration, retries, and error handling.
-
-        :param operation_name: Required. Operation name for telemetry/logging
-            (e.g., "CustomCheck", "CustomEndpoint")
-        :param method: Required. HTTP method (GET, POST, PUT, DELETE, PATCH)
-        :param path: Required. API path with optional template parameters
-            (e.g., "/stores/{store_id}/my-endpoint")
-        :param path_params: Path parameters to replace template variables.
-            If {store_id} is in the path and not provided here, it will be
-            automatically substituted from the client configuration.
-        :param body: Request body for POST/PUT/PATCH requests
+        Useful for calling endpoints not yet wrapped by the SDK while
+        still getting authentication, retries, and error handling.
+
+        :param operation_name: Operation name for telemetry (e.g., "CustomCheck")
+        :param method: HTTP method (GET, POST, PUT, DELETE, PATCH)
+        :param path: API path, e.g. "/stores/{store_id}/my-endpoint".
+            {store_id} is auto-substituted from config if not in path_params.
+        :param path_params: Path parameter substitutions (URL-encoded automatically)
+        :param body: Request body for POST/PUT/PATCH
         :param query_params: Query string parameters
-        :param headers: Custom request headers. SDK always enforces
-            Content-Type and Accept as application/json.
-        :param options: Additional request options:
-            - headers: Extra headers (merged; options headers take precedence)
-            - retry_params: Override retry parameters for this request
+        :param headers: Custom headers (SDK enforces Content-Type and Accept)
+        :param options: Extra options (headers, retry_params)
         :return: RawResponse with status, headers, and body
-        :raises FgaValidationException: If required parameters are missing
-        :raises ApiException: For HTTP errors
         """
         return await self._execute_api_request_internal(
             operation_name=operation_name,
@@ -1204,8 +1195,7 @@ async def _execute_api_request_internal(
         options: dict[str, int | str | dict[str, int | str]] | None = None,
         streaming: bool = False,
     ) -> RawResponse:
-        """Internal implementation for execute_api_request and execute_streamed_api_request."""
-        # 1. Validate and build request
+        """Shared implementation for execute_api_request and execute_streamed_api_request."""
         builder = ExecuteApiRequestBuilder(
             operation_name=operation_name,
             method=method,
@@ -1217,7 +1207,6 @@ async def _execute_api_request_internal(
         )
         builder.validate()
 
-        # 2. Build path, query params, and headers
         resource_path = builder.build_path(self.get_store_id())
         query_params_list = builder.build_query_params_list()
 
@@ -1226,7 +1215,6 @@ async def _execute_api_request_internal(
             options_headers = options["headers"]
         final_headers = builder.build_headers(options_headers)
 
-        # 3. Apply authentication
         auth_headers = dict(final_headers)
         await self._api_client.update_params_for_auth(
             auth_headers,
@@ -1235,7 +1223,6 @@ async def _execute_api_request_internal(
             oauth2_client=self._api._oauth2_client,
         )
 
-        # 4. Build telemetry attributes
         telemetry_attributes = {
             TelemetryAttributes.fga_client_request_method: operation_name.lower(),
         }
@@ -1244,12 +1231,10 @@ async def _execute_api_request_internal(
                 self.get_store_id()
             )
 
-        # 5. Extract retry params
         retry_params = None
         if options and options.get("retry_params"):
             retry_params = options["retry_params"]
 
-        # 6. Make API request
         await self._api_client.call_api(
             resource_path=resource_path,
             method=method.upper(),
@@ -1266,17 +1251,13 @@ async def _execute_api_request_internal(
             _streaming=streaming,
         )
 
-        # 7. Parse response
         rest_response: RESTResponse | None = getattr(
             self._api_client, "last_response", None
         )
-
         if rest_response is None:
             raise RuntimeError(
-                f"Failed to get response from API client for {method.upper()} "
-                f"request to '{resource_path}' (operation: {operation_name}). "
-                "This may indicate an internal SDK error, network problem, "
-                "or client configuration issue."
+                f"No response for {method.upper()} {resource_path} "
+                f"(operation: {operation_name})"
             )
 
         return RawResponse(

openfga_sdk/client/execute_api_request_builder.py

@@ -1,9 +1,4 @@
-"""
-Builders and utilities for execute_api_request functionality.
-
-This module provides reusable utilities for request building, header management,
-and response parsing to reduce code duplication across sync and async clients.
-"""
+"""Utilities for execute_api_request: request building, header management, response parsing."""
 
 import json
 import re
@@ -15,12 +10,7 @@
 
 
 class ExecuteApiRequestBuilder:
-    """
-    Builder for API request execution.
-
-    Encapsulates request validation, parameter building, and path construction
-    to eliminate duplication and improve maintainability.
-    """
+    """Builds and validates parameters for execute_api_request calls."""
 
     def __init__(
         self,
@@ -43,11 +33,7 @@ def __init__(
         self.headers = headers
 
     def validate(self) -> None:
-        """
-        Validate all required parameters are present.
-
-        :raises FgaValidationException: If any required parameter is missing
-        """
+        """Validate that all required parameters are present."""
         if not self.operation_name:
             raise FgaValidationException(
                 "operation_name is required for execute_api_request"
@@ -59,14 +45,9 @@ def validate(self) -> None:
 
     def build_path(self, configured_store_id: str | None = None) -> str:
         """
-        Build and validate final resource path with parameter substitution.
-
-        Automatically substitutes {store_id} with configured store_id if not
-        explicitly provided in path_params.
+        Build resource path with parameter substitution.
 
-        :param configured_store_id: Store ID from client configuration
-        :return: Final resource path with all parameters substituted
-        :raises FgaValidationException: If path construction fails
+        Auto-substitutes {store_id} from client config if not in path_params.
         """
         path = self.path
         params = dict(self.path_params) if self.path_params else {}
@@ -99,16 +80,7 @@ def build_path(self, configured_store_id: str | None = None) -> str:
         return result
 
     def build_query_params_list(self) -> list[tuple[str, str]]:
-        """
-        Convert query_params dict to list of tuples for the API client.
-
-        Handles:
-        - List values (expanded to multiple tuples with same key)
-        - None values (filtered out)
-        - Type conversion to string
-
-        :return: List of (key, value) tuples for query parameters
-        """
+        """Convert query_params dict to list of (key, value) tuples. Expands lists, filters None."""
         if not self.query_params:
             return []
 
@@ -127,15 +99,9 @@ def build_headers(
         options_headers: dict[str, str] | None = None,
     ) -> dict[str, str]:
         """
-        Build final headers with proper precedence and SDK enforcement.
+        Merge request headers, options headers, and SDK-enforced defaults.
 
-        Header precedence (highest to lowest):
-        1. SDK-enforced headers (Content-Type, Accept — always application/json)
-        2. Options headers (from method options parameter)
-        3. Request headers (from headers parameter)
-
-        :param options_headers: Headers from method options
-        :return: Final merged headers with SDK enforcement
+        SDK always enforces Content-Type and Accept as application/json.
         """
         result = dict(self.headers) if self.headers else {}
         if options_headers:
@@ -147,24 +113,13 @@ def build_headers(
 
 
 class ResponseParser:
-    """Parse raw REST responses to appropriate Python types."""
+    """Parse raw REST responses into Python types."""
 
     @staticmethod
     def parse_body(
         data: bytes | str | dict[str, Any] | None,
     ) -> bytes | str | dict[str, Any] | None:
-        """
-        Parse response body, attempting JSON deserialization.
-
-        Handles:
-        - None values (returned as-is)
-        - Dict objects (returned as-is)
-        - String values (attempts JSON parsing, falls back to string)
-        - Bytes values (attempts UTF-8 decode + JSON, falls back gracefully)
-
-        :param data: Raw response data from REST client
-        :return: Parsed response (dict if JSON, else original type)
-        """
+        """Parse response data, attempting JSON deserialization."""
         if data is None:
             return None
 

openfga_sdk/client/models/raw_response.py

@@ -1,9 +1,4 @@
-"""
-Raw response wrapper for raw_request method.
-
-This module provides a simple response wrapper for raw HTTP requests
-made through the SDK's raw_request method.
-"""
+"""Response wrapper for execute_api_request."""
 
 import json
 
@@ -14,32 +9,26 @@
 @dataclass
 class RawResponse:
     """
-    Response wrapper for raw HTTP requests.
-
-    This class provides a simple interface to access the response
-    from a raw_request call, including status code, headers, and body.
+    Response from execute_api_request / execute_streamed_api_request.
 
-    The body is automatically parsed as JSON if possible, otherwise
-    it's returned as a string or bytes.
+    The body is automatically parsed as JSON if possible,
+    otherwise returned as a string or bytes.
     """
 
     status: int
     """HTTP status code"""
 
     headers: dict[str, str]
-    """Response headers as a dictionary"""
+    """Response headers"""
 
     body: bytes | str | dict[str, Any] | None = None
-    """Response body (already parsed as dict if JSON, otherwise str or bytes)"""
+    """Response body (dict if JSON, otherwise str or bytes)"""
 
     def json(self) -> dict[str, Any] | None:
         """
-        Return the response body as a JSON dictionary.
-
-        The body is already parsed during the request, so this typically
-        just returns the body if it's a dict, or None otherwise.
+        Return the response body as a parsed JSON dictionary.
 
-        :return: Parsed JSON dictionary or None
+        :return: Parsed dict or None
         """
         if isinstance(self.body, dict):
             return self.body
@@ -49,7 +38,7 @@ def text(self) -> str | None:
         """
         Return the response body as a string.
 
-        :return: Response body as string or None
+        :return: Body as string, or None
         """
         if self.body is None:
             return None