fix(typing): include protocols for WebSocket middleware + cleanup (#2472)

Follow-up to #2390.

Author: vytas7

docs/conf.py

@@ -125,6 +125,8 @@
 # TODO(vytas): If we enable the "nitpicky" mode, we will have to add exceptions
 #   for all unresolved aliases.
 autodoc_type_aliases = {
+    'SyncMiddleware': 'SyncMiddleware',
+    'AsyncMiddleware': 'AsyncMiddleware',
     'PreparedMiddlewareResult': 'PreparedMiddlewareResult',
 }
 

falcon/_typing.py

@@ -200,14 +200,14 @@ def __call__(self, media: Any, content_type: Optional[str] = ...) -> bytes: ...
 Responder = Union[ResponderMethod, AsgiResponderMethod]
 
 
-# Middleware
-class MiddlewareWithProcessRequest(Protocol):
+# WSGI middleware interface
+class WsgiMiddlewareWithProcessRequest(Protocol):
     """WSGI Middleware with request handler."""
 
     def process_request(self, req: Request, resp: Response) -> None: ...
 
 
-class MiddlewareWithProcessResource(Protocol):
+class WsgiMiddlewareWithProcessResource(Protocol):
     """WSGI Middleware with resource handler."""
 
     def process_resource(
@@ -219,14 +219,15 @@ def process_resource(
     ) -> None: ...
 
 
-class MiddlewareWithProcessResponse(Protocol):
+class WsgiMiddlewareWithProcessResponse(Protocol):
     """WSGI Middleware with response handler."""
 
     def process_response(
         self, req: Request, resp: Response, resource: object, req_succeeded: bool
     ) -> None: ...
 
 
+# ASGI lifespan middleware interface
 class AsgiMiddlewareWithProcessStartup(Protocol):
     """ASGI middleware with startup handler."""
 
@@ -243,6 +244,7 @@ async def process_shutdown(
     ) -> None: ...
 
 
+# ASGI middleware interface
 class AsgiMiddlewareWithProcessRequest(Protocol):
     """ASGI middleware with request handler."""
 
@@ -273,13 +275,14 @@ async def process_response(
     ) -> None: ...
 
 
-class MiddlewareWithAsyncProcessRequestWs(Protocol):
+# ASGI WebSocket middleware
+class AsgiMiddlewareWithProcessRequestWs(Protocol):
     """ASGI middleware with WebSocket request handler."""
 
     async def process_request_ws(self, req: AsgiRequest, ws: WebSocket) -> None: ...
 
 
-class MiddlewareWithAsyncProcessResourceWs(Protocol):
+class AsgiMiddlewareWithProcessResourceWs(Protocol):
     """ASGI middleware with WebSocket resource handler."""
 
     async def process_resource_ws(
@@ -291,15 +294,18 @@ async def process_resource_ws(
     ) -> None: ...
 
 
-class UniversalMiddlewareWithProcessRequest(MiddlewareWithProcessRequest, Protocol):
+# Universal middleware that provides async versions via the _async postfix
+class UniversalMiddlewareWithProcessRequest(WsgiMiddlewareWithProcessRequest, Protocol):
     """WSGI/ASGI middleware with request handler."""
 
     async def process_request_async(
         self, req: AsgiRequest, resp: AsgiResponse
     ) -> None: ...
 
 
-class UniversalMiddlewareWithProcessResource(MiddlewareWithProcessResource, Protocol):
+class UniversalMiddlewareWithProcessResource(
+    WsgiMiddlewareWithProcessResource, Protocol
+):
     """WSGI/ASGI middleware with resource handler."""
 
     async def process_resource_async(
@@ -311,7 +317,9 @@ async def process_resource_async(
     ) -> None: ...
 
 
-class UniversalMiddlewareWithProcessResponse(MiddlewareWithProcessResponse, Protocol):
+class UniversalMiddlewareWithProcessResponse(
+    WsgiMiddlewareWithProcessResponse, Protocol
+):
     """WSGI/ASGI middleware with response handler."""
 
     async def process_response_async(
@@ -326,19 +334,34 @@ async def process_response_async(
 # NOTE(jkmnt): This typing is far from perfect due to the Python typing limitations,
 # but better than nothing. Middleware conforming to any protocol of the union
 # will pass the type check. Other protocols violations are not checked.
-Middleware = Union[
-    MiddlewareWithProcessRequest,
-    MiddlewareWithProcessResource,
-    MiddlewareWithProcessResponse,
+SyncMiddleware = Union[
+    WsgiMiddlewareWithProcessRequest,
+    WsgiMiddlewareWithProcessResource,
+    WsgiMiddlewareWithProcessResponse,
 ]
+"""Synchronous (WSGI) application middleware.
 
-AsgiMiddleware = Union[
+This type alias reflects the middleware interface for
+components that can be used with a WSGI app.
+"""
+
+AsyncMiddleware = Union[
     AsgiMiddlewareWithProcessRequest,
     AsgiMiddlewareWithProcessResource,
     AsgiMiddlewareWithProcessResponse,
+    # Lifespan middleware
     AsgiMiddlewareWithProcessStartup,
     AsgiMiddlewareWithProcessShutdown,
+    # WebSocket middleware
+    AsgiMiddlewareWithProcessRequestWs,
+    AsgiMiddlewareWithProcessResourceWs,
+    # Universal middleware with process_*_async methods
     UniversalMiddlewareWithProcessRequest,
     UniversalMiddlewareWithProcessResource,
     UniversalMiddlewareWithProcessResponse,
 ]
+"""Asynchronous (ASGI) application middleware.
+
+This type alias reflects the middleware interface for components that can be
+used with an ASGI app.
+"""

falcon/app.py

@@ -51,12 +51,12 @@
 from falcon._typing import ErrorHandler
 from falcon._typing import ErrorSerializer
 from falcon._typing import FindMethod
-from falcon._typing import Middleware
 from falcon._typing import ProcessResponseMethod
 from falcon._typing import ResponderCallable
 from falcon._typing import SinkCallable
 from falcon._typing import SinkPrefix
 from falcon._typing import StartResponse
+from falcon._typing import SyncMiddleware
 from falcon._typing import WSGIEnvironment
 from falcon.errors import CompatibilityError
 from falcon.errors import HTTPBadRequest
@@ -287,7 +287,7 @@ def process_response(
     _static_routes: List[
         Tuple[routing.StaticRoute, routing.StaticRoute, Literal[False]]
     ]
-    _unprepared_middleware: List[Middleware]
+    _unprepared_middleware: List[SyncMiddleware]
 
     # Attributes
     req_options: RequestOptions
@@ -306,7 +306,7 @@ def __init__(
         media_type: str = constants.DEFAULT_MEDIA_TYPE,
         request_type: Optional[Type[Request]] = None,
         response_type: Optional[Type[Response]] = None,
-        middleware: Optional[Union[Middleware, Iterable[Middleware]]] = None,
+        middleware: Optional[Union[SyncMiddleware, Iterable[SyncMiddleware]]] = None,
         router: Optional[routing.CompiledRouter] = None,
         independent_middleware: bool = True,
         cors_enable: bool = False,
@@ -328,12 +328,12 @@ def __init__(
                     # NOTE(kgriffs): Check to see if middleware is an
                     #   iterable, and if so, append the CORSMiddleware
                     #   instance.
-                    middleware = list(cast(Iterable[Middleware], middleware))
+                    middleware = list(cast(Iterable[SyncMiddleware], middleware))
                     middleware.append(cm)
                 except TypeError:
                     # NOTE(kgriffs): Assume the middleware kwarg references
                     #   a single middleware component.
-                    middleware = [cast(Middleware, middleware), cm]
+                    middleware = [cast(SyncMiddleware, middleware), cm]
 
         # set middleware
         self._unprepared_middleware = []
@@ -526,7 +526,7 @@ def router_options(self) -> routing.CompiledRouterOptions:
         return self._router.options
 
     def add_middleware(
-        self, middleware: Union[Middleware, Iterable[Middleware]]
+        self, middleware: Union[SyncMiddleware, Iterable[SyncMiddleware]]
     ) -> None:
         """Add one or more additional middleware components.
 
@@ -541,10 +541,10 @@ def add_middleware(
         #   the chance that middleware may be empty.
         if middleware:
             try:
-                middleware = list(cast(Iterable[Middleware], middleware))
+                middleware = list(cast(Iterable[SyncMiddleware], middleware))
             except TypeError:
                 # middleware is not iterable; assume it is just one bare component
-                middleware = [cast(Middleware, middleware)]
+                middleware = [cast(SyncMiddleware, middleware)]
 
             if (
                 self._cors_enable
@@ -1015,7 +1015,7 @@ def my_serializer(
     # ------------------------------------------------------------------------
 
     def _prepare_middleware(
-        self, middleware: List[Middleware], independent_middleware: bool = False
+        self, middleware: List[SyncMiddleware], independent_middleware: bool = False
     ) -> helpers.PreparedMiddlewareResult:
         return helpers.prepare_middleware(
             middleware=middleware, independent_middleware=independent_middleware

falcon/app_helpers.py

@@ -20,16 +20,16 @@
 from typing import IO, Iterable, List, Literal, Optional, overload, Tuple, Union
 
 from falcon import util
-from falcon._typing import AsgiMiddleware
 from falcon._typing import AsgiProcessRequestMethod as APRequest
 from falcon._typing import AsgiProcessRequestWsMethod
 from falcon._typing import AsgiProcessResourceMethod as APResource
 from falcon._typing import AsgiProcessResourceWsMethod
 from falcon._typing import AsgiProcessResponseMethod as APResponse
-from falcon._typing import Middleware
+from falcon._typing import AsyncMiddleware
 from falcon._typing import ProcessRequestMethod as PRequest
 from falcon._typing import ProcessResourceMethod as PResource
 from falcon._typing import ProcessResponseMethod as PResponse
+from falcon._typing import SyncMiddleware
 from falcon.constants import MEDIA_JSON
 from falcon.constants import MEDIA_XML
 from falcon.errors import CompatibilityError
@@ -64,15 +64,15 @@
 
 @overload
 def prepare_middleware(
-    middleware: Iterable[Middleware],
+    middleware: Iterable[SyncMiddleware],
     independent_middleware: bool = ...,
     asgi: Literal[False] = ...,
 ) -> PreparedMiddlewareResult: ...
 
 
 @overload
 def prepare_middleware(
-    middleware: Iterable[AsgiMiddleware],
+    middleware: Iterable[AsyncMiddleware],
     independent_middleware: bool = ...,
     *,
     asgi: Literal[True],
@@ -81,14 +81,14 @@ def prepare_middleware(
 
 @overload
 def prepare_middleware(
-    middleware: Union[Iterable[Middleware], Iterable[AsgiMiddleware]],
+    middleware: Union[Iterable[SyncMiddleware], Iterable[AsyncMiddleware]],
     independent_middleware: bool = ...,
     asgi: bool = ...,
 ) -> Union[PreparedMiddlewareResult, AsyncPreparedMiddlewareResult]: ...
 
 
 def prepare_middleware(
-    middleware: Union[Iterable[Middleware], Iterable[AsgiMiddleware]],
+    middleware: Union[Iterable[SyncMiddleware], Iterable[AsyncMiddleware]],
     independent_middleware: bool = False,
     asgi: bool = False,
 ) -> Union[PreparedMiddlewareResult, AsyncPreparedMiddlewareResult]:
@@ -223,7 +223,7 @@ def prepare_middleware(
 
 
 def prepare_middleware_ws(
-    middleware: Iterable[AsgiMiddleware],
+    middleware: Iterable[AsyncMiddleware],
 ) -> AsyncPreparedMiddlewareWsResult:
     """Check middleware interfaces and prepare WebSocket methods for request handling.
 

falcon/asgi/app.py

@@ -42,12 +42,12 @@
 from falcon import routing
 from falcon._typing import _UNSET
 from falcon._typing import AsgiErrorHandler
-from falcon._typing import AsgiMiddleware
 from falcon._typing import AsgiReceive
 from falcon._typing import AsgiResponderCallable
 from falcon._typing import AsgiResponderWsCallable
 from falcon._typing import AsgiSend
 from falcon._typing import AsgiSinkCallable
+from falcon._typing import AsyncMiddleware
 from falcon._typing import SinkPrefix
 import falcon.app
 from falcon.app_helpers import AsyncPreparedMiddlewareResult
@@ -357,7 +357,7 @@ async def process_resource_ws(
     _middleware_ws: AsyncPreparedMiddlewareWsResult
     _request_type: Type[Request]
     _response_type: Type[Response]
-    _unprepared_middleware: List[AsgiMiddleware]  # type: ignore[assignment]
+    _unprepared_middleware: List[AsyncMiddleware]  # type: ignore[assignment]
 
     ws_options: WebSocketOptions
     """A set of behavioral options related to WebSocket connections.
@@ -370,7 +370,7 @@ def __init__(
         media_type: str = constants.DEFAULT_MEDIA_TYPE,
         request_type: Optional[Type[Request]] = None,
         response_type: Optional[Type[Response]] = None,
-        middleware: Optional[Union[AsgiMiddleware, Iterable[AsgiMiddleware]]] = None,
+        middleware: Optional[Union[AsyncMiddleware, Iterable[AsyncMiddleware]]] = None,
         router: Optional[routing.CompiledRouter] = None,
         independent_middleware: bool = True,
         cors_enable: bool = False,
@@ -1165,7 +1165,7 @@ async def _handle_websocket(
                 raise
 
     def _prepare_middleware(  # type: ignore[override]
-        self, middleware: List[AsgiMiddleware], independent_middleware: bool = False
+        self, middleware: List[AsyncMiddleware], independent_middleware: bool = False
     ) -> AsyncPreparedMiddlewareResult:
         self._middleware_ws = prepare_middleware_ws(middleware)
 

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.
-"""Module that defines public Falcon type definitions."""
+"""Public Falcon type alias definitions."""
 
 from __future__ import annotations
 
@@ -20,6 +20,13 @@
 if TYPE_CHECKING:
     from falcon.asgi import SSEvent
 
+__all__ = (
+    'Headers',
+    'ReadableIO',
+    'AsyncReadableIO',
+    'SSEEmitter',
+)
+
 Headers = Dict[str, str]
 """Headers dictionary returned by the framework.