Advanced Usage¶

Session Objects¶

The Session object allows you to persist certain parameters across requests. It also establishes a CookieJar and passes it along to any requests made from the Session instance.

A session object has all the methods of the main Requests API.

Let’s persist some cookies across requests:

with requests.session() as s:

    s.get('http://httpbin.org/cookies/set/sessioncookie/123456789')
    r = s.get("http://httpbin.org/cookies")

    print r.content
    # '{"cookies": {"sessioncookie": "123456789"}}'

Sessions can also be used to provide default data to the request methods:

headers = {'x-test': 'true'}
auth = ('user', 'pass')

with requests.session(auth=auth, headers=headers) as c:

    # both 'x-test' and 'x-test2' are sent
    c.get('http://httpbin.org/headers', header={'x-test2', 'true'})

Event Hooks¶

Requests has a hook system that you can use to manipulate portions of the request process, or signal event handling.

Available hooks:

args:

A dictionary of the arguments being sent to Request().

pre_request:

The Request object, directly before being sent.

post_request:

The Request object, directly after being sent.

response:

The response generated from a Request.

You can assign a hook function on a per-request basis by passing a {hook_name: callback_function} dictionary to the hooks request paramaeter:

hooks=dict(args=print_url)

That callback_function will receive a chunk of data as its first argument.

def print_url(args):
    print args['url']

If an error occurs while executing your callback, a warning is given.

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.

Let’s print some request method arguments at runtime:

>>> requests.get('http://httpbin', hooks=dict(args=print_url))
http://httpbin
<Response [200]>

Let’s hijack some arguments this time with a new callback:

def hack_headers(args):
    if not args[headers]:
        args['headers'] = dict()

    args['headers'].update({'X-Testing': 'True'})

    return args

hooks = dict(args=hack_headers)
headers = dict(yo=dawg)

And give it a try:

>>> requests.get('http://httpbin/headers', hooks=hooks, headers=headers)
{
    "headers": {
        "Content-Length": "",
        "Accept-Encoding": "gzip",
        "Yo": "dawg",
        "X-Forwarded-For": "::ffff:24.127.96.129",
        "Connection": "close",
        "User-Agent": "python-requests.org",
        "Host": "httpbin.org",
        "X-Testing": "True",
        "X-Forwarded-Protocol": "",
        "Content-Type": ""
    }
}

Verbose Logging¶

If you want to get a good look at what HTTP requests are being sent by your application, you can turn on verbose logging.

To do so, just configure Requests with a stream to write to:

>>> requests.settings.verbose = sys.stderr
>>> requests.get('http://httpbin.org/headers')
2011-08-17T03:04:23.380175   GET   http://httpbin.org/headers
<Response [200]>