Merge branch 'master' into finish_typing

docs/_newsfragments/1853.breakingchange.rst

@@ -1,3 +1,60 @@
-The deprecated ``has_representation()`` method for :class:`~falcon.HTTPError` was
-removed, along with the ``NoRepresentation`` and ``OptionalRepresentation``
-classes.
+A number of previously deprecated methods, attributes and classes have now been
+removed:
+
+* In Falcon 3.0, the use of positional arguments was deprecated for the
+  optional initializer parameters of :class:`falcon.HTTPError` and its
+  subclasses.
+
+  We have now redefined these optional arguments as keyword-only, so passing
+  them as positional arguments will result in a :class:`TypeError`:
+
+  >>> import falcon
+  >>> falcon.HTTPForbidden('AccessDenied')
+  Traceback (most recent call last):
+    <...>
+  TypeError: HTTPForbidden.__init__() takes 1 positional argument but 2 were given
+  >>> falcon.HTTPForbidden('AccessDenied', 'No write access')
+  Traceback (most recent call last):
+    <...>
+  TypeError: HTTPForbidden.__init__() takes 1 positional argument but 3 were given
+
+  Instead, simply pass these parameters as keyword arguments:
+
+  >>> import falcon
+  >>> falcon.HTTPForbidden(title='AccessDenied')
+  <HTTPForbidden: 403 Forbidden>
+  >>> falcon.HTTPForbidden(title='AccessDenied', description='No write access')
+  <HTTPForbidden: 403 Forbidden>
+
+* The ``falcon-print-routes`` command-line utility is no longer supported;
+  ``falcon-inspect-app`` is a direct replacement.
+
+* A deprecated utility function, ``falcon.get_http_status()``, was removed.
+  Please use :meth:`falcon.code_to_http_status` instead.
+
+* A deprecated routing utility, ``compile_uri_template()``, was removed.
+  This function was only employed in the early versions of the framework, and
+  is expected to have been fully supplanted by the
+  :class:`~falcon.routing.CompiledRouter`. In a pinch, you can simply copy its
+  implementation from the Falcon 3.x source tree into your application.
+
+* The deprecated ``Response.add_link()`` method was removed; please use
+  :meth:`Response.append_link <falcon.Response.append_link>` instead.
+
+* The deprecated ``has_representation()`` method for :class:`~falcon.HTTPError`
+  was removed, along with the ``NoRepresentation`` and
+  ``OptionalRepresentation`` classes.
+
+* An undocumented, deprecated public method ``find_by_media_type()`` of
+  :class:`media.Handlers <falcon.media.Handlers>` was removed.
+  Apart from configuring handlers for Internet media types, the rest of
+  :class:`~falcon.media.Handlers` is only meant to be used internally by the
+  framework (unless documented otherwise).
+
+* Previously, the ``json`` module could be imported via ``falcon.util``.
+  This deprecated alias was removed; please import ``json`` directly from the
+  :mod:`standard library <json>`, or another third-party JSON library of
+  choice.
+
+We decided, on the other hand, to keep the deprecated :class:`falcon.API` alias
+until Falcon 5.0.

docs/_newsfragments/2090.breakingchange.rst

@@ -1,4 +1,5 @@
 The deprecated ``api_helpers`` was removed in favor of the ``app_helpers``
 module. In addition, the deprecated ``body``
-attributes for the :class:`~falcon.HTTPResponse`,
-:class:`~falcon.asgi.HTTPResponse`, and :class:`~falcon.HTTPStatus` classes.
+attributes for the :class:`~falcon.Response`,
+:class:`asgi.Response <falcon.asgi.Response>`,
+and :class:`~falcon.HTTPStatus` classes.

docs/_newsfragments/2253.misc.rst

@@ -1,3 +1,3 @@
 The :ref:`utility functions <util>` ``create_task()`` and
 ``get_running_loop()`` are now deprecated in favor of their standard library
