Merge pull request #4352 from alexwlchan/hooks-on-sessions

Add something to the docs about hooks on Session()

docs/user/advanced.rst

@@ -436,7 +436,7 @@ You can assign a hook function on a per-request basis by passing a
 ``{hook_name: callback_function}`` dictionary to the ``hooks`` request
 parameter::
 
-    hooks=dict(response=print_url)
+    hooks={'response': print_url}
 
 That ``callback_function`` will receive a chunk of data as its first
 argument.
@@ -452,12 +452,36 @@ If the callback function returns a value, it is assumed that it is to
 replace the data that was passed in. If the function doesn't return
 anything, nothing else is effected.
 
+::
+
+    def record_hook(r, *args, **kwargs):
+        r.hook_called = True
+        return r
+
 Let's print some request method arguments at runtime::
 
-    >>> requests.get('http://httpbin.org', hooks=dict(response=print_url))
+    >>> requests.get('http://httpbin.org', hooks={'response': print_url})
     http://httpbin.org
     <Response [200]>
 
+You can add multiple hooks to a single request.  Let's call two hooks at once::
+
+    >>> r = requests.get('http://httpbin.org', hooks={'response': [print_url, record_hook]})
+    >>> r.hook_called
+    True
+
+You can also add hooks to a ``Session`` instance.  Any hooks you add will then
+be called on every request made to the session.  For example::
+
+   >>> s = requests.Session()
+   >>> s.hooks['response'].append(print_url)
+   >>> s.get('http://httpbin.org')
+    http://httpbin.org
+    <Response [200]>
+
+A ``Session`` can have multiple hooks, which will be called in the order
+they are added.
+
 .. _custom-auth:
 
 Custom Authentication