弃用#
Conda 遵守 CEP-9 中定义的弃用计划。为了尽可能轻松地进行弃用，我们提供了几个辅助装饰器和函数，以方便正确的弃用流程。
提示
conda 待定/弃用版本遵循以下公式
pending_dep = (the next release + 4 months) round up to nearest .3 or .9
deprecation = pending_dep + 6 months
示例
pending_dep = (25.1 + 4 months) round up to nearest .3 or .9 = 25.9
deprecation = 25.9 + 6 months = 26.3
函数、方法、属性和类#
警告
要弃用枚举，请将其视为常量（请参阅常量和枚举）。
最简单的用例是弃用任何函数、方法或属性
示例文件，
foo.py。#from conda.deprecations import deprecated
@deprecated("23.9", "24.3")
def bar():
...
示例调用。#
>>> import foo
>>> foo.bar()
<stdin>:1: PendingDeprecationWarning: foo.bar is pending deprecation and will be removed in 24.3.
作为最低要求，我们必须始终指定两个版本
未来的弃用版本，其中函数、方法或属性将被标记为已弃用；在此之前，该功能将显示为待定弃用（我们将其视为评论期），以及
随后的弃用版本，其中函数、方法或属性将从代码库中删除。
此外，您可以提供附录，告知用户他们应该做什么代替
示例文件，
foo.py。#from conda.deprecations import deprecated
@deprecated("23.9", "24.3", addendum="Use `qux` instead.")
def bar():
...
示例调用。#
>>> import foo
>>> foo.bar()
<stdin>:1: PendingDeprecationWarning: foo.bar is pending deprecation and will be removed in 24.3. Use `qux` instead.
关键字参数#
警告
弃用或重命名位置参数是不必要地复杂的，并且不受支持。 相反，建议 (1) 设计一种自定义方法来检测已弃用的位置参数的使用情况（例如，类型检查），并使用 conda.deprecations.deprecated.topic 函数（请参阅主题）或 (2) 弃用函数/方法本身，并定义一个没有已弃用参数的新函数/方法。
与弃用函数或方法类似，弃用关键字参数也很常见
示例文件，
foo.py。#from conda.deprecations import deprecated
# prior implementation
# def bar(is_true=True):
# ...
@deprecated.argument("23.9", "24.3", "is_true")
def bar():
...
示例调用。#
>>> import foo
>>> foo.bar(is_true=True)
<stdin>:1: PendingDeprecationWarning: foo.bar(is_true) is pending deprecation and will be removed in 24.3.
或重命名关键字参数
示例文件，
foo.py。#from conda.deprecations import deprecated
# prior implementation
# def bar(is_true=True):
# ...
@deprecated.argument("23.9", "24.3", "is_true", rename="enabled")
def bar(enabled=True):
...
示例调用。#
>>> import foo
>>> foo.bar(is_true=True)
<stdin>:1: PendingDeprecationWarning: foo.bar(is_true) is pending deprecation and will be removed in 24.3. Use 'enabled' instead.
argparse.Action#
有时，需要弃用 CLI 参数。 为此，我们提供了一个辅助函数来 monkeypatch 任何 argparse.Action
示例文件，
foo.py。#import argparse
from conda.deprecations import deprecated
parser = argparse.ArgumentParser()
parser.add_argument(
"--force",
dest="yes",
action=deprecated.action(
"23.9",
"24.3",
argparse._StoreTrueAction,
addendum="Use `--yes` instead.",
),
default=False,
)
parser.parse_args()
python foo.py --force
foo.py:16: PendingDeprecationWarning: `--force` is pending deprecation and will be removed in 24.3. Use `--yes` instead.
常量和枚举#
我们还提供了一种弃用全局变量或常量的方法
示例文件，
foo.py。#from conda.deprecations import deprecated
deprecated.constant("23.9", "24.3", "ULTIMATE_CONSTANT", 42)
示例调用。#
>>> import foo
>>> foo.ULTIMATE_CONSTANT
<stdin>:1: PendingDeprecationWarning: foo.ULTIMATE_CONSTANT is pending deprecation and will be removed in 24.3.
枚举的工作方式类似
示例文件，
foo.py。#from enum import Enum
from conda.deprecations import deprecated
class Bar(Enum):
ULTIMATE_CONSTANT = 42
deprecated.constant("23.9", "24.3", "Bar", Bar)
del Bar
示例调用。#
>>> from foo import Bar
<stdin>:1: PendingDeprecationWarning: foo.Bar is pending deprecation and will be removed in 24.3.
注意
常量弃用依赖于 PEP-562 中引入的模块的 __getattr__。
模块#
整个模块也可以被弃用
示例文件，
foo.py。#from conda.deprecations import deprecated
deprecated.module("23.9", "24.3")
示例调用。#
>>> import foo
<stdin>:1: PendingDeprecationWarning: foo is pending deprecation and will be removed in 24.3.
主题#
最后，代码可能以多种其他方式运行，这也需要弃用。 为此，我们提供了一个通用的弃用函数
示例文件，
foo.py。#from conda.deprecations import deprecated
def bar(...):
# some logic
if ...:
deprecated.topic("23.9", "24.3", topic="The <TOPIC>")
# some more logic
示例调用。#
>>> import foo
>>> foo.bar(...)
<stdin>:1: PendingDeprecationWarning: The <TOPIC> is pending deprecation and will be removed in 24.3.