From 476ab203bc00cb57a7be24fb500b95447294ec92 Mon Sep 17 00:00:00 2001 From: Cory Benfield Date: Thu, 16 Jan 2014 08:37:29 +0000 Subject: [PATCH] Document contextlib.closing. --- docs/user/advanced.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst index 4e05303..f5e8e59 100644 --- a/docs/user/advanced.rst +++ b/docs/user/advanced.rst @@ -199,6 +199,20 @@ At this point only the response headers have been downloaded and the connection You can further control the workflow by use of the :class:`Response.iter_content ` and :class:`Response.iter_lines ` methods. Alternatively, you can read the undecoded body from the underlying urllib3 :class:`urllib3.HTTPResponse ` at :class:`Response.raw `. +If you set ``stream`` to ``True`` when making a request, Requests cannot +release the connection back to the pool unless you consume all the data or call +:class:`Response.close `. This can lead to +inefficiency with connections. If you find yourself partially reading request +bodies (or not reading them at all) while using ``stream=True``, you should +consider using ``contextlib.closing`` (`documented here`_), like this:: + + from contextlib import closing + + with closing(requests.get('http://httpbin.org/get', stream=True)) as r: + # Do things with the response here. + +.. _`documented here`: http://docs.python.org/2/library/contextlib.html#contextlib.closing + Keep-Alive ---------- -- 2.34.1