[3.9] bpo-47061: document module deprecations due to PEP 594 (GH-31984) (GH-32082)

Also removed asynchat, asyncore, and smtpd from their respective toctree entries so they are only  in the superceded subtree.
(cherry picked from commit 9ac2de922a)

Co-authored-by: Brett Cannon <brett@python.org>

Automerge-Triggered-By: GH:brettcannon

Doc/library/aifc.rst

@@ -3,6 +3,7 @@
 
 .. module:: aifc
    :synopsis: Read and write audio files in AIFF or AIFC format.
+   :deprecated:
 
 **Source code:** :source:`Lib/aifc.py`
 
@@ -11,6 +12,10 @@
    single: AIFF
    single: AIFF-C
 
+
+.. deprecated:: 3.11
+   The :mod:`aifc` module is deprecated (see :pep:`594` for details).
+
 --------------
 
 This module provides support for reading and writing AIFF and AIFF-C files.

Doc/library/audioop.rst

@@ -3,6 +3,10 @@
 
 .. module:: audioop
    :synopsis: Manipulate raw audio data.
+   :deprecated:
+
+.. deprecated:: 3.11
+   The :mod:`audioop` module is deprecated (see :pep:`594` for details).
 
 --------------
 

Doc/library/cgi.rst

@@ -3,6 +3,7 @@
 
 .. module:: cgi
    :synopsis: Helpers for running Python scripts via the Common Gateway Interface.
+   :deprecated:
 
 **Source code:** :source:`Lib/cgi.py`
 
@@ -14,6 +15,9 @@
    single: URL
    single: Common Gateway Interface
 
+.. deprecated:: 3.11
+   The :mod:`cgi` module is deprecated (see :pep:`594` for details).
+
 --------------
 
 Support module for Common Gateway Interface (CGI) scripts.

Doc/library/cgitb.rst

@@ -3,6 +3,7 @@
 
 .. module:: cgitb
    :synopsis: Configurable traceback handler for CGI scripts.
+   :deprecated:
 
 .. moduleauthor:: Ka-Ping Yee <ping@lfw.org>
 .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
@@ -15,6 +16,9 @@
    single: exceptions; in CGI scripts
    single: tracebacks; in CGI scripts
 
+.. deprecated:: 3.11
+   The :mod:`cgitb` module is deprecated (see :pep:`594` for details).
+
 --------------
 
 The :mod:`cgitb` module provides a special exception handler for Python scripts.

Doc/library/chunk.rst

@@ -3,6 +3,7 @@
 
 .. module:: chunk
    :synopsis: Module to read IFF chunks.
+   :deprecated:
 
 .. moduleauthor:: Sjoerd Mullender <sjoerd@acm.org>
 .. sectionauthor:: Sjoerd Mullender <sjoerd@acm.org>
@@ -16,6 +17,9 @@
    single: Real Media File Format
    single: RMFF
 
+.. deprecated:: 3.11
+   The :mod:`chunk` module is deprecated (see :pep:`594` for details).
+
 --------------
 
 This module provides an interface for reading files that use EA IFF 85 chunks.

Doc/library/crypt.rst

@@ -4,6 +4,7 @@
 .. module:: crypt
    :platform: Unix
    :synopsis: The crypt() function used to check Unix passwords.
+   :deprecated:
 
 .. moduleauthor:: Steven D. Majewski <sdm7g@virginia.edu>
 .. sectionauthor:: Steven D. Majewski <sdm7g@virginia.edu>
@@ -15,6 +16,9 @@
    single: crypt(3)
    pair: cipher; DES
 
+.. deprecated:: 3.11
+   The :mod:`crypt` module is deprecated (see :pep:`594` for details).
+
 --------------
 
 This module implements an interface to the :manpage:`crypt(3)` routine, which is

Doc/library/fileformats.rst

@@ -13,5 +13,4 @@ that aren't markup languages and are not related to e-mail.
    csv.rst
    configparser.rst
    netrc.rst
-   xdrlib.rst
    plistlib.rst

Doc/library/imghdr.rst

@@ -3,9 +3,13 @@
 
 .. module:: imghdr
    :synopsis: Determine the type of image contained in a file or byte stream.
+   :deprecated:
 
 **Source code:** :source:`Lib/imghdr.py`
 
+.. deprecated:: 3.11
+   The :mod:`imghdr` module is deprecated (see :pep:`594` for details).
+
 --------------
 
 The :mod:`imghdr` module determines the type of image contained in a file or

