Merge branch 'stable'

Author: davidism

docs/patterns/streaming.rst

@@ -8,6 +8,21 @@ roundtrip to the filesystem?
 
 The answer is by using generators and direct responses.
 
+HTTP Response Behavior
+----------------------
+
+**Headers cannot be changed after the streaming response starts.**
+
+When using streaming, it's important to be aware of the order than an HTTP
+response is sent. All headers must be sent first, then the body. More headers
+cannot be sent after the body has begun. Therefore, you must make sure all
+headers are set before starting the response, outside the generator.
+
+In particular, if the generator will access ``session``, be sure to do so in the
+view as well so that the ``Vary: cookie`` header will be set. Do not modify the
+session in the generator, as the ``Set-Cookie`` header will already be sent.
+
+
 Basic Usage
 -----------
 

docs/templating.rst

@@ -251,5 +251,11 @@ functions to make this easier to use.
         return stream_template("timeline.html")
 
 These functions automatically apply the
-:func:`~flask.stream_with_context` wrapper if a request is active, so
-that it remains available in the template.
+:func:`~flask.stream_with_context` wrapper if a request is active, so that
+:data:`.request`, :data:`.session`, and :data:`.g` remain available in the
+template.
+
+More headers cannot be sent after the body has begun. Therefore, you must
+make sure all headers are set before starting the response. In particular,
+if the template will access ``session``, be sure to do so in the view as
+well so that the ``Vary: cookie`` header will be set.

src/flask/helpers.py

@@ -68,6 +68,18 @@ def stream_with_context(
     available, even though at the point the generator runs the request context
     will typically have ended.
 
+    .. warning::
+
+        Due to the following caveat, it is often safer to pass the data you
+        need as arguments to the generator, rather than relying on the context
+        objects.
+
+    More headers cannot be sent after the body has begun. Therefore, you must
+    make sure all headers are set before starting the response. In particular,
+    if the generator will access ``session``, be sure to do so in the view as
+    well so that the ``Vary: cookie`` header will be set. Do not modify the
+    session in the generator, as the ``Set-Cookie`` header will already be sent.
+
     Use it as a decorator on a generator function:
 
     .. code-block:: python