Decorators in the python standard library (specifically @deprecated)

Question

I need to mark the procedures as deprecated, but apparently there is no standard library decoder for deprecation. I know the recipes for it and the warning module, but my question is: why is there no standard library decoder for this (general) task?

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

Answer 1

Here is a snippet of code modified from the one quoted by Leandro:

import warnings import functools def deprecated(func): """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.""" @functools.wraps(func) def new_func(*args, **kwargs): warnings.simplefilter('always', DeprecationWarning) # turn off filter warnings.warn("Call to deprecated function {}.".format(func.__name__), category=DeprecationWarning, stacklevel=2) warnings.simplefilter('default', DeprecationWarning) # reset filter return func(*args, **kwargs) return new_func # Examples @deprecated def some_old_function(x, y): return x + y class SomeClass: @deprecated def some_old_method(self, x, y): return x + y 

Because in some interpreters the first solution disclosed (without filter processing) can lead to suppression of the warning.

Answer 2

Here is another solution:

This decorator (actually a decorator factory ) allows you to send the reason for the message. It is also more useful to help the developer diagnose the problem by specifying the original file name and line number .

EDIT : this code uses the null recommendation: replace the warnings.warn_explicit line with warnings.warn(msg, category=DeprecationWarning, stacklevel=2) , which prints the function call site, not the function definition site. This makes debugging easier.

EDIT2 : This version allows the developer to specify an optional “cause” 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 an obsolete library:

• Python Package Index (PyPi)
• Github site
• Read Documents
• Twitter

New stable version v1.2.6 🎉

Answer 3

I assume that the reason is that Python code cannot be processed statically (as is done for C ++ compilers), you cannot get a warning about using some things before using it. I do not think it is a good idea to spam the user of your script with a bunch of messages. "Warning: this developer of this script is using an outdated API."

Update: but you can create a decorator that converts the original function to another. The new function will mark / check the switch, saying that this function has already been called and will display a message only when the switch is turned on. And / or upon exit, it can print a list of all the obsolete functions used in the program.

Answer 4

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

The deprecation library provides the deprecation decorator and the fail_if_not_removed decorator for your tests.

Installation

 pip install deprecation 

Usage example

 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 full documentation.

Answer 5

classmethod() , staticmethod() and various property decorators are important. There is also one of contextlib and several other less used ones.

Answer 6

You can create a utilities 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 

Answer 7

UPDATE: I think it's better when we show DeprecationWarning only the first time for each line of code and when we can send a message:

 import inspect import traceback import warnings import functools import time def deprecated(message: str = ''): """ 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 first time and filter is set for show DeprecationWarning. """ def decorator_wrapper(func): @functools.wraps(func) def function_wrapper(*args, **kwargs): current_call_source = '|'.join(traceback.format_stack(inspect.currentframe())) if current_call_source not in function_wrapper.last_call_source: warnings.warn("Function {} is now deprecated! {}".format(func.__name__, message), category=DeprecationWarning, stacklevel=2) function_wrapper.last_call_source.add(current_call_source) return func(*args, **kwargs) function_wrapper.last_call_source = set() return function_wrapper return decorator_wrapper @deprecated('You must use my_func2!') def my_func(): time.sleep(.1) print('aaa') time.sleep(.1) def my_func2(): print('bbb') warnings.simplefilter('always', DeprecationWarning) # turn off filter print('before cycle') for i in range(5): my_func() print('after cycle') my_func() my_func() my_func() 

Result:

 before cycle C:/Users/adr-0/OneDrive/Projects/Python/test/unit1.py:45: DeprecationWarning: Function my_func is now deprecated! You must use my_func2! aaa aaa aaa aaa aaa after cycle C:/Users/adr-0/OneDrive/Projects/Python/test/unit1.py:47: DeprecationWarning: Function my_func is now deprecated! You must use my_func2! aaa C:/Users/adr-0/OneDrive/Projects/Python/test/unit1.py:48: DeprecationWarning: Function my_func is now deprecated! You must use my_func2! aaa C:/Users/adr-0/OneDrive/Projects/Python/test/unit1.py:49: DeprecationWarning: Function my_func is now deprecated! You must use my_func2! aaa Process finished with exit code 0 

We can just click on the warning path and go to the line in PyCharm.

Answer 8

Complementing this answer from Stephen Vacellaro :

If you are using Anaconda, first install the deprecation package:

 conda install -c conda-forge deprecation 

Then paste the following at the top of the file

 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 full documentation.