From: Cory Benfield Date: Thu, 16 Jan 2014 08:37:29 +0000 (+0000) Subject: Document contextlib.closing. X-Git-Tag: v2.2.1~5^2 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=476ab203bc00cb57a7be24fb500b95447294ec92;p=services%2Fpython-requests.git Document contextlib.closing. --- 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 ----------