From 7ffe2d5fc2bce4bbf9a3c75b6bb091805f33ab55 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Wed, 28 Aug 2024 10:52:37 +0100 Subject: [PATCH] Document convention on compat modules --- docs/development/developer-guide.rst | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/development/developer-guide.rst b/docs/development/developer-guide.rst index 4566fef8d0..00cd3ff2e2 100644 --- a/docs/development/developer-guide.rst +++ b/docs/development/developer-guide.rst @@ -132,6 +132,30 @@ To refresh the dependencies, run the following command:: $ tox -e vendor + +--------------------- +Compatibility Modules +--------------------- + +Setuptools organises its own internal polyfills, backports, version conditional +imports and workarounds into a series of separated modules under the +``setuptools.compat`` package. These modules provide compatibility layers or +shims that ensure code runs smoothly across different Python versions. + +These modules are named to reflect the version of Python that requires the +legacy behavior. For example, the module ``setuptools.compat.py310`` supports +compatibility with Python 3.10 and earlier. +This naming convention is beneficial because it signals when the code +can be removed. When support for Python 3.10 is dropped (i.e., when +``requires-python = ">=3.11"`` is added to ``pyproject.toml``), +imports of the module ``py310`` will be easily identifiable as removable debt. + +Please note that these modules are implementation details of ``setuptools`` and +not part of the public API. The naming convention is documented above as a +guide for ``setuptools`` developers. There is no guarantee regarding the +stability of these modules and they should not be used in 3rd-party projects. + + ---------------- Type annotations ----------------