Merge branch 'master' into Issue-475/add-docs-query-strings

docs/_newsfragments/2124.newandimproved.rst

@@ -1 +1 @@
-Added kwarg samesite to :py:meth:`~falcon.Response.unset_cookie` to allow override of default ``Lax`` setting of `SameSite` on the unset cookie
+Added kwarg samesite to :meth:`~falcon.Response.unset_cookie` to allow override of default ``Lax`` setting of `SameSite` on the unset cookie

docs/_newsfragments/2213.newandimproved.rst

@@ -1,4 +1,4 @@
-Added kwarg ``partitioned`` to :py:meth:`~falcon.Response.set_cookie`
+Added kwarg ``partitioned`` to :meth:`~falcon.Response.set_cookie`
 to opt a cookie into partitioned storage, with a separate cookie jar per
 top-level site.
 See also

docs/_newsfragments/2301.misc.rst

@@ -0,0 +1 @@
+Deprecated the ``TimezoneGMT`` class. Use :attr:`datetime.timezone.utc` instead.

docs/api/cookies.rst

@@ -11,10 +11,10 @@ Getting Cookies
 ~~~~~~~~~~~~~~~
 
 Cookies can be read from a request either via the
-:py:meth:`~.falcon.Request.get_cookie_values` method or the
-:py:attr:`~.falcon.Request.cookies` attribute on the
-:py:class:`~.falcon.Request` object. Generally speaking, the
-:py:meth:`~.falcon.Request.get_cookie_values` method should be used unless you
+:meth:`~.falcon.Request.get_cookie_values` method or the
+:attr:`~.falcon.Request.cookies` attribute on the
+:class:`~.falcon.Request` object. Generally speaking, the
+:meth:`~.falcon.Request.get_cookie_values` method should be used unless you
 need a collection of all the cookies in the request.
 
 .. note::
@@ -68,10 +68,10 @@ Setting Cookies
 ~~~~~~~~~~~~~~~
 
 Setting cookies on a response may be done either via
-:py:meth:`~falcon.Response.set_cookie` or :py:meth:`~falcon.Response.append_header`.
+:meth:`~falcon.Response.set_cookie` or :meth:`~falcon.Response.append_header`.
 
 One of these methods should be used instead of
-:py:meth:`~falcon.Response.set_header`. With :py:meth:`~falcon.Response.set_header` you
+:meth:`~falcon.Response.set_header`. With :meth:`~falcon.Response.set_header` you
 cannot set multiple headers with the same name (which is how multiple cookies
 are sent to the client).
 
@@ -102,7 +102,7 @@ You can of course also set the domain, path and lifetime of the cookie.
 
 
 You can also instruct the client to remove a cookie with the
-:py:meth:`~falcon.Response.unset_cookie` method:
+:meth:`~falcon.Response.unset_cookie` method:
 
 .. code:: python
 
@@ -136,9 +136,9 @@ the request.
 
 When running your application in a development environment, you can
 disable this default behavior by setting
-:py:attr:`~falcon.ResponseOptions.secure_cookies_by_default` to ``False``
-via :py:attr:`falcon.App.resp_options` or
-:py:attr:`falcon.asgi.App.resp_options`. This lets you test your app
+:attr:`~falcon.ResponseOptions.secure_cookies_by_default` to ``False``
+via :attr:`falcon.App.resp_options` or
+:attr:`falcon.asgi.App.resp_options`. This lets you test your app
 locally without having to set up TLS. You can make this option configurable to
 easily switch between development and production environments.
 
@@ -148,11 +148,11 @@ The SameSite Attribute
 ~~~~~~~~~~~~~~~~~~~~~~
 
 The `SameSite` attribute may be set on a cookie using the
-:py:meth:`~falcon.Response.set_cookie` method. It is generally a good idea to
+:meth:`~falcon.Response.set_cookie` method. It is generally a good idea to
 at least set this attribute to ``'Lax'`` in order to mitigate
 `CSRF attacks <https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)>`_.
 
-Currently, :py:meth:`~falcon.Response.set_cookie` does not set `SameSite` by
+Currently, :meth:`~falcon.Response.set_cookie` does not set `SameSite` by
 default, although this may change in a future release.
 
 .. note::
@@ -165,7 +165,7 @@ default, although this may change in a future release.
 .. _RFC 6265, Section 4.1.2.5:
     https://tools.ietf.org/html/rfc6265#section-4.1.2.5
 
-When unsetting a cookie, :py:meth:`~falcon.Response.unset_cookie`,
+When unsetting a cookie, :meth:`~falcon.Response.unset_cookie`,
 the default `SameSite` setting of the unset cookie is ``'Lax'``, but can be changed
 by setting the 'samesite' kwarg.
 
@@ -182,7 +182,7 @@ enforced by Falcon, the framework does set ``Secure`` by default, unless
 specified otherwise
 (see also :attr:`~falcon.ResponseOptions.secure_cookies_by_default`).
 
-Currently, :py:meth:`~falcon.Response.set_cookie` does not set ``Partitioned``
+Currently, :meth:`~falcon.Response.set_cookie` does not set ``Partitioned``
 automatically depending on other attributes (like ``SameSite``),
 although this may change in a future release.
 

docs/api/middleware.rst

@@ -254,7 +254,7 @@ the following example:
 .. Tip::
     The *process_resource* method is only called when the request matches
     a route to a resource. To take action when a route is not found, a
-    :py:meth:`sink <falcon.App.add_sink>` may be used instead.
+    :meth:`sink <falcon.App.add_sink>` may be used instead.
 
 .. Tip::
     In order to pass data from a middleware function to a resource function

docs/api/redirects.rst

@@ -7,7 +7,7 @@ Falcon defines a set of exceptions that can be raised within a
 middleware method, hook, or responder in order to trigger
 a 3xx (Redirection) response to the client. Raising one of these
 classes short-circuits request processing in a manner similar to
-raising an instance or subclass of :py:class:`~.HTTPError`.
+raising an instance or subclass of :class:`~.HTTPError`.
 
 .. autoexception:: falcon.HTTPMovedPermanently
 

docs/api/routing.rst

@@ -334,14 +334,14 @@ Custom Routers
 --------------
 
 A custom routing engine may be specified when instantiating
-:py:meth:`falcon.App` or :py:meth:`falcon.asgi.App`. For example:
+:meth:`falcon.App` or :meth:`falcon.asgi.App`. For example:
 
 .. code:: python
 
     router = MyRouter()
     app = App(router=router)
 
-Custom routers may derive from the default :py:class:`~.CompiledRouter`
+Custom routers may derive from the default :class:`~.CompiledRouter`
 engine, or implement a completely different routing strategy (such as
 object-based routing).
 

docs/api/websocket.rst

@@ -226,7 +226,7 @@ one or both payload types, as in the following example.
     cbor_handler = ProtocolBuffersHandler()
     app.ws_options.media_handlers[falcon.WebSocketPayloadType.BINARY] = cbor_handler
 
-The ``falcon`` module defines the following :py:class:`~enum.Enum` values for
+The ``falcon`` module defines the following :class:`~enum.Enum` values for
 specifying the WebSocket payload type:
 
 .. code:: python

docs/changes/0.3.0.rst

@@ -3,11 +3,11 @@ Changelog for Falcon 0.3.0
 
 Breaking Changes
 ----------------
-- Date headers are now returned as :py:class:`datetime.datetime` objects
+- Date headers are now returned as :class:`datetime.datetime` objects
   instead of strings.
 - The expected signature for the ``add_route()`` method of custom routers no
   longer includes a `method_map` parameter. Custom routers should, instead,
-  call the :py:meth:`falcon.routing.util.map_http_methods` function directly
+  call the :meth:`falcon.routing.util.map_http_methods` function directly
   from their ``add_route()`` method if they require this mapping.
 
 New & Improved
@@ -16,22 +16,22 @@ New & Improved
 - This release includes a new router architecture for improved performance
   and flexibility.
 - A custom router can now be specified when instantiating the
-  :py:class:`API` class.
+  :class:`API` class.
 - URI templates can now include multiple parameterized fields within a
   single path segment.
 - Falcon now supports reading and writing cookies.
 - Falcon now supports Jython 2.7.
 - A method for getting a query param as a date was added to the
-  :py:class:`Request` class.
-- Date headers are now returned as :py:class:`datetime.datetime` objects.
+  :class:`Request` class.
+- Date headers are now returned as :class:`datetime.datetime` objects.
 - A default value can now be specified when calling
-  :py:meth:`Request.get_param`. This provides an alternative to using the
+  :meth:`Request.get_param`. This provides an alternative to using the
   pattern::
 
     value = req.get_param(name) or default_value
 
 - Friendly constants for status codes were added (e.g.,
-  :py:attr:`falcon.HTTP_NO_CONTENT` vs. :py:attr:`falcon.HTTP_204`.)
+  :attr:`falcon.HTTP_NO_CONTENT` vs. :attr:`falcon.HTTP_204`.)
 - Several minor performance optimizations were made to the code base.
 
 Fixed
@@ -40,6 +40,6 @@ Fixed
 - The query string parser was modified to improve handling of percent-encoded
   data.
 - Several errors in the documentation were corrected.
-- The :py:mod:`six` package was pinned to 1.4.0 or better.
-  :py:attr:`six.PY2` is required by Falcon, but that wasn't added to
-  :py:mod:`six` until version 1.4.0.
+- The :mod:`six` package was pinned to 1.4.0 or better.
+  :attr:`six.PY2` is required by Falcon, but that wasn't added to
+  :mod:`six` until version 1.4.0.

docs/changes/2.0.0.rst

@@ -219,7 +219,7 @@ New & Improved
 - Numerous changes were made to the docs to improve clarity and to provide
   better recommendations on how to best use various parts of the framework.
 - Added a new :attr:`~falcon.Response.headers` property to the :class:`~falcon.Response` class.
-- Removed the :py:mod:`six` and :py:mod:`python-mimeparse` dependencies.
+- Removed the :mod:`six` and :mod:`python-mimeparse` dependencies.
 - Added a new :attr:`~falcon.Response.complete` property to the :class:`~falcon.Response`
   class. This can be used to short-circuit request processing when the response
   has been pre-constructed.

docs/conf.py

@@ -10,12 +10,12 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-from datetime import datetime
 from collections import OrderedDict
 import configparser
+from datetime import datetime
 import multiprocessing
-import sys
 import os
+import sys
 
 sys.path.insert(0, os.path.abspath('..'))
 

docs/ext/rfc.py

@@ -22,7 +22,6 @@
 
 import re
 
-
 RFC_PATTERN = re.compile(r'RFC (\d{4}), Section ([\d\.]+)')
 
 

falcon/app.py

@@ -79,8 +79,8 @@ class App:
 
     Keyword Arguments:
         media_type (str): Default media type to use when initializing
-            :py:class:`~.RequestOptions` and
-            :py:class:`~.ResponseOptions`. The ``falcon``
+            :class:`~.RequestOptions` and
+            :class:`~.ResponseOptions`. The ``falcon``
             module provides a number of constants for common media types,
             such as ``falcon.MEDIA_MSGPACK``, ``falcon.MEDIA_YAML``,
             ``falcon.MEDIA_XML``, etc.
@@ -169,7 +169,7 @@ def process_response(self, req, resp, resource, req_succeeded)
 
         cors_enable (bool): Set this flag to ``True`` to enable a simple
             CORS policy for all responses, including support for preflighted
-            requests. An instance of :py:class:`~.CORSMiddleware` can instead be
+            requests. An instance of :class:`~.CORSMiddleware` can instead be
             passed to the middleware argument to customize its behaviour.
             (default ``False``).
             (See also: :ref:`CORS <cors>`)
@@ -180,9 +180,9 @@ def process_response(self, req, resp, resource, req_succeeded)
 
     Attributes:
         req_options: A set of behavioral options related to incoming
