Improving documentation/behavior for event hooks

[K900]

Right now (at least looking at https://www.python-httpx.org/advanced/#event-hooks) it's not really specified whether request/response hooks are allowed to modify the request/response objects, or whether that's actually useful.

Specifically, for response objects, it says

Called once the response has been returned.

Which can be interpreted in a way that does not accurately reflect the current behavior (response being returned from the client.request method vs. response being returned from the server).

If being able to modify requests/responses is intentional, it's probably a good idea to make that clear in the documentation and provide some examples. If it's not, then maybe it's better to enforce that in the code.

[tomchristie]

Good question.

The request hooks:

https://github.com/encode/httpx/blob/master/httpx/_client.py#L902-L903

And response hooks:

https://github.com/encode/httpx/blob/master/httpx/_client.py#L882-L883

Both simply pass the request or response instance to the function.

To the extent that request/response instances have some mutable aspects, you could alter some bits of them in the function as a side-effect. For instance:

def hook(request):
    request.headers['X-Custom'] = '...'

That's not particularly an intentional design feature, and I have considered if we'd do better with headers being an immutable data structure or not. (Although even if they were, it'd still be fiddly to make the entire request instance properly immutable.)

So 🤷‍♂️

[K900]

I've actually seen the source code, and currently have some code that uses this property in production, specifically to forward tracing info (i.e. request.headers['X-Trace-ID'] = get_trace_id_from_somewhere()). My question was more about documentation and whether this is something that you want to work (read: whether we should rely on this long term or find another way).

[tomchristie]

Not planning on changing that for 1.0, and we wouldn't be making API breaking changes in the 1.x series.
So, yes, that's a perfectly sensible usage.

[K900]

Appreciate the response! Would you be interested in a patch that adds an example of this kind of usage to the documentation?

[tomchristie]

Sure thing.

[K900]

Posted as #1645