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 a few examples:
>>> 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 therequest
method of the Session.Likewise, we override the
prepare_request
method so you can construct a PreparedRequest in the same way:>>> from requests import Request >>> from requests_toolbelt import sessions >>> s = sessions.BaseUrlSession( ... base_url='https://example.com/resource/') >>> request = Request(method='GET', url='sub-resource/') >>> prepared_request = s.prepare_request(request) >>> r = s.send(prepared_request) >>> print(r.request.url) https://example.com/resource/sub-resource
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 onurllib.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.
- prepare_request(request, *args, **kwargs)¶
Prepare the request after generating the complete URL.
- 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¶