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_explicit 行替换为 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 网站
• 阅读文档
• Twitter

新稳定版本 v1.2.13

Answer 3

未来的 Python 版本（3.13 之后）将包含 warnings.deprecated 装饰器 表示不推荐使用诸如 mypy 之类的类型检查器。

作为示例，请考虑名为library.pyi 的库存根：

from warnings import 已弃用

@deprecated("使用垃圾邮件代替")
火腿班：...

@deprecated(“它渴望峡湾”)
defnorwegian_blue(x:int)->;整数：...

@超载
@deprecated(“仅允许使用 str”)
def foo(x: int) ->;斯特：...
@超载
def foo(x: str) ->;斯特：...

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

from library import Ham # 错误：使用已弃用的 Ham 类。请改用垃圾邮件。

导入库

library.norwegian_blue(1) # 错误：使用已弃用的函数norwegian_blue。它渴望峡湾。
map(library.norwegian_blue, [1, 2, 3]) # 错误：使用已弃用的函数norwegian_blue。它渴望峡湾。

library.foo(1) # 错误：对 foo 使用已弃用的重载。仅允许 str。
library.foo("x") # 没有错误

ham = Ham() # 没有错误（上面已经报告过）

<块引用>

来源：PEP702

Answer 4

按照 muon 的建议，您可以安装 弃用 包。

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

Answer 7

Python 是一种动态类型语言。不必静态地将函数的类型声明为变量或参数类型。

因为它是动态的，如果在运行时处理的话，一切都是动态的。即使某个方法已被弃用，它也只能在运行时或解释期间知道。

使用 deprecation 模块来弃用方法。

deprecation 是一个支持自动弃用的库。它
提供 deprecated() 装饰器来包装功能，提供适当的
文档中和 Python 的警告 警告< /strong> 系统，如
以及 deprecation.fail_if_not_removed()用于测试的装饰器
确保最终删除不推荐使用的代码的方法。

安装：

python3.10 -m pip install deprecation

小演示：

import deprecation

@deprecation.deprecated(details="Use bar instead")
def foo():
    print("Foo")


def bar():
    print("Bar")


foo()

bar()

输出：

test.py: DeprecatedWarning: foo is deprecated. Use bar instead
  foo()

Foo

Bar