feat(python-sdk): add headers configuration property (#630)

Author: evansims

config/clients/python/template/README_initializing.mustache

@@ -76,6 +76,66 @@ async def main():
         return api_response
 ```
 
+### Custom Headers
+
+#### Default Headers
+
+You can configure default headers that will be sent with every request by passing them to the `ClientConfiguration`:
+
+```python
+from {{packageName}} import ClientConfiguration, OpenFgaClient
+
+
+async def main():
+    configuration = ClientConfiguration(
+        api_url=FGA_API_URL,
+        store_id=FGA_STORE_ID,
+        authorization_model_id=FGA_MODEL_ID,
+        headers={
+            "X-Custom-Header": "default-value",
+            "X-Request-Source": "my-app",
+        },
+    )
+
+    async with OpenFgaClient(configuration) as fga_client:
+        api_response = await fga_client.read_authorization_models()
+        return api_response
+```
+
+#### Per-Request Headers
+
+You can also send custom headers on a per-request basis by using the `options` parameter. Per-request headers will override any default headers with the same name.
+
+```python
+from {{packageName}} import ClientConfiguration, OpenFgaClient
+from {{packageName}}.client.models import ClientCheckRequest
+
+
+async def main():
+    configuration = ClientConfiguration(
+        api_url=FGA_API_URL,
+        store_id=FGA_STORE_ID,
+        authorization_model_id=FGA_MODEL_ID,
+    )
+
+    async with OpenFgaClient(configuration) as fga_client:
+        # Add custom headers to a specific request
+        result = await fga_client.check(
+            body=ClientCheckRequest(
+                user="user:anne",
+                relation="viewer",
+                object="document:roadmap",
+            ),
+            options={
+                "headers": {
+                    "X-Request-ID": "123e4567-e89b-12d3-a456-426614174000",
+                    "X-Custom-Header": "custom-value",  # Overrides default header value
+                }
+            }
+        )
+        return result
+```
+
 #### Synchronous Client
 
 To run outside of an async context, the project exports a synchronous client

config/clients/python/template/src/client/client.py.mustache

@@ -135,6 +135,11 @@ class OpenFgaClient:
         self._api_client = ApiClient(configuration)
         self._api = OpenFgaApi(self._api_client)
 
+        # Set default headers from configuration
+        if configuration.headers:
+            for header_name, header_value in configuration.headers.items():
+                self._api_client.set_default_header(header_name, header_value)
+
     {{#asyncio}}
     async def __aenter__(self):
         return self

config/clients/python/template/src/client/configuration.py.mustache

@@ -42,6 +42,7 @@ class ClientConfiguration(Configuration):
                 ]
                 | None
             ) = None,
+            headers: dict[str, str] | None = None,
         ):
         super().__init__(
             api_scheme,
@@ -53,6 +54,7 @@ class ClientConfiguration(Configuration):
             api_url=api_url,
             timeout_millisec=timeout_millisec,
             telemetry=telemetry,
+            headers=headers,
         )
         self._authorization_model_id = authorization_model_id
 

config/clients/python/template/src/configuration.py.mustache

@@ -193,6 +193,7 @@ class Configuration:
             | None
         ) = None,
         timeout_millisec: int | None = None,
+        headers: dict[str, str] | None = None,
     ):
         """Constructor"""
         self._url = api_url
@@ -317,6 +318,10 @@ class Configuration:
         """Telemetry configuration
         """
 
+        self._headers = headers or {}
+        """Default headers to be sent with every request
+        """
+
     def __deepcopy__(self, memo):
         cls = self.__class__
         result = cls.__new__(cls)
@@ -647,6 +652,17 @@ class Configuration:
                     f"timeout_millisec not within reasonable range (0,60000), {self._timeout_millisec}"
                 )
 
+        if self._headers is not None:
+            for key, value in self._headers.items():
+                if not isinstance(key, str):
+                    raise FgaValidationException(
+                        f"header keys must be strings, got {type(key).__name__} for key {key}"
+                    )
+                if not isinstance(value, str):
+                    raise FgaValidationException(
+                        f"header values must be strings, got {type(value).__name__} for key '{key}'"
+                    )
+
     @property
     def api_scheme(self):
         """Return connection is https or http."""
@@ -731,3 +747,31 @@ class Configuration:
         Update timeout milliseconds
         """
         self._timeout_millisec = value
+
+    @property
+    def headers(self) -> dict[str, str]:
+        """
+        Return default headers to be sent with every request.
+
+        Headers are key-value pairs that will be included in all API requests.
+        Common use cases include correlation IDs, API versioning, and tenant identification.
+        """
+        return self._headers
+
+    @headers.setter
+    def headers(self, value: dict[str, str] | None) -> None:
+        """
+        Update default headers to be sent with every request.
+
+        Args:
+            value: Dictionary of header names to values, or None to clear headers.
+                   Both keys and values must be strings.
+
+        Raises:
+            FgaValidationException: If value is not a dict or None.
+        """
+        if value is not None and not isinstance(value, dict):
+            raise FgaValidationException(
+                f"headers must be a dict or None, got {type(value).__name__}"
+            )
+        self._headers = value or {}

config/clients/python/template/src/sync/client/client.py.mustache

@@ -135,6 +135,11 @@ class OpenFgaClient:
         self._api_client = ApiClient(configuration)
         self._api = OpenFgaApi(self._api_client)
 
+        # Set default headers from configuration
+        if configuration.headers:
+            for header_name, header_value in configuration.headers.items():
+                self._api_client.set_default_header(header_name, header_value)
+
     def __enter__(self):
         return self