API 稳定性#

Ray 为 Ray 核心和库中的公共 API 提供了稳定性保证，这些 API 会被相应地装饰/标记。

API 可以被标记为

Ray 的 PublicAPI 稳定性定义基于 Google 稳定性级别指南，略有差异。

Alpha#

Alpha 组件经历快速迭代，拥有一组已知的用户，这些用户必须能够容忍更改。用户数量应是经过精心挑选、可管理的集合，以便能够与他们每个人单独沟通。

Alpha 组件必须允许并期望发生破坏性更改，用户不得期望其稳定性。

Beta 组件必须被认为是完整的，并准备好宣布稳定，以接受公开测试。

由于 beta 组件的用户对更改的容忍度较低，beta 组件应尽可能稳定；然而，beta 组件必须允许随时间推移而发生变化。这些变化应是最小的，但可能包括对 beta 组件的向后不兼容更改。

向后不兼容的更改必须在合理的弃用期之后进行，以便为用户提供迁移代码的机会。

Stable 组件必须在主要 API 版本生命周期内得到充分支持。由于用户期望标记为 stable 的组件具有这种稳定性，因此在主要版本内不得对这些组件进行破坏性更改（除非有特殊情况）。

ray.util.annotations.PublicAPI(*args, **kwargs)[source]#

用于记录公共 API 的注解。

公共 API 是向 Ray 最终用户公开的类和方法。

如果 stability="alpha"，则该 API 可供高级用户使用，他们能容忍并期望发生破坏性更改。

如果 stability="beta"，则该 API 仍是公共的，可供早期用户使用，但可能会发生更改。

如果 stability="stable"，则 API 在次要 Ray 版本之间（例如，Ray 1.4 -> 1.8）将保持向后兼容。

有关稳定性级别的完整定义，请参阅 Ray API 稳定性定义。

参数:

示例

>>> from ray.util.annotations import PublicAPI
>>> @PublicAPI
... def func(x):
...     return x

>>> @PublicAPI(stability="beta")
... def func(y):
...     return y

ray.util.annotations.DeveloperAPI(*args, **kwargs)[source]#

用于记录开发者 API 的注解。

开发者 API 是低级方法，明示地向高级 Ray 用户和库开发者公开。它们的接口可能在次要 Ray 版本之间发生变化。

示例

>>> from ray.util.annotations import DeveloperAPI
>>> @DeveloperAPI
... def func(x):
...     return x

ray.util.annotations.Deprecated(*args, **kwargs)[source]#

用于记录已弃用 API 的注解。

已弃用的 API 可能会在 Ray 的未来版本中移除。

示例

>>> from ray.util.annotations import Deprecated
>>> @Deprecated
... def func(x):
...     return x

>>> @Deprecated(message="g() is deprecated because the API is error "
...   "prone. Please call h() instead.")
... def g(y):
...     return y

通常可以假定未加注解的函数不属于 Ray 的公共 API。