Document Response.iter_lines() reentrancy issues

diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst
index ed990666dcb08e3dc4304ef2f78ddbba0396037f..a2fe653b579ab3227a2ef2e6c5db218d27da7629 100644 (file)
--- a/docs/user/advanced.rst
+++ b/docs/user/advanced.rst
@@ -399,6 +399,19 @@ set ``stream`` to ``True`` and iterate over the response with
         if line:
             print(json.loads(line))
 
+.. warning::
+
+    :class:`~requests.Response.iter_lines()` is not reentrant safe.
+    Calling this method multiple times causes some of the received data
+    being lost. In case you need to call it from multiple places, use
+    the resulting iterator object instead::
+
+        lines = r.iter_lines()
+        # Save the first line for later or just skip it
+        first_line = next(lines)
+        for line in lines:
+            print(line)
+
 .. _proxies:
 
 Proxies

diff --git a/requests/models.py b/requests/models.py
index 4b2648f6c6267e938e9d15f0ad9f1750145e0772..ce1eb40ea84612491fac3c04dacbe2b3e98caf04 100644 (file)
--- a/requests/models.py
+++ b/requests/models.py
@@ -688,6 +688,8 @@ class Response(object):
         """Iterates over the response data, one line at a time.  When
         stream=True is set on the request, this avoids reading the
         content at once into memory for large responses.
+
+        .. note:: This method is not reentrant safe.
         """
 
         pending = None