d& d Z ddlZddlZddlZddlZddlZ ddlZdZdZ e d e d fZ G d d ej Zd
Zy# e $ r dZ ej dk( rdZndZY Kw xY w) z
Classic deprecation warning
===========================
Classic ``@deprecated`` decorator to deprecate old python classes, functions or methods.
.. _The Warnings Filter: https://docs.python.org/3/library/warnings.html#the-warnings-filter
N PyPy c 8 e Zd ZdZdddef fd Zd Zd Z xZS )ClassicAdaptera8
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 :class:`~deprecated.sphinx.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.":
.. code-block:: python
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:
.. code-block:: python
@deprecated(reason="use another function", adapter_cls=MyClassicAdapter)
def some_old_function(x, y):
return x + y
r Nc r |xs d| _ |xs d| _ || _ || _ t t
| y)aQ
Construct a wrapper adapter.
:type reason: str
:param reason:
Reason message which documents the deprecation in your library (can be omitted).
:type version: str
:param version:
Version of your project which deprecates this feature.
If you follow the `Semantic Versioning `_,
the version number has the format "MAJOR.MINOR.PATCH".
:type action: str
:param 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`` or empty, the the global filtering mechanism is used.
See: `The Warnings Filter`_ in the Python documentation.
:type category: type
:param category:
The warning category to use for the deprecation warning.
By default, the category class is :class:`~DeprecationWarning`,
you can inherit this class to define your own deprecation warning category.
r N)reasonversionactioncategorysuperr __init__)selfr r r
r __class__s 4/usr/lib/python3/dist-packages/deprecated/classic.pyr zClassicAdapter.__init__V s6 6 l }"
nd,.r c ( |t j | rd}n d}nt j | rd}nd}| j r|dz
}| j r|dz
}|j |j
| j xs d| j xs d S ) z
Get the deprecation warning message for the user.
:param wrapped: Wrapped class or function.
:param instance: The object to which the wrapped function was bound when it was called.
:return: The warning message.
z Call to deprecated class {name}.z5Call to deprecated function (or staticmethod) {name}.z'Call to deprecated class method {name}.z!Call to deprecated method {name}.z ({reason})z' -- Deprecated since version {version}.r )namer r )inspectisclassr r format__name__)r wrappedinstancefmts r get_deprecated_msgz!ClassicAdapter.get_deprecated_msgw s w'8Mx(?9 ;; = C << < .wrapped_cls s --gt<;;!002 a --dkk4==I
cDMMN_`a a MM#
J[\v~~-#C=( 5d5f55a as ACC#)r r r( staticmethod)r r r. r- s `` @r __call__zClassicAdapter.__call__ s2 ??7 # H
6 +; 7GOr ) r
__module__ __qualname____doc__DeprecationWarningr r r0
__classcell__)r s @r r r # s& 0d !"TDV /Bg4 r r c j | r t | d t r
| d |d< | dd } | r.t | d s t t t | d | r|j
d |j
dt |j dt } |d
i || d }t j | r
| }|S t j | r(t j fd } || S t t t | t j t" fi |S ) a
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:
.. code-block:: python
from deprecated import deprecated
@deprecated
def some_old_function(x, y):
return x + y
You can also decorate a class or a method:
.. code-block:: python
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.
.. code-block:: python
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, :exc:`DeprecationWarning` is used but you can choose :exc:`FutureWarning`,
:exc:`PendingDeprecationWarning` or a custom subclass.
.. code-block:: python
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 the global filtering mechanism is used.
See: `The Warnings Filter`_ in the Python documentation.
.. code-block:: python
from deprecated import deprecated
@deprecated(action="error")
def some_old_function(x, y):
return x + y
r r Nr
r adapter_cls)adapterc , j | | }rPt j 5 t j t j |t
d d d n t j |t
| |i |S # 1 sw Y xY wr )r r" r# r$ r% _routine_stacklevel)wrapped_ instance_args_kwargs_r, r
r9 r s r wrapper_functionz$deprecated..wrapper_function s 009E!002 ^ --fh?
cHI\]^ ^ MM#EXY 2'22 ^ ^s 3B
B )
isinstance string_typescallable TypeErrorreprtypegetr4 popr r r isroutinewrapt decorator functoolspartial
deprecated)r* r+ r8 r r@ r
r9 r s @@@r rO rO s X
47L1 7xABx HT!W%T$q']+,, H%::j*<= jj ? ''q' ??7 # g&GN
w
'
__W
-
3 .
3 $G, , Dg /0 0 Z 26 22r )r3 rM r platformr" rK wrapt._wrappersr; r& ImportErrorpython_implementationrG rC AdapterFactoryr rO rA r r rU s
S 49% NU)) Nbp3w %x%%'61 s A A,+A,