Inline annotations in 2.34.0 cause mypy error for Request json payloads

[JamMarHer]

requests version 2.34.0 added inline type annotations. This is causing some issues with mypy, specifically building a Request with a json argument.

The MR (#7272) that introduced the feature notes that mypy support is not currently a goal, but I think it's worth sharing this issue.

Expected Result

Passing a JSON-compatible dictionary to the json argument of requests.Request should type-check successfully.

For example, a value typed as:

dict[str, None | bool | int | float | str]

or the narrower:

dict[str, str]

should be accepted as a valid JSON payload.

Actual Result

mypy reports an incompatible argument type error when a dictionary is passed to the json argument.

Reproduction Steps

Create a file named test.py:

from requests import Request

payload: dict[str, str] = {"test": "test"}

request = Request(json=payload)

Then run mypy (used 2.1.0) against the python code:

python -m mypy test.py
test.py:5: error: Argument "json" to "Request" has incompatible type "dict[str, str]"; expected "JsonType"  [arg-type]
test.py:5: note: "dict" is invariant -- see https://mypy.readthedocs.io/en/stable/common_issues.html#variance
test.py:5: note: Consider using "Mapping" instead, which is covariant in the value type
Found 1 error in 1 file (checked 1 source file)

System Information

$ python -m requests.help

{
  "chardet": {
    "version": null
  },
  "charset_normalizer": {
    "version": "3.4.7"
  },
  "cryptography": {
    "version": ""
  },
  "idna": {
    "version": "3.14"
  },
  "implementation": {
    "name": "CPython",
    "version": "3.13.13"
  },
  "platform": {
    "release": "24.6.0",
    "system": "Darwin"
  },
  "pyOpenSSL": {
    "openssl_version": "",
    "version": null
  },
  "requests": {
    "version": "2.34.0"
  },
  "system_ssl": {
    "version": "30600020"
  },
  "urllib3": {
    "version": "2.7.0"
  },
  "using_charset_normalizer": true,
  "using_pyopenssl": false
}

[nateprewitt]

Thanks for the report, @JamMarHer. While mypy doesn't run fully on Requests internals, all public facing APIs should be mypy compliant. I'll take a look at this today.

[nateprewitt]

So I think this is another variation of #7426. typeshed didn't try to type this and just called it Any. In initial testing, that seemed like it was glossing over specifics, but this is likely the case that drove that.

I don't think any Mapping definition is going to work here and I'm pretty sure can't do the parameterized protocol like we did for ParamsType. We may need to accept json is Any in what we can represent with Python's current type system. I'll put this on the list of Known Issues to address in 2.34.1.

After a closer look, Mapping does appear to work specifically because we're only concerned about the value, not the key. We're losing mutability and update we have with dict, but that's not actually needed. json gets passed directly through to json.dumps untouched and we have bytes on the PreparedRequest so post-preparation mutation shouldn't be a concern. Let's try expanding it and hold the Any escape hatch for now.

The primary issue here is explicitly constraining input prior to calling into Requests. If the payload variable is left as is, the type checker can infer things correctly, but explicitly constraining it is what triggers this issue. That's how it slipped through testing.

[markhobson]

Similarly the strict type hint for json causes problems when serialising with Pydantic. For example:

json = my_model.model_dump()
response = session.post("/my-url", json=json)

model_dump returns dict[str, Any] which is too lax for Mypy:

error: Argument "json" to "post" of "Session" has incompatible type "dict[str, Any]"; expected "JsonType"  [arg-type]

[nateprewitt]

Thanks for another data point, @markhobson. I think the comment above should handle that case as well. If you'd like to check against #7436, that's the current patch proposal. dict[str, Any] should satisfy the Mapping constraint from a quick local test.

[markhobson]

Thanks @nateprewitt. I tried the PR and it does indeed work for dict[str, Any], although I'm also doing something a bit different:

json = [my_model.model_dump() for my_model in my_models]
response = session.post("/my-url", json=json)

So json now becomes list[dict[str, Any]] which still fails the type check.

[nateprewitt]

@markhobson It's the same mutability issue for list as dict. I believe Sequence solves this the same way Mapping does in this case. I'll update the PR in the next few minutes if you have a moment to test after that.

[markhobson]

@nateprewitt Thanks, I've signed off now but I'll be able to try tomorrow.

[markhobson]

@nateprewitt Works for me, thanks for your help!