Skip to content

Engine

The engine module serves as the functional core of the fastapi-deprecation package. It contains the primary configuration model (DeprecationConfig) and the agnostic evaluation logic (evaluate_deprecation) used by both decorators and middlewares.

DeprecationConfig

DeprecationConfig is the universal data structure that holds all metadata for a deprecation lifecycle. Whether you define your deprecations via the @deprecated decorator or the DeprecationMiddleware, they are all internally normalized into DeprecationConfig definitions.

It also contains the centralized telemetry dispatch mechanisms unifying logging events across the framework.

DeprecationConfig dataclass

Configuration for deprecation.

Attributes:

Name Type Description
deprecation_date Optional[datetime]

The date when the endpoint is deprecated.
sunset_date Optional[datetime]

The date when the endpoint is sunset.
brownouts List[Tuple[datetime, datetime]]

List of brownout periods.
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.).
detail Optional[str]

Additional detail about the deprecation.
response Optional[Callable[[], Response] | Response]

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.
Source code in src/fastapi_deprecation/engine.py 
 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
@dataclass
class DeprecationConfig:
    """
    Configuration for deprecation.

    Attributes:
        deprecation_date (Optional[datetime]): The date when the endpoint is deprecated.
        sunset_date (Optional[datetime]): The date when the endpoint is sunset.
        brownouts (List[Tuple[datetime, datetime]]): List of brownout periods.
        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.).
        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.
    """

    deprecation_date: Optional[datetime] = None
    sunset_date: Optional[datetime] = None
    brownouts: List[Tuple[datetime, datetime]] = field(default_factory=list)
    alternative: Optional[str] = None
    alternative_status: int = status.HTTP_301_MOVED_PERMANENTLY
    link: Optional[str] = None
    links: Dict[str, str] = field(default_factory=dict)
    detail: Optional[str] = None
    custom_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

    def __post_init__(self):
        if (
            self.deprecation_date
            and self.sunset_date
            and self.deprecation_date > self.sunset_date
        ):
            raise ValueError("deprecation_date cannot be later than sunset_date")

        if self.brownout_probability > 0 and self.progressive_brownout:
            raise ValueError(
                "Cannot use both static brownout_probability and progressive_brownout"
            )

        if self.progressive_brownout and not (
            self.deprecation_date and self.sunset_date
        ):
            raise ValueError(
                "progressive_brownout requires both deprecation_date and sunset_date"
            )

        if not (0.0 <= self.brownout_probability <= 1.0):
            raise ValueError("brownout_probability must be between 0.0 and 1.0")

ActionType

Bases: Enum

Source code in src/fastapi_deprecation/engine.py 
48
49
50
class ActionType(Enum):
    WARN = "WARN"
    BLOCK = "BLOCK"

DeprecationResult dataclass

Source code in src/fastapi_deprecation/engine.py 
113
114
115
116
@dataclass
class DeprecationResult:
    action: ActionType
    headers: Dict[str, str]

set_deprecation_callback(callback)

Set a global callback for telemetry.

Source code in src/fastapi_deprecation/engine.py 
17
18
19
20
21
def set_deprecation_callback(callback: Callable[[Request, Response, Any], None]):
    """Set a global callback for telemetry."""
    global _DEPRECATION_CALLBACKS
    if callback:
        _DEPRECATION_CALLBACKS.append(callback)