Deprecated Decorator

Python @deprecated decorator to deprecate old python classes, functions or methods.

Removing a function from a library breaks the code of its users. Deprecating it first gives them time to migrate: the Deprecated library marks classes, functions, methods and parameters as deprecated, emits a warning that points at the calling code, and can document the deprecation in the docstring.

Installation

pip install Deprecated

Deprecated requires Python 3.12+ and wrapt.

Usage

Decorate a deprecated function, method or class with @deprecated:

from deprecated import deprecated


@deprecated(reason="use new_function", version="2.1.0")
def some_old_function(x, y):
    return x + y


some_old_function(1, 2)

Each call emits a warning located at the calling line:

example.py:9: DeprecationWarning: Call to deprecated function (or staticmethod) some_old_function. (use new_function) -- Deprecated since version 2.1.0.

@deprecated can also be used without arguments, and accepts other options: category (e.g. FutureWarning instead of DeprecationWarning), action (a local warning filter, e.g. "error") and extra_stacklevel (for wrappers of deprecated functions).

To deprecate a parameter rather than the whole function, use @deprecated_params:

from deprecated import deprecated_params


@deprecated_params("color", reason="'color' is ignored, use 'style'")
def draw(shape, color=None, style=None):
    ...

Calling draw("circle", color="red") emits DeprecationWarning: 'color' is ignored, use 'style'.

Documenting the life cycle

The Deprecated library can also document the life cycle of your functions and classes: the @deprecated, @versionadded and @versionchanged decorators update the docstring, according to your docstring format:

deprecated.sphinx: reStructuredText directives (.. deprecated:: 1.2.0),
deprecated.google: Google style sections (Deprecated:),
deprecated.numpy: NumPy style sections (Deprecated underlined with hyphens).

from deprecated.google import deprecated
from deprecated.google import versionadded


@deprecated(reason="use another function", version="1.2.0")
@versionadded(version="1.0.0")
def some_old_function(x, y):
    """Add two numbers.

    Args:
        x: first number.
        y: second number.
    """
    return x + y

The docstring of some_old_function ends with:

Version added:
    1.0.0

Deprecated:
    1.2.0: use another function

Why not `warnings.deprecated`?

Since Python 3.13, warnings.deprecated (PEP 702) emits a runtime warning and lets the type checkers report the use of deprecated objects. Deprecated complements it with version numbers, docstring updates (Sphinx, Google, NumPy), local warning filters and deprecated parameters. Both can be combined, see the white paper.

See the documentation for more details.