Skip to main content

Consume Server-Sent Event (SSE) messages with HTTPX.

Project description


Build Status Coverage Package version

Consume Server-Sent Event (SSE) messages with HTTPX.

Table of contents


NOTE: This is beta software. Please be sure to pin your dependencies.

pip install httpx-sse=="0.4.*"


httpx-sse provides the connect_sse and aconnect_sse helpers for connecting to an SSE endpoint. The resulting EventSource object exposes the .iter_sse() and .aiter_sse() methods to iterate over the server-sent events.

Example usage:

import httpx
from httpx_sse import connect_sse

with httpx.Client() as client:
    with connect_sse(client, "GET", "http://localhost:8000/sse") as event_source:
        for sse in event_source.iter_sse():
            print(sse.event,,, sse.retry)

You can try this against this example Starlette server (credit):

# Requirements: pip install uvicorn starlette sse-starlette
import asyncio
import uvicorn
from starlette.applications import Starlette
from starlette.routing import Route
from sse_starlette.sse import EventSourceResponse

async def numbers(minimum, maximum):
    for i in range(minimum, maximum + 1):
        await asyncio.sleep(0.9)
        yield {"data": i}

async def sse(request):
    generator = numbers(1, 5)
    return EventSourceResponse(generator)

routes = [
    Route("/sse", endpoint=sse)

app = Starlette(routes=routes)

if __name__ == "__main__":


Calling into Python web apps

You can call into Python web apps with HTTPX and httpx-sse to test SSE endpoints directly.

Here's an example of calling into a Starlette ASGI app...

import asyncio

import httpx
from httpx_sse import aconnect_sse
from sse_starlette.sse import EventSourceResponse
from starlette.applications import Starlette
from starlette.routing import Route

async def auth_events(request):
    async def events():
        yield {
            "event": "login",
            "data": '{"user_id": "4135"}',

    return EventSourceResponse(events())

app = Starlette(routes=[Route("/sse/auth/", endpoint=auth_events)])

async def main():
    async with httpx.AsyncClient(app=app) as client:
        async with aconnect_sse(
            client, "GET", "http://localhost:8000/sse/auth/"
        ) as event_source:
            events = [sse async for sse in event_source.aiter_sse()]
            (sse,) = events
            assert sse.event == "login"
            assert sse.json() == {"user_id": "4135"}

Handling reconnections


SSETransport and AsyncSSETransport don't have reconnection built-in. This is because how to perform retries is generally dependent on your use case. As a result, if the connection breaks while attempting to read from the server, you will get an httpx.ReadError from iter_sse() (or aiter_sse()).

However, httpx-sse does allow implementing reconnection by using the Last-Event-ID and reconnection time (in milliseconds), exposed as and sse.retry respectively.

Here's how you might achieve this using stamina...

import time
from typing import Iterator

import httpx
from httpx_sse import connect_sse, ServerSentEvent
from stamina import retry

def iter_sse_retrying(client, method, url):
    last_event_id = ""
    reconnection_delay = 0.0

    # `stamina` will apply jitter and exponential backoff on top of
    # the `retry` reconnection delay sent by the server.
    def _iter_sse():
        nonlocal last_event_id, reconnection_delay


        headers = {"Accept": "text/event-stream"}

        if last_event_id:
            headers["Last-Event-ID"] = last_event_id

        with connect_sse(client, method, url, headers=headers) as event_source:
            for sse in event_source.iter_sse():
                last_event_id =

                if sse.retry is not None:
                    reconnection_delay = sse.retry / 1000

                yield sse

    return _iter_sse()


with httpx.Client() as client:
    for sse in iter_sse_retrying(client, "GET", "http://localhost:8000/sse"):

API Reference


def connect_sse(
    client: httpx.Client,
    method: str,
    url: Union[str, httpx.URL],
) -> ContextManager[EventSource]

Connect to an SSE endpoint and return an EventSource context manager.

This sets Cache-Control: no-store on the request, as per the SSE spec, as well as Accept: text/event-stream.

If the response Content-Type is not text/event-stream, this will raise an SSEError.


async def aconnect_sse(
    client: httpx.AsyncClient,
    method: str,
    url: Union[str, httpx.URL],
) -> AsyncContextManager[EventSource]

An async equivalent to connect_sse.


def __init__(response: httpx.Response)

Helper for working with an SSE response.


The underlying httpx.Response.


def iter_sse() -> Iterator[ServerSentEvent]

Decode the response content and yield corresponding ServerSentEvent.

Example usage:

for sse in event_source.iter_sse():


async def iter_sse() -> AsyncIterator[ServerSentEvent]

An async equivalent to iter_sse.


Represents a server-sent event.

  • event: str - Defaults to "message".
  • data: str - Defaults to "".
  • id: str - Defaults to "".
  • retry: str | None - Defaults to None.


  • json() -> Any - Returns decoded as JSON.


An error that occurred while making a request to an SSE endpoint.


  • httpx.TransportError




All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog.

0.4.0 - 2023-12-22


  • Dropped Python 3.7 support, as it has reached EOL. (Pull #21)


  • Add official support for Python 3.12. (Pull #21)


  • Allow Content-Type that contain but are not strictly text/event-stream. (Pull #22 by @dbuades)
  • Improve error message when Content-Type is missing. (Pull #20 by @jamesbraza)

0.3.1 - 2023-06-01


  • Add __repr__() for ServerSentEvent model, which may help with debugging and other tasks. (Pull #16)

0.3.0 - 2023-04-27


  • Raising an SSEError if the response content type is not text/event-stream is now performed as part of iter_sse() / aiter_sse(), instead of connect_sse() / aconnect_sse(). This allows inspecting the response before iterating on server-sent events, such as checking for error responses. (Pull #12)

0.2.0 - 2023-03-27


  • connect_sse() and aconnect_sse() now require a method argument: connect_sse(client, "GET", ""). This provides support for SSE requests with HTTP verbs other than GET. (Pull #7)

0.1.0 - 2023-02-05

Initial release


  • Add connect_sse, aconnect_sse(), ServerSentEvent and SSEError.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

httpx-sse-0.4.0.tar.gz (12.6 kB view hashes)

Uploaded Source

Built Distribution

httpx_sse-0.4.0-py3-none-any.whl (7.8 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page