docs/patterns/streaming.rst - main - githubmirror/flask

docs/patterns/streaming.rst
100 строк3 KB
David Lord
Merge branch 'stable'
04 мар 2026, 18:36
04 мар 2026, 18:363a9d54f
Streaming Contents
==================

Sometimes you want to send an enormous amount of data to the client, much
more than you want to keep in memory.  When you are generating the data on
the fly though, how do you send that back to the client without the
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
-----------

This is a basic view function that generates a lot of CSV data on the fly.
The trick is to have an inner function that uses a generator to generate
data and to then invoke that function and pass it to a response object::

    @app.route('/large.csv')
    def generate_large_csv():
        def generate():
            for row in iter_all_rows():
                yield f"{','.join(row)}\n"
        return generate(), {"Content-Type": "text/csv"}

Each ``yield`` expression is directly sent to the browser.  Note though
that some WSGI middlewares might break streaming, so be careful there in
debug environments with profilers and other things you might have enabled.

Streaming from Templates
------------------------

The Jinja template engine supports rendering a template piece by
piece, returning an iterator of strings. Flask provides the
:func:`~flask.stream_template` and :func:`~flask.stream_template_string`
functions to make this easier to use.

.. code-block:: python

    from flask import stream_template

    @app.get("/timeline")
    def timeline():
        return stream_template("timeline.html")

The parts yielded by the render stream tend to match statement blocks in
the template.


Streaming with Context
----------------------

The :data:`.request` proxy will not be active while the generator is
running, because the app has already returned control to the WSGI server at that
point. If you try to access ``request``, you'll get a ``RuntimeError``.

If your generator function relies on data in ``request``, use the
:func:`.stream_with_context` wrapper. This will keep the request context active
during the generator.

.. code-block:: python

    from flask import stream_with_context, request
    from markupsafe import escape

    @app.route('/stream')
    def streamed_response():
        def generate():
            yield '<p>Hello '
            yield escape(request.args['name'])
            yield '!</p>'
        return stream_with_context(generate())

It can also be used as a decorator.

.. code-block:: python

    @stream_with_context
    def generate():
        ...

    return generate()

The :func:`~flask.stream_template` and
:func:`~flask.stream_template_string` functions automatically
use :func:`~flask.stream_with_context` if a request is active.