deprecate decorator

The following decorator can be used to mark a function/method as "deprecated" or "soon-to-be deprecated".

It accepts a message argument to display as warning and a class argument which defaults to PendingDeprecationWarning. You might want to pass DeprecationWarning here instead.

import functools
import warnings

def deprecate(msg, klass=PendingDeprecationWarning):
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            warnings.warn(msg, klass, stacklevel=2)
            return func(*args, **kwargs)
        return wrapper
    return decorator

Example:

warnings.simplefilter("once", category=(PendingDeprecationWarning, DeprecationWarning))

@deprecate("This function will be deprecated in the future. Use new_function().")
def old_function(a, b):
    new_function(a, b, 0)

def new_function(a, b, c):
    print(a+b+c)

old_function(1, 2)

And the relevant output:

deprecate.py:25: PendingDeprecationWarning: This function will be deprecated in the future. Use new_function().
  old_function(1, 2)
3