From 61c1047db2ef02556da9c28cc42c813b52db3aa9 Mon Sep 17 00:00:00 2001 From: Vytautas Liuolia Date: Wed, 16 Oct 2024 06:42:24 +0200 Subject: [PATCH] docs(changes): prepare Falcon `4.0.0rc1` (#2374) * docs(changes): describe a known typing issue * docs(changes): improve wording: "known typing limitations" * chore: prepare Falcon `4.0.0rc1` * docs(changes): stress that typing limitations do not affect runtime --- docs/changes/4.0.0.rst | 62 ++++++++++++++++++++++++++++++++---------- falcon/version.py | 2 +- 2 files changed, 49 insertions(+), 15 deletions(-) diff --git a/docs/changes/4.0.0.rst b/docs/changes/4.0.0.rst index c3e9d426a..98e1634df 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 `.) @@ -50,7 +49,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 +79,46 @@ 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 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 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 +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 `__.) + +.. important:: + This is only a typing limitation that has no effect outside of type + checking -- the above ``app`` will run just fine! + + Breaking Changes ---------------- @@ -407,12 +447,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 `__ 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."""