Source code for ray.util.annotations

[docs]def PublicAPI(*args, **kwargs): """Annotation for documenting public APIs. Public APIs are classes and methods exposed to end users of Ray. You can expect these APIs to remain backwards compatible across minor Ray releases (e.g., Ray 1.4 -> 1.8). If "stability" is beta, the API is still public and can be used by early users, but are subject to change. If "stability" is alpha, the API can be used by advanced users who are tolerant to and expect breaking changes. For a full definition of the stability levels, please refer to the `Google stability level guidelines <https://google.aip.dev/181>`_ Args: 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 """ if len(args) == 1 and len(kwargs) == 0 and callable(args[0]): return PublicAPI(stability="stable")(args[0]) if "stability" in kwargs: stability = kwargs["stability"] assert stability in ["stable", "beta", "alpha"], stability elif kwargs: raise ValueError("Unknown kwargs: {}".format(kwargs.keys())) else: stability = "stable" def wrap(obj): if not obj.__doc__: obj.__doc__ = "" if stability in ["alpha", "beta"]: obj.__doc__ += ( f"\n PublicAPI ({stability}): This API is in {stability} " "and may change before becoming stable." ) else: obj.__doc__ += "\n PublicAPI: This API is stable across Ray releases." return obj return wrap
[docs]def DeveloperAPI(obj): """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 """ if not obj.__doc__: obj.__doc__ = "" obj.__doc__ += "\n DeveloperAPI: This API may change across minor Ray releases." return obj
[docs]def Deprecated(*args, **kwargs): """Annotation for documenting a deprecated API. Deprecated APIs may be removed in future releases of Ray. Args: 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 """ if len(args) == 1 and len(kwargs) == 0 and callable(args[0]): return Deprecated()(args[0]) message = ( "\n DEPRECATED: This API is deprecated and may be removed " "in future Ray releases." ) if "message" in kwargs: message = message + " " + kwargs["message"] del kwargs["message"] if kwargs: raise ValueError("Unknown kwargs: {}".format(kwargs.keys())) def inner(obj): if not obj.__doc__: obj.__doc__ = "" obj.__doc__ += f"{message}" return obj return inner