aiohttp-sse

2.2.0 verified Wed Apr 15 auth: no python

aiohttp-sse provides server-sent events support for aiohttp. It allows building real-time web applications where the server pushes updates to clients over a single HTTP connection. The current version is 2.2.0, and it has a relatively active release cadence with several updates per year, focusing on Python and aiohttp compatibility.

pip install aiohttp-sse

Common errors

error ModuleNotFoundError: No module named 'aiohttp_sse' ↓

cause The 'aiohttp-sse' package is not installed in the Python environment.

fix

Install the package using pip: 'pip install aiohttp-sse'.

error ImportError: cannot import name 'EventSourceResponse' from 'aiohttp_sse' ↓

cause The 'EventSourceResponse' class is not available in the 'aiohttp_sse' module.

fix

Use 'sse_response' instead: 'from aiohttp_sse import sse_response'.

error AttributeError: 'EventSourceResponse' object has no attribute 'send' ↓

cause The 'EventSourceResponse' object does not have a 'send' method.

fix

Use 'sse_response' which provides the 'send' method: 'from aiohttp_sse import sse_response'.

error ModuleNotFoundError: No module named 'aiohttp-sse' ↓

cause The `aiohttp-sse` library is not installed in your Python environment or is not accessible on the Python path.

fix

Install the library using pip: pip install aiohttp-sse

error AttributeError: module 'aiohttp' has no attribute 'ClientSession' ↓

cause This typically occurs when you have a file named `aiohttp.py` in your project directory, which shadows the actual `aiohttp` library, or if you are trying to use an outdated API for `aiohttp` client requests.

fix

Rename any local file named aiohttp.py to something else (e.g., my_aiohttp_app.py). Ensure you are using aiohttp.ClientSession() for client requests, as direct aiohttp.get() was deprecated.

Warnings

breaking Python version support has been frequently dropped in major and minor releases. Version 2.2.0 dropped Python 3.7, and 2.1.0 dropped Python 3.6 support. Ensure your Python environment meets the `>=3.8` requirement for current versions. ↓

fix Upgrade Python to 3.8 or newer, or pin to an older `aiohttp-sse` version compatible with your Python environment.

breaking Major versions of `aiohttp-sse` are tied to specific `aiohttp` versions. Version 2.0.0 introduced compatibility with `aiohttp 3.0+`, while older versions like 1.0.0 required `aiohttp2+`, and 0.1.0 was for `aiohttp<2.0`. Mismatched `aiohttp` versions can lead to runtime errors. ↓

fix Check the `aiohttp-sse` release notes for the exact `aiohttp` version compatibility. Upgrade both `aiohttp-sse` and `aiohttp` to compatible versions.

gotcha Browsers keep the tab's loading spinner active as long as an SSE connection remains open, which can be confusing for users. ↓

fix Send an initial 'comment' event (e.g., `await resp.send(None, event='comment', data='connected')`) after establishing the SSE connection. This signals the browser that the connection is live and usually stops the spinner.

gotcha Prior to v2.2.0, specifically on Python 3.11+, the `EventSourceResponse.wait()` method could swallow user cancellation, making it difficult to gracefully shut down SSE streams. ↓

fix Upgrade to `aiohttp-sse` version 2.2.0 or newer to benefit from the fix for `EventSourceResponse.wait()` cancellation behavior on Python 3.11+.

gotcha `aiohttp` itself does not natively provide client-side Server-Sent Events parsing. Users attempting to consume `aiohttp-sse` streams with a plain `aiohttp.ClientSession` might find parsing challenging. ↓

fix For client-side SSE consumption, consider using dedicated libraries like `aiohttp-sse-client` or `aiosseclient` built on top of `aiohttp`, or implement custom parsing logic.

gotcha Web browsers often impose a limit (e.g., 6) on the number of concurrent HTTP connections to a single domain. Exceeding this limit with multiple SSE connections can cause new requests to hang or time out. ↓

fix Design client-side applications to manage and reuse SSE connections efficiently. Avoid opening an excessive number of simultaneous SSE streams from the same client to the same server. Adjusting browser settings (e.g., `network.http.speculative-parallel-limit` in Firefox) can also be done for testing, but is not a general solution for users.

Imports

sse_response
```
from aiohttp_sse import sse_response
```

EventSourceResponse

from aiohttp_sse import EventSourceResponse

Quickstart

This quickstart sets up an aiohttp web server that serves an HTML page. The HTML page contains JavaScript that connects to a '/hello' endpoint via Server-Sent Events. The '/hello' endpoint uses `aiohttp-sse`'s `sse_response` context manager to continuously send the current server time to the connected client.

import asyncio
import json
from datetime import datetime
from aiohttp import web
from aiohttp_sse import sse_response

async def hello(request: web.Request) -> web.StreamResponse:
    async with sse_response(request) as resp:
        # Optional: send an initial comment to stop browser loading spinner
        await resp.send(None, event='comment', data='connected')
        while resp.is_connected():
            time_dict = {"time": f"Server Time : {datetime.now()}"}
            data = json.dumps(time_dict, indent=2)
            print(data)
            await resp.send(data)
            await asyncio.sleep(1)
    return resp

async def index(_request: web.Request) -> web.Response:
    html = """
<html>
<body>
    <script>
        var eventSource = new EventSource("/hello");
        eventSource.addEventListener("message", event => {
            document.getElementById("response").innerText = event.data;
        });
    </script>
    <h1>Response from server:</h1>
    <div id="response"></div>
</body>
</html>
"""
    return web.Response(text=html, content_type="text/html")

app = web.Application()
app.router.add_route("GET", "/hello", hello)
app.router.add_route("GET", "/", index)

if __name__ == '__main__':
    web.run_app(app, host="127.0.0.1", port=8080)