feat(typing): parametrize App by default req/resp types on 3.13+ (#2591)

* feat(typing): use TypeVar defaults on 3.13+ (WiP)

* feat(typing): clean up _ReqT/_RespT with defaults

* docs(typing): document the new improvements

Co-authored-by: Jasper Spaans <j@jasper.es>

---------

Co-authored-by: Jasper Spaans <j@jasper.es>

Author: vytas7

docs/_newsfragments/2586.newandimproved.rst

@@ -0,0 +1,3 @@
+:ref:`Generic App types <generic_app_types>` are now automatically parametrized
+by the default request/response types (unless specified otherwise), courtesy of
+:class:`~typing.TypeVar`\'s default value support on CPython 3.13+.

docs/api/typing.rst

@@ -44,10 +44,11 @@ The use of generics should in most cases require no explicit effort on your
 side. However, if you annotate your variables or return types as
 ``falcon.App``, the type checker may require you to provide the explicit type
 parameters when running in the strict mode (Mypy calls the option
-``--disallow-any-generics``, also part of the ``--strict`` mode flag).
+``--disallow-any-generics``, also part of the ``--strict`` mode flag) on
+Python 3.12 or older.
 
 For instance, the following mini-application will not pass type checking with
-Mypy in the ``--strict`` mode:
+Mypy in the ``--strict`` mode on, e.g., CPython 3.12:
 
 .. code-block:: python
 
@@ -123,6 +124,11 @@ Both alternatives should now pass type checking in the ``--strict`` mode.
     :class:`generic types <typing.Generic>` parametrized by the request and
     response classes.
 
+.. versionchanged:: 4.3
+    :class:`falcon.App` and :class:`falcon.asgi.App` are now automatically
+    parametrized by the default request/response types unless specified
+    otherwise. However, this only works on CPython 3.13+.
+
 
 Known Limitations
 -----------------

docs/changes/4.3.0.rst

@@ -25,6 +25,7 @@ Many thanks to all of our talented and stylish contributors for this release!
 - `0x1618 <https://github.com/0x1618>`__
 - `0xMattB <https://github.com/0xMattB>`__
 - `granuels <https://github.com/granuels>`__
+- `jap <https://github.com/jap>`__
 - `rushevich <https://github.com/rushevich>`__
 - `thisisrick25 <https://github.com/thisisrick25>`__
 - `TudorGR <https://github.com/TudorGR>`__

falcon/_typing.py

@@ -11,7 +11,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-"""Private type aliases used internally by Falcon.."""
+"""Private type aliases used internally by Falcon."""
 
 from __future__ import annotations
 
@@ -63,10 +63,23 @@ class _Unset(Enum):
 _UNSET = _Unset.UNSET
 UnsetOr = Union[Literal[_Unset.UNSET], _T]
 
-_ReqT = TypeVar('_ReqT', bound='Request', contravariant=True)
-_RespT = TypeVar('_RespT', bound='Response', contravariant=True)
-_AReqT = TypeVar('_AReqT', bound='AsgiRequest', contravariant=True)
-_ARespT = TypeVar('_ARespT', bound='AsgiResponse', contravariant=True)
+# NOTE(vytas,jap): TypeVar's "default" argument is only available on 3.13+.
+if sys.version_info >= (3, 13):
+    _ExcT = TypeVar('_ExcT', bound=Exception, default=Exception)
+    _ReqT = TypeVar('_ReqT', bound='Request', contravariant=True, default='Request')
+    _RespT = TypeVar('_RespT', bound='Response', contravariant=True, default='Response')
+    _AReqT = TypeVar(
+        '_AReqT', bound='AsgiRequest', contravariant=True, default='AsgiRequest'
+    )
+    _ARespT = TypeVar(
+        '_ARespT', bound='AsgiResponse', contravariant=True, default='AsgiResponse'
+    )
+else:
+    _ExcT = TypeVar('_ExcT', bound=Exception)
+    _ReqT = TypeVar('_ReqT', bound='Request', contravariant=True)
+    _RespT = TypeVar('_RespT', bound='Response', contravariant=True)
+    _AReqT = TypeVar('_AReqT', bound='AsgiRequest', contravariant=True)
+    _ARespT = TypeVar('_ARespT', bound='AsgiResponse', contravariant=True)
 
 Link = dict[str, str]
 CookieArg = Mapping[str, Union[str, Cookie]]

falcon/app.py

@@ -31,17 +31,18 @@
     Generic,
     Literal,
     overload,
-    TypeVar,
 )
 import warnings
 
 from falcon import app_helpers as helpers
 from falcon import constants
 from falcon import responders
 from falcon import routing
+from falcon._typing import _ExcT
+from falcon._typing import _ReqT
+from falcon._typing import _RespT
 from falcon._typing import AsgiResponderCallable
 from falcon._typing import AsgiResponderWsCallable
-from falcon._typing import AsgiSinkCallable
 from falcon._typing import ErrorHandler
 from falcon._typing import ErrorSerializer
 from falcon._typing import FindMethod
@@ -86,10 +87,6 @@
     ]
 )
 
