Use Cases🔗

The most common reasons to deprecate something are renaming a function, renaming an argument, or replacing a class. This overview maps each scenario to the right topic page. If you are new to the library, start with Getting Started.

Topics🔗

Functions 🔗

Deprecating Python functions and methods: simple call forwarding, argument renaming with args_mapping, notice-only deprecation, self argument remapping with TargetMode.ARGS_REMAP, stacking multiple decorators for multi-release migrations, and conditional suppression with skip_if.

Classes 🔗

Deprecating classes, Enums, dataclasses, and module-level constants: forwarding an old class name to a replacement with deprecated_class(), wrapping module-level objects with deprecated_instance(), selective attribute deprecation with attrs_mapping, and stacking multiple proxy layers for multi-version attribute migrations.

Properties 🔗

Deprecating @property and @cached_property descriptors: decorator order rules, wrapping all three accessors (fget, fset, fdel) at once, chaining .setter / .deleter, and the dataclass field alias pattern.

Async 🔗

Deprecating async def functions and async generator functions: all three TargetModes, warning timing differences (await-time vs call-time), coroutine introspection behaviour, and concurrency caveats.

Advanced 🔗

Advanced patterns: injecting a deprecation notice into the docstring at import time (update_docstring=True), supplying a fixed default for a new required argument (args_extra), testing helpers (assert_no_warnings), deprecating @classmethod and @staticmethod descriptors, and generator functions.

Quick decision table🔗

Scenario	Where to look
Rename a function or method	Functions → Simple forwarding
Rename an argument	Functions → Argument renaming
Notice only — no replacement yet	Functions → Notice-only
Rename an argument within the same function	Functions → Self argument mapping
Stack decorators across releases	Functions → Stacked decorators
Suppress notice conditionally	Functions → Conditional skip
Rename a class, Enum, or dataclass	Classes → Class deprecation
Deprecate a module-level constant or object	Classes → Constants and instances
Deprecate selected class attributes	Classes → Selective attributes
Deprecate a `@property`	Properties
Deprecate an `async def` function	Async → Async functions
Deprecate an async generator	Async → Async generators
Inject deprecation notice into docstring	Advanced → Docstring updates
Inject a fixed default for a new required arg	Advanced → Injecting new args
Silence warnings in test fixtures	Advanced → Testing helpers
Deprecate a `@classmethod` or `@staticmethod`	Advanced → Class/static methods
Deprecate a generator function	Advanced → Generators

Use Cases🔗

Topics🔗

Functions🔗

Classes🔗

Properties🔗

Async🔗

Advanced🔗