feat(request): add get_query_string_as_media() method by MannXo · Pull Request #2548 · falconry/falcon

MannXo · 2025-10-08T12:29:05Z

Add new method to deserialize entire query string as media content. This supports OpenAPI 3.2 Parameter Object with content specification, where the query string is treated as serialized data (e.g., JSON).

The method:

URL-decodes the query string
Deserializes using configured media handlers
Caches results for performance
Supports both WSGI and ASGI (async) variants
Includes default_when_empty parameter for graceful error handling

Example usage:
# Query string: ?%7B%22numbers%22%3A%5B1%2C2%5D%7D data = req.get_query_string_as_media('application/json') # data == {'numbers': [1, 2]}

Closes #2546.

Summary of Changes

Replace this text with a high-level summary of the changes included in this PR.

Related Issues

Please reference here any issue #'s that are relevant to this PR, or simply enter "N/A" if this PR does not relate to any existing issues.

Pull Request Checklist

This is just a reminder about the most common mistakes. Please make sure that you tick all appropriate boxes. Reading our contribution guide at least once will save you a few review cycles!

If an item doesn't apply to your pull request, check it anyway to make it apparent that there's nothing to do.

If you have any questions to any of the points above, just submit and ask! This checklist is here to help you, not to deter you from contributing!

PR template inspired by the attrs project.

Add new method to deserialize entire query string as media content. This supports OpenAPI 3.2 Parameter Object with content specification, where the query string is treated as serialized data (e.g., JSON). The method: - URL-decodes the query string - Deserializes using configured media handlers - Caches results for performance - Supports both WSGI and ASGI (async) variants - Includes default_when_empty parameter for graceful error handling Example usage: # Query string: ?%7B%22numbers%22%3A%5B1%2C2%5D%7D data = req.get_query_string_as_media('application/json') # data == {'numbers': [1, 2]}

codecov · 2025-10-08T14:00:32Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (587bffd) to head (38879b6).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff            @@
##            master     #2548   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           64        64           
  Lines         7875      7890   +15     
  Branches      1078      1081    +3     
=========================================
+ Hits          7875      7890   +15

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Add comprehensive edge case tests to achieve 100% coverage: - test_cached_error_with_default_when_empty: Verify cached error returns default on subsequent call - test_cached_error_reraises_without_default: Verify cached error is re-raised without default These tests cover the error caching branches where the method is called multiple times after an error has been cached, both with and without the default_when_empty parameter. Total: 40 tests (20 WSGI + 20 ASGI)

Use the synchronous handler.deserialize() instead of deserialize_async() when processing query strings, since the data is already in memory as a string. This avoids type checking errors related to BytesIO not being compatible with AsyncReadableIO, and is more appropriate since no async I/O is needed for in-memory data.

vytas7

Thanks for this PR, it looks like an already very advanced implementation! 💯

However, as explained inline, we don't want to perform advanced caching of the deserialized media, at least not in the first iteration, given that this is a rather niche feature (it has been introduced in OpenAPI 3.2.0, previously this scenario was impossible to describe in OAS).

vytas7 · 2025-10-10T20:14:17Z

examples/query_string_as_media_example.py

Although we love good documentation, and this looks like an excellent walkthrough, maybe it devotes too much attention to this rather niche feature. 🤔

Moreover, is this script included anywhere?

Removed query_string_as_media_example.py for now. Can add back later if/when caching is implemented.

docs/_newsfragments/2546.newandimproved.rst

vytas7 · 2025-10-10T20:17:55Z

falcon/asgi/request.py

    _cached_uri: str | None = None
    _media: UnsetOr[Any] = _UNSET
    _media_error: Exception | None = None
+    _query_string_media: UnsetOr[Any] = _UNSET


This is a rather new niche feature, that is unlikely to be widely used, at least not directly after release.

So let's not allocate new requests attributes for caching it, simply deserialize it every time anew. It is unlikely to be called many times.

Removed _query_string_media and _query_string_media_error slots. Method now deserializes fresh on each call.

vytas7 · 2025-10-10T20:20:33Z

falcon/asgi/request.py

+                # memory as a string
+                from io import BytesIO
+
+                query_stream = BytesIO(decoded_query_string.encode('utf-8'))


Although Falcon is performance-oriented, as pointed out above, this method is going to be a rather niche feature, so maybe it would be possible to DRY the ASGI branch by calling the sync method to do the heavy lifting?

We could possibly just document that the synchronous handler is always used in this case, even for ASGI.

