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 5f900cf68776e5f771c044e6cdff77d436bed872..32714bd5a2d4a8af7642cdd461831c961eccc735 100644 (file)
--- 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.