Headers.encoding is cached from the raw bytes and never invalidated, so non-ASCII writes and reads fail after a read

[simpleqt]

Headers uses self._encoding for two different things — the explicitly configured encoding, and the cache for the encoding it lazily determines from the raw header bytes — and never invalidates that cache when the headers change. That makes two valid operations fail depending on access history:

import httpx

headers = httpx.Headers({"Custom": "Example"})
headers.encoding                                        # 'ascii' - determined and cached here
headers["Code-Point"] = "Code point: ☃"
# UnicodeEncodeError: 'ascii' codec can't encode character '\u2603' in position 12

fresh = httpx.Headers({"Custom": "Example"})
fresh["Code-Point"] = "Code point: ☃"                    # works: the utf-8 fallback from #820

headers = httpx.Headers({"Custom": "Example"})
headers.update([(b"Code-Point", "Code point: ☃".encode("utf-8"))])
headers.raw                                             # the right bytes are stored
headers["Code-Point"]
# UnicodeDecodeError: 'ascii' codec can't decode byte 0xe2 in position 12: ordinal not in range(128)

Byte keys and values are a supported HeaderTypes, and the utf-8/iso-8859-1 fallback in the encoding property exists exactly for them, so an object whose own raw is correct should not be unable to read it back. copy() also pins the determined encoding onto the copy, so the same gets inherited.

Where it comes from, in the current code:

• httpx/_models.py:183 — the encoding property writes the determined encoding back into self._encoding.
• httpx/_models.py:309-310 — __setitem__ encodes with self._encoding or "utf-8", i.e. the fallback only works while _encoding is still None.
• httpx/_models.py:279 — update() first caches the pre-update encoding of the existing headers through key in self → __contains__ → self.encoding.
• httpx/_models.py:282 — copy() carries the determined value over.

What I'd expect: _encoding keeps only an explicitly configured encoding, the determined one is cached separately, and the determined value is re-computed after update(), __setitem__ and __delitem__.

I have a fix for this with a regression test for both cases, and can open a pull request if you'd consider it.

[kasparovabi]

Same result here on httpx 0.28.1 (python:3.13-slim). Both of your snippets fail exactly as shown. The cached ascii also shows up in ordinary client use, after a single request or after a membership test in an event hook:

import httpx

def handler(request):
    return httpx.Response(200)

client = httpx.Client(headers={"Custom": "Example"}, transport=httpx.MockTransport(handler))
client.get("http://t/")
client.headers["X"] = "☃"
# UnicodeEncodeError: 'ascii' codec can't encode character '☃' in position 0

def hook(request):
    if "authorization" not in request.headers:   # __contains__ caches 'ascii'
        request.headers["X-Name"] = "José"

httpx.Client(transport=httpx.MockTransport(handler), event_hooks={"request": [hook]}).get("http://t/")
# UnicodeEncodeError: 'ascii' codec can't encode character '\xe9' in position 3

Until a fix lands, pinning the encoding explicitly avoids it, because then nothing is left for the lazy property to cache:

headers = httpx.Headers({"Custom": "Example"}, encoding="utf-8")
# or, on an existing object (client.headers, request.headers in a hook):
request.headers.encoding = "utf-8"

With the encoding pinned, both of your snippets and the event hook above work. Setting the encoding after a bytes update() also lets headers["Code-Point"] decode back to 'Code point: ☃', since the stored bytes were already correct. In the event hook, pinning first and then setting X-Name delivers José to the transport.

One thing to keep in mind about the workaround. With encoding="utf-8" pinned, decoding raw header bytes that are not valid UTF-8 raises instead of falling back to iso-8859-1, so it fits outgoing headers you control better than headers that come back from a server.