Match parsed form fields in request expectations

[sricharanreddycheruku]

Matching form-encoded request bodies currently requires a custom handler. This adds the data_form argument proposed in #369 to compare Werkzeug's parsed form fields.

A mapping compares the first value for each field, while a MultiDict compares all repeated values, consistently with query-string matching. Extra fields and missing empty-valued fields do not match. The raw body remains available to response handlers, and form expectations are mutually exclusive with data and json.

The argument is available on normal, oneshot, ordered, baked and blocking expectations. Existing positional arguments and representations remain unchanged. When the new argument is unused, it is not forwarded to custom matcher factories or expectation overrides. Includes a how-to example, API docstrings, a release note and the updated source-package test inventory.

Original submission validation on Linux / Python 3.12.14 using locked development dependencies with Poetry 2.1.1:

• All 17 new test cases fail on the original source because data_form is absent.
• Focused matcher, baked and blocking tests: 39 passed.
• Full HTTP and packaging suite (pytest -q tests --release): 171 passed, 3 skipped, 2 xfailed; one existing tar-extraction warning.
• Existing HTTPS suite (pytest -q tests --ssl): 1 passed, 175 skips from SSL selection.
• Mypy: no issues in 58 source files.
• make precommit and git diff --check: passed.
• make doc: passed; the same 59 warnings occur on unchanged source, with no new warnings.

Fixes #369

Revision after maintainer review:

• Removed the newly added keyword-only separators before data_form.
• Moved the form example into tests/examples/test_howto_form_data.py and included that tested file in the how-to documentation.
• Specified application/x-www-form-urlencoded and multipart/form-data as the Content-Type values Werkzeug uses to parse form fields.

Revision validation on Linux / Python 3.12.3 with pip-installed development dependencies and Poetry 2.1.1, rather than a lockfile installation:

• Full HTTP and packaging suite: 172 passed, 3 skipped, 2 xfailed, one existing warning.
• HTTPS selection: 1 passed, 176 skipped.
• Form matching and tested documentation example: 16 passed.
• Mypy: no issues in 59 source files.
• All applicable pre-commit hooks passed.
• Fresh documentation build succeeded with 59 warnings, matching the unchanged PR head.
• git diff --check passed.

[csernazs]

Thanks for your PR, I have a few comments only, otherwise looks good to me.

[csernazs]

hi @sricharanreddycheruku,

Sorry for being late. Your PR looks good now. Can you squash your commits? Then I'm happy to merge it.

Thanks for making the requested changes.

Zsolt