setuptools has been the canonical implementation of USE_PYTHON=distutils, namely the direct execution of ${PYSETUP} which is almost always setup.py. While this method continues to work for the most part, the setuptools maintainers have long considered the command line interface fragile and officially deprecated it. Version 58 is the last major version to fully support this interface, particularly the install subcommand, thence afterward unmaintained and acting collateral damage in favour of improved PEP-517 support.
Our USE_PYTHON=distutils has setuptools as both BUILD_DEPENDS and RUN_DEPENDS, which except for specific cases further described, is wrong. Some packages use pkg_resources included with setuptools to programatically reference resources within packages, but even this functionality has been deprecated in favour of importlib_resources, which is present in every supported (as of Q1 2023) Python standard library.
This page describes steps and strategies necessary to manage competing interests wrt setuptools. Packages that have not adopted PEP-517 or importlib_resources need to continue working but port maintainers are strongly encouraged to work with upstreams to modernise. This will also allow for more timely setuptools updates as upstream releases them.
PY_SETUPTOOLS
A new variable ${PY_SETUPTOOLS} will be introduced, in the same vein as variables for other third-party modules like ${PYNUMPY} and ${PY_BOOST}. This variable will provide the correct dependency line for setuptools based on the tooling specified, and is only valid for the port that it is used in.
Removal from RUN_DEPENDS
setuptools will be removed from RUN_DEPENDS to clean up runtime environments and reduce the dependency tree. Ports shall never specify RUN_DEPENDS=${PY_SETUPTOOLS} except in the following cases:
- Leaf ports (no further consumers) that actively use functionality contained in setuptools for core functions not related to Python package management
Helper ports of PEP-517 build backends that use devel/py-setuptools-scm to derive versions from source code management systems (git, mercurial, etc). Other ports shall not specify these as RUN_DEPENDS.
Any consumers not covered by the above exceptions should add BUILD_DEPENDS=${PY_SETUPTOOLS} directly if not USE_PYTHON=distutils. Efforts to remove the run dependency entirely, especially in affected upstream projects, are urged.
Different versions of setuptools cannot exist in the same environment.
devel/py-setuptools58
As setuptools 58 is the last version to support direct execution of ${PYSETUP} per upstream, a new port devel/py-setuptools58 will be introduced, allowing to pin USE_PYTHON=distutils to this version. Packages that have adopted PEP-517 specifying setuptools as the build backend will continue using the main setuptools port, which can then be updated on a more timely basis.
Disable compiling bytecode
${PYDISTUTILS_INSTALLARGS} will change to not compile bytecode. For CPython, a trigger does this automatically, including cleanup.