Merge branch 'main' into docs-fix-sphinx-warnings-whatsnew-2.0

Doc/c-api/set.rst

@@ -147,7 +147,7 @@ subtypes but not for instances of :class:`frozenset` or its subtypes.
 
    Return ``1`` if found and removed, ``0`` if not found (no action taken), and ``-1`` if an
    error is encountered.  Does not raise :exc:`KeyError` for missing keys.  Raise a
-   :exc:`TypeError` if the *key* is unhashable.  Unlike the Python :meth:`~set.discard`
+   :exc:`TypeError` if the *key* is unhashable.  Unlike the Python :meth:`~frozenset.discard`
    method, this function does not automatically convert unhashable sets into
    temporary frozensets. Raise :exc:`SystemError` if *set* is not an
    instance of :class:`set` or its subtype.

Doc/extending/newtypes.rst

@@ -296,7 +296,7 @@ An interesting advantage of using the :c:member:`~PyTypeObject.tp_members` table
 descriptors that are used at runtime is that any attribute defined this way can
 have an associated doc string simply by providing the text in the table.  An
 application can use the introspection API to retrieve the descriptor from the
-class object, and get the doc string using its :attr:`__doc__` attribute.
+class object, and get the doc string using its :attr:`!__doc__` attribute.
 
 As with the :c:member:`~PyTypeObject.tp_methods` table, a sentinel entry with a :c:member:`~PyMethodDef.ml_name` value
 of ``NULL`` is required.

Doc/howto/descriptor.rst

@@ -521,11 +521,11 @@ everyday Python programs.
 Descriptor protocol
 -------------------
 
-``descr.__get__(self, obj, type=None) -> value``
+``descr.__get__(self, obj, type=None)``
 
-``descr.__set__(self, obj, value) -> None``
+``descr.__set__(self, obj, value)``
 
-``descr.__delete__(self, obj) -> None``
+``descr.__delete__(self, obj)``
 
 That is all there is to it.  Define any of these methods and an object is
 considered a descriptor and can override default behavior upon being looked up
@@ -1013,17 +1013,23 @@ here is a pure Python equivalent:
             if obj is None:
                 return self
             if self.fget is None:
-                raise AttributeError(f"property '{self._name}' has no getter")
+                raise AttributeError(
+                    f'property {self._name!r} of {type(obj).__name__!r} object has no getter'
+                 )
             return self.fget(obj)
 
         def __set__(self, obj, value):
             if self.fset is None:
-                raise AttributeError(f"property '{self._name}' has no setter")
+                raise AttributeError(
+                    f'property {self._name!r} of {type(obj).__name__!r} object has no setter'
+                 )
             self.fset(obj, value)
 
         def __delete__(self, obj):
             if self.fdel is None:
-                raise AttributeError(f"property '{self._name}' has no deleter")
+                raise AttributeError(
+                    f'property {self._name!r} of {type(obj).__name__!r} object has no deleter'
+                 )
             self.fdel(obj)
 
         def getter(self, fget):
@@ -1054,6 +1060,11 @@ here is a pure Python equivalent:
         def delx(self):
             del self.__x
         x = Property(getx, setx, delx, "I'm the 'x' property.")
+        no_getter = Property(None, setx, delx, "I'm the 'x' property.")
+        no_setter = Property(getx, None, delx, "I'm the 'x' property.")
+        no_deleter = Property(getx, setx, None, "I'm the 'x' property.")
+        no_doc = Property(getx, setx, delx, None)
+
 
     # Now do it again but use the decorator style
 
@@ -1092,6 +1103,32 @@ here is a pure Python equivalent:
     >>> hasattr(ccc, 'x')
     False
 
