From da0c53a2b420edec5bfd455780cb9a9d7b1bd878 Mon Sep 17 00:00:00 2001 From: Vytautas Liuolia Date: Tue, 15 Oct 2024 21:30:04 +0200 Subject: [PATCH 1/4] docs(changes): describe a known typing issue --- docs/changes/4.0.0.rst | 45 +++++++++++++++++++++++++++++++++++------- 1 file changed, 38 insertions(+), 7 deletions(-) diff --git a/docs/changes/4.0.0.rst b/docs/changes/4.0.0.rst index c3e9d426a..c5bf5764d 100644 --- a/docs/changes/4.0.0.rst +++ b/docs/changes/4.0.0.rst @@ -50,7 +50,8 @@ Changes to Supported Platforms later 4.x release, especially if we are faced with incompatible ecosystem changes in typing, Cython, etc. -Typing support + +Typing Support -------------- Type checking support was introduced in version 4.0. While most of the library is @@ -79,6 +80,42 @@ runtime behavior, but may surface new or different errors with type checkers. Also, make sure to :ref:`let us know ` which essential aliases are missing from the public interface! +Known typing issues +^^^^^^^^^^^^^^^^^^^ + +Falcon's emphasis on flexibility and performance has presented certain +challenges when it comes to adding type annotations to the existing code base. +One currently unresolved case 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 `. + +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) + +(You can read more about this issue on GitHub: +`#2372 `__.) + + Breaking Changes ---------------- @@ -407,12 +444,6 @@ Misc Contributors to this Release ---------------------------- -.. note:: - If we missed you below, don’t worry! - - We will refresh the full list of contributors before the 4.0.0 final - release. - Many thanks to all of our talented and stylish contributors for this release! - `aarcex3 `__ From 4e8006b45a0d6d7de1259a80e37028b6900a49db Mon Sep 17 00:00:00 2001 From: Vytautas Liuolia Date: Tue, 15 Oct 2024 21:47:02 +0200 Subject: [PATCH 2/4] docs(changes): improve wording: "known typing limitations" --- docs/changes/4.0.0.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/changes/4.0.0.rst b/docs/changes/4.0.0.rst index c5bf5764d..c7ac58268 100644 --- a/docs/changes/4.0.0.rst +++ b/docs/changes/4.0.0.rst @@ -80,14 +80,14 @@ runtime behavior, but may surface new or different errors with type checkers. Also, make sure to :ref:`let us know ` which essential aliases are missing from the public interface! -Known typing issues -^^^^^^^^^^^^^^^^^^^ +Known typing limitations +^^^^^^^^^^^^^^^^^^^^^^^^ Falcon's emphasis on flexibility and performance has presented certain challenges when it comes to adding type annotations to the existing code base. -One currently unresolved case 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 +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 `. For instance, the following application might unexpectedly not pass type @@ -112,7 +112,7 @@ checking: app = App(request_type=MyRequest) app.add_error_handler(OSError, handle_os_error) -(You can read more about this issue on GitHub: +(Please also see the following GitHub issue: `#2372 `__.) From 512b3cbe9d996a13b9968bd2811bfdf6b322e824 Mon Sep 17 00:00:00 2001 From: Vytautas Liuolia Date: Tue, 15 Oct 2024 22:01:56 +0200 Subject: [PATCH 3/4] chore: prepare Falcon `4.0.0rc1` --- docs/changes/4.0.0.rst | 13 ++++++------- falcon/version.py | 2 +- 2 files changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/changes/4.0.0.rst b/docs/changes/4.0.0.rst index c7ac58268..204afa513 100644 --- a/docs/changes/4.0.0.rst +++ b/docs/changes/4.0.0.rst @@ -4,12 +4,11 @@ Changelog for Falcon 4.0.0 Summary ------- -Falcon ``4.0.0b4`` is hopefully the final beta release before moving forward to -a release candidate. +The first release candidate of Falcon 4.0 is here! -As Falcon 4.0 is now feature-complete, we would really be thankful if you -could test this beta release with your apps, and -:ref:`let us know if you run into any issues `! +As Falcon 4.0 is now nearing a stable release, in preparation for this +milestone, we would really be thankful if you could test this release candidate +with your apps, and :ref:`let us know if you run into any issues `! Please also check the list of **breaking changes** below. If you make use of type annotations in your Falcon app, please run your type @@ -17,9 +16,9 @@ checker of choice without any *typeshed* extensions for Falcon, and :ref:`report back to us ` how it went! As always, you can grab the new release -`from PyPI `__:: +`from PyPI `__:: - pip install falcon==4.0.0b4 + pip install falcon==4.0.0rc1 (Alternatively, continue reading these docs for more :ref:`installation options `.) diff --git a/falcon/version.py b/falcon/version.py index a10f53d7a..e123e18a1 100644 --- a/falcon/version.py +++ b/falcon/version.py @@ -14,5 +14,5 @@ """Falcon version.""" -__version__ = '4.0.0b4' +__version__ = '4.0.0rc1' """Current version of Falcon.""" From a61de22b2283711a6eb9c4294fa4c5642837617b Mon Sep 17 00:00:00 2001 From: Vytautas Liuolia Date: Tue, 15 Oct 2024 22:28:05 +0200 Subject: [PATCH 4/4] docs(changes): stress that typing limitations do not affect runtime --- docs/changes/4.0.0.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/changes/4.0.0.rst b/docs/changes/4.0.0.rst index 204afa513..98e1634df 100644 --- a/docs/changes/4.0.0.rst +++ b/docs/changes/4.0.0.rst @@ -114,6 +114,10 @@ checking: (Please also see the following GitHub issue: `#2372 `__.) +.. important:: + This is only a typing limitation that has no effect outside of type + checking -- the above ``app`` will run just fine! + Breaking Changes ----------------