Doc/library/internet.rst

@@ -20,8 +20,6 @@ is currently supported on most popular platforms.  Here is an overview:
 .. toctree::
 
    webbrowser.rst
-   cgi.rst
-   cgitb.rst
    wsgiref.rst
    urllib.rst
    urllib.request.rst
@@ -33,10 +31,7 @@ is currently supported on most popular platforms.  Here is an overview:
    ftplib.rst
    poplib.rst
    imaplib.rst
-   nntplib.rst
    smtplib.rst
-   smtpd.rst
-   telnetlib.rst
    uuid.rst
    socketserver.rst
    http.server.rst

Doc/library/ipc.rst

@@ -22,7 +22,5 @@ The list of modules described in this chapter is:
    ssl.rst
    select.rst
    selectors.rst
-   asyncore.rst
-   asynchat.rst
    signal.rst
    mmap.rst

Doc/library/mm.rst

@@ -11,12 +11,5 @@ discretion of the installation.  Here's an overview:
 
 .. toctree::
 
-   audioop.rst
-   aifc.rst
-   sunau.rst
    wave.rst
-   chunk.rst
    colorsys.rst
-   imghdr.rst
-   sndhdr.rst
-   ossaudiodev.rst

Doc/library/msilib.rst

@@ -4,6 +4,7 @@
 .. module:: msilib
    :platform: Windows
    :synopsis: Creation of Microsoft Installer files, and CAB files.
+   :deprecated:
 
 .. moduleauthor:: Martin v. Löwis <martin@v.loewis.de>
 .. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
@@ -12,6 +13,9 @@
 
 .. index:: single: msi
 
+.. deprecated:: 3.11
+   The :mod:`msilib` module is deprecated (see :pep:`594` for details).
+
 --------------
 
 The :mod:`msilib` supports the creation of Microsoft Installer (``.msi``) files.

Doc/library/netdata.rst

@@ -20,4 +20,3 @@ on the Internet.
    binhex.rst
    binascii.rst
    quopri.rst
-   uu.rst

Doc/library/nis.rst

@@ -5,10 +5,14 @@
 .. module:: nis
    :platform: Unix
    :synopsis: Interface to Sun's NIS (Yellow Pages) library.
+   :deprecated:
 
 .. moduleauthor:: Fred Gansevles <Fred.Gansevles@cs.utwente.nl>
 .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
 
+.. deprecated:: 3.11
+   The :mod:`nis` module is deprecated (see :pep:`594` for details).
+
 --------------
 
 The :mod:`nis` module gives a thin wrapper around the NIS library, useful for

Doc/library/nntplib.rst

@@ -3,6 +3,7 @@
 
 .. module:: nntplib
    :synopsis: NNTP protocol client (requires sockets).
+   :deprecated:
 
 **Source code:** :source:`Lib/nntplib.py`
 
@@ -10,6 +11,9 @@
    pair: NNTP; protocol
    single: Network News Transfer Protocol
 
+.. deprecated:: 3.11
+   The :mod:`nntplib` module is deprecated (see :pep:`594` for details).
+
 --------------
 
 This module defines the class :class:`NNTP` which implements the client side of

Doc/library/ossaudiodev.rst

@@ -4,6 +4,10 @@
 .. module:: ossaudiodev
    :platform: Linux, FreeBSD
    :synopsis: Access to OSS-compatible audio devices.
+   :deprecated:
+
+.. deprecated:: 3.11
+   The :mod:`ossaudiodev` module is deprecated (see :pep:`594` for details).
 
 --------------
 

Doc/library/pipes.rst

@@ -4,11 +4,15 @@
 .. module:: pipes
    :platform: Unix
    :synopsis: A Python interface to Unix shell pipelines.
+   :deprecated:
 
 .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
 
 **Source code:** :source:`Lib/pipes.py`
 
+.. deprecated:: 3.11
+   The :mod:`pipes` module is deprecated (see :pep:`594` for details).
+
 --------------
 
 The :mod:`pipes` module defines a class to abstract the concept of a *pipeline*

Doc/library/sndhdr.rst

@@ -3,6 +3,7 @@
 
 .. module:: sndhdr
    :synopsis: Determine type of a sound file.
+   :deprecated:
 
 .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
 .. Based on comments in the module source file.
@@ -13,6 +14,9 @@
    single: A-LAW
    single: u-LAW
 
