Merge branch 'master' into issue2382

.readthedocs.yaml

@@ -13,8 +13,11 @@ build:
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
   configuration: docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
 formats:
-   - pdf
+  - pdf
+
 # We recommend specifying your dependencies to enable reproducible builds:
 # https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
 python:

AUTHORS

@@ -199,6 +199,9 @@ listed below by date of first contribution:
 * Agustin Arce (aarcex3)
 * Christian Grossmüller (chgad)
 * Sai Prathik R (prathik2401)
+* Akshay Awate (AkshayAwate)
+* Jasper Spaans (jap)
+* Alessandro Chitarrini (chitvs)
 
 (et al.)
 

docs/api/index.rst

@@ -20,3 +20,4 @@ Framework Reference
    inspect
    util
    testing
+   typing

docs/api/typing.rst

@@ -0,0 +1,83 @@
+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.
+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)
+
+(We are working on addressing this limitation at the time of writing --
+please see the following GitHub issue for the progress, and possible solutions:
+`#2372 <https://github.com/falconry/falcon/issues/2372>`__.)
+
+Another known inconsistency is the typing of the
+:class:`converter interface <falcon.routing.BaseConverter>`, where certain
+subclasses (such as :class:`~falcon.routing.PathConverter`) declare a different
+input type than the base ``convert()`` method.
+(See also the discussions and possible solutions on the GitHub issue
+`#2396 <https://github.com/falconry/falcon/issues/2396>`__.)
+
+.. important::
+    The above issues are only typing limitations that have no effect outside of
+    type checking -- applications will work just fine at runtime!
+
+
+Public Type Aliases
+-------------------
+
+.. automodule:: falcon.typing
+    :members:

docs/api/util.rst

@@ -89,9 +89,3 @@ Other
 
 .. autoclass:: falcon.ETag
     :members:
-
-Type Aliases
-------------
-
-.. automodule:: falcon.typing
-    :members:

docs/changes/4.0.2.rst

@@ -0,0 +1,38 @@
+Changelog for Falcon 4.0.2
+==========================
+
+Summary
+-------
+
+This is a minor point release to fix some missed re-exports for type checkers.
+In addition, we have also included a couple of documentation improvements.
+
+
+Fixed
+-----
+
+- Running Mypy on code that uses parts of ``falcon.testing``
+  would previously lead to errors like::
+
+    Name "falcon.testing.TestClient" is not defined
+
+  This has been fixed by explicitly exporting the names that are
+  imported into the ``falcon.testing`` namespace. (`#2387 <https://github.com/falconry/falcon/issues/2387>`__)
+
+
+Misc
+----
+
+- The printable PDF version of our documentation was enabled on Read the Docs. (`#2365 <https://github.com/falconry/falcon/issues/2365>`__)
+
+
+Contributors to this Release
+----------------------------
+
+Many thanks to those who contributed to this bugfix release:
+
+- `AkshayAwate <https://github.com/AkshayAwate>`__
+- `CaselIT <https://github.com/CaselIT>`__
+- `chitvs <https://github.com/chitvs>`__
+- `jap <https://github.com/jap>`__
+- `vytas7 <https://github.com/vytas7>`__

docs/changes/4.1.0.rst

@@ -9,8 +9,8 @@ Falcon 4.1 is in development. The progress is tracked via the
 on GitHub.
 
 
-Changes to Supported Platforms
-------------------------------
+.. Changes to Supported Platforms
+.. ------------------------------
 
 .. NOTE(vytas): No changes to the supported platforms (yet).
 

docs/changes/index.rst

@@ -4,6 +4,7 @@ Changelogs
 .. toctree::
 
    4.1.0 <4.1.0>
+   4.0.2 <4.0.2>
    4.0.1 <4.0.1>
    4.0.0 <4.0.0>
    3.1.3 <3.1.3>

docs/user/faq.rst

@@ -1347,3 +1347,45 @@ Alternatively, you can set the Cookie header directly as demonstrated in this ve
 To include multiple values, simply use ``"; "`` to separate each name-value
 pair. For example, if you were to pass ``{'Cookie': 'xxx=yyy; hello=world'}``,
 you would get ``{'cookies': {'xxx': 'yyy', 'hello': 'world'}}``.
