setuptools has been the canonical implementation of USE_PYTHON=distutils, namely the direct execution of ${PYSETUP} which is almost always setup.py. The setuptools maintainers have long considered the command line interface fragile and officially deprecated it in version 58. While the interface still works in the latest versions, its presence is acting collateral damage against improved PEP-517 support.
Our USE_PYTHON=distutils traditionally 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 for 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.
Please file PRs for leaf ports (no further consumers) that actively use functionality contained in setuptools for core functions not related to Python package management and CC python@. Efforts to remove the run dependency entirely, especially in affected upstream projects, are urged.
Any consumers not covered by the above exceptions should add BUILD_DEPENDS=${PY_SETUPTOOLS} directly if not USE_PYTHON=distutils.
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 was to 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.
As of devel/py-pyproject_hooks 1.1, this part is being abandoned. pyproject-hooks is required to build all setuptools versions under PEP-517, and 1.1 introduced a slew of breaking changes that renders devel/py-setuptools58 inoperable at both build and runtime.
Disable compiling bytecode
${PYDISTUTILS_INSTALLARGS} will change to not compile bytecode. For CPython, a trigger does this automatically, including cleanup.