How-to › Move data in and out

How to stream a long HTTP response in Python with httpx#

Read an NDJSON or Server-Sent Events response line by line in sync and async Python, with a timeout per phase and a line splitter chosen on purpose.

Audience
API consumer
Level
beginner
Topic
Stream responses and subscriptions
Languages
Python
Verified

response.json() on a ten-minute export of meter readings holds every row in memory and prints nothing until the last byte lands. Switching to requests with stream=True shows the rows in bursts, long after the server sent them. httpx with its defaults raises ReadTimeout the first time the export goes quiet for five seconds.

What you get

You will end up with sync and async readers that hand you each reading as the server sends it, and an event-stream reader that can resume. A check times the arrivals. This is for you if you call an API whose responses run for minutes.

Short answer

Open the response with httpx’s client.stream(), read iter_bytes() or aiter_bytes(), and split on the newline byte yourself before parsing each line as JSON. Set httpx.Timeout per phase so a quiet stream outlives the five-second default. Use httpx-sse for text/event-stream, which exposes each event’s id and the server’s retry delay for a resume. A generated SDK’s stream helper saves the parsing only when it reads the body as it arrives.

You will need

Python 3.10 or later, or 3.11 for the OpenAPI Generator client, and an endpoint that answers NDJSON or Server-Sent Events. The sample’s npm ci installs its pinned PyPI packages into pydeps/, so Node 22 runs that one step. The sample’s api.json offers GET /readings as a JSON array or as NDJSON, and GET /readings/live as Server-Sent Events.

Approaches compared

ApproachWhen it fitsWhat it costs youWhen to pick something else
httpx client.streamNDJSON or plain text, in sync or async codeYou own the framing, the timeouts, and the error when a line is cutThe API ships a client that streams
httpx-sseThe endpoint answers text/event-streamOne more dependency, and reconnection is still your loop to writeThe body is NDJSON
KiotaYou already call the API through a Kiota clientIts typed get() buffers the body, so streaming means leaving the request builderYou only need the stream, not the typed models
OpenAPI GeneratorYou already ship its Python clientIts *_without_preload_content() method hands back an unread urllib3 response to parseYou want httpx and async
requests iter_linesSync code that already uses requestsA 512-byte read size that holds short lines back unless the body is chunkedYou need async, or lines on time
sdkgen streaming featureYou call the API through an sdkgen Python SDKstream('list') iterates a list parsed after the whole body arrivedReadings must reach you while the response is open

Voxgig maintains sdkgen. It is one of six options here, not the recommendation.

httpx by hand gives you control of every timeout and every byte, in exchange for writing the framing yourself. The generated clients save you that code, and all three here wait for the body before they parse it. requests sits between, with a read size you have to know about.

Check what the generated SDK yields

Generate the Python SDK with the streaming feature, as generate.sh does. Every entity has a stream() method with or without it; the feature takes over the iteration once a client sets it active:

npx --yes @voxgig/create-sdkgen@0.31.9 meter --def api.json -t py -f streaming

demo.py reads five readings, sent 50 ms apart, three ways. Each row records how many readings the server had sent when that one reached the caller:

python3 demo.py
sdkgen Reading().stream('list')
  r1   1.5 kWh   server had sent 5 of 5
  r2  1.75 kWh   server had sent 5 of 5
  r3   2.0 kWh   server had sent 5 of 5
  r4   2.5 kWh   server had sent 5 of 5
  r5  3.25 kWh   server had sent 5 of 5
httpx client.stream() and iter_bytes(), sync, URL from sdk.prepare()
  r1   1.5 kWh   server had sent 1 of 5
  r2  1.75 kWh   server had sent 2 of 5
  r3   2.0 kWh   server had sent 3 of 5
  r4   2.5 kWh   server had sent 4 of 5
  r5  3.25 kWh   server had sent 5 of 5
httpx AsyncClient.stream() and aiter_bytes()
  r1   1.5 kWh   server had sent 1 of 5
  r2  1.75 kWh   server had sent 2 of 5
  r3   2.0 kWh   server had sent 3 of 5
  r4   2.5 kWh   server had sent 4 of 5
  r5  3.25 kWh   server had sent 5 of 5