+
+Why do I see no error tracebacks in my ASGI application?
+--------------------------------------------------------
+
+When using Falcon with an ASGI server like Uvicorn,
+you might notice that server errors do not include any traceback by default.
+This behavior differs from WSGI, where the PEP-3333 specification defines the
+`wsgi.errors <https://peps.python.org/pep-3333/#environ-variables>`__ stream
+(which Falcon utilizes to log unhandled
+:class:`internal server errors <falcon.HTTPInternalServerError>`).
+
+Since there is no standardized way to log errors back to the ASGI server,
+the framework simply opts to log them using the ``falcon``
+:class:`logger <logging.Logger>`.
+
+The easiest way to get started is configuring the root logger via
+:func:`logging.basicConfig`:
+
+.. code:: python
+
+    import logging
+
+    import falcon
+    import falcon.asgi
+
+    logging.basicConfig(
+        format="%(asctime)s [%(levelname)s] %(message)s", level=logging.INFO)
+
+
+    class FaultyResource:
+        async def on_get(self, req, resp):
+            raise ValueError('foo')
+
+
+    app = falcon.asgi.App()
+    app.add_route('/things', FaultyResource())
+
+By adding the above logging configuration, you should now see tracebacks logged
+to :any:`stderr <sys.stderr>` when accessing ``/things``.
+
+For additional details on this topic,
+please refer to :ref:`debugging_asgi_applications`.

docs/user/tutorial-asgi.rst

@@ -115,6 +115,68 @@ Woohoo, it works!!!
 
 Well, sort of. Onwards to adding some real functionality!
 
+.. _debugging_asgi_applications:
+
+Debugging ASGI Applications
+---------------------------
+
+While developing and testing a Falcon ASGI application along the lines of this
+tutorial, you may encounter unexpected issues or behaviors, be it a copy-paste
+mistake, an idea that didn't work out, or unusual input where validation falls
+outside of the scope of this tutorial.
+
+Unlike WSGI, the ASGI specification has no standard mechanism for logging
+errors back to the application server, so Falcon falls back to the stdlib's
+:mod:`logging` (using the ``falcon`` :class:`logger <logging.Logger>`).
+
+As a well-behaved library, Falcon does not configure any loggers since that
+might interfere with the user's logging setup.
+Here's how you can set up basic logging in your ASGI Falcon application via
+:func:`logging.basicConfig`:
+
+.. code:: python
+
+    import logging
+
+    import falcon
+
+    logging.basicConfig(level=logging.INFO)
+
+
+    class ErrorResource:
+        def on_get(self, req, resp):
+            raise Exception('Something went wrong!')
+
+
+    app = falcon.App()
+    app.add_route('/error', ErrorResource())
+
+When the above route is accessed, Falcon will catch the unhandled exception and
+automatically log an error message. Below is an example of what the log output
+might look like:
+
+.. code-block:: none
+
+    ERROR:falcon.asgi.app:Unhandled exception in ASGI application
+    Traceback (most recent call last):
+      File "/path/to/your/app.py", line 123, in __call__
+        resp = resource.on_get(req, resp)
+      File "/path/to/your/app.py", line 7, in on_get
+        raise Exception("Something went wrong!")
+    Exception: Something went wrong!
+
+.. note::
+    While logging is helpful for development and debugging, be mindful of
+    logging sensitive information. Ensure that log files are stored securely
+    and are not accessible to unauthorized users.
+
+.. note::
+    Unhandled errors are only logged automatically by Falcon's default error
+    handler for :class:`Exception`. If you
+    :meth:`replace this handler <falcon.asgi.App.add_error_handler>` with your
+    own generic :class:`Exception` handler, you are responsible for logging or
+    reporting these errors yourself.
+
 .. _asgi_tutorial_config:
 
 Configuration
@@ -963,56 +1025,6 @@ adding ``--cov-fail-under=100`` (or any other percent threshold) to our
     tests in multiple environments would most probably involve running
     ``coverage`` directly, and combining results.
 
-Debugging ASGI Applications
----------------------------
-(This section also applies to WSGI applications)
-
-While developing and testing ASGI applications, understanding how to configure
-and utilize logging can be helpful, especially when you encounter unexpected
-issues or behaviors.
-
-By default, Falcon does not set up logging for you,
-but Python's built-in :mod:`logging` module provides a flexible framework for
-emitting and capturing log messages. Here's how you can set up basic logging in
-your ASGI Falcon application:
-
-.. code:: python
-
-    import logging
-
-    import falcon
-
-
-    logging.basicConfig(level=logging.INFO)
-
-    class ErrorResource:
-        def on_get(self, req, resp):
-            raise Exception('Something went wrong!')
-
-    app = falcon.App()
-    app.add_route('/error', ErrorResource())
-
-
-When the above route is accessed, Falcon will catch the unhandled exception and
-automatically log an error message. Below is an example of what the log output
-might look like:
-
-.. code-block:: none
-
-    ERROR:falcon.asgi.app:Unhandled exception in ASGI application
-    Traceback (most recent call last):
-      File "path/to/falcon/app.py", line 123, in __call__
-        resp = resource.on_get(req, resp)
-      File "/path/to/your/app.py", line 7, in on_get
-        raise Exception("Something went wrong!")
-    Exception: Something went wrong!
-
-
-.. note::
-   While logging is helpful for development and debugging, be mindful of logging
-   sensitive information. Ensure that log files are stored securely and are not
-   accessible to unauthorized users.
-
 What Now?
 ---------