AI Skill Report Card
Checking Platform Availability
Markdown--- name: checking-platform-availability description: Determines and documents platform availability constraints for Python standard library modules and features, following the conventions used in CPython documentation. Use when writing or reviewing "Availability" notes for docs, deciding whether code relying on platform-specific APIs is portable, or auditing modules for Unix/Windows/macOS/mobile/WASI/free-threading support. ---
Quick Start13 / 15
When documenting or evaluating a module/function that depends on OS or build-specific features, produce an availability note in this form:
Availability: Unix, Windows.
or with detail:
Availability: Unix, not Emscripten, not WASI.
This function is not available on Emscripten or WASI, see
:ref:`wasm-availability` for more information.
Rule of thumb: state the positive set of supported platforms first; if exceptions exist within a broad platform (e.g. "Unix but not this specific flavor"), add explicit not X clauses.
Recommendation▾
Add a 'bad output' example (e.g., vague 'most platforms' note) contrasted with the corrected version to reinforce pitfalls
Workflow14 / 15
Progress:
- Identify what platform-gated behavior is involved (syscall, header, library, hardware, build option)
- Classify against the standard availability categories (see below)
- Check for known exceptions within a category (specific Unix variants, mobile restrictions, WASI/Emscripten sandboxing)
- Check build-time gating (e.g., free-threaded builds, optional modules)
- Write the note using standard phrasing
- Add a explanatory sentence + cross-reference if the restriction is non-obvious
- Verify against CPython source (
Doc/library/,configure.ac,#ifdefguards) if precision matters
Standard availability categories
- Unix — general POSIX-like systems. If only some Unixes support it, name them or say "most Unix systems, see specific platform note."
- Windows
- macOS — sometimes distinct from generic Unix due to Darwin-specific behavior.
- Linux — used when a feature is genuinely Linux-only (e.g.
/proc, epoll,sendfileflags). - Emscripten, WASI — WebAssembly targets; frequently excluded rather than included, since these sandboxes lack process/thread/networking primitives. Reference
wasm-availabilityfor details. - iOS, Android — mobile platforms; often excluded from filesystem, subprocess, or multiprocessing features due to OS sandboxing.
- GNU/kFreeBSD, NetBSD, etc. — named explicitly only when behavior diverges from generic Unix.
- free-threaded build — call out when a feature behaves differently or is unavailable under
Py-GIL-disabledbuilds.
Phrasing template
Availability: <supported list>[, not <excluded list>].
<Optional: one-sentence reason>, see :ref:`<cross-ref>` for more information.
Recommendation▾
Include a real-world edge case like a feature whose availability changed across Python versions to show version-sensitivity handling in practice
Examples16 / 20
Example 1:
Input: os.fork() behavior note needed.
Output:
Availability: Unix, not Emscripten, not WASI, not iOS.
See :ref:`wasm-availability` for more information on WASM platforms.
Example 2:
Input: winreg module.
Output:
Availability: Windows.
Example 3:
Input: socket.SO_REUSEPORT constant.
Output:
Availability: Unix. Not available on all Unix platforms; check with
``hasattr(socket, "SO_REUSEPORT")``.
Example 4: Input: A feature that works everywhere except under free-threaded builds where it silently degrades. Output:
Availability: all platforms.
On the free-threaded build, this function acquires an internal lock,
which may affect performance under high contention.
Recommendation▾
Tighten the Best Practices and Common Pitfalls sections—some overlap exists (e.g., WASI/Emscripten mentioned in both) and could be merged for conciseness
Best Practices
- Prefer the exact platform names used in CPython docs (
Unix,Windows,macOS,Linux,Emscripten,WASI,iOS,Android) rather than inventing new labels. - Always check
hasattr/sys.platformguidance if runtime detection is more reliable than static docs (many POSIX features vary by libc). - When multiple exclusions exist, list them together after the main clause, each prefixed with
not. - Link to
wasm-availabilitywhenever Emscripten/WASI are excluded — don't just state the exclusion without explanation, since sandboxing reasons aren't obvious to readers. - For mobile (iOS/Android), note why — usually sandboxing, lack of subprocess spawning, or restricted filesystem access.
- Distinguish "not implemented" from "not applicable": some features are meaningless on a platform (e.g.,
os.setuidon Windows) rather than merely unported. - When auditing existing code for portability, search for
#ifdefguards andsys.platform ==checks as ground truth, not just docstrings.
Common Pitfalls
- Don't write "Availability: most platforms" without enumerating exceptions — always be explicit.
- Don't conflate "Unix" with "Linux" — a feature using
/procorepollis Linux-specific, not general Unix. - Don't omit WASI/Emscripten exclusions for anything touching threads, processes, sockets, or file locking — these are almost always unsupported there.
- Don't assume macOS behaves like generic Unix for filesystem case-sensitivity, sandboxing, or fork safety — call it out separately when relevant.
- Don't forget free-threaded build caveats for modules dealing with the GIL, C extension state, or module-level singletons.
- Don't state availability without verifying against current source; availability changes across versions (e.g., features later ported to Windows or gaining WASI support).