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

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

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`

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

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`.)

Lib/distutils/__init__.py

@@ -9,5 +9,11 @@ used from a setup script as
 """
 
 import sys
+import warnings
 
 __version__ = sys.version[:sys.version.index(' ')]
+
+warnings.warn("The distutils package deprecated and slated for "
+              "removal in Python 3.12. Use setuptools or check "
+              "PEP 632 for potential alternatives",
+              DeprecationWarning)

Misc/NEWS.d/next/Library/2021-01-27-20-49-32.bpo-41282.SEPdV0.rst

@@ -0,0 +1 @@
+Deprecate ``distutils`` in documentation and add warning on import.