Skip to content

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.

from fastapi import APIRouter, Depends
from fastapi_deprecation import DeprecationDependency

router = APIRouter(
    dependencies=[
        Depends(DeprecationDependency(deprecation_date="2024-06-01"))
    ]
)

fastapi_deprecation.dependencies

DeprecationDependency

A dependency that can be used to deprecate an endpoint or router.

Parameters:

Name Type Description Default
deprecation_date Optional[DateInput]

The date when the endpoint is deprecated.

 None
sunset_date Optional[DateInput]

The date when the endpoint is sunset.

 None
alternative Optional[str]

The alternative endpoint to redirect to.

 None
link Optional[str]

The link to the deprecation information (policy or migration guide).

 None
links Optional[dict[str, str]]

Additional links for deprecation information (newer versions, etc.).

 None
brownouts Optional[list[tuple[DateInput, DateInput]]]

List of brownout periods.

 None
detail Optional[str]

Additional detail about the deprecation.

 None
response Optional[Callable[[], Response] | Response]

Custom response to return.

 None
inject_cache_control bool

Whether to inject cache control headers.

 False
cache_tag Optional[str]

Cache tag for the deprecation.

 None
brownout_probability float

Probability of a brownout.

 0.0
progressive_brownout bool

Whether to use progressive brownout.

 False
Source code in src/fastapi_deprecation/dependencies.py 
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
class DeprecationDependency:
    """
    A dependency that can be used to deprecate an endpoint or router.

    Args:
        deprecation_date (Optional[DateInput]): The date when the endpoint is deprecated.
        sunset_date (Optional[DateInput]): The date when the endpoint is sunset.
        alternative (Optional[str]): The alternative endpoint to redirect to.
        link (Optional[str]): The link to the deprecation information (policy or migration guide).
        links (Optional[dict[str, str]]): Additional links for deprecation information (newer versions, etc.).
        brownouts (Optional[list[tuple[DateInput, DateInput]]]): List of brownout periods.
        detail (Optional[str]): Additional detail about the deprecation.
        response (Optional[Callable[[], StarletteResponse] | StarletteResponse]): Custom response to return.
        inject_cache_control (bool): Whether to inject cache control headers.
        cache_tag (Optional[str]): Cache tag for the deprecation.
        brownout_probability (float): Probability of a brownout.
        progressive_brownout (bool): Whether to use progressive brownout.
    """

    def __init__(
        self,
        deprecation_date: Optional[DateInput] = None,
        sunset_date: Optional[DateInput] = None,
        alternative: Optional[str] = None,
        alternative_status: int = status.HTTP_301_MOVED_PERMANENTLY,
        link: Optional[str] = None,
        links: Optional[dict[str, str]] = None,
        brownouts: Optional[list[tuple[DateInput, DateInput]]] = None,
        detail: Optional[str] = None,
        response: Optional[Callable[[], StarletteResponse] | StarletteResponse] = None,
        inject_cache_control: bool = False,
        cache_tag: Optional[str] = None,
        brownout_probability: float = 0.0,
        progressive_brownout: bool = False,
    ):
        dep_date = parse_date(deprecation_date) if deprecation_date else None
        sun_date = parse_date(sunset_date) if sunset_date else None

        parsed_brownouts = []
        if brownouts:
            for start, end in brownouts:
                parsed_brownouts.append((parse_date(start), parse_date(end)))

        self.config = DeprecationConfig(
            deprecation_date=dep_date,
            sunset_date=sun_date,
            brownouts=parsed_brownouts,
            alternative=alternative,
            alternative_status=alternative_status,
            link=link,
            links=links,
            detail=detail,
            custom_response=response,
            inject_cache_control=inject_cache_control,
            cache_tag=cache_tag,
            brownout_probability=brownout_probability,
            progressive_brownout=progressive_brownout,
        )

    def __getattr__(self, item):
        """Pass through attribute accesses to the internal DeprecationConfig for backwards compatibility."""
        return getattr(self.config, item)

    async def __call__(self, request: Request, response: Response):
        now = datetime.now(timezone.utc)
        result = process_deprecation(self.config, now)

        if result.action == ActionType.BLOCK:
            dummy_res = build_block_response(self.config, result)
            await execute_telemetry(request, dummy_res, self)

            if self.config.custom_response:
                raise DeprecationSunset(dummy_res)

            if self.config.alternative:
                headers = dict(result.headers)
                headers["Location"] = self.config.alternative
                raise HTTPException(
                    status_code=self.config.alternative_status,
                    detail=self.config.detail or "Endpoint is deprecated and replaced.",
                    headers=headers,
                )
            else:
                raise HTTPException(
                    status_code=status.HTTP_410_GONE,
                    detail=self.config.detail
                    or "Endpoint is deprecated and no longer available.",
                    headers=result.headers,
                )

        # WARN Phase
        apply_headers(response.headers, result.headers)

        await execute_telemetry(request, response, self)

__getattr__(item)

Pass through attribute accesses to the internal DeprecationConfig for backwards compatibility.

Source code in src/fastapi_deprecation/dependencies.py 
86
87
88
def __getattr__(self, item):
    """Pass through attribute accesses to the internal DeprecationConfig for backwards compatibility."""
    return getattr(self.config, item)