Done. ASGI implementation now delegates to parent: return request.Request.get_query_string_as_media(self, media_type, default_when_empty

MannXo · 2025-10-10T21:11:26Z

Thanks for this PR, it looks like an already very advanced implementation! 💯

However, as explained inline, we don't want to perform advanced caching of the deserialized media, at least not in the first iteration, given that this is a rather niche feature (it has been introduced in OpenAPI 3.2.0, previously this scenario was impossible to describe in OAS).

Thank you @vytas7 for the thorough review and your feedback. I have made some changes, to address your comments. Ready for the next round of review.

CaselIT · 2025-10-14T20:52:17Z

falcon/request.py

        self._media: UnsetOr[Any] = _UNSET
        self._media_error: Exception | None = None
+        self._query_string_media: UnsetOr[Any] = _UNSET
+        self._query_string_media_error: Exception | None = None


I guess we can now remove these

Done. Removed _query_string_media and _query_string_media_error

CaselIT · 2025-10-14T20:54:14Z

falcon/request.py

+
+        try:
+            return handler.deserialize(
+                query_stream, media_type, len(decoded_query_string.encode('utf-8'))


we could avoid this re-encoding by saving the bytes before creating the bytesio

Good catch. We now store query_bytes = decoded_query_string.encode('utf-8') and reuse it for BytesIO and len() to avoid double-encoding.

falcon/asgi/request.py

CaselIT · 2025-10-14T21:00:50Z

tests/test_request_query_string_media.py

+
+        assert resource.captured_media == {'emoji': '🚀', 'chinese': '你好'}
+
+    def test_error_caching(self, asgi, client):


this test is likely outdated since caching was removed

Updated the test comment to reflect current behavior (removed references to caching); the test logic remains and still passes.

tests/test_request_query_string_media.py

CaselIT · 2025-10-14T21:03:55Z

tests/test_request_query_string_media.py

+
+        assert resource.captured_media == {'uses': 'default'}
+
+    def test_cached_error_with_default_when_empty(self, asgi, client):


here too let's just remove the comments regarding the cache, the test if fine to have even with the current impl

Removed outdated cache comments and kept the test. It continues to validate error + default behavior

CaselIT · 2025-10-14T21:04:18Z

great work, thanks!

MannXo · 2025-10-16T07:18:06Z

great work, thanks!

Thank you for the review and comments. I have pushed a new commit. Ready for the next round of review.

vytas7

Hi again @MannXo, and sorry for taking time to respond to this one.

Your PR looks good for most of it, but IMHO we should remove the async version of the method, plus make a couple of other adjustments before merging (see inline).

falcon/asgi/request.py

vytas7 · 2025-12-28T16:34:07Z

tests/test_request_query_string_media.py

+
+
+@pytest.fixture
+def client(asgi):


I don't think this is needed, the util fixture can do this for you.

falcon/request.py

MannXo · 2025-12-29T10:20:09Z

Thank you for the comments @vytas7

I pushed a change including the following:
1- Removed the async method from request.py. Now inherits from parent WSGI class.
2- Removed custom fixture and async resource variations. All 19 tests now use util.create_app() pattern for both ASGI/WSGI.
3- Added try-except in request.py to catch HTTPUnsupportedMediaType and raise ValueError with a suitable message about missing media handler configuration.

P.S, The mypy_tests pipeline failure appears to be a pre-existing issue unrelated to my changes. (I get the same errors running the check on master)

vytas7 · 2025-12-29T11:25:30Z

P.S, The mypy_tests pipeline failure appears to be a pre-existing issue unrelated to my changes. (I get the same errors running the check on master)

~~Aye, a new Mypy version... I'll try to take a look at that.~~

Edit: still not 100% why we started getting this only now, but it is fun that it actually uncovers a real issue. When using testtools, Falcon TestCase's patch method is shadowed by testtools.TestCase.patch via diamond inheritance...
(If anyone is wondering what the heck is testtools, see #2156.)

vytas7

Thanks for the prompt updates @MannXo!
A couple more potential improvements (see inline), and I think we can merge this.

vytas7 · 2025-12-31T13:39:43Z

falcon/request.py

+            handler, _, _ = self.options.media_handlers._resolve(
+                media_type, self.options.default_media_type
+            )
+        except errors.HTTPUnsupportedMediaType:


Not critical for the first iteration, but it would be nice to optimize this slightly by passing raise_not_found=False to the _resolve method, and handling the case where handler is None instead. It should be much cheaper than raising one extra time unnecessarily.

vytas7 · 2025-12-31T13:41:45Z

tests/test_request_query_string_media.py

+        resource = CaptureQueryStringMedia()
+        app = util.create_app(asgi)
+        app.add_route('/test', resource)
+        client = testing.TestClient(app)


Could we DRY this block along the below lines (untested)? ⬇️

@pytest.fixture() def client(asgi, util): resource = CaptureQueryStringMedia() app = util.create_app(asgi) app.add_route('/test', resource) return testing.TestClient(app)

CaselIT

thanks for the change!

I looks mostly ok to me, I just just document the error if the media is missing and dry up a bit the tests

CaselIT · 2026-01-18T11:06:05Z

falcon/request.py

+            media_type, self.options.default_media_type, raise_not_found=False
+        )
+        if handler is None:
+            raise ValueError(


let's mention in the doc string that a value error is raised if no handler is found

Added Raises section

CaselIT · 2026-01-18T11:10:05Z

tests/test_request_query_string_media.py

+        client.simulate_get('/test', query_string=query_string)
+
+        # URLEncodedFormHandler should parse this
+        assert isinstance(resource.captured_media, dict)


we could also / instead compare the value

CaselIT · 2026-01-18T11:11:32Z

tests/test_request_query_string_media.py

+
+        assert resource.captured_media == {'emoji': '🚀', 'chinese': '你好'}
+
+    def test_error_caching(self, asgi, util):


not sure if this test is useful. it's fine to keep though

kept it for now

CaselIT · 2026-01-18T11:12:32Z

tests/test_request_query_string_media.py

+
+        assert resource.captured_media == [1, 2, 3, 4, 5]
+
+    def test_boolean_and_null_values(self, standard_client):


I would remove, we aren't testing a json serializer here

CaselIT · 2026-01-18T11:12:44Z

tests/test_request_query_string_media.py

+            'empty': None,
+        }
+
+    def test_numeric_values(self, standard_client):


same, would remove

CaselIT · 2026-01-18T11:13:40Z

tests/test_request_query_string_media.py

+
+        assert resource.error_message == 'Custom error'
+
+    def test_uses_default_media_type_when_none_specified(self, asgi, util):


same as test_simple_json_query_string, would remove

…ns, remove redundant tests

MannXo added 2 commits October 8, 2025 19:26

vytas7 requested changes Oct 10, 2025

View reviewed changes

remove caching from get_query_string_as_media

951f4e0

CaselIT requested changes Oct 14, 2025

View reviewed changes

CaselIT mentioned this pull request Oct 15, 2025

Add new method req.get_param_as_media() #2549

Open

MannXo force-pushed the feat/query-string-as-media branch from 7ea7c17 to 8cbae6b Compare October 16, 2025 07:10

refactor: remove query-string caching

5633332

MannXo force-pushed the feat/query-string-as-media branch from 8cbae6b to 5633332 Compare October 16, 2025 09:12

Merge branch 'master' into feat/query-string-as-media

4e658c7

vytas7 added the hacktoberfest-accepted label Oct 29, 2025

vytas7 added the blocked-by-release label Nov 8, 2025

Merge branch 'master' into feat/query-string-as-media

9dff053

vytas7 removed the blocked-by-release label Nov 11, 2025

Merge branch 'master' into feat/query-string-as-media

23ed9f1

vytas7 requested changes Dec 28, 2025

View reviewed changes

resolved PR comments.

69df029

Merge branch 'master' into feat/query-string-as-media

adbe960

vytas7 requested changes Dec 31, 2025

View reviewed changes

vytas7 requested a review from CaselIT December 31, 2025 13:45

resolved PR comments

fc14ac6

vytas7 removed the hacktoberfest-accepted label Jan 2, 2026

Merge branch 'master' into feat/query-string-as-media

d63bc23

Merge branch 'master' into feat/query-string-as-media

e83caf1

CaselIT reviewed Jan 18, 2026

View reviewed changes

vytas7 and others added 2 commits January 21, 2026 20:10

Merge branch 'master' into feat/query-string-as-media

b30f8dd

Address PR review: add ValueError to docstring, improve test assertio…

38879b6

…ns, remove redundant tests

MannXo requested a review from CaselIT January 25, 2026 09:52


		assert resource.captured_media == {'emoji': '🚀', 'chinese': '你好'}

		def test_error_caching(self, asgi, client):


		assert resource.captured_media == {'uses': 'default'}

		def test_cached_error_with_default_when_empty(self, asgi, client):


		assert resource.captured_media == {'emoji': '🚀', 'chinese': '你好'}

		def test_error_caching(self, asgi, util):


		assert resource.captured_media == [1, 2, 3, 4, 5]

		def test_boolean_and_null_values(self, standard_client):


		assert resource.error_message == 'Custom error'

		def test_uses_default_media_type_when_none_specified(self, asgi, util):

Uh oh!

Comments

Conversation

MannXo commented Oct 8, 2025 • edited by vytas7 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary of Changes

Related Issues

Pull Request Checklist

Uh oh!

codecov bot commented Oct 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

vytas7 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MannXo commented Oct 10, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

CaselIT commented Oct 14, 2025

Uh oh!

MannXo commented Oct 16, 2025

Uh oh!

vytas7 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

MannXo commented Dec 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vytas7 commented Dec 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vytas7 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

CaselIT left a comment

Choose a reason for hiding this comment

Uh oh!

MannXo commented Oct 8, 2025 •

edited by vytas7

Loading

codecov bot commented Oct 8, 2025 •

edited

Loading

MannXo commented Dec 29, 2025 •

edited

Loading

vytas7 commented Dec 29, 2025 •

edited

Loading