[3.10] bpo-47022: Document asynchat, asyncore and smtpd removals in 3.12 (GH-31891) (#31997)

Document the deprecation of asyncore, asynchat, and smtpd with a slated removal in Python 3.12 thanks to PEP 594..
(cherry picked from commit 7747384643)

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

Doc/library/asynchat.rst

@@ -3,6 +3,7 @@
 
 .. module:: asynchat
    :synopsis: Support for asynchronous command/response protocols.
+   :deprecated:
 
 .. moduleauthor:: Sam Rushing <rushing@nightmare.com>
 .. sectionauthor:: Steve Holden <sholden@holdenweb.com>
@@ -10,6 +11,7 @@
 **Source code:** :source:`Lib/asynchat.py`
 
 .. deprecated:: 3.6
+   :mod:`asynchat` will be removed in Python 3.12 (:pep:`594`).
    Please use :mod:`asyncio` instead.
 
 --------------

Doc/library/asyncore.rst

@@ -4,6 +4,7 @@
 .. module:: asyncore
    :synopsis: A base class for developing asynchronous socket handling
               services.
+   :deprecated:
 
 .. moduleauthor:: Sam Rushing <rushing@nightmare.com>
 .. sectionauthor:: Christopher Petrilli <petrilli@amber.org>
@@ -13,6 +14,7 @@
 **Source code:** :source:`Lib/asyncore.py`
 
 .. deprecated:: 3.6
+   :mod:`asyncore` will be removed in Python 3.12 (:pep:`594`).
    Please use :mod:`asyncio` instead.
 
 --------------

Doc/library/smtpd.rst

@@ -3,6 +3,7 @@
 
 .. module:: smtpd
    :synopsis: A SMTP server implementation in Python.
+   :deprecated:
 
 .. moduleauthor:: Barry Warsaw <barry@python.org>
 .. sectionauthor:: Moshe Zadka <moshez@moshez.org>
@@ -14,6 +15,7 @@
 This module offers several classes to implement SMTP (email) servers.
 
 .. deprecated:: 3.6
+   :mod:`smtpd` will be removed in Python 3.12 (:pep:`594`).
    The `aiosmtpd <https://aiosmtpd.readthedocs.io/>`_ package is a recommended
    replacement for this module.  It is based on :mod:`asyncio` and provides a
    more straightforward API.

Doc/library/superseded.rst

@@ -10,5 +10,8 @@ backwards compatibility. They have been superseded by other modules.
 
 .. toctree::
 
-   optparse.rst
+   asynchat.rst
+   asyncore.rst
+   smtpd.rst
    imp.rst
+   optparse.rst

Lib/asynchat.py

@@ -50,7 +50,7 @@ from collections import deque
 
 from warnings import warn
 warn(
-    'The asynchat module is deprecated. '
+    'The asynchat module is deprecated and will be removed in Python 3.12. '
     'The recommended replacement is asyncio',
     DeprecationWarning,
     stacklevel=2)

Lib/asyncore.py

@@ -58,7 +58,7 @@ from errno import EALREADY, EINPROGRESS, EWOULDBLOCK, ECONNRESET, EINVAL, \
      errorcode
 
 warnings.warn(
-    'The asyncore module is deprecated. '
+    'The asyncore module is deprecated and will be removed in Python 3.12. '
     'The recommended replacement is asyncio',
     DeprecationWarning,
     stacklevel=2)

Lib/smtpd.py

@@ -93,7 +93,8 @@ __all__ = [
 ]
 
 warn(
-    'The smtpd module is deprecated and unmaintained.  Please see aiosmtpd '
+    'The smtpd module is deprecated and unmaintained and will be removed '
+    'in Python 3.12.  Please see aiosmtpd '
     '(https://aiosmtpd.readthedocs.io/) for the recommended replacement.',
     DeprecationWarning,
     stacklevel=2)

Misc/NEWS.d/next/Library/2022-03-15-09-29-52.bpo-47022.uaEDcI.rst

@@ -0,0 +1,4 @@
+The :mod:`asynchat`, :mod:`asyncore` and  :mod:`smtpd` modules have been
+deprecated since at least Python 3.6. Their documentation and deprecation
+warnings and have now been updated to note they will removed in Python 3.12
+(:pep:`594`).