python-peps/pep-0632.rst

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 been silently replacing distutils with
setuptools when installing packages for a long time already, and the
distutils documentation has stated that it is being phased out since
2014 (or earlier). It is time to remove it from 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 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 unnecessary test maintenance. It will also help promote
the development of alternative build backends, which can now be
supported more easily thanks to PEP 517. [4]_


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

The following Tools in CPython also refer to distutils. Note that none
of these are installed with CPython:

* PC/layout (references will be removed)
* Tools/msi (references will be removed)
* Tools/peg_generator (will be adapted to a different build tool)
* Tools/test2to3 (example project will be removed)

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 (see [5]_), or to migrate to an
alternative build backend (see PEP 517 [4]_).

Code already exists in setuptools to transparently switch ``setup.py``
files using distutils onto their equivalents, and so most working
build scripts are already known to work with setuptools. Such scripts
may need to update their import statements. Consult the setuptools
documentation for specific migration advice. [5]_

Some projects use alternate sets of patches over distutils, notably,
numpy.distutils. [6]_ Projects that we know are doing this have been
informed.

Many build scripts use custom commands or narrowly scoped patches. As
these packages are already subject to setuptools overriding distutils,
we expect minimal disruption as a result of distutils being removed.
Scripts may still need to be updated to avoid importing distutils.


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] PEP 517 - A build-system independent format for source trees
   (https://www.python.org/dev/peps/pep-0517/)

.. [5] Porting from Distutils
   (https://setuptools.readthedocs.io/en/latest/distutils-legacy.html)

.. [6] 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: