feat!: Make route handlers functional decorators

docs/release-notes/2.x-changelog.rst

@@ -3057,7 +3057,7 @@
  :pr: 1647
 
  Dependencies can now be used in the
- :class:`~litestar.handlers.websocket_listener` hooks
+ :func:`~litestar.handlers.websocket_listener` hooks
  ``on_accept``, ``on_disconnect`` and the ``connection_lifespan`` context
  manager. The ``socket`` parameter is therefore also not mandatory anymore in
  those callables.
@@ -3208,7 +3208,7 @@
  :issue: 1615
 
  A bug was fixed that would cause a type error when using a
- :class:`websocket_listener <litestar.handlers.websocket_listener>`
+ :func:`websocket_listener <litestar.handlers.websocket_listener>`
  in a ``Controller``
 
  .. change:: Add ``connection_accept_handler`` to ``websocket_listener``
@@ -3217,7 +3217,7 @@
  :issue: 1571
 
  Add a new ``connection_accept_handler`` parameter to
- :class:`websocket_listener <litestar.handlers.websocket_listener>`,
+ :func:`websocket_listener <litestar.handlers.websocket_listener>`,
  which can be used to customize how a connection is accepted, for example to
  add headers or subprotocols
 
@@ -3305,7 +3305,7 @@
  appropriate event hooks - to use a context manager.
 
  The ``connection_lifespan`` argument was added to the
- :class:`WebSocketListener <litestar.handlers.websocket_listener>`, which accepts
+ :func:`WebSocketListener <litestar.handlers.websocket_listener>`, which accepts
  an asynchronous context manager, which can be used to handle the lifespan of
  the socket.
 
@@ -3419,7 +3419,7 @@
  :pr: 1518
 
  Support for DTOs has been added to :class:`WebSocketListener <litestar.handlers.WebsocketListener>` and
- :class:`WebSocketListener <litestar.handlers.websocket_listener>`. A ``dto`` and ``return_dto`` parameter has
+ :func:`WebSocketListener <litestar.handlers.websocket_listener>`. A ``dto`` and ``return_dto`` parameter has
  been added, providing the same functionality as their route handler counterparts.
 
  .. change:: DTO based serialization plugin

docs/release-notes/whats-new-3.rst

@@ -142,3 +142,39 @@ If you were relying on this utility, you can define it yourself as follows:
 
  def is_sync_or_async_generator(obj: Any) -> bool:
  return isgeneratorfunction(obj) or isasyncgenfunction(obj)
+
+
+Removal of semantic HTTP route handler classes
+-----------------------------------------------
+
+The semantic ``HTTPRouteHandler`` classes have been removed in favour of functional
+decorators. ``route``, ``get``, ``post``, ``patch``, ``put``, ``head`` and ``delete``
+are now all decorator functions returning :class:`~.handlers.HTTPRouteHandler`
+instances.
+
+As a result, customizing the decorators directly is not possible anymore. Instead, to
+use a route handler decorator with a custom route handler class, the ``handler_class``
+parameter to the decorator function can be used:
+
+Before:
+
+.. code-block:: python
+
+ class my_get_handler(get):
+ ... # custom handler
+
+ @my_get_handler()
+ async def handler() -> Any:
+ ...
+
+After:
+
+.. code-block:: python
+
+ class MyHTTPRouteHandler(HTTPRouteHandler):
+ ... # custom handler
+
+
+ @get(handler_class=MyHTTPRouteHandler)
+ async def handler() -> Any:
+ ...

docs/usage/routing/handlers.rst

@@ -7,7 +7,7 @@ handler :term:`decorators <decorator>` exported from Litestar.
 For example:
 
 .. code-block:: python
- :caption: Defining a route handler by decorating a function with the :class:`@get() <.handlers.get>` :term:`decorator`
+ :caption: Defining a route handler by decorating a function with the :func:`@get() <.handlers.get>` :term:`decorator`
 
  from litestar import get
 
@@ -146,12 +146,11 @@ There are several reasons for why this limitation is enforced:
 HTTP route handlers
 -------------------
 
-The most commonly used route handlers are those that handle HTTP requests and responses.
-These route handlers all inherit from the :class:`~.handlers.HTTPRouteHandler` class, which is aliased as the
-:term:`decorator` called :func:`~.handlers.route`:
+The :class:`~.handlers.HTTPRouteHandler` is used to handle HTTP requests, and can be
+created with the :func:`~.handlers.route` :term:`decorator`:
 
 .. code-block:: python
