Use Cases¶
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 = open(destination_filename, 'wb')
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 URL-encoded 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 resp.text()
print(content)
print('Single value dictionary')
resp = yield treq.get('http://httpbin.org/get',
params={'foo': 'bar', 'baz': 'bax'})
content = yield resp.text()
print(content)
print('Multi value dictionary')
resp = yield treq.get('http://httpbin.org/get',
params={'foo': ['bar', 'baz', 'bax']})
content = yield resp.text()
print(content)
print('Mixed value dictionary')
resp = yield treq.get('http://httpbin.org/get',
params={'foo': ['bar', 'baz'], 'bax': 'quux'})
content = yield resp.text()
print(content)
print('Preserved query parameters')
resp = yield treq.get('http://httpbin.org/get?foo=bar',
params={'baz': 'bax'})
content = yield resp.text()
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 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:')
print(response.history())
return print_response(response)
d.addCallback(cb)
|
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 cookies()
method.
The object returned by 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: {}'.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)