Python 3.13+warningsterm

warnings.deprecated

issuing warnings

A decorator (3.13+) marking a function or class as deprecated: using it emits a DeprecationWarning, and type checkers flag the call.

Syntax

@warnings.deprecated(message, /, *, category=DeprecationWarning, stacklevel=1)

It works in two worlds at once: mypy and pyright see the mark statically, and at run time every call, instantiation or subclassing emits a DeprecationWarning pointing at the caller's line. It is an ordinary warning and filters apply as usual: outside __main__ nobody sees it by default. category=None keeps only the static mark. For versions before 3.13 the same decorator lives in typing_extensions; the message is stored in __deprecated__.

Examples

from warnings import deprecated, catch_warnings, simplefilter
@deprecated('используйте new_api()')
def old_api():
    return 42
with catch_warnings(record=True) as caught:
    simplefilter('always', DeprecationWarning)
    print(old_api())  # → 42
print(caught[0].category is DeprecationWarning)  # → True
print(old_api.__deprecated__)  # → используйте new_api()

See also

Common errors

Open in the full glossarydocs.python.orgReport an inaccuracy