API

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

deprecat

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

Classic deprecation warning

Classic @deprecat decorator to deprecate python classes, functions, methods or kwargs.

class deprecat.classic.ClassicAdapter(reason='', version='', action=None, deprecated_args=None, category=<class 'DeprecationWarning'>)

Classic 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.

Parameters

reason: str

Reason for deprecation of this method or class.

version: str

Version of your project which deprecates this method or class.

action: str

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

deprecated_args: dict

Dictionary in the following format to deprecate x and y deprecated_args = {‘x’: {‘reason’: ‘some reason’,’version’: ‘1.0’}, ‘y’: {‘reason’: ‘another reason’,’version’: ‘2.0’}}

category: class

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.

get_deprecated_msg(wrapped, instance, kwargs)

Get the deprecation warning message for the user.

Parameters

wrapped: object

Wrapped class or function.

instance: object

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

kwargs:

The kwargs of the wrapped function.

Returns

The warning message.

__call__(wrapped)

Decorate your class or function.

Parameters

wrapped: object

Wrapped class or function.

Returns

Decorated class or function.

deprecat.classic.deprecat(*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.

Sphinx directive integration

The purpose of this module is to defined decorators which adds this Sphinx directives to the docstring of your function and classes. Additionally, the @deprecat decorator will emit a deprecation warning when the function/method is called or the class is constructed.

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:

• deprecated: to document a deprecated feature.

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

Construct a wrapper adapter.

Parameters

reason: str

Reason for deprecation.

version: str

Version of your project which deprecates this feature.

action: str

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

deprecated_args: dict

Dictionary in the following format to deprecate x and y deprecated_args = {‘x’: {‘reason’: ‘some reason’,’version’: ‘1.0’},’y’: {‘reason’: ‘another reason’,’version’: ‘2.0’}}

category: class

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.

line_length: numeric

Max line length of the directive text. If non null, a long text is wrapped in several lines.

directive: {“versionadded”, “versionchanged”, “deprecated”}

Sphinx directive

Warning

deprecat supports docstring modification for deprecated_args only in the numpydoc format, if your documentation uses any other format, this won’t work. Later we might add support for other formats, for now there are no such plans.

Notes

Sphinx adapter overrides 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 added in the directive block if not empty.

See also

We use admonitions in sphinx to render warnings for every deprecated argument just below its description in docstring. refer to this link for more information.

__call__(wrapped)

Add the Sphinx directive to your class or function.

Parameters

wrapped: object

Wrapped class or function.

Returns

the decorated class or function.

get_deprecated_msg(wrapped, instance, kwargs)

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.

kwargs:

The kwargs of the wrapped function.

Returns

The warning message.

deprecat.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 documents the version of the project which adds this new functionality in your library.

Parameters

reason: str

Reason for deprecation of this method or class.

version: str

Version of your project which deprecates this method or class.

line_length: numeric

Max line length of the directive text. If non null, a long text is wrapped in several lines.

Returns

Decorator used to modify docstring.

deprecat.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 documents the version of the project which modifies this functionality in your library.

Parameters

reason: str

Reason for deprecation of this method or class.

version: str

Version of your project which deprecates this method or class.

line_length: numeric

Max line length of the directive text. If non null, a long text is wrapped in several lines.

Returns

Decorator used to modify docstring.

deprecat.sphinx.deprecat(reason='', directive='deprecated', version='', line_length=70, deprecated_args=None, **kwargs)

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

Parameters

reason: str

Reason for deprecation of this method or class.

version: str

Version of your project which deprecates this method or class.

action: str

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

: str

String of kwargs to be deprecated, e.g. “x y” to deprecate x and y.

category: class

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.

line_length: numeric

Max line length of the directive text. If non null, a long text is wrapped in several lines.

deprecated_args: dict

Dictionary in the following format to deprecate x and y deprecated_args = {‘x’: {‘reason’: ‘some reason’,’version’: ‘1.0’},’y’: {‘reason’: ‘another reason’, ‘version’: ‘2.0’}}

Returns

Decorator used to deprecate a function, method, class or kwarg.

Examples

This module contains examples for the deprecat package.

class deprecat.example.test_deprecat_on_class(*args, **kwargs)

Here we test deprecation on a class, like this one.

Deprecated since version 2.0: useless

class deprecat.example.test_deprecat_on_class_method

randomfunction(a, b)

Here we test deprecation on a method of a class, like this one.

Deprecated since version 2.0: useless

deprecat.example.test_deprecat_on_function(a, b)

Here we test deprecation on a function.

Deprecated since version 2.0: useless

deprecat.example.test_deprecated_args(a, b, c=3, d=4)

Here we test deprecation on a function with arguments.

Parameters

aint

This is the first argument.

Deprecated

Parameter a deprecated since 4.0

bint

This is the second argument.

cint, optional

This is the third argument.

dint, optional

This is the fourth argument.

Returnsint

This is the return value.