Deprecated Decorator

Deprecated: a price tag reading "@deprecated, best before: next major"

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.

Authors

Deprecated was started by Marcos CARDOSO, building on the recipes shared in this Stack Overflow discussion by Leandro REGUEIRO, Patrizio BERTONI and Eric WIESER.

Laurent LAPORTE has been the main author and maintainer of the library for many years.

Release files for Deprecated 3.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for Deprecated 3.0.0
File	Size	Uploaded
deprecated-3.0.0.tar.gz	166.9 kB	Sep 26, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for Deprecated 3.0.0
File	Interpreter	ABI	Platform	Reset
deprecated-3.0.0-py3-none-any.whl 21.9 kB Sep 26, 2026	Python 3	none	any	Details

Total release size: 188.8 kB

Release files / deprecated-3.0.0.tar.gz

Download URL	deprecated-3.0.0.tar.gz
Size	166.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`16850204d3a1e6bb0acd06bff48d96e8b0a0d25d1c52f71705405a0f4894192d`
BLAKE2b-256 checksum How to use checksums	`f79c16649913bf14c73e0a9453782e148362ff2657067deff6aa9c7ebcddcc31`
Upload date	Sep 26, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.9 {"installer":{"name":"uv","version":"0.12.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`

Release files / deprecated-3.0.0-py3-none-any.whl

Download URL	deprecated-3.0.0-py3-none-any.whl
Size	21.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`58204cf4a7f6270d547af5c278ee7a6bb56045a4b3d8441a1cd11660f41b7939`
BLAKE2b-256 checksum How to use checksums	`83ae676feae8e4644a6d7169951a97f61c56f416c73f67bf1761f2461d75cc81`
Upload date	Sep 26, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.9 {"installer":{"name":"uv","version":"0.12.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`