Merge branch 'main' into patch-1

Author: encukou

.github/CODEOWNERS

@@ -260,33 +260,33 @@ Include/pyhash.h                 @gpshead @picnixz
 Python/pyhash.c                  @gpshead @picnixz
 
 # The import system (including importlib)
-**/*import*                   @brettcannon @ericsnowcurrently @ncoghlan @warsaw
-Python/import.c               @brettcannon @ericsnowcurrently @ncoghlan @warsaw @kumaraditya303
+**/*import*                   @brettcannon @ericsnowcurrently @ncoghlan @warsaw @FFY00
+Python/import.c               @brettcannon @ericsnowcurrently @ncoghlan @warsaw @FFY00 @kumaraditya303
 **/*freeze*                   @ericsnowcurrently
 **/*frozen*                   @ericsnowcurrently
 **/*modsupport*               @ericsnowcurrently
-**/*modulefinder*             @ericsnowcurrently
+**/*modulefinder*             @ericsnowcurrently @FFY00
 **/*moduleobject*             @ericsnowcurrently
 **/*multiphase*               @ericsnowcurrently
-**/*pkgutil*                  @ericsnowcurrently
+**/*pkgutil*                  @ericsnowcurrently @FFY00
 **/*pythonrun*                @ericsnowcurrently
-**/*runpy*                    @ericsnowcurrently
+**/*runpy*                    @ericsnowcurrently @FFY00
 **/*singlephase*              @ericsnowcurrently
 Doc/c-api/module.rst          @ericsnowcurrently
 Lib/test/test_module/         @ericsnowcurrently
-Python/dynload_*.c            @ericsnowcurrently
+Python/dynload_*.c            @ericsnowcurrently @FFY00
 
 # Initialisation
-**/*initconfig*               @ericsnowcurrently
-**/*pathconfig*               @ericsnowcurrently
-**/*preconfig*                @ericsnowcurrently
+**/*initconfig*               @ericsnowcurrently @FFY00
+**/*pathconfig*               @ericsnowcurrently @FFY00
+**/*preconfig*                @ericsnowcurrently @FFY00
 Doc/library/sys_path_init.rst @FFY00
 Doc/c-api/init_config.rst     @FFY00
 
 # Interpreter main program
-Modules/main.c                @ericsnowcurrently
-Programs/_bootstrap_python.c  @ericsnowcurrently
-Programs/python.c             @ericsnowcurrently
+Modules/main.c                @ericsnowcurrently @FFY00
+Programs/_bootstrap_python.c  @ericsnowcurrently @FFY00
+Programs/python.c             @ericsnowcurrently @FFY00
 
 # JIT
 .github/workflows/jit.yml     @savannahostrowski
@@ -316,8 +316,8 @@ Tools/peg_generator/          @pablogsal @lysnikolaou
 
 # Runtime state/lifecycle
 **/*gil*                      @ericsnowcurrently
-**/*pylifecycle*              @ericsnowcurrently @ZeroIntensity
-**/*pystate*                  @ericsnowcurrently @ZeroIntensity
+**/*pylifecycle*              @ericsnowcurrently @ZeroIntensity @FFY00
+**/*pystate*                  @ericsnowcurrently @ZeroIntensity @FFY00
 Include/internal/pycore_*_init.h          @ericsnowcurrently
 Include/internal/pycore_*_state.h         @ericsnowcurrently
 Include/internal/pycore_atexit.h          @ericsnowcurrently
@@ -505,13 +505,13 @@ Lib/idlelib/                  @terryjreedy
 Lib/turtledemo/               @terryjreedy
 
 # importlib.metadata
-Doc/library/importlib.metadata.rst  @jaraco @warsaw
-Lib/importlib/metadata/             @jaraco @warsaw
-Lib/test/test_importlib/metadata/   @jaraco @warsaw
+Doc/library/importlib.metadata.rst  @jaraco @warsaw @FFY00
+Lib/importlib/metadata/             @jaraco @warsaw @FFY00
+Lib/test/test_importlib/metadata/   @jaraco @warsaw @FFY00
 
 # importlib.resources
