treq: High-level Twisted HTTP Client API

Release v0.2.1.

treq depends on Twisted>=12.1.0 and optionally pyOpenSSL.

All example code depends on Twisted>=12.3.0.

Why?

requests by Kenneth Reitz is a wonderful library. I want the same ease of use when writing Twisted applications. treq is not of course a perfect clone of requests. I have tried to stay true to the do-what-i-mean spirit of the requests API and also kept the API familiar to users of Twisted and twisted.web.client.Agent on which treq is based.

Quick Start

Installation:

pip install treq

GET

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

Full example: basic_get.py

POST

1
2
3
4
5
6
def main(reactor, *args):
    d = treq.post('http://httpbin.org/post',
                  json.dumps({"msg": "Hello!"}),
                  headers={'Content-Type': ['application/json']})
    d.addCallback(print_response)
    return d

Full example: basic_post.py

Why not 100% requests-alike?

Initially when I started off working on treq I thought the API should look exactly like requests except anything that would involve the network would return a Deferred.

Over time while attempting to mimic the requests API it became clear that not enough code could be shared between requests and treq for it to be worth the effort to translate many of the usage patterns from requests.

With the current version of treq I have tried to keep the API simple, yet remain familiar to users of Twisted and its lower-level HTTP libraries.

Feature Parity w/ Requests

Even though mimicing the requests API is not a goal, supporting most of it’s features is. Here is a list of requests features and their status in treq.

  requests treq
International Domains and URLs yes no
Keep-Alive & Connection Pooling yes yes
Sessions with Cookie Persistence yes yes
Browser-style SSL Verification yes yes [1]
Basic Authentication yes yes
Digest Authentication yes no
Elegant Key/Value Cookies yes yes
Automatic Decompression yes yes
Unicode Response Bodies yes yes
Multipart File Uploads yes yes
Connection Timeouts yes yes
.netrc support yes no
Python 2.6 yes yes
Python 2.7 yes yes
Python 3.x yes no
[1]Requires Twisted>=14.0 and service_identity.

Indices and tables