python 标准库中的装饰器（特别是@deprecated）
Posted
技术标签:
【中文标题】python 标准库中的装饰器（特别是@deprecated）【英文标题】：decorators in the python standard lib (@deprecated specifically) 【发布时间】：2011-02-01 22:32:54 【问题描述】：我需要将例程标记为已弃用，但显然没有可弃用的标准库装饰器。我知道它的配方和警告模块，但我的问题是：为什么这个（常见）任务没有标准库装饰器？
附加问题：标准库中是否有标准装饰器？
【问题讨论】：
现在有一个deprecation 包 我了解这样做的方法，但来到这里是为了了解为什么它不在标准库中（我认为是 OP 的情况）并且没有看到一个好的答案实际问题 为什么经常出现这样的问题，以至于问题得到了几十个甚至没有尝试回答问题的答案，并且主动忽略了诸如“我知道食谱”之类的东西？太疯狂了！ @Catskul 因为假网点。 您可以使用Deprecated 库。 【参考方案1】：我猜原因是 Python 代码不能被静态处理（就像 C++ 编译器所做的那样），在实际使用它之前你不会收到关于使用某些东西的警告。我认为向您的脚本用户发送大量消息“警告：此脚本的此开发人员正在使用已弃用的 API”向用户发送垃圾邮件并不是一个好主意。
更新： 但您可以创建将原始功能转换为另一个功能的装饰器。新功能将标记/检查开关，告知该功能已被调用，并且仅在将开关变为开启状态时才会显示消息。和/或在退出时它可能会打印程序中使用的所有已弃用函数的列表。
【讨论】：
并且您应该能够在从模块导入函数时指出弃用。 Decorator 将是一个合适的工具。 @JanuszLenar，即使我们不使用已弃用的功能，也会显示该警告。但我想我可以用一些提示更新我的答案。【参考方案2】：这里有一些 sn-p，根据 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
因为在某些解释器中，第一个暴露的解决方案（没有过滤器处理）可能会导致警告抑制。
【讨论】：
为什么不使用functools.wraps 而不是像那样设置名称和文档？
@Maximilian：编辑添加了这一点，以防止将来复制此代码的人也犯错
我不喜欢副作用（打开/关闭过滤器）。决定这一点不是装饰者的工作。
开启和关闭过滤器可能会触发bugs.python.org/issue29672
没有回答实际问题。【参考方案3】：
这是另一个解决方案：
这个装饰器（实际上是decorator factory）允许你给出一个reason信息。通过提供源文件名和行号来帮助开发人员诊断问题也更有用。
编辑：此代码使用 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：这个装饰器现在是弃用库的一部分：
Python package index (PyPi) GitHub website Read The Docs Twitter新的稳定版本 v1.2.13 ?
【讨论】：
工作，好吧 - 我更喜欢用warnings.warn(msg, category=DeprecationWarning, stacklevel=2) 替换 warn_explicit 行，它打印函数调用站点而不是函数定义站点。它使调试更容易。
您好，我想在a GPLv3-licensed library 中使用您的代码sn-p。您是否愿意根据 GPLv3 or any more permissive license 重新许可您的代码，以便我可以合法地这样做？
@LaurentLAPORTE 我知道。 CC-BY-SO 不允许在 GPLv3 中使用（因为 share-alike 位），这就是为什么我要问您是否愿意在与 GPL 兼容的许可下特别发布此代码。如果没有，那很好，我不会使用你的代码。
没有回答实际问题。
@DannyVarod 我知道，但是对于代码，CC-BY-SA 比 GPL 更严格。当我问这个问题时，我正在研究 GPL 库。 GPL 库可以使用 GPL 代码或更宽松的代码，但 GPL 库可以不使用 CC-BY-SA 代码，所以我无法使用这个代码 sn-p。 （无论如何，CC-BY-SA 从未用于代码；在更宽松的情况下，SO 在用户贡献中许可代码 sn-ps 会做得很好，因为就像现在一样，大多数用户不能使用他们在 SO 上找到的代码 sn-ps )【参考方案4】：
更新：我认为更好的是，当我们只为每个代码行第一次显示 DeprecationWarning 并且我们可以发送一些消息时：
import inspect
import traceback
import warnings
import functools
import time
def deprecated(message: str = ''):
"""
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 first time and filter is set for show DeprecationWarning.
"""
def decorator_wrapper(func):
@functools.wraps(func)
def function_wrapper(*args, **kwargs):
current_call_source = '|'.join(traceback.format_stack(inspect.currentframe()))
if current_call_source not in function_wrapper.last_call_source:
warnings.warn("Function is now deprecated! ".format(func.__name__, message),
category=DeprecationWarning, stacklevel=2)
function_wrapper.last_call_source.add(current_call_source)
return func(*args, **kwargs)
function_wrapper.last_call_source = set()
return function_wrapper
return decorator_wrapper
@deprecated('You must use my_func2!')
def my_func():
time.sleep(.1)
print('aaa')
time.sleep(.1)
def my_func2():
print('bbb')
warnings.simplefilter('always', DeprecationWarning) # turn off filter
print('before cycle')
for i in range(5):
my_func()
print('after cycle')
my_func()
my_func()
my_func()
结果：
before cycle
C:/Users/adr-0/OneDrive/Projects/Python/test/unit1.py:45: DeprecationWarning: Function my_func is now deprecated! You must use my_func2!
aaa
aaa
aaa
aaa
aaa
after cycle
C:/Users/adr-0/OneDrive/Projects/Python/test/unit1.py:47: DeprecationWarning: Function my_func is now deprecated! You must use my_func2!
aaa
C:/Users/adr-0/OneDrive/Projects/Python/test/unit1.py:48: DeprecationWarning: Function my_func is now deprecated! You must use my_func2!
aaa
C:/Users/adr-0/OneDrive/Projects/Python/test/unit1.py:49: DeprecationWarning: Function my_func is now deprecated! You must use my_func2!
aaa
Process finished with exit code 0
我们只需点击警告路径，然后转到 PyCharm 中的行。
【讨论】：
没有回答实际问题。【参考方案5】：你可以创建一个 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
然后导入deprecation装饰器如下：
from .utils import deprecated
@deprecated("Use method yyy instead")
def some_method()"
pass
【讨论】：
谢谢，我正在使用它来将用户发送到正确的位置，而不仅仅是显示弃用消息！ 没有回答实际问题。【参考方案6】：As muon suggested，您可以为此安装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/。
【讨论】：
没有回答实际问题。 注意 PyCharm 无法识别此以上是关于python 标准库中的装饰器（特别是@deprecated）的主要内容，如果未能解决你的问题，请参考以下文章