+.. deprecated:: 3.11
+   The :mod:`sndhdr` module is deprecated (see :pep:`594` for details).
+
 --------------
 
 The :mod:`sndhdr` provides utility functions which attempt to determine the type

Doc/library/spwd.rst

@@ -4,6 +4,10 @@
 .. module:: spwd
    :platform: Unix
    :synopsis: The shadow password database (getspnam() and friends).
+   :deprecated:
+
+.. deprecated:: 3.11
+   The :mod:`spwd` module is deprecated (see :pep:`594` for details).
 
 --------------
 

Doc/library/sunau.rst

@@ -3,11 +3,15 @@
 
 .. module:: sunau
    :synopsis: Provide an interface to the Sun AU sound format.
+   :deprecated:
 
 .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
 
 **Source code:** :source:`Lib/sunau.py`
 
+.. deprecated:: 3.11
+   The :mod:`sunau` module is deprecated (see :pep:`594` for details).
+
 --------------
 
 The :mod:`sunau` module provides a convenient interface to the Sun AU sound

Doc/library/superseded.rst

@@ -10,8 +10,26 @@ backwards compatibility. They have been superseded by other modules.
 
 .. toctree::
 
+   aifc.rst
    asynchat.rst
    asyncore.rst
-   smtpd.rst
+   audioop.rst
+   cgi.rst
+   cgitb.rst
+   chunk.rst
+   crypt.rst
+   imghdr.rst
    imp.rst
+   msilib.rst
+   nntplib.rst
+   nis.rst
    optparse.rst
+   ossaudiodev.rst
+   pipes.rst
+   smtpd.rst
+   sndhdr.rst
+   spwd.rst
+   sunau.rst
+   telnetlib.rst
+   uu.rst
+   xdrlib.rst

Doc/library/telnetlib.rst

@@ -3,6 +3,7 @@
 
 .. module:: telnetlib
    :synopsis: Telnet client class.
+   :deprecated:
 
 .. sectionauthor:: Skip Montanaro <skip@pobox.com>
 
@@ -10,6 +11,9 @@
 
 .. index:: single: protocol; Telnet
 
+.. deprecated:: 3.11
+   The :mod:`telnetlib` module is deprecated (see :pep:`594` for details).
+
 --------------
 
 The :mod:`telnetlib` module provides a :class:`Telnet` class that implements the

Doc/library/unix.rst

@@ -13,14 +13,10 @@ of it.  Here's an overview:
 
    posix.rst
    pwd.rst
-   spwd.rst
    grp.rst
-   crypt.rst
    termios.rst
    tty.rst
    pty.rst
    fcntl.rst
-   pipes.rst
    resource.rst
-   nis.rst
    syslog.rst

Doc/library/uu.rst

@@ -3,11 +3,15 @@
 
 .. module:: uu
    :synopsis: Encode and decode files in uuencode format.
+   :deprecated:
 
 .. moduleauthor:: Lance Ellinghouse
 
 **Source code:** :source:`Lib/uu.py`
 
+.. deprecated:: 3.11
+   The :mod:`uu` module is deprecated (see :pep:`594` for details).
+
 --------------
 
 This module encodes and decodes files in uuencode format, allowing arbitrary

Doc/library/windows.rst

@@ -9,7 +9,6 @@ This chapter describes modules that are only available on MS Windows platforms.
 
 .. toctree::
 
-   msilib.rst
    msvcrt.rst
    winreg.rst
    winsound.rst

Doc/library/xdrlib.rst

@@ -3,6 +3,7 @@
 
 .. module:: xdrlib
    :synopsis: Encoders and decoders for the External Data Representation (XDR).
+   :deprecated:
 
 **Source code:** :source:`Lib/xdrlib.py`
 
@@ -10,6 +11,9 @@
    single: XDR
    single: External Data Representation
 
+.. deprecated:: 3.11
+   The :mod:`xdrlib` module is deprecated (see :pep:`594` for details).
+
 --------------
 
 The :mod:`xdrlib` module supports the External Data Representation Standard as

Misc/NEWS.d/next/Library/2022-03-18-13-30-40.bpo-47061.etLHK5.rst

@@ -0,0 +1,5 @@
+Deprecate the various modules listed by :pep:`594`:
+
+aifc, asynchat, asyncore, audioop, cgi, cgitb, chunk, crypt,
+imghdr, msilib, nntplib, nis, ossaudiodev, pipes, smtpd,
+sndhdr, spwd, sunau, telnetlib, uu, xdrlib