170 lines
6.0 KiB
ReStructuredText
170 lines
6.0 KiB
ReStructuredText
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:
|