# Handling Streaming Responses

In addition to receiving responses with `IResponse.deliverBody`.

treq provides a helper function `treq.collect()` which takes a `response`, and a single argument function which will be called with all new data available from the response. Much like `IProtocol.dataReceived`, `treq.collect()` knows nothing about the framing of your data and will simply call your collector function with any data that is currently available.

Here is an example which simply a `file` object’s write method to `treq.collect()` to save the response body to a file.

    1
    2
    3
    4
    5
    6

    def download_file(reactor, url, destination_filename):
        destination = file(destination_filename, 'w')
        d = treq.get(url)
        d.addCallback(treq.collect, destination.write)
        d.addBoth(lambda _: destination.close())
        return d

Full example: `download_file.py`

# Query Parameters

`treq.request()` supports a `params` keyword argument which will be urlencoded and added to the `url` argument in addition to any query parameters that may already exist.

The `params` argument may be either a `dict` or a `list` of `(key, value)` tuples.

If it is a `dict` then the values in the dict may either be a `str` value or a `list` of `str` values.

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31

    @inlineCallbacks
    def main(reactor):
        print 'List of tuples'
        resp = yield treq.get('http://httpbin.org/get',
                              params=[('foo', 'bar'), ('baz', 'bax')])
        content = yield treq.content(resp)
        print content

        print 'Single value dictionary'
        resp = yield treq.get('http://httpbin.org/get',
                              params={'foo': 'bar', 'baz': 'bax'})
        content = yield treq.content(resp)
        print content

        print 'Multi value dictionary'
        resp = yield treq.get('http://httpbin.org/get',
                              params={'foo': ['bar', 'baz', 'bax']})
        content = yield treq.content(resp)
        print content

        print 'Mixed value dictionary'
        resp = yield treq.get('http://httpbin.org/get',
                              params={'foo': ['bar', 'baz'], 'bax': 'quux'})
        content = yield treq.content(resp)
        print content

        print 'Preserved query parameters'
        resp = yield treq.get('http://httpbin.org/get?foo=bar',
                              params={'baz': 'bax'})
        content = yield treq.content(resp)
        print content

Full example: `query_params.py`

# Auth

HTTP Basic authentication as specified in RFC 2617 is easily supported by passing an `auth` keyword argument to any of the request functions.

The `auth` argument should be a tuple of the form `('username', 'password')`.

    1
    2
    3
    4
    5
    6
    7

    def main(reactor, *args):
        d = treq.get(
            'http://httpbin.org/basic-auth/treq/treq',
            auth=('treq', 'treq')
        )
        d.addCallback(print_response)
        return d

Full example: `basic_auth.py`

# Redirects

treq handles redirects by default.

The following will print a 200 OK response.

    1
    2
    3
    4
    5
    6

    def main(reactor, *args):
        d = treq.get('http://httpbin.org/redirect/1')
        d.addCallback(print_response)
        return d

    react(main, [])

Full example: `redirects.py`

You can easily disable redirects by simply passing allow_redirects=False to any of the request methods.

    1
    2
    3
    4
    5
    6

    def main(reactor, *args):
        d = treq.get('http://httpbin.org/redirect/1', allow_redirects=False)
        d.addCallback(print_response)
        return d

    react(main, [])

Full example: `disable_redirects.py`

You can even access the complete history of treq response objects by calling the history() method on the the response.

    1
    2
    3
    4
    5
    6
    7
    8
    9

    def main(reactor, *args):
        d = treq.get('http://httpbin.org/redirect/1')

        def cb(response):
            print 'Response history:', response.history()
            return print_response(response)

        d.addCallback(cb)
        return d

Full example: `response_history.py`

# Cookies

Cookies can be set by passing a `dict` or `cookielib.CookieJar` instance via the `cookies` keyword argument. Later cookies set by the server can be retrieved using the `treq.cookies()` function.

The the object returned by `treq.cookies()` supports the same key/value access as requests cookies

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14

    def main(reactor, *args):
        d = treq.get('http://httpbin.org/cookies/set?hello=world')

        def _get_jar(resp):
            jar = resp.cookies()

            print 'The server set our hello cookie to: {0}'.format(jar['hello'])

            return treq.get('http://httpbin.org/cookies', cookies=jar)

        d.addCallback(_get_jar)
        d.addCallback(print_response)

        return d

Full example: `using_cookies.py`

# Agent Customization

treq creates its own twisted.web.client.Agent with reasonable defaults, but you may want to provide your own custom agent. A custom agent can be passed to the various treq request methods using the `agent` keyword argument.

    custom_agent = Agent(reactor, connectTimeout=42)
    treq.get(url, agent=custom_agent)