Skip to content

Commit

Permalink
[serve] Add Ray API stability annotations (ray-project#17295)
Browse files Browse the repository at this point in the history
  • Loading branch information
@edoakes @stephanie-wang
edoakes authored and stephanie-wang committed Jul 31, 2021
1 parent 2779d89 commit e0d47e8
Showing 1 changed file with 26 additions and 25 deletions.
51 changes: 26 additions & 25 deletions python/ray/serve/api.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@

from ray import cloudpickle
from ray.actor import ActorHandle
from ray.util.annotations import Deprecated, PublicAPI
from ray.serve.common import BackendInfo, GoalId
from ray.serve.config import (BackendConfig, HTTPOptions, ReplicaConfig)
from ray.serve.constants import (DEFAULT_HTTP_HOST, DEFAULT_HTTP_PORT,
Expand Down Expand Up @@ -578,6 +579,7 @@ def get_handle(
return handle


@PublicAPI
def start(
detached: bool = False,
http_host: Optional[str] = DEFAULT_HTTP_HOST,
Expand Down Expand Up @@ -713,11 +715,10 @@ def start(
return client


@Deprecated
def connect() -> Client:
"""Connect to an existing Serve instance on this Ray cluster.
DEPRECATED. Will be removed in Ray 1.5. See docs for details.
If calling from the driver program, the Serve instance on this Ray cluster
must first have been initialized using `serve.start(detached=True)`.
Expand Down Expand Up @@ -751,6 +752,7 @@ def connect() -> Client:
return client


@PublicAPI
def shutdown() -> None:
"""Completely shut down the connected Serve instance.
Expand All @@ -764,15 +766,14 @@ def shutdown() -> None:
_set_global_client(None)


@Deprecated
def create_endpoint(endpoint_name: str,
*,
backend: str = None,
route: Optional[str] = None,
methods: List[str] = ["GET"]) -> None:
"""Create a service endpoint given route_expression.
DEPRECATED. Will be removed in Ray 1.5. See docs for details.
Args:
endpoint_name (str): A name to associate to with the endpoint.
backend (str, required): The backend that will serve requests to
Expand All @@ -791,34 +792,31 @@ def create_endpoint(endpoint_name: str,
_internal=True)


@Deprecated
def delete_endpoint(endpoint: str) -> None:
"""Delete the given endpoint.
DEPRECATED. Will be removed in Ray 1.5. See docs for details.
Does not delete any associated backends.
"""
return _get_global_client().delete_endpoint(endpoint, _internal=True)


@Deprecated
def list_endpoints() -> Dict[str, Dict[str, Any]]:
"""Returns a dictionary of all registered endpoints.
DEPRECATED. Will be removed in Ray 1.5. See docs for details.
The dictionary keys are endpoint names and values are dictionaries
of the form: {"methods": List[str], "traffic": Dict[str, float]}.
"""
return _get_global_client().list_endpoints(_internal=True)


@Deprecated
def update_backend_config(
backend_tag: str,
config_options: Union[BackendConfig, Dict[str, Any]]) -> None:
"""Update a backend configuration for a backend tag.
DEPRECATED. Will be removed in Ray 1.5. See docs for details.
Keys not specified in the passed will be left unchanged.
Args:
Expand All @@ -839,17 +837,17 @@ def update_backend_config(
backend_tag, config_options, _internal=True)


@Deprecated
def get_backend_config(backend_tag: str) -> BackendConfig:
"""Get the backend configuration for a backend tag.
DEPRECATED. Will be removed in Ray 1.5. See docs for details.
Args:
backend_tag(str): A registered backend.
"""
return _get_global_client().get_backend_config(backend_tag, _internal=True)


@Deprecated
def create_backend(
backend_tag: str,
backend_def: Union[Callable, Type[Callable], str],
Expand All @@ -858,8 +856,6 @@ def create_backend(
config: Optional[Union[BackendConfig, Dict[str, Any]]] = None) -> None:
"""Create a backend with the provided tag.
DEPRECATED. Will be removed in Ray 1.5. See docs for details.
Args:
backend_tag (str): a unique tag assign to identify this backend.
backend_def (callable, class, str): a function or class
Expand Down Expand Up @@ -893,21 +889,19 @@ def create_backend(
_internal=True)


@Deprecated
def list_backends() -> Dict[str, BackendConfig]:
"""Returns a dictionary of all registered backends.
DEPRECATED. Will be removed in Ray 1.5. See docs for details.
Dictionary maps backend tags to backend config objects.
"""
return _get_global_client().list_backends(_internal=True)


@Deprecated
def delete_backend(backend_tag: str, force: bool = False) -> None:
"""Delete the given backend.
DEPRECATED. Will be removed in Ray 1.5. See docs for details.
The backend must not currently be used by any endpoints.
Args:
Expand All @@ -919,12 +913,11 @@ def delete_backend(backend_tag: str, force: bool = False) -> None:
backend_tag, force=force, _internal=True)


@Deprecated
def set_traffic(endpoint_name: str,
traffic_policy_dictionary: Dict[str, float]) -> None:
"""Associate a service endpoint with traffic policy.
DEPRECATED. Will be removed in Ray 1.5. See docs for details.
Example:
>>> serve.set_traffic("service-name", {
Expand All @@ -941,12 +934,11 @@ def set_traffic(endpoint_name: str,
endpoint_name, traffic_policy_dictionary, _internal=True)


@Deprecated
def shadow_traffic(endpoint_name: str, backend_tag: str,
proportion: float) -> None:
"""Shadow traffic from an endpoint to a backend.
DEPRECATED. Will be removed in Ray 1.5. See docs for details.
The specified proportion of requests will be duplicated and sent to the
backend. Responses of the duplicated traffic will be ignored.
The backend must not already be in use.
Expand All @@ -963,6 +955,7 @@ def shadow_traffic(endpoint_name: str, backend_tag: str,
endpoint_name, backend_tag, proportion, _internal=True)


@Deprecated
def get_handle(
endpoint_name: str,
missing_ok: bool = False,
Expand All @@ -972,8 +965,6 @@ def get_handle(
) -> Union[RayServeHandle, RayServeSyncHandle]:
"""Retrieve RayServeHandle for service endpoint to invoke it from Python.
DEPRECATED. Will be removed in Ray 1.5. See docs for details.
Args:
endpoint_name (str): A registered service endpoint.
missing_ok (bool): If true, then Serve won't check the endpoint is
Expand All @@ -994,6 +985,7 @@ def get_handle(
_internal=True)


@PublicAPI
def get_replica_context() -> ReplicaContext:
"""When called from a backend, returns the backend tag and replica tag.
Expand All @@ -1016,6 +1008,7 @@ def get_replica_context() -> ReplicaContext:
return _INTERNAL_REPLICA_CONTEXT


@PublicAPI(stability="beta")
def ingress(app: Union["FastAPI", "APIRouter"]):
"""Mark a FastAPI application ingress for Serve.
Expand Down Expand Up @@ -1093,6 +1086,7 @@ def __del__(self):
return decorator


@PublicAPI
class Deployment:
def __init__(self,
func_or_class: Callable,
Expand Down Expand Up @@ -1213,11 +1207,12 @@ def __call__(self):
raise RuntimeError("Deployments cannot be constructed directly. "
"Use `deployment.deploy() instead.`")

@PublicAPI
def deploy(self, *init_args, _blocking=True):
"""Deploy or update this deployment.
Args:
*init_args (optional): args to pass to the class __init__
init_args (optional): args to pass to the class __init__
method. Not valid if this deployment wraps a function.
"""
if len(init_args) == 0 and self._init_args is not None:
Expand All @@ -1235,11 +1230,13 @@ def deploy(self, *init_args, _blocking=True):
_blocking=_blocking,
_internal=True)

@PublicAPI
def delete(self):
"""Delete this deployment."""
return _get_global_client().delete_deployment(
self._name, _internal=True)

@PublicAPI
def get_handle(self, sync: Optional[bool] = True
) -> Union[RayServeHandle, RayServeSyncHandle]:
"""Get a ServeHandle to this deployment to invoke it from Python.
Expand All @@ -1260,6 +1257,7 @@ def get_handle(self, sync: Optional[bool] = True
_internal_use_serve_request=False,
_internal=True)

@PublicAPI
def options(
self,
func_or_class: Optional[Callable] = None,
Expand Down Expand Up @@ -1360,6 +1358,7 @@ def deployment(name: Optional[str] = None,
pass


@PublicAPI
def deployment(
_func_or_class: Optional[Callable] = None,
name: Optional[str] = None,
Expand Down Expand Up @@ -1453,6 +1452,7 @@ def decorator(_func_or_class):
return decorator(_func_or_class) if callable(_func_or_class) else decorator


@PublicAPI
def get_deployment(name: str) -> Deployment:
"""Dynamically fetch a handle to a Deployment object.
Expand Down Expand Up @@ -1489,6 +1489,7 @@ def get_deployment(name: str) -> Deployment:
)


@PublicAPI
def list_deployments() -> Dict[str, Deployment]:
"""Returns a dictionary of all active deployments.
Expand Down

0 comments on commit e0d47e8

Please sign in to comment.