Deprecate Starlette and Router decorators

starlette/applications.py

@@ -1,4 +1,5 @@
 import typing
+import warnings
 
 from starlette.datastructures import State, URLPath
 from starlette.middleware import Middleware
@@ -123,43 +124,17 @@ async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
         scope["app"] = self
         await self.middleware_stack(scope, receive, send)
 
-    # The following usages are now discouraged in favour of configuration
-    # during Starlette.__init__(...)
     def on_event(self, event_type: str) -> typing.Callable:  # pragma: nocover
         return self.router.on_event(event_type)
 
     def mount(
         self, path: str, app: ASGIApp, name: typing.Optional[str] = None
     ) -> None:  # pragma: nocover
-        """
-        We no longer document this API, and its usage is discouraged.
-        Instead you should use the following approach:
-
-        routes = [
-            Mount(path, ...),
-            ...
-        ]
-
-        app = Starlette(routes=routes)
-        """
-
         self.router.mount(path, app=app, name=name)
 
     def host(
         self, host: str, app: ASGIApp, name: typing.Optional[str] = None
     ) -> None:  # pragma: no cover
-        """
-        We no longer document this API, and its usage is discouraged.
-        Instead you should use the following approach:
-
-        routes = [
-            Host(path, ...),
-            ...
-        ]
-
-        app = Starlette(routes=routes)
-        """
-
         self.router.host(host, app=app, name=name)
 
     def add_middleware(
@@ -201,6 +176,12 @@ def add_websocket_route(
     def exception_handler(
         self, exc_class_or_status_code: typing.Union[int, typing.Type[Exception]]
     ) -> typing.Callable:  # pragma: nocover
+        warnings.warn(
+            "The `exception_handler` decorator is deprecated, and will be removed in version 1.0.0."  # noqa: E501
+            "Refer to https://www.starlette.io/exceptions/ for the recommended approach.",  # noqa: E501
+            DeprecationWarning,
+        )
+
         def decorator(func: typing.Callable) -> typing.Callable:
             self.add_exception_handler(exc_class_or_status_code, func)
             return func
@@ -218,12 +199,8 @@ def route(
         We no longer document this decorator style API, and its usage is discouraged.
         Instead you should use the following approach:
 
-        routes = [
-            Route(path, endpoint=..., ...),
-            ...
-        ]
-
-        app = Starlette(routes=routes)
+        >>> routes = [Route(path, endpoint=...), ...]
+        >>> app = Starlette(routes=routes)
         """
 
         def decorator(func: typing.Callable) -> typing.Callable:
@@ -245,12 +222,8 @@ def websocket_route(
         We no longer document this decorator style API, and its usage is discouraged.
         Instead you should use the following approach:
 
-        routes = [
-            WebSocketRoute(path, endpoint=..., ...),
-            ...
-        ]
-
-        app = Starlette(routes=routes)
+        >>> routes = [WebSocketRoute(path, endpoint=...), ...]
+        >>> app = Starlette(routes=routes)
         """
 
         def decorator(func: typing.Callable) -> typing.Callable:
@@ -264,14 +237,14 @@ def middleware(self, middleware_type: str) -> typing.Callable:  # pragma: nocove
         We no longer document this decorator style API, and its usage is discouraged.
         Instead you should use the following approach:
 
-        middleware = [
-            Middleware(...),
-            ...
-        ]
-
-        app = Starlette(middleware=middleware)
+        >>> middleware = [Middleware(...), ...]
+        >>> app = Starlette(middleware=middleware)
         """
-
+        warnings.warn(
+            "The `middleware` decorator is deprecated, and will be removed in version 1.0.0. "  # noqa: E501
+            "Refer to https://www.starlette.io/middleware/#using-middleware for recommended approach.",  # noqa: E501
+            DeprecationWarning,
+        )
         assert (
             middleware_type == "http"
         ), 'Currently only middleware("http") is supported.'

starlette/routing.py

@@ -737,41 +737,15 @@ async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
     def __eq__(self, other: typing.Any) -> bool:
         return isinstance(other, Router) and self.routes == other.routes
 
-    # The following usages are now discouraged in favour of configuration
-    #  during Router.__init__(...)
     def mount(
         self, path: str, app: ASGIApp, name: typing.Optional[str] = None
     ) -> None:  # pragma: nocover
-        """
-        We no longer document this API, and its usage is discouraged.
-        Instead you should use the following approach:
-
-        routes = [
-            Mount(path, ...),
-            ...
-        ]
-
-        app = Starlette(routes=routes)
-        """
-
         route = Mount(path, app=app, name=name)
         self.routes.append(route)
 
     def host(
         self, host: str, app: ASGIApp, name: typing.Optional[str] = None
     ) -> None:  # pragma: no cover
-        """
-        We no longer document this API, and its usage is discouraged.
-        Instead you should use the following approach:
-
-        routes = [
-            Host(path, ...),
-            ...
-        ]
-
-        app = Starlette(routes=routes)
-        """
-
         route = Host(host, app=app, name=name)
         self.routes.append(route)
 
@@ -809,13 +783,14 @@ def route(
         We no longer document this decorator style API, and its usage is discouraged.
         Instead you should use the following approach:
 
-        routes = [
-            Route(path, endpoint=..., ...),
-            ...
-        ]
-
-        app = Starlette(routes=routes)
+        >>> routes = [Route(path, endpoint=...), ...]
+        >>> app = Starlette(routes=routes)
         """
+        warnings.warn(
+            "The `route` decorator is deprecated, and will be removed in version 1.0.0."
+            "Refer to https://www.starlette.io/routing/#http-routing for the recommended approach.",  # noqa: E501
+            DeprecationWarning,
+        )
 
         def decorator(func: typing.Callable) -> typing.Callable:
             self.add_route(
@@ -836,13 +811,14 @@ def websocket_route(
         We no longer document this decorator style API, and its usage is discouraged.
         Instead you should use the following approach:
 
-        routes = [
-            WebSocketRoute(path, endpoint=..., ...),
-            ...
-        ]
-
-        app = Starlette(routes=routes)
+        >>> routes = [WebSocketRoute(path, endpoint=...), ...]
+        >>> app = Starlette(routes=routes)
         """
+        warnings.warn(
+            "The `websocket_route` decorator is deprecated, and will be removed in version 1.0.0. Refer to "  # noqa: E501
+            "https://www.starlette.io/routing/#websocket-routing for the recommended approach.",  # noqa: E501
+            DeprecationWarning,
+        )
 
         def decorator(func: typing.Callable) -> typing.Callable:
             self.add_websocket_route(path, func, name=name)
@@ -861,6 +837,12 @@ def add_event_handler(
             self.on_shutdown.append(func)
 
     def on_event(self, event_type: str) -> typing.Callable:  # pragma: nocover
+        warnings.warn(
+            "The `on_event` decorator is deprecated, and will be removed in version 1.0.0. "  # noqa: E501
+            "Refer to https://www.starlette.io/events/#registering-events for recommended approach.",  # noqa: E501
+            DeprecationWarning,
+        )
+
         def decorator(func: typing.Callable) -> typing.Callable:
             self.add_event_handler(event_type, func)
             return func