Merge branch 'main' into import-zoneinfo-pydatetime

Author: serhiy-storchaka

Doc/c-api/init_config.rst

@@ -2258,6 +2258,7 @@ If a ``._pth`` file is present:
 * Set :c:member:`~PyConfig.isolated` to ``1``.
 * Set :c:member:`~PyConfig.use_environment` to ``0``.
 * Set :c:member:`~PyConfig.site_import` to ``0``.
+* Set :c:member:`~PyConfig.user_site_directory` to ``0`` (since 3.15).
 * Set :c:member:`~PyConfig.safe_path` to ``1``.
 
 If :c:member:`~PyConfig.home` is not set and a ``pyvenv.cfg`` file is present in
@@ -2278,6 +2279,12 @@ The ``__PYVENV_LAUNCHER__`` environment variable is used to set
    therefore affected by :option:`-S`.
 
 
+.. versionchanged:: 3.15
+
+   :c:member:`~PyConfig.user_site_directory` is now set to ``0`` when a
+   ``._pth`` file is present.
+
+
 Py_GetArgcArgv()
 ================
 

Doc/howto/remote_debugging.rst

@@ -374,13 +374,13 @@ To locate a thread:
    reliable thread to target.
 
 3. Optionally, use the offset ``interpreter_state.threads_head`` to iterate
-through the linked list of all thread states. Each ``PyThreadState`` structure
-contains a ``native_thread_id`` field, which may be compared to a target thread
-ID to find a specific thread.
+   through the linked list of all thread states. Each ``PyThreadState``
+   structure contains a ``native_thread_id`` field, which may be compared to
+   a target thread ID to find a specific thread.
 
-1. Once a valid ``PyThreadState`` has been found, its address can be used in
-later steps of the protocol, such as writing debugger control fields and
-scheduling execution.
+4. Once a valid ``PyThreadState`` has been found, its address can be used in
+   later steps of the protocol, such as writing debugger control fields and
+   scheduling execution.
 
 The following is an example implementation that locates the main thread state::
 
@@ -454,15 +454,15 @@ its fields are defined by the ``_Py_DebugOffsets`` structure and include the
 following:
 
 - ``debugger_script_path``: A fixed-size buffer that holds the full path to a
-   Python source file (``.py``).  This file must be accessible and readable by
-   the target process when execution is triggered.
+  Python source file (``.py``).  This file must be accessible and readable by
+  the target process when execution is triggered.
 
 - ``debugger_pending_call``: An integer flag. Setting this to ``1`` tells the
-   interpreter that a script is ready to be executed.
+  interpreter that a script is ready to be executed.
 
 - ``eval_breaker``: A field checked by the interpreter during execution.
-   Setting bit 5 (``_PY_EVAL_PLEASE_STOP_BIT``, value ``1U << 5``) in this
-   field causes the interpreter to pause and check for debugger activity.
+  Setting bit 5 (``_PY_EVAL_PLEASE_STOP_BIT``, value ``1U << 5``) in this
+  field causes the interpreter to pause and check for debugger activity.
 
 To complete the injection, the debugger must perform the following steps:
 

Doc/library/_thread.rst

@@ -120,13 +120,16 @@ This module defines the following constants and functions:
    Its value may be used to uniquely identify this particular thread system-wide
    (until the thread terminates, after which the value may be recycled by the OS).
 
-   .. availability:: Windows, FreeBSD, Linux, macOS, OpenBSD, NetBSD, AIX, DragonFlyBSD, GNU/kFreeBSD.
+   .. availability:: Windows, FreeBSD, Linux, macOS, OpenBSD, NetBSD, AIX, DragonFlyBSD, GNU/kFreeBSD, Solaris.
 
    .. versionadded:: 3.8
 
    .. versionchanged:: 3.13
       Added support for GNU/kFreeBSD.
 
