Event hooks

[tomchristie]

Based on #1215 but addressing review comments from @florimondmanca.

Minor API change here is that hooks must now be set as a list of callables, and do not accept the shorthand "set a single callable" style.

Closes #790

Valid examples:

client = httpx.Client()
assert dict(client.event_hooks) == {'request': [], 'response': []}

client.event_hooks['request'] = [some_callable]
assert dict(client.event_hooks) == {'request': [some_callable], 'response': []}

client.event_hooks['request'].append(some_other_callable)
assert dict(client.event_hooks) == {'request': [some_callable, some_other_callable], 'response': []}

client.event_hooks['request'] = []
assert dict(client.event_hooks) == {'request': [], 'response': []}

There's probably marginally more scope for accidentally breaking things than in #1215 (Eg. del client.event_hooks['request'] would end up causing a failure, as would client.event_hooks['request'] = some_callable) but on the flip side it's a bit simpler without the EventHooks mapping structure.

In either case I'm happy enough with this take, since if we did ever later decide to add the extra structure in #1215, then we could still choose to do so, since it would be backwards compatible with this slightly more minimal approach.

Rendered docs...

[tomchristie]

Here's the behaviour we'll want for event hooks...

• request - Called exactly once, with callback(request). We want the fully prepared request at this point, including any auth headers.
• auth - Usually not called, except for multiple auth flows, where it's called with callback(response, request).
• redirect - Called for redirects, with callback(response, request).
• response - Called exactly once, with callback(response).

That'd give us a nice symmetry where we always end up with the same number of request/response arguments across the full set of callbacks.

The only possible alternative I could see to that would be to have redirect and auth smooshed down into a single case. (Probably still just labelled redirect) since you probably always want to handle the "multiple requests got made" in the same way.

[tomchristie]

Prompting me to think that we've kinda got our send_handling_auth and send_handling_redirects around the wrong way, really.

[tomchristie]

@florimondmanca 🙏 😁

[florimondmanca]

@tomchristie Im generally okay with these changes and approch, assuming we're clear enough that we will want support for additional hooks than requests and responses.

That said, before committing to this API I'd sure like your opinion on how this interacts with telemetry support, #1264 ? Especially the "per-request context" aspects.

[florimondmanca]

Code looks good! 👍👍