Merge branch 'main' into fix-issue-46375

Author: emmatyping

.github/SECURITY.md

@@ -1,7 +1,7 @@
 # Security Policy
 
 Python [provides a security policy and threat model](https://devguide.python.org/security/policy/)
-in the Python Development Guide documenting what bugs are vulnerabilities,
+in the Python Developer's Guide documenting what bugs are vulnerabilities,
 how to structure reports, and what versions of Python accept reports.
 
 Python Security Response Team (PSRT) members

Doc/c-api/long.rst

@@ -71,6 +71,12 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
    on failure.
 
 
+.. c:function:: PyObject* PyLong_FromUnsignedLongLong(unsigned long long v)
+
+   Return a new :c:type:`PyLongObject` object from a C :c:expr:`unsigned long long`,
+   or ``NULL`` on failure.
+
+
 .. c:function:: PyObject* PyLong_FromInt32(int32_t value)
                 PyObject* PyLong_FromInt64(int64_t value)
 
@@ -81,12 +87,6 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
    .. versionadded:: 3.14
 
 
-.. c:function:: PyObject* PyLong_FromUnsignedLongLong(unsigned long long v)
-
-   Return a new :c:type:`PyLongObject` object from a C :c:expr:`unsigned long long`,
-   or ``NULL`` on failure.
-
-
 .. c:function:: PyObject* PyLong_FromUInt32(uint32_t value)
                 PyObject* PyLong_FromUInt64(uint64_t value)
 

Doc/c-api/typeobj.rst

@@ -2975,13 +2975,13 @@ Buffer Object Structures
    steps:
 
    (1) Check if the request can be met. If not, raise :exc:`BufferError`,
-       set :c:expr:`view->obj` to ``NULL`` and return ``-1``.
+       set ``view->obj`` to ``NULL`` and return ``-1``.
 
    (2) Fill in the requested fields.
 
    (3) Increment an internal counter for the number of exports.
 
-   (4) Set :c:expr:`view->obj` to *exporter* and increment :c:expr:`view->obj`.
+   (4) Set ``view->obj`` to *exporter* and increment ``view->obj``.
 
    (5) Return ``0``.
 
@@ -3007,10 +3007,10 @@ Buffer Object Structures
    schemes can be used:
 
    * Re-export: Each member of the tree acts as the exporting object and
-     sets :c:expr:`view->obj` to a new reference to itself.
+     sets ``view->obj`` to a new reference to itself.
 
    * Redirect: The buffer request is redirected to the root object of the
-     tree. Here, :c:expr:`view->obj` will be a new reference to the root
+     tree. Here, ``view->obj`` will be a new reference to the root
      object.
 
    The individual fields of *view* are described in section
@@ -3064,7 +3064,7 @@ Buffer Object Structures
    *view* argument.
 
 
-   This function MUST NOT decrement :c:expr:`view->obj`, since that is
+   This function MUST NOT decrement ``view->obj``, since that is
    done automatically in :c:func:`PyBuffer_Release` (this scheme is
    useful for breaking reference cycles).
 

Doc/howto/functional.rst

@@ -1042,7 +1042,7 @@ first calculation. ::
     >>> functools.reduce(operator.concat, [])
     Traceback (most recent call last):
       ...
-    TypeError: reduce() of empty sequence with no initial value
+    TypeError: reduce() of empty iterable with no initial value
     >>> functools.reduce(operator.mul, [1, 2, 3], 1)
     6
     >>> functools.reduce(operator.mul, [], 1)

Doc/library/bisect.rst

@@ -200,7 +200,7 @@ example uses :py:func:`~bisect.bisect` to look up a letter grade for an exam sco
 based on a set of ordered numeric breakpoints: 90 and up is an 'A', 80 to 89 is
 a 'B', and so on::
 
-   >>> def grade(score)
+   >>> def grade(score):
    ...     i = bisect([60, 70, 80, 90], score)
    ...     return "FDCBA"[i]
    ...

Doc/library/collections.abc.rst

@@ -456,7 +456,7 @@ Notes on using :class:`Set` and :class:`MutableSet` as a mixin:
    The :class:`Set` mixin provides a :meth:`!_hash` method to compute a hash value
    for the set; however, :meth:`~object.__hash__` is not defined because not all sets
    are :term:`hashable` or immutable.  To add set hashability using mixins,
-   inherit from both :meth:`Set` and :meth:`Hashable`, then define
+   inherit from both :class:`Set` and :class:`Hashable`, then define
    ``__hash__ = Set._hash``.
 
 .. seealso::

Doc/library/collections.rst

@@ -1233,7 +1233,7 @@ variants of :deco:`functools.lru_cache`:
 .. testcode::
 
     from collections import OrderedDict
-    from time import time
+    from time import monotonic
 
     class TimeBoundedLRU:
         "LRU Cache that invalidates and refreshes old entries."
@@ -1248,10 +1248,10 @@ variants of :deco:`functools.lru_cache`:
             if args in self.cache:
                 self.cache.move_to_end(args)
                 timestamp, result = self.cache[args]
-                if time() - timestamp <= self.maxage:
+                if monotonic() - timestamp <= self.maxage:
                     return result
             result = self.func(*args)
-            self.cache[args] = time(), result
+            self.cache[args] = monotonic(), result
             if len(self.cache) > self.maxsize:
                 self.cache.popitem(last=False)
             return result

Doc/library/difflib.rst

@@ -724,7 +724,7 @@ Finally, we compare the two:
 
    >>> result = list(d.compare(text1, text2))
 
-``result`` is a list of strings, so let's pretty-print it:
+``result`` is a list of strings, so let's pretty-print it::
 
    >>> from pprint import pprint
    >>> pprint(result)
@@ -739,7 +739,7 @@ Finally, we compare the two:
     '?           ++++ ^                      ^\n',
     '+   5. Flat is better than nested.\n']
 
-As a single multi-line string it looks like this:
+As a single multi-line string it looks like this::
 
    >>> import sys
    >>> sys.stdout.writelines(result)

Doc/library/importlib.resources.rst

@@ -240,7 +240,6 @@ For all the following functions:
 
     .. versionchanged:: 3.13
         Multiple *path_names* are accepted.
-        *encoding* and *errors* must be given as keyword arguments.
 
 
 .. function:: is_resource(anchor, *path_names)

Doc/library/io.rst

@@ -38,6 +38,7 @@ will raise a :exc:`TypeError`.  So will giving a :class:`bytes` object to the
    Operations that used to raise :exc:`IOError` now raise :exc:`OSError`, since
    :exc:`IOError` is now an alias of :exc:`OSError`.
 
+.. _text-io:
 
 Text I/O
 ^^^^^^^^
@@ -65,6 +66,7 @@ In-memory text streams are also available as :class:`StringIO` objects::
 The text stream API is described in detail in the documentation of
 :class:`TextIOBase`.
 
+.. _binary-io:
 
 Binary I/O
 ^^^^^^^^^^
@@ -103,6 +105,13 @@ stream by opening a file in binary mode with buffering disabled::
 
 The raw stream API is described in detail in the docs of :class:`RawIOBase`.
 
+.. warning::
+   Raw I/O is a low-level interface and methods generally must have their return
+   values checked and be explicitly retried to ensure an operation completes.
+   For instance :meth:`~RawIOBase.write` returns the number of bytes written
+   which may be less than the number of bytes provided (a partial write).
+   High-level I/O objects like :ref:`binary-io` and :ref:`text-io` implement
+   retry behavior.
 
 .. _io-text-encoding:
 
@@ -478,8 +487,11 @@ I/O Base Classes
 
       Read up to *size* bytes from the object and return them.  As a convenience,
       if *size* is unspecified or -1, all bytes until EOF are returned.
-      Otherwise, only one system call is ever made.  Fewer than *size* bytes may
-      be returned if the operating system call returns fewer than *size* bytes.
+
+      Attempts to make only one system call but will retry if interrupted and
+      the signal handler does not raise an exception (see :pep:`475` for the
+      rationale). This means fewer than *size* bytes may be returned if the
+      operating system call returns fewer than *size* bytes.
 
       If 0 bytes are returned, and *size* was not 0, this indicates end of file.
       If the object is in non-blocking mode and no bytes are available,
@@ -493,13 +505,19 @@ I/O Base Classes
       Read and return all the bytes from the stream until EOF, using multiple
       calls to the stream if necessary.
 
+      If ``0`` bytes are returned this indicates end of file. If the object is in
+      non-blocking mode and the underlying :meth:`read` returns ``None``
+      indicating no bytes are available, ``None`` is returned.
+
    .. method:: readinto(b, /)
 
       Read bytes into a pre-allocated, writable
       :term:`bytes-like object` *b*, and return the
       number of bytes read.  For example, *b* might be a :class:`bytearray`.
-      If the object is in non-blocking mode and no bytes
-      are available, ``None`` is returned.
+
+      If ``0`` is returned and ``len(b)`` is not ``0``, this indicates end of file. If
+      the object is in non-blocking mode and no bytes are available, ``None`` is
+      returned.
 
    .. method:: write(b, /)
 
@@ -513,6 +531,13 @@ I/O Base Classes
       this method returns, so the implementation should only access *b*
       during the method call.
 
+      .. warning::
+
+         This function does not ensure all bytes are written or an exception is
+         thrown. Callers may implement that behavior by checking the return
+         value and, if it is less than the length of *b*, looping with additional
+         write calls until all unwritten bytes are written. High-level I/O
+         objects like :ref:`binary-io` and :ref:`text-io` implement retry behavior.
 
 .. class:: BufferedIOBase
 
@@ -641,7 +666,11 @@ Raw File I/O
 .. class:: FileIO(name, mode='r', closefd=True, opener=None)
 
    A raw binary stream representing an OS-level file containing bytes data.  It
-   inherits from :class:`RawIOBase`.
+   inherits from :class:`RawIOBase` and implements its low-level access design.
+   This means :meth:`~RawIOBase.write` does not guarantee all bytes are written
+   and :meth:`~RawIOBase.read` may read less bytes than requested even when more
+   bytes may be present in the underlying file. To get "write all" and
+   "read at least" behavior, use :ref:`binary-io`.
 
    The *name* can be one of two things:
 
@@ -661,10 +690,6 @@ Raw File I/O
    implies writing, so this mode behaves in a similar way to ``'w'``. Add a
    ``'+'`` to the mode to allow simultaneous reading and writing.
 
-   The :meth:`~RawIOBase.read` (when called with a positive argument),
-   :meth:`~RawIOBase.readinto` and :meth:`~RawIOBase.write` methods on this
-   class will only make one system call.
-
    A custom opener can be used by passing a callable as *opener*. The underlying
    file descriptor for the file object is then obtained by calling *opener* with
    (*name*, *flags*). *opener* must return an open file descriptor (passing
@@ -676,6 +701,13 @@ Raw File I/O
    See the :func:`open` built-in function for examples on using the *opener*
    parameter.
 
+   .. warning::
+      :class:`FileIO` is a low-level I/O object and members, such as
+      :meth:`~RawIOBase.read` and :meth:`~RawIOBase.write`, need to have their
+      return values checked explicitly in a retry loop to implement "write all"
+      and "read at least" behavior. High-level I/O objects :ref:`binary-io` and
+      :ref:`text-io` implement retry behavior.
+
    .. versionchanged:: 3.3
       The *opener* parameter was added.
       The ``'x'`` mode was added.