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