In FastAPI 0.143, how does a yielding path operation's output differ under the default response class, EventSourceResponse and StreamingResponse?
answer
- three modes, one keyword
- who encodes the items
- jsonl, event-stream, raw bytes
- media_type on a subclass
basics
~20 sWith no response_class FastAPI sends JSON Lines; with EventSourceResponse it sends Server-Sent Events with JSON data; with StreamingResponse it passes each chunk through untouched, so only the first two validate items against the return type.
solid answer
~40 sThe same `yield` gives three different responses. With no `response_class`, FastAPI serializes each item to one JSON line, `application/jsonl`. With `EventSourceResponse` it wraps each item's JSON in an SSE event, `text/event-stream`, and adds the keep-alive ping and no-cache headers. With `StreamingResponse` it does no conversion at all: strings are encoded to UTF-8, bytes pass through, a dict fails, and the return annotation is not used to validate anything. A plain `StreamingResponse` sends no `Content-Type`, so for binary or text downloads I subclass it and set `media_type`. In all three modes a `def` generator is stepped in the thread pool and an `async def` one on the event loop.
code
python · 22 linesimport io
from collections.abc import Iterable
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
app = FastAPI()
class PlainTextStream(StreamingResponse):
media_type = "text/plain"
ARCHIVE = io.BytesIO(b"line 1\nline 2\nline 3\n") # stands in for a log file on disk
@app.get("/logs/archive", response_class=PlainTextStream)
def download_archive() -> Iterable[bytes]:
# def: each step runs in the thread pool, so a blocking read
# does not stall the event loop; chunks go out exactly as yielded
ARCHIVE.seek(0)
yield from ARCHIVEgo deeper
Recall the three outputs: JSON Lines by default, events with EventSourceResponse, raw chunks with StreamingResponse.
Explain who encodes the items in each mode, where the return annotation is used, and why a StreamingResponse subclass sets media_type.
Spot the failures that appear mid-stream: a dict yielded to StreamingResponse, a missing Content-Type, a blocking read in an async def generator.
Set a convention for which streaming mode each kind of consumer gets, so clients, OpenAPI item schemas and error signalling stay consistent.
## Three modes, one keyword Since **FastAPI 0.134**, any path operation function may `yield` instead of `return`. What reaches the client then depends on the `response_class` you set on the decorator. The function body can be identical in all three cases; the encoding is chosen by FastAPI's routing layer when the route is registered. | `response_class` | Media type sent | What happens to each yielded item | Return annotation used for | |---|---|---|---| | not set | `application/jsonl` | serialized to JSON, newline appended | validation, filtering, OpenAPI `itemSchema` | | `EventSourceResponse` (from `fastapi.sse`, 0.135+) | `text/event-stream` | JSON-encoded into an event's data, or a `ServerSentEvent` encoded field by field | validation and the `data` schema in OpenAPI, except for `ServerSentEvent` items | | `StreamingResponse` | none unless set | sent as-is: `str` encoded, `bytes` passed through | nothing; it is only for your editor | ## Default: JSON Lines When no response class is given, the generator is wrapped in Starlette's `StreamingResponse` with `media_type="application/jsonl"`. With an `AsyncIterable[Item]` or `Iterable[Item]` annotation, each item is validated against `Item`, filtered to its declared fields and serialized by Pydantic. Without one, items go through `jsonable_encoder`. This is the mode for **structured records**: log entries, rows of an export, partial results. ## EventSourceResponse: Server-Sent Events Setting `response_class=EventSourceResponse` keeps the item handling but changes the framing: each item becomes one Server-Sent Event, with its JSON in the data field. You can also yield `ServerSentEvent` objects to set `event`, `id`, `retry`, `comment` or an unencoded `raw_data`. On top of the framing FastAPI adds: - `Cache-Control: no-cache` and `X-Accel-Buffering: no` headers; - a `: ping` keep-alive comment after 15 seconds without an event. This is the mode for **browser consumers** that listen with `EventSource` or an event-stream parser. ## StreamingResponse: bytes you own With `response_class=StreamingResponse`, FastAPI hands each chunk to the response unchanged. The rules are Starlette's: - a `str` chunk is encoded with the response's charset (UTF-8); - a `bytes` or `memoryview` chunk is sent as-is; - anything else fails: yielding a dict raises `AttributeError: 'dict' object has no attribute 'encode'` once the stream has started. Nothing is validated, filtered or JSON-encoded, and the OpenAPI entry gets no item schema. A bare `StreamingResponse` also sends **no `Content-Type` header**, because its `media_type` is unset. The decorator has no `media_type` argument for this, so the FastAPI docs show a small subclass that sets the class attribute, such as `media_type = "image/png"` or `"text/plain"`, and passing that subclass as `response_class`. This is the mode for **raw bytes or text**: a file download read in chunks, generated audio, or plain text whose format you control completely. ## def versus async def, in every mode The choice of response class does not change how the generator is driven: 1. An `async def` generator runs on the event loop; any blocking call inside it stalls all requests, so it must await non-blocking APIs. 2. A plain `def` generator is advanced one step at a time in a worker thread, so blocking file or network reads are safe. Annotate it with `Iterable[...]`. The thread pool's size and how it is shared with `def` endpoints and dependencies belong to FastAPI's thread-pool offloading. ## What the generated schema shows The mode also decides what the OpenAPI document says about the endpoint: - JSON Lines with an item type: the response content is `application/jsonl` with the model as its `itemSchema`. - Server-Sent Events: the content is `text/event-stream` with an event `itemSchema`; its `data` field embeds the item model's schema, or stays a plain string when you yield `ServerSentEvent`. - `StreamingResponse`: no content schema at all, since FastAPI does not know what the bytes are. ## Choosing between them - Pick **JSON Lines** for service-to-service streams, command-line consumers and exports where each record is JSON. - Pick **Server-Sent Events** when a browser renders the stream and benefits from named events, ids and keep-alive. - Pick **StreamingResponse** when the payload is not JSON at all, and set its media type yourself. - Returning `StreamingResponse(gen())` from a normal function still works, but it bypasses the per-item validation the yield modes give you.
- Why does yielding a dict from a path operation with response_class=StreamingResponse fail, and when?StreamingResponse only knows `str`, `bytes` and `memoryview` chunks; it calls `.encode` on anything that is not bytes, which a dict lacks. The error surfaces while the body is streaming, after the 200 status has been sent. Remove the response class to get JSON Lines, or encode the dict yourself.
- How do you give a yielding StreamingResponse endpoint a Content-Type header?Subclass `StreamingResponse`, set the class attribute `media_type` (for example `"text/csv"`), and pass the subclass as `response_class`. The decorator has no `media_type` argument, and the plain class sends no Content-Type header at all.
- StreamingResponse JSON-encodes each yielded dict like the default mode does.
- The return annotation validates items for every response class.
- A yielding endpoint always sends text/event-stream.
- StreamingResponse sends application/octet-stream when no media type is set.
- An async def generator can call blocking file reads safely.
Assumes FastAPI 0.143; yield with the default class and StreamingResponse dates from 0.134, and EventSourceResponse from 0.135.