Accessing streaming Response.encoding early disables callable auto-detection

[Timotty]

Potential issue

For a streaming response with a callable default_encoding, inspecting response.encoding before reading the body permanently caches a provisional UTF-8 fallback. The callable then never runs, and .text depends on property-access order.

Minimal reproduction

import httpx


class Transport(httpx.BaseTransport):
    def handle_request(self, request):
        class Stream(httpx.SyncByteStream):
            def __iter__(self):
                yield "héllo".encode("iso-8859-1")

        return httpx.Response(200, stream=Stream())


with httpx.Client(
    transport=Transport(), default_encoding=lambda data: "iso-8859-1"
) as client:
    with client.stream("GET", "https://example.com/") as response:
        response.read()
        print("read first:", response.encoding, repr(response.text))

    with client.stream("GET", "https://example.com/") as response:
        print("early encoding:", response.encoding)
        response.read()
        print("encoding first:", response.encoding, repr(response.text))

Actual:

read first: iso-8859-1 'héllo'
early encoding: utf-8
encoding first: utf-8 'h�llo'

Expected: once the response is read, the second response should call the detector and decode identically to the first. It seems reasonable to return a provisional UTF-8 fallback before bytes are available without caching it; on subsequent access after .read()/.aread(), call the detector. This would not change incremental iter_text() decoding (which cannot auto-detect without buffering).

httpx/_models.py:652-672, Response.encoding, currently saves self._encoding = encoding or "utf-8" even when the body is not available. Is recalculating after reading in this case compatible with the intended property semantics? I can submit a focused PR with sync/async tests and documentation if approved.

Verified against default-branch commit b5addb64f0161ff6bfe94c124ef76f6a1fba5254, HTTPX 0.28.1, Python 3.12.13 on Windows; searched open/closed issues and PRs for streaming/autodetection/early .encoding access and found no matching report.

AI disclosure: bug discovery assisted by Luna (timotty-responses/luna); reproduction and proposed fix reviewed with OpenCode (GPT-6 Sol). No PR has been published.

[AbdullahTammar]

For callers affected by the early property access, a workaround is to run the detector explicitly after buffering, then assign the encoding before accessing .text:

# detect is the same bytes -> encoding callable passed to the client.
response.read()  # await response.aread() for AsyncClient
response.encoding = detect(response.content) or "utf-8"
text = response.text

Tested on HTTPX 0.28.1 with b'h\xe9llo', an early response.encoding read returning UTF-8, and a detector returning iso-8859-1: the explicit assignment decodes the accented character correctly. This applies to the no-charset case in your reproduction; do not blindly replace a valid server-supplied charset.

If .text has already been accessed, the encoding setter raises ValueError; decode response.content separately instead. This buffers the complete response, so it is not a solution for unbounded incremental streams.

This is a caller-side workaround; the compatibility decision about changing the property's caching behavior still needs maintainer input. HTTPX encoding documentation.