treq: High-level Twisted HTTP Client API

Release v21.1.0 (What’s new?).

treq depends on a recent Twisted and functions on Python 2.7 and Python 3.3+ (including PyPy).

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

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

Full example: basic_get.py

POST

def main(reactor):
    d = treq.post("https://httpbin.org/post",
                  data={"form": "data"})
    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 with Requests

Even though mimicking the requests API is not a goal, supporting most of its features is. Here is a list of requests features and their status in treq.

requests

treq

International Domains and URLs

yes

yes

Keep-Alive & Connection Pooling

yes

yes

Sessions with Cookie Persistence

yes

yes

Browser-style SSL Verification

yes

yes

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

HTTP(S) Proxy Suport

yes

no

.netrc support

yes

no

Python 2.7

yes

yes

Python 3.x

yes

yes

Indices and tables