Python标准库中的装饰器（@deprecated特指）

Question

我想把一些程序里的功能标记为不推荐使用，但好像没有一个标准的库可以直接做到这一点。我知道有一些方法可以实现这个功能，比如使用警告模块，但我想问的是：为什么没有一个标准的装饰器来处理这个常见的任务呢？

还有一个附加问题：标准库里有没有其他的标准装饰器呢？

Answer 1

正如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 2

这里有另一个解决方案：

这个装饰器（实际上是一个装饰器工厂）可以让你提供一个原因消息。它还可以帮助开发者更好地诊断问题，因为它会给出源文件名和行号。

编辑：这段代码使用了Zero的建议：它把warnings.warn_explicit这一行替换成了warnings.warn(msg, category=DeprecationWarning, stacklevel=2)，这样可以打印出函数调用的位置，而不是函数定义的位置。这让调试变得更简单。

编辑2：这个版本允许开发者指定一个可选的“原因”消息。

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()

编辑3：这个装饰器现在是Deprecated库的一部分：

• Python包索引（PyPi）
• GitHub网站
• 文档网站
• 推特

新稳定版本 v1.2.13

Answer 3

这里有一段代码，是根据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

因为在某些解释器中，第一种解决方案（没有处理过滤器的那种）可能会导致警告被抑制。