gh-95913: Edit & expand Deprecated section of 3.11 WhatsNew (#98581)

* Refine Sphinx syntax and grammar/phrasing in Deprecated section items
* Organize into lang/builtins, modules & stdlib sections
* Convert PEP 594 module list into a grid to not waste as much space
* Add importlib.resources deprecated functions to section

1 files changed, 108 insertions, 82 deletions

diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst
index d743c2e08b..954b89c827 100644
--- a/Doc/whatsnew/3.11.rst
+++ b/Doc/whatsnew/3.11.rst
@@ -1587,78 +1587,107 @@ This section lists Python APIs that have been deprecated in Python 3.11.
 
 Deprecated C APIs are :ref:`listed separately <whatsnew311-c-api-deprecated>`.
 
+
+.. _whatsnew311-deprecated-language:
+.. _whatsnew311-deprecated-builtins:
+
+Language/Builtins
+-----------------
+
 * Chaining :class:`classmethod` descriptors (introduced in :issue:`19072`)
   is now deprecated.  It can no longer be used to wrap other descriptors
   such as :class:`property`.  The core design of this feature was flawed
   and caused a number of downstream problems.  To "pass-through" a
-  :class:`classmethod`, consider using the ``__wrapped__`` attribute
+  :class:`classmethod`, consider using the :attr:`!__wrapped__` attribute
   that was added in Python 3.10.
   (Contributed by Raymond Hettinger in :gh:`89519`.)
 
-* Octal escapes in string and bytes literals with value larger than ``0o377`` now
-  produce :exc:`DeprecationWarning`.
-  In a future Python version they will be a :exc:`SyntaxWarning` and
+* Octal escapes in string and bytes literals with values larger than ``0o377``
+  (255 in decimal) now produce a :exc:`DeprecationWarning`.
+  In a future Python version, they will raise a :exc:`SyntaxWarning` and
   eventually a :exc:`SyntaxError`.
   (Contributed by Serhiy Storchaka in :gh:`81548`.)
 
-* The :mod:`lib2to3` package and ``2to3`` tool are now deprecated and may not
-  be able to parse Python 3.10 or newer. See the :pep:`617` (New PEG parser for
-  CPython).  (Contributed by Victor Stinner in :issue:`40360`.)
+* The delegation of :func:`int` to :meth:`~object.__trunc__` is now deprecated.
+  Calling ``int(a)`` when ``type(a)`` implements :meth:`!__trunc__` but not
+  :meth:`~object.__int__` or :meth:`~object.__index__` now raises
+  a :exc:`DeprecationWarning`.
+  (Contributed by Zackery Spytz in :issue:`44977`.)
 
-* Undocumented modules ``sre_compile``, ``sre_constants`` and ``sre_parse``
-  are now deprecated.
-  (Contributed by Serhiy Storchaka in :issue:`47152`.)
 
-* :class:`webbrowser.MacOSX` is deprecated and will be removed in Python 3.13.
-  It is untested and undocumented and also not used by webbrowser itself.
-  (Contributed by Dong-hee Na in :issue:`42255`.)
+.. _whatsnew311-deprecated-modules:
 
-* The behavior of returning a value from a :class:`~unittest.TestCase` and
-  :class:`~unittest.IsolatedAsyncioTestCase` test methods (other than the
-  default ``None`` value), is now deprecated.
+Modules
+-------
 
-* Deprecated the following :mod:`unittest` functions, scheduled for removal in
-  Python 3.13:
+.. _whatsnew311-pep594:
 
-  * :func:`unittest.findTestCases`
-  * :func:`unittest.makeSuite`
-  * :func:`unittest.getTestCaseNames`
+* :pep:`594` led to the deprecations of the following modules
+  slated for removal in Python 3.13:
 
-  Use :class:`~unittest.TestLoader` method instead:
+  +---------------------+---------------------+---------------------+---------------------+---------------------+
+  | :mod:`aifc`         | :mod:`chunk`        | :mod:`msilib`       | :mod:`pipes`        | :mod:`telnetlib`    |
+  +---------------------+---------------------+---------------------+---------------------+---------------------+
+  | :mod:`audioop`      | :mod:`crypt`        | :mod:`nis`          | :mod:`sndhdr`       | :mod:`uu`           |
+  +---------------------+---------------------+---------------------+---------------------+---------------------+
+  | :mod:`cgi`          | :mod:`imghdr`       | :mod:`nntplib`      | :mod:`spwd`         | :mod:`xdrlib`       |
+  +---------------------+---------------------+---------------------+---------------------+---------------------+
+  | :mod:`cgitb`        | :mod:`mailcap`      | :mod:`ossaudiodev`  | :mod:`sunau`        |                     |
+  +---------------------+---------------------+---------------------+---------------------+---------------------+
 
-  * :meth:`unittest.TestLoader.loadTestsFromModule`
-  * :meth:`unittest.TestLoader.loadTestsFromTestCase`
-  * :meth:`unittest.TestLoader.getTestCaseNames`
+  (Contributed by Brett Cannon in :issue:`47061` and Victor Stinner in
+  :gh:`68966`.)
 
-  (Contributed by Erlend E. Aasland in :issue:`5846`.)
+* The :mod:`asynchat`, :mod:`asyncore` and  :mod:`smtpd` modules have been
+  deprecated since at least Python 3.6. Their documentation and deprecation
+  warnings have now been updated to note they will removed in Python 3.12.
+  (Contributed by Hugo van Kemenade in :issue:`47022`.)
 
-* The :meth:`turtle.RawTurtle.settiltangle` is deprecated since Python 3.1,
-  it now emits a deprecation warning and will be removed in Python 3.13. Use
-  :meth:`turtle.RawTurtle.tiltangle` instead (it was earlier incorrectly marked
-  as deprecated, its docstring is now corrected).
-  (Contributed by Hugo van Kemenade in :issue:`45837`.)
+* The :mod:`lib2to3` package and :ref:`2to3 <2to3-reference>` tool
+  are now deprecated and may not be able to parse Python 3.10 or newer.
+  See :pep:`617`, introducing the new PEG parser, for details.
+  (Contributed by Victor Stinner in :issue:`40360`.)
+
+* Undocumented modules :mod:`!sre_compile`, :mod:`!sre_constants`
+  and :mod:`!sre_parse` are now deprecated.
+  (Contributed by Serhiy Storchaka in :issue:`47152`.)
 
-* The delegation of :func:`int` to :meth:`__trunc__` is now deprecated. Calling
-  ``int(a)`` when ``type(a)`` implements :meth:`__trunc__` but not
-  :meth:`__int__` or :meth:`__index__` now raises a :exc:`DeprecationWarning`.
-  (Contributed by Zackery Spytz in :issue:`44977`.)
+
+.. _whatsnew311-deprecated-stdlib:
+
+Standard Library
+----------------
 
 * The following have been deprecated in :mod:`configparser` since Python 3.2.
   Their deprecation warnings have now been updated to note they will removed in
   Python 3.12:
 
-  * the :class:`configparser.SafeConfigParser` class
-  * the :attr:`configparser.ParsingError.filename` property
+  * the :class:`!configparser.SafeConfigParser` class
+  * the :attr:`!configparser.ParsingError.filename` property
   * the :meth:`configparser.RawConfigParser.readfp` method
 
   (Contributed by Hugo van Kemenade in :issue:`45173`.)
 
-* :class:`configparser.LegacyInterpolation` has been deprecated in the docstring
-  since Python 3.2. It now emits a :exc:`DeprecationWarning` and will be removed
+* :class:`!configparser.LegacyInterpolation` has been deprecated in the docstring
+  since Python 3.2, and is not listed in the :mod:`configparser` documentation.
+  It now emits a :exc:`DeprecationWarning` and will be removed
   in Python 3.13. Use :class:`configparser.BasicInterpolation` or
   :class:`configparser.ExtendedInterpolation` instead.
   (Contributed by Hugo van Kemenade in :issue:`46607`.)
 
+* The older set of :mod:`importlib.resources` functions were deprecated
+  in favor of the replacements added in Python 3.9
+  and will be removed in a future Python version,
+  due to not supporting resources located within package subdirectories:
+
+  * :func:`importlib.resources.contents`
+  * :func:`importlib.resources.is_resource`
+  * :func:`importlib.resources.open_binary`
+  * :func:`importlib.resources.open_text`
+  * :func:`importlib.resources.read_binary`
+  * :func:`importlib.resources.read_text`
+  * :func:`importlib.resources.path`
+
 * The :func:`locale.getdefaultlocale` function is deprecated and will be
   removed in Python 3.13. Use :func:`locale.setlocale`,
   :func:`locale.getpreferredencoding(False) <locale.getpreferredencoding>` and
@@ -1669,46 +1698,25 @@ Deprecated C APIs are :ref:`listed separately <whatsnew311-c-api-deprecated>`.
   removed in Python 3.13. Use ``locale.setlocale(locale.LC_ALL, "")`` instead.
   (Contributed by Victor Stinner in :gh:`90817`.)
 
-.. _whatsnew311-pep594:
-
-* :pep:`594` led to the deprecations of the following modules which are
-  slated for removal in Python 3.13:
-
-  * :mod:`aifc`
-  * :mod:`audioop`
-  * :mod:`cgi`
-  * :mod:`cgitb`
-  * :mod:`chunk`
-  * :mod:`crypt`
-  * :mod:`imghdr`
-  * :mod:`mailcap`
-  * :mod:`msilib`
-  * :mod:`nis`
-  * :mod:`nntplib`
-  * :mod:`ossaudiodev`
-  * :mod:`pipes`
-  * :mod:`sndhdr`
-  * :mod:`spwd`
-  * :mod:`sunau`
-  * :mod:`telnetlib`
-  * :mod:`uu`
-  * :mod:`xdrlib`
-
-  (Contributed by Brett Cannon in :issue:`47061` and Victor Stinner in
-  :gh:`68966`.)
+* Stricter rules will now be applied for numerical group references
+  and group names in :ref:`regular expressions <re-syntax>`.
+  Only sequences of ASCII digits will now be accepted as a numerical reference,
+  and the group name in :class:`bytes` patterns and replacement strings
+  can only contain ASCII letters, digits and underscores.
+  For now, a deprecation warning is raised for syntax violating these rules.
+  (Contributed by Serhiy Storchaka in :gh:`91760`.)
 
-* The :mod:`asynchat`, :mod:`asyncore` and  :mod:`smtpd` modules have been
-  deprecated since at least Python 3.6. Their documentation and deprecation
-  warnings have now been updated to note they will removed in Python 3.12.
-  (Contributed by Hugo van Kemenade in :issue:`47022`.)
+* In the :mod:`re` module, the :func:`!re.template` function
+  and the corresponding :data:`!re.TEMPLATE` and :data:`!re.T` flags
+  are deprecated, as they were undocumented and lacked an obvious purpose.
+  They will be removed in Python 3.13.
+  (Contributed by Serhiy Storchaka and Miro Hrončok in :gh:`92728`.)
 
-* More strict rules will be applied now applied for numerical group references
-  and group names in regular expressions in future Python versions.
-  Only sequence of ASCII digits will be now accepted as a numerical reference.
-  The group name in bytes patterns and replacement strings could only
-  contain ASCII letters and digits and underscore.
-  For now, a deprecation warning is raised for such syntax.
-  (Contributed by Serhiy Storchaka in :gh:`91760`.)
+* :func:`turtle.settiltangle` has been deprecated since Python 3.1;
+  it now emits a deprecation warning and will be removed in Python 3.13. Use
+  :func:`turtle.tiltangle` instead (it was earlier incorrectly marked
+  as deprecated, and its docstring is now corrected).
+  (Contributed by Hugo van Kemenade in :issue:`45837`.)
 
 * :class:`typing.Text`, which exists solely to provide compatibility support
   between Python 2 and Python 3 code, is now deprecated. Its removal is
@@ -1716,14 +1724,32 @@ Deprecated C APIs are :ref:`listed separately <whatsnew311-c-api-deprecated>`.
   wherever possible.
   (Contributed by Alex Waygood in :gh:`92332`.)
 
-* The keyword argument syntax for constructing :data:`~typing.TypedDict` types
+* The keyword argument syntax for constructing :data:`typing.TypedDict` types
   is now deprecated. Support will be removed in Python 3.13. (Contributed by
   Jingchen Ye in :gh:`90224`.)
 
-* The :func:`re.template` function and the corresponding :const:`re.TEMPLATE`
-  and :const:`re.T` flags are deprecated, as they were undocumented and
-  lacked an obvious purpose. They will be removed in Python 3.13.
-  (Contributed by Serhiy Storchaka and Miro Hrončok in :gh:`92728`.)
+* :class:`!webbrowser.MacOSX` is deprecated and will be removed in Python 3.13.
+  It is untested, undocumented, and not used by :mod:`webbrowser` itself.
+  (Contributed by Dong-hee Na in :issue:`42255`.)
+
+* The behavior of returning a value from a :class:`~unittest.TestCase` and
+  :class:`~unittest.IsolatedAsyncioTestCase` test methods (other than the
+  default ``None`` value) is now deprecated.
+
+* Deprecated the following not-formally-documented :mod:`unittest` functions,
+  scheduled for removal in Python 3.13:
+
+  * :func:`!unittest.findTestCases`
+  * :func:`!unittest.makeSuite`
+  * :func:`!unittest.getTestCaseNames`
+
+  Use :class:`~unittest.TestLoader` methods instead:
+
+  * :meth:`unittest.TestLoader.loadTestsFromModule`
+  * :meth:`unittest.TestLoader.loadTestsFromTestCase`
+  * :meth:`unittest.TestLoader.getTestCaseNames`
+
+  (Contributed by Erlend E. Aasland in :issue:`5846`.)
 
 
 .. _whatsnew311-pending-removal: