GraphQLClient support

• A method for building GraphQL integrations has been introduced.
• It follows the "Clientele" pattern of the standard APIClient.

Query example:

@client.query('''
    query($owner: String!, $name: String!) {
        repository(owner: $owner, name: $name) {
            name
            stargazerCount
        }
    }
''')
def get_repo(owner: str, name: str, result: RepositoryData) -> Repository:
    return result.repository

Mutation example:

@client.mutation('''
    mutation($title: String!) {
        createIssue(input: {title: $title}) {
            issue { id title }
        }
    }
''')
def create_issue(title: str, result: IssueData) -> Issue:
    return result.createIssue.issue

• Dropped scaffold-api command
• Dropped generate-basic command
• Drop httpx_client from APIClient
• Drop httpx_async_client from APIClient

This release includes testing tools to make API integration testing easier.

ResponseFactory

• Added ResponseFactory to clientele.testing for quick response fixtures.
• Create common HTTP responses easily: ok(), created(), not_found(), bad_request(), internal_server_error(), and more.

NetworkErrorFactory

• Added NetworkErrorFactory factory to clientele.testing for simulating network-level failures.
• Simulate common network errors like timeout(), connection_refused(), connection_reset(), and dns_failure().
• FakeHTTPBackend now supports queue_error() to queue errors for specific paths.

• Fix streaming responses to truly yield instead of consuming the full response.
• Introduces new http_backend methods for handling streaming however the backend chooses.

Retry support

• Built-in retries.retry decorator for handling retry logic.
• This is built on top of stamina - a popular and reliable retry package.
• The retry logic is customised to suit Clientele's exception handling.

from clientele import api, retries

client = api.APIClient(api.BaseConfig(base_url="https://httpbin.org/"))

@retries.retry(attempts=3)
@client.get("/status/{status_code}")
def get_status(status_code: int, result: dict) -> dict:
    return result

Improved testing

• We have drastically improved the testing support for Clientele.
• The FakeHTTPBackend is now designed for testing.
• The queue_response method now takes a http.Response object as well as the path.
• The new configure_client_for_testing function accepts an existing client and then returns it with a new testing backend.

from clientele.testing import configure_client_for_testing
from clientele import http
from my_api_client import client, my_function

def my_test():
    # Swap normal backend for a Fake HTTP backend
    fake_backend: http.FakeHTTPBackend = configure_client_for_testing(my_api_client.client)

    # Configure HTTP responses
    fake_backend.queue_response(
        path="/users",
        response_obj=Response(
            status_code=201,
            content=b'{"id": 10, "name": "Bob"}',
            headers={"content-type": "application/json"},
        ),
    )

    # Call function as normal, but it now calls the fake backend
    response = my_function()

Dropped explore command

• While it is a cool feature, it distracts from the purpose of Clientele, so it is being removed.

• Add configure method to APIClient - enabling reconfiguration of clients. Thank you Christian Assing for the contribution.

Request Logging

• Added optional request/response logging to APIClient via the logger parameter in BaseConfig. Logs include method, URL, status code, and elapsed time in seconds.
• Uses a Logger Protocol with @runtime_checkable for flexibility.

CLI commands update

• A new command start-api has been introduced.
• The new command will replace scaffold-api and generate-basic in 2.0.0
• Currently it behaves as an alias for both.
• If not url or file is provided, will call generate-basic, otherwise it calls scaffold-api.

Start a basic client with one command:

uvx clientele start-api -o /path/to/my_client

• Dropped the generate and generate-class commands from the CLI.

• Support for OpenAPI discriminated unions (oneOf + discriminator). Schemas with discriminators now generate proper Pydantic discriminated unions using typing.Annotated[..., pydantic.Field(discriminator="...")].
• scaffold-api now adds mypy configuration to the pyproject.toml that is produced with a scaffolded client.

HTTP Backends

• Clientele now supports configurable HTTP backends.
• If you want to use aiohttp, reqwests or niquests you can write an HTTPBackend so Clientele can support it.
• Clientele ships with a default HttpxHTTPBackend that will be used if no other is configured.
• Introduces a new clientele.http.Response wrapper for generic handling of responses.
• The response_parser callbacks now take the generic clientele.http.Response instead of httpx.Response.
• Introduces a new FakeHTTPBackend that can be used for testing.

Direct requests

• An optional approach for making requests with Clientele is now available.
• This approach does not enforce the decorator pattern.
• But still offers smart data hydration and response mapping.
• Support for both async and sync.

• cache_backend can now be set in the BaseConfig, and will be used if it is not None. This saves you having to annotate the cache backend repeatedly in decorators.