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

Adding Removal Version

You can add a removal version to the deprecation warning by adding the removal_version parameter to the decorator. This will add a warning to the user that the function will be removed in the next versions.

from deprecat.sphinx import deprecat

@deprecat(reason="this is a bad function", version = "2.0", remove_version = "3.0")
def some_deprecated_function(x, y):
    """
    Parameters
    ----------
    x: float
        x is a nice number

    y: float
        y is also a nice number
    """
    return x+y

This is the output we get when we try to run some_deprecated_function(x=2, y=3)

DeprecationWarning: Call to deprecated method randomfunction. useless
Warning: This deprecated feature will be removed in version 3.0 -- Deprecated since version 2.0. -- Will be removed in version 3.0.

Live Examples

If you want to see the sphinx admonitions in action, check this out