From f53aed16111903d4f1fcce204e4e7a6f1fc09ee9 Mon Sep 17 00:00:00 2001 From: Cory Benfield Date: Sat, 8 Jun 2013 11:09:39 +0100 Subject: [PATCH] Document blocking calls. --- docs/user/advanced.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst index a69a140..ffcb777 100644 --- a/docs/user/advanced.rst +++ b/docs/user/advanced.rst @@ -268,6 +268,8 @@ Then, we can make a request using our Pizza Auth:: >>> requests.get('http://pizzabin.org/admin', auth=PizzaAuth('kenneth')) +.. _streaming-requests + Streaming Requests ------------------ @@ -574,3 +576,19 @@ a good start would be to subclass the ``requests.adapters.BaseAdapter`` class. .. _`described here`: http://kennethreitz.org/exposures/the-future-of-python-http .. _`urllib3`: https://github.com/shazow/urllib3 +Blocking Or Non-Blocking? +------------------------- + +With the default Transport Adapter in place, Requests does not provide any kind +of non-blocking IO. The ``Response.content`` property will block until the +entire response has been downloaded. If you require more granularity, the +streaming features of the library (see :ref:`streaming-requests`) allow you to +retrieve smaller quantities of the response at a time. However, these calls +will still block. + +If you are concerned about the use of blocking IO, there are lots of projects +out there that combine Requests with one of Python's asynchronicity frameworks. +Two excellent examples are `grequests`_ and `requests-futures`_. + +.. _`grequests`: https://github.com/kennethreitz/grequests +.. _`requests-futures`: https://github.com/ross/requests-futures -- 2.34.1