python标准库中的装饰器(具体为@deprecated)

Question

我需要将例程标记为已弃用,但显然没有标准的库装饰器可供弃用.我知道它的配方和警告模块,但我的问题是:为什么这个(常见)任务没有标准的库装饰器？

附加问题:标准库中是否有标准装饰器？

Answer 1

这里有一些片段,根据Leandro引用的片段进行修改:

import warnings
import functools

def deprecated(func):
    """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."""
    @functools.wraps(func)
    def new_func(*args, **kwargs):
        warnings.simplefilter('always', DeprecationWarning)  # turn off filter
        warnings.warn("Call to deprecated function {}.".format(func.__name__),
                      category=DeprecationWarning,
                      stacklevel=2)
        warnings.simplefilter('default', DeprecationWarning)  # reset filter
        return func(*args, **kwargs)
    return new_func

# Examples

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

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

因为在某些解释器中,暴露的第一个解决方案(没有过滤器处理)可能会导致警告抑制.

Answer 2

这是另一个解决方案:

这个装饰器(实际上是一个装饰工厂)允许你给出一个原因信息.通过提供源文件名和行号来帮助开发人员诊断问题也更有用.

编辑:此代码使用Zero的建议:它替换warnings.warn_explicitline by warnings.warn(msg, category=DeprecationWarning, stacklevel=2),它打印函数调用站点而不是函数定义站点.它使调试更容易.

EDIT2:此版本允许开发人员指定可选的"原因"消息.

import functools
import inspect
import warnings

string_types = (type(b''), type(u''))


def deprecated(reason):
    """
    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.
    """

    if isinstance(reason, string_types):

        # The @deprecated is used with a 'reason'.
        #
        # .. code-block:: python
        #
        #    @deprecated("please, use another function")
        #    def old_function(x, y):
        #      pass

        def decorator(func1):

            if inspect.isclass(func1):
                fmt1 = "Call to deprecated class {name} ({reason})."
            else:
                fmt1 = "Call to deprecated function {name} ({reason})."

            @functools.wraps(func1)
            def new_func1(*args, **kwargs):
                warnings.simplefilter('always', DeprecationWarning)
                warnings.warn(
                    fmt1.format(name=func1.__name__, reason=reason),
                    category=DeprecationWarning,
                    stacklevel=2
                )
                warnings.simplefilter('default', DeprecationWarning)
                return func1(*args, **kwargs)

            return new_func1

        return decorator

    elif inspect.isclass(reason) or inspect.isfunction(reason):

        # The @deprecated is used without any 'reason'.
        #
        # .. code-block:: python
        #
        #    @deprecated
        #    def old_function(x, y):
        #      pass

        func2 = reason

        if inspect.isclass(func2):
            fmt2 = "Call to deprecated class {name}."
        else:
            fmt2 = "Call to deprecated function {name}."

        @functools.wraps(func2)
        def new_func2(*args, **kwargs):
            warnings.simplefilter('always', DeprecationWarning)
            warnings.warn(
                fmt2.format(name=func2.__name__),
                category=DeprecationWarning,
                stacklevel=2
            )
            warnings.simplefilter('default', DeprecationWarning)
            return func2(*args, **kwargs)

        return new_func2

    else:
        raise TypeError(repr(type(reason)))

您可以将此装饰器用于函数,方法和类.

这是一个简单的例子:

@deprecated("use another function")
def some_old_function(x, y):
    return x + y


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


@deprecated("use another class")
class SomeOldClass(object):
    pass


some_old_function(5, 3)
SomeClass().some_old_method(8, 9)
SomeOldClass()

你会得到:

deprecated_example.py:59: DeprecationWarning: Call to deprecated function or method some_old_function (use another function).
  some_old_function(5, 3)
deprecated_example.py:60: DeprecationWarning: Call to deprecated function or method some_old_method (use another method).
  SomeClass().some_old_method(8, 9)
deprecated_example.py:61: DeprecationWarning: Call to deprecated class SomeOldClass (use another class).
  SomeOldClass()

EDIT3:这个装饰器现在是Deprecated库的一部分:

• Python包索引(PyPi)
• GitHub网站
• 阅读文档
• Lulu.com上的电子书

新的稳定版本v1.2.4

Answer 3

未来的 Python 版本（3.12 之后）将包含warnings.deprecated装饰器，该装饰器将指示弃用类型检查器，例如mypy.

作为一个例子，考虑这个名为library.pyi的库存根：

from warnings import deprecated

@deprecated("Use Spam instead")
class Ham: ...

@deprecated("It is pining for the fiords")
def norwegian_blue(x: int) -> int: ...

@overload
@deprecated("Only str will be allowed")
def foo(x: int) -> str: ...
@overload
def foo(x: str) -> str: ...

以下是类型检查器应如何处理该库的使用：

from library import Ham  # error: Use of deprecated class Ham. Use Spam instead.

import library

library.norwegian_blue(1)  # error: Use of deprecated function norwegian_blue. It is pining for the fiords.
map(library.norwegian_blue, [1, 2, 3])  # error: Use of deprecated function norwegian_blue. It is pining for the fiords.

library.foo(1)  # error: Use of deprecated overload for foo. Only str will be allowed.
library.foo("x")  # no error

ham = Ham()  # no error (already reported above)

来源：PEP702

Answer 4

如muon所建议，您可以deprecation为此安装软件包。

该deprecation库为您的测试提供了一个deprecated装饰器和一个fail_if_not_removed装饰器。

安装

pip install deprecation

用法示例

import deprecation

@deprecation.deprecated(deprecated_in="1.0", removed_in="2.0",
                        current_version=__version__,
                        details="Use the bar function instead")
def foo():
    """Do some stuff"""
    return 1

有关完整文档，请参见http://deprecation.readthedocs.io/。

Answer 5

我想原因是Python代码不能静态处理(就像它对C++编译器所做的那样),在实际使用之前你不能得到关于使用某些东西的警告.我不认为用一堆消息向您的脚本用户发送垃圾邮件是"好主意""警告:此脚本的开发人员正在使用已弃用的API".

更新:但您可以创建装饰器,将原始功能转换为另一个.新功能将标记/检查开关,告知该功能已被调用,并且仅在转换为开启状态时显示消息.和/或在退出时,它可以打印程序中使用的所有已弃用函数的列表.

Answer 6

您可以创建一个utils文件

import warnings

def deprecated(message):
  def deprecated_decorator(func):
      def deprecated_func(*args, **kwargs):
          warnings.warn("{} is a deprecated function. {}".format(func.__name__, message),
                        category=DeprecationWarning,
                        stacklevel=2)
          warnings.simplefilter('default', DeprecationWarning)
          return func(*args, **kwargs)
      return deprecated_func
  return deprecated_decorator

然后导入弃用装饰器,如下所示:

from .utils import deprecated

@deprecated("Use method yyy instead")
def some_method()"
 pass