FileField writes into the Mapping given as a file tuple's 4th element

[datrixlab]

FileTypes declares the 4th element of a file tuple as Mapping[str, str]:

Tuple[Optional[str], FileContent, Optional[str], Mapping[str, str]],

but FileField.__init__ binds that element straight to its local headers and then writes into it:

filename, fileobj, content_type, headers = value  # type: ignore
...
if content_type is not None and not has_content_type_header:
    headers["Content-Type"] = content_type

Mapping has no __setitem__, and the mapping belongs to the caller. Three things follow, all reproduced on master (b5addb6):

1. A real Mapping is rejected, though the annotation permits it.

MappingProxyType   -> TypeError: 'mappingproxy' object does not support item assignment
custom Mapping     -> TypeError: 'ROMap' object does not support item assignment

2. A caller's dict is written into.

before: {'Expires': '0'}
after : {'Expires': '0', 'Content-Type': 'image/png'}

3. Reusing one headers mapping across files sends the wrong content type. This is the one that bites silently. After the first file the mapping carries a Content-Type, so has_content_type_header is true for every later file and their own content types are skipped:

shared = {"Expires": "0"}
httpx.Request("POST", "http://x/", files=[
    ("f1", ("logo.png",  b"x", "image/png",        shared)),
    ("f2", ("notes.txt", b"y", "text/plain",       shared)),
    ("f3", ("data.json", b"z", "application/json", shared)),
])

Content-Disposition: form-data; name="f1"; filename="logo.png"
Content-Type: image/png
Content-Disposition: form-data; name="f2"; filename="notes.txt"
Content-Type: image/png          <- wrong
Content-Disposition: form-data; name="f3"; filename="data.json"
Content-Type: image/png          <- wrong

With three independent dicts the same upload is correct, so nothing about the files themselves is at fault.

The 3-tuple branch a few lines above already starts from a fresh dict, so this looks like the 4-tuple branch simply not matching it rather than a deliberate choice.

Fix would be one line — headers = dict(file_headers) — and it also lets the # type: ignore on that unpack go away, since the tuple element stops being assigned to a dict-annotated name. I have that plus three regression tests ready if you would like a PR: the full suite gives the same 28 failures as master on this machine (network/server tests plus one Windows-specific one in test_multipart.py), with the three new tests passing.

[ibam28]

Confirmed — all three behaviors reproduce on current master (FileField.__init__ in httpx/_multipart.py, installed from git today).

The mechanics: the local headers variable is re-bound to the caller's 4th tuple element by filename, fileobj, content_type, headers = value, and then written to here:

if content_type is not None and not has_content_type_header:
    headers["Content-Type"] = content_type

Meanwhile FileTypes (httpx/_types.py) declares that element as Mapping[str, str], so an immutable mapping is type-legal but raises TypeError at request-build time, and a caller-owned dict gets mutated.

On (3), one addition to the report: the later files don't just lose their own content type — they silently render the first file's one:

f1 logo.png  -> Content-Type: image/png   (correct)
f2 notes.txt -> Content-Type: image/png   (should be text/plain)
f3 data.json -> Content-Type: image/png   (should be application/json)

After the first field writes Content-Type into the shared mapping, has_content_type_header is truthy for every later field, so their own content_type values are skipped and the stale header leaks into their parts.

Workaround until this is fixed: give each file its own mapping (dict(shared)).

Minimal fix suggestion: headers = dict(headers) right after unpacking the 4-tuple, before the has_content_type_header check. That keeps the Mapping[str, str] annotation honest and fixes all three cases at once — the three scenarios in this report would make good regression tests.

[VimalN2005]

"Hi! I've implemented and tested the headers = dict(file_headers) fix locally along with the 3 regression tests (covering MappingProxyType, non-mutation of caller dict, and multi-file shared headers). All tests pass with full coverage and zero side-effects. I'm ready to open a PR for this — should I go ahead?"