From 2c4849defeda74c191c35c4b1997547b1aae425e Mon Sep 17 00:00:00 2001 From: Alex Chan Date: Mon, 23 Oct 2017 08:30:35 +0100 Subject: [PATCH 1/4] Add something to the docs about hooks on Session() --- docs/user/advanced.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst index 613df205..443b43e9 100644 --- a/docs/user/advanced.rst +++ b/docs/user/advanced.rst @@ -458,6 +458,15 @@ Let's print some request method arguments at runtime:: http://httpbin.org +You can also assign hooks to a ``Session`` instance. The hook will then be +called on every request made to the session. For example:: + + >>> s = requests.Session() + >>> s.hooks = dict(response=print_url) + >>> s.get('http://httpbin.org') + http://httpbin.org + + .. _custom-auth: Custom Authentication From 87f3b0a5595d875515de15927e1d2803dbfda73c Mon Sep 17 00:00:00 2001 From: Alex Chan Date: Mon, 23 Oct 2017 13:25:31 +0100 Subject: [PATCH 2/4] Switch to using dict literals, it's 2017 --- docs/user/advanced.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst index 443b43e9..93f86baa 100644 --- a/docs/user/advanced.rst +++ b/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. @@ -454,7 +454,7 @@ anything, nothing else is effected. 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 @@ -462,7 +462,7 @@ You can also assign hooks to a ``Session`` instance. The hook will then be called on every request made to the session. For example:: >>> s = requests.Session() - >>> s.hooks = dict(response=print_url) + >>> s.hooks['response'].append(print_url) >>> s.get('http://httpbin.org') http://httpbin.org From 40c5a8b0c28e2756e83ecfab0160ca3be37391e1 Mon Sep 17 00:00:00 2001 From: Alex Chan Date: Mon, 23 Oct 2017 13:25:46 +0100 Subject: [PATCH 3/4] Clarify that a Session can have multiple hooks --- docs/user/advanced.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst index 93f86baa..c24f6e5b 100644 --- a/docs/user/advanced.rst +++ b/docs/user/advanced.rst @@ -458,8 +458,8 @@ Let's print some request method arguments at runtime:: http://httpbin.org -You can also assign hooks to a ``Session`` instance. The hook will then be -called on every request made to the session. For example:: +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) @@ -467,6 +467,9 @@ called on every request made to the session. For example:: http://httpbin.org +A ``Session`` can have multiple hooks, which will be called in the order +they are added. + .. _custom-auth: Custom Authentication From c5ed41e00a2010fc251ed5655d9f1923c345878a Mon Sep 17 00:00:00 2001 From: Alex Chan Date: Tue, 24 Oct 2017 07:27:55 +0100 Subject: [PATCH 4/4] Add an example of two hooks --- docs/user/advanced.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst index c24f6e5b..587b3fdc 100644 --- a/docs/user/advanced.rst +++ b/docs/user/advanced.rst @@ -452,12 +452,24 @@ 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={'response': print_url}) http://httpbin.org +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::