# FastAPI Request ID
A FastAPI middleware for request ID propagation and tracing across microservices.
## Quick Start
### 1. Add Middleware
```python
from fastapi import FastAPI
from fastapi_reqid import RequestIDMiddleware
app = FastAPI()
# Add middleware with default settings
app.add_middleware(RequestIDMiddleware)
# Or customize it
app.add_middleware(
RequestIDMiddleware,
header_name="X-Correlation-ID", # Custom header name
generator=lambda: str(uuid.uuid4()) # Custom ID generator
)
```
### 2. Access Request ID
```python
from fastapi import Request
from fastapi_reqid import get_request_id
@app.get("/")
async def root(request: Request):
# Access via request.state
request_id = request.state.request_id
# Or use the context helper
request_id = get_request_id()
return {"request_id": request_id}
```
## HTTP Client Decorators
Automatically inject request IDs into outgoing HTTP requests.
### httpx
```python
from fastapi import Request
from fastapi_reqid import inject_httpx_requestid
@app.get("/external")
@inject_httpx_requestid
async def call_external(request: Request):
client = request.state.httpx_client
response = await client.get("https://api.example.com")
return response.json()
```
### aiohttp
```python
from fastapi import Request
from fastapi_reqid import inject_aiohttp_requestid
@app.get("/external")
@inject_aiohttp_requestid
async def call_external(request: Request):
session = request.state.aiohttp_session
async with session.get("https://api.example.com") as resp:
return await resp.json()
```
### requests
```python
from fastapi import Request
from fastapi_reqid import inject_requests_requestid
@app.get("/external")
@inject_requests_requestid
def call_external(request: Request):
session = request.state.requests_session
response = session.get("https://api.example.com")
return response.json()
```
## Manual Request ID Management
Use these functions to manually get or set request IDs:
```python
from fastapi_reqid import get_request_id, set_request_id, request_id_context
# Get current request ID
request_id = get_request_id()
# Set request ID manually
token = set_request_id("custom-request-id")
try:
# Do work with this request ID
pass
finally:
# Reset to previous value
request_id_context.reset(token)
```
## Building and Publishing
### Building the Library
This project uses [uv](https://github.com/astral-sh/uv) for building. To build the distribution packages:
```bash
# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh
# Build the package (creates wheel and source distribution)
uv build
```
This will create two files in the `dist/` directory:
- `fastapi_reqid-{version}-py3-none-any.whl` - Python wheel
- `fastapi_reqid-{version}.tar.gz` - Source distribution
### Publishing to PyPI
#### Test on TestPyPI First (Recommended)
Before publishing to the main PyPI, test your package on TestPyPI:
```bash
# Publish to TestPyPI
uv publish --publish-url https://test.pypi.org/legacy/
```
You'll need a TestPyPI account and API token from [test.pypi.org](https://test.pypi.org).
#### Publish to PyPI
Once you've verified the package works correctly:
```bash
# Publish to PyPI
uv publish
```
You'll need a PyPI account and API token from [pypi.org](https://pypi.org).
### Development Setup
To set up a development environment:
```bash
# Create virtual environment
uv venv
# Install package in editable mode with dev dependencies
uv pip install -e ".[dev]"
# Run tests
pytest
```
## How It Works
1. The middleware extracts the request ID from incoming headers (default: `X-Request-ID`)
2. If no request ID is found, it generates one using UUID v4
3. The request ID is stored in both `request.state` and a context variable
4. The request ID is automatically added to response headers
5. Context is automatically cleaned up after each request
## License
MIT License - see LICENSE file for details
Raw data
{
"_id": null,
"home_page": null,
"name": "fastapi-reqid",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "correlation-id, fastapi, middleware, request-id, tracing",
"author": null,
"author_email": "Lareira Digital Development Team <developers@lareira.digital>",
"download_url": "https://files.pythonhosted.org/packages/ab/90/9975acd8e5e861ba738210df70f0a0ab99c14804bf1e48c0671a53abe197/fastapi_reqid-0.1.0.tar.gz",
"platform": null,
"description": "# FastAPI Request ID\n\nA FastAPI middleware for request ID propagation and tracing across microservices.\n\n## Quick Start\n\n### 1. Add Middleware\n\n```python\nfrom fastapi import FastAPI\nfrom fastapi_reqid import RequestIDMiddleware\n\napp = FastAPI()\n\n# Add middleware with default settings\napp.add_middleware(RequestIDMiddleware)\n\n# Or customize it\napp.add_middleware(\n RequestIDMiddleware,\n header_name=\"X-Correlation-ID\", # Custom header name\n generator=lambda: str(uuid.uuid4()) # Custom ID generator\n)\n```\n\n### 2. Access Request ID\n\n```python\nfrom fastapi import Request\nfrom fastapi_reqid import get_request_id\n\n@app.get(\"/\")\nasync def root(request: Request):\n # Access via request.state\n request_id = request.state.request_id\n\n # Or use the context helper\n request_id = get_request_id()\n\n return {\"request_id\": request_id}\n```\n\n## HTTP Client Decorators\n\nAutomatically inject request IDs into outgoing HTTP requests.\n\n### httpx\n\n```python\nfrom fastapi import Request\nfrom fastapi_reqid import inject_httpx_requestid\n\n@app.get(\"/external\")\n@inject_httpx_requestid\nasync def call_external(request: Request):\n client = request.state.httpx_client\n response = await client.get(\"https://api.example.com\")\n return response.json()\n```\n\n### aiohttp\n\n```python\nfrom fastapi import Request\nfrom fastapi_reqid import inject_aiohttp_requestid\n\n@app.get(\"/external\")\n@inject_aiohttp_requestid\nasync def call_external(request: Request):\n session = request.state.aiohttp_session\n async with session.get(\"https://api.example.com\") as resp:\n return await resp.json()\n```\n\n### requests\n\n```python\nfrom fastapi import Request\nfrom fastapi_reqid import inject_requests_requestid\n\n@app.get(\"/external\")\n@inject_requests_requestid\ndef call_external(request: Request):\n session = request.state.requests_session\n response = session.get(\"https://api.example.com\")\n return response.json()\n```\n\n## Manual Request ID Management\n\nUse these functions to manually get or set request IDs:\n\n```python\nfrom fastapi_reqid import get_request_id, set_request_id, request_id_context\n\n# Get current request ID\nrequest_id = get_request_id()\n\n# Set request ID manually\ntoken = set_request_id(\"custom-request-id\")\ntry:\n # Do work with this request ID\n pass\nfinally:\n # Reset to previous value\n request_id_context.reset(token)\n```\n\n## Building and Publishing\n\n### Building the Library\n\nThis project uses [uv](https://github.com/astral-sh/uv) for building. To build the distribution packages:\n\n```bash\n# Install uv if you haven't already\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Build the package (creates wheel and source distribution)\nuv build\n```\n\nThis will create two files in the `dist/` directory:\n- `fastapi_reqid-{version}-py3-none-any.whl` - Python wheel\n- `fastapi_reqid-{version}.tar.gz` - Source distribution\n\n### Publishing to PyPI\n\n#### Test on TestPyPI First (Recommended)\n\nBefore publishing to the main PyPI, test your package on TestPyPI:\n\n```bash\n# Publish to TestPyPI\nuv publish --publish-url https://test.pypi.org/legacy/\n```\n\nYou'll need a TestPyPI account and API token from [test.pypi.org](https://test.pypi.org).\n\n#### Publish to PyPI\n\nOnce you've verified the package works correctly:\n\n```bash\n# Publish to PyPI\nuv publish\n```\n\nYou'll need a PyPI account and API token from [pypi.org](https://pypi.org).\n\n### Development Setup\n\nTo set up a development environment:\n\n```bash\n# Create virtual environment\nuv venv\n\n# Install package in editable mode with dev dependencies\nuv pip install -e \".[dev]\"\n\n# Run tests\npytest\n```\n\n## How It Works\n\n1. The middleware extracts the request ID from incoming headers (default: `X-Request-ID`)\n2. If no request ID is found, it generates one using UUID v4\n3. The request ID is stored in both `request.state` and a context variable\n4. The request ID is automatically added to response headers\n5. Context is automatically cleaned up after each request\n\n## License\n\nMIT License - see LICENSE file for details\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "FastAPI middleware for request ID propagation with support for httpx, aiohttp, and requests",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/lareira-digital/fastapi-reqid",
"Issues": "https://github.com/lareira-digital/fastapi-reqid/issues",
"Repository": "https://github.com/lareira-digital/fastapi-reqid"
},
"split_keywords": [
"correlation-id",
" fastapi",
" middleware",
" request-id",
" tracing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "101e2884f4e937e832dde3f90ebeddfb95b49996592efc247d55d24201615ef8",
"md5": "0065726c425b113fb5304c0d0251a574",
"sha256": "c3ba5db518b573ce4ed5868a27aae93dd7c338b935d8083c821eee46797d1da8"
},
"downloads": -1,
"filename": "fastapi_reqid-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0065726c425b113fb5304c0d0251a574",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 6423,
"upload_time": "2025-10-30T23:43:54",
"upload_time_iso_8601": "2025-10-30T23:43:54.664576Z",
"url": "https://files.pythonhosted.org/packages/10/1e/2884f4e937e832dde3f90ebeddfb95b49996592efc247d55d24201615ef8/fastapi_reqid-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ab909975acd8e5e861ba738210df70f0a0ab99c14804bf1e48c0671a53abe197",
"md5": "a9a1e94d779edb265b0bbc8670ba0902",
"sha256": "78897ba7578dfef9c9eda142bd606c9d28ab4e2d07adaaab23a23e2291b3e2f3"
},
"downloads": -1,
"filename": "fastapi_reqid-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "a9a1e94d779edb265b0bbc8670ba0902",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 5660,
"upload_time": "2025-10-30T23:43:56",
"upload_time_iso_8601": "2025-10-30T23:43:56.252900Z",
"url": "https://files.pythonhosted.org/packages/ab/90/9975acd8e5e861ba738210df70f0a0ab99c14804bf1e48c0671a53abe197/fastapi_reqid-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-30 23:43:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lareira-digital",
"github_project": "fastapi-reqid",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "fastapi-reqid"
}
JSON
