Reputation: 143785

decorators in the python standard lib (@deprecated specifically)

I need to mark routines as deprecated, but apparently there's no standard library decorator for deprecation. I am aware of recipes for it and the warnings module, but my question is: why is there no standard library decorator for this (common) task ?

Additional question: are there standard decorators in the standard library at all ?

Upvotes: 256

Answers (7)

Patrizio Bertoni

Reputation: 2712

Here's a snippet, modified from those cited by Leandro, with added support for typing:

from typing import Callable, ParamSpec, TypeVar
import warnings
import functools


rT = TypeVar('rT') # return type
pT = ParamSpec('pT') # parameters type
def deprecated(func: Callable[pT, rT]) -> Callable[pT, rT]:
    """Use this decorator to mark functions as deprecated.
    Every time the decorated function runs, it will emit
    a "deprecation" warning."""
    @functools.wraps(func)
    def new_func(*args: pT.args, **kwargs: pT.kwargs):
        warnings.simplefilter('always', DeprecationWarning)  # turn off filter
        warnings.warn("Call to a deprecated function {}.".format(func.__name__),
                      category=DeprecationWarning,
                      stacklevel=2)
        warnings.simplefilter('default', DeprecationWarning)  # reset filter
        return func(*args, **kwargs)
    return new_func


### Examples ###

T1 = TypeVar('T1', float, str)
@deprecated
def some_old_function(x: T1, y: T1) -> T1:
    return x + y

class SomeClass:
    @deprecated
    def some_old_method(self, x, y):
        return x + y

# Type inference test
# NOTE: `some_old_function` either accepts and returns `float`
#   or accepts and returns `str`
foo = some_old_function
a = 3.45
b = 3.67
c = foo(a, b)   # `float` type is successfully inferred for `c`

Filter handling with warnings.simplefilter is important because, for some interpreters, the first solution could suppress the warning.

As suggested in the comments, @functools.wraps(func) carries over metadata (name, docstring, arguments specs) from the original function to the wrapping function. This preserves proper linting for the decorated functions.

Upvotes: 95

thehale

Reputation: 1756

A future Python version (after 3.13) will include the warnings.deprecated decorator which will indicate deprecations to type checkers like mypy.

As an example, consider this library stub named library.pyi:

from warnings import deprecated

@deprecated("Use Spam instead")
class Ham: ...

@deprecated("It is pining for the fiords")
def norwegian_blue(x: int) -> int: ...

@overload
@deprecated("Only str will be allowed")
def foo(x: int) -> str: ...
@overload
def foo(x: str) -> str: ...

Here is how type checkers should handle usage of this library:

from library import Ham  # error: Use of deprecated class Ham. Use Spam instead.

import library

library.norwegian_blue(1)  # error: Use of deprecated function norwegian_blue. It is pining for the fiords.
map(library.norwegian_blue, [1, 2, 3])  # error: Use of deprecated function norwegian_blue. It is pining for the fiords.

library.foo(1)  # error: Use of deprecated overload for foo. Only str will be allowed.
library.foo("x")  # no error

ham = Ham()  # no error (already reported above)

Source: PEP702

Upvotes: 51

Erika Dsouza

Reputation: 1083

You can create a utils file

import warnings

def deprecated(message):
  def deprecated_decorator(func):
      def deprecated_func(*args, **kwargs):
          warnings.warn("{} is a deprecated function. {}".format(func.__name__, message),
                        category=DeprecationWarning,
                        stacklevel=2)
          warnings.simplefilter('default', DeprecationWarning)
          return func(*args, **kwargs)
      return deprecated_func
  return deprecated_decorator

And then import the deprecation decorator as follows:

from .utils import deprecated

@deprecated("Use method yyy instead")
def some_method():
 pass

Upvotes: 19

user8234870

Reputation:

Python is a dynamically typed language. Not necessary declare the type to variable or argument type for function statically.

Since its dynamic every thing if processed at runtime. Even if a method is deprecated it will be known at runtime or during interpretation only.

use deprecation module to deprecate methods.

deprecation is a library that enables automated deprecations. It offers the deprecated() decorator to wrap functions, providing proper warnings both in documentation and via Python’s warnings system, as well as the deprecation.fail_if_not_removed() decorator for test methods to ensure that deprecated code is eventually removed.

Installing :

python3.10 -m pip install deprecation

Small demonstration:

import deprecation

@deprecation.deprecated(details="Use bar instead")
def foo():
    print("Foo")


def bar():
    print("Bar")


foo()

bar()

Output:

test.py: DeprecatedWarning: foo is deprecated. Use bar instead
  foo()

Foo

Bar

Upvotes: 1

Laurent LAPORTE

Reputation: 22942

Here is another solution:

This decorator (a decorator factory in fact) allow you to give a reason message. It is also more useful to help the developer to diagnose the problem by giving the source filename and line number.

EDIT: This code use Zero's recommendation: it replace warnings.warn_explicit line by warnings.warn(msg, category=DeprecationWarning, stacklevel=2), which prints the function call site rather than the function definition site. It makes debugging easier.

EDIT2: This version allow the developper to specify an optional "reason" message.

import functools
import inspect
import warnings

string_types = (type(b''), type(u''))


def deprecated(reason):
    """
    This is a decorator which can be used to mark functions
    as deprecated. It will result in a warning being emitted
    when the function is used.
    """

    if isinstance(reason, string_types):

        # The @deprecated is used with a 'reason'.
        #
        # .. code-block:: python
        #
        #    @deprecated("please, use another function")
        #    def old_function(x, y):
        #      pass

        def decorator(func1):

            if inspect.isclass(func1):
                fmt1 = "Call to deprecated class {name} ({reason})."
            else:
                fmt1 = "Call to deprecated function {name} ({reason})."

            @functools.wraps(func1)
            def new_func1(*args, **kwargs):
                warnings.simplefilter('always', DeprecationWarning)
                warnings.warn(
                    fmt1.format(name=func1.__name__, reason=reason),
                    category=DeprecationWarning,
                    stacklevel=2
                )
                warnings.simplefilter('default', DeprecationWarning)
                return func1(*args, **kwargs)

            return new_func1

        return decorator

    elif inspect.isclass(reason) or inspect.isfunction(reason):

        # The @deprecated is used without any 'reason'.
        #
        # .. code-block:: python
        #
        #    @deprecated
        #    def old_function(x, y):
        #      pass

        func2 = reason

        if inspect.isclass(func2):
            fmt2 = "Call to deprecated class {name}."
        else:
            fmt2 = "Call to deprecated function {name}."

        @functools.wraps(func2)
        def new_func2(*args, **kwargs):
            warnings.simplefilter('always', DeprecationWarning)
            warnings.warn(
                fmt2.format(name=func2.__name__),
                category=DeprecationWarning,
                stacklevel=2
            )
            warnings.simplefilter('default', DeprecationWarning)
            return func2(*args, **kwargs)

        return new_func2

    else:
        raise TypeError(repr(type(reason)))

You can use this decorator for functions, methods and classes.

Here is a simple example:

@deprecated("use another function")
def some_old_function(x, y):
    return x + y


class SomeClass(object):
    @deprecated("use another method")
    def some_old_method(self, x, y):
        return x + y


@deprecated("use another class")
class SomeOldClass(object):
    pass


some_old_function(5, 3)
SomeClass().some_old_method(8, 9)
SomeOldClass()

You'll get:

deprecated_example.py:59: DeprecationWarning: Call to deprecated function or method some_old_function (use another function).
  some_old_function(5, 3)
deprecated_example.py:60: DeprecationWarning: Call to deprecated function or method some_old_method (use another method).
  SomeClass().some_old_method(8, 9)
deprecated_example.py:61: DeprecationWarning: Call to deprecated class SomeOldClass (use another class).
  SomeOldClass()

EDIT3: This decorator is now part of the Deprecated library:

New stable release v1.2.13 🎉

Upvotes: 84

Stevoisiak

Reputation: 26742

As muon suggested, you can install the deprecation package for this.

The deprecation library provides a deprecated decorator and a fail_if_not_removed decorator for your tests.

Installation

pip install deprecation

Example Usage

import deprecation

@deprecation.deprecated(deprecated_in="1.0", removed_in="2.0",
                        current_version=__version__,
                        details="Use the bar function instead")
def foo():
    """Do some stuff"""
    return 1

See http://deprecation.readthedocs.io/ for the full documentation.

Upvotes: 34

ony

Reputation: 13223

I guess the reason is that Python code can't be processed statically (as it done for C++ compilers), you can't get warning about using some things before actually using it. I don't think that it's a good idea to spam user of your script with a bunch of messages "Warning: this developer of this script is using deprecated API".

Update: but you can create decorator which will transform original function into another. New function will mark/check switch telling that this function was called already and will show message only on turning switch into on state. And/or at exit it may print list of all deprecated functions used in program.