我需要将例程标记为已弃用的，但显然没有标准库装饰器来实现这个目的。我知道有关此任务的建议和警告模块，但我的问题是：为什么没有标准库装饰器来处理这个（常见）任务？
另外一个问题：标准库中是否有标准的装饰器？
Python标准库中的装饰器（特别是@deprecated）
226
- Stefano Borini
8
23现在有一个名为 deprecation 的包。 - muon
19我了解如何完成它，但是我来这里是为了了解为什么它不在标准库中（正如我认为OP的情况），并且没有看到一个好的回答实际的问题。 - SwimBikeRun
20为什么经常会出现这样的情况，即问题得到了数十个回答，但它们甚至没有试图回答问题，并且积极忽略了一些事情，比如“我知道食谱”？这太疯狂了！ - Catskul
7因为虚假的网络积分。 - Stefano Borini
2我不知道是否有任何反对“为什么”问题的规定，但在我看来，许多“为什么”问题很可能有简洁的答案，而且这些问题/答案可能很重要，所以如果它们被禁止，我会感到难过。 - Catskul
显示剩余3条评论
8个回答
92
这里是一些片段，修改自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
因为在某些解释器中，第一个提出的解决方案（没有过滤处理）可能会导致警告抑制。
- Patrizio Bertoni
8
14为什么不使用
functools.wraps而是像那样设置名称和文档？ - Maximilian33我不喜欢副作用（打开/关闭过滤器）。这不是装饰者的职责来决定。 - Kentzo
1打开或关闭过滤器可能会触发http://bugs.python.org/issue29672。 - gerrit
23未回答实际问题。 - Catskul
4完全同意@Kentzo的观点——禁用过滤器然后将其重置为默认值会让某个开发人员头疼不已。 - Aaron V
显示剩余3条评论
82
这里有另一种解决方案:
这个装饰器（实际上是一个装饰器工厂）可以让你给出一个原因信息。它也更有用，可以通过给出源代码文件名和行号来帮助开发人员诊断问题。
编辑: 这段代码使用了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()
EDIT3:这个装饰器现在已经成为 Deprecated 库的一部分：
新的稳定发行版 v1.2.13
- Laurent LAPORTE
7
6可以这样翻译：效果很好——我更喜欢用
warnings.warn(msg, category=DeprecationWarning, stacklevel=2)替换warn_explicit这一行，因为它会打印出函数调用位置而不是函数定义位置，这样可以更方便地进行调试。 - Zero1@LaurentLAPORTE 我知道。CC-BY-SO不允许在GPLv3内使用（因为共享条款），这就是为什么我要问你是否愿意在GPL兼容的许可证下特别发布此代码。如果不行，没关系，我不会使用你的代码。 - gerrit
13未回答实际问题。 - Catskul
2@DannyVarod 我知道，但对于代码而言，CC-BY-SA比GPL更加严格。当我提出这个问题时，我正在开发一个GPL库。GPL库可以使用GPL代码或更宽松的代码，但是GPL库不能使用CC-BY-SA代码，因此我无法使用这个代码片段。（而且CC-BY-SA从未用于代码；SO在许可用户贡献中的代码片段时应该采用更宽松的许可证，因为现在大多数用户无法使用他们在SO上找到的代码片段） - gerrit
显示剩余2条评论
32
正如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/获取完整文档。
- Stevoisiak
2
16没有回答实际问题。 - Catskul
6注意：PyCharm 无法识别此内容。 - c z
19
你可以创建一个 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
- Erika Dsouza
2
1谢谢，我使用这个来将用户发送到正确的位置，而不仅仅显示弃用消息！ - German Attanasio
13未回答实际问题。 - Catskul
19
我猜原因是Python代码无法像C ++编译器那样静态处理，不能在实际使用之前获得有关某些事物使用的警告。我认为向脚本用户发送大量消息“警告：此脚本的开发者正在使用已弃用的API”并不是一个好主意。
更新：但是您可以创建装饰器，将原始函数转换为另一个函数。新函数将标记/检查开关，说明已调用该函数，并仅在将开关切换为打开状态时显示消息。在退出时，它还可以打印程序中使用的所有已弃用函数的列表。
- ony
2
5当从模块导入函数时，您应该能够指示其已被废弃。 装饰器是实现此功能的正确工具。 - Janusz Lenar
@JanuszLenar，即使我们不使用那个已弃用的函数，该警告也会显示出来。但我想我可以在我的答案中加上一些提示。 - ony
7
Python 3.12将包括
typing.deprecated装饰器，该装饰器将向类型检查器（如mypy）指示已废弃的功能。
As an example, consider this library stub named library.pyi:
from typing 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: ...Here is how type checkers should handle usage of this library:
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)Source: PEP702
- thehale
1
1@Catskul，也许这终于回答了这个问题？ - CervEd
1
Python是一种动态类型的语言。不需要在变量或函数参数类型上进行静态声明。
由于它是动态的，因此所有内容都是在运行时处理的。即使某个方法已过时，也只有在运行时或解释期间才会知道。
使用deprecation模块来弃用方法。
deprecation是一个启用自动弃用的库。 它提供了deprecated()装饰器来包装函数，为文档和通过Python的warnings系统提供适当的警告，以及为测试方法提供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
- devp
1
Python是一种动态类型的语言，但它通过
typing模块实现了静态类型。这种类型在运行时没有任何影响，只被静态分析工具（如mypy或编辑器集成）使用。我对这个答案进行了负评，因为它提出的解决方案在问题描述中明确提到是不令人满意的。运行时警告可以工作，但它们无法告诉mypy或您的编辑器此函数已被弃用。 - undefined0
更新：我认为更好的做法是，当我们只在每行代码第一次显示弃用警告时，并且我们可以发送一些消息：
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 中的警告路径，跳转到相应的代码行。
- ADR
1
8未回答实际问题。 - Catskul
网页内容由stack overflow 提供, 点击上面的可以查看英文原文，
原文链接
原文链接