Document contextlib.closing.

1 files changed, 14 insertions, 0 deletions

diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst
index 4e05303b..f5e8e59f 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 <requests.Response.iter_content>` and :class:`Response.iter_lines <requests.Response.iter_lines>` methods. Alternatively, you can read the undecoded body from the underlying urllib3 :class:`urllib3.HTTPResponse <urllib3.response.HTTPResponse>` at :class:`Response.raw <requests.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 <requests.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
 ----------