API 稳定性#

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

一个API可以被标记为：

  • 公共API，这意味着该API对最终用户开放。公共API有三个子级别（alpha、beta、稳定），如下所述。

  • 开发者API，这意味着该API明确地向*高级* Ray用户和库开发者开放

  • 已弃用，可能在未来的Ray版本中被移除。

Ray 的 PublicAPI 稳定性定义基于 Google 稳定性级别指南，略有不同：

阿尔法#

一个 alpha 组件会经历快速迭代，有一组已知的用户 必须 对变化保持宽容。用户数量 应该 是一个经过筛选、可管理的集合，以便能够个别地与所有用户进行沟通。

在alpha组件中，**必须**允许并预期会有重大变更，用户**必须**不对稳定性有任何期望。

Beta#

一个 beta 组件 必须 被认为是完整的，并且准备好在公开测试后宣布为稳定。

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

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

稳定#

一个 稳定 的组件 必须 在整个主要API版本的生命周期内得到完全支持。因为用户期望从标记为稳定的组件中获得这种稳定性，所以在主要版本内对这些组件 必须 没有破坏性的更改（除非在特殊情况下）。

文档字符串#

ray.util.annotations.PublicAPI(*args, **kwargs)[源代码]#

用于记录公共API的注释。

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

如果 stability="alpha"，API 可以被能够容忍并预期重大变更的高级用户使用。

如果 stability="beta"，API 仍然是公开的，早期用户可以使用，但可能会发生变化。

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

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

参数:

  • stability – {“稳定版”, “测试版”, “内测版”} 之一。

  • api_group – 可选。仅用于文档渲染目的。同一组的API将在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)[源代码]#

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

开发者API是显式暴露给高级Ray用户和库开发者的低级方法。它们的接口可能会在Ray的次要版本之间发生变化。

示例

>>> from ray.util.annotations import DeveloperAPI
>>> @DeveloperAPI
... def func(x):
...     return x
ray.util.annotations.Deprecated(*args, **kwargs)[源代码]#

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

不推荐使用的API可能在Ray的未来版本中被移除。

参数:

message – 一条帮助用户理解弃用原因并提供迁移路径的消息。

示例

>>> 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。