starlette-request-id
Request-ID context and response propagation middleware for Starlette applications.
Requirements
- Python 3.11+ (CI validates 3.11, 3.12, 3.13, and 3.14)
- Starlette >1.2.0 and <2.0.0
Install
uv add starlette-request-id
pip install starlette-request-id
Basic usage
from starlette.applications import Starlette
from starlette_request_id import RequestIdMiddleware
app = Starlette()
app.add_middleware(RequestIdMiddleware)
RequestIdMiddleware reads x-request-id, creates a UUID4 ID if it is absent,
exposes it through request_id_ctx, and writes the active value to the response
header. See examples/basic_usage.py for logging and outbound-header
propagation.
Examples
Run the standalone example:
uv run --with uvicorn examples/basic_usage.py
Run the dedicated Uvicorn example:
uv run --with 'uvicorn[standard]' uvicorn examples.uvicorn_runner:app --reload
Run the Gunicorn example with Uvicorn workers:
uv run --with gunicorn --with uvicorn gunicorn -c examples/gunicorn_conf.py examples.gunicorn_runner:app
Then send a request with a chosen ID:
curl -H 'x-request-id: example-id' http://127.0.0.1:8000/
Starlette 1.3 uses app.add_route(path, endpoint) to register handlers; the
examples follow that API.
Configuration
app.add_middleware(
RequestIdMiddleware,
id_header="x-correlation-id",
get_default_id_func=lambda: "generated-id",
)
A supplied value is preserved exactly; the generator is called only when the header is absent.
Logging
from starlette_request_id import init_logger, request_id_ctx
These exports are the shared APIs from request-id-helper, so applications
that import request_id_ctx directly from request_id_helper observe the same
request value.
Error responses and middleware order
The middleware adds the header to response starts emitted by the application
and its inner exception handlers. It does not render exceptions. If an outer
error middleware constructs a response after an exception escapes
RequestIdMiddleware, put that error middleware inside RequestIdMiddleware
or make it write the request-ID header itself.
Migrating from 1.x
2.0.0 drops Python 3.8–3.10 and replaces the internal BaseHTTPMiddleware
implementation with pure ASGI middleware. Existing imports of
RequestIdMiddleware, REQUEST_ID_HEADER, request_id_ctx, init_logger,
and LogExtraFactory continue to work. Update deployment environments to
Python 3.11+, use Starlette's add_route() API, and retain request-id-helper
as the shared logging/context provider.
Development
uv sync --all-groups
make lint
make test
make build
License
starlette-request-id is distributed under the Apache License 2.0.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file starlette_request_id-2.0.0.tar.gz.
File metadata
- Download URL: starlette_request_id-2.0.0.tar.gz
- Upload date:
- Size: 47.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
7a7d8856a77f2c73fdf7feaace1985db5ef397ca7ba6d8bb54cc9f5336c03f63
|
|
| MD5 |
bb086181387f70539cb31a0a1869554c
|
|
| BLAKE2b-256 |
eb8c4ab9e80f9e71f3ddd869ca85aad9b8b34f722d79b0d64889662d9c3563ff
|
Provenance
The following attestation bundles were made for starlette_request_id-2.0.0.tar.gz:
Publisher:
publish.yml on bigbag/starlette-request-id
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
starlette_request_id-2.0.0.tar.gz -
Subject digest:
7a7d8856a77f2c73fdf7feaace1985db5ef397ca7ba6d8bb54cc9f5336c03f63 - Sigstore transparency entry: 2206812551
- Sigstore integration time:
-
Permalink:
bigbag/starlette-request-id@d7623d39353407818702c7c842dade5a656c2dba -
Branch / Tag:
refs/tags/v2.0.0 - Owner: https://github.com/bigbag
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@d7623d39353407818702c7c842dade5a656c2dba -
Trigger Event:
push
-
Statement type:
File details
Details for the file starlette_request_id-2.0.0-py3-none-any.whl.
File metadata
- Download URL: starlette_request_id-2.0.0-py3-none-any.whl
- Upload date:
- Size: 8.1 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
a3870603280d40995f95112a3088579951553ffbf3eba7984df250a4f8c116bc
|
|
| MD5 |
99c233c585f4f46144bc53046ffc8b12
|
|
| BLAKE2b-256 |
868c26999c59b4432d74afce828f2dcad1a26992a987e4f1d1f7dbfa372f3e70
|
Provenance
The following attestation bundles were made for starlette_request_id-2.0.0-py3-none-any.whl:
Publisher:
publish.yml on bigbag/starlette-request-id
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
starlette_request_id-2.0.0-py3-none-any.whl -
Subject digest:
a3870603280d40995f95112a3088579951553ffbf3eba7984df250a4f8c116bc - Sigstore transparency entry: 2206812562
- Sigstore integration time:
-
Permalink:
bigbag/starlette-request-id@d7623d39353407818702c7c842dade5a656c2dba -
Branch / Tag:
refs/tags/v2.0.0 - Owner: https://github.com/bigbag
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@d7623d39353407818702c7c842dade5a656c2dba -
Trigger Event:
push
-
Statement type:
