From 65aa7f64d9900380d2246a34d5747782d85d5c8c Mon Sep 17 00:00:00 2001 From: Federico Caselli Date: Mon, 26 Aug 2024 13:54:23 +0200 Subject: [PATCH] docs: remove unnecessary py domain form Sphinx references (#2272) --- docs/_newsfragments/2124.newandimproved.rst | 2 +- docs/_newsfragments/2213.newandimproved.rst | 2 +- docs/api/cookies.rst | 28 +++++----- docs/api/middleware.rst | 2 +- docs/api/redirects.rst | 2 +- docs/api/routing.rst | 4 +- docs/api/websocket.rst | 2 +- docs/changes/0.3.0.rst | 20 +++---- docs/changes/2.0.0.rst | 2 +- falcon/app.py | 10 ++-- falcon/asgi/app.py | 12 ++--- falcon/asgi/request.py | 4 +- falcon/asgi/response.py | 6 +-- falcon/asgi/ws.py | 2 +- falcon/media/base.py | 42 +++++++-------- falcon/media/json.py | 4 +- falcon/media/msgpack.py | 2 +- falcon/request.py | 12 ++--- falcon/response.py | 6 +-- falcon/routing/compiled.py | 6 +-- falcon/routing/util.py | 2 +- falcon/testing/client.py | 60 ++++++++++----------- falcon/testing/helpers.py | 18 +++---- falcon/testing/resource.py | 8 +-- falcon/testing/test_case.py | 10 ++-- falcon/util/time.py | 2 +- 26 files changed, 135 insertions(+), 135 deletions(-) diff --git a/docs/_newsfragments/2124.newandimproved.rst b/docs/_newsfragments/2124.newandimproved.rst index dae847273..edcaa0bdd 100644 --- a/docs/_newsfragments/2124.newandimproved.rst +++ b/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 \ No newline at end of file +Added kwarg samesite to :meth:`~falcon.Response.unset_cookie` to allow override of default ``Lax`` setting of `SameSite` on the unset cookie \ No newline at end of file diff --git a/docs/_newsfragments/2213.newandimproved.rst b/docs/_newsfragments/2213.newandimproved.rst index 403c2ede5..981fc0ac6 100644 --- a/docs/_newsfragments/2213.newandimproved.rst +++ b/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 diff --git a/docs/api/cookies.rst b/docs/api/cookies.rst index 2afb9c70e..719e025e4 100644 --- a/docs/api/cookies.rst +++ b/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 `_. -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. diff --git a/docs/api/middleware.rst b/docs/api/middleware.rst index cfcbc0505..ea6db856f 100644 --- a/docs/api/middleware.rst +++ b/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 ` may be used instead. + :meth:`sink ` may be used instead. .. Tip:: In order to pass data from a middleware function to a resource function diff --git a/docs/api/redirects.rst b/docs/api/redirects.rst index 72ca9837b..3e177db93 100644 --- a/docs/api/redirects.rst +++ b/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 diff --git a/docs/api/routing.rst b/docs/api/routing.rst index b1b4ef36f..347b3516d 100644 --- a/docs/api/routing.rst +++ b/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). diff --git a/docs/api/websocket.rst b/docs/api/websocket.rst index 0f35addfb..66b457722 100644 --- a/docs/api/websocket.rst +++ b/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 diff --git a/docs/changes/0.3.0.rst b/docs/changes/0.3.0.rst index 2a53ecc97..6731a9910 100644 --- a/docs/changes/0.3.0.rst +++ b/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. diff --git a/docs/changes/2.0.0.rst b/docs/changes/2.0.0.rst index 985d75361..999577962 100644 --- a/docs/changes/2.0.0.rst +++ b/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. diff --git a/falcon/app.py b/falcon/app.py index 53cffe397..a71c6530d 100644 --- a/falcon/app.py +++ b/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 `) @@ -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 diff --git a/falcon/asgi/app.py b/falcon/asgi/app.py index d606d6690..472ded751 100644 --- a/falcon/asgi/app.py +++ b/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 `) @@ -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 diff --git a/falcon/asgi/request.py b/falcon/asgi/request.py index d91806d13..f4f4f1d73 100644 --- a/falcon/asgi/request.py +++ b/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] diff --git a/falcon/asgi/response.py b/falcon/asgi/response.py index 44e52d85a..b545b5201 100644 --- a/falcon/asgi/response.py +++ b/falcon/asgi/response.py @@ -99,7 +99,7 @@ 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. @@ -107,7 +107,7 @@ async def producer(): 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(): diff --git a/falcon/asgi/ws.py b/falcon/asgi/ws.py index a5f3a5a3a..0599a25f3 100644 --- a/falcon/asgi/ws.py +++ b/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 diff --git a/falcon/media/base.py b/falcon/media/base.py index 20bf45158..320b92bd0 100644 --- a/falcon/media/base.py +++ b/falcon/media/base.py @@ -30,11 +30,11 @@ def serialize(self, media: object, content_type: str) -> bytes: """Serialize the media object on a :any:`falcon.Response`. By default, this method raises an instance of - :py:class:`NotImplementedError`. Therefore, it must be + :class:`NotImplementedError`. Therefore, it must be overridden in order to work with WSGI apps. Child classes can ignore this method if they are only to be used with ASGI apps, as long as they override - :py:meth:`~.BaseHandler.serialize_async`. + :meth:`~.BaseHandler.serialize_async`. Note: @@ -61,19 +61,19 @@ def serialize(self, media: object, content_type: str) -> bytes: async def serialize_async(self, media: object, content_type: str) -> bytes: """Serialize the media object on a :any:`falcon.Response`. - This method is similar to :py:meth:`~.BaseHandler.serialize` + This method is similar to :meth:`~.BaseHandler.serialize` except that it is asynchronous. The default implementation simply calls - :py:meth:`~.BaseHandler.serialize`. If the media object may be + :meth:`~.BaseHandler.serialize`. If the media object may be awaitable, or is otherwise something that should be read asynchronously, subclasses must override the default implementation in order to handle that case. Note: - By default, the :py:meth:`~.BaseHandler.serialize` - method raises an instance of :py:class:`NotImplementedError`. + By default, the :meth:`~.BaseHandler.serialize` + method raises an instance of :class:`NotImplementedError`. Therefore, child classes must either override - :py:meth:`~.BaseHandler.serialize` or - :py:meth:`~.BaseHandler.serialize_async` in order to be + :meth:`~.BaseHandler.serialize` or + :meth:`~.BaseHandler.serialize_async` in order to be compatible with ASGI apps. Args: @@ -94,11 +94,11 @@ def deserialize( """Deserialize the :any:`falcon.Request` body. By default, this method raises an instance of - :py:class:`NotImplementedError`. Therefore, it must be + :class:`NotImplementedError`. Therefore, it must be overridden in order to work with WSGI apps. Child classes can ignore this method if they are only to be used with ASGI apps, as long as they override - :py:meth:`~.BaseHandler.deserialize_async`. + :meth:`~.BaseHandler.deserialize_async`. Note: @@ -131,18 +131,18 @@ async def deserialize_async( ) -> object: """Deserialize the :any:`falcon.Request` body. - This method is similar to :py:meth:`~.BaseHandler.deserialize` except + This method is similar to :meth:`~.BaseHandler.deserialize` except that it is asynchronous. The default implementation adapts the - synchronous :py:meth:`~.BaseHandler.deserialize` method - via :py:class:`io.BytesIO`. For improved performance, media handlers should + synchronous :meth:`~.BaseHandler.deserialize` method + via :class:`io.BytesIO`. For improved performance, media handlers should override this method. Note: - By default, the :py:meth:`~.BaseHandler.deserialize` - method raises an instance of :py:class:`NotImplementedError`. + By default, the :meth:`~.BaseHandler.deserialize` + method raises an instance of :class:`NotImplementedError`. Therefore, child classes must either override - :py:meth:`~.BaseHandler.deserialize` or - :py:meth:`~.BaseHandler.deserialize_async` in order to be + :meth:`~.BaseHandler.deserialize` or + :meth:`~.BaseHandler.deserialize_async` in order to be compatible with ASGI apps. Args: @@ -178,7 +178,7 @@ def serialize(self, media: object) -> str: """Serialize the media object to a Unicode string. By default, this method raises an instance of - :py:class:`NotImplementedError`. Therefore, it must be + :class:`NotImplementedError`. Therefore, it must be overridden if the child class wishes to support serialization to TEXT (0x01) message payloads. @@ -194,7 +194,7 @@ def deserialize(self, payload: str) -> object: """Deserialize TEXT payloads from a Unicode string. By default, this method raises an instance of - :py:class:`NotImplementedError`. Therefore, it must be + :class:`NotImplementedError`. Therefore, it must be overridden if the child class wishes to support deserialization from TEXT (0x01) message payloads. @@ -214,7 +214,7 @@ def serialize(self, media: object) -> Union[bytes, bytearray, memoryview]: """Serialize the media object to a byte string. By default, this method raises an instance of - :py:class:`NotImplementedError`. Therefore, it must be + :class:`NotImplementedError`. Therefore, it must be overridden if the child class wishes to support serialization to BINARY (0x02) message payloads. @@ -232,7 +232,7 @@ def deserialize(self, payload: bytes) -> object: """Deserialize BINARY payloads from a byte string. By default, this method raises an instance of - :py:class:`NotImplementedError`. Therefore, it must be + :class:`NotImplementedError`. Therefore, it must be overridden if the child class wishes to support deserialization from BINARY (0x02) message payloads. diff --git a/falcon/media/json.py b/falcon/media/json.py index 2f795abb6..f3f2cee1d 100644 --- a/falcon/media/json.py +++ b/falcon/media/json.py @@ -10,7 +10,7 @@ class JSONHandler(BaseHandler): """JSON media handler. - This handler uses Python's standard :py:mod:`json` library by default, but + This handler uses Python's standard :mod:`json` library by default, but can be easily configured to use any of a number of third-party JSON libraries, depending on your needs. For example, you can often realize a significant performance boost under CPython by using an @@ -202,7 +202,7 @@ async def _serialize_async_b(self, media, content_type) -> bytes: class JSONHandlerWS(TextBaseHandlerWS): """WebSocket media handler for de(serializing) JSON to/from TEXT payloads. - This handler uses Python's standard :py:mod:`json` library by default, but + This handler uses Python's standard :mod:`json` library by default, but can be easily configured to use any of a number of third-party JSON libraries, depending on your needs. For example, you can often realize a significant performance boost under CPython by using an diff --git a/falcon/media/msgpack.py b/falcon/media/msgpack.py index 71edb7897..0267e2511 100644 --- a/falcon/media/msgpack.py +++ b/falcon/media/msgpack.py @@ -8,7 +8,7 @@ class MessagePackHandler(BaseHandler): - """Handler built using the :py:mod:`msgpack` module. + """Handler built using the :mod:`msgpack` module. This handler uses ``msgpack.unpackb()`` and ``msgpack.Packer().pack()``. The MessagePack ``bin`` type is used to distinguish between Unicode strings diff --git a/falcon/request.py b/falcon/request.py index d9ac218b0..1641a295f 100644 --- a/falcon/request.py +++ b/falcon/request.py @@ -222,13 +222,13 @@ class Request: doc = json.load(req.stream) For a slight performance cost, you may instead wish to use - :py:attr:`bounded_stream`, which wraps the native WSGI + :attr:`bounded_stream`, which wraps the native WSGI input object to normalize its behavior. Note: If an HTML form is POSTed to the API using the *application/x-www-form-urlencoded* media type, and - the :py:attr:`~.RequestOptions.auto_parse_form_urlencoded` + the :attr:`~.RequestOptions.auto_parse_form_urlencoded` option is set, the framework will consume `stream` in order to parse the parameters and merge them into the query string parameters. In this @@ -647,7 +647,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. """ return self.env['wsgi.url_scheme'] @@ -937,7 +937,7 @@ def access_route(self) -> List[str]: - ``X-Real-IP`` If none of these headers are available, the value of - :py:attr:`~.remote_addr` is used instead. + :attr:`~.remote_addr` is used instead. Note: Per `RFC 7239`_, the access route may contain "unknown" @@ -995,7 +995,7 @@ def remote_addr(self) -> str: Note: If your application is behind one or more reverse - proxies, you can use :py:attr:`~.access_route` + proxies, you can use :attr:`~.access_route` to retrieve the real IP address of the client. """ try: @@ -1409,7 +1409,7 @@ def get_param( automatically parse the parameters from the request body and merge them into the query string parameters. To enable this functionality, set - :py:attr:`~.RequestOptions.auto_parse_form_urlencoded` to + :attr:`~.RequestOptions.auto_parse_form_urlencoded` to ``True`` via :any:`App.req_options`. Note, however, that the diff --git a/falcon/response.py b/falcon/response.py index 6c97904d1..9e50c68f2 100644 --- a/falcon/response.py +++ b/falcon/response.py @@ -416,7 +416,7 @@ def set_cookie( # noqa: C901 Note: The default value for this argument is normally ``True``, but can be modified by setting - :py:attr:`~.ResponseOptions.secure_cookies_by_default` + :attr:`~.ResponseOptions.secure_cookies_by_default` via :any:`App.resp_options`. Warning: @@ -734,7 +734,7 @@ def append_header(self, name, value): Note: While this method can be used to efficiently append raw Set-Cookie headers to the response, you may find - :py:meth:`~.set_cookie` to be more convenient. + :meth:`~.set_cookie` to be more convenient. Args: name (str): Header name (case-insensitive). The name may contain @@ -1225,7 +1225,7 @@ class ResponseOptions: An instance of this class is exposed via :attr:`falcon.App.resp_options` and :attr:`falcon.asgi.App.resp_options` for configuring certain - :py:class:`~.Response` behaviors. + :class:`~.Response` behaviors. """ secure_cookies_by_default: bool diff --git a/falcon/routing/compiled.py b/falcon/routing/compiled.py index 138e79a5d..961af5a1a 100644 --- a/falcon/routing/compiled.py +++ b/falcon/routing/compiled.py @@ -916,9 +916,9 @@ def _validate(self, name): class CompiledRouterOptions: """Defines a set of configurable router options. - An instance of this class is exposed via :py:attr:`falcon.App.router_options` - and :py:attr:`falcon.asgi.App.router_options` for configuring certain - :py:class:`~.CompiledRouter` behaviors. + An instance of this class is exposed via :attr:`falcon.App.router_options` + and :attr:`falcon.asgi.App.router_options` for configuring certain + :class:`~.CompiledRouter` behaviors. """ converters: ConverterDict diff --git a/falcon/routing/util.py b/falcon/routing/util.py index 684699a3e..3d254acc1 100644 --- a/falcon/routing/util.py +++ b/falcon/routing/util.py @@ -41,7 +41,7 @@ def compile_uri_template(template): Each field is converted to a named group, so that when a match is found, the fields can be easily extracted using - :py:meth:`re.MatchObject.groupdict`. + :meth:`re.MatchObject.groupdict`. This function does not support the more flexible templating syntax used in the default router. Only simple paths with bracketed diff --git a/falcon/testing/client.py b/falcon/testing/client.py index d265d8997..1521128e7 100644 --- a/falcon/testing/client.py +++ b/falcon/testing/client.py @@ -186,7 +186,7 @@ class _ResultBase: will "win" and be represented in `headers`. cookies (dict): A dictionary of - :py:class:`falcon.testing.Cookie` values parsed from the + :class:`falcon.testing.Cookie` values parsed from the response, by name. The cookies dictionary can be used directly in subsequent requests:: @@ -306,7 +306,7 @@ class Result(_ResultBase): will "win" and be represented in `headers`. cookies (dict): A dictionary of - :py:class:`falcon.testing.Cookie` values parsed from the + :class:`falcon.testing.Cookie` values parsed from the response, by name. encoding (str): Text encoding of the response body, or ``None`` if the encoding can not be determined. @@ -400,7 +400,7 @@ class StreamedResult(_ResultBase): will "win" and be represented in `headers`. cookies (dict): A dictionary of - :py:class:`falcon.testing.Cookie` values parsed from the + :class:`falcon.testing.Cookie` values parsed from the response, by name. encoding (str): Text encoding of the response body, or ``None`` if the encoding can not be determined. @@ -565,7 +565,7 @@ def simulate_request( for the 'Set-Cookie' header. Returns: - :py:class:`~.Result`: The result of the request + :class:`~.Result`: The result of the request """ if _is_asgi_app(app): @@ -765,7 +765,7 @@ async def _simulate_request_asgi( for the 'Set-Cookie' header. Returns: - :py:class:`~.Result`: The result of the request + :class:`~.Result`: The result of the request """ path, query_string, headers, body, extras = _prepare_sim_args( @@ -1048,14 +1048,14 @@ async def __aexit__(self, ex_type, ex, tb): async def simulate_get(self, path='/', **kwargs) -> _ResultBase: """Simulate a GET request to an ASGI application. - (See also: :py:meth:`falcon.testing.simulate_get`) + (See also: :meth:`falcon.testing.simulate_get`) """ return await self.simulate_request('GET', path, **kwargs) def simulate_get_stream(self, path='/', **kwargs): """Simulate a GET request to an ASGI application with a streamed response. - (See also: :py:meth:`falcon.testing.simulate_get` for a list of + (See also: :meth:`falcon.testing.simulate_get` for a list of supported keyword arguments.) This method returns an async context manager that can be used to obtain @@ -1090,7 +1090,7 @@ def simulate_ws(self, path='/', **kwargs): """Simulate a WebSocket connection to an ASGI application. All keyword arguments are passed through to - :py:meth:`falcon.testing.create_scope_ws`. + :meth:`falcon.testing.create_scope_ws`. This method returns an async context manager that can be used to obtain a managed :class:`falcon.testing.ASGIWebSocketSimulator` instance. @@ -1117,49 +1117,49 @@ def simulate_ws(self, path='/', **kwargs): async def simulate_head(self, path='/', **kwargs) -> _ResultBase: """Simulate a HEAD request to an ASGI application. - (See also: :py:meth:`falcon.testing.simulate_head`) + (See also: :meth:`falcon.testing.simulate_head`) """ return await self.simulate_request('HEAD', path, **kwargs) async def simulate_post(self, path='/', **kwargs) -> _ResultBase: """Simulate a POST request to an ASGI application. - (See also: :py:meth:`falcon.testing.simulate_post`) + (See also: :meth:`falcon.testing.simulate_post`) """ return await self.simulate_request('POST', path, **kwargs) async def simulate_put(self, path='/', **kwargs) -> _ResultBase: """Simulate a PUT request to an ASGI application. - (See also: :py:meth:`falcon.testing.simulate_put`) + (See also: :meth:`falcon.testing.simulate_put`) """ return await self.simulate_request('PUT', path, **kwargs) async def simulate_options(self, path='/', **kwargs) -> _ResultBase: """Simulate an OPTIONS request to an ASGI application. - (See also: :py:meth:`falcon.testing.simulate_options`) + (See also: :meth:`falcon.testing.simulate_options`) """ return await self.simulate_request('OPTIONS', path, **kwargs) async def simulate_patch(self, path='/', **kwargs) -> _ResultBase: """Simulate a PATCH request to an ASGI application. - (See also: :py:meth:`falcon.testing.simulate_patch`) + (See also: :meth:`falcon.testing.simulate_patch`) """ return await self.simulate_request('PATCH', path, **kwargs) async def simulate_delete(self, path='/', **kwargs) -> _ResultBase: """Simulate a DELETE request to an ASGI application. - (See also: :py:meth:`falcon.testing.simulate_delete`) + (See also: :meth:`falcon.testing.simulate_delete`) """ return await self.simulate_request('DELETE', path, **kwargs) async def simulate_request(self, *args, **kwargs) -> _ResultBase: """Simulate a request to an ASGI application. - Wraps :py:meth:`falcon.testing.simulate_request` to perform a + Wraps :meth:`falcon.testing.simulate_request` to perform a WSGI request directly against ``self.app``. Equivalent to:: falcon.testing.simulate_request(self.app, *args, **kwargs) @@ -1289,7 +1289,7 @@ def simulate_get(app, path, **kwargs) -> _ResultBase: for the 'Set-Cookie' header. Returns: - :py:class:`~.Result`: The result of the request + :class:`~.Result`: The result of the request """ return simulate_request(app, 'GET', path, **kwargs) @@ -1387,7 +1387,7 @@ def simulate_head(app, path, **kwargs) -> _ResultBase: for the 'Set-Cookie' header. Returns: - :py:class:`~.Result`: The result of the request + :class:`~.Result`: The result of the request """ return simulate_request(app, 'HEAD', path, **kwargs) @@ -1498,7 +1498,7 @@ def simulate_post(app, path, **kwargs) -> _ResultBase: for the 'Set-Cookie' header. Returns: - :py:class:`~.Result`: The result of the request + :class:`~.Result`: The result of the request """ return simulate_request(app, 'POST', path, **kwargs) @@ -1609,7 +1609,7 @@ def simulate_put(app, path, **kwargs) -> _ResultBase: for the 'Set-Cookie' header. Returns: - :py:class:`~.Result`: The result of the request + :class:`~.Result`: The result of the request """ return simulate_request(app, 'PUT', path, **kwargs) @@ -1698,7 +1698,7 @@ def simulate_options(app, path, **kwargs) -> _ResultBase: (default: ``None``) Returns: - :py:class:`~.Result`: The result of the request + :class:`~.Result`: The result of the request """ return simulate_request(app, 'OPTIONS', path, **kwargs) @@ -1804,7 +1804,7 @@ def simulate_patch(app, path, **kwargs) -> _ResultBase: for the 'Set-Cookie' header. Returns: - :py:class:`~.Result`: The result of the request + :class:`~.Result`: The result of the request """ return simulate_request(app, 'PATCH', path, **kwargs) @@ -1910,7 +1910,7 @@ def simulate_delete(app, path, **kwargs) -> _ResultBase: for the 'Set-Cookie' header. Returns: - :py:class:`~.Result`: The result of the request + :class:`~.Result`: The result of the request """ return simulate_request(app, 'DELETE', path, **kwargs) @@ -2012,56 +2012,56 @@ async def __aexit__(self, ex_type, ex, tb): def simulate_get(self, path='/', **kwargs) -> _ResultBase: """Simulate a GET request to a WSGI application. - (See also: :py:meth:`falcon.testing.simulate_get`) + (See also: :meth:`falcon.testing.simulate_get`) """ return self.simulate_request('GET', path, **kwargs) def simulate_head(self, path='/', **kwargs) -> _ResultBase: """Simulate a HEAD request to a WSGI application. - (See also: :py:meth:`falcon.testing.simulate_head`) + (See also: :meth:`falcon.testing.simulate_head`) """ return self.simulate_request('HEAD', path, **kwargs) def simulate_post(self, path='/', **kwargs) -> _ResultBase: """Simulate a POST request to a WSGI application. - (See also: :py:meth:`falcon.testing.simulate_post`) + (See also: :meth:`falcon.testing.simulate_post`) """ return self.simulate_request('POST', path, **kwargs) def simulate_put(self, path='/', **kwargs) -> _ResultBase: """Simulate a PUT request to a WSGI application. - (See also: :py:meth:`falcon.testing.simulate_put`) + (See also: :meth:`falcon.testing.simulate_put`) """ return self.simulate_request('PUT', path, **kwargs) def simulate_options(self, path='/', **kwargs) -> _ResultBase: """Simulate an OPTIONS request to a WSGI application. - (See also: :py:meth:`falcon.testing.simulate_options`) + (See also: :meth:`falcon.testing.simulate_options`) """ return self.simulate_request('OPTIONS', path, **kwargs) def simulate_patch(self, path='/', **kwargs) -> _ResultBase: """Simulate a PATCH request to a WSGI application. - (See also: :py:meth:`falcon.testing.simulate_patch`) + (See also: :meth:`falcon.testing.simulate_patch`) """ return self.simulate_request('PATCH', path, **kwargs) def simulate_delete(self, path='/', **kwargs) -> _ResultBase: """Simulate a DELETE request to a WSGI application. - (See also: :py:meth:`falcon.testing.simulate_delete`) + (See also: :meth:`falcon.testing.simulate_delete`) """ return self.simulate_request('DELETE', path, **kwargs) def simulate_request(self, *args, **kwargs) -> _ResultBase: """Simulate a request to a WSGI application. - Wraps :py:meth:`falcon.testing.simulate_request` to perform a + Wraps :meth:`falcon.testing.simulate_request` to perform a WSGI request directly against ``self.app``. Equivalent to:: falcon.testing.simulate_request(self.app, *args, **kwargs) diff --git a/falcon/testing/helpers.py b/falcon/testing/helpers.py index de24c6b21..f2cbcb45b 100644 --- a/falcon/testing/helpers.py +++ b/falcon/testing/helpers.py @@ -1268,12 +1268,12 @@ def create_req(options=None, **kwargs) -> falcon.Request: """Create and return a new Request instance. This function can be used to conveniently create a WSGI environ - and use it to instantiate a :py:class:`falcon.Request` object in one go. + and use it to instantiate a :class:`falcon.Request` object in one go. The arguments for this function are identical to those - of :py:meth:`falcon.testing.create_environ`, except an additional + of :meth:`falcon.testing.create_environ`, except an additional `options` keyword argument may be set to an instance of - :py:class:`falcon.RequestOptions` to configure certain + :class:`falcon.RequestOptions` to configure certain aspects of request parsing in lieu of the defaults. """ @@ -1287,22 +1287,22 @@ def create_asgi_req( """Create and return a new ASGI Request instance. This function can be used to conveniently create an ASGI scope - and use it to instantiate a :py:class:`falcon.asgi.Request` object + and use it to instantiate a :class:`falcon.asgi.Request` object in one go. The arguments for this function are identical to those - of :py:meth:`falcon.testing.create_scope`, with the addition of + of :meth:`falcon.testing.create_scope`, with the addition of `body`, `req_type`, and `options` arguments as documented below. Keyword Arguments: body (bytes): The body data to use for the request (default b''). If - the value is a :py:class:`str`, it will be UTF-8 encoded to + the value is a :class:`str`, it will be UTF-8 encoded to a byte string. - req_type (object): A subclass of :py:class:`falcon.asgi.Request` + req_type (object): A subclass of :class:`falcon.asgi.Request` to instantiate. If not specified, the standard - :py:class:`falcon.asgi.Request` class will simply be used. + :class:`falcon.asgi.Request` class will simply be used. options (falcon.RequestOptions): An instance of - :py:class:`falcon.RequestOptions` that should be used to determine + :class:`falcon.RequestOptions` that should be used to determine certain aspects of request parsing in lieu of the defaults. """ diff --git a/falcon/testing/resource.py b/falcon/testing/resource.py index 28cf70398..cb1715bcb 100644 --- a/falcon/testing/resource.py +++ b/falcon/testing/resource.py @@ -149,10 +149,10 @@ class SimpleTestResource: Only noop ``on_get()`` and ``on_post()`` responders are implemented; when overriding these, or adding additional responders in child classes, they can be decorated with the - :py:meth:`falcon.testing.capture_responder_args` hook in + :meth:`falcon.testing.capture_responder_args` hook in order to capture the *req*, *resp*, and *params* arguments that are passed to the responder. Responders may also be decorated with - the :py:meth:`falcon.testing.set_resp_defaults` hook in order to + the :meth:`falcon.testing.set_resp_defaults` hook in order to set *resp* properties to default *status*, *body*, and *header* values. @@ -238,10 +238,10 @@ class SimpleTestResourceAsync(SimpleTestResource): Only noop ``on_get()`` and ``on_post()`` responders are implemented; when overriding these, or adding additional responders in child classes, they can be decorated with the - :py:meth:`falcon.testing.capture_responder_args` hook in + :meth:`falcon.testing.capture_responder_args` hook in order to capture the *req*, *resp*, and *params* arguments that are passed to the responder. Responders may also be decorated with - the :py:meth:`falcon.testing.set_resp_defaults` hook in order to + the :meth:`falcon.testing.set_resp_defaults` hook in order to set *resp* properties to default *status*, *body*, and *header* values. diff --git a/falcon/testing/test_case.py b/falcon/testing/test_case.py index e3b7ec559..1b07b97f4 100644 --- a/falcon/testing/test_case.py +++ b/falcon/testing/test_case.py @@ -32,19 +32,19 @@ class TestCase(unittest.TestCase, TestClient): - """Extends :py:mod:`unittest` to support WSGI/ASGI functional testing. + """Extends :mod:`unittest` to support WSGI/ASGI functional testing. Note: - If available, uses :py:mod:`testtools` in lieu of - :py:mod:`unittest`. + If available, uses :mod:`testtools` in lieu of + :mod:`unittest`. This base class provides some extra plumbing for unittest-style test cases, to help simulate WSGI or ASGI requests without having to spin up an actual web server. Various simulation methods are - derived from :py:class:`falcon.testing.TestClient`. + derived from :class:`falcon.testing.TestClient`. Simply inherit from this class in your test case classes instead of - :py:class:`unittest.TestCase` or :py:class:`testtools.TestCase`. + :class:`unittest.TestCase` or :class:`testtools.TestCase`. Attributes: app (object): A WSGI or ASGI application to target when simulating diff --git a/falcon/util/time.py b/falcon/util/time.py index e6e13c38d..7df942ba0 100644 --- a/falcon/util/time.py +++ b/falcon/util/time.py @@ -16,7 +16,7 @@ class TimezoneGMT(datetime.tzinfo): - """GMT timezone class implementing the :py:class:`datetime.tzinfo` interface.""" + """GMT timezone class implementing the :class:`datetime.tzinfo` interface.""" GMT_ZERO = datetime.timedelta(hours=0)