Rodin
54 lines
3.3 KiB
Markdown
54 lines
3.3 KiB
Markdown
# 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
|