1treq: High-level Twisted HTTP Client API
2========================================
3
4Release v\ |release| (:doc:`What's new? <changelog>`).
5
6`treq <https://pypi.org/project/treq>`_ depends on a recent Twisted and functions on Python 2.7 and Python 3.3+ (including PyPy).
7
8Why?
9----
10
11`requests`_ by Kenneth Reitz is a wonderful library.
12I want the same ease of use when writing Twisted applications.
13treq is not of course a perfect clone of `requests`_.
14I 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 :class:`twisted.web.client.Agent` on which treq is based.
15
16.. _requests: https://requests.readthedocs.io/en/master/
17.. _Twisted: https://twistedmatrix.com/
18
19Quick Start
20-----------
21
22Installation
23
24.. code-block:: console
25
26    $ pip install treq
27
28GET
29+++
30
31.. literalinclude:: examples/basic_get.py
32    :pyobject: main
33
34Full example: :download:`basic_get.py <examples/basic_get.py>`
35
36POST
37++++
38
39.. literalinclude:: examples/basic_post.py
40    :pyobject: main
41
42Full example: :download:`basic_post.py <examples/basic_post.py>`
43
44
45Why not 100% requests-alike?
46----------------------------
47
48Initially 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 :class:`~twisted.internet.defer.Deferred`.
49
50Over 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`_.
51
52With 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.
53
54
55Feature Parity with Requests
56----------------------------
57
58Even though mimicking the `requests`_ API is not a goal, supporting most of its features is.
59Here is a list of `requests`_ features and their status in treq.
60
61+----------------------------------+----------+----------+
62|                                  | requests |   treq   |
63+----------------------------------+----------+----------+
64| International Domains and URLs   | yes      | yes      |
65+----------------------------------+----------+----------+
66| Keep-Alive & Connection Pooling  | yes      | yes      |
67+----------------------------------+----------+----------+
68| Sessions with Cookie Persistence | yes      | yes      |
69+----------------------------------+----------+----------+
70| Browser-style SSL Verification   | yes      | yes      |
71+----------------------------------+----------+----------+
72| Basic Authentication             | yes      | yes      |
73+----------------------------------+----------+----------+
74| Digest Authentication            | yes      | no       |
75+----------------------------------+----------+----------+
76| Elegant Key/Value Cookies        | yes      | yes      |
77+----------------------------------+----------+----------+
78| Automatic Decompression          | yes      | yes      |
79+----------------------------------+----------+----------+
80| Unicode Response Bodies          | yes      | yes      |
81+----------------------------------+----------+----------+
82| Multipart File Uploads           | yes      | yes      |
83+----------------------------------+----------+----------+
84| Connection Timeouts              | yes      | yes      |
85+----------------------------------+----------+----------+
86| HTTP(S) Proxy Suport             | yes      | no       |
87+----------------------------------+----------+----------+
88| .netrc support                   | yes      | no       |
89+----------------------------------+----------+----------+
90| Python 2.7                       | yes      | yes      |
91+----------------------------------+----------+----------+
92| Python 3.x                       | yes      | yes      |
93+----------------------------------+----------+----------+
94
95Table of Contents
96-----------------
97
98.. toctree::
99    :maxdepth: 3
100
101    howto
102    testing
103    api
104    changelog
105
106Indices and tables
107==================
108
109* :ref:`genindex`
110* :ref:`modindex`
111* :ref:`search`
112