Merge branch 'master' into middleware_typing

.github/workflows/cibuildwheel.yaml

@@ -52,6 +52,54 @@ jobs:
           name: cibw-sdist
           path: dist/falcon-*
 
+  publish-sdist:
+    name: publish-sdist
+    needs:
+      - build-sdist
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          pattern: cibw-sdist
+          path: dist
+          merge-multiple: true
+
+      - name: Check collected artifacts
+        run: |
+          tools/check_dist.py ${{ github.event_name == 'release' && format('-r {0}', github.ref) || '' }}
+
+      - name: Upload sdist to release
+        uses: AButler/[email protected]
+        if: github.event_name == 'release'
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          files: 'dist/*.tar.gz'
+
+      - name: Publish sdist and pure-Python wheel to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        if: github.event_name == 'workflow_dispatch'
+        with:
+          password: ${{ secrets.TEST_PYPI_TOKEN }}
+          repository-url: https://test.pypi.org/legacy/
+
+      - name: Publish sdist and pure-Python wheel to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        if: github.event_name == 'release'
+        with:
+          password: ${{ secrets.PYPI_TOKEN }}
+
   build-wheels:
     name: ${{ matrix.python }}-${{ matrix.platform.name }}
     needs: build-sdist
@@ -123,59 +171,9 @@ jobs:
           name: cibw-wheel-${{ matrix.python }}-${{ matrix.platform.name }}
           path: wheelhouse/falcon-*.whl
 
-  publish-sdist:
-    name: publish-sdist
-    needs:
-      - build-sdist
-      - build-wheels
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 2
-
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-
-      - name: Download artifacts
-        uses: actions/download-artifact@v4
-        with:
-          pattern: cibw-sdist
-          path: dist
-          merge-multiple: true
-
-      - name: Check collected artifacts
-        run: |
-          tools/check_dist.py ${{ github.event_name == 'release' && format('-r {0}', github.ref) || '' }}
-
-      - name: Upload sdist to release
-        uses: AButler/[email protected]
-        if: github.event_name == 'release'
-        with:
-          repo-token: ${{ secrets.GITHUB_TOKEN }}
-          files: 'dist/*.tar.gz'
-
-      - name: Publish sdist and pure-Python wheel to TestPyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
-        if: github.event_name == 'workflow_dispatch'
-        with:
-          password: ${{ secrets.TEST_PYPI_TOKEN }}
-          repository-url: https://test.pypi.org/legacy/
-
-      - name: Publish sdist and pure-Python wheel to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
-        if: github.event_name == 'release'
-        with:
-          password: ${{ secrets.PYPI_TOKEN }}
-
   publish-wheels:
     name: publish-wheels
     needs:
-      - build-sdist
       - build-wheels
       - publish-sdist
     runs-on: ubuntu-latest

.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/community/index.rst

@@ -6,4 +6,5 @@ Community Guide
 
    help
    contributing
+   packaging
    ../user/faq