[Serve] Gate the deprecation warnings behind envvar (ray-project#27479)

Signed-off-by: Stefan van der Kleij <[email protected]>

python/ray/serve/_private/constants.py

@@ -100,3 +100,9 @@
 class ServeHandleType(str, Enum):
  SYNC = "SYNC"
  ASYNC = "ASYNC"
+
+
+# Deprecation message for V1 migrations.
+MIGRATION_MESSAGE = (
+ "See https://docs.ray.io/en/latest/serve/index.html for more information."
+)

python/ray/serve/_private/utils.py

@@ -428,3 +428,17 @@ def in_interactive_shell():
  import __main__ as main
 
  return not hasattr(main, "__file__")
+
+
+def guarded_deprecation_warning(*args, **kwargs):
+ """Wrapper for deprecation warnings, guarded by a flag."""
+ if os.environ.get("SERVE_WARN_V1_DEPRECATIONS", "0") == "1":
+ from ray._private.utils import deprecated
+
+ return deprecated(*args, **kwargs)
+ else:
+
+ def noop_decorator(func):
+ return func
+
+ return noop_decorator

python/ray/serve/api.py

@@ -11,15 +11,15 @@
 
 from ray import cloudpickle
 from ray.dag import DAGNode
-from ray.util.annotations import DeveloperAPI, PublicAPI
-from ray._private.utils import deprecated
+from ray.util.annotations import Deprecated, PublicAPI
 
 from ray.serve.application import Application
 from ray.serve._private.client import ServeControllerClient
 from ray.serve.config import AutoscalingConfig, DeploymentConfig, HTTPOptions
 from ray.serve._private.constants import (
  DEFAULT_HTTP_HOST,
  DEFAULT_HTTP_PORT,
+ MIGRATION_MESSAGE,
 )
 from ray.serve.context import (
  ReplicaContext,
@@ -42,15 +42,16 @@
  ensure_serialization_context,
  in_interactive_shell,
  install_serve_encoders_to_fastapi,
+ guarded_deprecation_warning,
 )
 
 from ray.serve._private import api as _private_api
 
 logger = logging.getLogger(__file__)
 
 
-@deprecated(instructions="Please see https://docs.ray.io/en/latest/serve/index.html")
-@PublicAPI(stability="beta")
+@guarded_deprecation_warning(instructions=MIGRATION_MESSAGE)
+@Deprecated(message=MIGRATION_MESSAGE)
 def start(
  detached: bool = False,
  http_options: Optional[Union[dict, HTTPOptions]] = None,
@@ -103,7 +104,7 @@ def start(
  return client
 
 
-@PublicAPI
+@PublicAPI(stability="stable")
 def shutdown() -> None:
  """Completely shut down the connected Serve instance.
 
@@ -124,7 +125,7 @@ def shutdown() -> None:
  _set_global_client(None)
 
 
-@PublicAPI
+@PublicAPI(stability="beta")
 def get_replica_context() -> ReplicaContext:
  """If called from a deployment, returns the deployment and replica tag.
 
@@ -270,7 +271,7 @@ def deployment(
  pass
 
 
-@PublicAPI
+@PublicAPI(stability="beta")
 def deployment(
  _func_or_class: Optional[Callable] = None,
  name: Optional[str] = None,
@@ -388,8 +389,8 @@ def decorator(_func_or_class):
  return decorator(_func_or_class) if callable(_func_or_class) else decorator
 
 
-@deprecated(instructions="Please see https://docs.ray.io/en/latest/serve/index.html")
-@PublicAPI
+@guarded_deprecation_warning(instructions=MIGRATION_MESSAGE)
+@Deprecated(message=MIGRATION_MESSAGE)
 def get_deployment(name: str) -> Deployment:
  """Dynamically fetch a handle to a Deployment object.
 
@@ -412,8 +413,8 @@ def get_deployment(name: str) -> Deployment:
  return _private_api.get_deployment(name)
 
 
-@deprecated(instructions="Please see https://docs.ray.io/en/latest/serve/index.html")
-@PublicAPI
+@guarded_deprecation_warning(instructions=MIGRATION_MESSAGE)
+@Deprecated(message=MIGRATION_MESSAGE)
 def list_deployments() -> Dict[str, Deployment]:
  """Returns a dictionary of all active deployments.
 
@@ -511,7 +512,7 @@ def run(
  return ingress._get_handle()
 
 
-@DeveloperAPI
+@PublicAPI(stability="alpha")
 def build(target: Union[ClassNode, FunctionNode]) -> Application:
  """Builds a Serve application into a static application.
 

python/ray/serve/deployment.py

@@ -18,15 +18,14 @@
  AutoscalingConfig,
  DeploymentConfig,
 )
-from ray.serve._private.constants import SERVE_LOGGER_NAME
+from ray.serve._private.constants import SERVE_LOGGER_NAME, MIGRATION_MESSAGE
 from ray.serve.handle import RayServeHandle, RayServeSyncHandle
-from ray.serve._private.utils import DEFAULT
-from ray.util.annotations import PublicAPI
+from ray.serve._private.utils import DEFAULT, guarded_deprecation_warning
+from ray.util.annotations import Deprecated, PublicAPI
 from ray.serve.schema import (
  RayActorOptionsSchema,
  DeploymentSchema,
 )
-from ray._private.utils import deprecated
 
 
 logger = logging.getLogger(SERVE_LOGGER_NAME)
@@ -201,10 +200,8 @@ def bind(self, *args, **kwargs) -> Union[ClassNode, FunctionNode]:
  },
  )
 
- @deprecated(
- instructions="Please see https://docs.ray.io/en/latest/serve/index.html"
- )
- @PublicAPI
+ @guarded_deprecation_warning(instructions=MIGRATION_MESSAGE)
+ @Deprecated(message=MIGRATION_MESSAGE)
  def deploy(self, *init_args, _blocking=True, **init_kwargs):
  """Deploy or update this deployment.
 
@@ -245,10 +242,8 @@ def _deploy(self, *init_args, _blocking=True, **init_kwargs):
  _blocking=_blocking,
  )
 
- @deprecated(
- instructions="Please see https://docs.ray.io/en/latest/serve/index.html"
- )
- @PublicAPI
+ @guarded_deprecation_warning(instructions=MIGRATION_MESSAGE)
+ @Deprecated(message=MIGRATION_MESSAGE)
  def delete(self):
  """Delete this deployment."""
 
@@ -260,10 +255,8 @@ def _delete(self):
 
  return get_global_client().delete_deployments([self._name])
 
- @deprecated(
- instructions="Please see https://docs.ray.io/en/latest/serve/index.html"
- )
- @PublicAPI
+ @guarded_deprecation_warning(instructions=MIGRATION_MESSAGE)
+ @Deprecated(message=MIGRATION_MESSAGE)
  def get_handle(
  self, sync: Optional[bool] = True
  ) -> Union[RayServeHandle, RayServeSyncHandle]: