190 lines
6.9 KiB
ReStructuredText
190 lines
6.9 KiB
ReStructuredText
PEP: 632
|
||
Title: Deprecate distutils module
|
||
Author: Steve Dower <steve.dower@python.org>
|
||
Discussions-To: https://discuss.python.org/t/pep-632-deprecate-distutils-module/5134
|
||
Status: Draft
|
||
Type: Standards Track
|
||
Content-Type: text/x-rst
|
||
Created: 03-Sep-2020
|
||
Python-Version: 3.10
|
||
Post-History: 03-Sep-2020
|
||
|
||
|
||
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:
|