+   .. versionchanged:: next
+      Added support for Solaris.
+
 
 .. function:: stack_size([size])
 

Doc/library/asyncio-eventloop.rst

@@ -304,6 +304,12 @@ clocks to track time.
    custom :class:`contextvars.Context` for the *callback* to run in.
    The current context is used when no *context* is provided.
 
+   .. note::
+
+      For performance, callbacks scheduled with :meth:`loop.call_later`
+      may run up to one clock-resolution early (see
+      ``time.get_clock_info('monotonic').resolution``).
+
    .. versionchanged:: 3.7
       The *context* keyword-only parameter was added. See :pep:`567`
       for more details.
@@ -324,6 +330,12 @@ clocks to track time.
    An instance of :class:`asyncio.TimerHandle` is returned which can
    be used to cancel the callback.
 
+   .. note::
+
+      For performance, callbacks scheduled with :meth:`loop.call_at`
+      may run up to one clock-resolution early (see
+      ``time.get_clock_info('monotonic').resolution``).
+
    .. versionchanged:: 3.7
       The *context* keyword-only parameter was added. See :pep:`567`
       for more details.

Doc/library/asyncio-protocol.rst

@@ -390,11 +390,11 @@ Subprocess Transports
    Return the transport for the communication pipe corresponding to the
    integer file descriptor *fd*:
 
-   * ``0``: readable streaming transport of the standard input (*stdin*),
+   * ``0``: writable streaming transport of the standard input (*stdin*),
      or :const:`None` if the subprocess was not created with ``stdin=PIPE``
-   * ``1``: writable streaming transport of the standard output (*stdout*),
+   * ``1``: readable streaming transport of the standard output (*stdout*),
      or :const:`None` if the subprocess was not created with ``stdout=PIPE``
-   * ``2``: writable streaming transport of the standard error (*stderr*),
+   * ``2``: readable streaming transport of the standard error (*stderr*),
      or :const:`None` if the subprocess was not created with ``stderr=PIPE``
    * other *fd*: :const:`None`
 

Doc/library/asyncio-stream.rst

@@ -321,6 +321,9 @@ StreamWriter
          stream.write(data)
          await stream.drain()
 
+      .. note::
+         The *data* buffer should be a C contiguous one-dimensional :term:`bytes-like object <bytes-like object>`.
+
    .. method:: writelines(data)
 
       The method writes a list (or any iterable) of bytes to the underlying socket

Doc/library/asyncio-sync.rst

@@ -157,7 +157,7 @@ Event
 
       Clear (unset) the event.
 
-      Tasks awaiting on :meth:`~Event.wait` will now block until the
+      Subsequent tasks awaiting on :meth:`~Event.wait` will now block until the
       :meth:`~Event.set` method is called again.
 
    .. method:: is_set()

Doc/library/dataclasses.rst

@@ -161,9 +161,11 @@ Module contents
      :class:`object`, this means it will fall back to id-based hashing).
 
    - *frozen*: If true (the default is ``False``), assigning to fields will
-     generate an exception.  This emulates read-only frozen instances.  If
-     :meth:`~object.__setattr__` or :meth:`~object.__delattr__` is defined in the class, then
-     :exc:`TypeError` is raised.  See the discussion below.
+     generate an exception.  This emulates read-only frozen instances.
+     See the :ref:`discussion <dataclasses-frozen>` below.
+
+     If :meth:`~object.__setattr__` or :meth:`~object.__delattr__` is defined in the class
+     and *frozen* is true, then :exc:`TypeError` is raised.
 
    - *match_args*: If true (the default is ``True``), the
      :attr:`~object.__match_args__` tuple will be created from the list of

Doc/library/dbm.rst

@@ -90,10 +90,13 @@ the Oracle Berkeley DB.
    .. versionchanged:: 3.11
       *file* accepts a :term:`path-like object`.
 
-The object returned by :func:`~dbm.open` supports the same basic functionality as a
-:class:`dict`; keys and their corresponding values can be stored, retrieved, and
-deleted, and the :keyword:`in` operator and the :meth:`!keys` method are
-available, as well as :meth:`!get` and :meth:`!setdefault` methods.
+The object returned by :func:`~dbm.open` supports the basic
+functionality of mutable :term:`mappings <mapping>`;
+keys and their corresponding values can be stored, retrieved, and
+deleted, and iteration, the :keyword:`in` operator and methods :meth:`!keys`,
+:meth:`!get`, :meth:`!setdefault` and :meth:`!clear` are available.
+The :meth:`!keys` method returns a list instead of a view object.
+The :meth:`!setdefault` method requires two arguments.
 
 Key and values are always stored as :class:`bytes`. This means that when
 strings are used they are implicitly converted to the default encoding before
@@ -114,6 +117,10 @@ will automatically close them when done.
    Deleting a key from a read-only database raises a database module specific exception
    instead of :exc:`KeyError`.
 
+.. versionchanged:: 3.13
+   :meth:`!clear` methods are now available for all :mod:`dbm` backends.
+
+
 The following example records some hostnames and a corresponding title,  and
 then prints out the contents of the database::
 
@@ -173,9 +180,6 @@ or any other SQLite browser, including the SQLite CLI.
 .. function:: open(filename, /, flag="r", mode=0o666)
 
    Open an SQLite database.
-   The returned object behaves like a :term:`mapping`,
-   implements a :meth:`!close` method,
-   and supports a "closing" context manager via the :keyword:`with` keyword.
 
    :param filename:
       The path to the database to be opened.
@@ -192,6 +196,17 @@ or any other SQLite browser, including the SQLite CLI.
       The Unix file access mode of the file (default: octal ``0o666``),
       used only when the database has to be created.
 
+   The returned database object behaves similar to a mutable :term:`mapping`,
+   but the :meth:`!keys` method returns a list, and
+   the :meth:`!setdefault` method requires two arguments.
+   It also supports a "closing" context manager via the :keyword:`with` keyword.
+
+   The following methods are also provided:
+
+   .. method:: sqlite3.close()
+
+      Close the SQLite database.
+
    .. method:: sqlite3.reorganize()
 
       If you have carried out a lot of deletions and would like to shrink the space
@@ -204,6 +219,7 @@ or any other SQLite browser, including the SQLite CLI.
 
       .. versionadded:: next
 
+
 :mod:`dbm.gnu` --- GNU database manager
 ---------------------------------------
 
@@ -232,6 +248,11 @@ functionality like crash tolerance.
    raised for general mapping errors like specifying an incorrect key.
 
 
+.. data:: open_flags
+
+   A string of characters the *flag* parameter of :meth:`~dbm.gnu.open` supports.
+
+
 .. function:: open(filename, flag="r", mode=0o666, /)
 
    Open a GDBM database and return a :class:`!gdbm` object.
@@ -270,14 +291,25 @@ functionality like crash tolerance.
    .. versionchanged:: 3.11
       *filename* accepts a :term:`path-like object`.
 
-   .. data:: open_flags
+   :class:`!gdbm` objects behave similar to mutable :term:`mappings <mapping>`,
+   but methods :meth:`!items`, :meth:`!values`, :meth:`!pop`, :meth:`!popitem`,
+   and :meth:`!update` are not supported,
+   the :meth:`!keys` method returns a list, and
+   the :meth:`!setdefault` method requires two arguments.
+   It also supports a "closing" context manager via the :keyword:`with` keyword.
+
+   .. versionchanged:: 3.2
+      Added the :meth:`!get` and :meth:`!setdefault` methods.
 
-      A string of characters the *flag* parameter of :meth:`~dbm.gnu.open` supports.
+   .. versionchanged:: 3.13
+      Added the :meth:`!clear` method.
 
-   :class:`!gdbm` objects behave similar to :term:`mappings <mapping>`,
-   but :meth:`!items` and :meth:`!values` methods are not supported.
    The following methods are also provided:
 
+   .. method:: gdbm.close()
+
+      Close the GDBM database.
+
    .. method:: gdbm.firstkey()
 
       It's possible to loop over every key in the database using this method  and the
@@ -313,16 +345,6 @@ functionality like crash tolerance.
       When the database has been opened in fast mode, this method forces any
       unwritten data to be written to the disk.
 
-   .. method:: gdbm.close()
-
-      Close the GDBM database.
-
-   .. method:: gdbm.clear()
-
-      Remove all items from the GDBM database.
-
-      .. versionadded:: 3.13
-
 
 :mod:`dbm.ndbm` --- New Database Manager
 ----------------------------------------
@@ -383,22 +405,27 @@ This module can be used with the "classic" NDBM interface or the
    :param int mode:
       |mode_param_doc|
 
-   :class:`!ndbm` objects behave similar to :term:`mappings <mapping>`,
-   but :meth:`!items` and :meth:`!values` methods are not supported.
-   The following methods are also provided:
-
    .. versionchanged:: 3.11
       Accepts :term:`path-like object` for filename.
 
-   .. method:: ndbm.close()
+   :class:`!ndbm` objects behave similar to mutable :term:`mappings <mapping>`,
+   but methods :meth:`!items`, :meth:`!values`, :meth:`!pop`, :meth:`!popitem`,
+   and :meth:`!update` are not supported,
+   the :meth:`!keys` method returns a list, and
+   the :meth:`!setdefault` method requires two arguments.
+   It also supports a "closing" context manager via the :keyword:`with` keyword.
 
-      Close the NDBM database.
+   .. versionchanged:: 3.2
+      Added the :meth:`!get` and :meth:`!setdefault` methods.
 
-   .. method:: ndbm.clear()
+   .. versionchanged:: 3.13
+      Added the :meth:`!clear` method.
 
-      Remove all items from the NDBM database.
+   The following method is also provided:
 
-      .. versionadded:: 3.13
+   .. method:: ndbm.close()
+
+      Close the NDBM database.
 
 
 :mod:`dbm.dumb` --- Portable DBM implementation
@@ -436,9 +463,6 @@ The :mod:`!dbm.dumb` module defines the following:
 .. function:: open(filename, flag="c", mode=0o666)
 
    Open a :mod:`!dbm.dumb` database.
-   The returned database object behaves similar to a :term:`mapping`,
-   in addition to providing :meth:`~dumbdbm.sync` and :meth:`~dumbdbm.close`
-   methods.
 
    :param filename:
       The basename of the database file (without extensions).
@@ -477,14 +501,12 @@ The :mod:`!dbm.dumb` module defines the following:
    .. versionchanged:: 3.11
       *filename* accepts a :term:`path-like object`.
 
-   In addition to the methods provided by the
-   :class:`collections.abc.MutableMapping` class,
-   the following methods are provided:
+   The returned database object behaves similar to a mutable :term:`mapping`,
+   but the :meth:`!keys` and :meth:`!items` methods return lists, and
+   the :meth:`!setdefault` method requires two arguments.
+   It also supports a "closing" context manager via the :keyword:`with` keyword.
 
-   .. method:: dumbdbm.sync()
-
-      Synchronize the on-disk directory and data files.  This method is called
-      by the :meth:`shelve.Shelf.sync` method.
+   The following methods are also provided:
 
    .. method:: dumbdbm.close()
 
@@ -501,3 +523,8 @@ The :mod:`!dbm.dumb` module defines the following:
          that this factor changes for each :mod:`dbm` submodule.
 
       .. versionadded:: next
+
+   .. method:: dumbdbm.sync()
+
+      Synchronize the on-disk directory and data files.  This method is called
+      by the :meth:`shelve.Shelf.sync` method.