-_ExcT = TypeVar('_ExcT', bound=Exception)
-_ReqT = TypeVar('_ReqT', bound=Request, contravariant=True)
-_RespT = TypeVar('_RespT', bound=Response, contravariant=True)
-
 
 class App(Generic[_ReqT, _RespT]):
     '''The main entry point into a Falcon-based WSGI app.
@@ -268,17 +265,17 @@ def process_response(
     # NOTE(caselit): this should actually be a protocol of the methods required
     # by a router, hardcoded to CompiledRouter for convenience for now.
     _router: routing.CompiledRouter
-    _serialize_error: ErrorSerializer
+    _serialize_error: ErrorSerializer[_ReqT, _RespT]
     _sink_and_static_routes: tuple[
         tuple[
             Pattern[str] | routing.StaticRoute,
-            SinkCallable | AsgiSinkCallable | routing.StaticRoute,
+            SinkCallable[_ReqT, _RespT] | routing.StaticRoute,
             bool,
         ],
         ...,
     ]
     _sink_before_static_route: bool
-    _sinks: list[tuple[Pattern[str], SinkCallable | AsgiSinkCallable, Literal[True]]]
+    _sinks: list[tuple[Pattern[str], SinkCallable[_ReqT, _RespT], Literal[True]]]
     _static_routes: list[
         tuple[routing.StaticRoute, routing.StaticRoute, Literal[False]]
     ]
@@ -1167,7 +1164,7 @@ def _get_responder(
                 if m:
                     if is_sink:
                         params = m.groupdict()  # type: ignore[union-attr]
-                    responder = obj
+                    responder = obj  # type: ignore[assignment,unused-ignore]
 
                     break
             else:
@@ -1220,7 +1217,7 @@ def _python_error_handler(
         req.log_error(traceback.format_exc())
         self._compose_error_response(req, resp, HTTPInternalServerError())
 
-    def _find_error_handler(self, ex: Exception) -> ErrorHandler | None:
+    def _find_error_handler(self, ex: Exception) -> ErrorHandler[_ReqT, _RespT] | None:
         # NOTE(csojinb): The `__mro__` class attribute returns the method
         # resolution order tuple, i.e. the complete linear inheritance chain
         # ``(type(ex), ..., object)``. For a valid exception class, the last

falcon/app_helpers.py

@@ -21,6 +21,8 @@
 from typing import IO, Literal, Optional, overload, Union
 
 from falcon import util
+from falcon._typing import _AReqT
+from falcon._typing import _ARespT
 from falcon._typing import _ReqT
 from falcon._typing import _RespT
 from falcon._typing import AsgiProcessRequestMethod as APRequest
@@ -75,7 +77,7 @@ def prepare_middleware(
 
 @overload
 def prepare_middleware(
-    middleware: Iterable[AsyncMiddleware],
+    middleware: Iterable[AsyncMiddleware[_AReqT, _ARespT]],
     independent_middleware: bool = ...,
     *,
     asgi: Literal[True],
@@ -84,14 +86,16 @@ def prepare_middleware(
 
 @overload
 def prepare_middleware(
-    middleware: Iterable[SyncMiddleware[_ReqT, _RespT]] | Iterable[AsyncMiddleware],
+    middleware: Iterable[SyncMiddleware[_ReqT, _RespT]]
+    | Iterable[AsyncMiddleware[_AReqT, _ARespT]],
     independent_middleware: bool = ...,
     asgi: bool = ...,
 ) -> PreparedMiddlewareResult | AsyncPreparedMiddlewareResult: ...
 
 
 def prepare_middleware(
-    middleware: Iterable[SyncMiddleware[_ReqT, _RespT]] | Iterable[AsyncMiddleware],
+    middleware: Iterable[SyncMiddleware[_ReqT, _RespT]]
+    | Iterable[AsyncMiddleware[_AReqT, _ARespT]],
     independent_middleware: bool = False,
     asgi: bool = False,
 ) -> PreparedMiddlewareResult | AsyncPreparedMiddlewareResult:
@@ -225,7 +229,7 @@ def prepare_middleware(
 
 
 def prepare_middleware_ws(
-    middleware: Iterable[AsyncMiddleware],
+    middleware: Iterable[AsyncMiddleware[_AReqT, _ARespT]],
 ) -> AsyncPreparedMiddlewareWsResult:
     """Check middleware interfaces and prepare WebSocket methods for request handling.
 

falcon/asgi/app.py

@@ -28,13 +28,15 @@
     ClassVar,
     overload,
     TYPE_CHECKING,
-    TypeVar,
 )
 import warnings
 
 from falcon import constants
 from falcon import responders
 from falcon import routing
+from falcon._typing import _AReqT as _ReqT
+from falcon._typing import _ARespT as _RespT
+from falcon._typing import _ExcT
 from falcon._typing import _UNSET
 from falcon._typing import AsgiErrorHandler
 from falcon._typing import AsgiReceive
@@ -81,7 +83,7 @@
 __all__ = ('App',)
 
 
-# TODO(vytas): Clean up these foul workarounds before the 4.0 release.
+# TODO(vytas): Clean up these foul workarounds before the 5.0 release.
 MultipartFormHandler._ASGI_MULTIPART_FORM = MultipartForm
 
 _EVT_RESP_EOF: AsgiSendMsg = {'type': EventType.HTTP_RESPONSE_BODY}
@@ -92,10 +94,6 @@
 
 _FALLBACK_WS_ERROR_CODE = 3011
 
-_ExcT = TypeVar('_ExcT', bound=Exception)
-_ReqT = TypeVar('_ReqT', bound=Request, contravariant=True)
-_RespT = TypeVar('_RespT', bound=Response, contravariant=True)
-
 
 class App(falcon.app.App[_ReqT, _RespT]):
     '''The main entry point into a Falcon-based ASGI app.