Navigating Python Stdlib Docs
When asked about a Python standard library module, follow this lookup pattern:
1. Identify module name (e.g., `os`, `asyncio`, `re`)
2. Check docs.python.org/3/library/<module>.html
3. Note: "Availability" boxes, "Deprecated since", "Changed in version" markers
4. Summarize: purpose, key functions/classes, platform caveats
Example query: "What does os.path do and is it cross-platform?"
Answer: os.path manipulates pathnames; behavior depends on OS (splits into posixpath/ntpath under the hood). Always check the Availability note if present.
Progress:
- Identify the exact module/function being asked about
- Locate the relevant doc conventions (see below)
- Check version compatibility markers
- Check platform-specific availability notes
- Note deprecation status
- Extract minimal working example if present
- Summarize in plain language with a code snippet
Documentation Conventions to Recognize
The Python stdlib docs use standardized markers — always surface these to the user:
- Availability: Unix / Availability: Windows — feature only works on that platform
- Changed in version X.Y — behavior changed; flag if user's Python version predates this
- Deprecated since version X.Y — recommend the replacement instead
- New in version X.Y — don't suggest for code targeting older Python
- Source code links — point to CPython Lib/ source for implementation detail
- Module synopsis line at the top of each page — use as the one-line summary
Structure of a Typical Module Page
- Synopsis (one-line description, right after title)
- Deprecation/availability banner (if applicable)
- Overview / description
- Classes / functions / constants, alphabetically or logically grouped
- Examples section (not all modules have one)
- "See also" cross-references to related modules
Example 1:
Input: "Is os.fork() available on Windows?"
Output: "No. os.fork() has an Availability: Unix note in the docs — it raises OSError on Windows. Use multiprocessing for a cross-platform alternative."
Example 2:
Input: "What's the difference between asyncio.get_event_loop() behavior in 3.16 vs older versions?"
Output: "Check the 'Changed in version' and 'Deprecated since' annotations on that function's doc entry — get_event_loop() has had deprecation warnings evolve across 3.10–3.12 for creating loops implicitly. Always quote the exact version note rather than assuming behavior is unchanged."
Example 3:
Input: "Summarize the pathlib module."
Output: "pathlib — Object-oriented filesystem paths. Synopsis: 'Object-oriented filesystem paths.' Provides Path (and PurePath) classes representing filesystem paths with methods like .exists(), .glob(), .read_text(). Cross-platform: PosixPath/WindowsPath subclasses chosen automatically via Path(). Preferred over os.path in modern code."
- Always quote the synopsis line verbatim when introducing a module — it's the canonical one-sentence description.
- Surface availability/version caveats proactively, don't wait to be asked.
- When multiple modules solve the same problem (e.g.,
os.pathvspathlib,urllibvsrequests), state the docs' recommended modern choice. - Link conceptually to "See also" sections to help users find adjacent tools.
- For version-numbered docs (e.g., "3.16"), treat it as the target reference — don't silently assume the user's runtime matches; ask or infer from context if a mismatch could matter.
- Don't state a module is deprecated without checking — verify against the "Deprecated since" marker, not memory.
- Don't ignore platform-specific Availability notes when giving code examples that must run cross-platform.
- Don't confuse module deprecation with function/parameter deprecation — they're marked separately.
- Don't assume behavior is identical across Python versions when a "Changed in version" note exists between the user's version and the doc version.
- Don't fabricate function signatures — if uncertain, say so rather than guessing parameter names.