Heuristic:Openai Openai python Streaming Resource Management
| Knowledge Sources | |
|---|---|
| Domains | Optimization, Streaming |
| Last Updated | 2026-02-15 10:00 GMT |
Overview
Always use context managers (`with`/`async with`) for streaming responses and realtime connections to ensure proper resource cleanup; failure to close streams leaks HTTP connections.
Description
The SDK provides `Stream` and `AsyncStream` classes for Server-Sent Events (SSE) streaming, and realtime WebSocket connections via `connect()`. Both hold open network connections that must be explicitly closed. The recommended pattern is to use Python context managers (`with` statement), which automatically close the connection when exiting the block. If context managers cannot be used, the `.close()` method must be called manually. Failing to close streams leads to leaked HTTP connections, which can exhaust the connection pool and cause cascading failures.
Usage
Apply this heuristic whenever you use:
- Streaming chat completions — `client.chat.completions.create(stream=True)`
- Streaming responses — `client.responses.create(stream=True)`
- Realtime connections — `client.beta.realtime.connect()` or `client.realtime.connect()`
- Streaming audio — TTS streaming responses
- Streaming image generation — `client.images.generate(stream=True)`
The Insight (Rule of Thumb)
- Action: Always wrap streaming API calls in a `with` (sync) or `async with` (async) block.
- Value: Automatic cleanup of HTTP connections and WebSocket connections.
- Trade-off: Slightly more indentation in code, but prevents resource leaks.
- Alternative: If context manager doesn't fit your architecture, use `.enter()` to get the connection/stream, then must call `.close()` in a `finally` block.
- SSE protocol detail: Per the SSE spec, `last_event_id` is NOT reset between events — important if implementing custom event tracking.
Reasoning
HTTP streaming connections hold a TCP socket open for the duration of the stream. If the stream object is garbage collected without being closed, the underlying connection remains open until the server times it out or the process exits. With connection pooling (default: 1000 max connections), leaked connections can accumulate and eventually prevent new requests from being made.
WebSocket connections have the same issue but are more critical because they maintain persistent bidirectional communication channels.
Context manager pattern (recommended) from `_streaming.py:104-121`:
class Stream:
def __enter__(self) -> Self:
return self
def __exit__(self, ...):
self.close()
def close(self) -> None:
# Releases the underlying HTTP connection
self.response.close()
Realtime connection warning from `resources/beta/realtime/realtime.py:352`:
# Warning: You must remember to close the connection with `.close()`.
connection = await client.beta.realtime.connect(...).enter()
# ...
await connection.close()
SSE last_event_id from `_streaming.py:338`:
# NOTE: as per the SSE spec, do not reset last_event_id.