Merge branch 'main' into docs/refwarn/whatsnew-3.10

# Conflicts:
#	Doc/tools/.nitignore

Author: AA-Turner

Doc/extending/extending.rst

@@ -426,7 +426,7 @@ A pointer to the module definition must be returned via :c:func:`PyModuleDef_Ini
 so that the import machinery can create the module and store it in ``sys.modules``.
 
 When embedding Python, the :c:func:`!PyInit_spam` function is not called
-automatically unless there's an entry in the :c:data:`PyImport_Inittab` table.
+automatically unless there's an entry in the :c:data:`!PyImport_Inittab` table.
 To add the module to the initialization table, use :c:func:`PyImport_AppendInittab`,
 optionally followed by an import of the module::
 

Doc/library/shutil.rst

@@ -90,6 +90,13 @@ Directory and files operations
       copy the file more efficiently. See
       :ref:`shutil-platform-dependent-efficient-copy-operations` section.
 
+.. exception:: SpecialFileError
+
+   This exception is raised when :func:`copyfile` or :func:`copytree` attempt
+   to copy a named pipe.
+
+   .. versionadded:: 2.7
+
 .. exception:: SameFileError
 
    This exception is raised if source and destination in :func:`copyfile`

Doc/library/test.rst

@@ -851,7 +851,7 @@ The :mod:`test.support` module defines the following functions:
    Decorator for tests that fill the address space.
 
 
-.. function:: linked_with_musl()
+.. function:: linked_to_musl()
 
    Return ``False`` if there is no evidence the interpreter was compiled with
    ``musl``, otherwise return a version triple, either ``(0, 0, 0)`` if the

Doc/reference/simple_stmts.rst

@@ -831,6 +831,9 @@ where the :keyword:`import` statement occurs.
 
 .. index:: single: __all__ (optional module attribute)
 
+.. attribute:: module.__all__
+   :no-typesetting:
+
 The *public names* defined by a module are determined by checking the module's
 namespace for a variable named ``__all__``; if defined, it must be a sequence
 of strings which are names defined or imported by that module.  The names

Doc/tools/.nitignore

@@ -11,7 +11,6 @@ Doc/c-api/module.rst
 Doc/c-api/stable.rst
 Doc/c-api/type.rst
 Doc/c-api/typeobj.rst
-Doc/extending/extending.rst
 Doc/library/ast.rst
 Doc/library/asyncio-extending.rst
 Doc/library/email.charset.rst
@@ -61,7 +60,4 @@ Doc/using/windows.rst
 Doc/whatsnew/2.4.rst
 Doc/whatsnew/2.5.rst
 Doc/whatsnew/2.6.rst
-Doc/whatsnew/2.7.rst
-Doc/whatsnew/3.4.rst
 Doc/whatsnew/3.5.rst
-Doc/whatsnew/3.6.rst

Doc/whatsnew/2.7.rst

@@ -1541,7 +1541,7 @@ changes, or look through the Subversion logs for all the details.
   buffer API, which fixed a test suite failure (fix by Antoine Pitrou;
   :issue:`7133`) and automatically set
   OpenSSL's :c:macro:`!SSL_MODE_AUTO_RETRY`, which will prevent an error
-  code being returned from :meth:`recv` operations that trigger an SSL
+  code being returned from :meth:`!recv` operations that trigger an SSL
   renegotiation (fix by Antoine Pitrou; :issue:`8222`).
 
   The :func:`~ssl.SSLContext.wrap_socket` constructor function now takes a
@@ -2031,7 +2031,7 @@ version 1.3.  Some of the new features are:
 * ElementTree's code for converting trees to a string has been
   significantly reworked, making it roughly twice as fast in many
   cases.  The :meth:`ElementTree.write() <xml.etree.ElementTree.ElementTree.write>`
-  and :meth:`Element.write` methods now have a *method* parameter that can be
+  and :meth:`!Element.write` methods now have a *method* parameter that can be
   "xml" (the default), "html", or "text".  HTML mode will output empty
   elements as ``<empty></empty>`` instead of ``<empty/>``, and text
   mode will skip over elements and only output the text chunks.  If
@@ -2044,7 +2044,7 @@ version 1.3.  Some of the new features are:
   Namespace handling has also been improved.  All ``xmlns:<whatever>``
   declarations are now output on the root element, not scattered throughout
   the resulting XML.  You can set the default namespace for a tree
-  by setting the :attr:`default_namespace` attribute and can
+  by setting the :attr:`!default_namespace` attribute and can
   register new prefixes with :meth:`~xml.etree.ElementTree.register_namespace`.  In XML mode,
   you can use the true/false *xml_declaration* parameter to suppress the
   XML declaration.
@@ -2181,14 +2181,14 @@ Changes to Python's build process and to the C API include:
   discussed in :issue:`5753`, and fixed by Antoine Pitrou.
 
 * New macros: the Python header files now define the following macros:
-  :c:macro:`Py_ISALNUM`,
-  :c:macro:`Py_ISALPHA`,
-  :c:macro:`Py_ISDIGIT`,
-  :c:macro:`Py_ISLOWER`,
-  :c:macro:`Py_ISSPACE`,
-  :c:macro:`Py_ISUPPER`,
-  :c:macro:`Py_ISXDIGIT`,
-  :c:macro:`Py_TOLOWER`, and :c:macro:`Py_TOUPPER`.
+  :c:macro:`!Py_ISALNUM`,
+  :c:macro:`!Py_ISALPHA`,
+  :c:macro:`!Py_ISDIGIT`,
+  :c:macro:`!Py_ISLOWER`,
+  :c:macro:`!Py_ISSPACE`,
+  :c:macro:`!Py_ISUPPER`,
+  :c:macro:`!Py_ISXDIGIT`,
+  :c:macro:`!Py_TOLOWER`, and :c:macro:`!Py_TOUPPER`.
   All of these functions are analogous to the C
   standard macros for classifying characters, but ignore the current
   locale setting, because in
@@ -2234,7 +2234,7 @@ Changes to Python's build process and to the C API include:
 
 * When using the :c:type:`PyMemberDef` structure to define attributes
   of a type, Python will no longer let you try to delete or set a
-  :c:macro:`T_STRING_INPLACE` attribute.
+  :c:macro:`!T_STRING_INPLACE` attribute.
 
   .. rev 79644
 
@@ -2259,12 +2259,12 @@ Changes to Python's build process and to the C API include:
   :issue:`6491`.)
 
 * The :program:`configure` script now checks for floating-point rounding bugs
-  on certain 32-bit Intel chips and defines a :c:macro:`X87_DOUBLE_ROUNDING`
+  on certain 32-bit Intel chips and defines a :c:macro:`!X87_DOUBLE_ROUNDING`
   preprocessor definition.  No code currently uses this definition,
   but it's available if anyone wishes to use it.
   (Added by Mark Dickinson; :issue:`2937`.)
 
-  :program:`configure` also now sets a :envvar:`LDCXXSHARED` Makefile
+  :program:`configure` also now sets a :envvar:`!LDCXXSHARED` Makefile
   variable for supporting C++ linking.  (Contributed by Arfrever
   Frehtes Taifersar Arahesis; :issue:`1222585`.)
 

Doc/whatsnew/3.4.rst

@@ -122,7 +122,7 @@ Significantly improved library modules:
   on Unix <whatsnew-multiprocessing-no-fork>` (:issue:`8713`).
 * :mod:`email` has a new submodule, :mod:`~email.contentmanager`, and
   a new :mod:`~email.message.Message` subclass
-  (:class:`~email.contentmanager.EmailMessage`) that :ref:`simplify MIME
+  (:class:`~email.message.EmailMessage`) that :ref:`simplify MIME
   handling <whatsnew_email_contentmanager>` (:issue:`18891`).
 * The :mod:`inspect` and :mod:`pydoc` modules are now capable of
   correct introspection of a much wider variety of callable objects,
@@ -154,7 +154,7 @@ Security improvements:
   <whatsnew34-sslcontext>`.
 * All modules in the standard library that support SSL now support server
   certificate verification, including hostname matching
-  (:func:`ssl.match_hostname`) and CRLs (Certificate Revocation lists, see
+  (:func:`!ssl.match_hostname`) and CRLs (Certificate Revocation lists, see
   :func:`ssl.SSLContext.load_verify_locations`).
 
 CPython implementation improvements:
@@ -739,7 +739,7 @@ these new components.
 In addition, a new application-friendly class :class:`~dis.Bytecode` provides
 an object-oriented API for inspecting bytecode in both in human-readable form
 and for iterating over instructions.  The :class:`~dis.Bytecode` constructor
-takes the same arguments that :func:`~dis.get_instruction` does (plus an
+takes the same arguments that :func:`~dis.get_instructions` does (plus an
 optional *current_offset*), and the resulting object can be iterated to produce
 :class:`~dis.Instruction` objects.  But it also has a :mod:`~dis.Bytecode.dis`
 method, equivalent to calling :mod:`~dis.dis` on the constructor argument, but
@@ -958,8 +958,9 @@ http
 optional additional *explain* parameter which can be used to provide an
 extended error description, overriding the hardcoded default if there is one.
 This extended error description will be formatted using the
-:attr:`~http.server.HTTP.error_message_format` attribute and sent as the body
-of the error response.  (Contributed by Karl Cow in :issue:`12921`.)
+:attr:`~http.server.BaseHTTPRequestHandler.error_message_format` attribute
+and sent as the body of the error response.
+(Contributed by Karl Cow in :issue:`12921`.)
 
 The :mod:`http.server` :ref:`command line interface <http-server-cli>` now has
 a ``-b/--bind`` option that causes the server to listen on a specific address.
@@ -1221,7 +1222,7 @@ pickle
 :mod:`pickle` now supports (but does not use by default) a new pickle protocol,
 protocol 4.  This new protocol addresses a number of issues that were present
 in previous protocols, such as the serialization of nested classes, very large
-strings and containers, and classes whose :meth:`__new__` method takes
+strings and containers, and classes whose :meth:`~object.__new__` method takes
 keyword-only arguments.  It also provides some efficiency improvements.
 
 .. seealso::
@@ -1299,7 +1300,7 @@ affect the behaviour of :func:`help`.
 re
 --
 
-New :func:`~re.fullmatch` function and :meth:`.regex.fullmatch` method anchor
+New :func:`~re.fullmatch` function and :meth:`.Pattern.fullmatch` method anchor
 the pattern at both ends of the string to match.  This provides a way to be
 explicit about the goal of the match, which avoids a class of subtle bugs where
 ``$`` characters get lost during code changes or the addition of alternatives
@@ -1519,7 +1520,7 @@ subprocess
 be used to provide the contents of ``stdin`` for the command that is run.
 (Contributed by Zack Weinberg in :issue:`16624`.)
 
-:func:`~subprocess.getstatus` and :func:`~subprocess.getstatusoutput` now
+:func:`~subprocess.getoutput` and :func:`~subprocess.getstatusoutput` now
 work on Windows.  This change was actually inadvertently made in 3.3.4.
 (Contributed by Tim Golden in :issue:`10197`.)
 
@@ -1535,7 +1536,7 @@ plain tuple.  (Contributed by Claudiu Popa in :issue:`18901`.)
 called automatically at the end of the block.  (Contributed by Serhiy Storchaka
 in :issue:`18878`.)
 
-:meth:`.AU_write.setsampwidth` now supports 24 bit samples, thus adding
+:meth:`!AU_write.setsampwidth` now supports 24 bit samples, thus adding
 support for writing 24 sample using the module.  (Contributed by
 Serhiy Storchaka in :issue:`19261`.)
 
@@ -1615,7 +1616,7 @@ A new :func:`~types.DynamicClassAttribute` descriptor provides a way to define
 an attribute that acts normally when looked up through an instance object, but
 which is routed to the *class* ``__getattr__`` when looked up through the
 class.  This allows one to have properties active on a class, and have virtual
-attributes on the class with the same name (see :mod:`Enum` for an example).
+attributes on the class with the same name (see :mod:`enum` for an example).
 (Contributed by Ethan Furman in :issue:`19030`.)
 
 
@@ -1709,7 +1710,7 @@ matching calls, which means an argument can now be matched by either position
 or name, instead of only by position.  (Contributed by Antoine Pitrou in
 :issue:`17015`.)
 
-:func:`~mock.mock_open` objects now have ``readline`` and ``readlines``
+:func:`~unittest.mock.mock_open` objects now have ``readline`` and ``readlines``
 methods.  (Contributed by Toshio Kuratomi in :issue:`17467`.)
 
 
@@ -1729,8 +1730,8 @@ installed in the virtual environment.  (Contributed by Nick Coghlan in
 wave
 ----
 
-The :meth:`~wave.getparams` method now returns a namedtuple rather than a
-plain tuple.  (Contributed by Claudiu Popa in :issue:`17487`.)
+The :meth:`~wave.Wave_read.getparams` method now returns a namedtuple rather
+than a plain tuple.  (Contributed by Claudiu Popa in :issue:`17487`.)
 
 :meth:`wave.open` now supports the context management protocol.  (Contributed
 by Claudiu Popa in :issue:`17616`.)
@@ -1788,7 +1789,7 @@ example, this could be used to exclude test files from the archive.
 (Contributed by Christian Tismer in :issue:`19274`.)
 
 The *allowZip64* parameter to :class:`~zipfile.ZipFile` and
-:class:`~zipfile.PyZipfile` is now ``True`` by default.  (Contributed by
+:class:`~zipfile.PyZipFile` is now ``True`` by default.  (Contributed by
 William Mallard in :issue:`17201`.)
 
 
@@ -1817,7 +1818,7 @@ PEP 442: Safe Object Finalization
 ---------------------------------
 
 :pep:`442` removes the current limitations and quirks of object finalization
-in CPython. With it, objects with :meth:`__del__` methods, as well as
+in CPython. With it, objects with :meth:`~object.__del__` methods, as well as
 generators with :keyword:`finally` clauses, can be finalized when they are
 part of a reference cycle.
 
@@ -2043,7 +2044,7 @@ Significant Optimizations
   strings is now significantly faster.  (Contributed by Victor Stinner and
   Antoine Pitrou in :issue:`15596`.)
 
-* A performance issue in :meth:`io.FileIO.readall` has been solved.  This
+* A performance issue in :meth:`!io.FileIO.readall` has been solved.  This
   particularly affects Windows, and significantly speeds up the case of piping
   significant amounts of data through :mod:`subprocess`.  (Contributed
   by Richard Oudkerk in :issue:`15758`.)
@@ -2103,7 +2104,7 @@ Deprecations in the Python API
 * The :mod:`!imp` module is pending deprecation. To keep compatibility with
   Python 2/3 code bases, the module's removal is currently not scheduled.
 
-* The :mod:`formatter` module is pending deprecation and is slated for removal
+* The :mod:`!formatter` module is pending deprecation and is slated for removal
   in Python 3.6.
 
 * ``MD5`` as the default *digestmod* for the :func:`hmac.new` function is
@@ -2120,11 +2121,11 @@ Deprecations in the Python API
 
 * The *strict* argument of :class:`~html.parser.HTMLParser` is deprecated.
 
-* The :mod:`plistlib` :func:`~plistlib.readPlist`,
-  :func:`~plistlib.writePlist`, :func:`~plistlib.readPlistFromBytes`, and
-  :func:`~plistlib.writePlistToBytes` functions are deprecated in favor of the
+* The :mod:`plistlib` :func:`!readPlist`,
+  :func:`!writePlist`, :func:`!readPlistFromBytes`, and
+  :func:`!writePlistToBytes` functions are deprecated in favor of the
   corresponding new functions :func:`~plistlib.load`, :func:`~plistlib.dump`,
-  :func:`~plistlib.loads`, and :func:`~plistlib.dumps`.  :func:`~plistlib.Data`
+  :func:`~plistlib.loads`, and :func:`~plistlib.dumps`.  :func:`!Data`
   is deprecated in favor of just using the :class:`bytes` constructor.
 
 * The :mod:`sysconfig` key ``SO`` is deprecated, it has been replaced by
@@ -2212,8 +2213,8 @@ removed:
   that do not have a __format__ method that handles it.  See :issue:`7994` for
   background.
 
-* :meth:`difflib.SequenceMatcher.isbjunk` and
-  :meth:`difflib.SequenceMatcher.isbpopular` were deprecated in 3.2, and have
+* :meth:`!difflib.SequenceMatcher.isbjunk` and
+  :meth:`!difflib.SequenceMatcher.isbpopular` were deprecated in 3.2, and have
   now been removed: use ``x in sm.bjunk`` and
   ``x in sm.bpopular``, where *sm* is a :class:`~difflib.SequenceMatcher` object
   (:issue:`13248`).
@@ -2280,7 +2281,7 @@ Changes in the Python API
 * :meth:`!importlib.util.module_for_loader` now sets ``__loader__`` and
   ``__package__`` unconditionally to properly support reloading. If this is not
   desired then you will need to set these attributes manually. You can use
-  :func:`importlib.util.module_to_load` for module management.
+  :func:`!importlib.util.module_to_load` for module management.
 
 * Import now resets relevant attributes (e.g. ``__name__``, ``__loader__``,
   ``__package__``, ``__file__``, ``__cached__``) unconditionally when reloading.
@@ -2428,7 +2429,7 @@ Changes in the Python API
   disallowed command forms didn't make any sense and are unlikely to be in use.
 
 * The :func:`re.split`, :func:`re.findall`, and :func:`re.sub` functions, and
-  the :meth:`~re.match.group` and :meth:`~re.match.groups` methods of
+  the :meth:`~re.Match.group` and :meth:`~re.Match.groups` methods of
   ``match`` objects now always return a *bytes* object when the string
   to be matched is a :term:`bytes-like object`.  Previously the return type
   matched the input type, so if your code was depending on the return value