python-patterns/sources/cpython.md

CPython source notes

Repo: python/cpython Local checkout: /home/ubuntu/repos/rodin-sources/cpython

Why this repo is useful

• CPython is a strong source for patterns that survive long-term compatibility pressure.
• It is especially useful for API-boundary choices and error-shape choices because stdlib modules must stay understandable to a huge caller base.
• Caveat: stdlib code is not stylistically uniform. Treat repeated shapes across modules as signal; do not treat a single module's convention as "the Python way."

Public API boundaries are often declared explicitly

Repeated evidence

• Lib/operator.py:13-20 declares a tight __all__ list instead of exporting every helper or alias in the module namespace.
• Lib/smtplib.py:55-58 does the same for the SMTP module, listing public exceptions and the SMTP client.
• Lib/warnings.py:3-18 likewise enumerates the supported warning helpers instead of relying on incidental module globals.

Why it matters

Repeated signal: when a module has helper names, aliases, or internal scaffolding, CPython often freezes the supported surface explicitly. That makes the public API a maintained decision rather than an accident of file layout.

Caveat / counterexample

This is common, not universal. Some stdlib modules still expose names without a curated __all__, so the useful pattern is not "always add __all__" but "use it when the file contains more than the intended public surface."

Exception trees are shaped around recovery needs, not just taxonomy

Repeated evidence

• Lib/smtplib.py:69-71 defines SMTPException as the broad catch point for the module.
• Lib/smtplib.py:73-86 adds semantic subtypes for unsupported commands and disconnected-session failures.
• Lib/smtplib.py:88-100 defines SMTPResponseException and stores structured payload on the exception itself via smtp_code and smtp_error.
• Lib/smtplib.py:102-125 and Lib/smtplib.py:128-142 narrow further into sender, recipient, data, connect, HELO, and auth failures.

Why it matters

Repeated signal: CPython exception trees usually give callers two useful options at once:

• catch broadly at the subsystem boundary, or
• branch narrowly on structured failure data when recovery differs.

This is stronger than a flat set of unrelated exception classes and stronger than raising plain OSError/ValueError with message parsing.

Resource-owning helpers usually make lifetime visible

Repeated evidence

• Lib/contextlib.py:31-43 defines the abstract context-manager protocol directly in the stdlib.
• Lib/tempfile.py:487-539 wraps temporary files so __enter__ returns the wrapper and __exit__ guarantees cleanup.
• Lib/tempfile.py:758-761 also guards context entry on closed temporary files, showing that lifetime rules are enforced, not just documented.

Why it matters

Repeated signal: when a stdlib helper owns cleanup-sensitive state, CPython prefers explicit context-manager boundaries over ambient cleanup assumptions.

Pattern candidates supported by this repo

• declare public module surfaces explicitly when helper names would otherwise leak
• build exception hierarchies around caller recovery paths
• attach structured data to exceptions when callers need to branch without string parsing
• make resource lifetime obvious with context-manager boundaries