API

This part of the documentation covers all the interfaces of the Deprecated Library.

Deprecated Library

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

Classic deprecation warning

Classic @deprecated decorator to deprecate old python classes, functions or methods.

class deprecated.classic.ClassicAdapter(reason='', version='', action=None, category=<class 'DeprecationWarning'>, extra_stacklevel=0)

Classic adapter – for advanced usage only

This adapter is used to get the deprecation message according to the wrapped object type: class, function, standard method, static method, or class method.

This is the base class of the SphinxAdapter class which is used to update the wrapped object docstring.

You can also inherit this class to change the deprecation message.

In the following example, we change the message into “The … is deprecated.”:

import inspect

from deprecated.classic import ClassicAdapter
from deprecated.classic import deprecated


class MyClassicAdapter(ClassicAdapter):
    def get_deprecated_msg(self, wrapped, instance):
        if instance is None:
            if inspect.isclass(wrapped):
                fmt = "The class {name} is deprecated."
            else:
                fmt = "The function {name} is deprecated."
        else:
            if inspect.isclass(instance):
                fmt = "The class method {name} is deprecated."
            else:
                fmt = "The method {name} is deprecated."
        if self.reason:
            fmt += " ({reason})"
        if self.version:
            fmt += " -- Deprecated since version {version}."
        return fmt.format(name=wrapped.__name__,
                          reason=self.reason or "",
                          version=self.version or "")

Then, you can use your MyClassicAdapter class like this in your source code:

@deprecated(reason="use another function", adapter_cls=MyClassicAdapter)
def some_old_function(x, y):
    return x + y
get_deprecated_msg(wrapped, instance)

Get the deprecation warning message for the user.

Parameters:

  • wrapped – Wrapped class or function.

  • instance – The object to which the wrapped function was bound when it was called.

Returns:

The warning message.

deprecated.classic.deprecated(*args, **kwargs)

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.

Classic usage:

To use this, decorate your deprecated function with @deprecated decorator:

from deprecated import deprecated


@deprecated
def some_old_function(x, y):
    return x + y

You can also decorate a class or a method:

from deprecated import deprecated


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


@deprecated
class SomeOldClass(object):
    pass

You can give a reason message to help the developer to choose another function/class, and a version number to specify the starting version number of the deprecation.

from deprecated import deprecated


@deprecated(reason="use another function", version='1.2.0')
def some_old_function(x, y):
    return x + y

The category keyword argument allow you to specify the deprecation warning class of your choice. By default, DeprecationWarning is used, but you can choose FutureWarning, PendingDeprecationWarning or a custom subclass.

from deprecated import deprecated


@deprecated(category=PendingDeprecationWarning)
def some_old_function(x, y):
    return x + y

The action keyword argument allow you to locally change the warning filtering. action can be one of “error”, “ignore”, “always”, “default”, “module”, or “once”. If None, empty or missing, the global filtering mechanism is used. See: The Warnings Filter in the Python documentation.

from deprecated import deprecated


@deprecated(action="error")
def some_old_function(x, y):
    return x + y

The extra_stacklevel keyword argument allows you to specify additional stack levels to consider instrumentation rather than user code. With the default value of 0, the warning refers to where the class was instantiated or the function was called.

Sphinx directive integration

We usually need to document the life-cycle of functions and classes: when they are created, modified or deprecated.

To do that, Sphinx has a set of Paragraph-level markups:

  • versionadded: to document the version of the project which added the described feature to the library,

  • versionchanged: to document changes of a feature,

  • deprecated: to document a deprecated feature.

The purpose of this module is to defined decorators which adds this Sphinx directives to the docstring of your function and classes.

Of course, the @deprecated decorator will emit a deprecation warning when the function/method is called or the class is constructed.

class deprecated.sphinx.SphinxAdapter(directive, reason='', version='', action=None, category=<class 'DeprecationWarning'>, extra_stacklevel=0, line_length=70)

Sphinx adapter – for advanced usage only

This adapter override the ClassicAdapter in order to add the Sphinx directives to the end of the function/class docstring. Such a directive is a Paragraph-level markup

  • The directive can be one of “versionadded”, “versionchanged” or “deprecated”.

  • The version number is added if provided.

  • The reason message is obviously added in the directive block if not empty.

get_deprecated_msg(wrapped, instance)

Get the deprecation warning message (without Sphinx cross-referencing syntax) for the user.

Parameters:

  • wrapped – Wrapped class or function.

  • instance – The object to which the wrapped function was bound when it was called.

Returns:

The warning message.

Added in version 1.2.12: Strip Sphinx cross-referencing syntax from warning message.

deprecated.sphinx.deprecated(reason='', version='', line_length=70, **kwargs)

This decorator can be used to insert a “deprecated” directive in your function/class docstring in order to document the version of the project which deprecates this functionality in your library.

Parameters:

  • reason (str) – Reason message which documents the deprecation in your library (can be omitted).

  • version (str) – Version of your project which deprecates this feature. If you follow the Semantic Versioning, the version number has the format “MAJOR.MINOR.PATCH”.

  • line_length (int) – Max line length of the directive text. If non nul, a long text is wrapped in several lines.

Keyword arguments can be:

  • “action”: A warning filter used to activate or not the deprecation warning. Can be one of “error”, “ignore”, “always”, “default”, “module”, or “once”. If None, empty or missing, the global filtering mechanism is used.

  • “category”: The warning category to use for the deprecation warning. By default, the category class is DeprecationWarning, you can inherit this class to define your own deprecation warning category.

  • “extra_stacklevel”: Number of additional stack levels to consider instrumentation rather than user code. With the default value of 0, the warning refers to where the class was instantiated or the function was called.

Returns:

a decorator used to deprecate a function.

Changed in version 1.2.13: Change the signature of the decorator to reflect the valid use cases.

Changed in version 1.2.15: Add the extra_stacklevel parameter.

deprecated.sphinx.versionadded(reason='', version='', line_length=70)

This decorator can be used to insert a “versionadded” directive in your function/class docstring in order to document the version of the project which adds this new functionality in your library.

Parameters:

  • reason (str) – Reason message which documents the addition in your library (can be omitted).

  • version (str) –

    Version of your project which adds this feature. If you follow the Semantic Versioning, the version number has the format “MAJOR.MINOR.PATCH”, and, in the case of a new functionality, the “PATCH” component should be “0”.

  • line_length (int) – Max line length of the directive text. If non nul, a long text is wrapped in several lines.

Returns:

the decorated function.

deprecated.sphinx.versionchanged(reason='', version='', line_length=70)

This decorator can be used to insert a “versionchanged” directive in your function/class docstring in order to document the version of the project which modifies this functionality in your library.

Parameters:

  • reason (str) – Reason message which documents the modification in your library (can be omitted).

  • version (str) –

    Version of your project which modifies this feature. If you follow the Semantic Versioning, the version number has the format “MAJOR.MINOR.PATCH”.

  • line_length (int) – Max line length of the directive text. If non nul, a long text is wrapped in several lines.

Returns:

the decorated function.