The SDK’s stream('list') is a generator over a list that its requests transport has already parsed, so every reading arrives after the fifth was sent. It still earns its place for a short list, because a caller writes the same loop as for a long one. When the readings must arrive on time, take the URL from the SDK’s prepare(), which builds the request and sends nothing, and stream it with httpx.

Read each line as it arrives

client.stream() returns the response before the body is read, and the with block closes the connection when the loop ends or raises:

# One timeout per phase. The read timeout is the longest gap allowed between two
# chunks, not the length of the whole response, so a long export that keeps sending
# chunks does not trip it.
TIMEOUT = httpx.Timeout(connect=5.0, read=60.0, write=5.0, pool=5.0)
NDJSON = {"accept": "application/x-ndjson"}


def split_ndjson(chunks):
    """Split on b"\\n" alone, as NDJSON specifies, and parse each line.

    iter_lines() splits like str.splitlines(), which also breaks on U+2028 and
    other separators that are legal inside a JSON string.
    """
    buffered = b""
    for chunk in chunks:
        buffered += chunk
        *lines, buffered = buffered.split(b"\n")
        for line in lines:
            if line.strip():
                yield json.loads(line)
    if buffered.strip():
        raise ValueError(f"the stream ended mid-line: {buffered[:20]!r}")


def iter_readings(client: httpx.Client, url: str, headers=None):
    with client.stream("GET", url, headers={**NDJSON, **(headers or {})}) as response:
        response.raise_for_status()
        yield from split_ndjson(response.iter_bytes())

The async reader is the same code with httpx.AsyncClient, async with, and aiter_bytes(). Each phase of httpx.Timeout has its own limit, and read is the one a quiet stream meets.

Resume an event stream from the last id

httpx-sse parses text/event-stream and leaves reconnection to you. Its README says so, and gives each event’s id and retry as the values to reconnect with:

def watch_readings(client: httpx.Client, url: str, state: dict):
    """Yield readings. `state` keeps the last event id and the server's retry delay."""
    headers = {}
    if state.get("last_id") is not None:
        headers["last-event-id"] = state["last_id"]
    with connect_sse(client, "GET", url, headers=headers) as source:
        for sse in source.iter_sse():
            if sse.retry is not None:
                state["retry_ms"] = sse.retry
            if sse.event != "reading":
                continue
            state["last_id"] = sse.id
            yield json.loads(sse.data)
python3 resume.py
  r1  first connection
  r2  first connection
reconnect with last-event-id r2; the server asked for a retry delay of 2000 ms
  r3  second connection
  r4  second connection
  r5  second connection
last-event-id the server saw: [None, 'r2']

Send Kiota’s request with stream=True

Kiota’s Python readings.get() calls send_collection_async and returns parsed Reading objects, and its /readings/live builder returns the whole body as bytes. Kiota’s abstractions page describes a response handler that can return the native HTTP response instead. kiota_stream.py takes a shorter route. It builds the request with the generated to_get_request_information(), turns it into an httpx.Request with the adapter’s convert_to_native_async(), and sends it with stream=True:

python3 kiota_stream.py
readings.get(): 5 Reading objects, server had sent 5 of 5
readings.live.get(): bytes
the same request as an httpx.Request, accept: application/x-ndjson
  server had sent, as each reading arrived: [1, 2, 3, 4, 5]

convert_to_native_async() runs the adapter’s authentication provider before it builds the request, so the hand-off keeps Kiota’s URL template and credentials. Kiota is the better choice when the rest of your code already talks to the API through its fluent builders.

Leave the OpenAPI Generator response unread

OpenAPI Generator’s Python client generates list_readings_without_preload_content(), which returns the urllib3 response unread. Unless you pass your own Accept, the serializer offers both media types to select_header_accept():

        # set the HTTP header `Accept`
        if not any(key.lower() == 'accept' for key in _header_params):
            _header_params['Accept'] = self.api_client.select_header_accept(
                [
                    'application/json', 
                    'application/x-ndjson'
                ]
            )

That function returns the first entry containing json, so the request asks for the array:

        for accept in accepts:
            if re.search('json', accept, re.IGNORECASE):
                return accept

        return accepts[0]

oag_stream.py passes _headers={"Accept": "application/x-ndjson"} and reads the response with urllib3’s stream(1024):

