diff --git a/docs/api.rst b/docs/api.rst index 7225a837..8d277c81 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -81,6 +81,8 @@ Status Code Lookup >>> requests.codes['\o/'] 200 +.. _api-cookies: + Cookies ~~~~~~~ diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst index 080ca24b..8466a4af 100644 --- a/docs/user/advanced.rst +++ b/docs/user/advanced.rst @@ -45,6 +45,24 @@ Any dictionaries that you pass to a request method will be merged with the session-level values that are set. The method-level parameters override session parameters. +Note, however, that method-level parameters will *not* be persisted across +requests, even if using a session. This example will only send the cookies +with the first request, but not the second:: + + s = requests.Session() + r = s.get('http://httpbin.org/cookies', cookies={'from-my': 'browser'}) + print(r.text) + # '{"cookies": {"from-my": "browser"}}' + + r = s.get('http://httpbin.org/cookies') + print(r.text) + # '{"cookies": {}}' + + +If you want to manually add cookies to your session, use the +:ref:`Cookie utility functions ` to manipulate +:attr:`Session.cookies `. + Sessions can also be used as context managers:: with requests.Session() as s: