API Reference🔗

Auto-generated from source docstrings. For usage examples see the User Guide.

Decorator🔗

`deprecate.deprecation.deprecated(target=TargetMode.NOTIFY, deprecated_in='', remove_in='', stream=deprecation_warning, num_warns=1, template_mgs=None, args_mapping=None, args_extra=None, skip_if=False, update_docstring=False, docstring_style='auto')` 🔗

Decorate a function/method with warning message and forward calls to target.

This decorator marks a function or method as deprecated and can automatically forward all calls to a replacement implementation. It supports argument mapping, custom warning messages, and flexible warning control.

For generator functions (def gen(): yield) and async generator functions (async def gen(): yield), the deprecation warning fires at call time — when the (async) generator object is created — not at first iteration. The generator body executes lazily as normal when iterated (next() / async for).

Parameters:

Name	Type	Description	Default
`target`	`Union[bool, None, Callable, TargetMode]`	How to handle the deprecation. Defaults to :attr:`~deprecate.TargetMode.NOTIFY` (warn-only; source body executes unchanged). Pass an explicit value to forward calls or remap arguments: `Callable`: Forward all calls to this callable (function, method, or class target). The decorated function's body is not executed under normal forwarding — use `pass` or `...` as the body. Exception: when `skip_if` evaluates `True` at call time, the source body executes as a fallback, so keep a working implementation if you combine `target=Callable` with `skip_if`. :attr:`~deprecate.TargetMode.ARGS_REMAP` (or legacy `True`): Self-deprecation — deprecate argument names only, remapping them within the same function body :attr:`~deprecate.TargetMode.NOTIFY` (default): Warning-only mode — no forwarding, source body executes normally Omitting `target` is the preferred way to express warn-only deprecation. Passing `target=None` is a legacy synonym that also resolves to :attr:`~deprecate.TargetMode.NOTIFY` but emits a :class:`FutureWarning` directing you to use the enum form.	`NOTIFY`
`deprecated_in`	`str`	Version when the function was deprecated (e.g., "1.0.0"). Default is empty string.	`''`
`remove_in`	`str`	Version when the function will be removed (e.g., "2.0.0"). Default is empty string.	`''`
`stream`	`Optional[Callable]`	Function to output warnings (default: :func:`~deprecate.deprecation.deprecation_warning`, which is :func:`warnings.warn` with `FutureWarning` category). Set to `None` to disable warnings entirely.	`deprecation_warning`
`num_warns`	`int`	Number of times to show warning per function or per deprecated argument: - `1` (default): Show warning once per function/argument - `-1`: Show warning on every call - `0`: Suppress deprecation warnings emitted for the decorated function/argument - `N > 1`: Show warning N times total	`1`
`template_mgs`	`Optional[str]`	Custom warning message template with format specifiers: - `source_name`: Function name (e.g., "my_func") - `source_path`: Full path (e.g., "module.my_func") - `target_name`: Target function name (only for callable targets) - `target_path`: Full target path (only for callable targets) - `deprecated_in`: Value of deprecated_in parameter - `remove_in`: Value of remove_in parameter - `argument_map`: String showing argument mapping (for args deprecation only) Example: "v%(deprecated_in)s: `%(source_name)s` was deprecated."	`None`
`args_mapping`	`Optional[ArgsMapping]`	Map or skip arguments when forwarding: - `{'old_arg': 'new_arg'}`: Rename argument - `{'old_arg': None}`: Skip argument (don't forward it) - `{}`: Empty mapping (no remapping) Works with both `target=Callable` and `target=True`.	`None`
`args_extra`	`Optional[dict[str, Any]]`	Additional arguments merged into kwargs before the call. Used when target is a Callable or :attr:`~deprecate._types.TargetMode.ARGS_REMAP` (with `args_mapping`). Ignored when target is :attr:`~deprecate._types.TargetMode.NOTIFY`. Example: `{'new_required_arg': 42}`	`None`
`skip_if`	`Union[bool, Callable]`	Conditionally skip deprecation warning and forwarding: - `bool`: Static condition (True = skip deprecation) - `Callable`: Function returning bool (checked at runtime, must return bool) If condition is True, original function executes without warning.	`False`
`update_docstring`	`bool`	If True, automatically inject a deprecation notice into the function's docstring (inserted before Google/NumPy-style sections when present, otherwise appended at the end).	`False`
`docstring_style`	`Literal['auto', 'rst', 'mkdocs', 'markdown']`	Output style for injected deprecation notice when `update_docstring=True`. Supported values: - `"auto"` (default): Automatically choose a style based on the current environment (e.g., loaded modules, CLI/tooling context). This may resolve to either `"rst"` or `"mkdocs"`/`"markdown"` at decoration time. - `"rst"`: Explicitly force Sphinx-style `.. deprecated::` directive. - `"mkdocs"` or `"markdown"`: Explicitly force a Markdown admonition of the form `!!! warning "Deprecated in X"`. Validated eagerly at decoration time regardless of `update_docstring`.	`'auto'`

Returns:

Type	Description
`Callable[[Callable[..., Any]], Callable[..., Any]]`	Decorator function that wraps the source function/method.

Warns:

Type	Description
`UserWarning`	If applied directly to a class. The decorator delegates to :func:`~deprecate.proxy.deprecated_class` and emits this warning. Use `@deprecated_class()` directly to suppress it. Suppressed when `stream=None`.
`UserWarning`	If `deprecated_in` is absent, `stream` is not `None`, no `template_mgs` is set, and the decorated source is not a class. Fired at decoration time (not call time) to catch missing version metadata early. Suppressed by passing `stream=None` or `template_mgs`.

Raises:

Type	Description
`TypeError`	If the source is a class method and target is a method on a different class (cross-class method forwarding detected at decoration time via `__qualname__` comparison). Skipped silently when the target's qualname prefix names a class absent from the target's module globals.
`TypeError`	If skip_if is a callable that doesn't return a bool.
`TypeError`	If arguments in args_mapping don't exist in target function and target doesn't accept **kwargs.

Example

Basic forwarding🔗

def new_func(x: int) -> int: ... return x * 2 @deprecated(target=new_func, deprecated_in="1.0", remove_in="2.0") ... def old_func(x: int) -> int: ... pass

Argument mapping🔗

@deprecated( ... target=new_func, ... args_mapping={'old_name': 'new_name', 'unused': None} ... ) ... def old_func(old_name: int, unused: str) -> int: ... pass

Self-deprecation🔗

from deprecate import TargetMode @deprecated(target=TargetMode.ARGS_REMAP, args_mapping={'old_arg': 'new_arg'}) ... def my_func(old_arg: int = 0, new_arg: int = 0) -> int: ... return new_arg * 2

Warn-only (default — no target needed)🔗

@deprecated(deprecated_in="1.0", remove_in="2.0") ... def legacy_func(x: int) -> int: ... return x

Proxy🔗

`deprecate.proxy.deprecated_class(target=None, *, deprecated_in='', remove_in='', num_warns=1, stream=deprecation_warning, template_mgs=None, args_mapping=None, args_extra=None, update_docstring=False, docstring_style='auto', _misconfigured_override=False)` 🔗

Decorator factory for deprecating class definitions with optional target redirection.

Apply @deprecated_class(...) to an Enum or dataclass to wrap the class in a :class:~deprecate.proxy._DeprecatedProxy. All attribute, item, and call access on the resulting object will emit a deprecation warning and, if target is provided, will be forwarded to the replacement class.

Parameters:

Name	Type	Description	Default
`target`	`Any`	Optional replacement class to redirect all access to.	`None`
`deprecated_in`	`str`	Version string when the class was deprecated.	`''`
`remove_in`	`str`	Version string when the class will be removed.	`''`
`num_warns`	`int`	Maximum number of warnings to emit per proxy instance. `1` warns once; `-1` warns on every access.	`1`
`stream`	`Optional[Callable[..., None]]`	Callable used to emit warnings. Defaults to :data:`~deprecate.deprecation.deprecation_warning`.	`deprecation_warning`
`template_mgs`	`Optional[str]`	Optional custom warning message template that overrides the built-in templates. When `None` (default), the built-in template for the active scenario is used (callable-target, no-target, or per-argument for `args_mapping`). Available `%`-style placeholders: `%(source_name)s` — the deprecated class name (taken from `cls.__name__`) `%(deprecated_in)s` — value of the `deprecated_in` argument `%(remove_in)s` — value of the `remove_in` argument `%(target_name)s` — target class name (only when target is callable) `%(target_path)s` — fully-qualified target path (only when target is callable) `%(argument_map)s` — formatted \`old\` -> \`new\``` string (only for per-argument warnings emitted byargs_mapping``) Example: `"v%(deprecated_in)s:`%(source_name)s`->`%(target_name)s`"`.	`None`
`args_mapping`	`Optional[dict[str, Optional[str]]]`	Optional dict remapping keyword argument names when the decorated class is called. Keys are old argument names; values are new names, or `None` to drop the argument entirely. When provided without an explicit callable target, the mode auto-resolves to :attr:`~deprecate._types.TargetMode.ARGS_REMAP`: the proxy warns only when an old argument name is actually used in the call, matching the per-argument warning behaviour of `@deprecated(target=TargetMode.ARGS_REMAP, args_mapping=...)`. Passing `args_mapping` together with `target=TargetMode.NOTIFY` is a misconfiguration and emits a :class:`UserWarning` at decoration time (will be :class:`TypeError` in v1.0). Similarly, `target=TargetMode.ARGS_REMAP` without `args_mapping` emits a :class:`UserWarning` at decoration time.	`None`
`args_extra`	`Optional[dict[str, Any]]`	Optional dict of extra keyword arguments merged into the forwarded call after `args_mapping` has been applied. Caller-supplied values override entries with the same key. Ignored when `target` is :attr:`~deprecate._types.TargetMode.NOTIFY` (passing both emits a :class:`UserWarning` at decoration time; will be :class:`TypeError` in v1.0).	`None`
`update_docstring`	`bool`	If `True`, inject a deprecation notice into the class docstring at decoration time (same behaviour as `@deprecated(update_docstring=True)`).	`False`
`docstring_style`	`Literal['auto', 'rst', 'mkdocs', 'markdown']`	Output style for the injected notice when `update_docstring=True`. `"auto"` detects the doc engine at decoration time; `"rst"` emits a `.. deprecated::` directive; `"mkdocs"` / `"markdown"` emit a `!!! warning` admonition.	`'auto'`

Returns:

Type	Description
`Callable[[type], _DeprecatedProxy]`	A decorator that wraps the class in a :class:`~deprecate.proxy._DeprecatedProxy`.

Examples:

>>> from enum import Enum
>>> class NewColor(Enum):
...     RED = 1
>>> @deprecated_class(target=NewColor, deprecated_in="1.0", remove_in="2.0", stream=None)
... class OldColor(Enum):
...     RED = 1
>>> OldColor.RED is NewColor.RED
True
>>> OldColor(1) is NewColor.RED
True

When only argument names changed, omit target and supply args_mapping. The proxy auto-resolves to :attr:~deprecate._types.TargetMode.ARGS_REMAP and warns only when the old argument name is passed:

>>> class Config:
...     def __init__(self, timeout: int = 0) -> None:
...         self.timeout = timeout
>>> LegacyConfig = deprecated_class(
...     args_mapping={"time_limit": "timeout"},
...     deprecated_in="1.5", remove_in="2.0", stream=None,
... )(Config)
>>> LegacyConfig(timeout=30).timeout     # new name — no remap needed
30
>>> LegacyConfig(time_limit=30).timeout  # old name — remapped to timeout
30

`deprecate.proxy.deprecated_instance(obj, *, name='', deprecated_in='', remove_in='', num_warns=1, stream=deprecation_warning, template_mgs=None, read_only=False, args_extra=None)` 🔗

Wrap any Python object with deprecation warnings.

Returns a :class:~deprecate.proxy._DeprecatedProxy that transparently forwards all read access to obj while emitting a :class:FutureWarning. In read-only mode any write attempt through the proxy raises :class:AttributeError.

Parameters:

Name	Type	Description	Default
`obj`	`Any`	The object to deprecate (dict, list, custom object, …).	required
`name`	`str`	Display name for obj used in the warning message. When omitted, the type name of obj is used (e.g. `"dict"`).	`''`
`deprecated_in`	`str`	Version string when obj was deprecated.	`''`
`remove_in`	`str`	Version string when obj will be removed.	`''`
`num_warns`	`int`	Maximum number of warnings to emit. `1` (default) warns once; `-1` warns on every access.	`1`
`stream`	`Optional[Callable[..., None]]`	Callable used to emit warnings. Defaults to :data:`~deprecate.deprecation.deprecation_warning` (:class:`FutureWarning`). Pass `None` to suppress warnings.	`deprecation_warning`
`template_mgs`	`Optional[str]`	Optional custom warning message template that overrides the built-in templates. When `None` (default), the built-in template for the active scenario is used. See :func:`~deprecate.proxy.deprecated_class` for the available `%`-style placeholders.	`None`
`read_only`	`bool`	If `True`, raise :class:`AttributeError` on any write attempt through the proxy. Only the following standard collection mutator names are intercepted: `append`, `clear`, `discard`, `extend`, `insert`, `pop`, `remove`, `setdefault`, `update`, `add`. Custom method names (e.g. `register()`, `reload()`, `set_value()`) are not blocked.	`False`
`args_extra`	`Optional[dict[str, Any]]`	Optional dict of extra keyword arguments merged into the forwarded call when the proxy is invoked. Caller-supplied values override entries with the same key.	`None`

Returns:

Name	Type	Description
`A`	`_DeprecatedProxy`

Example

cfg = {"threshold": 0.5, "enabled": True} proxy = deprecated_instance( ... cfg, ... name="config_dict", ... deprecated_in="1.0", ... remove_in="2.0", ... stream=None, ... ) proxy["threshold"] 0.5 proxy.get("enabled") True

Audit🔗

`deprecate.audit.find_deprecation_wrappers(module, recursive=True, include_members=True)` 🔗

Scan a module or package for deprecated wrappers and validate them.

This is a development/CI tool to scan a codebase for all wrappers created with :func:~deprecate.deprecated, :func:~deprecate.deprecated_class, or :func:~deprecate.deprecated_instance and validate that each wrapper configuration is meaningful. Returns comprehensive information about each deprecated wrapper including validation results that help identify misconfigured wrappers.

Parameters:

Name	Type	Description	Default
`module`	`Union[Any, str]`	A Python module or package to scan for deprecated wrappers. Can be: - Imported module object (e.g., `import my_package; find_deprecation_wrappers(my_package)`) - String module path (e.g., `find_deprecation_wrappers("my_package.submodule")`)	required
`recursive`	`bool`	If True (default), recursively scan submodules. If False, only scan the top-level module.	`True`
`include_members`	`bool`	If True, also scan deprecated methods and constructors defined on classes.	`True`

Returns:

Type Description

list[DeprecationWrapperInfo]

List of :class:~deprecate.audit.DeprecationWrapperInfo dataclasses, one per deprecated wrapper found.

list[DeprecationWrapperInfo]

Each contains: - module: Module name where the wrapper is defined - function: Wrapper name - deprecated_info: DeprecationConfig metadata from the decorator (__deprecated__ attribute) - invalid_args: List of args_mapping keys not in wrapper signature - empty_args_mapping: True if args_mapping is None or empty - identity_args_mapping: List of identity mappings (key == value) - self_reference: True if target points to same wrapper - no_effect: True if wrapper has zero impact

Example

from deprecate import find_deprecation_wrappers from tests import collection_deprecate as my_package

results = find_deprecation_wrappers(my_package) print(len(results) > 0) # Should find deprecated wrappers True

Also works with string module paths🔗

results = find_deprecation_wrappers("tests.collection_deprecate") print(len(results) > 0) True

Filter to find only problematic wrappers🔗

problematic = [r for r in results if r.invalid_args or r.no_effect] print(len(results) > 0) # May or may not have problematic ones True

Note

Requires that the module be importable
Inspects the __deprecated__ attribute set by the :func:~deprecate.deprecated decorator
Skips private/magic attributes and imports from other modules
Uses static member inspection to avoid scan-time side effects from dynamic attribute access

`deprecate.audit.validate_deprecation_wrapper(func)` 🔗

Validate if a deprecated wrapper configuration is effective.

This is a development tool to check if deprecated wrappers are configured correctly and will have the intended effect. It examines the __deprecated__ attribute set by the :func:~deprecate.deprecated decorator and identifies configurations that would result in zero impact:

args_mapping keys that don't exist in the function's signature
Empty or None args_mapping (no argument remapping)
Identity mappings where key equals value (e.g., {'arg': 'arg'})
Target pointing to the same function (self-reference)
target=None with no args_mapping (just warns, no forwarding)

Parameters:

Name	Type	Description	Default
`func`	`Callable`	The decorated function to validate. Must have a `__deprecated__` attribute set by the `@deprecated` decorator.	required

Returns:

Type Description

DeprecationWrapperInfo

function: Name of the wrapper being validated
deprecated_info: The typed :class:~deprecate._types.DeprecationConfig metadata from __deprecated__
invalid_args: List of args_mapping keys not in wrapper signature
empty_args_mapping: True if args_mapping is None or empty
identity_args_mapping: List of args where key equals value (no effect)
self_reference: True if target is the same as the wrapper
no_effect: True if wrapper has zero impact (all checks combined)
empty_deprecated_in: True when deprecated_in is absent or empty

Raises:

Type	Description
`ValueError`	If the wrapper has missing or invalid `__deprecated__` metadata (expected :class:`~deprecate._types.DeprecationConfig`).

Example

from deprecate import deprecated, validate_deprecation_wrapper def new_implementation(value: int) -> int: ... return value * 2

@deprecated(target=new_implementation, deprecated_in="1.0", args_mapping={"old_val": "value"}) ... def old_func(old_val: int) -> int: ... pass

Valid mapping to different function - has effect🔗

result = validate_deprecation_wrapper(old_func) result.no_effect False result.invalid_args []

@deprecated(target=True, deprecated_in="1.0", args_mapping={"arg": "arg"}) ... def identity_func(arg: int) -> int: ... return arg

Identity mapping with self-deprecation - no effect🔗

result = validate_deprecation_wrapper(identity_func) result.identity_args_mapping ['arg'] result.no_effect True

Note

Use this function during development or in CI to ensure deprecation decorators are configured meaningfully. Invalid configurations won't cause runtime errors but will silently have no effect.

`deprecate.audit.validate_deprecation_expiry(module, current_version=None, recursive=True, include_members=False)` 🔗

Check all deprecated callables in a module/package for expired removal deadlines.

This enforcement tool scans an entire module or package for deprecated functions and checks if any have passed their scheduled removal version. It's designed for CI/CD pipelines to automatically detect and report zombie code across a codebase.

The function uses :func:~deprecate.audit.find_deprecation_wrappers to discover all deprecated wrappers, then checks each one against the current version. Any wrappers that have reached or passed their removal deadline are collected and reported.

Parameters:

Name	Type	Description	Default
`module`	`Union[Any, str]`	A Python module or package to scan. Can be: - Imported module object (e.g., `import my_package; validate_deprecation_expiry(my_package, "2.0")`) - String module path (e.g., `validate_deprecation_expiry("my_package.submodule", "2.0")`)	required
`current_version`	`Optional[str]`	The current version of your package to compare against removal deadlines (e.g., `"2.0.0"`). If None, attempts to auto-detect the version using the package name from the module path (e.g., `"mypackage"` extracts `mypackage` as package name).	`None`
`recursive`	`bool`	If True (default), recursively scan submodules. If False, only scan the top-level module.	`True`
`include_members`	`bool`	If True, also scan deprecated class members (methods, constructors).	`False`

Returns:

Type	Description
`list[str]`	List of error messages for callables that have expired (past their removal deadline).
`list[str]`	Empty list if all deprecated callables are still within their deprecation period.

Example

Check a specific module with version before any deadlines🔗

from deprecate import validate_deprecation_expiry expired = validate_deprecation_expiry("tests.collection_deprecate", "0.1", recursive=False) len(expired) 0

Check with version past some removal deadlines🔗

expired = validate_deprecation_expiry("tests.collection_deprecate", "0.5", recursive=False) print(len(expired)) # Some functions have remove_in="0.5" 28

Note

Skips callables without a remove_in field (warnings only, no removal deadline)
Skips callables that cannot be imported or accessed
Silently skips callables with invalid remove_in version formats
Uses semantic versioning comparison (e.g., "1.2.3" vs "2.0.0")
Intended for automated checks in CI/CD pipelines
Can be integrated into test suites or pre-commit hooks

`deprecate.audit.validate_deprecation_chains(module, recursive=True)` 🔗

Validate that deprecated functions don't form chains with other deprecated code.

This is a developer utility that scans a module or package for deprecated functions that form chains in two ways:

TARGET chains: The target argument points to another deprecated callable instead of the final non-deprecated implementation.
STACKED chains: Multiple @deprecated(True, ...) decorators are stacked on the same function with argument mappings that should be collapsed, or a callable target is itself a self-deprecation (target=True) requiring mapping composition.

Both types are wasteful: wrappers should point directly to the final (non-deprecated) implementation with composed argument mappings.

Detection is based purely on decorator metadata (__deprecated__ attributes) — no source-code or AST inspection is performed.

Parameters:

Name	Type	Description	Default
`module`	`Union[Any, str]`	A Python module or package to scan for deprecation chains. Can be: - Imported module object (e.g., `import my_package; validate_deprecation_chains(my_package)`) - String module path (e.g., `validate_deprecation_chains("my_package.submodule")`)	required
`recursive`	`bool`	If True (default), recursively scan submodules. If False, only scan the top-level module.	`True`

Returns:

Type	Description
`list[DeprecationWrapperInfo]`	List of :class:`~deprecate.audit.DeprecationWrapperInfo` where `chain_type` is not `None`, i.e. every
`list[DeprecationWrapperInfo]`	deprecated wrapper that forms a chain (`ChainType.TARGET` or `ChainType.STACKED`).

Example

from deprecate import validate_deprecation_chains import tests.collection_chains as test_module

issues = validate_deprecation_chains(test_module, recursive=False) len(issues) > 0 # Should find chains True

Note

Only flags callees using the :func:~deprecate.deprecated decorator
Uses :func:~deprecate.audit.find_deprecation_wrappers and inspects chain_type to detect chains

`deprecate.audit.DeprecationWrapperInfo` `dataclass` 🔗

Information about a deprecated wrapper and its validation results.

This dataclass represents a deprecated wrapper (a :func:~deprecate.deprecated-decorated function or a :func:~deprecate.proxy.deprecated_class/:func:~deprecate.proxy.deprecated_instance proxy), containing both identification info and validation results from :func:~deprecate.audit.validate_deprecation_wrapper or :func:~deprecate.audit.find_deprecation_wrappers.

Attributes:

Name	Type	Description
`module`	`str`	Module name where the wrapper is defined (empty for direct validation).
`function`	`str`	Wrapper name.
`deprecated_info`	`DeprecationConfig`	The `__deprecated__` attribute from the decorator, as a :class:`~deprecate._types.DeprecationConfig`.
`invalid_args`	`list[str]`	List of `args_mapping` keys that don't exist in the wrapper's signature.
`empty_args_mapping`	`bool`	True if `args_mapping` is None or empty (no argument remapping).
`identity_args_mapping`	`list[str]`	List of args where key equals value (e.g., `{'arg': 'arg'}`).
`self_reference`	`bool`	True if target points to the same wrapper.
`no_effect`	`bool`	True if wrapper has zero impact (combines all checks).
`all_identity`	`bool`	True when every configured mapping is an identity mapping (key == value, non-empty).
`chain_type`	`Optional[ChainType]`	The kind of deprecation chain detected, or `None` if no chain. See :class:`~deprecate.audit.ChainType` for values (:attr:`~deprecate.audit.ChainType.TARGET` or :attr:`~deprecate.audit.ChainType.STACKED`).
`misconfigured_target`	`bool`	True when the wrapper has an invalid target configuration: `target=False`, :attr:`~deprecate._types.TargetMode.NOTIFY` with `args_mapping`, or :attr:`~deprecate._types.TargetMode.ARGS_REMAP` with empty `args_mapping`.
`empty_deprecated_in`	`bool`	True when `deprecated_in` is empty. Missing `remove_in` alone is a valid use case (many libraries deprecate without a scheduled removal date), so only the absence of `deprecated_in` is treated as a misconfiguration signal. CI pipelines can filter on this field to surface wrappers that lack the introductory version metadata without crashing callers.
`api_type`	`str`	Inferred deprecated API type for report generation. Possible values: `callable`, `args`, `class`, `dataclass`, `dataclass attributes`, `data`, `class constructor`, `class constructor args`, `class method`, `class method args`, `classmethod`, `classmethod args`, `staticmethod`, `staticmethod args`.

Example

info = DeprecationWrapperInfo( ... module="my_package.module", ... function="old_function", ... deprecated_info=DeprecationConfig(deprecated_in="1.0", remove_in="2.0"), ... invalid_args=["nonexistent"], ... no_effect=True, ... ) info.function 'old_function' info.invalid_args ['nonexistent']

`empty_mapping` `property` 🔗

Deprecated alias for :attr:~deprecate.audit.DeprecationWrapperInfo.empty_args_mapping.

Deprecated in 0.8

Renamed to :attr:~deprecate.audit.DeprecationWrapperInfo.empty_args_mapping. Will be removed in v1.0.

Note

Python's default warning filter deduplicates per (message, category, module, lineno), so accessing this property in a loop from the same call site emits at most one warning.

`identity_mapping` `property` 🔗

Deprecated alias for :attr:~deprecate.audit.DeprecationWrapperInfo.identity_args_mapping.

Deprecated in 0.8

Renamed to :attr:~deprecate.audit.DeprecationWrapperInfo.identity_args_mapping. Will be removed in v1.0.

Note

Python's default warning filter deduplicates per (message, category, module, lineno), so accessing this property in a loop from the same call site emits at most one warning.

`__post_init__()` 🔗

Derive empty_deprecated_in from deprecated_info to keep them in sync.

`deprecate.audit.ChainType` 🔗

Bases: Enum

Type of deprecation chain detected by :func:~deprecate.audit.validate_deprecation_chains.

Attributes:

Name	Type	Description
`TARGET`		The `target` argument is itself a callable decorated with :func:`~deprecate.deprecated` (a forwarding chain). Fix by pointing directly to the final non-deprecated target.
`STACKED`		Arg mappings chain and must be composed/collapsed. Two sub-cases: (a) Callable `target` is itself `@deprecated(True, args_mapping=...)` — the caller's mapping feeds into the target's self-renaming, so both hops must be collapsed into one. (b) Multiple `@deprecated(True, args_mapping=...)` decorators are stacked on the same function and should be merged into a single decorator.

Types🔗

`deprecate.TargetMode` 🔗

Bases: Enum

Selects @deprecated behaviour when no callable replacement is provided.

Attributes:

Name	Type	Description
`NOTIFY`		Notify-only deprecation -- warn on every call; original body executes unchanged. Replaces `target=None`. Passing `args_mapping` or `args_extra` with this mode emits a :class:`UserWarning` today; :class:`TypeError` is planned in `v1.0`.
`ARGS_REMAP`		Deprecate argument names only -- warn only when deprecated argument names are passed; remaps kwargs via `args_mapping` before calling the original body. Replaces `target=True`. This mode is strongly recommended with `args_mapping`; omitting it emits a :class:`UserWarning` today, and :class:`TypeError` is planned in `v1.0`.

Examples:

>>> from deprecate import TargetMode
>>> TargetMode.NOTIFY.value
'notify'
>>> TargetMode.ARGS_REMAP.value
'args_remap'

Utilities🔗

`deprecate.utils.void(*args, **kwrgs)` 🔗

Empty function that accepts any arguments and returns None.

This helper function is used to silence IDE warnings about unused parameters in deprecated functions where the body is never executed (calls are forwarded to a target function). It's purely a convenience for developers.

Parameters:

Name	Type	Description	Default
`*args`	`Any`	Any positional arguments (ignored).	`()`
`**kwrgs`	`Any`	Any keyword arguments (ignored).	`{}`

Returns:

Type	Description
`Any`	None always.

Example

from deprecate import deprecated, void

def new_func(x: int) -> int: ... return x * 2

@deprecated(target=new_func, deprecated_in="1.0", remove_in="2.0") ... def old_func(x: int) -> int: ... void(x) # Silences IDE warning about unused 'x' ... # This line is never reached - call forwarded to new_func

Note

This function has no runtime effect - it's purely for developer convenience. You can also use pass or just a docstring instead of calling void().

`deprecate.utils.assert_no_warnings(warning_type=None, match=None)` 🔗

Context manager asserting that no warnings are raised — the inverse of pytest.warns().

Useful for testing that refactored code properly avoids deprecated functionality or that new implementations don't trigger warnings.

Parameters:

Name	Type	Description	Default
`warning_type`	`Optional[type[Warning]]`	The warning type that must NOT be raised (e.g., :class:`FutureWarning`, :class:`DeprecationWarning`). If `None`, asserts that no warnings of any type are raised.	`None`
`match`	`Optional[str]`	If given, only fail if a warning message contains this string. If `None`, fails on any warning of the specified type.	`None`

Raises:

Type	Description
`AssertionError`	If a warning of the specified type (and optionally matching the message pattern) was raised during the context.

Example

Assert new function doesn't trigger FutureWarning🔗

import warnings def new_func(x: int) -> int: ... return x * 2 with assert_no_warnings(FutureWarning): ... result = new_func(42) result 84

Assert NO warnings at all are raised🔗

def clean_function(): ... pass with assert_no_warnings(): ... clean_function()

Only fail if warning message matches pattern🔗

def some_function(): ... warnings.warn("deprecated feature", FutureWarning)

Passes because warning contains "feature", not "other"🔗

with assert_no_warnings(FutureWarning, match="other"): ... some_function()

Note

This context manager is particularly useful in pytest for testing that refactored code properly uses new APIs without triggering deprecation warnings.

API Reference🔗

Decorator🔗

deprecate.deprecation.deprecated(target=TargetMode.NOTIFY, deprecated_in='', remove_in='', stream=deprecation_warning, num_warns=1, template_mgs=None, args_mapping=None, args_extra=None, skip_if=False, update_docstring=False, docstring_style='auto') 🔗

Basic forwarding🔗

Argument mapping🔗

Self-deprecation🔗

Warn-only (default — no target needed)🔗

Proxy🔗

deprecate.proxy.deprecated_class(target=None, *, deprecated_in='', remove_in='', num_warns=1, stream=deprecation_warning, template_mgs=None, args_mapping=None, args_extra=None, update_docstring=False, docstring_style='auto', _misconfigured_override=False) 🔗

deprecate.proxy.deprecated_instance(obj, *, name='', deprecated_in='', remove_in='', num_warns=1, stream=deprecation_warning, template_mgs=None, read_only=False, args_extra=None) 🔗

Audit🔗

deprecate.audit.find_deprecation_wrappers(module, recursive=True, include_members=True) 🔗

Also works with string module paths🔗

Filter to find only problematic wrappers🔗

deprecate.audit.validate_deprecation_wrapper(func) 🔗

Valid mapping to different function - has effect🔗

Identity mapping with self-deprecation - no effect🔗

deprecate.audit.validate_deprecation_expiry(module, current_version=None, recursive=True, include_members=False) 🔗

Check a specific module with version before any deadlines🔗

Check with version past some removal deadlines🔗

deprecate.audit.validate_deprecation_chains(module, recursive=True) 🔗

deprecate.audit.DeprecationWrapperInfo dataclass 🔗

empty_mapping property 🔗

identity_mapping property 🔗

__post_init__() 🔗

deprecate.audit.ChainType 🔗

Types🔗

deprecate.TargetMode 🔗

Utilities🔗

deprecate.utils.void(*args, **kwrgs) 🔗

deprecate.utils.assert_no_warnings(warning_type=None, match=None) 🔗

Assert new function doesn't trigger FutureWarning🔗

Assert NO warnings at all are raised🔗

Only fail if warning message matches pattern🔗

Passes because warning contains "feature", not "other"🔗

`deprecate.deprecation.deprecated(target=TargetMode.NOTIFY, deprecated_in='', remove_in='', stream=deprecation_warning, num_warns=1, template_mgs=None, args_mapping=None, args_extra=None, skip_if=False, update_docstring=False, docstring_style='auto')` 🔗

`deprecate.proxy.deprecated_class(target=None, *, deprecated_in='', remove_in='', num_warns=1, stream=deprecation_warning, template_mgs=None, args_mapping=None, args_extra=None, update_docstring=False, docstring_style='auto', _misconfigured_override=False)` 🔗

`deprecate.proxy.deprecated_instance(obj, *, name='', deprecated_in='', remove_in='', num_warns=1, stream=deprecation_warning, template_mgs=None, read_only=False, args_extra=None)` 🔗

`deprecate.audit.find_deprecation_wrappers(module, recursive=True, include_members=True)` 🔗

`deprecate.audit.validate_deprecation_wrapper(func)` 🔗

`deprecate.audit.validate_deprecation_expiry(module, current_version=None, recursive=True, include_members=False)` 🔗

`deprecate.audit.validate_deprecation_chains(module, recursive=True)` 🔗

`deprecate.audit.DeprecationWrapperInfo` `dataclass` 🔗

`empty_mapping` `property` 🔗

`identity_mapping` `property` 🔗

`__post_init__()` 🔗

`deprecate.audit.ChainType` 🔗

`deprecate.TargetMode` 🔗

`deprecate.utils.void(*args, **kwrgs)` 🔗

`deprecate.utils.assert_no_warnings(warning_type=None, match=None)` 🔗