diff --git a/pep-0632.rst b/pep-0632.rst index f04cf762b..03741b482 100644 --- a/pep-0632.rst +++ b/pep-0632.rst @@ -65,7 +65,9 @@ Specification In Python 3.10 and 3.11, distutils will be formally marked as deprecated. All known issues will be closed at this time. -``import distutils`` will raise a deprecation warning. +``import distutils`` will raise a deprecation warning. New issues that +would be considered release blocking may still be fixed, but support +for new tools or platforms will not be added. During Python 3.10 and 3.11, uses of distutils within the standard library may change to use alternative APIs. @@ -149,6 +151,89 @@ for CPython's native module builds without relying on the standard library copy of distutils. +Migration Advice +================ + +.. note:: + This section suggests some alternative replacements for popular + functionality that is being formally deprecated with this PEP. It + is current at time of writing, but is not kept up to date. + +For these modules or types, ``setuptools`` is the best substitute: + +* ``distutils.ccompiler`` +* ``distutils.cmd.Command`` +* ``distutils.command`` +* ``distutils.config`` +* ``distutils.core.Distribution`` +* ``distutils.errors`` + +For these modules or types, use the standards-defined Python Packaging +Authority packages specified: + +* ``distutils.version`` - use ``packaging`` + +For these modules or functions, use the standard library module shown: + +* ``distutils.fancy_getopt`` - use ``argparse`` +* ``distutils.spawn.find_executable`` - use ``shutil.which`` +* ``distutils.spawn.spawn`` - use ``subprocess.run`` +* ``distutils.sysconfig`` - use ``sysconfig`` +* ``distutils.util.get_platform`` - use ``platform`` + +For these functions, and any others not mentioned here, you will need +to reimplement the functionality yourself. The legacy documentation +can be found at https://docs.python.org/3.9/distutils/apiref.html + +* ``distutils.dir_util.create_tree`` +* ``distutils.util.change_root`` +* ``distutils.util.strtobool`` + + +Rejected Ideas +============== + +Deprecate but do not delete +--------------------------- + +The primary concern with this approach is that distutils most +frequently breaks because of platform differences, which means that +without maintenance, it will stop working out-of-sync with any +Python release. This makes it impossible for libraries to reliably +detect when they will stop working. + +In contrast, this PEP proposes a concrete date, known well in advance, +when distutils will stop working, and commits to not breaking the API +before that time. This gives maintainers a predictable schedule, +ensures any breakage occurs at a point where users will already be +expecting changed behavior, and provides a reliable detection +mechanism (specifically, that ``import distutils`` raises). + +Finally, as long as distutils remains in the standard library in any +form, it will interfere with third-party packages that provide shims +or replacements, including setuptools. Completely removing the +package at a known version makes it possible for third-parties to +safely use a substitute. + + +Only deprecate the setuptools-like functionality +------------------------------------------------ + +This suggestion assumes that there exists a volunteer to maintain +whatever is left, which is not true. It also implies that anybody +knows which functionality should remain, which as seen in the +discussions is not at all clear. + +Most helper functions in distutils already have supported (and +improved) alternatives, often in the standard library, and there is +little that can be done to the legacy versions without breaking +compatibility. (And any break requiring maintainers to update their +code is essentially equivalent to requiring them to import a different +function.) + +The last point from the previous section also applies here. + + References ==========