- :caption: Defining a route handler by decorating a function with the :class:`@route() <.handlers.route>`
+ :caption: Defining a route handler by decorating a function with the :func:`@route() <.handlers.route>`
  :term:`decorator`
 
  from litestar import HttpMethod, route
@@ -160,20 +159,24 @@ These route handlers all inherit from the :class:`~.handlers.HTTPRouteHandler` c
  @route(path="/some-path", http_method=[HttpMethod.GET, HttpMethod.POST])
  async def my_endpoint() -> None: ...
 
-As mentioned above, :func:`@route() <.handlers.route>` is merely an alias for ``HTTPRouteHandler``,
-thus the below code is equivalent to the one above:
+The same can be achieved without a decorator, by using ``HTTPRouteHandler`` directly:
 
 .. code-block:: python
- :caption: Defining a route handler by decorating a function with the
- :class:`HTTPRouteHandler <.handlers.HTTPRouteHandler>` class
+ :caption: Defining a route handler creating an instance of
+ :class:`HTTPRouteHandler <.handlers.HTTPRouteHandler>`
 
  from litestar import HttpMethod
  from litestar.handlers.http_handlers import HTTPRouteHandler
 
 
- @HTTPRouteHandler(path="/some-path", http_method=[HttpMethod.GET, HttpMethod.POST])
  async def my_endpoint() -> None: ...
 
+ handler = HTTPRouteHandler(
+ path="/some-path",
+ http_method=[HttpMethod.GET, HttpMethod.POST],
+ fn=my_endpoint
+ )
+
 
 Semantic handler :term:`decorators <decorator>`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -189,8 +192,8 @@ which correlates with their name:
 * :func:`@post() <.handlers.post>`
 * :func:`@put() <.handlers.put>`
 
-These are used exactly like :func:`@route() <.handlers.route>` with the sole exception that you cannot configure the
-:paramref:`~.handlers.HTTPRouteHandler.http_method` :term:`kwarg <argument>`:
+These are used exactly like :func:`@route() <.handlers.route>` with the sole exception that you don't need to configure
+the :paramref:`~.handlers.HTTPRouteHandler.http_method` :term:`kwarg <argument>`:
 
 .. dropdown:: Click to see the predefined route handlers
 
@@ -240,11 +243,6 @@ These are used exactly like :func:`@route() <.handlers.route>` with the sole exc
  @delete(path="/resources/{pk:int}")
  async def delete_resource(pk: int) -> None: ...
 
-Although these :term:`decorators <decorator>` are merely subclasses of :class:`~.handlers.HTTPRouteHandler` that pre-set
-the :paramref:`~.handlers.HTTPRouteHandler.http_method`, using :func:`@get() <.handlers.get>`,
-:func:`@patch() <.handlers.patch>`, :func:`@put() <.handlers.put>`, :func:`@delete() <.handlers.delete>`, or
-:func:`@post() <.handlers.post>` instead of :func:`@route() <.handlers.route>` makes the code clearer and simpler.
-
 Furthermore, in the OpenAPI specification each unique combination of HTTP verb (e.g. ``GET``, ``POST``, etc.) and path
 is regarded as a distinct `operation <https://spec.openapis.org/oas/latest.html#operation-object>`_\ , and each
 operation should be distinguished by a unique :paramref:`~.handlers.HTTPRouteHandler.operation_id` and optimally
@@ -277,22 +275,25 @@ A WebSocket connection can be handled with a :func:`@websocket() <.handlers.Webs
  await socket.send_json({...})
  await socket.close()
 
-The :func:`@websocket() <.handlers.WebsocketRouteHandler>` :term:`decorator` is an alias of the
-:class:`~.handlers.WebsocketRouteHandler` class. Thus, the below code is equivalent to the one above:
+The :func:`@websocket() <.handlers.WebsocketRouteHandler>` :term:`decorator` can be used to create an instance of
+:class:`~.handlers.WebsocketRouteHandler`. Therefore, the below code is equivalent to the one above:
 
 .. code-block:: python
  :caption: Using the :class:`~.handlers.WebsocketRouteHandler` class directly
 
  from litestar import WebSocket
  from litestar.handlers.websocket_handlers import WebsocketRouteHandler
 
-
- @WebsocketRouteHandler(path="/socket")
  async def my_websocket_handler(socket: WebSocket) -> None:
  await socket.accept()
  await socket.send_json({...})
  await socket.close()
 
+ my_websocket_handler = WebsocketRouteHandler(
+ path="/socket",
+ fn=my_websocket_handler,
+ )
+
 In difference to HTTP routes handlers, websocket handlers have the following requirements:
 
 #. They **must** declare a ``socket`` :term:`kwarg <argument>`.
@@ -332,8 +333,8 @@ If you need to write your own ASGI application, you can do so using the :func:`@
  )
  await response(scope=scope, receive=receive, send=send)
 
