Why docs do not use context manager for several examples

[ltoniazzi]

I was wondering why, for example, the Async client with httpx example does not use a context manager (here), meanwhile, the aiothhp example does here .

Both cases should clean up clients right? Or the first case is just trying to simplify the code presentation?

[xXMrNidaXx]

Context managers in docs — great question!

Why docs often skip them:

1. Simplicity for examples

# Docs prioritize clarity
client = OpenAI()
response = client.chat.completions.create(...)

# vs more verbose
with OpenAI() as client:
    response = client.chat.completions.create(...)

2. HTTP client reuse

# OpenAI client handles connection pooling
# Context manager not strictly needed for basic use
client = OpenAI()  # Connections managed internally

When to use context manager:

# 1. Explicit cleanup
with OpenAI() as client:
    # Client closed after block
    response = client.chat.completions.create(...)

# 2. Async with proper cleanup
async with AsyncOpenAI() as client:
    response = await client.chat.completions.create(...)

# 3. Testing/short scripts
with OpenAI() as client:
    # Ensures cleanup even on error
    ...

Best practice for production:

# Long-running app: create once, reuse
client = OpenAI()

# Short script: context manager is fine
with OpenAI() as client:
    ...

We use both patterns at RevolutionAI depending on context. Docs could definitely show more context manager examples for completeness!

[christiansousadev]

Hi @ltoniazzi,

This is a subtle but critical point regarding Resource Governance.

Documentation often prioritizes "Readability" over "Production Resilience". By omitting the context manager (with / async with), the example stays on a single indentation level, making it easier for a beginner to copy-paste into a REPL or a Jupyter Notebook without worrying about indentation errors.

However, from an Architectural standpoint, here is why this matters:

Socket Exhaustion: When you initialize an AsyncOpenAI client (which uses httpx under the hood) without a context manager, the underlying connection pool might not be closed immediately after the script finishes or the request ends. In high-concurrency environments (like a FastAPI microservice), failing to explicitly close the client can lead to a "leak" of open file descriptors/sockets.

The aiohttp vs httpx discrepancy: aiohttp is historically more "strict" about session management. It will often throw a RuntimeWarning if a session is left open. httpx (used by OpenAI) is more "forgiving" in simple scripts, but in a Production Governance context, both should be treated with the same rigor.

Best Practice Recommendation:

For any Production-grade Python application, you should follow the "Singleton or Context" rule:

For Long-running Apps (FastAPI/Lifespan): Initialize the client once during startup, store it in the app.state, and close it during shutdown. This ensures proper Connection Pooling and reuse.

For Scripts/Tasks: Always use the context manager to ensure the aexit logic triggers the cleanup of the transport layer, especially if an exception occurs.

Python

Governance-first approach for short tasks

async with AsyncOpenAI() as client:
try:
response = await client.chat.completions.create(...)
except Exception as e:
logger.error(f"Audit failure: {e}")
raise

Transport is guaranteed to close here

The documentation simplifies the "presentation layer," but as developers, we must implement the "governance layer" by ensuring every resource we open is explicitly accounted for and closed.