-counterparts, :func:`asyncio.create_task` and `:func:`asyncio.get_running_loop`.
+counterparts, :func:`asyncio.create_task` and :func:`asyncio.get_running_loop`.

docs/api/routing.rst

@@ -478,8 +478,6 @@ be used by custom routing engines.
 
 .. autofunction:: falcon.routing.set_default_responders
 
-.. autofunction:: falcon.routing.compile_uri_template
-
 .. autofunction:: falcon.app_helpers.prepare_middleware
 
 .. autofunction:: falcon.app_helpers.prepare_middleware_ws

docs/api/util.rst

@@ -32,7 +32,6 @@ HTTP Status
 
 .. autofunction:: falcon.http_status_to_code
 .. autofunction:: falcon.code_to_http_status
-.. autofunction:: falcon.get_http_status
 
 Media types
 -----------

falcon/__init__.py

@@ -77,7 +77,6 @@
     'ETag',
     'get_argnames',
     'get_bound_method',
-    'get_http_status',
     'get_running_loop',
     'http_cookies',
     'http_date_to_dt',
@@ -609,7 +608,6 @@
 from falcon.util import ETag
 from falcon.util import get_argnames
 from falcon.util import get_bound_method
-from falcon.util import get_http_status
 from falcon.util import get_running_loop
 from falcon.util import http_cookies
 from falcon.util import http_date_to_dt

falcon/app.py

@@ -1265,20 +1265,20 @@ def _update_sink_and_static_routes(self) -> None:
 
 
 # TODO(myusko): This class is a compatibility alias, and should be removed
-# in the next major release (4.0).
+# in Falcon 5.0.
 class API(App):
     """Compatibility alias of :class:`falcon.App`.
 
     ``API`` was renamed to :class:`App <falcon.App>` in Falcon 3.0 in order to
     reflect the breadth of applications that :class:`App <falcon.App>`, and its
     ASGI counterpart in particular, can now be used for.
 
-    This compatibility alias should be considered deprecated; it will be
-    removed in a future release.
+    This compatibility alias is deprecated; it will be removed entirely in
+    Falcon 5.0.
     """
 
     @deprecation.deprecated(
-        'API class may be removed in a future release, use falcon.App instead.'
+        'The API class will be removed in Falcon 5.0, use falcon.App instead.'
     )
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         super().__init__(*args, **kwargs)

falcon/asgi/app.py

@@ -1060,7 +1060,7 @@ async def _call_lifespan_handlers(
                     )
                     return
 
-                if self.req_options.auto_parse_form_urlencoded:
+                if self.req_options._auto_parse_form_urlencoded:
                     await send(
                         {
                             'type': EventType.LIFESPAN_STARTUP_FAILED,

falcon/asgi/request.py

@@ -41,7 +41,7 @@
 from falcon.typing import MISSING
 from falcon.typing import MissingOr
 from falcon.typing import StoreArgument
-from falcon.util import deprecated
+from falcon.util import deprecation
 from falcon.util import ETag
 from falcon.util.uri import parse_host
 from falcon.util.uri import parse_query_string
@@ -348,8 +348,12 @@ def root_path(self) -> str:
         return ''
 
     @property
-    # NOTE(caselit): Deprecated long ago. Warns since 4.0
-    @deprecated('Use `root_path` instead', is_property=True)
+    # NOTE(caselit): Deprecated long ago. Warns since 4.0.
+    @deprecation.deprecated(
+        'Use `root_path` instead. '
+        '(This compatibility alias will be removed in Falcon 5.0.)',
+        is_property=True,
+    )
     def app(self) -> str:
         """Deprecated alias for :attr:`root_path`."""
         return self.root_path

falcon/cmd/inspect_app.py

@@ -84,12 +84,13 @@ def load_app(parser, args):
     return app
 
 
+# TODO(vytas): Remove this placeholder altogether in Falcon 5.0.
 def route_main():
-    print(
-        'The "falcon-print-routes" command is deprecated. '
-        'Please use "falcon-inspect-app"'
+    sys.stderr.write(
+        'The "falcon-print-routes" command is no longer supported. \n\n'
+        'Please use "falcon-inspect-app" instead.\n\n'
     )
-    main()
+    sys.exit(2)
 
 
 def main():