Initial extracted documentation set

2026-06-01 21:42:05 +00:00
commit 60ffec18e4
17 changed files with 1590 additions and 0 deletions
@@ -0,0 +1,53 @@
+# 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