Use ParamSpec for LRU cache decorators

[zeel2104]

Summary of Changes

Typed Falcon's internal LRU cache decorator helpers with ParamSpec so decorated callables preserve their original argument and return types.

This also exposes the cache_clear() method through typing for cached callables, allowing existing type: ignore[attr-defined] comments around media handler cache clearing to be removed. While validating the stricter typing, an ASGI testing client call site was updated to explicitly handle the None status case before normalizing the response status.

Related Issues

Closes #2629

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.

• Applied changes to both WSGI and ASGI code paths and interfaces (where applicable).
• Added tests for changed code.
• Performed automated tests and code quality checks by running tox.
• Prefixed code comments with GitHub nick and an appropriate prefix.
• Coding style is consistent with the rest of the framework.
• Updated documentation for changed code.
  • Added docstrings for any new classes, functions, or modules.
  • Updated docstrings for any modifications to existing code.
  • Updated both WSGI and ASGI docs (where applicable).
  • Added references to new classes, functions, or modules to the relevant RST file under docs/.
  • Updated all relevant supporting documentation files under docs/.
  • A copyright notice is included at the top of any new modules (using your own name or the name of your organization).
  • Changed/added classes/methods/functions have appropriate versionadded, versionchanged, or deprecated directives.
• Changes (and possible deprecations) have towncrier news fragments under docs/_newsfragments/, with the file name format {issue_number}.{fragment_type}.rst. (Run tox -e towncrier, and inspect docs/_build/html/changes/ in the browser to ensure it renders correctly.)
• LLM output, if any, has been carefully reviewed and tested by a human developer. (See also: Use of LLMs ("AI").)

Checks Performed

python -B -m pytest tests\test_media_handlers.py
# 37 passed, 5 skipped

tox was not available locally, and raw python -m mypy --strict falcon was blocked by local Python 3.14/toolchain issues, including strict_bytes being reported as an unrecognized mypy option and unrelated existing typing errors.

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.

[codecov]

Codecov Report

❌ Patch coverage is 77.77778% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 99.97%. Comparing base (b1b683a) to head (0e1aebb).

Files with missing lines	Patch %	Lines
falcon/testing/client.py	0.00%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##            master    #2641      +/-   ##
===========================================
- Coverage   100.00%   99.97%   -0.03%     
===========================================
  Files           64       64              
  Lines         7976     7981       +5     
  Branches      1102     1103       +1     
===========================================
+ Hits          7976     7979       +3     
- Misses           0        1       +1     
- Partials         0        1       +1     

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

[vytas7]

Hi @zeel2104 , and thanks for this PR.

Unfortunately, it is not really possible to contribute meaningfully without having access to tox and/or the underlying tools. Being able to verify is even more important in the case of code being generated by an LLM.

You can always create a venv, and install what's required within.