feat: Deprecate subclassing route handler decorators (#3439)

* Deprecate subclassing route handler decorators

docs/conf.py

@@ -184,6 +184,7 @@
  ("py:exc", "HTTPExceptions"),
  (PY_CLASS, "litestar.template.Template"),
  (PY_CLASS, "litestar.middleware.compression.gzip_facade.GzipCompression"),
+ (PY_CLASS, "litestar.handlers.http_handlers.decorators._SubclassWarningMixin"),
 ]
 
 nitpick_ignore_regex = [

litestar/handlers/http_handlers/decorators.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import warnings
 from typing import TYPE_CHECKING
 
 from litestar.enums import HttpMethod, MediaType
@@ -45,7 +46,17 @@
 MSG_SEMANTIC_ROUTE_HANDLER_WITH_HTTP = "semantic route handlers cannot define http_method"
 
 
-class delete(HTTPRouteHandler):
+class _SubclassWarningMixin:
+ def __init_subclass__(cls, **kwargs: Any) -> None:
+ warnings.warn(
+ "Semantic HTTP route handler classes are deprecated and will be replaced by"
+ "functional decorators in Litestar 3.0.",
+ category=DeprecationWarning,
+ stacklevel=2,
+ )
+
+
+class delete(HTTPRouteHandler, _SubclassWarningMixin):
  """DELETE Route Decorator.
 
  Use this decorator to decorate an HTTP handler for DELETE requests.
@@ -217,7 +228,7 @@ def __init__(
  )
 
 
-class get(HTTPRouteHandler):
+class get(HTTPRouteHandler, _SubclassWarningMixin):
  """GET Route Decorator.
 
  Use this decorator to decorate an HTTP handler for GET requests.
@@ -390,7 +401,7 @@ def __init__(
  )
 
 
-class head(HTTPRouteHandler):
+class head(HTTPRouteHandler, _SubclassWarningMixin):
  """HEAD Route Decorator.
 
  Use this decorator to decorate an HTTP handler for HEAD requests.
@@ -580,7 +591,7 @@ def _validate_handler_function(self) -> None:
  raise ImproperlyConfiguredException("A response to a head request should not have a body")
 
 
-class patch(HTTPRouteHandler):
+class patch(HTTPRouteHandler, _SubclassWarningMixin):
  """PATCH Route Decorator.
 
  Use this decorator to decorate an HTTP handler for PATCH requests.
@@ -752,7 +763,7 @@ def __init__(
  )
 
 
-class post(HTTPRouteHandler):
+class post(HTTPRouteHandler, _SubclassWarningMixin):
  """POST Route Decorator.
 
  Use this decorator to decorate an HTTP handler for POST requests.
@@ -924,7 +935,7 @@ def __init__(
  )
 
 
-class put(HTTPRouteHandler):
+class put(HTTPRouteHandler, _SubclassWarningMixin):
  """PUT Route Decorator.
 
  Use this decorator to decorate an HTTP handler for PUT requests.

tests/unit/test_handlers/test_http_handlers/test_deprecation.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+import pytest
+
+from litestar.handlers import delete, get, head, patch, post, put
+
+
+@pytest.mark.parametrize("handler_cls", [get, post, put, patch, delete, head])
+def test_subclass_warns_deprecation(handler_cls: get | post | put | patch | delete | head) -> None:
+ with pytest.warns(DeprecationWarning):
+
+ class SubClass(handler_cls): # type: ignore[valid-type, misc]
+ pass