PEP 0632: Deprecate distutils module (#1581)

pep-0632.rst

@@ -0,0 +1,169 @@
+PEP: 632
+Title: Deprecate distutils module
+Author: Steve Dower <steve.dower@python.org>
+Status: Draft
+Type: Standards Track
+Content-Type: text/x-rst
+Created: 03-Sep-2020
+Post-History: 
+
+
+Abstract
+========
+
+The distutils module [1]_ has for a long time recommended using the
+setuptools package [2]_ instead. Setuptools has recently integrated a
+complete copy of distutils and is no longer dependent on the standard
+library [3]_. Pip has silently replaced distutils with setuptools when
+building packages for a long time already. It is time to remove it
+from the (public part of the) standard library.
+
+
+Motivation
+==========
+
+distutils [1]_ is a largely undocumented and unmaintained collection
+of utilities for packaging and distributing Python packages, including
+compilation of native extension modules. It defines a configuration
+format that describes a Python distribution and provides the tools to
+convert a directory of source code into a source distribution, and
+some forms of binary distribution. Because of its place in the
+standard library, many updates can only be released with a major
+release, and users cannot rely on particular fixes being available.
+
+setuptools [2]_ is a better documented and well maintained enhancement
+based on distutils. While it provides very similar functionality, it
+is much better able to support users on earlier Python releases, and
+can respond to bug reports more quickly. A number of platform-specific
+enhancements already exist in setuptools that have not been added to
+distutils, and there is been a long-standing recommendation in the
+distutils documentation to prefer setuptools.
+
+Historically, setuptools has extended distutils using subclassing and
+monkeypatching, but has now taken a copy of the underlying code. [3]_
+As a result, the second last major dependency on distutils is gone and
+there is no need to keep it in the standard library.
+
+The final dependency on distutils is CPython itself, which uses it to
+build the native extension modules in the standard library (except on
+Windows). Because this is a CPython build-time dependency, it is
+possible to continue to use distutils for this specific case without
+it being part of the standard library.
+
+Deprecation and removal will make it obvious that issues should be
+fixed in the setuptools project, and will reduce a source of bug
+reports and test maintenance that is unnecessary. It will also help
+promote the development of alternative build backends, which can now
+be supported more easily thanks to PEP 517.
+
+
+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.
+
+During Python 3.10 and 3.11, uses of distutils within the standard
+library may change to use alternative APIs.
+
+In Python 3.12, distutils will no longer be installed by ``make
+install`` or any of the first-party distribution. Third-party
+redistributors should no longer include distutils in their bundles or
+repositories.
+
+This PEP makes no specification on migrating the parts of the CPython
+build process that currently use distutils. Depending on
+contributions, this migration may occur at any time.
+
+After Python 3.12 is started and when the CPython build process no
+longer depends on distutils being in the standard library, the entire
+``Lib/distutils`` directory and ``Lib/test/test_distutils.py`` file
+will be removed from the repository.
+
+Other references to distutils will be cleaned up. As of Python 3.9's
+initial release, the following modules have references in code or
+comments:
+
+* Lib/ctypes/util.py
+* Lib/site.py
+* Lib/sysconfig.py
+* Lib/_aix_support.py
+* Lib/_bootsubprocess.py
+* Lib/_osx_support.py
+* Modules/_decimal/tests/formathelper.py
+
+As the distutils code is already included in setuptools, there is no
+need to republish it in any other form. Those who require access to
+the functionality should use setuptools or an alternative build
+backend.
+
+Backwards Compatibility
+=======================
+
+Code that imports distutils will no longer work from Python 3.12.
+
+The suggested migration path is to use the equivalent (though not
+identical) imports from setuptools.
+
+Compatibility shims already exist in setuptools and pip to
+transparently migrate old code, however, these are controlled by
+external projects and are in no way bound by this PEP. Consult their
+latest documentation for migration advice.
+
+Some projects use alternate sets of shims over distutils, notably,
+numpy.distutils. [4]_ Where known, these projects have been informed.
+
+Many use custom commands or more narrowly scoped patches, mostly
+constrained to ``setup.py`` files. As these packages are already
+subject to setuptools being injected by pip, we expect minimal
+disruption as a result of distutils being removed.
+
+
+Reference Implementation
+========================
+
+setuptools version 48 includes the complete copy of distutils, and as
+such is no longer dependent on the standard library's copy. Most
+implementation issues they have faced are due to the continuing
+existence of distutils in the standard library, and so removal will
+improve the stability of their implementation.
+
+There is not yet a reference implementation for the removal of
+distutils from the standard library, nor is there an implementation
+for CPython's native module builds without relying on the standard
+library copy of distutils.
+
+
+References
+==========
+
+.. [1] distutils - Building and installing Python modules
+   (https://docs.python.org/3.9/library/distutils.html)
+
+.. [2] setuptools - PyPI
+   (https://pypi.org/project/setuptools/)
+
+.. [3] setuptools Issue #417 - Adopt distutils
+   (https://github.com/pypa/setuptools/issues/417)
+
+.. [4] Packaging (numpy.distutils)
+   (https://numpy.org/doc/stable/reference/distutils.html)
+
+
+Copyright
+=========
+
+This document is placed in the public domain or under the
+CC0-1.0-Universal license, whichever is more permissive.
+
+
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   coding: utf-8
+   End: