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.

[yousufkidiya17]

"Question: Why docs do not use context manager for several examples?\n\n---\n\n## Short answer\n\nBecause most examples are one-shot snippets: open client \u2192 make 1 call \u2192 print. A context manager only pays for itself when you have resource cleanup (files, sessions, locks) or want to guarantee teardown on exceptions. A network client doesn't leak if the process exits right after.\n\n## The real distinction\n\nThe OpenAI SDK client:\n- Holds a connection pool (httpx.Client under the hood).\n- With with client: (i.e. client.close()), the pool is explicitly shut down, which is polite in long-lived processes (servers, notebooks that run many cells).\n- In a short script, the OS reclaims everything at process exit, so with is optional \u2014 that's why examples skip it.\n\n## Where you should use a context manager\n\npython\n# Long-lived: server, worker, notebook\nfrom openai import OpenAI\n\nwith OpenAI() as client: # closed cleanly when done\n resp = client.chat.completions.create(\n model=\"gpt-4o-mini\",\n messages=[{\"role\": \"user\", \"content\": \"hi\"}],\n )\n print(resp.choices[0].message.content)\n\n\nFor a persistent client (one client for the whole app), don't open/close per request \u2014 keep one instance and close it in your app's shutdown hook instead:\n\npython\nclient = OpenAI() # reuse everywhere\n\n# on shutdown (FastAPI lifespan / atexit):\n# client.close()\n\n\n## TL;DR\n\nDocs use plain OpenAI() because the examples are disposable scripts; context managers are about deterministic cleanup, which only matters when the client outlives a single call.\n\n---"

[yousufkidiya17]

Draft — Answer for Discussion #2779

Question: Why docs do not use context manager for several examples?

---

Short answer

Because most examples are one-shot snippets: open client → make 1 call → print. A context manager only pays for itself when you have resource cleanup (files, sessions, locks) or want to guarantee teardown on exceptions. A network client doesn't leak if the process exits right after.

The real distinction

The OpenAI SDK client:

• Holds a connection pool (httpx.Client under the hood).
• With with client: (i.e. client.close()), the pool is explicitly shut down, which is polite in long-lived processes (servers, notebooks that run many cells).
• In a short script, the OS reclaims everything at process exit, so with is optional — that's why examples skip it.

Where you should use a context manager

# Long-lived: server, worker, notebook
from openai import OpenAI

with OpenAI() as client:          # closed cleanly when done
    resp = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "hi"}],
    )
    print(resp.choices[0].message.content)

For a persistent client (one client for the whole app), don't open/close per request — keep one instance and close it in your app's shutdown hook instead:

client = OpenAI()  # reuse everywhere

# on shutdown (FastAPI lifespan / atexit):
# client.close()

TL;DR

Docs use plain OpenAI() because the examples are disposable scripts; context managers are about deterministic cleanup, which only matters when the client outlives a single call.

---