feat(python-sdk): add headers configuration property

[evansims]

This pull request adds a headers property to the SDK's client configuration class, allowing developers to pass headers that are automatically included in all API requests by default.

This pattern aligns the Python SDK with behavior already present in the other SDKs.

from openfga_sdk.client import ClientConfiguration, OpenFgaClient

# Configure default headers that apply to ALL requests
config = ClientConfiguration(
    api_url="https://api.fga.example",
    store_id="01ARZ3NDEKTSV4RRFFQ69G5FAV",
    headers={
        "X-Tenant-ID": "tenant-123",
        "X-App-Version": "1.0.0",
        "X-Request-Priority": "normal"
    }
)

async with OpenFgaClient(config) as client:
    # Default headers are automatically included in all requests
    await client.read_authorization_models()
    # Includes: X-Tenant-ID: tenant-123, X-App-Version: 1.0.0, X-Request-Priority: normal

    # Add per-request headers (merged with defaults)
    await client.check(
        user="user:alice",
        relation="viewer",
        object="document:roadmap",
        options={
            "headers": {
                "X-Request-ID": "req-456",
                "X-Correlation-ID": "corr-789"
            }
        }
    )
    # Includes: X-Tenant-ID: tenant-123, X-App-Version: 1.0.0, X-Request-Priority: normal,
    #           X-Request-ID: req-456, X-Correlation-ID: corr-789

    # Override default headers with per-request values
    await client.check(
        user="user:bob",
        relation="admin",
        object="document:secrets",
        options={
            "headers": {
                "X-Request-Priority": "high", # Overrides default "normal" priority
                "X-Request-ID": "req-789"
            }
        }
    )
    # Includes: X-Tenant-ID: tenant-123, X-App-Version: 1.0.0,
    #           X-Request-Priority: high (OVERRIDDEN), X-Request-ID: req-789

References

openfga/python-sdk#233

Review Checklist

• I have clicked on "allow edits by maintainers".
• I have added documentation for new/changed functionality in this PR or in a PR to openfga.dev [Provide a link to any relevant PRs in the references section above]
• The correct base branch is being used, if not main
• I have added tests to validate that the change in functionality is working as expected

[coderabbitai]

Walkthrough

Adds documentation to the Python client README template explaining how to set default and per-request custom HTTP headers, with examples for async usage and overriding defaults via options.headers. No code or API changes.

Changes

Cohort / File(s)	Summary
Docs: Python template README config/clients/python/template/README_initializing.mustache	Added sections and examples for Default Headers and Per-Request Headers; shows set_default_header usage on the internal API client and per-request override via options.headers; includes async client examples; no functional code changes.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

Possibly related issues

• Add documentation and examples for per-request custom HTTP headers usage python-sdk#215 — Adds README documentation/examples for default and per-request custom headers, matching this PR’s additions.

Possibly related PRs

• fix(python-sdk): custom header precedence #627 — Adjusts header merge logic and tests to ensure per-request headers override defaults; directly related to the documented behavior.

Suggested reviewers

• Siddhant-K-code
• rhamzeh

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Title Check	⚠️ Warning	The title claims a new headers configuration property feature, but the pull request only adds documentation in the Python SDK README for custom header usage without modifying code or configuration APIs. Labeling it as a feat misrepresents the scope of the changeset and the conventional commit type. A docs prefix and a title referencing README guidance would be more accurate.	Update the title to accurately reflect the documentation changes, for example “docs(python-sdk): add custom headers guidance to README,” and use the docs conventional commit type instead of feat.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch docs/python/custom-headers

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}