-Like other route handlers, the :func:`@asgi() <.handlers.asgi>` :term:`decorator` is an alias of the
-:class:`~.handlers.ASGIRouteHandler` class. Thus, the code below is equivalent to the one above:
+:func:`@asgi() <.handlers.asgi>` :term:`decorator` can be used to create an instance of
+:class:`~.handlers.ASGIRouteHandler`. Therefore, the code below is equivalent to the one above:
 
 .. code-block:: python
  :caption: Using the :class:`~.handlers.ASGIRouteHandler` class directly
@@ -343,8 +344,6 @@ Like other route handlers, the :func:`@asgi() <.handlers.asgi>` :term:`decorator
  from litestar.status_codes import HTTP_400_BAD_REQUEST
  from litestar.types import Scope, Receive, Send
 
-
- @ASGIRouteHandler(path="/my-asgi-app")
  async def my_asgi_app(scope: Scope, receive: Receive, send: Send) -> None:
  if scope["type"] == "http":
  if scope["method"] == "GET":
@@ -356,7 +355,10 @@ Like other route handlers, the :func:`@asgi() <.handlers.asgi>` :term:`decorator
  )
  await response(scope=scope, receive=receive, send=send)
 
-Limitations of ASGI route handlers
+ my_asgi_app = ASGIRouteHandler(path="/my-asgi-app", fn=my_asgi_app)
+
+
+ASGI route handler considerations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In difference to the other route handlers, the :func:`@asgi() <.handlers.asgi>` route handler accepts only three

docs/usage/websockets.rst

@@ -8,7 +8,7 @@ exceptions, and parsing incoming and serializing outgoing data. In addition to t
 low-level :class:`WebSocket route handler <.handlers.websocket>`, Litestar offers two
 high level interfaces:
 
-- :class:`websocket_listener <.handlers.websocket_listener>`
+- :func:`websocket_listener <.handlers.websocket_listener>`
 - :class:`WebSocketListener <.handlers.WebsocketListener>`
 
 
@@ -38,7 +38,7 @@ type of data which should be received, and it will be converted accordingly.
 
 .. note::
  Contrary to WebSocket route handlers, functions decorated with
- :class:`websocket_listener <.handlers.websocket_listener>` don't have to be
+ :func:`websocket_listener <.handlers.websocket_listener>` don't have to be
  asynchronous.
 
 

litestar/channels/plugin.py

@@ -116,11 +116,11 @@ def on_app_init(self, app_config: AppConfig) -> AppConfig:
  if self._create_route_handlers:
  if self._arbitrary_channels_allowed:
  path = self._handler_root_path + "{channel_name:str}"
