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

python/ray/serve/_private/constants.py

@@ -100,3 +100,9 @@ RAY_SERVE_KV_TIMEOUT_S = float(os.environ.get("RAY_SERVE_KV_TIMEOUT_S", "0")) or
 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,8 +11,7 @@ from uvicorn.lifespan.on import LifespanOn
 
 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
@@ -20,6 +19,7 @@ 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,6 +42,7 @@ from ray.serve._private.utils import (
     ensure_serialization_context,
     in_interactive_shell,
     install_serve_encoders_to_fastapi,
+    guarded_deprecation_warning,
 )
 
 from ray.serve._private import api as _private_api
@@ -49,8 +50,8 @@ 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 deployment(
     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 @@ from ray.serve.config import (
     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 @@ class Deployment:
                 },
             )
 
-    @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 @@ class Deployment:
             _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 @@ class Deployment:
 
         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]: