# 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