Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
151 changes: 151 additions & 0 deletions .github/workflows/build-wheels.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,151 @@
name: Build distributions

on:
workflow_call:
inputs:
check-version-tag:
type: boolean
default: false

permissions:
contents: read
actions: read

jobs:
sdist:
runs-on: ubuntu-latest
outputs:
filename: ${{ steps.sdist.outputs.filename }}
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
with:
enable-cache: false
- name: Check that the tag matches the version
if: inputs.check-version-tag
run: test "${GITHUB_REF_NAME#v}" = "$(uv version --short)"
- name: Build the source distribution
run: uv build --sdist --out-dir dist
- name: Check the source distribution
run: uvx twine@7.0.0 check --strict dist/*.tar.gz
- name: Record the source distribution filename
id: sdist
shell: bash
run: |
files=(dist/*.tar.gz)
test "${#files[@]}" -eq 1
test -f "${files[0]}"
echo "filename=${files[0]#dist/}" >> "$GITHUB_OUTPUT"
- uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
with:
name: dist-sdist
path: dist/*.tar.gz
if-no-files-found: error

wheels:
needs: sdist
name: Wheels (${{ matrix.id }})
runs-on: ${{ matrix.os }}
strategy:
fail-fast: false
matrix:
include:
- id: linux-x86_64
os: ubuntu-latest
platform: linux
arch: x86_64
- id: linux-aarch64
os: ubuntu-24.04-arm
platform: linux
arch: aarch64
- id: macos-x86_64
os: macos-15-intel
platform: macos
arch: x86_64
- id: macos-arm64
os: macos-latest
platform: macos
arch: arm64
- id: windows-amd64
os: windows-latest
platform: windows
arch: AMD64
- id: windows-arm64
os: windows-11-arm
platform: windows
arch: ARM64
env:
CIBW_ARCHS: ${{ matrix.arch }}
CIBW_PLATFORM: ${{ matrix.platform }}
PACKAGE_DIR: dist/${{ needs.sdist.outputs.filename }}
steps:
- uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
with:
name: dist-sdist
path: dist/
- uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
with:
enable-cache: false
# The CLI avoids the composite action's unpinned nested actions.
- name: Build and test wheels
if: runner.os != 'Windows'
run: uvx --from cibuildwheel==4.2.0 cibuildwheel --output-dir wheelhouse "$PACKAGE_DIR"
- name: Build and test wheels (Windows)
if: runner.os == 'Windows'
run: uvx --from cibuildwheel==4.2.0 cibuildwheel --output-dir wheelhouse "$env:PACKAGE_DIR"
- uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
with:
name: dist-wheels-${{ matrix.id }}
path: wheelhouse/*.whl
if-no-files-found: error

verify:
needs: [sdist, wheels]
runs-on: ubuntu-latest
steps:
- uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
with:
pattern: dist-*
merge-multiple: true
path: dist/
- uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
with:
enable-cache: false
- name: Check the distributions
run: uvx twine@7.0.0 check --strict dist/*
- name: Check native wheel coverage
shell: python
run: |
from pathlib import Path
import zipfile

assert len(list(Path("dist").glob("*.tar.gz"))) == 1
wheels = list(Path("dist").glob("*.whl"))
assert wheels, "No wheels were built"
expected = {
("manylinux", "x86_64"), ("manylinux", "aarch64"),
("musllinux", "x86_64"), ("musllinux", "aarch64"),
("macosx", "x86_64"), ("macosx", "arm64"),
("win", "amd64"), ("win", "arm64"),
}
found = set()
for wheel in wheels:
_, python, abi, platforms = wheel.stem.rsplit("-", 3)
assert (python, abi) == ("cp311", "abi3"), wheel.name
with zipfile.ZipFile(wheel) as archive:
names = archive.namelist()
metadata = [name for name in names if name.endswith(".dist-info/WHEEL")]
assert len(metadata) == 1, wheel.name
assert b"Root-Is-Purelib: false" in archive.read(metadata[0]), wheel.name
assert any(
name.startswith("msgspec_fastapi/_defaults.")
and name.endswith((".so", ".pyd"))
for name in names
), wheel.name
for platform in platforms.split("."):
for family, arch in expected:
if platform.startswith(family + "_") and platform.endswith("_" + arch):
found.add((family, arch))
assert found == expected, f"Missing wheel platforms: {expected - found}"
32 changes: 20 additions & 12 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,22 @@ jobs:
- name: Check formatting
run: uv run --no-sync ruff format --check .

typing:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
with:
enable-cache: false
- name: Install typing tools
run: uv sync --python 3.13 --group typing
- name: Check source types
run: uv run --no-sync mypy src/msgspec_fastapi --follow-imports=silent
- name: Check the native interface stubs
run: uv run --no-sync python -m mypy.stubtest msgspec_fastapi._defaults --concise

test:
name: Python ${{ matrix.python }}, ${{ matrix.bounds }} dependency bounds
runs-on: ubuntu-latest
Expand Down Expand Up @@ -62,15 +78,7 @@ jobs:
run: uv run --no-sync pytest

build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
with:
enable-cache: false
- name: Build
run: uv build
- name: Check the distributions
run: uvx twine@7.0.0 check --strict dist/*
permissions:
contents: read
actions: read
uses: ./.github/workflows/build-wheels.yml
28 changes: 9 additions & 19 deletions .github/workflows/publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -10,24 +10,12 @@ permissions:

jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
with:
persist-credentials: false
- uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
with:
enable-cache: false
- name: Check that the tag matches the version
run: test "${GITHUB_REF_NAME#v}" = "$(uv version --short)"
- name: Run tests
run: uv run --python 3.13 --group test pytest
- name: Build
run: uv build
- uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
with:
name: dist
path: dist/
permissions:
contents: read
actions: read
uses: ./.github/workflows/build-wheels.yml
with:
check-version-tag: true

publish:
needs: build
Expand All @@ -37,9 +25,11 @@ jobs:
url: https://pypi.org/project/msgspec-fastapi/
permissions:
id-token: write
actions: read
steps:
- uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
with:
name: dist
pattern: dist-*
merge-multiple: true
path: dist/
- uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -5,4 +5,8 @@ __pycache__/
.ruff_cache/
.mypy_cache/
dist/
build/
*.egg-info/
*.so
*.pyd
uv.lock
4 changes: 4 additions & 0 deletions MANIFEST.in
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
include LICENSE README.md pyproject.toml setup.py MANIFEST.in
recursive-include src/msgspec_fastapi *.py *.pyi *.c py.typed
recursive-include docs *.svg
recursive-include tests *.py
68 changes: 58 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,9 @@ not part of msgspec; feedback is welcome in the issues.
pip install msgspec-fastapi
```

The package includes an internal C extension for checking copied defaults and
metadata. Building from source requires a C11 compiler and CPython headers.

## Usage

```python
Expand Down Expand Up @@ -120,6 +123,9 @@ Things to keep in mind:

## What it does

The package uses msgspec for its JSON validation and encoding, without calling Pydantic
validators or serializers. FastAPI still depends on Pydantic for its own internals.

- A msgspec body parameter (a Struct or another type msgspec can decode) is decoded from
the raw request bytes by a `msgspec.json.Decoder` built once at route registration. A
body with a non-JSON content type returns 415, malformed JSON or JSON nested too deeply
Expand All @@ -138,49 +144,91 @@ Things to keep in mind:
instance are not checked. A NaN or infinite value in a `float` field is encoded as
`null` unless a constraint rejects it. In a `Decimal` field it is encoded as a string,
while FastAPI with Pydantic rejects non-finite `Decimal` values.
- Responses of routes without a return annotation or `response_model`, or with
`-> None`, are also encoded with msgspec, so the output can differ from FastAPI's
`jsonable_encoder` (for example, `bytes` are base64-encoded and `Decimal` is encoded as
a string).
- With the default `MsgspecJSONResponse`, responses of routes without a return
annotation or `response_model`, or with `-> None`, are also encoded with msgspec.
In addition to msgspec's built-in types, `pathlib` paths and standard-library IP
addresses, interfaces and networks are encoded as strings. Other objects, including
`BaseModel` instances, `HttpUrl` and `SecretStr`, are unsupported and raise `TypeError`
during encoding. Values supported directly by msgspec retain its encoding: for example,
`bytes` are base64-encoded and `Decimal` is encoded as a string.
- Path, query, header and cookie parameters keep FastAPI extraction, aliases and
defaults, but are converted with `msgspec.convert(strict=False)` instead of Pydantic,
so coercion differs for some inputs (for example, `" 1.5"` is rejected for `float`
and `"nan"` is accepted for `Decimal`). Parameter types must be supported by msgspec;
Pydantic-specific types such as `AnyUrl` raise `TypeError` at route registration.
- On the msgspec validation path, string `pattern` constraints from FastAPI parameters,
`Body` and supported nested `Field` annotations use Rust's `regex` engine through
`regexrs-py`, without catastrophic backtracking. Patterns are compiled once at route
registration. Compiled Python `re.Pattern` objects are rejected rather than falling
back to a backtracking engine.
Native `msgspec.Meta(pattern=...)` constraints retain msgspec's Python regex behavior
and are outside this protection.
- Generator endpoints support JSON Lines with the default response class and SSE with
`response_class=EventSourceResponse`. Plain yielded items with declared msgspec
types are validated with the same instance-trust rules as ordinary responses. Untyped
yielded values are also encoded with msgspec. Explicit instances of the exact
`ServerSentEvent` class support preformatted `raw_data` and metadata-only events;
subclasses are unsupported. A non-`None` `data` payload without
`raw_data` is rejected. For a Struct or Raw payload with event metadata, use
`ServerSentEvent(raw_data=msgspec.json.encode(payload).decode('utf-8'), id='...')`.
Explicit `StreamingResponse` keeps raw chunks. Streaming bodies retain dependency
validation and generator cleanup.
- Custom response classes are supported. Typed response validation and field projection
happen before response construction. A `JSONResponse` class that does not inherit
`MsgspecJSONResponse` receives JSON-compatible values converted with msgspec, including
for untyped returns. Returned `Response` instances pass through unchanged.
- Structural JSON body errors include field names, encoded aliases, keys and indices,
with multiple errors for supported Structs, regular dataclasses, TypedDicts and
built-in containers. Diagnostics never repeat model validation hooks or default
factories: types with hooks or unsupported diagnostic shapes retain the original
first error. The default 422 handler encodes error details with msgspec; custom
application exception handlers are preserved. Error details added by dependencies must
also be encodable by this encoder or handled by a custom exception handler.
- `install_openapi(app)` adds the msgspec JSON schemas to the OpenAPI document. Call it
once before serving. Routes, webhooks and callbacks are discovered from the application
when the document is built; the optional router arguments remain accepted for
compatibility. Hidden routes do not add msgspec components. As in FastAPI, the document
is cached: set `app.openapi_schema = None` to rebuild it after adding routes.
- Body descriptions and examples, `openapi_extra` request metadata and response examples
are preserved. JSON body routes document their 400, 415 and 422 responses.
- A Pydantic body or response model is left to FastAPI; the route parameters are still
validated with msgspec.
- JSON body and response types must be supported by msgspec. Pydantic models and
custom Pydantic types are rejected at route registration. Pydantic data objects are
also rejected before implicit copies of defaults and route metadata.

## Limitations

- Only one msgspec body parameter per route, and it cannot be combined with other
FastAPI body fields. Only JSON bodies are supported: `application/json`,
`application/*+json`, or a request without a content type when `strict_content_type`
is `False`. `Form()` and `File()` parameters are left to FastAPI.
- When both the parameters and the body are invalid, only the parameter errors are
returned; FastAPI returns both.
is `False`. JSON body parameters in `Depends` functions are not supported; declare
the JSON body on the route endpoint. `Form()` and `File()` parameters are left to FastAPI.
- On ordinary non-streaming routes, when both the parameters and body are invalid, only
the parameter errors are returned; FastAPI returns both.
- Structs, alone or inside containers, are not supported as path, query, header or
cookie parameters, or as `Form()` and `File()` parameters.
- Defaults and copied metadata do not support container subclasses, custom state/reduction
methods, registered copy reducers, dynamic attribute access or custom copy descriptors.
Ordinary application-defined Python `__deepcopy__` methods and default factories remain
application code.
- `response_model_include`, `response_model_exclude`, `response_model_exclude_*` and
`response_model_by_alias=False` are rejected for typed msgspec responses.

## Development

```sh
uv sync --group test --group lint
uv sync --group test --group lint --group typing
uv run --group test pytest
uv run --group lint ruff check .
uv run --group lint ruff format --check .
uv run --group typing mypy src/msgspec_fastapi --follow-imports=silent
uv run --group typing python -m mypy.stubtest msgspec_fastapi._defaults
uv run --group lint pre-commit install
uv run --group lint pre-commit run --all-files
```

After changing C sources, rebuild the extension with
`uv sync --reinstall-package msgspec-fastapi --group test --group lint --group typing`.

Ruff checks imports, annotations and common Python errors, and formats the code.
CI runs the same Ruff version as the pre-commit hooks. Test endpoints that exercise the absence
of a response annotation intentionally omit it.
Loading
Loading