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
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
|
treq: High-level Twisted HTTP Client API
========================================
Release v\ |release| (:doc:`What's new? <changelog>`).
`treq <https://pypi.org/project/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 :class:`twisted.web.client.Agent` on which treq is based.
.. _requests: https://requests.readthedocs.io/en/master/
.. _Twisted: https://twistedmatrix.com/
Quick Start
-----------
Installation
.. code-block:: console
$ pip install treq
GET
+++
.. literalinclude:: examples/basic_get.py
:pyobject: main
Full example: :download:`basic_get.py <examples/basic_get.py>`
POST
++++
.. literalinclude:: examples/basic_post.py
:pyobject: main
Full example: :download:`basic_post.py <examples/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 :class:`~twisted.internet.defer.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 Support | yes | no |
+----------------------------------+----------+----------+
| .netrc support | yes | no |
+----------------------------------+----------+----------+
| Python 3.x | yes | yes |
+----------------------------------+----------+----------+
Table of Contents
-----------------
.. toctree::
:maxdepth: 3
howto
testing
api
changelog
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
|
