diff --git a/docs/conf.py b/docs/conf.py index 6ac7d2b..e9d5714 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -30,6 +30,7 @@ extensions = [ "sphinx.ext.autodoc", "sphinx.ext.viewcode", + "sphinx.ext.intersphinx", ] html_theme = "furo" diff --git a/docs/index.rst b/docs/index.rst index fc8477f..cd5de4f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -19,6 +19,7 @@ Contents install usage + module-policy Indices and tables diff --git a/docs/module-policy.rst b/docs/module-policy.rst new file mode 100644 index 0000000..36425f3 --- /dev/null +++ b/docs/module-policy.rst @@ -0,0 +1,49 @@ +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 :py:func:`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!