fastapi-deprecation 0.2.1__tar.gz

fastapi_deprecation-0.2.1/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build-n-publish:
+    name: Build and Publish
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/fastapi-deprecation
+    permissions:
+      id-token: write  # IMPORTANT: this permission is mandatory for trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish distribution 📦 to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

fastapi_deprecation-0.2.1/.github/workflows/test.yml

@@ -0,0 +1,34 @@
+name: Test
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    types: [opener, synchronize, reopened]
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install the project
+        run: uv sync --all-extras --dev
+
+      - name: Run tests
+        run: uv run pytest tests
+
+      - name: Lint with Ruff
+        run: uv run ruff check .

fastapi_deprecation-0.2.1/.gitignore

@@ -0,0 +1,12 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+_version.py
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+site/

fastapi_deprecation-0.2.1/.pre-commit-config.yaml

@@ -0,0 +1,22 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.1.6
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
+
+  - repo: https://github.com/compilerla/conventional-pre-commit
+    rev: v3.2.0
+    hooks:
+      - id: conventional-pre-commit
+        stages: [commit-msg]
+        args: []

fastapi_deprecation-0.2.1/.python-version

@@ -0,0 +1 @@
+3.10

fastapi_deprecation-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fractal Vision
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fastapi_deprecation-0.2.1/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: fastapi-deprecation
+Version: 0.2.1
+Summary: Endpoint deprecation management for FastAPI made easy
+License: MIT License
+        
+        Copyright (c) 2026 Fractal Vision
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.129.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: python-dateutil>=2.9.0.post0
+Requires-Dist: typing-extensions>=4.15.0
+Description-Content-Type: text/markdown
+
+# FastAPI Deprecation
+
+<div align="center">
+  <p align="center">
+    <strong>RFC 9745 compliant API deprecation for FastAPI.</strong>
+  </p>
+  <p align="center">
+    <a href="https://github.com/fractalvision/fastapi-deprecation/actions/workflows/test.yml">
+      <img src="https://github.com/fractalvision/fastapi-deprecation/actions/workflows/test.yml/badge.svg" alt="Test Status"/>
+    </a>
+  </p>
+</div>
+
+---
+
+**FastAPI Deprecation** helps you manage the lifecycle of your API endpoints using standard HTTP headers (`Deprecation`, `Sunset`, `Link`) and automated blocking logic. It allows you to gracefully warn clients about upcoming deprecations and automatically shut down endpoints when they reach their sunset date.
+
+## Features
+
+- **Standard Compliance**: Fully implements [RFC 9745](https://datatracker.ietf.org/doc/rfc9745/) and [RFC 8594](https://datatracker.ietf.org/doc/rfc8594/).
+- **Decorator-based**: Simple `@deprecated` decorator for your path operations.
+- **Automated Blocking**: Automatically returns `410 Gone` or `301 Moved Permanently` after the `sunset_date`.
+- **OpenAPI Integration**: Automatically marks endpoints as deprecated in Swagger UI and ReDoc.
+- **Router Support**: Deprecate entire routers or sub-applications with `DeprecationDependency`.
+- **Extended Features**:
+    - **Telemetry**: Track usage of deprecated endpoints.
+    - **Brownouts**: Schedule temporary shutdowns to simulate future removal.
+    - **Future Deprecation**: Announce upcoming deprecations before they become active.
+
+## Installation
+
+```bash
+pip install fastapi-deprecation
+# or with uv
+uv add fastapi-deprecation
+```
+
+## Documentation
+
+To run the documentation locally:
+
+```bash
+uv run zensical serve
+```
+
+## Quick Start
+
+```python
+from fastapi import FastAPI
+from fastapi_deprecation import deprecated, auto_deprecate_openapi
+
+app = FastAPI()
+
+@app.get("/old-endpoint")
+@deprecated(
+    deprecation_date="2024-01-01",
+    sunset_date="2025-01-01",
+    alternative="/new-endpoint",
+    detail="This endpoint is old and tired."
+)
+async def old():
+    return {"message": "Enjoy it while it lasts!"}
+
+# Don't forget to update the schema at the end!
+auto_deprecate_openapi(app)
+```
+
+## How It Works
+
+1.  **Warning Phase** (Before Sunset):
+    *   Requests return `200 OK`.
+    *   Response headers include:
+        *   `Deprecation: @1704067200` (Unix timestamp of `deprecation_date`)
+        *   `Sunset: Wed, 01 Jan 2025 00:00:00 GMT`
+        *   `Link: </new-endpoint>; rel="alternative"`
+
+2.  **Blocking Phase** (After Sunset):
+    *   Requests return `410 Gone` (or `301 Moved Permanently` if `alternative` is set).
+    *   The `detail` message is returned in the response body.
+
+## Advanced Usage
+
+### 1. Brownouts (Scheduled Unavailability)
+You can simulate future shutdowns by scheduling "brownouts" — temporary periods where the endpoint returns `410 Gone` (or `301` if alternative is set). This forces clients to notice the deprecation before the final sunset.
+
+```python
+@deprecated(
+    sunset_date="2025-12-31",
+    brownouts=[
+        # 1-hour brownout
+        ("2025-11-01T09:00:00Z", "2025-11-01T10:00:00Z"),
+        # 1-day brownout
+        ("2025-12-01T00:00:00Z", "2025-12-02T00:00:00Z"),
+    ],
+    detail="Service is temporarily unavailable due to scheduled brownout."
+)
+async def my_endpoint(): ...
+```
+
+### 2. Telemetry & Logging
+Track usage of deprecated endpoints using a global callback. This is useful for monitoring which clients are still using old APIs.
+
+```python
+import logging
+from fastapi import Request, Response
+from fastapi_deprecation import set_deprecation_callback, DeprecationDependency
+
+logger = logging.getLogger("deprecation")
+
+def log_usage(request: Request, response: Response, dep: DeprecationDependency):
+    logger.warning(
+        f"Deprecated endpoint {request.url} accessed. "
+        f"Deprecation date: {dep.deprecation_date}"
+    )
+
+set_deprecation_callback(log_usage)
+```
+
+### 3. Deprecating Entire Routers
+To deprecate a whole group of endpoints, use `DeprecationDependency` on the `APIRouter`.
+
+```python
+from fastapi import APIRouter, Depends
+from fastapi_deprecation import DeprecationDependency
+
+router = APIRouter(
+    dependencies=[Depends(DeprecationDependency(deprecation_date="2024-01-01"))]
+)
+
+@router.get("/sub-route")
+async def sub(): ...
+```
+
+### 4. Recursive OpenAPI Support
+When using `auto_deprecate_openapi(app)`, it automatically traverses potentially mounted sub-applications (`app.mount(...)`) and marks their routes as deprecated if configured.
+
+```python
+root_app.mount("/v1", v1_app)
+# This will update OpenAPI for both root_app AND v1_app
+auto_deprecate_openapi(root_app)
+```
+
+### 5. Future Deprecation
+You can announce a *future* deprecation date. The `Deprecation` header will still be sent (as per RFC 9745), allowing clients to prepare in advance.
+
+```python
+@deprecated(deprecation_date="2030-01-01")
+async def future_proof(): ...
+```
+
+See the [Documentation](https://example.com/docs) for full details on API reference and advanced configuration.

fastapi_deprecation-0.2.1/README.md

@@ -0,0 +1,151 @@
+# FastAPI Deprecation
+
+<div align="center">
+  <p align="center">
+    <strong>RFC 9745 compliant API deprecation for FastAPI.</strong>
+  </p>
+  <p align="center">
+    <a href="https://github.com/fractalvision/fastapi-deprecation/actions/workflows/test.yml">
+      <img src="https://github.com/fractalvision/fastapi-deprecation/actions/workflows/test.yml/badge.svg" alt="Test Status"/>
+    </a>
+  </p>
+</div>
+
+---
+
+**FastAPI Deprecation** helps you manage the lifecycle of your API endpoints using standard HTTP headers (`Deprecation`, `Sunset`, `Link`) and automated blocking logic. It allows you to gracefully warn clients about upcoming deprecations and automatically shut down endpoints when they reach their sunset date.
+
+## Features
+
+- **Standard Compliance**: Fully implements [RFC 9745](https://datatracker.ietf.org/doc/rfc9745/) and [RFC 8594](https://datatracker.ietf.org/doc/rfc8594/).
+- **Decorator-based**: Simple `@deprecated` decorator for your path operations.
+- **Automated Blocking**: Automatically returns `410 Gone` or `301 Moved Permanently` after the `sunset_date`.
+- **OpenAPI Integration**: Automatically marks endpoints as deprecated in Swagger UI and ReDoc.
+- **Router Support**: Deprecate entire routers or sub-applications with `DeprecationDependency`.
+- **Extended Features**:
+    - **Telemetry**: Track usage of deprecated endpoints.
+    - **Brownouts**: Schedule temporary shutdowns to simulate future removal.
+    - **Future Deprecation**: Announce upcoming deprecations before they become active.
+
+## Installation
+
+```bash
+pip install fastapi-deprecation
+# or with uv
+uv add fastapi-deprecation
+```
+
+## Documentation
+
+To run the documentation locally:
+
+```bash
+uv run zensical serve
+```
+
+## Quick Start
+
+```python
+from fastapi import FastAPI
+from fastapi_deprecation import deprecated, auto_deprecate_openapi
+
+app = FastAPI()
+
+@app.get("/old-endpoint")
+@deprecated(
+    deprecation_date="2024-01-01",
+    sunset_date="2025-01-01",
+    alternative="/new-endpoint",
+    detail="This endpoint is old and tired."
+)
+async def old():
+    return {"message": "Enjoy it while it lasts!"}
+
+# Don't forget to update the schema at the end!
+auto_deprecate_openapi(app)
+```
+
+## How It Works
+
+1.  **Warning Phase** (Before Sunset):
+    *   Requests return `200 OK`.
+    *   Response headers include:
+        *   `Deprecation: @1704067200` (Unix timestamp of `deprecation_date`)
+        *   `Sunset: Wed, 01 Jan 2025 00:00:00 GMT`
+        *   `Link: </new-endpoint>; rel="alternative"`
+
+2.  **Blocking Phase** (After Sunset):
+    *   Requests return `410 Gone` (or `301 Moved Permanently` if `alternative` is set).
+    *   The `detail` message is returned in the response body.
+
+## Advanced Usage
+
+### 1. Brownouts (Scheduled Unavailability)
+You can simulate future shutdowns by scheduling "brownouts" — temporary periods where the endpoint returns `410 Gone` (or `301` if alternative is set). This forces clients to notice the deprecation before the final sunset.
+
+```python
+@deprecated(
+    sunset_date="2025-12-31",
+    brownouts=[
+        # 1-hour brownout
+        ("2025-11-01T09:00:00Z", "2025-11-01T10:00:00Z"),
+        # 1-day brownout
+        ("2025-12-01T00:00:00Z", "2025-12-02T00:00:00Z"),
+    ],
+    detail="Service is temporarily unavailable due to scheduled brownout."
+)
+async def my_endpoint(): ...
+```
+
+### 2. Telemetry & Logging
+Track usage of deprecated endpoints using a global callback. This is useful for monitoring which clients are still using old APIs.
+
+```python
+import logging
+from fastapi import Request, Response
+from fastapi_deprecation import set_deprecation_callback, DeprecationDependency
+
+logger = logging.getLogger("deprecation")
+
+def log_usage(request: Request, response: Response, dep: DeprecationDependency):
+    logger.warning(
+        f"Deprecated endpoint {request.url} accessed. "
+        f"Deprecation date: {dep.deprecation_date}"
+    )
+
+set_deprecation_callback(log_usage)
+```
+
+### 3. Deprecating Entire Routers
+To deprecate a whole group of endpoints, use `DeprecationDependency` on the `APIRouter`.
+
+```python
+from fastapi import APIRouter, Depends
+from fastapi_deprecation import DeprecationDependency
+
+router = APIRouter(
+    dependencies=[Depends(DeprecationDependency(deprecation_date="2024-01-01"))]
+)
+
+@router.get("/sub-route")
+async def sub(): ...
+```
+
+### 4. Recursive OpenAPI Support
+When using `auto_deprecate_openapi(app)`, it automatically traverses potentially mounted sub-applications (`app.mount(...)`) and marks their routes as deprecated if configured.
+
+```python
+root_app.mount("/v1", v1_app)
+# This will update OpenAPI for both root_app AND v1_app
+auto_deprecate_openapi(root_app)
+```
+
+### 5. Future Deprecation
+You can announce a *future* deprecation date. The `Deprecation` header will still be sent (as per RFC 9745), allowing clients to prepare in advance.
+
+```python
+@deprecated(deprecation_date="2030-01-01")
+async def future_proof(): ...
+```
+
+See the [Documentation](https://example.com/docs) for full details on API reference and advanced configuration.

fastapi_deprecation-0.2.1/docs/index.md

@@ -0,0 +1,138 @@
+# FastAPI Deprecation
+
+<div align="center">
+  <p align="center">
+    <strong>RFC 9745 compliant API deprecation for FastAPI.</strong>
+  </p>
+</div>
+
+---
+
+**FastAPI Deprecation** helps you manage the lifecycle of your API endpoints using standard HTTP headers (`Deprecation`, `Sunset`, `Link`) and automated blocking logic. It allows you to gracefully warn clients about upcoming deprecations and automatically shut down endpoints when they reach their sunset date.
+
+## Features
+
+- **Standard Compliance**: Fully implements [RFC 9745](https://datatracker.ietf.org/doc/rfc9745/) and [RFC 8594](https://datatracker.ietf.org/doc/rfc8594/).
+- **Decorator-based**: Simple `@deprecated` decorator for your path operations.
+- **Automated Blocking**: Automatically returns `410 Gone` or `301 Moved Permanently` after the `sunset_date`.
+- **OpenAPI Integration**: Automatically marks endpoints as deprecated in Swagger UI and ReDoc.
+- **Router Support**: Deprecate entire routers or sub-applications with `DeprecationDependency`.
+- **Extended Features**:
+    - **Telemetry**: Track usage of deprecated endpoints.
+    - **Brownouts**: Schedule temporary shutdowns to simulate future removal.
+    - **Future Deprecation**: Announce upcoming deprecations before they become active.
+
+## Installation
+
+```bash
+pip install fastapi-deprecation
+# or with uv
+uv add fastapi-deprecation
+```
+
+## Quick Start
+
+```python
+from fastapi import FastAPI
+from fastapi_deprecation import deprecated, auto_deprecate_openapi
+
+app = FastAPI()
+
+@app.get("/old-endpoint")
+@deprecated(
+    deprecation_date="2024-01-01",
+    sunset_date="2025-01-01",
+    alternative="/new-endpoint",
+    detail="This endpoint is old and tired."
+)
+async def old():
+    return {"message": "Enjoy it while it lasts!"}
+
+# Don't forget to update the schema at the end!
+auto_deprecate_openapi(app)
+```
+
+## How It Works
+
+1.  **Warning Phase** (Before Sunset):
+    *   Requests return `200 OK`.
+    *   Response headers include:
+        *   `Deprecation: @1704067200` (Unix timestamp of `deprecation_date`)
+        *   `Sunset: Wed, 01 Jan 2025 00:00:00 GMT`
+        *   `Link: </new-endpoint>; rel="alternative"`
+
+2.  **Blocking Phase** (After Sunset):
+    *   Requests return `410 Gone` (or `301 Moved Permanently` if `alternative` is set).
+    *   The `detail` message is returned in the response body.
+
+## Advanced Usage
+
+### 1. Brownouts (Scheduled Unavailability)
+You can simulate future shutdowns by scheduling "brownouts" — temporary periods where the endpoint returns `410 Gone` (or `301` if alternative is set). This forces clients to notice the deprecation before the final sunset.
+
+```python
+@deprecated(
+    sunset_date="2025-12-31",
+    brownouts=[
+        # 1-hour brownout
+        ("2025-11-01T09:00:00Z", "2025-11-01T10:00:00Z"),
+        # 1-day brownout
+        ("2025-12-01T00:00:00Z", "2025-12-02T00:00:00Z"),
+    ],
+    detail="Service is temporarily unavailable due to scheduled brownout."
+)
+async def my_endpoint(): ...
+```
+
+### 2. Telemetry & Logging
+Track usage of deprecated endpoints using a global callback. This is useful for monitoring which clients are still using old APIs.
+
+```python
+import logging
+from fastapi import Request, Response
+from fastapi_deprecation import set_deprecation_callback, DeprecationDependency
+
+logger = logging.getLogger("deprecation")
+
+def log_usage(request: Request, response: Response, dep: DeprecationDependency):
+    logger.warning(
+        f"Deprecated endpoint {request.url} accessed. "
+        f"Deprecation date: {dep.deprecation_date}"
+    )
+
+set_deprecation_callback(log_usage)
+```
+
+### 3. Deprecating Entire Routers
+To deprecate a whole group of endpoints, use `DeprecationDependency` on the `APIRouter`.
+
+```python
+from fastapi import APIRouter, Depends
+from fastapi_deprecation import DeprecationDependency
+
+router = APIRouter(
+    dependencies=[Depends(DeprecationDependency(deprecation_date="2024-01-01"))]
+)
+
+@router.get("/sub-route")
+async def sub(): ...
+```
+
+### 4. Recursive OpenAPI Support
+When using `auto_deprecate_openapi(app)`, it automatically traverses potentially mounted sub-applications (`app.mount(...)`) and marks their routes as deprecated if configured.
+
+```python
+root_app.mount("/v1", v1_app)
+# This will update OpenAPI for both root_app AND v1_app
+auto_deprecate_openapi(root_app)
+```
+
+### 5. Future Deprecation
+You can announce a *future* deprecation date. The `Deprecation` header will still be sent (as per RFC 9745), allowing clients to prepare in advance.
+
+```python
+@deprecated(deprecation_date="2030-01-01")
+async def future_proof(): ...
+```
+
+Check the [API Reference](reference/core.md) for full details.

fastapi_deprecation-0.2.1/docs/reference/core.md

@@ -0,0 +1,30 @@
+# Core API
+
+The `core` module provides the primary interface for deprecating endpoints in FastAPI: the `@deprecated` decorator.
+
+## Usage
+
+The `@deprecated` decorator should be placed *above* your path operation function but *below* the FastAPI router decorator (though order usually doesn't matter for functionality, it keeps the code clean).
+
+```python
+from fastapi import FastAPI
+from fastapi_deprecation import deprecated
+
+app = FastAPI()
+
+@app.get("/items")
+@deprecated(
+    deprecation_date="2024-01-01",
+    sunset_date="2025-01-01",
+    alternative="/new_items"
+)
+async def read_items():
+    return [{"item_id": "Foo"}]
+```
+
+## Reference
+
+::: fastapi_deprecation.core
+    options:
+      show_root_heading: true
+      show_source: true

fastapi_deprecation-0.2.1/docs/reference/dependencies.md

@@ -0,0 +1,41 @@
+# Dependencies API
+
+The `dependencies` module contains the underlying logic for handling deprecation lifecycles. It allows for more advanced usage patterns, such as applying deprecation to entire routers or registering global callbacks.
+
+## Router Deprecation
+
+You can deprecate an entire `APIRouter` by adding `DeprecationDependency` to its dependencies list.
+
+```python
+from fastapi import APIRouter, Depends
+from fastapi_deprecation import DeprecationDependency
+
+router = APIRouter(
+    dependencies=[
+        Depends(DeprecationDependency(deprecation_date="2024-06-01"))
+    ]
+)
+```
+
+## Telemetry Callbacks
+
+You can register a callback to be notified whenever a deprecated endpoint is accessed. This is useful for logging, analytics, or alerting.
+
+```python
+import logging
+from fastapi_deprecation import set_deprecation_callback
+
+logger = logging.getLogger("deprecation")
+
+def on_deprecation(request, response, dep):
+    logger.warning(f"Deprecated usage: {request.url}")
+
+set_deprecation_callback(on_deprecation)
+```
+
+## Reference
+
+::: fastapi_deprecation.dependencies
+    options:
+      show_root_heading: true
+      show_source: true