弃用

Conda 遵守 CEP-9 中定义的弃用时间表。为了尽可能使弃用变得简单明了，我们提供了一些辅助装饰器和函数来帮助完成正确的弃用流程。

函数、方法、属性和类

警告

要弃用枚举，请将它们视为常量（参见 常量和枚举）。

最简单的用例是弃用任何函数、方法或属性

示例文件，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.

作为最低要求，我们必须始终指定两个版本

1. 未来弃用版本，其中函数、方法或属性将被标记为弃用；在此之前，该功能将显示为待弃用（我们将其视为评论期），以及

2. 随后的弃用版本，其中函数、方法或属性将从代码库中删除。

此外，您可以提供一个附录来告知用户应该做什么

示例文件，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 参数。为此，我们提供了一个辅助函数来修补任何 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.

注意

常量弃用依赖于模块的 __getattr__，该模块是在 PEP-562 中引入的。

模块

整个模块也可以被弃用

示例文件，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.