diff --git a/docs/changes/4.0.0.rst b/docs/changes/4.0.0.rst index bd15d6a1e..bdb8b235a 100644 --- a/docs/changes/4.0.0.rst +++ b/docs/changes/4.0.0.rst @@ -4,18 +4,31 @@ Changelog for Falcon 4.0.0 Summary ------- -Falcon 4.0 is in development. The progress is tracked via the -`Version 4.0 milestone `__ -on GitHub. +The first alpha release of Falcon 4.0.0 is here! + +We would really appreciate if you could help with early testing on your code! +You can grab this release from PyPI (``pip install falcon==4.0.0a1``), +and :ref:`let us know how it went `! + +Although we are still in the process of polishing the last items from the +`version 4.0 milestone `__, +we do not expect (m)any radical changes from now on until Falcon 4.0.0 final. +The full changelog of new features, breaking changes and fixes will be rendered +as part of the first beta release. Changes to Supported Platforms ------------------------------ -- CPython 3.11 is now fully supported. (`#2072 `__) -- CPython 3.12 is now fully supported. (`#2196 `__) -- CPython 3.13 is now fully supported. (`#2258 `__) -- End-of-life Python 3.5, 3.6 & 3.7 are no longer supported. (`#2074 `__, `#2273 `__) +- CPython 3.11 is now fully supported. + (`#2072 `__) +- CPython 3.12 is now fully supported. + (`#2196 `__) +- CPython 3.13 is now fully supported. + (`#2258 `__) +- End-of-life Python 3.5, 3.6 & 3.7 are no longer supported. + (`#2074 `__, + `#2273 `__) - Soon end-of-life Python 3.8 is no longer actively supported, but the framework should still continue to install from source and function. - The Falcon 4.x series is guaranteed to support CPython 3.10 and @@ -32,17 +45,38 @@ now typed, further type annotations may be added throughout the 4.x release cycl 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 - All type aliases in falcon are considered private, and if used should be - imported inside ``if TYPE_CHECKING:`` blocks to avoid possible import errors - after an update. + 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 ` which essential aliases are + missing from the public interface! .. towncrier release notes start 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/docs/user/intro.rst b/docs/user/intro.rst index c6c22f228..ba35f6199 100644 --- a/docs/user/intro.rst +++ b/docs/user/intro.rst @@ -87,7 +87,7 @@ Now, if you do make changes to Falcon itself, please consider contributing your Falcon License -------------- -Copyright 2012-2017 by Rackspace Hosting, Inc. and other contributors, +Copyright 2012-2024 by Rackspace Hosting, Inc. and other contributors, as noted in the individual source code files. Licensed under the Apache License, Version 2.0 (the "License"); diff --git a/e2e-tests/conftest.py b/e2e-tests/conftest.py index 342d177c7..ecc842602 100644 --- a/e2e-tests/conftest.py +++ b/e2e-tests/conftest.py @@ -1,4 +1,4 @@ -# Copyright 2020-2021 by Vytautas Liuolia. +# Copyright 2020-2024 by Vytautas Liuolia. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. diff --git a/e2e-tests/test_e2e.py b/e2e-tests/test_e2e.py index 9bc02df88..8d33f888f 100644 --- a/e2e-tests/test_e2e.py +++ b/e2e-tests/test_e2e.py @@ -1,4 +1,4 @@ -# Copyright 2020-2021 by Vytautas Liuolia. +# Copyright 2020-2024 by Vytautas Liuolia. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. diff --git a/falcon/__init__.py b/falcon/__init__.py index e3b3012b5..5c383b774 100644 --- a/falcon/__init__.py +++ b/falcon/__init__.py @@ -265,6 +265,7 @@ 'HTTP_BAD_GATEWAY', 'HTTP_BAD_REQUEST', 'HTTP_CONFLICT', + 'HTTP_CONTENT_TOO_LARGE', 'HTTP_CONTINUE', 'HTTP_CREATED', 'HTTP_EARLY_HINTS', diff --git a/falcon/_typing.py b/falcon/_typing.py index 223533021..d82a5bac5 100644 --- a/falcon/_typing.py +++ b/falcon/_typing.py @@ -1,4 +1,4 @@ -# Copyright 2021-2023 by Vytautas Liuolia. +# Copyright 2021-2024 by Vytautas Liuolia. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. diff --git a/falcon/asgi/_asgi_helpers.py b/falcon/asgi/_asgi_helpers.py index 9bbd12e88..cf9e18bbc 100644 --- a/falcon/asgi/_asgi_helpers.py +++ b/falcon/asgi/_asgi_helpers.py @@ -1,4 +1,4 @@ -# Copyright 2020 by Vytautas Liuolia. +# Copyright 2020-2024 by Vytautas Liuolia. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. diff --git a/falcon/asgi/multipart.py b/falcon/asgi/multipart.py index eee479f23..85d98e30a 100644 --- a/falcon/asgi/multipart.py +++ b/falcon/asgi/multipart.py @@ -1,4 +1,4 @@ -# Copyright 2019-2023 by Vytautas Liuolia. +# Copyright 2019-2024 by Vytautas Liuolia. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. diff --git a/falcon/asgi/reader.py b/falcon/asgi/reader.py index c2adda791..1d748dd89 100644 --- a/falcon/asgi/reader.py +++ b/falcon/asgi/reader.py @@ -1,4 +1,4 @@ -# Copyright 2019-2020 by Vytautas Liuolia. +# Copyright 2019-2024 by Vytautas Liuolia. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. diff --git a/falcon/asgi/response.py b/falcon/asgi/response.py index a2f5911e3..42cc05830 100644 --- a/falcon/asgi/response.py +++ b/falcon/asgi/response.py @@ -33,7 +33,7 @@ from falcon._typing import _UNSET from falcon._typing import ResponseCallbacks from falcon.typing import AsyncReadableIO -from falcon.typing import SseEmitter +from falcon.typing import SSEEmitter from falcon.util.misc import _encode_items_to_latin1 from falcon.util.misc import is_python_func @@ -53,7 +53,7 @@ class Response(response.Response): # PERF(kgriffs): These will be shadowed when set on an instance; let's # us avoid having to implement __init__ and incur the overhead of # an additional function call. - _sse: Optional[SseEmitter] = None + _sse: Optional[SSEEmitter] = None _registered_callbacks: Optional[List[ResponseCallbacks]] = None stream: Union[AsyncReadableIO, AsyncIterator[bytes], None] # type: ignore[assignment] @@ -95,7 +95,7 @@ async def producer(): """ @property - def sse(self) -> Optional[SseEmitter]: + def sse(self) -> Optional[SSEEmitter]: """A Server-Sent Event (SSE) emitter, implemented as an async iterator or generator that yields a series of of :class:`falcon.asgi.SSEvent` instances. Each event will be @@ -143,7 +143,7 @@ async def emitter(): return self._sse @sse.setter - def sse(self, value: Optional[SseEmitter]) -> None: + def sse(self, value: Optional[SSEEmitter]) -> None: self._sse = value def set_stream( diff --git a/falcon/cyutil/misc.pyx b/falcon/cyutil/misc.pyx index b7962aa62..61b688cda 100644 --- a/falcon/cyutil/misc.pyx +++ b/falcon/cyutil/misc.pyx @@ -1,4 +1,4 @@ -# Copyright 2020-2021 by Vytautas Liuolia. +# Copyright 2020-2024 by Vytautas Liuolia. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. diff --git a/falcon/cyutil/reader.pyx b/falcon/cyutil/reader.pyx index 039e72a8f..449983a97 100644 --- a/falcon/cyutil/reader.pyx +++ b/falcon/cyutil/reader.pyx @@ -1,4 +1,4 @@ -# Copyright 2019-2020 by Vytautas Liuolia. +# Copyright 2019-2024 by Vytautas Liuolia. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. diff --git a/falcon/cyutil/uri.pyx b/falcon/cyutil/uri.pyx index 477e7cc7e..bb42cfdff 100644 --- a/falcon/cyutil/uri.pyx +++ b/falcon/cyutil/uri.pyx @@ -1,4 +1,4 @@ -# Copyright 2019-2020 by Vytautas Liuolia. +# Copyright 2019-2024 by Vytautas Liuolia. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. diff --git a/falcon/media/multipart.py b/falcon/media/multipart.py index 3f4eca88f..4cf1b24e4 100644 --- a/falcon/media/multipart.py +++ b/falcon/media/multipart.py @@ -1,4 +1,4 @@ -# Copyright 2019-2023 by Vytautas Liuolia. +# Copyright 2019-2024 by Vytautas Liuolia. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. diff --git a/falcon/typing.py b/falcon/typing.py index 5ff4f47f1..1eadeee9f 100644 --- a/falcon/typing.py +++ b/falcon/typing.py @@ -33,13 +33,13 @@ def read(self, n: Optional[int] = ..., /) -> bytes: ... # ASGI class AsyncReadableIO(Protocol): - """Async file like protocol that defines only a read method and is iterable.""" + """Async file-like protocol that defines only a read method, and is iterable.""" async def read(self, n: Optional[int] = ..., /) -> bytes: ... def __aiter__(self) -> AsyncIterator[bytes]: ... -SseEmitter = AsyncIterator[Optional['SSEvent']] -"""Async iterator or generator that generates Server-Sent Events -returning :class:`falcon.asgi.SSEvent` insatnces. +SSEEmitter = AsyncIterator[Optional['SSEvent']] +"""Async generator or iterator over Server-Sent Events +(instances of :class:`falcon.asgi.SSEvent`). """ diff --git a/falcon/util/reader.py b/falcon/util/reader.py index 645b35520..8f5431d5c 100644 --- a/falcon/util/reader.py +++ b/falcon/util/reader.py @@ -1,4 +1,4 @@ -# Copyright 2019-2020 by Vytautas Liuolia. +# Copyright 2019-2024 by Vytautas Liuolia. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. diff --git a/falcon/version.py b/falcon/version.py index 35f56858a..9f4e66609 100644 --- a/falcon/version.py +++ b/falcon/version.py @@ -14,5 +14,5 @@ """Falcon version.""" -__version__ = '4.0.0.dev2' +__version__ = '4.0.0a1' """Current version of Falcon."""