+    >>> cc = CC()
+    >>> cc.x = 33
+    >>> try:
+    ...     cc.no_getter
+    ... except AttributeError as e:
+    ...     e.args[0]
+    ...
+    "property 'no_getter' of 'CC' object has no getter"
+
+    >>> try:
+    ...     cc.no_setter = 33
+    ... except AttributeError as e:
+    ...     e.args[0]
+    ...
+    "property 'no_setter' of 'CC' object has no setter"
+
+    >>> try:
+    ...     del cc.no_deleter
+    ... except AttributeError as e:
+    ...     e.args[0]
+    ...
+    "property 'no_deleter' of 'CC' object has no deleter"
+
+    >>> CC.no_doc.__doc__ is None
+    True
+
 The :func:`property` builtin helps whenever a user interface has granted
 attribute access and then subsequent changes require the intervention of a
 method.

Doc/library/asyncio-stream.rst

@@ -204,6 +204,10 @@ StreamReader
    directly; use :func:`open_connection` and :func:`start_server`
    instead.
 
+   .. method:: feed_eof()
+
+      Acknowledge the EOF.
+
    .. coroutinemethod:: read(n=-1)
 
       Read up to *n* bytes from the stream.

Doc/library/doctest.rst

@@ -143,13 +143,13 @@ Simple Usage: Checking Examples in Docstrings
 ---------------------------------------------
 
 The simplest way to start using doctest (but not necessarily the way you'll
-continue to do it) is to end each module :mod:`M` with::
+continue to do it) is to end each module :mod:`!M` with::
 
    if __name__ == "__main__":
        import doctest
        doctest.testmod()
 
-:mod:`doctest` then examines docstrings in module :mod:`M`.
+:mod:`!doctest` then examines docstrings in module :mod:`!M`.
 
 Running the module as a script causes the examples in the docstrings to get
 executed and verified::
@@ -403,10 +403,10 @@ What's the Execution Context?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 By default, each time :mod:`doctest` finds a docstring to test, it uses a
-*shallow copy* of :mod:`M`'s globals, so that running tests doesn't change the
-module's real globals, and so that one test in :mod:`M` can't leave behind
+*shallow copy* of :mod:`!M`'s globals, so that running tests doesn't change the
+module's real globals, and so that one test in :mod:`!M` can't leave behind
 crumbs that accidentally allow another test to work.  This means examples can
-freely use any names defined at top-level in :mod:`M`, and names defined earlier
+freely use any names defined at top-level in :mod:`!M`, and names defined earlier
 in the docstring being run. Examples cannot see names defined in other
 docstrings.
 
@@ -958,7 +958,8 @@ and :ref:`doctest-simple-testfile`.
 
    Optional argument *exclude_empty* defaults to false.  If true, objects for which
    no doctests are found are excluded from consideration. The default is a backward
-   compatibility hack, so that code still using :meth:`doctest.master.summarize` in
+   compatibility hack, so that code still using
+   :meth:`doctest.master.summarize <DocTestRunner.summarize>` in
    conjunction with :func:`testmod` continues to get output for objects with no
    tests. The *exclude_empty* argument to the newer :class:`DocTestFinder`
    constructor defaults to true.
@@ -997,7 +998,7 @@ As your collection of doctest'ed modules grows, you'll want a way to run all
 their doctests systematically.  :mod:`doctest` provides two functions that can
 be used to create :mod:`unittest` test suites from modules and text files
 containing doctests.  To integrate with :mod:`unittest` test discovery, include
-a :func:`load_tests` function in your test module::
+a :ref:`load_tests <load_tests-protocol>` function in your test module::
 
    import unittest
    import doctest
@@ -1111,19 +1112,24 @@ from text files and modules with doctests:
       :func:`DocTestSuite` returns an empty :class:`unittest.TestSuite` if *module*
       contains no docstrings instead of raising :exc:`ValueError`.
 
+.. exception:: failureException
+
+   When doctests which have been converted to unit tests by :func:`DocFileSuite`
+   or :func:`DocTestSuite` fail, this exception is raised showing the name of
+   the file containing the test and a (sometimes approximate) line number.
 
 Under the covers, :func:`DocTestSuite` creates a :class:`unittest.TestSuite` out
-of :class:`doctest.DocTestCase` instances, and :class:`DocTestCase` is a
-subclass of :class:`unittest.TestCase`. :class:`DocTestCase` isn't documented
+of :class:`!doctest.DocTestCase` instances, and :class:`!DocTestCase` is a
+subclass of :class:`unittest.TestCase`. :class:`!DocTestCase` isn't documented
 here (it's an internal detail), but studying its code can answer questions about
 the exact details of :mod:`unittest` integration.
 
 Similarly, :func:`DocFileSuite` creates a :class:`unittest.TestSuite` out of
-:class:`doctest.DocFileCase` instances, and :class:`DocFileCase` is a subclass
-of :class:`DocTestCase`.
+:class:`!doctest.DocFileCase` instances, and :class:`!DocFileCase` is a subclass
+of :class:`!DocTestCase`.
 
 So both ways of creating a :class:`unittest.TestSuite` run instances of
-:class:`DocTestCase`.  This is important for a subtle reason: when you run
+:class:`!DocTestCase`.  This is important for a subtle reason: when you run
 :mod:`doctest` functions yourself, you can control the :mod:`doctest` options in
 use directly, by passing option flags to :mod:`doctest` functions.  However, if
 you're writing a :mod:`unittest` framework, :mod:`unittest` ultimately controls
@@ -1144,14 +1150,14 @@ reporting flags specific to :mod:`unittest` support, via this function:
    section :ref:`doctest-options`.  Only "reporting flags" can be used.
 
    This is a module-global setting, and affects all future doctests run by module
-   :mod:`unittest`:  the :meth:`runTest` method of :class:`DocTestCase` looks at
-   the option flags specified for the test case when the :class:`DocTestCase`
+   :mod:`unittest`:  the :meth:`!runTest` method of :class:`!DocTestCase` looks at
+   the option flags specified for the test case when the :class:`!DocTestCase`
    instance was constructed.  If no reporting flags were specified (which is the
-   typical and expected case), :mod:`doctest`'s :mod:`unittest` reporting flags are
+   typical and expected case), :mod:`!doctest`'s :mod:`unittest` reporting flags are
    :ref:`bitwise ORed <bitwise>` into the option flags, and the option flags
    so augmented are passed to the :class:`DocTestRunner` instance created to
    run the doctest.  If any reporting flags were specified when the
-   :class:`DocTestCase` instance was constructed, :mod:`doctest`'s
+   :class:`!DocTestCase` instance was constructed, :mod:`!doctest`'s
    :mod:`unittest` reporting flags are ignored.
 
    The value of the :mod:`unittest` reporting flags in effect before the function
@@ -1321,7 +1327,8 @@ Example Objects
       A dictionary mapping from option flags to ``True`` or ``False``, which is used
       to override default options for this example.  Any option flags not contained
       in this dictionary are left at their default value (as specified by the
-      :class:`DocTestRunner`'s :attr:`optionflags`). By default, no options are set.
+      :class:`DocTestRunner`'s :ref:`optionflags <doctest-options>`).
+      By default, no options are set.
 
 
 .. _doctest-doctestfinder:
@@ -1560,7 +1567,7 @@ DocTestRunner objects
 
       The output of each example is checked using the :class:`DocTestRunner`'s
       output checker, and the results are formatted by the
-      :meth:`DocTestRunner.report_\*` methods.
+      :meth:`!DocTestRunner.report_\*` methods.
 
 
    .. method:: summarize(verbose=None)
@@ -1735,12 +1742,12 @@ code under the debugger:
    module) of the object with the doctests of interest.  The result is a string,
    containing the object's docstring converted to a Python script, as described for
    :func:`script_from_examples` above.  For example, if module :file:`a.py`
-   contains a top-level function :func:`f`, then ::
+   contains a top-level function :func:`!f`, then ::
 
       import a, doctest
       print(doctest.testsource(a, "a.f"))
 
-   prints a script version of function :func:`f`'s docstring, with doctests
+   prints a script version of function :func:`!f`'s docstring, with doctests
    converted to code, and the rest placed in comments.
 
 

Doc/library/email.errors.rst

@@ -58,6 +58,15 @@ The following exception classes are defined in the :mod:`email.errors` module:
    :class:`~email.mime.nonmultipart.MIMENonMultipart` (e.g.
    :class:`~email.mime.image.MIMEImage`).
 
+.. exception:: MessageDefect()
+
+   This is the base class for all defects found when parsing email messages.
+   It is derived from :exc:`ValueError`.
+
+.. exception:: HeaderDefect()
+
+   This is the base class for all defects found when parsing email headers.
+   It is derived from :exc:`MessageDefect`.
 
 Here is the list of the defects that the :class:`~email.parser.FeedParser`
 can find while parsing messages.  Note that the defects are added to the message

Doc/library/functions.rst

@@ -1221,7 +1221,7 @@ are always available.  They are listed here in alphabetical order.
 
    *buffering* is an optional integer used to set the buffering policy.  Pass 0
    to switch buffering off (only allowed in binary mode), 1 to select line
-   buffering (only usable in text mode), and an integer > 1 to indicate the size
+   buffering (only usable when writing in text mode), and an integer > 1 to indicate the size
    in bytes of a fixed-size chunk buffer. Note that specifying a buffer size this
    way applies for binary buffered I/O, but ``TextIOWrapper`` (i.e., files opened
    with ``mode='r+'``) would have another buffering. To disable buffering in

Doc/library/gzip.rst

@@ -105,7 +105,7 @@ The module defines the following items:
    should only be provided in compression mode.  If omitted or ``None``, the
    current time is used.  See the :attr:`mtime` attribute for more details.
 
-   Calling a :class:`GzipFile` object's :meth:`close` method does not close
+   Calling a :class:`GzipFile` object's :meth:`!close` method does not close
    *fileobj*, since you might wish to append more material after the compressed
    data.  This also allows you to pass an :class:`io.BytesIO` object opened for
    writing as *fileobj*, and retrieve the resulting memory buffer using the

Doc/library/importlib.resources.rst

@@ -50,7 +50,7 @@ for example, a package and its resources can be imported from a zip file using
 ``get_resource_reader(fullname)`` method as specified by
 :class:`importlib.resources.abc.ResourceReader`.
 
-.. data:: Anchor
+.. class:: Anchor
 
     Represents an anchor for resources, either a :class:`module object
     <types.ModuleType>` or a module name as a string. Defined as
@@ -63,7 +63,7 @@ for example, a package and its resources can be imported from a zip file using
     (think files). A Traversable may contain other containers (think
     subdirectories).
 
-    *anchor* is an optional :data:`Anchor`. If the anchor is a
+    *anchor* is an optional :class:`Anchor`. If the anchor is a
     package, resources are resolved from that package. If a module,
     resources are resolved adjacent to that module (in the same package
     or the package root). If the anchor is omitted, the caller's module
@@ -72,10 +72,10 @@ for example, a package and its resources can be imported from a zip file using
     .. versionadded:: 3.9
 
     .. versionchanged:: 3.12
-       "package" parameter was renamed to "anchor". "anchor" can now
+       *package* parameter was renamed to *anchor*. *anchor* can now
        be a non-package module and if omitted will default to the caller's
-       module. "package" is still accepted for compatibility but will raise
-       a DeprecationWarning. Consider passing the anchor positionally or
+       module. *package* is still accepted for compatibility but will raise
+       a :exc:`DeprecationWarning`. Consider passing the anchor positionally or
        using ``importlib_resources >= 5.10`` for a compatible interface
        on older Pythons.
 
@@ -96,4 +96,4 @@ for example, a package and its resources can be imported from a zip file using
     .. versionadded:: 3.9
 
     .. versionchanged:: 3.12
-       Added support for ``traversable`` representing a directory.
+       Added support for *traversable* representing a directory.