-Doc/library/importlib.resources.abc.rst   @jaraco @warsaw
-Doc/library/importlib.resources.rst       @jaraco @warsaw
+Doc/library/importlib.resources.abc.rst   @jaraco @warsaw @FFY00
+Doc/library/importlib.resources.rst       @jaraco @warsaw @FFY00
 Lib/importlib/resources/                  @jaraco @warsaw @FFY00
 Lib/test/test_importlib/resources/        @jaraco @warsaw @FFY00
 

Doc/Makefile

@@ -58,7 +58,7 @@ build:
 	@if [ -f  ../Misc/NEWS ] ; then \
 		echo "Using existing Misc/NEWS file"; \
 		cp ../Misc/NEWS build/NEWS; \
-	elif $(BLURB) help >/dev/null 2>&1 && $(SPHINXBUILD) --version >/dev/null 2>&1; then \
+	elif $(BLURB) --version && $(SPHINXBUILD) --version ; then \
 		if [ -d ../Misc/NEWS.d ]; then \
 			echo "Building NEWS from Misc/NEWS.d with blurb"; \
 			$(BLURB) merge -f build/NEWS; \

Doc/c-api/exceptions.rst

@@ -699,6 +699,8 @@ Signal Handling
 
    - Executing a pending :ref:`remote debugger <remote-debugging>` script.
 
+   - Raise the exception set by :c:func:`PyThreadState_SetAsyncExc`.
+
    If any handler raises an exception, immediately return ``-1`` with that
    exception set.
    Any remaining interruptions are left to be processed on the next
@@ -714,6 +716,9 @@ Signal Handling
       This function may now execute a remote debugger script, if remote
       debugging is enabled.
 
+   .. versionchanged:: next
+      The exception set by :c:func:`PyThreadState_SetAsyncExc` is now raised.
+
 
 .. c:function:: void PyErr_SetInterrupt()
 

Doc/c-api/threads.rst

@@ -699,13 +699,25 @@ pointer and a void pointer argument.
 
 .. c:function:: int PyThreadState_SetAsyncExc(unsigned long id, PyObject *exc)
 
-   Asynchronously raise an exception in a thread. The *id* argument is the thread
-   id of the target thread; *exc* is the exception object to be raised. This
-   function does not steal any references to *exc*. To prevent naive misuse, you
-   must write your own C extension to call this.  Must be called with an :term:`attached thread state`.
-   Returns the number of thread states modified; this is normally one, but will be
-   zero if the thread id isn't found.  If *exc* is ``NULL``, the pending
-   exception (if any) for the thread is cleared. This raises no exceptions.
+   Schedule an exception to be raised asynchronously in a thread.
+   If the thread has a previously scheduled exception, it is overwritten.
+
+   The *id* argument is the thread id of the target thread, as returned by
+   :c:func:`PyThread_get_thread_ident`.
+   *exc* is the class of the exception to be raised, or ``NULL`` to clear
+   the pending exception (if any).
+
+   Return the number of affected thread states.
+   This is normally ``1`` if *id* is found, even when no change was
+   made (the given *exc* was already pending, or *exc* is ``NULL`` but
+   no exception is pending).
+   If the thread id isn't found, return ``0``.  This raises no exceptions.
+
+   To prevent naive misuse, you must write your own C extension to call this.
+   This function must be called with an :term:`attached thread state`.
+   This function does not steal any references to *exc*.
+   This function does not necessarily interrupt system calls such as
+   :py:func:`~time.sleep`.
 
    .. versionchanged:: 3.7
       The type of the *id* parameter changed from :c:expr:`long` to
@@ -743,7 +755,8 @@ Operating system thread APIs
    :term:`attached thread state`.
 
    .. seealso::
-      :py:func:`threading.get_ident`
+      :py:func:`threading.get_ident` and :py:attr:`threading.Thread.ident`
+      expose this identifier to Python.
 
 
 .. c:function:: PyObject *PyThread_GetInfo(void)

Doc/library/contextlib.rst

@@ -21,9 +21,9 @@ Functions and classes provided:
 .. class:: AbstractContextManager
 
    An :term:`abstract base class` for classes that implement
-   :meth:`object.__enter__` and :meth:`object.__exit__`. A default
-   implementation for :meth:`object.__enter__` is provided which returns
-   ``self`` while :meth:`object.__exit__` is an abstract method which by default
+   :meth:`~object.__enter__` and :meth:`~object.__exit__`. A default
+   implementation for :meth:`~object.__enter__` is provided which returns
+   ``self`` while :meth:`~object.__exit__` is an abstract method which by default
    returns ``None``. See also the definition of :ref:`typecontextmanager`.
 
    .. versionadded:: 3.6
@@ -32,9 +32,9 @@ Functions and classes provided:
 .. class:: AbstractAsyncContextManager
 
    An :term:`abstract base class` for classes that implement
-   :meth:`object.__aenter__` and :meth:`object.__aexit__`. A default
-   implementation for :meth:`object.__aenter__` is provided which returns
-   ``self`` while :meth:`object.__aexit__` is an abstract method which by default
+   :meth:`~object.__aenter__` and :meth:`~object.__aexit__`. A default
+   implementation for :meth:`~object.__aenter__` is provided which returns
+   ``self`` while :meth:`~object.__aexit__` is an abstract method which by default
    returns ``None``. See also the definition of
    :ref:`async-context-managers`.
 
@@ -228,7 +228,7 @@ Functions and classes provided:
 
 .. function:: nullcontext(enter_result=None)
 
-   Return a context manager that returns *enter_result* from ``__enter__``, but
+   Return a context manager that returns *enter_result* from :meth:`~object.__enter__`, but
    otherwise does nothing. It is intended to be used as a stand-in for an
    optional context manager, for example::
 
@@ -335,7 +335,7 @@ Functions and classes provided:
    For example, the output of :func:`help` normally is sent to *sys.stdout*.
    You can capture that output in a string by redirecting the output to an
    :class:`io.StringIO` object. The replacement stream is returned from the
-   ``__enter__`` method and so is available as the target of the
+   :meth:`~object.__enter__` method and so is available as the target of the
    :keyword:`with` statement::
 
         with redirect_stdout(io.StringIO()) as f:
@@ -396,7 +396,8 @@ Functions and classes provided:
    A base class that enables a context manager to also be used as a decorator.
 
    Context managers inheriting from ``ContextDecorator`` have to implement
-   ``__enter__`` and ``__exit__`` as normal. ``__exit__`` retains its optional
+   :meth:`~object.__enter__` and :meth:`~object.__exit__` as normal.
+   ``__exit__`` retains its optional
    exception handling even when used as a decorator.
 
    ``ContextDecorator`` is used by :func:`contextmanager`, so you get this
@@ -710,9 +711,9 @@ context management protocol.
 Catching exceptions from ``__enter__`` methods
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-It is occasionally desirable to catch exceptions from an ``__enter__``
+It is occasionally desirable to catch exceptions from an :meth:`~object.__enter__`
 method implementation, *without* inadvertently catching exceptions from
-the :keyword:`with` statement body or the context manager's ``__exit__``
+the :keyword:`with` statement body or the context manager's :meth:`~object.__exit__`
 method. By using :class:`ExitStack` the steps in the context management
 protocol can be separated slightly in order to allow this::
 

Doc/library/os.rst

@@ -2409,6 +2409,10 @@ features:
    .. versionchanged:: 3.6
       Accepts a :term:`path-like object`.
 
+   .. versionchanged:: next
+      ``os.listdir(-1)`` now fails with ``OSError(errno.EBADF)`` rather than
+      listing the current directory.
+
 
 .. function:: listdrives()
 
@@ -2939,6 +2943,10 @@ features:
    .. versionchanged:: 3.7
       Added support for :ref:`file descriptors <path_fd>` on Unix.
 
+   .. versionchanged:: next
+      ``os.scandir(-1)`` now fails with ``OSError(errno.EBADF)`` rather than
+      listing the current directory.
+
 
 .. class:: DirEntry
 
@@ -4574,6 +4582,10 @@ These functions are all available on Linux only.
    .. versionchanged:: 3.6
       Accepts a :term:`path-like object`.
 
+   .. versionchanged:: next
+      ``os.listxattr(-1)`` now fails with ``OSError(errno.EBADF)`` rather than
+      listing extended attributes of the current directory.
+
 
 .. function:: removexattr(path, attribute, *, follow_symlinks=True)
 

Doc/library/site.rst

@@ -64,7 +64,8 @@ When running under a :ref:`virtual environment <sys-path-init-virtual-environmen
 the ``pyvenv.cfg`` file in :data:`sys.prefix` is checked for site-specific
 configurations. If the ``include-system-site-packages`` key exists and is set to
 ``true`` (case-insensitive), the system-level prefixes will be searched for
-site-packages, otherwise they won't.
+site-packages, otherwise they won't.  If the system-level prefixes are not searched then
+the user site prefixes are also implicitly not searched for site-packages.
 
 .. index::
    single: # (hash); comment

Doc/library/sys_path_init.rst

@@ -57,15 +57,19 @@ otherwise they are set to the same value as :data:`sys.base_prefix` and
 :data:`sys.base_exec_prefix`, respectively.
 This is used by :ref:`sys-path-init-virtual-environments`.
 
-Finally, the :mod:`site` module is processed and :file:`site-packages` directories
-are added to the module search path. A common way to customize the search path is
-to create :mod:`sitecustomize` or :mod:`usercustomize` modules as described in
-the :mod:`site` module documentation.
+Finally, the :mod:`site` module is processed and :file:`site-packages`
+directories are added to the module search path.  The :envvar:`PYTHONUSERBASE`
+environment variable controls where is searched for user site-packages and the
+:envvar:`PYTHONNOUSERSITE` environment variable prevents searching for user
+site-packages all together.  A common way to customize the search path is to
+create :mod:`sitecustomize` or :mod:`usercustomize` modules as described in the
+:mod:`site` module documentation.
 
 .. note::
 
-   Certain command line options may further affect path calculations.
-   See :option:`-E`, :option:`-I`, :option:`-s` and :option:`-S` for further details.
+   The command line options :option:`-E`, :option:`-P`, :option:`-I`,
+   :option:`-S` and :option:`-s` further affect path calculations, see their
+   documentation for details.
 
 .. versionchanged:: 3.14
 
@@ -96,11 +100,10 @@ Please refer to :mod:`site`'s
 
 .. note::
 
-   There are other ways how "virtual environments" could be implemented, this
-   documentation refers implementations based on the ``pyvenv.cfg`` mechanism,
-   such as :mod:`venv`. Most virtual environment implementations follow the
-   model set by :mod:`venv`, but there may be exotic implementations that
-   diverge from it.
+   There are other ways "virtual environments" could be implemented.
+   This documentation refers to implementations based on the ``pyvenv.cfg``
+   mechanism, such as :mod:`venv`, that many virtual environment implementations
+   follow.
 
 _pth files
 ----------

Doc/library/wave.rst

@@ -181,11 +181,21 @@ Wave_write Objects
       Set the number of channels.
 
 
+   .. method:: getnchannels()
+
+      Return the number of channels.
+
+
    .. method:: setsampwidth(n)
 
       Set the sample width to *n* bytes.
 
 
+   .. method:: getsampwidth()
+
+      Return the sample width in bytes.
+
+
    .. method:: setframerate(n)
 
       Set the frame rate to *n*.
@@ -195,26 +205,53 @@ Wave_write Objects
          integer.
 
 
+   .. method:: getframerate()
+
+      Return the frame rate.
+
+
    .. method:: setnframes(n)
 
       Set the number of frames to *n*.  This will be changed later if the number
       of frames actually written is different (this update attempt will
       raise an error if the output stream is not seekable).
 
 
+   .. method:: getnframes()
+
+      Return the number of audio frames written so far.
+
+
    .. method:: setcomptype(type, name)
 
       Set the compression type and description. At the moment, only compression type
       ``NONE`` is supported, meaning no compression.
 
 
+   .. method:: getcomptype()
+
+      Return the compression type (``'NONE'``).
+
+
+   .. method:: getcompname()
+
+      Return the human-readable compression type name.
+
+
    .. method:: setparams(tuple)
 
       The *tuple* should be ``(nchannels, sampwidth, framerate, nframes, comptype,
       compname)``, with values valid for the ``set*()`` methods.  Sets all
       parameters.
 
 
+   .. method:: getparams()
+
+      Return a :func:`~collections.namedtuple`
+      ``(nchannels, sampwidth, framerate, nframes, comptype, compname)``
+      containing the current output parameters.
+
+
    .. method:: tell()
 
       Return current position in the file, with the same disclaimer for the