Specialized Sessions

The toolbelt provides specialized session classes in the requests_toolbelt.sessions module.

class requests_toolbelt.sessions.BaseUrlSession(base_url=None)

A Session with a URL that all requests will use as a base.

Let’s start by looking at an example:

>>> from requests_toolbelt import sessions
>>> s = sessions.BaseUrlSession(
...     base_url='https://example.com/resource/')
>>> r = s.get('sub-resource/' params={'foo': 'bar'})
>>> print(r.request.url)
https://example.com/resource/sub-resource/?foo=bar

Our call to the get method will make a request to the URL passed in when we created the Session and the partial resource name we provide.

We implement this by overriding the request method so most uses of a Session are covered. (This, however, precludes the use of PreparedRequest objects).

Note

The base URL that you provide and the path you provide are very important.

Let’s look at another similar example

>>> from requests_toolbelt import sessions
>>> s = sessions.BaseUrlSession(
...     base_url='https://example.com/resource/')
>>> r = s.get('/sub-resource/' params={'foo': 'bar'})
>>> print(r.request.url)
https://example.com/sub-resource/?foo=bar

The key difference here is that we called get with /sub-resource/, i.e., there was a leading /. This changes how we create the URL because we rely on urllib.parse.urljoin.

To override how we generate the URL, sub-class this method and override the create_url method.

Based on implementation from https://github.com/kennethreitz/requests/issues/2554#issuecomment-109341010

create_url(url)

Create the URL based off this partial path.

request(method, url, *args, **kwargs)

Send the request after generating the complete URL.

BaseUrlSession

New in version 0.7.0.

Many people have written Session subclasses that allow a “base URL” to be specified so all future requests need not specify the complete URL. To create one simplified and easy to configure version, we’ve added the requests_toolbelt.sessions.BaseUrlSession object to the Toolbelt.

class requests_toolbelt.sessions.BaseUrlSession(base_url=None)

A Session with a URL that all requests will use as a base.

Let’s start by looking at an example:

>>> from requests_toolbelt import sessions
>>> s = sessions.BaseUrlSession(
...     base_url='https://example.com/resource/')
>>> r = s.get('sub-resource/' params={'foo': 'bar'})
>>> print(r.request.url)
https://example.com/resource/sub-resource/?foo=bar

Our call to the get method will make a request to the URL passed in when we created the Session and the partial resource name we provide.

We implement this by overriding the request method so most uses of a Session are covered. (This, however, precludes the use of PreparedRequest objects).

Note

The base URL that you provide and the path you provide are very important.

Let’s look at another similar example

>>> from requests_toolbelt import sessions
>>> s = sessions.BaseUrlSession(
...     base_url='https://example.com/resource/')
>>> r = s.get('/sub-resource/' params={'foo': 'bar'})
>>> print(r.request.url)
https://example.com/sub-resource/?foo=bar

The key difference here is that we called get with /sub-resource/, i.e., there was a leading /. This changes how we create the URL because we rely on urllib.parse.urljoin.

To override how we generate the URL, sub-class this method and override the create_url method.

Based on implementation from https://github.com/kennethreitz/requests/issues/2554#issuecomment-109341010

create_url(url)

Create the URL based off this partial path.

request(method, url, *args, **kwargs)

Send the request after generating the complete URL.