Quickstart sets r.encoding after r.text, which raises ValueError

[HighnessAtharva]

Following the quickstart in order in one Python session, the "Text Encoding" section reads r.text and then shows:

>>> r.encoding = 'ISO-8859-1'

On the current release this raises:

ValueError: Setting encoding after `text` has been accessed is not allowed.

The setter's docstring documents that rule, but the quickstart does not, so a reader who runs the snippets in order hits it. A one-line change would fix it: "If you need to override the standard behaviour, set the encoding before you access r.text." I can open a PR with that wording if it helps.

Found by running the quickstart in a clean python:3.11-slim container with FirstRun.

[Benjyyy16]

Confirmed on httpx 0.28.1. It's intentional behaviour, the quickstart just doesn't mention it.

Why: the first access to r.text decodes r.content and caches the result in r._text. The encoding setter refuses to change after that (if hasattr(self, "_text"): raise ValueError(...)), because the cached text would no longer match the new encoding.

>>> r = httpx.Response(200, content="héllo".encode(), headers={"content-type": "text/plain"})
>>> r.text
'héllo'
>>> r.encoding = "ISO-8859-1"
ValueError: Setting encoding after `text` has been accessed is not allowed.

Workarounds, depending on what you need:

1. Set it before reading .text:

   r = httpx.get(url)
   r.encoding = "ISO-8859-1"
   r.text

2. If .text was already read, decode the bytes yourself (always works, no cache involved):

   r.content.decode("ISO-8859-1")

3. To apply it to every response, configure the client instead of the response:

   client = httpx.Client(default_encoding="ISO-8859-1")  # or a callable, e.g. charset_normalizer-based

   default_encoding is only used when the server doesn't send a charset.

So the doc fix you propose ("set the encoding before you access r.text") matches the actual contract; reordering the quickstart so the r.encoding = ... snippet runs on a fresh response would also avoid the error when following it top to bottom.