From f6d19ac7c03b12bbf839824381376e228d0fffad Mon Sep 17 00:00:00 2001 From: Simon Mo Date: Fri, 5 Aug 2022 13:38:44 -0700 Subject: [PATCH] [Serve] Gate the deprecation warnings behind envvar (#27479) --- python/ray/serve/_private/constants.py | 6 ++++++ python/ray/serve/_private/utils.py | 14 ++++++++++++++ python/ray/serve/api.py | 25 +++++++++++++------------ python/ray/serve/deployment.py | 25 +++++++++---------------- 4 files changed, 42 insertions(+), 28 deletions(-) diff --git a/python/ray/serve/_private/constants.py b/python/ray/serve/_private/constants.py index aec04a6a5..1011925b0 100644 --- a/python/ray/serve/_private/constants.py +++ b/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." +) diff --git a/python/ray/serve/_private/utils.py b/python/ray/serve/_private/utils.py index 663024649..8082ac86f 100644 --- a/python/ray/serve/_private/utils.py +++ b/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 diff --git a/python/ray/serve/api.py b/python/ray/serve/api.py index b1c316f3c..7a6c0cc81 100644 --- a/python/ray/serve/api.py +++ b/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. diff --git a/python/ray/serve/deployment.py b/python/ray/serve/deployment.py index 9357b8cc6..6d4e216f0 100644 --- a/python/ray/serve/deployment.py +++ b/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]: