# 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.