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 chooseFutureWarning
,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 markupThe 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.