{"course":{"slug":"python-for-ai","title":"Python, from Zero, for AI","url":"https://addaly.com/learn/python-for-ai","level":"beginner","track":"build"},"lesson":{"slug":"consuming-a-stream","title":"Consuming a streamed reply: server-sent events, line by line","url":"https://addaly.com/learn/python-for-ai/consuming-a-stream","position":55,"of":89,"minutes":9,"answer":"A streamed model reply is one long HTTP response made of data: lines, each carrying a JSON fragment; read it with iter_lines, parse each fragment, print with flush=True.","keyIdea":"A streamed model reply is one long HTTP response made of data: lines, each carrying a JSON fragment; read it with iter_lines, parse each fragment, print with flush=True, and accumulate the text yourself because nothing else will."},"body":{"format":"markdown","text":"## What streaming actually is\n\nWithout streaming, a model API generates the whole reply, then sends it. A 500-token answer at 50 tokens per second means ten seconds of nothing, then everything. With streaming, the server starts sending tokens as it produces them, over a single HTTP response that stays open until the generation ends.\n\nThe wire format is **server-sent events**, and it is text:\n\n```\nevent: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"text_delta\",\"text\":\"The\"}}\n\nevent: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"text_delta\",\"text\":\" answer\"}}\n\n```\n\nEach event is a few lines; a blank line ends it. The `data:` line carries JSON. That is the whole protocol. A course on how a model *decides* those tokens lives elsewhere; this lesson is about reading them.\n\n## Reading it with requests\n\n```python\nimport json, requests\n\nr = session.post(\n    url,\n    headers=headers,\n    json={**payload, \"stream\": True},\n    # do not read the body up front\n    stream=True,\n    timeout=(5, 120),\n)\nr.raise_for_status()\n# SSE is always UTF-8; with no charset in the header\n# requests would guess ISO-8859-1 and garble Hindi\nr.encoding = \"utf-8\"\n\nparts = []\nfor line in r.iter_lines(decode_unicode=True):\n    if not line or not line.startswith(\"data:\"):\n        continue\n    data = line[len(\"data:\") :].strip()\n    # OpenAI's terminator; Anthropic sends a message_stop\n    # event\n    if data == \"[DONE]\":\n        break\n    event = json.loads(data)\n    # provider-specific; see below\n    text = extract_text(event)\n    if text:\n        parts.append(text)\n        print(text, end=\"\", flush=True)\n\nprint()\nfull = \"\".join(parts)\n```\n\nThree details carry the weight.\n\n`stream=True` on the `requests` call tells it not to download the body before returning. Without it, `iter_lines` still works but only after the entire reply has arrived, which defeats the purpose.\n\n`iter_lines` yields each line as it is received. `decode_unicode=True` gives you `str` rather than `bytes`.\n\n`flush=True` on `print`. When stdout is a terminal Python flushes on each newline, and you are printing none. When stdout is a pipe or a file it is block-buffered and flushes only when the buffer fills. Either way, without `flush=True` the tokens arrive but do not appear, and you conclude the server is not streaming.\n\n## The extract step differs per provider\n\nOpenAI's chunks look like:\n\n```python\ndef extract_text(event):\n    choices = event.get(\"choices\") or []\n    if not choices:\n        return \"\"\n    return choices[0].get(\"delta\", {}).get(\"content\") or \"\"\n```\n\nAnthropic's:\n\n```python\ndef extract_text(event):\n    if event.get(\"type\") == \"content_block_delta\":\n        return event[\"delta\"].get(\"text\", \"\")\n    return \"\"\n```\n\nUse `.get()` everywhere here. The stream carries events that are not text (a start event, usage figures at the end, a stop reason) and indexing them as if they were text raises `KeyError` mid-stream, at which point the connection is dropped and the partial answer is lost.\n\n## With the SDK\n\n```python\nwith client.messages.stream(model=m, max_tokens=500, messages=msgs) as stream:\n    for text in stream.text_stream:\n        print(text, end=\"\", flush=True)\n    final = stream.get_final_message()\n```\n\nThe SDK parses the events and hands you text. `get_final_message()` returns the assembled message with the usage figures, which a later lesson uses for cost. OpenAI's is `for chunk in client.chat.completions.create(..., stream=True)`, with the text in `chunk.choices[0].delta.content`, sometimes `None`.\n\n## Accumulate, because nobody else will\n\nA stream gives you fragments. If you want the full answer afterwards (to save it, to parse JSON out of it, to log it) you must collect it yourself. The `parts` list above is not optional. Appending to a list and joining once at the end is the right pattern; `full += text` in the loop copies the growing string every time, which is quadratic and noticeable past a few thousand fragments.\n\n## A stream can end early\n\nThe server can close the connection at any point: a network fault, a timeout, a server-side error surfaced as an `error` event. Your loop ends and you have half an answer. Check the terminal event before trusting the text. OpenAI sets `finish_reason` on the last chunk (`\"stop\"` is good, `\"length\"` means the token limit cut it off); Anthropic sends a `message_delta` with `stop_reason`. If neither arrived, the stream broke and the partial text should be marked as partial, not saved as an answer.\n\nAlso apply the read timeout. It counts time between bytes, and with streaming the gaps are short, so a 30-second read timeout catches a stuck stream without failing a long healthy one. A stream is the one place where a short read timeout is fine.\n\n## Turning it into a generator\n\nWrap the loop in a function with `yield` and the caller can consume it like any sequence, print it, or feed it to a web interface:\n\n```python\ndef stream_text(session, url, headers, payload):\n    with session.post(url, headers=headers, json={**payload, \"stream\": True},\n                      stream=True, timeout=(5, 30)) as r:\n        r.raise_for_status()\n        for line in r.iter_lines(decode_unicode=True):\n            if line.startswith(\"data:\") and line[5:].strip() != \"[DONE]\":\n                text = extract_text(json.loads(line[5:]))\n                if text:\n                    yield text\n```\n\nThe `with` ensures the connection is released when the caller stops early. Module 9 plugs this exact function into a web interface.\n\n## Try this now\n\nRun the raw `requests` version against Ollama's OpenAI-compatible endpoint, which streams for free. Remove `flush=True` and run it with output piped through `cat` to watch the whole answer appear at once. Then put it back."},"check":{"question":"A developer streams a reply with `stream=True` and prints each text fragment as it arrives using `print(fragment, end=\"\")`. Nothing appears for twenty seconds, then the whole answer shows at once. What is the most likely cause?","options":[{"text":"The server buffered the entire generation before sending, so streaming was never really on.","correct":false,"tempting":"Possible but rare; the far commoner cause is on the client, and this diagnosis skips the check that would show it."},{"text":"`iter_lines()` waits for the response to complete before yielding anything, so genuine streaming requires `iter_content()` with a small chunk size and a hand-written line splitter.","correct":false,"tempting":"`iter_lines` yields as lines arrive; it does not wait for the end of the body."},{"text":"The JSON parser needed the closing bracket of the whole response before any fragment could be decoded.","correct":false,"tempting":"Each SSE event is its own complete JSON object; there is no enclosing document to wait for."},{"text":"Nothing was newline-terminated, so stdout's buffer held the fragments until it filled; `flush=True` after each print empties it.","correct":true}]},"prev":{"slug":"sdks-versus-raw-requests","title":"A provider's SDK: what it does for you, what it hides, and how to read it","url":"https://addaly.com/learn/python-for-ai/sdks-versus-raw-requests"},"next":{"slug":"asyncio-and-concurrent-calls","title":"asyncio: twenty calls in the time of one","url":"https://addaly.com/learn/python-for-ai/asyncio-and-concurrent-calls"},"authorship":"Founder and series editor: Dr Mustafa Mun. Written by AI models to a written standard. Source and assessment review continues. Academic review invited.","review":{"status":"Draft, open for academic review"},"cite":"Addaly (2026) 'Consuming a streamed reply: server-sent events, line by line', in Python, from Zero, for AI. Edited by M. Mun. Addaly. Available at: https://addaly.com/learn/python-for-ai/consuming-a-stream (Accessed: 21 November 2026).","licence":{"name":"CC BY-NC-SA 4.0","url":"https://creativecommons.org/licenses/by-nc-sa/4.0/"},"reader":{"schema":1,"title":"Consuming a streamed reply: server-sent events, line by line","courseTitle":"Python, from Zero, for AI","module":{"index":6,"slug":"talking-to-a-service","title":"Talking to a service: HTTP from Python, done properly"},"answer":null,"keyIdea":"A streamed model reply is one long HTTP response made of data: lines, each carrying a JSON fragment; read it with iter_lines, parse each fragment, print with flush=True, and accumulate the text yourself because nothing else will.","hero":{"kind":"plate","image":null,"alt":null,"caption":null},"blocks":[{"t":"h2","id":"what-streaming-actually-is","runs":[{"text":"What streaming actually is"}]},{"t":"p","runs":[{"text":"Without streaming, a model API generates the whole reply, then sends it. A 500-token answer at 50 tokens per second means ten seconds of nothing, then everything. With streaming, the server starts sending tokens as it produces them, over a single HTTP response that stays open until the generation ends."}]},{"t":"p","runs":[{"text":"The wire format is "},{"text":"server-sent events","b":true},{"text":", and it is text:"}]},{"t":"code","lang":"","label":"Text","text":"event: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"text_delta\",\"text\":\"The\"}}\n\nevent: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"text_delta\",\"text\":\" answer\"}}\n"},{"t":"p","runs":[{"text":"Each event is a few lines; a blank line ends it. The "},{"text":"data:","code":true},{"text":" line carries JSON. That is the whole protocol. A course on how a model "},{"text":"decides","i":true},{"text":" those tokens lives elsewhere; this lesson is about reading them."}]},{"t":"h2","id":"reading-it-with-requests","runs":[{"text":"Reading it with requests"}]},{"t":"code","lang":"python","label":"Python","text":"import json, requests\n\nr = session.post(\n    url,\n    headers=headers,\n    json={**payload, \"stream\": True},\n    # do not read the body up front\n    stream=True,\n    timeout=(5, 120),\n)\nr.raise_for_status()\n# SSE is always UTF-8; with no charset in the header\n# requests would guess ISO-8859-1 and garble Hindi\nr.encoding = \"utf-8\"\n\nparts = []\nfor line in r.iter_lines(decode_unicode=True):\n    if not line or not line.startswith(\"data:\"):\n        continue\n    data = line[len(\"data:\") :].strip()\n    # OpenAI's terminator; Anthropic sends a message_stop\n    # event\n    if data == \"[DONE]\":\n        break\n    event = json.loads(data)\n    # provider-specific; see below\n    text = extract_text(event)\n    if text:\n        parts.append(text)\n        print(text, end=\"\", flush=True)\n\nprint()\nfull = \"\".join(parts)"},{"t":"p","runs":[{"text":"Three details carry the weight."}]},{"t":"p","runs":[{"text":"stream=True","code":true},{"text":" on the "},{"text":"requests","code":true},{"text":" call tells it not to download the body before returning. Without it, "},{"text":"iter_lines","code":true},{"text":" still works but only after the entire reply has arrived, which defeats the purpose."}]},{"t":"p","runs":[{"text":"iter_lines","code":true},{"text":" yields each line as it is received. "},{"text":"decode_unicode=True","code":true},{"text":" gives you "},{"text":"str","code":true},{"text":" rather than "},{"text":"bytes","code":true},{"text":"."}]},{"t":"p","runs":[{"text":"flush=True","code":true},{"text":" on "},{"text":"print","code":true},{"text":". When stdout is a terminal Python flushes on each newline, and you are printing none. When stdout is a pipe or a file it is block-buffered and flushes only when the buffer fills. Either way, without "},{"text":"flush=True","code":true},{"text":" the tokens arrive but do not appear, and you conclude the server is not streaming."}]},{"t":"h2","id":"the-extract-step-differs-per-provider","runs":[{"text":"The extract step differs per provider"}]},{"t":"p","runs":[{"text":"OpenAI’s chunks look like:"}]},{"t":"code","lang":"python","label":"Python","text":"def extract_text(event):\n    choices = event.get(\"choices\") or []\n    if not choices:\n        return \"\"\n    return choices[0].get(\"delta\", {}).get(\"content\") or \"\""},{"t":"p","runs":[{"text":"Anthropic’s:"}]},{"t":"code","lang":"python","label":"Python","text":"def extract_text(event):\n    if event.get(\"type\") == \"content_block_delta\":\n        return event[\"delta\"].get(\"text\", \"\")\n    return \"\""},{"t":"p","runs":[{"text":"Use "},{"text":".get()","code":true},{"text":" everywhere here. The stream carries events that are not text (a start event, usage figures at the end, a stop reason) and indexing them as if they were text raises "},{"text":"KeyError","code":true},{"text":" mid-stream, at which point the connection is dropped and the partial answer is lost."}]},{"t":"h2","id":"with-the-sdk","runs":[{"text":"With the SDK"}]},{"t":"code","lang":"python","label":"Python","text":"with client.messages.stream(model=m, max_tokens=500, messages=msgs) as stream:\n    for text in stream.text_stream:\n        print(text, end=\"\", flush=True)\n    final = stream.get_final_message()"},{"t":"p","runs":[{"text":"The SDK parses the events and hands you text. "},{"text":"get_final_message()","code":true},{"text":" returns the assembled message with the usage figures, which a later lesson uses for cost. OpenAI’s is "},{"text":"for chunk in client.chat.completions.create(..., stream=True)","code":true},{"text":", with the text in "},{"text":"chunk.choices[0].delta.content","code":true},{"text":", sometimes "},{"text":"None","code":true},{"text":"."}]},{"t":"h2","id":"accumulate-because-nobody-else-will","runs":[{"text":"Accumulate, because nobody else will"}]},{"t":"p","runs":[{"text":"A stream gives you fragments. If you want the full answer afterwards (to save it, to parse JSON out of it, to log it) you must collect it yourself. The "},{"text":"parts","code":true},{"text":" list above is not optional. Appending to a list and joining once at the end is the right pattern; "},{"text":"full += text","code":true},{"text":" in the loop copies the growing string every time, which is quadratic and noticeable past a few thousand fragments."}]},{"t":"h2","id":"a-stream-can-end-early","runs":[{"text":"A stream can end early"}]},{"t":"p","runs":[{"text":"The server can close the connection at any point: a network fault, a timeout, a server-side error surfaced as an "},{"text":"error","code":true},{"text":" event. Your loop ends and you have half an answer. Check the terminal event before trusting the text. OpenAI sets "},{"text":"finish_reason","code":true},{"text":" on the last chunk ("},{"text":"\"stop\"","code":true},{"text":" is good, "},{"text":"\"length\"","code":true},{"text":" means the token limit cut it off); Anthropic sends a "},{"text":"message_delta","code":true},{"text":" with "},{"text":"stop_reason","code":true},{"text":". If neither arrived, the stream broke and the partial text should be marked as partial, not saved as an answer."}]},{"t":"p","runs":[{"text":"Also apply the read timeout. It counts time between bytes, and with streaming the gaps are short, so a 30-second read timeout catches a stuck stream without failing a long healthy one. A stream is the one place where a short read timeout is fine."}]},{"t":"h2","id":"turning-it-into-a-generator","runs":[{"text":"Turning it into a generator"}]},{"t":"p","runs":[{"text":"Wrap the loop in a function with "},{"text":"yield","code":true},{"text":" and the caller can consume it like any sequence, print it, or feed it to a web interface:"}]},{"t":"code","lang":"python","label":"Python","text":"def stream_text(session, url, headers, payload):\n    with session.post(url, headers=headers, json={**payload, \"stream\": True},\n                      stream=True, timeout=(5, 30)) as r:\n        r.raise_for_status()\n        for line in r.iter_lines(decode_unicode=True):\n            if line.startswith(\"data:\") and line[5:].strip() != \"[DONE]\":\n                text = extract_text(json.loads(line[5:]))\n                if text:\n                    yield text"},{"t":"p","runs":[{"text":"The "},{"text":"with","code":true},{"text":" ensures the connection is released when the caller stops early. Module 9 plugs this exact function into a web interface."}]},{"t":"h2","id":"try-this-now","runs":[{"text":"Try this now"}],"role":"try"},{"t":"p","runs":[{"text":"Run the raw "},{"text":"requests","code":true},{"text":" version against Ollama’s OpenAI-compatible endpoint, which streams for free. Remove "},{"text":"flush=True","code":true},{"text":" and run it with output piped through "},{"text":"cat","code":true},{"text":" to watch the whole answer appear at once. Then put it back."}]}],"check":{"question":[{"text":"A developer streams a reply with "},{"text":"stream=True","code":true},{"text":" and prints each text fragment as it arrives using "},{"text":"print(fragment, end=\"\")","code":true},{"text":". Nothing appears for twenty seconds, then the whole answer shows at once. What is the most likely cause?"}],"options":[{"text":[{"text":"The server buffered the entire generation before sending, so streaming was never really on."}],"correct":false,"tempting":[{"text":"Possible but rare; the far commoner cause is on the client, and this diagnosis skips the check that would show it."}]},{"text":[{"text":"iter_lines()","code":true},{"text":" waits for the response to complete before yielding anything, so genuine streaming requires "},{"text":"iter_content()","code":true},{"text":" with a small chunk size and a hand-written line splitter."}],"correct":false,"tempting":[{"text":"iter_lines","code":true},{"text":" yields as lines arrive; it does not wait for the end of the body."}]},{"text":[{"text":"The JSON parser needed the closing bracket of the whole response before any fragment could be decoded."}],"correct":false,"tempting":[{"text":"Each SSE event is its own complete JSON object; there is no enclosing document to wait for."}]},{"text":[{"text":"Nothing was newline-terminated, so stdout’s buffer held the fragments until it filled; "},{"text":"flush=True","code":true},{"text":" after each print empties it."}],"correct":true,"tempting":null}],"order":[0,1,2,3],"why":null},"prev":{"slug":"sdks-versus-raw-requests","title":"A provider’s SDK: what it does for you, what it hides, and how to read it","minutes":8},"next":{"slug":"asyncio-and-concurrent-calls","title":"asyncio: twenty calls in the time of one","minutes":10}}}