弃用

用于弃用类、函数和函数参数的装饰器。

类型变量

class T
TypeVar('T')

函数

deprecated(func: Callable[[...], T], since: str | None = None, until: str | None = None, replacement: str | None = None, message: str | None = '') → Callable[[...], T][source]
deprecated(func: None = None, since: str | None = None, until: str | None = None, replacement: str | None = None, message: str | None = '') → Callable[[Callable[[...], T]], Callable[[...], T]]

用于将可调用对象标记为弃用的装饰器。

被装饰的可调用对象在使用时将发出警告。弃用可调用对象的文档字符串（docstring）会进行调整，以表明该可调用对象已被弃用。

参数:

  • func – 要装饰的函数。不应由用户设置。

  • since – 弃用开始的版本或日期。

  • until – 弃用可调用对象被移除的版本或日期。

  • replacement – 替换弃用可调用对象的标识符。

  • message – 可调用对象被弃用的原因。

返回:

被装饰的可调用对象。

返回类型:

可调用对象

示例

基本用法

from manim.utils.deprecation import deprecated

@deprecated
def foo(**kwargs):
    pass


@deprecated
class Bar:
    def __init__(self):
        pass

    @deprecated
    def baz(self):
        pass


foo()
# WARNING  The function foo has been deprecated and may be removed in a later version.

a = Bar()
# WARNING  The class Bar has been deprecated and may be removed in a later version.

a.baz()
# WARNING  The method Bar.baz has been deprecated and may be removed in a later version.

您可以指定更多信息以获得更精确的警告

from manim.utils.deprecation import deprecated


@deprecated(
    since="v0.2", until="v0.4", replacement="bar", message="It is cooler."
)
def foo():
    pass


foo()
# WARNING  The function foo has been deprecated since v0.2 and is expected to be removed after v0.4. Use bar instead. It is cooler.

您也可以使用日期而非版本

from manim.utils.deprecation import deprecated


@deprecated(since="05/01/2021", until="06/01/2021")
def foo():
    pass


foo()
# WARNING  The function foo has been deprecated since 05/01/2021 and is expected to be removed after 06/01/2021.
deprecated_params(params=None, since=None, until=None, message='', redirections=None)[source]

用于将可调用对象的参数标记为弃用的装饰器。

它也可以用于将弃用的参数值自动重定向到其替代值。

参数:

  • params (str | Iterable[str] | None) –

    要弃用的参数。可以包含

    • 一个字符串可迭代对象，其中每个元素代表一个要弃用的参数

    • 单个字符串，参数名称由逗号或空格分隔。

  • since (str | None) – 弃用开始的版本或日期。

  • until (str | None) – 弃用可调用对象被移除的版本或日期。

  • message (str) – 可调用对象被弃用的原因。

  • redirections (None | Iterable[tuple[str, str] | Callable[[...], dict[str, Any]]]) –

    参数重定向列表。每个重定向可以是以下之一

    • 一个包含两个字符串的元组。第一个字符串定义弃用参数的名称；第二个字符串定义要重定向到的参数的名称，当尝试使用第一个字符串时。

    • 执行映射操作的函数。函数的参数名称决定了哪些参数用作输入。函数必须返回一个包含重定向参数的字典。

    重定向的参数也会被隐式弃用。

返回:

被装饰的可调用对象。

返回类型:

可调用对象

抛出:

  • ValueError – 如果未定义任何参数（无论是显式还是隐式）。

  • ValueError – 如果定义的参数是无效的 Python 标识符。

示例

基本用法

from manim.utils.deprecation import deprecated_params

@deprecated_params(params="a, b, c")
def foo(**kwargs):
    pass


foo(x=2, y=3, z=4)
# No warning

foo(a=2, b=3, z=4)
# WARNING  The parameters a and b of method foo have been deprecated and may be removed in a later version.

您还可以指定额外信息以获得更精确的警告

from manim.utils.deprecation import deprecated_params


@deprecated_params(
    params="a, b, c",
    since="v0.2",
    until="v0.4",
    message="The letters x, y, z are cooler.",
)
def foo(**kwargs):
    pass


foo(a=2)
# WARNING  The parameter a of method foo has been deprecated since v0.2 and is expected to be removed after v0.4. The letters x, y, z are cooler.

基本参数重定向

from manim.utils.deprecation import deprecated_params


@deprecated_params(
    redirections=[
        # Two ways to redirect one parameter to another:
        ("old_param", "new_param"),
        lambda old_param2: {"new_param22": old_param2},
    ]
)
def foo(**kwargs):
    return kwargs


foo(x=1, old_param=2)
# WARNING  The parameter old_param of method foo has been deprecated and may be removed in a later version.
# returns {"x": 1, "new_param": 2}

使用计算值进行重定向

from manim.utils.deprecation import deprecated_params


@deprecated_params(
    redirections=[lambda runtime_in_ms: {"run_time": runtime_in_ms / 1000}]
)
def foo(**kwargs):
    return kwargs


foo(runtime_in_ms=500)
# WARNING  The parameter runtime_in_ms of method foo has been deprecated and may be removed in a later version.
# returns {"run_time": 0.5}

将多个参数值重定向到一个

from manim.utils.deprecation import deprecated_params


@deprecated_params(
    redirections=[lambda buff_x=1, buff_y=1: {"buff": (buff_x, buff_y)}]
)
def foo(**kwargs):
    return kwargs


foo(buff_x=2)
# WARNING  The parameter buff_x of method foo has been deprecated and may be removed in a later version.
# returns {"buff": (2, 1)}

将一个参数重定向到多个

from manim.utils.deprecation import deprecated_params


@deprecated_params(
    redirections=[
        lambda buff=1: {"buff_x": buff[0], "buff_y": buff[1]}
        if isinstance(buff, tuple)
        else {"buff_x": buff, "buff_y": buff}
    ]
)
def foo(**kwargs):
    return kwargs


foo(buff=0)
# WARNING  The parameter buff of method foo has been deprecated and may be removed in a later version.
# returns {"buff_x": 0, buff_y: 0}

foo(buff=(1, 2))
# WARNING  The parameter buff of method foo has been deprecated and may be removed in a later version.
# returns {"buff_x": 1, buff_y: 2}