From: K900 Date: Fri, 21 May 2021 09:30:30 +0000 (+0300) Subject: docs: slightly clarify event hooks (#1645) X-Git-Tag: 0.18.2~8 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=776dbb578b1fd69f84c5bf75a80cd74dc823a41c;p=thirdparty%2Fhttpx.git docs: slightly clarify event hooks (#1645) * Be more specific about when the hooks are called * Explicitly mention and demonstrate that hooks are allowed to modify requests See https://github.com/encode/httpx/discussions/1637 --- diff --git a/docs/advanced.md b/docs/advanced.md index 5f900cf6..32714bd5 100644 --- a/docs/advanced.md +++ b/docs/advanced.md @@ -228,10 +228,10 @@ every time a particular type of event takes place. There are currently two event hooks: -* `request` - Called once a request is about to be sent. Passed the `request` instance. -* `response` - Called once the response has been returned. Passed the `response` instance. +* `request` - Called after a request is fully prepared, but before it is sent to the network. Passed the `request` instance. +* `response` - Called after the response has been fetched from the network, but before it is returned to the caller. Passed the `response` instance. -These allow you to install client-wide functionality such as logging and monitoring. +These allow you to install client-wide functionality such as logging, monitoring or tracing. ```python def log_request(request): @@ -255,6 +255,15 @@ def raise_on_4xx_5xx(response): client = httpx.Client(event_hooks={'response': [raise_on_4xx_5xx]}) ``` +The hooks are also allowed to modify `request` and `response` objects. + +```python +def add_timestamp(request): + request.headers['x-request-timestamp'] = datetime.now(tz=datetime.utc).isoformat() + +client = httpx.Client(event_hooks={'request': [add_timestamp]}) +``` + Event hooks must always be set as a **list of callables**, and you may register multiple event hooks for each type of event.