Clarification of keep-alive behavior.

The existing behavior was a little opaque for me--I was making a PUT request which returned a HTTP 204 with a 0-byte body. I was never reading the body and was wondering why my connections were not being reused.

diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst
index e1b7d14..9d1a943 100644 (file)
--- a/docs/user/advanced.rst
+++ b/docs/user/advanced.rst
@@ -80,6 +80,8 @@ Keep-Alive
 
 Excellent news — thanks to urllib3, keep-alive is 100% automatic within a session! Any requests that you make within a session will automatically reuse the appropriate connection!
 
+Note that connections are only released back to the pool for reuse once all body data has been read; be sure to either set ``prefetch`` to ``True`` or read the ``content`` property of the ``Response`` object.
+
 If you'd like to disable keep-alive, you can simply set the ``keep_alive`` configuration to ``False``::
 
     s = requests.session()