code: def PublicAPI(*args, **kwargs):
      """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
      :ref:`Ray API Stability definitions <api-stability>`.
  
      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 stability in ["alpha", "beta"]:
              message = (
                  f"**PublicAPI ({stability}):** This API is in {stability} "
                  "and may change before becoming stable."
              )
              _append_doc(obj, message=message)
  
          _mark_annotated(obj)
          return obj
  
      return wrap
  
file_path: ray/python/ray/util/annotations.py
imports: from typing import Optional
  import inspect
  import sys
  import warnings
  from functools import wraps
label_desc: Use image node_id 1 for calling a global function with example usage: PublicAPI() and returns: wrap, PublicAPI, obj