python3 oag_stream.py
list_readings(): 5 Reading objects, server had sent 5 of 5, accept: application/json
list_readings_without_preload_content(), accept: application/x-ndjson
  server had sent, as each reading arrived: [1, 2, 3, 4, 5]

The generated package asks for Python 3.11 and Pydantic. It suits a team that ships that generator’s clients in several languages and wants no second HTTP library.

Check it worked

check.py records time.monotonic() as each reading arrives and compares it with the server’s count:

python3 check.py
ok  sdkgen stream('list') yields all five within 50 ms, after the last was sent
ok  httpx sync: one reading per send, first to last at least 0.5 s apart
ok  httpx async: one reading per send, first to last at least 0.5 s apart
ok  a read timeout shorter than a quiet gap raises ReadTimeout
ok  the per-phase TIMEOUT reads the same quiet stream to the end
ok  a body that ends mid-line raises
ok  split_ndjson keeps a line that carries U+2028 in a string
ok  httpx iter_lines() splits that line in two
ok  httpx-sse resumes from Last-Event-ID with no repeats
ok  requests iter_lines() hands over each line of a chunked body as it lands
ok  requests iter_lines() holds back a short body that ends at the close
ok  requests iter_lines() with chunk_size=1 hands over that body's lines as they land
ok  Kiota readings.get() returns after the last reading was sent
ok  Kiota's request sent by httpx with stream=True yields each reading as it is sent
ok  OpenAPI Generator list_readings() asks for JSON and returns after the last reading
ok  OpenAPI Generator's unread response, read in chunks, yields each reading as it is sent

The server sends a reading every 150 ms in the first three checks, so a reader that buffers fails the spread. Each failed check prints FAIL and makes the script exit 1.

When it goes wrong

python3 pitfall.py
httpx default timeout: Timeout(timeout=5.0)
quiet for 0.6 s, read timeout 0.3 s: ReadTimeout after ['r1', 'r2']
requests ITER_CHUNK_SIZE: 512
requests iter_lines(), chunked body, server's count per line:    [1, 2, 3, 4, 5]
requests iter_lines(), body ends at close, server's count per line: [5, 5, 5, 5, 5]
iter_lines() on a reading with U+2028 in a string: ['r1', 'JSONDecodeError', 'JSONDecodeError', 'r3', 'r4', 'r5']
split_ndjson(iter_bytes()) on the same body:       ['r1', 'r2', 'r3', 'r4', 'r5']

The stream stops with ReadTimeout during a pause. The httpx default allows five seconds between chunks. Set read to more than the longest pause the API documents, and keep connect short.

requests shows nothing, then every line at once. iter_lines() reads 512 bytes at a time. A chunked body hands over each chunk as it lands, but a body that ends at the connection’s close returns a read only once 512 bytes arrive or the connection closes. Pass chunk_size=1, which reads a byte at a time, or use httpx.

A valid line fails to parse. httpx’s iter_lines() splits like str.splitlines(), which breaks on U+2028, a character JSON allows inside a string without an escape.1 Split on b"\n" yourself.

When not to do this

Do not stream a response that is a few kilobytes and arrives in one round trip. response.json() is shorter, and the sdkgen stream('list') loop costs nothing at that size.

Do not hand-write an SSE parser when httpx-sse covers the format. The parser is the easy part to get almost right, and the README carries a reconnection example built on id and retry.

Do not set timeout=None to make a quiet stream survive. It removes the connect and pool limits too, so a dead host hangs the caller. Raise read alone.

Pick Kiota or OpenAPI Generator when the rest of the integration already uses their typed models, and stream through their request builders for the one endpoint that needs it.

Last verified

Verified 2026-11-20 against Python 3.13.18, Node 22.23.5, httpx 0.28.1, httpx-sse 0.4.3, requests 2.34.2, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3, Kiota 1.38.0 with its Python packages 1.18.0, and OpenAPI Generator 7.27.0 with Pydantic 2.14.4. Every output block is what the command preceding it printed. The generators ran once, through generate.sh, and their output is committed and run.

Footnotes

  1. RFC 8259 lists the characters a JSON string must escape, and U+2028 and U+2029 are not among them. JavaScript string literals refused both until the JSON superset proposal allowed them, which TC39’s list of finished proposals places in ECMAScript 2019. Python’s str.splitlines() counts both as line boundaries. ↩︎ Back to text

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.