Repository: falconry/falcon

Issue:
Revisit RequestOptions.auto_parse_form_urlencoded
Create a media handler for `application/x-www-form-urlencoded` that can be used via `req.media`. As part of this work, deprecate the use of the `auto_parse_form_urlencoded` (which merges form params into query string params) by adding a note to the docs to that effect.

The implementation can be patterned after `Request._parse_form_urlencoded()`

Discussion:
codecov[bot]: # [Codecov](https://codecov.io/gh/falconry/falcon/pull/1602?src=pr&el=h1) Report
> Merging [#1602](https://codecov.io/gh/falconry/falcon/pull/1602?src=pr&el=desc) into [master](https://codecov.io/gh/falconry/falcon/commit/a14a8e367497bd559773f70510c928da781a0f6f?src=pr&el=desc) will **not change** coverage.
> The diff coverage is `100%`.

[![Impacted file tree graph](https://codecov.io/gh/falconry/falcon/pull/1602/graphs/tree.svg?width=650&token=zOtkfNQ3h6&height=150&src=pr)](https://codecov.io/gh/falconry/falcon/pull/1602?src=pr&el=tree)

```diff
@@          Coverage Diff           @@
##           master   #1602   +/-   ##
======================================
  Coverage     100%    100%           
======================================
  Files          40      40           
  Lines        2595    2597    +2     
  Branches      394     394           
======================================
+ Hits         2595    2597    +2
```


| [Impacted Files](https://codecov.io/gh/falconry/falcon/pull/1602?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [falcon/request.py](https://codecov.io/gh/falconry/falcon/pull/1602/diff?src=pr&el=tree#diff-ZmFsY29uL3JlcXVlc3QucHk=) | `100% <ø> (ø)` | :arrow_up: |
| [falcon/media/handlers.py](https://codecov.io/gh/falconry/falcon/pull/1602/diff?src=pr&el=tree#diff-ZmFsY29uL21lZGlhL2hhbmRsZXJzLnB5) | `100% <100%> (ø)` | :arrow_up: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/falconry/falcon/pull/1602?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/falconry/falcon/pull/1602?src=pr&el=footer). Last update [a14a8e3...7d55f4d](https://codecov.io/gh/falconry/falcon/pull/1602?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).


Patch:
diff --git a/docs/_newsfragments/1580-auto-parse-form-urlencoded.removal.rst b/docs/_newsfragments/1580-auto-parse-form-urlencoded.removal.rst
new file mode 100644
index 0000000..d719ea9
--- /dev/null
+++ b/docs/_newsfragments/1580-auto-parse-form-urlencoded.removal.rst
@@ -0,0 +1,3 @@
+The :attr:`~.RequestOptions.auto_parse_form_urlencoded` option is now
+deprecated in favor of :class:`falcon.media.URLEncodedFormHandler`.
+(See also: :ref:`access_urlencoded_form`).
diff --git a/docs/api/media.rst b/docs/api/media.rst
index a7f7b06..9041ea3 100644
--- a/docs/api/media.rst
+++ b/docs/api/media.rst
@@ -3,10 +3,11 @@
 Media
 =====
 
-Falcon allows for easy and customizable internet media type handling. By default
-Falcon only enables a single JSON handler. However, additional handlers
-can be configured through the :any:`falcon.RequestOptions` and
-:any:`falcon.ResponseOptions` objects specified on your :any:`falcon.App`.
+Falcon allows for easy and customizable internet media type handling. By
+default Falcon only enables handlers for JSON and URL-encoded HTML
+forms. However, additional handlers can be configured through the
+:any:`falcon.RequestOptions` and :any:`falcon.ResponseOptions` objects
+specified on your :any:`falcon.App`.
 
 .. note::
 
diff --git a/docs/user/faq.rst b/docs/user/faq.rst
index cf2c4ec..f2b4949 100644
--- a/docs/user/faq.rst
+++ b/docs/user/faq.rst
@@ -521,46 +521,40 @@ To work around this, RFC 3986 specifies ``+`` as a reserved character,
 and recommends percent-encoding any such characters when their literal value is
 desired (``%2B`` in the case of ``+``).
 
+.. _access_urlencoded_form:
+
 How can I access POSTed form params?
 ------------------------------------
-By default, Falcon does not consume request bodies. However, setting
-the :attr:`~RequestOptions.auto_parse_form_urlencoded` to ``True``
-on an instance of ``falcon.App``
-will cause the framework to consume the request body when the
-content type is ``application/x-www-form-urlencoded``, making
-the form parameters accessible via :attr:`~.Request.params`,
-:meth:`~.Request.get_param`, etc.
-
-.. code:: python
-
-    app.req_options.auto_parse_form_urlencoded = True
-
-Alternatively, :class:`falcon.media.URLEncodedFormHandler` may be
-:ref:`installed <custom_media_handlers>` to handle the
-``application/x-www-form-urlencoded`` content type. The form parameters can
-then be simply accessed as :attr:`Request.media <falcon.Request.media>`:
+By default, Falcon does not consume request bodies. However, a :ref:`media
+handler <media>` for the ``application/x-www-form-urlencoded`` content type is
+installed by default, thus making the POSTed form available as
+:attr:`Request.media <falcon.Request.media>` with zero configuration:
 
 .. code:: python
 
     import falcon
-    from falcon import media
 
+    # ...
 
-    handlers = media.Handlers({
-        falcon.MEDIA_JSON: media.JSONHandler(),
-        falcon.MEDIA_URLENCODED: media.URLEncodedFormHandler(),
-        # ... and any other request media handlers you may need
-    })
+    class MyResource:
+        def on_post(self, req, resp):
+            form = req.media
+            # TODO: Handle the submitted URL-encoded form
+            # ...
 
-    api = falcon.API()
-    api.req_options.media_handlers = handlers
+            # NOTE: Falcon chooses the right media handler automatically, but
+            #   if we wanted to differentiate from, for instance, JSON, we
+            #   could check whether req.content_type == falcon.MEDIA_URLENCODED
+            #   or use mimeparse to implement more sophisticated logic.
 
 .. note::
-   Going forward, the :attr:`~RequestOptions.auto_parse_form_urlencoded` way to
-   access the submitted form may be deprecated in favor of the media handler in
-   further development versions of Falcon 3.0 series;
-   :class:`falcon.media.URLEncodedFormHandler` would then be installed by
-   default.
+   In prior versions of Falcon, a POSTed URL-encoded form could be automatically
+   consumed and merged into :attr:`~.Request.params` by setting the
+   :attr:`~.RequestOptions.auto_parse_form_urlencoded` option to ``True``. This
+   behavior is still supported in the Falcon 3.x series. However, it has been
+   deprecated in favor of :class:`~.media.URLEncodedFormHandler`, and the
+   option to merge URL-encoded form data into
+   :attr:`~.Request.params` may be removed in a future release.
 
 POSTed form parameters may also be read directly from
 :attr:`~.Request.stream` and parsed via
diff --git a/falcon/media/handlers.py b/falcon/media/handlers.py
index 90e78ae..fc1d928 100644
--- a/falcon/media/handlers.py
+++ b/falcon/media/handlers.py
@@ -1,7 +1,9 @@
 from collections import UserDict
 
 from falcon import errors
+from falcon.constants import MEDIA_URLENCODED
 from falcon.media import JSONHandler
+from falcon.media import URLEncodedFormHandler
 from falcon.vendor import mimeparse
 
 
@@ -11,6 +13,7 @@ class Handlers(UserDict):
         handlers = initial or {
             'application/json': JSONHandler(),
             'application/json; charset=UTF-8': JSONHandler(),
+            MEDIA_URLENCODED: URLEncodedFormHandler(),
         }
 
         # NOTE(jmvrbanac): Directly calling UserDict as it's not inheritable.
diff --git a/falcon/request.py b/falcon/request.py
index e389039..5efb7e1 100644
--- a/falcon/request.py
+++ b/falcon/request.py
@@ -1164,6 +1164,14 @@ class Request:
             :py:attr:`~.RequestOptions.auto_parse_form_urlencoded` to
             ``True`` via :any:`App.req_options`.
 
+            Note, however, that the
+            :attr:`~.RequestOptions.auto_parse_form_urlencoded` option is
+            considered deprecated as of Falcon 3.0 in favor of accessing the
+            URL-encoded form via :attr:`~Request.media`, and it may be removed
+            in a future release.
+
+            See also: :ref:`access_urlencoded_form`
+
         Note:
             Similar to the way multiple keys in form data is handled,
             if a query parameter is assigned a comma-separated list of
@@ -1812,6 +1820,14 @@ class RequestOptions:
             Enabling this option makes the form parameters accessible
             via :attr:`~.params`, :meth:`~.get_param`, etc.
 
+            Warning:
+                The `auto_parse_form_urlencoded` option is considered
+                deprecated as of Falcon 3.0 in favor of accessing the
+                URL-encoded form via :attr:`~Request.media`, and it may be
+                removed in a future release.
+
+                See also: :ref:`access_urlencoded_form`
+
             Warning:
                 When this option is enabled, the request's body
                 stream will be left at EOF. The original data is


Test patch:
diff --git a/tests/test_media_urlencoded.py b/tests/test_media_urlencoded.py
index 6f05c2c..615ce36 100644
--- a/tests/test_media_urlencoded.py
+++ b/tests/test_media_urlencoded.py
@@ -37,17 +37,9 @@ class MediaMirror:
 
 @pytest.fixture
 def client():
-    handlers = media.Handlers({
-        falcon.MEDIA_JSON: media.JSONHandler(),
-        falcon.MEDIA_URLENCODED: media.URLEncodedFormHandler(),
-    })
-    api = falcon.API()
-    api.req_options.media_handlers = handlers
-    api.resp_options.media_handlers = handlers
-
-    api.add_route('/media', MediaMirror())
-
-    return testing.TestClient(api)
+    app = falcon.App()
+    app.add_route('/media', MediaMirror())
+    return testing.TestClient(app)
 
 
 def test_empty_form(client):
@@ -61,6 +53,11 @@ def test_empty_form(client):
     ('a=1&b=&c=3', {'a': '1', 'b': '', 'c': '3'}),
     ('param=undefined', {'param': 'undefined'}),
     ('color=green&color=black', {'color': ['green', 'black']}),
+    (
+        'food=hamburger+%28%F0%9F%8D%94%29&sauce=BBQ',
+        {'food': 'hamburger (🍔)', 'sauce': 'BBQ'},
+    ),
+    ('flag%1&flag%2&flag%1&flag%2', {'flag%1': ['', ''], 'flag%2': ['', '']}),
 ])
 def test_urlencoded_form(client, body, expected):
     resp = client.simulate_post(