From 6fbf085b9955b071cdbb4cee8ac1f8ae2aa87bd5 Mon Sep 17 00:00:00 2001
From: Vytautas Liuolia <vytautas.liuolia@gmail.com>
Date: Sat, 2 Nov 2024 16:14:12 +0100
Subject: [PATCH 1/2] docs(typing): restructure typing docs into a separate
 chapter

---
 docs/api/index.rst  |  1 +
 docs/api/typing.rst | 75 +++++++++++++++++++++++++++++++++++++++++++++
 docs/api/util.rst   |  6 ----
 3 files changed, 76 insertions(+), 6 deletions(-)
 create mode 100644 docs/api/typing.rst

diff --git a/docs/api/index.rst b/docs/api/index.rst
index fdeaadfe3..80ca97517 100644
--- a/docs/api/index.rst
+++ b/docs/api/index.rst
@@ -20,3 +20,4 @@ Framework Reference
    inspect
    util
    testing
+   typing
diff --git a/docs/api/typing.rst b/docs/api/typing.rst
new file mode 100644
index 000000000..5d2e5e872
--- /dev/null
+++ b/docs/api/typing.rst
@@ -0,0 +1,75 @@
+Typing Support
+==============
+
+Type checking support was introduced in version 4.0. While most of the library is
+now typed, further type annotations may be added throughout the 4.x release cycle.
+To improve them, we may introduce changes to the typing that do not affect
+runtime behavior, but may surface new or different errors with type checkers.
+
+.. role:: python(code)
+    :language: python
+
+.. note::
+    All undocumented type aliases coming from ``falcon._typing`` are considered
+    private to the framework itself, and not meant for annotating applications
+    using Falcon. To that end, it is advisable to only use classes from the
+    public interface, and public aliases from :mod:`falcon.typing`, e.g.:
+
+    .. code-block:: python
+
+        class MyResource:
+            def on_get(self, req: falcon.Request, resp: falcon.Response) -> None:
+                resp.media = {'message': 'Hello, World!'}
+
+    If you still decide to reuse the private aliases anyway, they should
+    preferably be imported inside :python:`if TYPE_CHECKING:` blocks in order
+    to avoid possible runtime errors after an update.
+    Also, make sure to :ref:`let us know <chat>` which essential aliases are
+    missing from the public interface!
+
+
+Known limitations
+-----------------
+
+Falcon's emphasis on flexibility and performance presents certain
+challenges when it comes to adding type annotations to the existing code base.
+One notable limitation involves using custom :class:`~falcon.Request` and/or
+:class:`~falcon.Response` types in callbacks that are passed back
+to the framework, such as when adding an
+:meth:`error handler <falcon.App.add_error_handler>`.
+
+For instance, the following application might unexpectedly not pass type
+checking:
+
+.. code-block:: python
+
+    from typing import Any
+
+    from falcon import App, HTTPInternalServerError, Request, Response
+
+
+    class MyRequest(Request):
+        ...
+
+
+    def handle_os_error(req: MyRequest, resp: Response, ex: Exception,
+                        params: dict[str, Any]) -> None:
+        raise HTTPInternalServerError(title='OS error!') from ex
+
+
+    app = App(request_type=MyRequest)
+    app.add_error_handler(OSError, handle_os_error)
+
+(Please also see the following GitHub issue:
+`#2372 <https://github.com/falconry/falcon/issues/2372>`__.)
+
+.. important::
+    This is only a typing limitation that has no effect outside of type
+    checking -- the above ``app`` will run just fine!
+
+
+Public type aliases
+-------------------
+
+.. automodule:: falcon.typing
+    :members:
diff --git a/docs/api/util.rst b/docs/api/util.rst
index 254b4cb60..93fa163a4 100644
--- a/docs/api/util.rst
+++ b/docs/api/util.rst
@@ -89,9 +89,3 @@ Other
 
 .. autoclass:: falcon.ETag
     :members:
-
-Type Aliases
-------------
-
-.. automodule:: falcon.typing
-    :members:

From 56729795294cce65612521db76a3453abf3eecd6 Mon Sep 17 00:00:00 2001
From: Vytautas Liuolia <vytautas.liuolia@gmail.com>
Date: Mon, 4 Nov 2024 18:14:32 +0100
Subject: [PATCH 2/2] docs(typing): tweak misc stuff for consistency

---
 docs/api/typing.rst | 8 ++++----
 falcon/typing.py    | 2 +-
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/api/typing.rst b/docs/api/typing.rst
index 5d2e5e872..5bca16c44 100644
--- a/docs/api/typing.rst
+++ b/docs/api/typing.rst
@@ -1,5 +1,5 @@
-Typing Support
-==============
+Typing
+======
 
 Type checking support was introduced in version 4.0. While most of the library is
 now typed, further type annotations may be added throughout the 4.x release cycle.
@@ -28,7 +28,7 @@ runtime behavior, but may surface new or different errors with type checkers.
     missing from the public interface!
 
 
-Known limitations
+Known Limitations
 -----------------
 
 Falcon's emphasis on flexibility and performance presents certain
@@ -68,7 +68,7 @@ checking:
     checking -- the above ``app`` will run just fine!
 
 
-Public type aliases
+Public Type Aliases
 -------------------
 
 .. automodule:: falcon.typing
diff --git a/falcon/typing.py b/falcon/typing.py
index 1eadeee9f..dd4aa8212 100644
--- a/falcon/typing.py
+++ b/falcon/typing.py
@@ -26,7 +26,7 @@
 
 # WSGI
 class ReadableIO(Protocol):
-    """File like protocol that defines only a read method."""
+    """File-like protocol that defines only a read method."""
 
     def read(self, n: Optional[int] = ..., /) -> bytes: ...