Metadata-Version: 2.4
Name: fastapi-typed-client
Version: 0.7.0
Summary: Generate a fully-typed client for your FastAPI app with the Pydantic models from your code (mostly for testing)
Keywords: fastapi,client,testing,typed,httpx,pydantic,api-client
Author: Lukas Schmelzeisen
Author-email: Lukas Schmelzeisen <me@lschmelzeisen.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: AnyIO
Classifier: Framework :: FastAPI
Classifier: Framework :: Pydantic
Classifier: Framework :: Pydantic :: 2
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Dist: fastapi>=0.142.2
Requires-Dist: httpx2>=2.13.1
Requires-Dist: pydantic>=2.13.5
Requires-Dist: rich>=15.0.0
Requires-Dist: typer>=0.27.2
Requires-Python: >=3.14
Project-URL: source, https://github.com/lschmelzeisen/fastapi-typed-client
Project-URL: issues, https://github.com/lschmelzeisen/fastapi-typed-client/issues
Project-URL: changelog, https://github.com/lschmelzeisen/fastapi-typed-client/blob/main/CHANGELOG.md
Description-Content-Type: text/markdown

# fastapi-typed-client

[![PyPI](https://img.shields.io/pypi/v/fastapi-typed-client)](https://pypi.org/project/fastapi-typed-client/)
[![Python 3.14](https://img.shields.io/pypi/pyversions/fastapi-typed-client)](https://pypi.org/project/fastapi-typed-client/)
[![License](https://img.shields.io/pypi/l/fastapi-typed-client)](./LICENSE)

Generate a fully-typed client for your [FastAPI](https://fastapi.tiangolo.com/) app with the Pydantic models from your code.

[Quickstart](#quickstart) • [Features](#features) • [Introduction](#introduction) • [Usage](#usage) • [Development](#development)  • [License](#license) • [Changelog](./CHANGELOG.md)

## Quickstart

If you are using [uv](https://docs.astral.sh/uv/) (recommended) and your FastAPI app is importable from `module.submodule` with name `app`:

```shell
uvx fastapi-typed-client generate module.submodule:app
```

Otherwise, do this (preferably in a [virtual environment](https://fastapi.tiangolo.com/virtual-environments/)):

```shell
pip install fastapi-typed-client
fastapi-typed-client generate module.submodule:app
```

This will generate a file called `fastapi_client.py` (or if your FastAPI app has a title: `<title>_client.py`). You can then use it like this:

```python
from module.submodule import app, YourPydanticModel
from fastapi_client import FastAPIClient

with FastAPIClient.from_app(app) as client:
    print(client.your_endpoint(your_param=YourPydanticModel(foo="bar")))
```

For help on available options, see:

```shell
fastapi-typed-client generate --help
```

## Features

Generates a client for your FastAPI app that:

- Has **full type annotations** for all endpoint parameters and combinations of status codes and response models
- Detects **unexpected responses** (undeclared status codes or bodies that do not match the declared model) and raises dedicated exceptions or returns them as typed results
- Uses the **types and Pydantic models defined in your app code**
- Can be either **sync or async** (via the `--async` CLI option)
- Support for **path**, **query**, **header**, **body**, **form**, and **file parameters** (`UploadFile`/`File()`/`Form()` endpoints are sent as `multipart/form-data` or form-urlencoded; plus experimental support for **cookie parameters**)
- Support for **security schemes** (`HTTPBearer`, `HTTPBasic`, `APIKeyHeader`, `APIKeyCookie`, `APIKeyQuery`, `OAuth2PasswordBearer`, `OAuth2AuthorizationCodeBearer`, `OpenIdConnect`)
- Support for **streams of JSON objects** (experimental)
- Only depends on [Pydantic](https://pydantic.dev/), [HTTPX](https://www.python-httpx.org/), [`fastapi.encoders`](https://fastapi.tiangolo.com/reference/encoders/), and any Pydantic models that your app defines at runtime
- Generated code is **human-readable**, has **diff-friendly formatting**, **controllable import styles**, and is **designed to be checked into version control**
- Supports Python 3.14 and FastAPI >= 0.138.0 (open an [issue](https://github.com/lschmelzeisen/fastapi-typed-client/issues) if you need support for older versions)

## Introduction

The main use case of this tool is to write type-checked tests for FastAPI apps.

Let's take the following file `birthday_app.py` as an example of a simple FastAPI app:

```python
from datetime import date
from fastapi import FastAPI, HTTPException, status
from pydantic import BaseModel

class BirthdayData(BaseModel):
    name: str
    birthday: date

class GetBirthdayError(BaseModel):
    detail: str

app_db: dict[str, date] = {}  # Simple in-memory dict, just for example.
app = FastAPI(title="BirthdayApp")

@app.post("/birthday", status_code=status.HTTP_201_CREATED)
def register_birthday(data: BirthdayData) -> bool:
    app_db[data.name] = data.birthday
    return True

@app.get(
    "/birthday/{name}",
    responses={status.HTTP_404_NOT_FOUND: {"model": GetBirthdayError}},
)
def get_birthday(name: str) -> BirthdayData:
    if name not in app_db:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND, detail=f"No birthday data for {name}"
        )
    return BirthdayData(name=name, birthday=app_db[name])
```

This app allows us to store and retrieve birthday information. Note that the `register_birthday` endpoint returns a status code of `201 Created` instead of the default `200 Ok`, and that the `get_birthday` endpoint returns a JSON object of shape `BirthdayData` on success or of shape `GetBirthdayError` with a `404 Not Found` on failure.

With regular [FastAPI testing](https://fastapi.tiangolo.com/tutorial/testing/), we might test this app like so:

```python
import pytest
from birthday_app import app, app_db
from datetime import date
from fastapi.testclient import TestClient

@pytest.fixture
def client() -> TestClient:
    app_db.clear()
    return TestClient(app)

def test_register_birthday(client: TestClient) -> None:
    name = "Elvis"
    birthday = date(year=1935, month=1, day=8)

    register_response = client.post(
        "/birthday", json={"name": name, "birthday": f"{birthday:%Y-%m-%d}"}
    )
    register_response.raise_for_status()
    assert register_response.json() is True

    get_response = client.get(f"/birthday/{name}")
    get_response.raise_for_status()
    assert get_response.json() == {"name": name, "birthday": f"{birthday:%Y-%m-%d}"}

def test_unregistered_birthday(client: TestClient) -> None:
    response = client.get("/birthday/Elvis")
    assert response.status_code == 404
    assert response.json()["detail"] == "No birthday data for Elvis"
```

While this definitely tests the desired behavior of our app, this code is not ideal:

- Our tests hardcode the HTTP method and URL pattern that each endpoint expects and construct URLs with path parameters manually in multiple places.
- Our test code must be aware of how our app serializes and deserializes JSON. For example, how `birthday` is represented by FastAPI.
- Our tests need to specify what format each endpoint expects for its parameters. Path parameters need to be encoded in the URL, body parameters need to be gathered in a dict and passed to the `json` argument of `client.post`, whereas query parameters would need to be passed to the `params` argument. If we were to change the `alias` of a parameter, or if we refactor a body parameter to a query parameter, our tests would need to be updated to reflect this change.
- We use `response.raise_for_status()` to check assert that our endpoints did not return an error. However, this only checks for any `2xx` status code and silently would accept if `register_birthday` would erroneously return a `200 Ok` instead of a `201 Created`.
- There are no type-based guarantees for our test code. The type checker doesn't know what parameters are permissible to pass into an endpoint and what things they could return. For example, the type-checker can't know whether `response.json()["detail"]` is valid, nor can your IDE provide any type-based hints about it.

It's up to you whether you consider each of these points as downsides. For example, you can argue that you want your tests to duplicate such implementation details to protect against accidentally changing them. In any case, fastapi-typed-client allows us to address these concerns when desired.

First, we generate a fully-typed client for our FastAPI app with:

```shell
fastapi-typed-client generate birthday_app:app
```

This creates a file `birthday_app_client.py` (check out the [example generated client](./examples/birthday_app_client.py) if you want to see the actual generated code), which allows us to now write our tests as follows:

```python
import pytest
from birthday_app import BirthdayData, GetBirthdayError, app, app_db
from birthday_app_client import BirthdayAppClient
from collections.abc import Iterator
from datetime import date
from http import HTTPStatus
from typing import Literal, assert_type

@pytest.fixture
def client() -> Iterator[BirthdayAppClient]:
    app_db.clear()
    with BirthdayAppClient.from_app(app) as client:
        yield client

def test_register_birthday(client: BirthdayAppClient) -> None:
    name = "Elvis"
    birthday = date(year=1935, month=1, day=8)

    register_response = client.register_birthday(
        BirthdayData(name=name, birthday=birthday), raise_if_not_default_status=True
    )
    assert_type(register_response.status, Literal[HTTPStatus.CREATED])
    assert_type(register_response.data, bool)
    assert register_response.data is True

    get_response = client.get_birthday(name, raise_if_not_default_status=True)
    assert_type(get_response.status, Literal[HTTPStatus.OK])
    assert_type(get_response.data, BirthdayData)
    assert get_response.data == BirthdayData(name=name, birthday=birthday)

def test_unregistered_birthday(client: BirthdayAppClient) -> None:
    response = client.get_birthday("Elvis")
    assert response.status == HTTPStatus.NOT_FOUND
    assert_type(response.data, GetBirthdayError)
    assert response.data.detail == "No birthday data for Elvis"
```

Note that:

- We can now "call" our endpoints via simple methods like `client.register_birthday()` and `client.get_birthday()`. However, the same HTTP roundtrip and JSON serialization/deserialization as before takes place in the background.
- Our endpoints receive parameters with the _exact same_ types as we specified them in our original FastAPI app. In this case, we import `BirthdayData` from `birthday_app` and pass it to our endpoint.
- Everything is type-checked. The above code features a few `assert_type()` calls to demonstrate which types the type checker is aware of, but otherwise these are not needed. The generated client checks whether response data can be deserialized as expected, so our tests do not need to worry about this.
- Our tests do not repeat implementation details like HTTP methods and URL schemas.

### Comparison to OpenAPI client generators

Easy [client generation based on an app's OpenAPI spec](https://fastapi.tiangolo.com/advanced/generate-clients/) is one of the main advantages of FastAPI and fairly common.

The main difference between fastapi-typed-client and such tools (like [openapi-python-client](https://github.com/openapi-generators/openapi-python-client)) is that it reuses the types and Pydantic models from our application code instead of generating new ones.

This greatly simplifies writing tests, since we are aware of all the types from writing the app implementation. Additionally, it keeps diffs minimal when changing the app implementation and thus the generated clients.

## Usage

### Generating a client for a FastAPI app

To generate a new client for your FastAPI app from the command line:

```shell
fastapi-typed-client generate [OPTIONS] APP_IMPORT_STR
```

Where `APP_IMPORT_STR` is the FastAPI app import string in the format `module.submodule:app_name`. That is, your app needs to be importable as `from module.submodule import app_name`.

The following options are available (see also `fastapi-typed-client generate --help`):

- `--output-path PATH`: Path to write the generated client to. Defaults to `--title` (converted to snake_case) + `.py`.
- `--title TEXT`: Title for the class of the generated client. Defaults to the FastAPI app title (converted to UpperCamelCase) + `Client`.
- `--async`: Make generated client async.
- `--import-barrier MODULE`:  Module path(s) in format `module.submodule` to set as import barriers. Forces types in submodules to be imported through the barrier rather than directly. Can be specified multiple times.
- `--import-client-base`: Import the client base from `fastapi_typed_client.client` instead of writing it to the output file. Intended when working with multiple generated clients at once.
- `--raise-if-not-default-status`: Client methods will raise an exception by default if the respective endpoint does not return its default status code. With or without option, this can also be controlled at each method call with the `raise_if_not_default_status` parameter.  
- `--no-raise-if-unexpected-response`: Client methods will return unexpected responses (with a status code the endpoint does not declare or with a body that does not match the declared model) by default instead of raising an exception. With or without option, this can also be controlled at each method call with the `raise_if_unexpected_response` parameter.

Alternatively, for programmatic access, the function `generate_fastapi_typed_client()`, which can be imported from `fastapi_typed_client`, exposes the same functionality as the CLI command. Its parameters correspond one-to-one to the CLI options.

### Instantiating a generated client

The following assumes that your FastAPI app is available as `from fastapi_app import app` and your generated client class is named `FastAPIClient` in file `fastapi_client.py` (this may be changed using the `--output-path` and `--title` options).

To create an instance of the generated client you need to pass it an instance of a [`httpx.Client`](https://www.python-httpx.org/api/#client) (or of [`httpx.AsyncClient`](https://www.python-httpx.org/api/#asyncclient) if using `--async`) that connects to your `app`. See [FastAPI Testing](https://fastapi.tiangolo.com/tutorial/testing/) or [FastAPI Async Tests](https://fastapi.tiangolo.com/advanced/async-tests/) for how to do this. Then instantiate `FastAPIClient` like this:

```python
from fastapi_client import FastAPIClient

client = FastAPIClient(httpx_client)
# Do something with client.
```

For convenience, the classmethod `.from_app()` can be used to directly create a client for your `app`:

```python
from fastapi_app import app
from fastapi_client import FastAPIClient

with FastAPIClient.from_app(app) as client:
    pass  # Do something with client.
```

This approach uses FastAPI's [TestClient](https://fastapi.tiangolo.com/reference/testclient/) under the hood and thus triggers the [lifespan events](https://fastapi.tiangolo.com/advanced/testing-events/) of your FastAPI app. Because FastAPI does not have an async `TestClient`, this is _not_ the case if you use `--async`. Use something like [asgi-lifespan](https://github.com/florimondmanca/asgi-lifespan)'s `LifespanManager` to trigger lifespan events yourself if needed.

Note that `.from_app()` re-raises unhandled exceptions from your endpoints instead of returning a `500 Internal Server Error`. To receive a `500` instead, pass e.g. `TestClient(app, raise_server_exceptions=False)` (or `AsyncClient(transport=ASGITransport(app, raise_app_exceptions=False))` with `--async`) to the client's constructor.

### Using a generated client

The generated `FastAPIClient` will contain one generated method for each endpoint defined by your FastAPI app.

That is, for an endpoint defined as follows:

```python
@app.get("/endpoint-url/{foo}")
def endpoint(
    foo: str,  # path parameters
    bar: int,  # query parameter
    baz: BazModel,  # body parameter (with custom Pydantic model)
) -> ResponseModel:  # custom Pydantic Model for response
    ...
```

The generated client will contain a method similar to the following (plus `@overload`s that adjust the return type depending on `raise_if_not_default_status` and `raise_if_unexpected_response`):

```python
from fastapi_app import BazModel, ResponseModel
from http import HTTPStatus
from typing import Literal

class FastAPIClient:
    def endpoint(
        self,
        foo: str,
        bar: int,
        baz: BazModel,
        *,
        raise_if_not_default_status: bool = False,
        raise_if_unexpected_response: bool = True,
        client_exts: FastAPIClientExtensions | None = None
    ) -> FastAPIClientResult[Literal[HTTPStatus.OK], ResponseModel]:
        ...
```

With an [client instance](#instantiating-a-generated-client) you can then just call this as `client.endpoint(foo="foo", bar=123, baz=BazModel())`. If you are unsure about the parameters and types of your generated client, it is helpful to review the generated `fastapi_client.py`. See [auxiliary classes](#auxiliary-classes), for documentation on classes like `FastAPIClientResult` and `FastAPIClientExtensions`.

Path, query, header, and cookie parameters are sent as the strings that FastAPI parses back into the passed values: Booleans become `true`/`false`, lists become repeated query parameters or header lines, and path values are percent-encoded (except for `/`, so that `{param:path}` works). Since these locations have no representation for `None` or empty lists, passing one omits the parameter, but only if FastAPI then falls back to the same value (e.g. `None` for `param: int | None = None`). Otherwise, and for other values that cannot be sent (e.g. lists containing `None`, header or cookie values that are not printable ASCII or have surrounding whitespace, cookie values containing `;`, or path values with `.` or `..` segments), a `FastAPIClientUnencodableParamError` is raised before sending the request.

Note that FastAPI does not coerce strings into literals, so it rejects every value of a `Literal[1]` parameter in these locations, unless it coerces the value itself, e.g. via `Annotated[Literal[1], BeforeValidator(int), Header()]`.

For endpoints that can return errors (either because they define errors as [additional responses](https://fastapi.tiangolo.com/advanced/additional-responses/) or because they take parameters which can result in a Pydantic `ValidationError`) the return type of the generated endpoint method will be a union of all status codes with their respective response models.

If you set the `raise_if_not_default_status` parameter to `True` or use `--raise-if-not-default-status` when generating your client, the return type will just be the default status code (i.e., `200 Ok` or the one defined via `status_code` in the endpoint's decorator) with its response model. Should the endpoint return a different status code, a `FastAPIClientNotDefaultStatusError` will be raised, which contains the response status code and deserialized data.

Responses that don't match the endpoint's declaration are _unexpected_: a status code the endpoint does not declare (e.g. a `500 Internal Server Error`, or a status from a middleware or reverse proxy), or a declared status code whose body does not validate against its model. By default, these raise `FastAPIClientUnexpectedStatusError` or `FastAPIClientUnexpectedBodyError`, respectively (never `FastAPIClientNotDefaultStatusError`).

If you set the `raise_if_unexpected_response` parameter to `False` or use `--no-raise-if-unexpected-response`, unexpected responses are instead returned as `FastAPIClientUnexpectedStatus` or `FastAPIClientUnexpectedBody` and added to the method's return type. Since these can carry any status, comparing `result.status` no longer narrows `result.data`, so exclude them via `isinstance()` first:

```python
from fastapi_app import BazModel, ResponseModel
from fastapi_client import FastAPIClientUnexpectedResponse
from http import HTTPStatus
from typing import assert_type

result = client.endpoint(
    foo="foo", bar=123, baz=BazModel(), raise_if_unexpected_response=False
)
if isinstance(result, FastAPIClientUnexpectedResponse):
    print(result.response.status_code, result.data)  # data is the body parsed as JSON.
elif result.status == HTTPStatus.OK:
    assert_type(result.data, ResponseModel)
```

To type responses your app produces outside of routes (e.g. a middleware answering `400` with a problem-details body), declare them via `FastAPI(responses={400: {"model": Problem}})` or `APIRouter(responses=...)`. FastAPI merges these into every route's responses.

There is experimental support for streaming endpoints. The following patterns are detected automatically from FastAPI's route metadata, and the streaming type is only applied to the default response of an endpoint (additional responses still produce regular `data` for their respective status codes):

- **JSON Lines** ([FastAPI docs](https://fastapi.tiangolo.com/tutorial/stream-json-lines/)). Endpoints declared as `-> Iterable[T]` / `-> AsyncIterable[T]` (without an explicit `response_class`), or the older custom-subclass-of-`StreamingResponse`-and-`JSONResponse` pattern. The generated method returns `Iterator[T]` (or `AsyncIterator[T]` for async clients):

  ```python
  for item in client.your_endpoint().data:
      print(item.field)
  ```

- **Server-Sent Events** ([FastAPI docs](https://fastapi.tiangolo.com/tutorial/server-sent-events/)). Endpoints with `response_class=EventSourceResponse`. The generated method returns `Iterator[FastAPIClientSSE[T]]` (or async equivalent), exposing the `data` (parsed as `T`), `event`, `id`, `retry`, and `comment` fields of each SSE event:

  ```python
  for event in client.your_endpoint().data:
      print(event.event, event.id, event.data)
  ```

- **Raw bytes/string streaming** ([FastAPI docs](https://fastapi.tiangolo.com/advanced/stream-data/)). Endpoints with `response_class=StreamingResponse` and a return annotation of `Iterable[bytes]` / `AsyncIterable[bytes]` (or `str`). The generated method returns `Iterator[bytes]` / `Iterator[str]` (or async equivalents) yielding chunks unmodified:

  ```python
  for chunk in client.your_endpoint().data:
      handle(chunk)
  ```

Items of JSON Lines streams and the `data` of SSE events are validated against the declared model while iterating. By default, an item that does not validate (or is not valid JSON) raises a `FastAPIClientUnexpectedStreamItemError` during iteration (i.e., after the endpoint method has returned) and closes the stream. With `raise_if_unexpected_response=False`, such items are instead yielded as `FastAPIClientUnexpectedStreamItem` (for SSE, as the `data` of the respective `FastAPIClientSSE`, keeping the event's other fields) and iteration continues, so the item types become `T | FastAPIClientUnexpectedStreamItem`. Raw bytes/string streams are not validated. Streaming endpoints that return a status code other than the default are read fully and behave like non-streaming endpoints.

See the corresponding tests for end-to-end examples ([test_streaming_json_response.py](./tests/test_core/test_streaming_json_response.py), [test_stream_json_lines.py](./tests/test_core/test_stream_json_lines.py), [test_stream_sse.py](./tests/test_core/test_stream_sse.py), [test_stream_raw.py](./tests/test_core/test_stream_raw.py)).

### Auxiliary classes

The following auxiliary classes are either included in the generated `fastapi_client.py` file or imported from `fastapi_typed_client.client` if using `--import-client-base`.

#### `FastAPIClientResult[Status: http.HTTPStatus, Model]`
  
Parameterized type that is returned by each endpoint method. The generic parameters `Status` and `Model` specify status code and response model of each endpoint in the type system. Endpoint's with [additional responses](https://fastapi.tiangolo.com/advanced/additional-responses/) return a union of specializations of this type. 

Instance attributes:

- `status: Status`: The [`http.HTTPStatus`](https://docs.python.org/3/library/http.html#http.HTTPStatus) of the response
- `data: Model`: The deserialized response data
- `model: type[Model]`: The type used to deserialize the response data
- `response: Response`: The raw `httpx.Response` object

#### `FastAPIClientUnexpectedStatus`, `FastAPIClientUnexpectedBody`, and `FastAPIClientUnexpectedStreamItem`

Returned (or yielded, for stream items) instead of raised when using `raise_if_unexpected_response=False` or `--no-raise-if-unexpected-response`. `FastAPIClientUnexpectedResponse` is the union of all three and can be used with `isinstance()`.

`FastAPIClientUnexpectedStatus` (status code the endpoint does not declare) instance attributes:

- `status: HTTPStatus | None`: The [`http.HTTPStatus`](https://docs.python.org/3/library/http.html#http.HTTPStatus) of the response (or `None` for non-standard status codes like `499` or `520`, see `response.status_code` for the raw code)
- `data: JsonValue`: The response body parsed as JSON (or `None` if empty or not valid JSON)
- `response: Response`: The raw `httpx.Response` object

`FastAPIClientUnexpectedBody` (declared status code with a body that does not validate) instance attributes:

- `status: HTTPStatus`: The [`http.HTTPStatus`](https://docs.python.org/3/library/http.html#http.HTTPStatus) of the response
- `data: JsonValue`: The response body parsed as JSON (or `None` if empty or not valid JSON)
- `model: type[Any]`: The declared model the response body failed to validate against
- `validation_error: ValidationError`: The Pydantic `ValidationError` raised during validation
- `response: Response`: The raw `httpx.Response` object

`FastAPIClientUnexpectedStreamItem` (JSON Lines item or SSE `data` that does not validate; for SSE, yielded as `data` of a `FastAPIClientSSE`) instance attributes:

- `data: JsonValue`: The stream item parsed as JSON (or `None` if not valid JSON)
- `raw: str`: The raw JSON line or SSE `data` of the stream item
- `model: type[Any]`: The declared model the stream item failed to validate against
- `validation_error: ValidationError`: The Pydantic `ValidationError` raised during validation

#### `FastAPIClientError`

Base class of all exceptions raised by generated clients, i.e., of `FastAPIClientNotDefaultStatusError`, `FastAPIClientUnexpectedResponseError`, `FastAPIClientUnencodableParamError`, and `FastAPIClientConflictingParamError`.

#### `FastAPIClientNotDefaultStatusError`
  
Exception raised when using `raise_if_not_default_status=True` or `--raise-if-not-default-status` and an endpoint returns a declared but non-default status code.

Instance attributes:

- `default_status: HTTPStatus`: The expected status code
- `result: FastAPIClientResult`: The actual result received

#### `FastAPIClientUnexpectedResponseError`

Exception raised when using `raise_if_unexpected_response=True` (the default) and an endpoint returns an unexpected response. Specifically, one of its subclasses is raised: `FastAPIClientUnexpectedStatusError`, `FastAPIClientUnexpectedBodyError` (chained from the Pydantic `ValidationError`), or `FastAPIClientUnexpectedStreamItemError` (chained from the Pydantic `ValidationError`, raised while iterating over a stream).

Instance attributes:

- `result: FastAPIClientUnexpectedResponse`: The unexpected response received (typed as `FastAPIClientUnexpectedStatus`, `FastAPIClientUnexpectedBody`, or `FastAPIClientUnexpectedStreamItem` on the respective subclass)

#### `FastAPIClientUnencodableParamError`

Exception raised before sending a request if a path, query, header, cookie, or security parameter has a value that cannot be sent such that FastAPI parses it back into the same value (see [using a generated client](#using-a-generated-client)). Also subclasses `ValueError`. Its message never includes the value, since it might be a secret.

Instance attributes:

- `location: Literal["path", "query", "header", "cookie"]`: Where the parameter is sent
- `name: str`: The name of the parameter on the wire (i.e., its alias, if any)
- `value: Any`: The value that cannot be sent

#### `FastAPIClientConflictingParamError`

Exception raised before sending a request if a security parameter and another parameter would both be sent as the same header (case-insensitively), cookie, or query parameter. Also subclasses `ValueError`.

Instance attributes:

- `location: Literal["query", "header", "cookie"]`: Where the parameters are sent
- `name: str`: The name of the parameters on the wire

#### `FastAPIClientHTTPValidationError` and `FastAPIClientValidationError`
  
Pydantic models for deserializing `422 Unprocessable Entity` responses from your FastAPI app.

Instance attributes of `FastAPIClientHTTPValidationError`:

- `detail: Sequence[FastAPIClientValidationError]`: List of validation errors

Instance attributes of `FastAPIClientValidationError`:

- `loc: Sequence[str | int]`: Location of the error
- `msg: str`: Error message
- `type: str`: Error type

#### `FastAPIClientSSE[Data]`

Generic Pydantic model returned by streaming SSE endpoint methods. Subclasses [`fastapi.sse.ServerSentEvent`](https://fastapi.tiangolo.com/tutorial/server-sent-events/) and overrides the `data` field with the endpoint-specific type.

Instance attributes:

- `data: Data | None`: The deserialized event payload (or `None` for events that only carry metadata such as comments)
- `event: str | None`: Optional event type name
- `id: str | None`: Optional event id
- `retry: int | None`: Optional reconnection time in milliseconds
- `comment: str | None`: Optional comment line(s)
- `raw_data: str | None`: Pre-formatted, non-JSON `data:` payload (mutually exclusive with `data`)

#### `FastAPIClientExtensions`
  
TypedDict for passing additional options via the `client_exts` parameter to each endpoint. Currently only supports the following field:

- `timeout: float | tuple[float | None, float | None, float | None, float | None] | httpx.Timeout | None`: Request timeout, directly passed to [`httpx.Client.request`](https://www.python-httpx.org/api/#client)

### Current limitations

The following FastAPI features are not yet supported:

- [WebSockets](https://fastapi.tiangolo.com/advanced/websockets/) endpoints
- Endpoints that can be reached via more than one HTTP method
- Endpoints with duplicate parameter names (e.g., a query and a header parameter with the same name)
- Endpoints using any of `response_model_include`, `response_model_exclude`, `response_model_by_alias`, `response_model_exclude_unset`, `response_model_exclude_defaults`, or `response_model_exclude_none`
- Endpoints with `FileResponse`, `HTMLResponse`, `PlainTextResponse`, `RedirectResponse` or a custom response class
- The `HTTPDigest` security scheme (challenge-response flow, not reducible to a static header)
- Path parameter values that are empty or contain `/` (except for `{param:path}` parameters), since they change which route is matched

## Development

Contributions welcome! Feel free to create [issues](https://github.com/lschmelzeisen/fastapi-typed-client/issues) and [pull requests](https://github.com/lschmelzeisen/fastapi-typed-client/pulls).

There is a `Makefile` with helpers for how to run the development tools ([uv](https://docs.astral.sh/uv/), [Ruff](https://docs.astral.sh/ruff/), [Pyrefly](https://pyrefly.org/), [pytest](https://docs.pytest.org)). Run `make help` for an overview of available commands.

## License

Licensed under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0).