docs: prepare Falcon 4.0.0a1 (#2342)

* docs: prepare Falcon `4.0.0a1` * chore: add a forgotten constant to `falcon.__all__` * chore: address review comments + other tweaks
falconry · Sep 28, 2024 · 217dc46 · 217dc46
1 parent ec13858
commit 217dc46
Show file tree

Hide file tree

Showing 17 changed files with 66 additions and 31 deletions.
diff --git 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 <https://github.com/falconry/falcon/milestone/34>`__
-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 <chat>`!
+
+Although we are still in the process of polishing the last items from the
+`version 4.0 milestone <https://github.com/falconry/falcon/milestone/34>`__,
+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 <https://github.com/falconry/falcon/issues/2072>`__)
-- CPython 3.12 is now fully supported. (`#2196 <https://github.com/falconry/falcon/issues/2196>`__)
-- CPython 3.13 is now fully supported. (`#2258 <https://github.com/falconry/falcon/issues/2258>`__)
-- End-of-life Python 3.5, 3.6 & 3.7 are no longer supported. (`#2074 <https://github.com/falconry/falcon/pull/2074>`__, `#2273 <https://github.com/falconry/falcon/pull/2273>`__)
+- CPython 3.11 is now fully supported.
+  (`#2072 <https://github.com/falconry/falcon/issues/2072>`__)
+- CPython 3.12 is now fully supported.
+  (`#2196 <https://github.com/falconry/falcon/issues/2196>`__)
+- CPython 3.13 is now fully supported.
+  (`#2258 <https://github.com/falconry/falcon/issues/2258>`__)
+- End-of-life Python 3.5, 3.6 & 3.7 are no longer supported.
+  (`#2074 <https://github.com/falconry/falcon/pull/2074>`__,
+  `#2273 <https://github.com/falconry/falcon/pull/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 <chat>` 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 <https://github.com/aarcex3>`__

diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -14,5 +14,5 @@
 
 """Falcon version."""
 
-__version__ = '4.0.0.dev2'
+__version__ = '4.0.0a1'
 """Current version of Falcon."""