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:
|