bpo-41282: Add deprecation warning and docs for distutils (PEP 632) (GH-24355)

4 files changed, 35 insertions, 0 deletions

diff --git a/Doc/distutils/index.rst b/Doc/distutils/index.rst
index 1f72a255424..2ccddc38b5f 100644
--- a/Doc/distutils/index.rst
+++ b/Doc/distutils/index.rst
@@ -12,6 +12,13 @@
    :ref:`distributing-index`
       The up to date module distribution documentations
 
+.. note::
+
+   The entire ``distutils`` package has been deprecated and will be
+   removed in Python 3.12. This documentation is retained as a
+   reference only, and will be removed with the package. See the
+   :ref:`What's New <distutils-deprecated>` entry for more information.
+
 .. include:: ./_setuptools_disclaimer.rst
 
 .. note::
diff --git a/Doc/install/index.rst b/Doc/install/index.rst
index e6d5a3e6ebd..b6b7085fb35 100644
--- a/Doc/install/index.rst
+++ b/Doc/install/index.rst
@@ -10,6 +10,13 @@
 
 .. TODO: Fill in XXX comments
 
+.. note::
+
+   The entire ``distutils`` package has been deprecated and will be
+   removed in Python 3.12. This documentation is retained as a
+   reference only, and will be removed with the package. See the
+   :ref:`What's New <distutils-deprecated>` entry for more information.
+
 .. seealso::
 
    :ref:`installing-index`
diff --git a/Doc/library/distutils.rst b/Doc/library/distutils.rst
index 62abc85ac39..31c4ae5b239 100644
--- a/Doc/library/distutils.rst
+++ b/Doc/library/distutils.rst
@@ -9,6 +9,11 @@
 
 --------------
 
+:mod:`distutils` is deprecated with removal planned for Python 3.12.
+See the :ref:`What's New <distutils-deprecated>` entry for more information.
+
+--------------
+
 The :mod:`distutils` package provides support for building and installing
 additional modules into a Python installation.  The new modules may be either
 100%-pure Python, or may be extension modules written in C, or may be
diff --git a/Doc/whatsnew/3.10.rst b/Doc/whatsnew/3.10.rst
index 16bb8fb2817..cf7d1e80758 100644
--- a/Doc/whatsnew/3.10.rst
+++ b/Doc/whatsnew/3.10.rst
@@ -341,9 +341,21 @@ The ``BUTTON5_*`` constants are now exposed in the :mod:`curses` module if
 they are provided by the underlying curses library.
 (Contributed by Zackery Spytz in :issue:`39273`.)
 
+.. _distutils-deprecated:
+
 distutils
 ---------
 
+The entire ``distutils`` package is deprecated, to be removed in Python
+3.12. Its functionality for specifying package builds has already been
+completely replaced by third-party packages ``setuptools`` and
+``packaging``, and most other commonly used APIs are available elsewhere
+in the standard library (such as :mod:`platform`, :mod:`shutil`,
+:mod:`subprocess` or :mod:`sysconfig`). There are no plans to migrate
+any other functionality from ``distutils``, and applications that are
+using other functions should plan to make private copies of the code.
+Refer to :pep:`632` for discussion.
+
 The ``bdist_wininst`` command deprecated in Python 3.8 has been removed.
 The ``bdist_wheel`` command is now recommended to distribute binary packages
 on Windows.
@@ -583,6 +595,10 @@ Deprecated
   as appropriate to help identify code which needs updating during
   this transition.
 
+* The entire ``distutils`` namespace is deprecated, to be removed in
+  Python 3.12. Refer to the :ref:`module changes <distutils-deprecated>`
+  section for more information.
+
 * Non-integer arguments to :func:`random.randrange` are deprecated.
   The :exc:`ValueError` is deprecated in favor of a :exc:`TypeError`.
   (Contributed by Serhiy Storchaka and Raymond Hettinger in :issue:`37319`.)