docs: remove unnecessary py domain form Sphinx references (#2272)

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/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.

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/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

falcon/asgi/request.py

@@ -365,7 +365,7 @@ def scheme(self) -> str:
         Note:
             If the request was proxied, the scheme may not
             match what was originally requested by the client.
-            :py:attr:`forwarded_scheme` can be used, instead,
+            :attr:`forwarded_scheme` can be used, instead,
             to handle such cases.
         """
         # PERF(kgriffs): Use try...except because we normally expect the
@@ -526,7 +526,7 @@ def remote_addr(self) -> str:
         the ASGI server, or ``'127.0.0.1'`` if unknown.
 
         This property's value is equivalent to the last element of the
-        :py:attr:`~.access_route` property.
+        :attr:`~.access_route` property.
         """  # noqa: D205
         route = self.access_route
         return route[-1]

falcon/asgi/response.py

@@ -99,15 +99,15 @@ async def producer():
 
                 resp.stream = await aiofiles.open('resp_data.bin', 'rb')
 
-            If the object assigned to :py:attr:`~.stream` holds any resources
+            If the object assigned to :attr:`~.stream` holds any resources
             (such as a file handle) that must be explicitly released, the
             object must implement a ``close()`` method. The ``close()`` method
             will be called after exhausting the iterable or file-like object.
 
             Note:
                 In order to be compatible with Python 3.7+ and PEP 479,
                 async iterators must return ``None`` instead of raising
-                :py:class:`StopIteration`. This requirement does not
+                :class:`StopIteration`. This requirement does not
                 apply to async generators (PEP 525).
 
             Note:
@@ -116,7 +116,7 @@ async def producer():
 
         sse (coroutine): A Server-Sent Event (SSE) emitter, implemented as
             an async iterator or generator that yields a series of
-            of :py:class:`falcon.asgi.SSEvent` instances. Each event will be
+            of :class:`falcon.asgi.SSEvent` instances. Each event will be
             serialized and sent to the client as HTML5 Server-Sent Events::
 
                 async def emitter():

falcon/asgi/ws.py

@@ -533,7 +533,7 @@ class WebSocketOptions:
     """Defines a set of configurable WebSocket options.
 
     An instance of this class is exposed via :attr:`falcon.asgi.App.ws_options`
-    for configuring certain :py:class:`~.WebSocket` behaviors.
+    for configuring certain :class:`~.WebSocket` behaviors.
     """
 
     error_close_code: int