deprecat decorator

Python @deprecat decorator to deprecate old python classes, functions or methods.

Installation

pip install deprecat

Compatibility

Python >=3.6

Usage

Deprecated function

from deprecat import deprecat

@deprecat(reason="this is a bad function", version = '2.0')
def some_deprecated_function(x, y):
    return x+y

If the user tries to use the deprecated function some_deprecated_function(2, 3), they will have a warning:

5

DeprecationWarning: Call to deprecated function (or staticmethod) some_deprecated_function. (this is a bad function) -- Deprecated since version 2.0.

some_deprecated_function(2, 3)

Deprecated method

from deprecat import deprecat

class thisclassisuseful:

    def __init__(self,value):
        self.value = value

    @deprecat(reason="this is a bad method", version = 2.0)
    def some_deprecated_function(self):
        print(self.value)

Let's try running this:

x = thisclassisuseful('abc')
x.some_deprecated_function()

Here's what we get:

abc

DeprecationWarning: Call to deprecated method some_deprecated_function. 
(this is a bad method) -- Deprecated since version 2.0.

x.some_deprecated_function()

Deprecated class

from deprecat import deprecat

@deprecat(reason="useless", version = 2.0)
class badclass:

    def __init__(self):
        print("you just ran this class")

Now when we call badclass() we get:

you just ran this class

DeprecationWarning: Call to deprecated class badclass. 
(useless) -- Deprecated since version 2.0.

badclass()

Sphinx Decorator - Functions

You can use the sphinx decorator in deprecat to emit warnings and add a sphinx warning directive with custom title (using admonition) in docstring. Let's say this is our function (this can be done for methods and classes as well, just like the classic deprecat decorator)

from deprecat.sphinx import deprecat

@deprecat(
    reason=""" this is very buggy say bye""",
    version='0.3.0')
def myfunction(x):
    """
    Calculate the square of a number.

    :param x: a number
    :return: number * number
    """
    return x*x

Now when we try to use this as myfunction(3) we get the warning as usual:

DeprecationWarning: Call to deprecated function (or staticmethod) myfunction. ( this is very buggy say bye) -- Deprecated since version 0.3.0.

myfunction(3)

9

Additionally, we have a modified docstring (print(myfunction.__doc__) as follows:

Calculate the square of a number.

:param x: a number
:return: number * number

.. deprecated:: 0.3.0
  this is very buggy say bye

Deprecated kwargs

Suppose you have this function where two of the keyword arguments are not useful anymore so you can deprecate them like this.

from deprecat.sphinx import deprecat

@deprecat(deprecated_args={'a':{'version':'4.0','reason':'nothing'}, 'b':{'version':'3.0','reason':'something'}})
def multiply(a, b, c):
    """
    Compute the product

    Parameters
    ----------
    a: float
        a is a nice number

    b: float
        b is also a nice number

    c: float
        c is ok too
    """
    return a*b*c

This is the output we get when we try to run multiply(a=1,b=2,c=3)

DeprecationWarning: Call to deprecated Parameter b. (something) -- Deprecated since v3.0.
multiply(a=1,b=2,c=3)

DeprecationWarning: Call to deprecated Parameter a. (nothing) -- Deprecated since v4.0.
multiply(a=1,b=2,c=3)

6

Now, the cool part is your docstring (multiply.__doc__) get's modified as well. This is how it renders in Sphinx

Authors

The authors of this library are: Marcos CARDOSO, and Laurent LAPORTE. The original code was made in this StackOverflow post by Leandro REGUEIRO, Patrizio BERTONI, and Eric WIESER.

Modified and now maintained by: Meenal Jhajharia