chore: tweak documentation & CI (2026-01) (#2592)

* chore: tweak misc stuff (2026-01)

* chore(asgi): skip SSE tests on 3.15.0+ (started failing on `a4`)

* chore(AUTHORS): update 4.3 contrib so far

* docs(req/resp): misc spelling/grammar/styling stuff found by LLM

* chore: refine skip messages/conditions for 3.15.0 alpha

* docs: duplicate docstrings for some ASGI header props

Author: vytas7

AUTHORS

@@ -220,7 +220,8 @@ listed below by date of first contribution:
 * Swapnaneel Patra (thisisrick25)
 * 0x1618
 * 0xMattB
-* bricklayer (bricklayer25)
+* bricklayer (rushevich)
+* granuels
 
 (et al.)
 

docs/changes/4.3.0.rst

@@ -24,7 +24,8 @@ Many thanks to all of our talented and stylish contributors for this release!
 
 - `0x1618 <https://github.com/0x1618>`__
 - `0xMattB <https://github.com/0xMattB>`__
-- `bricklayer25 <https://github.com/bricklayer25>`__
+- `granuels <https://github.com/granuels>`__
+- `rushevich <https://github.com/rushevich>`__
 - `thisisrick25 <https://github.com/thisisrick25>`__
 - `TudorGR <https://github.com/TudorGR>`__
 - `vytas7 <https://github.com/vytas7>`__

falcon/asgi/request.py

@@ -255,12 +255,20 @@ def __init__(
     # trouble.
     # ------------------------------------------------------------------------
 
+    # NOTE(vytas): Duplicating docstrings from the WSGI flavor here, otherwise
+    #   Sphinx doesn't seem to pick them up.
     auth: str | None = asgi_helpers._header_property('Authorization')
+    """Value of the Authorization header, or ``None`` if the header is missing."""
     expect: str | None = asgi_helpers._header_property('Expect')
+    """Value of the Expect header, or ``None`` if the header is missing."""
     if_range: str | None = asgi_helpers._header_property('If-Range')
+    """Value of the If-Range header, or ``None`` if the header is missing."""
+    last_event_id: str | None = asgi_helpers._header_property('Last-Event-ID')
+    """Value of the Last-Event-ID header, or ``None`` if the header is missing."""
     referer: str | None = asgi_helpers._header_property('Referer')
+    """Value of the Referer header, or ``None`` if the header is missing."""
     user_agent: str | None = asgi_helpers._header_property('User-Agent')
-    last_event_id: str | None = asgi_helpers._header_property('Last-Event-ID')
+    """Value of the User-Agent header, or ``None`` if the header is missing."""
 
     @property
     def accept(self) -> str:
@@ -874,9 +882,9 @@ def get_param(
 
     @property
     def env(self) -> NoReturn:  # type:ignore[override]
-        """The env property is not available in ASGI. Use :attr:`~.store` instead."""
+        """The env property is not available in ASGI. Use :attr:`~.scope` instead."""
         raise AttributeError(
-            'The env property is not available in ASGI. Use :attr:`~.store` instead'
+            'The env property is not available in ASGI. Use req.scope instead.'
         )
 
     def log_error(self, message: str) -> NoReturn:

falcon/request.py

@@ -345,18 +345,18 @@ def __repr__(self) -> str:
     # Properties
     # ------------------------------------------------------------------------
 
-    user_agent: str | None = helpers._header_property('HTTP_USER_AGENT')
-    """Value of the User-Agent header, or ``None`` if the header is missing."""
     auth: str | None = helpers._header_property('HTTP_AUTHORIZATION')
     """Value of the Authorization header, or ``None`` if the header is missing."""
     expect: str | None = helpers._header_property('HTTP_EXPECT')
     """Value of the Expect header, or ``None`` if the header is missing."""
     if_range: str | None = helpers._header_property('HTTP_IF_RANGE')
     """Value of the If-Range header, or ``None`` if the header is missing."""
-    referer: str | None = helpers._header_property('HTTP_REFERER')
-    """Value of the Referer header, or ``None`` if the header is missing."""
     last_event_id: str | None = helpers._header_property('HTTP_LAST_EVENT_ID')
     """Value of the Last-Event-ID header, or ``None`` if the header is missing."""
+    referer: str | None = helpers._header_property('HTTP_REFERER')
+    """Value of the Referer header, or ``None`` if the header is missing."""
+    user_agent: str | None = helpers._header_property('HTTP_USER_AGENT')
+    """Value of the User-Agent header, or ``None`` if the header is missing."""
 
     @property
     def forwarded(self) -> list[Forwarded] | None:
@@ -635,7 +635,7 @@ def root_path(self) -> str:
         of the server.
 
         (In WSGI it corresponds to the "SCRIPT_NAME" environ variable defined
-        by PEP-3333; in ASGI it Corresponds to the "root_path"ASGI HTTP
+        by PEP-3333; in ASGI it Corresponds to the "root_path" ASGI HTTP
         scope field.)
         """  # noqa: D205
         # PERF(kgriffs): try..except is faster than get() assuming that
@@ -810,7 +810,7 @@ def forwarded_host(self) -> str:
         by the first proxy in front of the application server.
 
         The following request headers are checked, in order of
-        preference, to determine the forwarded scheme:
+        preference, to determine the forwarded host:
 
             - ``Forwarded``
             - ``X-Forwarded-Host``
@@ -1671,8 +1671,7 @@ def get_param_as_float(
         Keyword Args:
             required (bool): Set to ``True`` to raise
                 ``HTTPBadRequest`` instead of returning ``None`` when the
-                parameter is not found or is not an float (default
-                ``False``).
+                parameter is not found or is not a float (default ``False``).
             min_value (float): Set to the minimum value allowed for this
                 param. If the param is found and it is less than min_value, an
                 ``HTTPError`` is raised.

falcon/response.py

@@ -440,9 +440,9 @@ def set_cookie(  # noqa: C901
                 mitigate some forms of cross-site scripting. (default: ``True``)
 
                 Note:
-                    HttpOnly cookies are not visible to javascript scripts
+                    HttpOnly cookies are not visible to JavaScript scripts
                     in the browser. They are automatically sent to the server
-                    on javascript ``XMLHttpRequest`` or ``Fetch`` requests.
+                    on JavaScript ``XMLHttpRequest`` or ``Fetch`` requests.
 
                 (See also: RFC 6265, Section 4.1.2.6)
 
@@ -485,9 +485,9 @@ def set_cookie(  # noqa: C901
         """
 
         if not _is_ascii_encodable(name):
-            raise KeyError('name is not ascii encodable')
+            raise KeyError('name is not ASCII encodable')
         if not _is_ascii_encodable(value):
-            raise ValueError('value is not ascii encodable')
+            raise ValueError('value is not ASCII encodable')
 
         value = str(value)
 
@@ -570,7 +570,7 @@ def unset_cookie(
         agent to immediately expire its own copy of the cookie.
 
         Note:
-            Modern browsers place restriction on cookies without the
+            Modern browsers place restrictions on cookies without the
             "same-site" cookie attribute set. To that end this attribute
             is set to ``'Lax'`` by this method.
 
@@ -924,11 +924,11 @@ def append_link(
                 A list of tags may be given in order to indicate to the
                 client that the target resource is available in multiple
                 languages.
-            type_hint(str): Provides a hint as to the media type of the
+            type_hint (str): Provides a hint as to the media type of the
                 result of dereferencing the link (default ``None``). As noted
                 in RFC 5988, this is only a hint and does not override the
                 Content-Type header returned when the link is followed.
-            crossorigin(str):  Determines how cross origin requests are handled.
+            crossorigin (str):  Determines how cross origin requests are handled.
                 Can take values 'anonymous' or 'use-credentials' or None.
                 (See:
                 https://www.w3.org/TR/html50/infrastructure.html#cors-settings-attribute)

tests/asgi/test_sse.py

@@ -1,5 +1,6 @@
 import asyncio
 import json
+import sys
 
 import pytest
 
@@ -66,6 +67,12 @@ async def emitter():
     assert result.text == ': ping\n\n'
 
 
+# TODO(vytas): Remove later during the CPython 3.15 dev cycle.
+#   See also: https://github.com/python/cpython/issues/143939.
+@pytest.mark.skipif(
+    sys.version_info[:4] == (3, 15, 0, 'alpha'),
+    reason='Raises "cannot reuse already awaited coroutine", CPython bug gh-143939',
+)
 def test_multiple_events():
     expected_result_text = (
         'data: ketchup\n'
@@ -151,6 +158,12 @@ async def _test():
     falcon.async_to_sync(_test)
 
 
+# TODO(vytas): Remove later during the CPython 3.15 dev cycle.
+#   See also: https://github.com/python/cpython/issues/143939.
+@pytest.mark.skipif(
+    sys.version_info[:4] == (3, 15, 0, 'alpha'),
+    reason='Raises "cannot reuse already awaited coroutine", CPython bug gh-143939',
+)
 def test_multiple_events_early_disconnect():
     class SomeResource:
         async def on_get(self, req, resp):