Requests-SSE Client

0.5.3 · active · verified Fri Apr 17

requests-sse is a Python client library for Server-Sent Events (SSE), built on top of the popular 'requests' HTTP library. It provides an `EventSource` object for consuming event streams, handling reconnections and message parsing according to the WHATWG SSE specification. The current stable version is 0.5.3, with a beta 0.6.0b0 indicating an upcoming major release. The library generally follows an active release cadence with minor updates and bug fixes.

Common errors

```
AttributeError: 'EventSource' object has no attribute 'option'
```
cause You are trying to pass an `option` parameter to the `EventSource` constructor, which was removed in version 0.3.0.

fix Remove the `option` parameter from your `EventSource` initialization. Review your code to adapt to this breaking change.
```
Content-Type must be 'text/event-stream'
```
cause The server you are connecting to is not sending the `Content-Type: text/event-stream` header, or it includes additional parameters that prevent strict validation (pre-0.5.3).

fix Ensure the server correctly sets the `Content-Type` header to `text/event-stream`. If on an older version of `requests-sse` (<0.5.3), upgrading might fix issues with extra `charset` parameters in the content-type.
```
TypeError: argument of type 'bytes' is not iterable (or similar type error for event.data)
```
cause Your code is expecting `event.data` or `event.type` to be of a specific non-string type (e.g., bytes, integer) but in `0.6.0b0+` these fields are strictly strings.

fix If you have upgraded to `0.6.0b0` (or a future stable `0.6.0`), ensure your code always expects `event.data` and `event.type` to be strings and handles conversion (e.g., `json.loads(event.data)`) explicitly if needed.

Warnings

breaking The upcoming 0.6.0b0 (beta) release introduces significant changes to SSE parsing logic and `MessageEvent` data types. Specifically, `MessageEvent.data` and `MessageEvent.type` will always be strings, and SSE field parsing aligns more strictly with WHATWG event stream rules (e.g., stripping only one leading space).
Fix: Review the 0.6.0b0 changelog carefully before upgrading. Ensure your code expects `event.data` and `event.type` to be strings. Adjust parsing logic if you were relying on previous whitespace handling or `retry` field parsing behavior.
deprecated Python 3.7 is no longer officially supported as of version 0.4.0. While the library might still function on Python 3.7, it is not tested and compatibility is not guaranteed.
Fix: Upgrade to Python 3.8 or a newer supported version (currently Python 3.8 to 3.11 for stable 0.5.3).
breaking The `option` parameter for `EventSource` initialization was removed.
Fix: Remove the `option` parameter from `EventSource` constructor calls. If specific functionality was handled by `option`, you may need to find alternative ways to configure it or handle it externally.
gotcha The internal session closing behavior for `EventSource` changed in version 0.4.0. The `EventSource.close()` method now explicitly closes the underlying session, rather than relying solely on `__exit__` (used in `with` statements).
Fix: When not using `EventSource` as a context manager (`with EventSource(...)`), ensure you explicitly call `es.close()` to properly release resources and close the HTTP session.

Install

pip install requests-sse Install stable version

Imports

EventSource
```
from requests_sse import EventSource
```
MessageEvent
```
from requests_sse import MessageEvent
```
Typically accessed via an `EventSource` iteration, but can be imported for type hinting or custom handling.

Quickstart

This quickstart demonstrates how to connect to a Server-Sent Events stream using `EventSource` and iterate over incoming `MessageEvent` objects. It uses the `with` statement for proper resource management and shows how to access event properties like `id`, `event` (type), and `data`.

import os
from requests_sse import EventSource

# Example of a public SSE endpoint (Wikimedia recent changes stream)
SSE_ENDPOINT = os.environ.get('SSE_URL', 'https://stream.wikimedia.org/v2/stream/recentchange')

try:
    with EventSource(SSE_ENDPOINT) as es:
        print(f"Connected to SSE stream: {SSE_ENDPOINT}")
        message_count = 0
        for event in es:
            if event.event == "message":
                print(f"Received message: ID={event.id}, Type='{event.type}', Data='{event.data[:100]}...' ")
            else:
                print(f"Received event '{event.event}': ID={event.id}, Data='{event.data[:100]}...' ")
            message_count += 1
            # For demonstration, break after receiving 3 messages
            if message_count >= 3:
                break
except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →