Merge branch 'main' into windows-add-sys-abiflags

Author: XuehaiPan

Doc/library/annotationlib.rst

@@ -317,11 +317,22 @@ Functions
    Compute the annotations dict for an object.
 
    *obj* may be a callable, class, module, or other object with
-   :attr:`~object.__annotate__` and :attr:`~object.__annotations__` attributes.
-   Passing in an object of any other type raises :exc:`TypeError`.
+   :attr:`~object.__annotate__` or :attr:`~object.__annotations__` attributes.
+   Passing any other object raises :exc:`TypeError`.
 
    The *format* parameter controls the format in which annotations are returned,
    and must be a member of the :class:`Format` enum or its integer equivalent.
+   The different formats work as follows:
+
+   * VALUE: :attr:`!object.__annotations__` is tried first; if that does not exist,
+     the :attr:`!object.__annotate__` function is called if it exists.
+   * FORWARDREF: If :attr:`!object.__annotations__` exists and can be evaluated successfully,
+     it is used; otherwise, the :attr:`!object.__annotate__` function is called. If it
+     does not exist either, :attr:`!object.__annotations__` is tried again and any error
+     from accessing it is re-raised.
+   * STRING: If :attr:`!object.__annotate__` exists, it is called first;
+     otherwise, :attr:`!object.__annotations__` is used and stringified
+     using :func:`annotations_to_string`.
 
    Returns a dict. :func:`!get_annotations` returns a new dict every time
    it's called; calling it twice on the same object will return two

Doc/library/asyncio-eventloop.rst

@@ -1440,6 +1440,8 @@ Allows customizing how exceptions are handled in the event loop.
    * 'protocol' (optional): :ref:`Protocol <asyncio-protocol>` instance;
    * 'transport' (optional): :ref:`Transport <asyncio-transport>` instance;
    * 'socket' (optional): :class:`socket.socket` instance;
+   * 'source_traceback' (optional): Traceback of the source;
+   * 'handle_traceback' (optional): Traceback of the handle;
    * 'asyncgen' (optional): Asynchronous generator that caused
                             the exception.
 

Doc/library/audit_events.rst

@@ -23,25 +23,30 @@ information on handling these events.
 The following events are raised internally and do not correspond to any
 public API of CPython:
 
-+--------------------------+-------------------------------------------+
-| Audit event              | Arguments                                 |
-+==========================+===========================================+
-| _winapi.CreateFile       | ``file_name``, ``desired_access``,        |
-|                          | ``share_mode``, ``creation_disposition``, |
-|                          | ``flags_and_attributes``                  |
-+--------------------------+-------------------------------------------+
-| _winapi.CreateJunction   | ``src_path``, ``dst_path``                |
-+--------------------------+-------------------------------------------+
-| _winapi.CreateNamedPipe  | ``name``, ``open_mode``, ``pipe_mode``    |
-+--------------------------+-------------------------------------------+
-| _winapi.CreatePipe       |                                           |
-+--------------------------+-------------------------------------------+
-| _winapi.CreateProcess    | ``application_name``, ``command_line``,   |
-|                          | ``current_directory``                     |
-+--------------------------+-------------------------------------------+
-| _winapi.OpenProcess      | ``process_id``, ``desired_access``        |
-+--------------------------+-------------------------------------------+
-| _winapi.TerminateProcess | ``handle``, ``exit_code``                 |
-+--------------------------+-------------------------------------------+
-| ctypes.PyObj_FromPtr     | ``obj``                                   |
-+--------------------------+-------------------------------------------+
++----------------------------+-------------------------------------------+
+| Audit event                | Arguments                                 |
++============================+===========================================+
+| _winapi.CreateFile         | ``file_name``, ``desired_access``,        |
+|                            | ``share_mode``, ``creation_disposition``, |
+|                            | ``flags_and_attributes``                  |
++----------------------------+-------------------------------------------+
+| _winapi.CreateJunction     | ``src_path``, ``dst_path``                |
++----------------------------+-------------------------------------------+
+| _winapi.CreateNamedPipe    | ``name``, ``open_mode``, ``pipe_mode``    |
++----------------------------+-------------------------------------------+
+| _winapi.CreatePipe         |                                           |
++----------------------------+-------------------------------------------+
+| _winapi.CreateProcess      | ``application_name``, ``command_line``,   |
+|                            | ``current_directory``                     |
++----------------------------+-------------------------------------------+
+| _winapi.OpenProcess        | ``process_id``, ``desired_access``        |
++----------------------------+-------------------------------------------+
+| _winapi.TerminateProcess   | ``handle``, ``exit_code``                 |
++----------------------------+-------------------------------------------+
+| _posixsubprocess.fork_exec | ``exec_list``, ``args``, ``env``          |
++----------------------------+-------------------------------------------+
+| ctypes.PyObj_FromPtr       | ``obj``                                   |
++----------------------------+-------------------------------------------+
+
+.. versionadded:: next
+   The ``_posixsubprocess.fork_exec`` internal audit event.

Doc/library/ctypes.rst

@@ -1779,7 +1779,8 @@ in :mod:`!ctypes`) which inherits from the private :class:`_CFuncPtr` class:
 
 .. audit-event:: ctypes.call_function func_pointer,arguments foreign-functions
 
-   Some ways to invoke foreign function calls may raise an auditing event
+   Some ways to invoke foreign function calls as well as some of the
+   functions in this module may raise an auditing event
    ``ctypes.call_function`` with arguments ``function pointer`` and ``arguments``.
 
 .. _ctypes-function-prototypes:

Doc/library/dataclasses.rst

@@ -344,6 +344,15 @@ Module contents
    Other attributes may exist, but they are private and must not be
    inspected or relied on.
 
+.. class:: InitVar
+
+   ``InitVar[T]`` type annotations describe variables that are :ref:`init-only
+   <dataclasses-init-only-variables>`. Fields annotated with :class:`!InitVar`
+   are considered pseudo-fields, and thus are neither returned by the
+   :func:`fields` function nor used in any way except adding them as
+   parameters to :meth:`~object.__init__` and an optional
+   :meth:`__post_init__`.
+
 .. function:: fields(class_or_instance)
 
    Returns a tuple of :class:`Field` objects that define the fields for this
@@ -600,8 +609,8 @@ Init-only variables
 
 Another place where :func:`@dataclass <dataclass>` inspects a type annotation is to
 determine if a field is an init-only variable.  It does this by seeing
-if the type of a field is of type ``dataclasses.InitVar``.  If a field
-is an ``InitVar``, it is considered a pseudo-field called an init-only
+if the type of a field is of type :class:`InitVar`.  If a field
+is an :class:`InitVar`, it is considered a pseudo-field called an init-only
 field.  As it is not a true field, it is not returned by the
 module-level :func:`fields` function.  Init-only fields are added as
 parameters to the generated :meth:`~object.__init__` method, and are passed to

Doc/library/plistlib.rst

@@ -147,8 +147,9 @@ The following classes are available:
    Wraps an :class:`int`.  This is used when reading or writing NSKeyedArchiver
    encoded data, which contains UID (see PList manual).
 
-   It has one attribute, :attr:`data`, which can be used to retrieve the int value
-   of the UID.  :attr:`data` must be in the range ``0 <= data < 2**64``.
+   .. attribute:: data
+
+      Int value of the UID.  It must be in the range ``0 <= data < 2**64``.
 
    .. versionadded:: 3.8
 

Doc/library/readline.rst

@@ -72,6 +72,12 @@ The following functions relate to the init file and user configuration:
 
    Execute a readline initialization file. The default filename is the last filename
    used. This calls :c:func:`!rl_read_init_file` in the underlying library.
+   It raises an :ref:`auditing event <auditing>` ``open`` with the file name
+   if given, and :code:`"<readline_init_file>"` otherwise, regardless of
+   which file the library resolves.
+
+   .. versionchanged:: next
+      The auditing event was added.
 
 
 Line buffer
@@ -109,14 +115,24 @@ The following functions operate on a history file:
 
    Load a readline history file, and append it to the history list.
    The default filename is :file:`~/.history`.  This calls
-   :c:func:`!read_history` in the underlying library.
+   :c:func:`!read_history` in the underlying library
+   and raises an :ref:`auditing event <auditing>` ``open`` with the file
+   name if given and :code:`"~/.history"` otherwise.
+
+   .. versionchanged:: next
+      The auditing event was added.
 
 
 .. function:: write_history_file([filename])
 
    Save the history list to a readline history file, overwriting any
    existing file.  The default filename is :file:`~/.history`.  This calls
-   :c:func:`!write_history` in the underlying library.
+   :c:func:`!write_history` in the underlying library and raises an
+   :ref:`auditing event <auditing>` ``open`` with the file name if given and
+   :code:`"~/.history"` otherwise.
+
+   .. versionchanged:: next
+      The auditing event was added.
 
 
 .. function:: append_history_file(nelements[, filename])
@@ -125,10 +141,14 @@ The following functions operate on a history file:
    :file:`~/.history`.  The file must already exist.  This calls
    :c:func:`!append_history` in the underlying library.  This function
    only exists if Python was compiled for a version of the library
-   that supports it.
+   that supports it. It raises an :ref:`auditing event <auditing>` ``open``
+   with the file name if given and :code:`"~/.history"` otherwise.
 
    .. versionadded:: 3.5
 
+   .. versionchanged:: next
+      The auditing event was added.
+
 
 .. function:: get_history_length()
               set_history_length(length)

Doc/library/socket.rst

@@ -149,22 +149,27 @@ created.  Socket addresses are represented as follows:
       :const:`BDADDR_LE_RANDOM`.
 
     .. versionchanged:: 3.14
-      Added ``cid`` and ``bdaddr_type`` fields.
+       Added ``cid`` and ``bdaddr_type`` fields.
 
   - :const:`BTPROTO_RFCOMM` accepts ``(bdaddr, channel)`` where ``bdaddr``
     is the Bluetooth address as a string and ``channel`` is an integer.
 
-  - :const:`BTPROTO_HCI` accepts ``(device_id,)`` where ``device_id`` is
-    either an integer or a string with the Bluetooth address of the
-    interface. (This depends on your OS; NetBSD and DragonFlyBSD expect
-    a Bluetooth address while everything else expects an integer.)
+  - :const:`BTPROTO_HCI` accepts a format that depends on your OS.
+
+    - On Linux it accepts a tuple ``(device_id,)`` where ``device_id``
+      is an integer specifying the number of the Bluetooth device.
+    - On FreeBSD, NetBSD and DragonFly BSD it accepts ``bdaddr``
+      where ``bdaddr`` is the Bluetooth address as a string.
 
     .. versionchanged:: 3.2
        NetBSD and DragonFlyBSD support added.
 
-  - :const:`BTPROTO_SCO` accepts ``bdaddr`` where ``bdaddr`` is a
-    :class:`bytes` object containing the Bluetooth address in a
-    string format. (ex. ``b'12:23:34:45:56:67'``)
+    .. versionchanged:: 3.13.3
+       FreeBSD support added.
+
+  - :const:`BTPROTO_SCO` accepts ``bdaddr`` where ``bdaddr`` is
+    the Bluetooth address as a string or a :class:`bytes` object.
+    (ex. ``'12:23:34:45:56:67'`` or ``b'12:23:34:45:56:67'``)
 
     .. versionchanged:: next
        FreeBSD support added.
@@ -662,16 +667,15 @@ Constants
    These constants describe the Bluetooth address type when binding or
    connecting a :const:`BTPROTO_L2CAP` socket.
 
-    .. versionadded:: 3.14
+   .. versionadded:: 3.14
 
 .. data:: HCI_FILTER
           HCI_TIME_STAMP
           HCI_DATA_DIR
 
-   For use with :const:`BTPROTO_HCI`. :const:`HCI_FILTER` is not
-   available for NetBSD or DragonFlyBSD. :const:`HCI_TIME_STAMP` and
-   :const:`HCI_DATA_DIR` are not available for FreeBSD, NetBSD, or
-   DragonFlyBSD.
+   For use with :const:`BTPROTO_HCI`. :const:`!HCI_FILTER` is only
+   available on Linux and FreeBSD. :const:`!HCI_TIME_STAMP` and
+   :const:`!HCI_DATA_DIR` are only available on Linux.
 
 .. data:: AF_QIPCRTR
 

Doc/library/urllib.request.rst

@@ -146,16 +146,19 @@ The :mod:`urllib.request` module defines the following functions:
    attribute to modify its position in the handlers list.
 
 
-.. function:: pathname2url(path)
+.. function:: pathname2url(path, *, add_scheme=False)
 
    Convert the given local path to a ``file:`` URL. This function uses
-   :func:`~urllib.parse.quote` function to encode the path. For historical
-   reasons, the return value omits the ``file:`` scheme prefix. This example
-   shows the function being used on Windows::
+   :func:`~urllib.parse.quote` function to encode the path.
+
+   If *add_scheme* is false (the default), the return value omits the
+   ``file:`` scheme prefix. Set *add_scheme* to true to return a complete URL.
+
+   This example shows the function being used on Windows::
 
       >>> from urllib.request import pathname2url
       >>> path = 'C:\\Program Files'
-      >>> 'file:' + pathname2url(path)
+      >>> pathname2url(path, add_scheme=True)
       'file:///C:/Program%20Files'
 
    .. versionchanged:: 3.14
@@ -168,17 +171,25 @@ The :mod:`urllib.request` module defines the following functions:
       sections. For example, the path ``/etc/hosts`` is converted to
       the URL ``///etc/hosts``.
 
+   .. versionchanged:: next
+      The *add_scheme* argument was added.
+
 
-.. function:: url2pathname(url)
+.. function:: url2pathname(url, *, require_scheme=False)
 
    Convert the given ``file:`` URL to a local path. This function uses
-   :func:`~urllib.parse.unquote` to decode the URL. For historical reasons,
-   the given value *must* omit the ``file:`` scheme prefix. This example shows
-   the function being used on Windows::
+   :func:`~urllib.parse.unquote` to decode the URL.
+
+   If *require_scheme* is false (the default), the given value should omit a
+   ``file:`` scheme prefix. If *require_scheme* is set to true, the given
+   value should include the prefix; a :exc:`~urllib.error.URLError` is raised
+   if it doesn't.
+
+   This example shows the function being used on Windows::
 
       >>> from urllib.request import url2pathname
       >>> url = 'file:///C:/Program%20Files'
-      >>> url2pathname(url.removeprefix('file:'))
+      >>> url2pathname(url, require_scheme=True)
       'C:\\Program Files'
 
    .. versionchanged:: 3.14
@@ -193,6 +204,9 @@ The :mod:`urllib.request` module defines the following functions:
       returned (as before), and on other platforms a
       :exc:`~urllib.error.URLError` is raised.
 
+   .. versionchanged:: next
+      The *require_scheme* argument was added.
+
 
 .. function:: getproxies()
 

Doc/tools/.nitignore

@@ -32,7 +32,6 @@ Doc/library/optparse.rst
 Doc/library/os.rst
 Doc/library/pickletools.rst
 Doc/library/platform.rst
-Doc/library/plistlib.rst
 Doc/library/profile.rst
 Doc/library/pyexpat.rst
 Doc/library/resource.rst