feat(typing): type request module (#2271)

* Type request module

* types: improve types in media, request helpers

* types: type sync request

* types: type async request

* typing: additional improvements and clanup

* typing: minor overload improvements and removal of unnecessary casts

* style: fix docs linter issues

* fix: catch warning and fix typing errors

* fix: allow untyped defs in the test package

* chore: try fixing missing coverage

* chore: remove no longer needed except clauses

* chore: try making coverage happy

* chore: try making coverage happy, take 2

* typing: normalize naming convention

* chore: ruff check fixes

* refactor: move missing to typing module; underscore it

---------

Co-authored-by: Piotr Kopalko <copalco@gmail.com>
Co-authored-by: Dave Tapley <dave@tapley.com>

docs/conf.py

@@ -10,12 +10,12 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-from datetime import datetime
 from collections import OrderedDict
 import configparser
+from datetime import datetime
 import multiprocessing
-import sys
 import os
+import sys
 
 sys.path.insert(0, os.path.abspath('..'))
 

docs/ext/rfc.py

@@ -22,7 +22,6 @@
 
 import re
 
-
 RFC_PATTERN = re.compile(r'RFC (\d{4}), Section ([\d\.]+)')
 
 

falcon/asgi/_request_helpers.py

@@ -11,9 +11,15 @@
 # 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.
+from __future__ import annotations
 
+from typing import Any, Optional, TYPE_CHECKING
 
-def header_property(header_name):
+if TYPE_CHECKING:
+    from falcon.asgi import Request
+
+
+def header_property(header_name: str) -> Any:
     """Create a read-only header property.
 
     Args:
@@ -25,14 +31,14 @@ def header_property(header_name):
 
     """
 
-    header_name = header_name.lower().encode()
+    header_bytes = header_name.lower().encode()
 
-    def fget(self):
+    def fget(self: Request) -> Optional[str]:
         try:
             # NOTE(vytas): Supporting ISO-8859-1 for historical reasons as per
             #   RFC 7230, Section 3.2.4; and to strive for maximum
             #   compatibility with WSGI.
-            return self._asgi_headers[header_name].decode('latin1') or None
+            return self._asgi_headers[header_bytes].decode('latin1') or None
         except KeyError:
             return None
 

falcon/asgi/app.py

@@ -567,7 +567,7 @@ async def watch_disconnect():
             if resp._registered_callbacks:
                 self._schedule_callbacks(resp)
 
-            handler, _, _ = self.resp_options.media_handlers._resolve(
+            sse_handler, _, _ = self.resp_options.media_handlers._resolve(
                 MEDIA_JSON, MEDIA_JSON, raise_not_found=False
             )
 
@@ -583,7 +583,7 @@ async def watch_disconnect():
                 await send(
                     {
                         'type': EventType.HTTP_RESPONSE_BODY,
-                        'body': event.serialize(handler),
+                        'body': event.serialize(sse_handler),
                         'more_body': True,
                     }
                 )