Add draft name inclusion policy

Author: thatch

docs/inclusion.rst

@@ -0,0 +1,58 @@
+Name Inclusion
+==============
+
+Because of how fundamental name membership is, we hope to not meaningfully
+change this often.  Simply put, Python is "batteries included" and these are the
+names of the batteries that you might expect your interpreter to come with.
+
+    Tenet 1: The intended use is platform- and version-agnostic import
+    classification, whether that's for sorting or dependency analysis.
+
+The primary goal is to be able to examine an import statement and decide whether
+that import is referencing code that the user doesn't need to install
+separately, for example from an import sorter to separate a "stdlib" block from
+a "third-party" block, or a tool like `checkdeps`_ to know that a name doesn't
+need to be attributed to a third-party project.
+
+.. checkdeps: https://pypi.org/project/checkdeps/
+
+For almost all real-world cases, this means we only need to examine the
+top-level name, which is simpler to store and query.  Although namespace
+packages can affect what project a full name is attributed to, it doesn't
+generally change its third-partiness.
+
+You also don't need to even query for relative imports, and what the relative
+import "evaluates to" doesn't matter.
+
+A slightly more formal definition is:
+
+    Any top-level name that is supplied with an installed cpython interpreter
+    compiled with standard flags on some platform (doesn't have to be your
+    current one), unless its utility is completely outweighed by its danger.
+
+Calling out a few important things there:
+
+* It doesn't matter where you run ``stdlibs`` -- it takes a union view of all
+  possible platforms and system dependencies being available.
+* Even if your particular install doesn't come with ``_bzip2.so`` because of a
+  missing dependency, it's still one of the batteries.
+* We only handle cpython, and only vanilla for now, but that's out of
+  disinterest rather than principle.  If Microsoft offered a Python on its app
+  store that came with an additional (definitively not third-party) module, we
+  would probably include it.
+* We don't particularly care whether a name is a python module, compiled module,
+  package, etc.  If an import could theoretically succeed, that's enough.  A
+  little more explicitly, if someday there is a ``.pth`` file that makes an
+  import work, we would probably include its name.
+* We differ from ``sys.stdlib_module_names`` in that we include "test" modules
+  for historical and simplicity reasons.  They're installed on most Python
+  distributions, so meet the criteria for inclusion here.  See
+  `generate_stdlib_module_names.py`_ and some discussion on `issue 127484`_.
+* That said, we're willing to exclude names based on their lack of usefulness
+  from the perspective of import classification -- when we started this project,
+  python 2.7 was already obsolete and included a *dir* called ``test``.  Almost
+  all real-world code that does an ``import test`` would be a first-party
+  import, and this is a choice name that people do use.
+
+.. _generate_stdlib_module_names.py: https://github.com/python/cpython/blob/main/Tools/build/generate_stdlib_module_names.py
+.. _issue 127484: https://github.com/python/cpython/issues/127484

docs/index.rst

@@ -5,5 +5,6 @@
     :maxdepth: 1
 
     api
+    inclusion
     changelog