-            requests. (See also: :py:class:`~.RequestOptions`)
+            requests. (See also: :class:`~.RequestOptions`)
         resp_options: A set of behavioral options related to outgoing
-            responses. (See also: :py:class:`~.ResponseOptions`)
+            responses. (See also: :class:`~.ResponseOptions`)
         router_options: Configuration options for the router. If a
             custom router is in use, and it does not expose any
             configurable options, referencing this attribute will raise

falcon/asgi/_request_helpers.py

@@ -11,9 +11,15 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+from __future__ import annotations
 
+from typing import Any, Optional, TYPE_CHECKING
 
-def header_property(header_name):
+if TYPE_CHECKING:
+    from falcon.asgi import Request
+
+
+def header_property(header_name: str) -> Any:
     """Create a read-only header property.
 
     Args:
@@ -25,14 +31,14 @@ def header_property(header_name):
 
     """
 
-    header_name = header_name.lower().encode()
+    header_bytes = header_name.lower().encode()
 
-    def fget(self):
+    def fget(self: Request) -> Optional[str]:
         try:
             # NOTE(vytas): Supporting ISO-8859-1 for historical reasons as per
             #   RFC 7230, Section 3.2.4; and to strive for maximum
             #   compatibility with WSGI.
-            return self._asgi_headers[header_name].decode('latin1') or None
+            return self._asgi_headers[header_bytes].decode('latin1') or None
         except KeyError:
             return None
 

falcon/asgi/app.py

@@ -77,8 +77,8 @@ class App(falcon.app.App):
 
     Keyword Arguments:
         media_type (str): Default media type to use when initializing
-            :py:class:`~.RequestOptions` and
-            :py:class:`~.ResponseOptions`. The ``falcon``
+            :class:`~.RequestOptions` and
+            :class:`~.ResponseOptions`. The ``falcon``
             module provides a number of constants for common media types,
             such as ``falcon.MEDIA_MSGPACK``, ``falcon.MEDIA_YAML``,
             ``falcon.MEDIA_XML``, etc.
@@ -231,7 +231,7 @@ async def process_response(self, req, resp, resource, req_succeeded)
 
         cors_enable (bool): Set this flag to ``True`` to enable a simple
             CORS policy for all responses, including support for preflighted
-            requests. An instance of :py:class:`..CORSMiddleware` can instead be
+            requests. An instance of :class:`..CORSMiddleware` can instead be
             passed to the middleware argument to customize its behaviour.
             (default ``False``).
             (See also: :ref:`CORS <cors>`)
@@ -242,11 +242,11 @@ async def process_response(self, req, resp, resource, req_succeeded)
 
     Attributes:
         req_options: A set of behavioral options related to incoming
-            requests. (See also: :py:class:`~.RequestOptions`)
+            requests. (See also: :class:`~.RequestOptions`)
         resp_options: A set of behavioral options related to outgoing
-            responses. (See also: :py:class:`~.ResponseOptions`)
+            responses. (See also: :class:`~.ResponseOptions`)
         ws_options: A set of behavioral options related to WebSocket
-            connections. (See also: :py:class:`~.WebSocketOptions`)
+            connections. (See also: :class:`~.WebSocketOptions`)
         router_options: Configuration options for the router. If a
             custom router is in use, and it does not expose any
             configurable options, referencing this attribute will raise
@@ -567,7 +567,7 @@ async def watch_disconnect():
             if resp._registered_callbacks:
                 self._schedule_callbacks(resp)
 
-            handler, _, _ = self.resp_options.media_handlers._resolve(
+            sse_handler, _, _ = self.resp_options.media_handlers._resolve(
                 MEDIA_JSON, MEDIA_JSON, raise_not_found=False
             )
 
@@ -583,7 +583,7 @@ async def watch_disconnect():
                 await send(
                     {
                         'type': EventType.HTTP_RESPONSE_BODY,
-                        'body': event.serialize(handler),
+                        'body': event.serialize(sse_handler),
                         'more_body': True,
                     }
                 )