- route_handlers = [WebsocketRouteHandler(path)(self._ws_handler_func)]
+ route_handlers = [WebsocketRouteHandler(path, fn=self._ws_handler_func)]
  else:
  route_handlers = [
- WebsocketRouteHandler(self._handler_root_path + channel_name)(
- self._create_ws_handler_func(channel_name)
+ WebsocketRouteHandler(
+ self._handler_root_path + channel_name, fn=self._create_ws_handler_func(channel_name)
  )
  for channel_name in self._channels
  ]

litestar/controller.py

@@ -222,7 +222,7 @@ def get_route_handlers(self) -> list[BaseRouteHandler]:
  route_handler = deepcopy(self_handler)
  # at the point we get a reference to the handler function, it's unbound, so
  # we replace it with a regular bound method here
- route_handler._fn = types.MethodType(route_handler._fn, self)
+ route_handler.fn = types.MethodType(route_handler.fn, self)
  route_handler.owner = self
  route_handlers.append(route_handler)
 

litestar/handlers/asgi_handlers.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, Mapping, Sequence
+from typing import TYPE_CHECKING, Any, Callable, Mapping, Sequence
 
 from litestar.exceptions import ImproperlyConfiguredException
 from litestar.handlers.base import BaseRouteHandler
@@ -13,24 +13,20 @@
 if TYPE_CHECKING:
  from litestar.connection import ASGIConnection
  from litestar.types import (
+ AsyncAnyCallable,
  ExceptionHandlersMap,
  Guard,
- MaybePartial, # noqa: F401
  )
 
 
 class ASGIRouteHandler(BaseRouteHandler):
- """ASGI Route Handler decorator.
-
- Use this decorator to decorate ASGI applications.
- """
-
  __slots__ = ("is_mount",)
 
  def __init__(
  self,
  path: str | Sequence[str] | None = None,
  *,
+ fn: AsyncAnyCallable,
  exception_handlers: ExceptionHandlersMap | None = None,
  guards: Sequence[Guard] | None = None,
  name: str | None = None,
@@ -39,17 +35,20 @@ def __init__(
  signature_namespace: Mapping[str, Any] | None = None,
  **kwargs: Any,
  ) -> None:
- """Initialize ``ASGIRouteHandler``.
+ """Route handler for ASGI routes.
 
  Args:
+ path: A path fragment for the route handler function or a list of path fragments. If not given defaults to
+ ``/``.
+ fn: The handler function.
+
+ .. versionadded:: 3.0
  exception_handlers: A mapping of status codes and/or exception types to handler functions.
  guards: A sequence of :class:`Guard <.types.Guard>` callables.
  name: A string identifying the route handler.
  opt: A string key mapping of arbitrary values that can be accessed in :class:`Guards <.types.Guard>` or
  wherever you have access to :class:`Request <.connection.Request>` or
  :class:`ASGI Scope <.types.Scope>`.
- path: A path fragment for the route handler function or a list of path fragments. If not given defaults to
- ``/``
  is_mount: A boolean dictating whether the handler's paths should be regarded as mount paths. Mount path
  accept any arbitrary paths that begin with the defined prefixed path. For example, a mount with the path
  ``/some-path/`` will accept requests for ``/some-path/`` and any sub path under this, e.g.
@@ -61,6 +60,7 @@ def __init__(
  self.is_mount = is_mount
  super().__init__(
  path,
+ fn=fn,
  exception_handlers=exception_handlers,
  guards=guards,
  name=name,
@@ -101,4 +101,50 @@ async def handle(self, connection: ASGIConnection[ASGIRouteHandler, Any, Any, An
  await self.fn(scope=connection.scope, receive=connection.receive, send=connection.send)
 
 
-asgi = ASGIRouteHandler
+def asgi(
+ path: str | Sequence[str] | None = None,
+ *,
+ exception_handlers: ExceptionHandlersMap | None = None,
+ guards: Sequence[Guard] | None = None,
+ name: str | None = None,
+ opt: Mapping[str, Any] | None = None,
+ is_mount: bool = False,
+ signature_namespace: Mapping[str, Any] | None = None,
+ handler_class: type[ASGIRouteHandler] = ASGIRouteHandler,
+ **kwargs: Any,
+) -> Callable[[AsyncAnyCallable], ASGIRouteHandler]:
+ """Create an :class:`ASGIRouteHandler`.
+
+ Args:
+ path: A path fragment for the route handler function or a sequence of path fragments. If not given defaults
+ to ``/``
+ exception_handlers: A mapping of status codes and/or exception types to handler functions.
+ guards: A sequence of :class:`Guard <.types.Guard>` callables.
+ name: A string identifying the route handler.
+ opt: A string keyed mapping of arbitrary values that can be accessed in :class:`Guards <.types.Guard>` or
+ wherever you have access to :class:`Request <.connection.Request>` or
+ :class:`ASGI Scope <.types.Scope>`.
+ signature_namespace: A mapping of names to types for use in forward reference resolution during signature
+ modelling.
+ is_mount: A boolean dictating whether the handler's paths should be regarded as mount paths. Mount path
+ accept any arbitrary paths that begin with the defined prefixed path. For example, a mount with the path
+ ``/some-path/`` will accept requests for ``/some-path/`` and any sub path under this, e.g.
+ ``/some-path/sub-path/`` etc.
+ handler_class: Route handler class instantiated by the decorator
+ **kwargs: Any additional kwarg - will be set in the opt dictionary.
+ """
+
+ def decorator(fn: AsyncAnyCallable) -> ASGIRouteHandler:
+ return handler_class(
+ fn=fn,
+ path=path,
+ exception_handlers=exception_handlers,
+ guards=guards,
+ name=name,
+ opt=opt,
+ is_mount=is_mount,
+ signature_namespace=signature_namespace,
+ **kwargs,
+ )
+
+ return decorator