Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 72 ยท Routing and Views

Streaming Responses and Server-Sent Events

Stream data from Flask with generators, stream_with_context, large CSV downloads and Server-Sent Events. Learn the SSE format, the browser EventSource API and what to watch out for in production.

Normally a view builds the whole response in memory and returns it. For a small page that is perfect. But what if you are exporting a million rows to CSV, sending a large file, or showing the progress of a long job? Building everything first wastes memory and makes the user stare at a blank screen. With a streaming response Flask starts sending as soon as the first piece is ready and keeps going while you produce the rest.

In this lesson you will return generators, keep the request context alive with stream_with_context, stream a CSV export, and build live updates with Server-Sent Events (SSE), a simple one-way channel from server to browser.

A generator is a response

If a view returns a generator (or any iterator), Flask wraps it in a streaming Response and sends every yielded string as it appears. You can also build the response explicitly with Response(generator(), mimetype="...").

Python Return a generator

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Look at the header check: a streamed response has no Content-Length, because Flask does not know the size in advance. Over HTTP/1.1 the server then uses chunked transfer encoding; you do not need to do anything.

stream_with_context

The generator runs after your view function has returned, while the response is being written. By then Flask has already torn down the request context, so touching request or session inside the generator raises "working outside of request context". Wrap the generator with stream_with_context to keep the context alive for as long as it runs.

Python Using request inside a generator

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Reading what you need before creating the generator is the cleanest approach. Use stream_with_context when the generator must keep using request, session, g or the database session from Flask-SQLAlchemy.

Streaming a large CSV export

A typical use: an admin downloads a report with many rows. Writing it all into a string would hold every row in memory; a generator holds one row at a time. The trick is to reuse one csv.writer over a tiny in-memory buffer and yield whatever it wrote.

Python Stream a CSV download

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

For real database data, pair this with yield_per or a server-side cursor so the driver also streams. Flask can only stream what your code hands it lazily.

Plain file downloads already stream: send_file and send_from_directory read the file in pieces, support range requests, and set Content-Length for you (see file uploads).

Server-Sent Events

SSE is a standard way for a server to push text events to a browser over an ordinary HTTP response that never ends. It is simpler than WebSockets (see Flask-SocketIO): one direction only, plain HTTP, automatic reconnection built into the browser.

The format is text with a very small grammar. Each event is a few field: value lines ending with a blank line:

TEXT
event: progress
id: 7
data: {"percent": 70}

  • data: is the payload (several data: lines are joined with newlines).
  • event: names the event; if omitted the browser fires a generic message event.
  • id: lets the browser say where it stopped (Last-Event-ID header) when it reconnects.
  • A line starting with : is a comment, often used as a heartbeat to keep proxies from closing an idle connection.

The response must have Content-Type: text/event-stream and should not be cached.

Python An SSE endpoint

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

X-Accel-Buffering: no asks nginx not to buffer the response; without it events may arrive in one lump at the end. Many proxies need this or similar configuration.

The browser side

The browser's built-in EventSource does the connecting, parsing and reconnecting. This read-only snippet shows how a page would use the endpoint above:

HTML
<progress id="bar" max="100" value="0"></progress>
<script>
  const source = new EventSource("/progress");

  source.addEventListener("progress", (e) => {
    document.getElementById("bar").value = JSON.parse(e.data).percent;
  });

  source.addEventListener("done", () => source.close());   // stop reconnecting
  source.onerror = () => console.log("connection lost, the browser will retry");
</script>

If you never call close(), the browser reconnects forever, so send a final event the page understands.

Production notes

Streaming ties up a worker for as long as a connection stays open.

  • A sync gunicorn worker serves one stream at a time. Use threads (--threads) or async workers (gevent, eventlet), or run streaming endpoints in a separate service.
  • Proxies and CDNs may buffer or time out. Send a comment line (: keep-alive\n\n) every 15-30 seconds and disable buffering for that route.
  • Compression middleware can hold output until it has enough bytes; exclude text/event-stream.
  • For multi-user live updates, publish events through Redis (pub/sub) and let each connection subscribe, so any worker can serve any client.
  • Use SSE when only the server talks. Choose WebSockets when the browser also sends frequent messages.
  • Authenticate the SSE route like any other. EventSource sends cookies but cannot set custom headers, so cookie sessions work and bearer tokens do not.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does a Flask view that returns a generator do?

    Flask wraps iterators in a streaming Response and writes each chunk as soon as the generator yields it.
  2. 2. Why use stream_with_context?

    The generator runs after the view returned, when the request context would normally be gone. stream_with_context keeps it alive.
  3. 3. What ends one Server-Sent Event in the stream?

    Events are separated by an empty line. Fields such as data: and event: are one per line.
  4. 4. Which header value must an SSE response use?

    text/event-stream tells the browser's EventSource to parse the body as events. Do not set Content-Length: the body has no fixed size.
  5. 5. Why can a plain gunicorn sync worker be a poor fit for SSE?

    A stream holds its worker for the whole connection. Use threads, async workers or a separate streaming service.

Summary

  • A view can return a generator; Flask sends each chunk as it is yielded, without Content-Length.
  • Use stream_with_context (or read request values first) when the generator needs the request context.
  • Streaming a CSV with one csv.writer and a reusable buffer keeps memory flat for huge exports; send_file already streams files.
  • SSE is a one-way text protocol: data:, event:, id:, blank-line separators, Content-Type: text/event-stream, and automatic reconnection with Last-Event-ID.
  • In production, plan for open connections: threads or async workers, no proxy buffering, heartbeats, and Redis pub/sub for fan-out.

Next: add two-way messaging with Flask-SocketIO, or look at long-running work in Async Views and Background Tasks.