Module inclusion policy

Python is a dynamic language with a complex module system, including modules that are created only at runtime or appear on specific supported platforms.

This page exists to document stdlib-list’s approach to module detection and subsequent inclusion. It is not intended to be permanent, and may change over time as Python itself changes (or our approach to module detection improves).

Current guiding rules

  • Missing top-level modules are a bug: if a new version of Python adds a new top-level module, our failure to detect it should be considered a bug.

    Concretely: if examplemodule is present in Python 3.999, then it should be included in the stdlib_list("3.999") listing.

  • Missing sub-modules are best-effort: if examplemodule contains examplemodule.foo.bar.baz.deeply.nested, we make a best-effort attempt to detect each inner module but make no guarantee about doing so.

    Our rationale for this is that “stdlib-ness” is inherited from the parent module, even when not explicitly listed. In other words: anything that matches examplemodule.* is in the standard library by definition so long as examplemodule is in the standard library.

  • Platform-specific modules are best-effort: stdlib-list is currently collected from Linux builds of CPython. This means that Windows- and macOS-specific modules (i.e., modules that aren’t installed except for on those hosts) are not necessarily included.

    This includes top-level modules.

  • Missing non-CPython modules are not supported: stdlib-list is implicitly a list of CPython’s standard library modules, which are expected to be mirrored in other implementations of Python.

  • Psuedo-modules are not supported: Python sometimes makes use of “pesudo-modules”, i.e. namespaces placed into sys.modules that don’t pass inspect.ismodule(). We don’t currently support these, since the semantics for doing so are unclear. See stdlib-list#117 for additional details.

If you have a scenario not covered by the rules above, please file an issue!