API 稳定性#

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

API 可以被标记为：

  • PublicAPI，这意味着 API 公开给最终用户。 PublicAPI 具有三个子级别（alpha、beta、stable），如下所述。

  • :ref:`DeveloperAPI <developer-api-def>`这意味着 API 显式暴露给 高级 Ray 用户和库开发人员

  • Deprecated，可能会在 Ray 的未来版本中删除。

Ray 的 PublicAPI 稳定性定义基于 Google 稳定性级别指南，有细微差别：

Alpha#

alpha 组件会与一组已知的用户进行快速迭代，这些用户 必须 能够容忍变化。用户数量 应该 是经过精心策划、 可管理的集合，以便可以单独与所有用户进行通信。

alpha 组件重大更改 必须 允许和预期，并且 用户 必须 不能期望稳定性。

测试版#

beta 组件应该尽可能稳定；然而， beta 组件 必须 允许随时间变化。

Because users of beta components tend to have a lower tolerance of change, beta components should be as stable as possible; however, the beta component must be permitted to change over time. These changes should be minimal but may include backwards-incompatible changes to beta components.

Backwards-incompatible changes must be made only after a reasonable deprecation period to provide users with an opportunity to migrate their code.

Stable#

A stable component must be fully-supported over the lifetime of the major API version. Because users expect such stability from components marked stable, there must be no breaking changes to these components within a major version (excluding extraordinary circumstances).

Docstrings#

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

Annotation for documenting public APIs.

Public APIs are classes and methods exposed to end users of Ray.

If stability="alpha", the API can be used by advanced users who are tolerant to and expect breaking changes.

If stability="beta", the API is still public and can be used by early users, but are subject to change.

If stability="stable", the APIs will remain backwards compatible across minor Ray releases (e.g., Ray 1.4 -> 1.8).

For a full definition of the stability levels, please refer to the Ray API Stability definitions.

Parameters

stability – One of {“stable”, “beta”, “alpha”}.

Examples

>>> 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]#

Annotation for documenting developer APIs.

Developer APIs are lower-level methods explicitly exposed to advanced Ray users and library developers. Their interfaces may change across minor Ray releases.

Examples

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

Annotation for documenting a deprecated API.

Deprecated APIs may be removed in future releases of Ray.

Parameters

message – a message to help users understand the reason for the deprecation, and provide a migration path.

Examples

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

Undecorated functions can be generally assumed to not be part of the Ray public API.