[pull] main from python:main

.github/SECURITY.md

@@ -1,17 +1,24 @@
 # Security Policy
 
-## Supported Versions
+Python [provides a security policy and threat model](https://devguide.python.org/security/policy/)
+in the Python Development Guide documenting what bugs are vulnerabilities,
+how to structure reports, and what versions of Python accept reports.
 
-The Python team applies security fixes according to the table
-in [the devguide](
-https://devguide.python.org/versions/#supported-versions
-).
+Python Security Response Team (PSRT) members
+balance security work against many other responsibilities. Please be thoughtful
+about the time and attention your report requires. Repeated failure to respect
+the security policy will result in future reports being rejected, or the
+reporter being banned from the ``python`` GitHub organization, regardless of
+technical merit.
 
 ## Reporting a Vulnerability
 
-Please read the guidelines on reporting security issues [on the
-official website](https://www.python.org/dev/security/) for
-instructions on how to report a security-related problem to
-the Python team responsibly.
+The [Python security policy](https://devguide.python.org/security/policy/)
+documents [how to submit a vulnerability report](https://devguide.python.org/security/policy/#how-to-submit-a-vulnerability-report)
+using GitHub Security Advisories. Please read the security policy
+prior to filing a vulnerability report, especially the section on [what information to
+include and exclude](https://devguide.python.org/security/policy/#what-to-include-and-how-to-structure-a-vulnerability-report)
+in vulnerability reports. Following the security policy means the PSRT can
+quickly and efficiently triage your report, not following the security policy
+will only delay triaging your report.
 
-To reach the response team, email `security at python dot org`.

Doc/c-api/typehints.rst

@@ -31,7 +31,7 @@ two types exist -- :ref:`GenericAlias <types-genericalias>` and
       static PyMethodDef my_obj_methods[] = {
           // Other methods.
           ...
-          {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS, "See PEP 585"}
+          {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS, "my_obj is generic over its contained type"}
           ...
       }
 

Doc/library/array.rst

@@ -121,6 +121,8 @@ The module defines the following type:
    :exc:`TypeError` is raised. Array objects also implement the buffer interface,
    and may be used wherever :term:`bytes-like objects <bytes-like object>` are supported.
 
+   Arrays are :ref:`generic <generics>` over the type of their contents.
+
    .. audit-event:: array.__new__ typecode,initializer array.array
 
 

Doc/library/asyncio-future.rst

@@ -101,6 +101,8 @@ Future Object
    implementations can inject their own optimized implementations
    of a Future object.
 
+   Futures are :ref:`generic <generics>` over the type of their results.
+
    .. versionchanged:: 3.7
       Added support for the :mod:`contextvars` module.
 

Doc/library/asyncio-task.rst

@@ -1230,6 +1230,9 @@ Task object
    blocks. If the coroutine returns or raises without blocking, the task
    will be finished eagerly and will skip scheduling to the event loop.
 
+   Tasks are :ref:`generic <generics>` over the return type of their wrapped
+   coroutines.
+
    .. versionchanged:: 3.7
       Added support for the :mod:`contextvars` module.
 

Doc/library/collections.rst

@@ -484,6 +484,8 @@ or subtracting from an empty counter.
     Unix. They are also useful for tracking transactions and other pools of data
     where only the most recent activity is of interest.
 
+    Deques are :ref:`generic <generics>` over the type of their contents.
+
 
     Deque objects support the following methods:
 
@@ -739,6 +741,9 @@ stack manipulations such as ``dup``, ``drop``, ``swap``, ``over``, ``pick``,
     as if they were passed to the :class:`dict` constructor, including keyword
     arguments.
 
+    :class:`!defaultdict`\s are :ref:`generic <generics>` over two types,
+    signifying (respectively) the types of the dictionary's keys and values.
+
 
     :class:`defaultdict` objects support the following method in addition to the
     standard :class:`dict` operations:

Doc/library/contextvars.rst

@@ -42,6 +42,9 @@ Context Variables
    references to context variables which prevents context variables
    from being properly garbage collected.
 
+   :class:`!ContextVar`\s are :ref:`generic <generics>` over the type of
+   their contained value.
+
    .. attribute:: ContextVar.name
 
       The name of the variable.  This is a read-only property.
@@ -130,6 +133,9 @@ Context Variables
    Tokens support the :ref:`context manager protocol <context-managers>`
    to automatically reset context variables. See :meth:`ContextVar.set`.
 
+   Tokens are :ref:`generic <generics>` over the same type as the
+   :class:`ContextVar` which created them.
+
    .. versionadded:: 3.14
 
       Added support for usage as a context manager.

Doc/library/ctypes.rst

@@ -3177,6 +3177,8 @@ Arrays and pointers
    subscript and slice accesses; for slice reads, the resulting object is
    *not* itself an :class:`Array`.
 
+   Arrays are :ref:`generic <generics>` over the type of their elements.
+
 
    .. attribute:: _length_
 

Doc/library/exceptions.rst

@@ -984,6 +984,9 @@ their subgroups based on the types of the contained exceptions.
    raises a :exc:`TypeError` if any contained exception is not an
    :exc:`Exception` subclass.
 
+   Exception groups are :ref:`generic <generics>` over the type of their
+   contained exceptions.
+
    .. impl-detail::
 
       The ``excs`` parameter may be any sequence, but lists and tuples are

Doc/library/io.rst

@@ -824,9 +824,9 @@ than raw I/O does.
 
 .. class:: BufferedRandom(raw, buffer_size=DEFAULT_BUFFER_SIZE)
 
-   A buffered binary stream providing higher-level access to a seekable
-   :class:`RawIOBase` raw binary stream.  It inherits from :class:`BufferedReader`
-   and :class:`BufferedWriter`.
+   A buffered binary stream implementing :class:`BufferedIOBase` interfaces
+   providing higher-level access to a seekable :class:`RawIOBase` raw binary
+   stream.
 
    The constructor creates a reader and writer for a seekable raw stream, given
    in the first argument.  If the *buffer_size* is omitted it defaults to

Doc/library/os.rst

@@ -2994,6 +2994,9 @@ features:
    To be directly usable as a :term:`path-like object`, ``os.DirEntry``
    implements the :class:`PathLike` interface.
 
+   :class:`!DirEntry` objects are :ref:`generic <generics>` over the type of the
+   path (:class:`str` or :class:`bytes`).
+
    Attributes and methods on a ``os.DirEntry`` instance are as follows:
 
    .. attribute:: name

Doc/library/queue.rst

@@ -76,6 +76,8 @@ The :mod:`!queue` module defines the following classes and exceptions:
    Constructor for an unbounded :abbr:`FIFO (first-in, first-out)` queue.
    Simple queues lack advanced functionality such as task tracking.
 
+   Simple queues are :ref:`generic <generics>` over the type of their items.
+
    .. versionadded:: 3.7
 
 

Doc/library/re.rst

@@ -1257,6 +1257,9 @@ Regular expression objects
 
    Compiled regular expression object returned by :func:`re.compile`.
 
+   Patterns are :ref:`generic <generics>` over the type of string they handle
+   (:class:`str` or :class:`bytes`).
+
    .. versionchanged:: 3.9
       :py:class:`re.Pattern` supports ``[]`` to indicate a Unicode (str) or bytes pattern.
       See :ref:`types-genericalias`.
@@ -1419,6 +1422,9 @@ when there is no match, you can test whether there was a match with a simple
 
    Match object returned by successful ``match``\ es and ``search``\ es.
 
+   Matches are :ref:`generic <generics>` over the type of string which was
+   matched (:class:`str` or :class:`bytes`).
+
    .. versionchanged:: 3.9
       :py:class:`re.Match` supports ``[]`` to indicate a Unicode (str) or bytes match.
       See :ref:`types-genericalias`.

Doc/library/shutil.rst

@@ -700,7 +700,7 @@ provided.  They rely on the :mod:`zipfile` and :mod:`tarfile` modules.
 
    Register an archiver for the format *name*.
 
-   *function* is the callable that will be used to unpack archives. The callable
+   *function* is the callable that will be used to create archives. The callable
    will receive the *base_name* of the file to create, followed by the
    *base_dir* (which defaults to :data:`os.curdir`) to start archiving from.
    Further arguments are passed as keyword arguments: *owner*, *group*,

Doc/library/stdtypes.rst

@@ -1403,6 +1403,8 @@ application).
    Many other operations also produce lists, including the :func:`sorted`
    built-in.
 
+   Lists are :ref:`generic <generics>` over the types of their items.
+
    Lists implement all of the :ref:`common <typesseq-common>` and
    :ref:`mutable <typesseq-mutable>` sequence operations. Lists also provide the
    following additional method:
@@ -1494,6 +1496,10 @@ homogeneous data is needed (such as allowing storage in a :class:`set` or
    Tuples implement all of the :ref:`common <typesseq-common>` sequence
    operations.
 
+   Tuples are :ref:`generic <generics>` over the types of their contents.
+   For more information, refer to
+   :ref:`the typing documentation on annotating tuples <annotating-tuples>`.
+
 For heterogeneous collections of data where access by name is clearer than
 access by index, :func:`collections.namedtuple` may be a more appropriate
 choice than a simple tuple object.
@@ -4586,6 +4592,9 @@ copying.
    types such as :class:`bytes` and :class:`bytearray`, an element is a single
    byte, but other types such as :class:`array.array` may have bigger elements.
 
+   :class:`!memoryview`\s are :ref:`generic <generics>` over the type of their
+   underlying data.
+
    ``len(view)`` is equal to the length of :meth:`~memoryview.tolist`, which
    is the nested list representation of the view. If ``view.ndim = 1``,
    this is equal to the number of elements in the view.
@@ -5279,6 +5288,8 @@ Note, the *elem* argument to the :meth:`~object.__contains__`,
 :meth:`~set.discard` methods may be a set.  To support searching for an equivalent
 frozenset, a temporary one is created from *elem*.
 
+Sets and frozensets are :ref:`generic <generics>` over the type of their elements.
+
 .. seealso::
 
    For detailed information on thread-safety guarantees for :class:`set`
@@ -5382,6 +5393,9 @@ can be used interchangeably to index the same dictionary entry.
       Dictionary order is guaranteed to be insertion order.  This behavior was
       an implementation detail of CPython from 3.6.
 
+   Dictionaries are :ref:`generic <generics>` over two types, signifying
+   (respectively) the types of the dictionary's keys and values.
+
    These are the operations that dictionaries support (and therefore, custom
    mapping types should support too):
 
@@ -5719,6 +5733,9 @@ Frozen dictionaries
    :class:`!frozendict` is not a :class:`!dict` subclass but inherits directly
    from ``object``.
 
+   Like dictionaries, frozendicts are :ref:`generic <generics>` over two types,
+   signifying (respectively) the types of the frozendict's keys and values.
+
    .. versionadded:: 3.15
 
 

Doc/library/string.templatelib.rst

@@ -245,6 +245,8 @@ Types
    ...
    3.0 | 1. + 2. | None | .2f
 
+   Interpolations are :ref:`generic <generics>` over the types of their values.
+
    .. rubric:: Attributes
 
    .. attribute:: value

Doc/library/types.rst

@@ -386,6 +386,10 @@ Standard names are defined for the following types:
    entries, which means that when the mapping changes, the view reflects these
    changes.
 
+   :class:`!MappingProxyType`\s are :ref:`generic <generics>` over two types,
+   signifying (respectively) the types of the underlying mapping's keys and
+   values.
+
    .. versionadded:: 3.3
 
    .. versionchanged:: 3.9

Doc/library/weakref.rst

@@ -120,6 +120,9 @@ See :ref:`__slots__ documentation <slots>` for details.
 
    This is a subclassable type rather than a factory function.
 
+   Weak references are :ref:`generic <generics>` over the type of the object they
+   reference.
+
    .. attribute:: __callback__
 
       This read-only attribute returns the callback currently associated to the

Doc/reference/datamodel.rst

@@ -3868,6 +3868,9 @@ Coroutines also have the methods listed below, which are analogous to
 those of generators (see :ref:`generator-methods`).  However, unlike
 generators, coroutines do not directly support iteration.
 
+Coroutines are :ref:`generic <generics>` over the types of their yield, send,
+and return values, respectively.
+
 .. versionchanged:: 3.5.2
    It is a :exc:`RuntimeError` to await on a coroutine more than once.
 

Lib/imaplib.py

@@ -712,7 +712,7 @@ def login(self, user, password):
         """
         typ, dat = self._simple_command('LOGIN', user, self._quote(password))
         if typ != 'OK':
-            raise self.error(dat[-1])
+            raise self.error(dat[-1].decode('UTF-8', 'replace'))
         self.state = 'AUTH'
         return typ, dat
 

Lib/test/test_imaplib.py

@@ -434,6 +434,16 @@ def cmd_AUTHENTICATE(self, tag, args):
                 r'\[AUTHENTICATIONFAILED\] invalid'):
             client.authenticate('MYAUTH', lambda x: b'fake')
 
+    def test_invalid_login(self):
+        class MyServer(SimpleIMAPHandler):
+            def cmd_LOGIN(self, tag, args):
+                self.server.logged = args[0]
+                self._send_tagged(tag, 'NO', '[LOGIN] failed')
+        client, _ = self._setup(MyServer)
+        with self.assertRaisesRegex(imaplib.IMAP4.error,
+                r'\[LOGIN\] failed'):
+            client.login('user', 'wrongpass')
+
     def test_valid_authentication_bytes(self):
         class MyServer(SimpleIMAPHandler):
             def cmd_AUTHENTICATE(self, tag, args):

Misc/NEWS.d/next/Documentation/2026-05-23-17-27-41.gh-issue-150319.ol9tWK.rst

@@ -0,0 +1,2 @@
+Generic builtin and standard library types now document the meaning of their
+type parameters.

Misc/NEWS.d/next/Library/2023-02-26-14-07-18.gh-issue-91099._QPbEL.rst

@@ -0,0 +1,2 @@
+:meth:`imaplib.IMAP4.login` now raises exceptions with :class:`str` instead of
+:class:`bytes`. Patch by Florian Best.

Modules/_asynciomodule.c

@@ -1742,7 +1742,8 @@ static PyMethodDef FutureType_methods[] = {
     _ASYNCIO_FUTURE_DONE_METHODDEF
     _ASYNCIO_FUTURE_GET_LOOP_METHODDEF
     _ASYNCIO_FUTURE__MAKE_CANCELLED_ERROR_METHODDEF
-    {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS, PyDoc_STR("See PEP 585")},
+    {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS,
+    PyDoc_STR("Futures are generic over the type of their results")},
     {NULL, NULL}        /* Sentinel */
 };
 
@@ -2927,7 +2928,8 @@ static PyMethodDef TaskType_methods[] = {
     _ASYNCIO_TASK_SET_NAME_METHODDEF
     _ASYNCIO_TASK_GET_CORO_METHODDEF
     _ASYNCIO_TASK_GET_CONTEXT_METHODDEF
-    {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS, PyDoc_STR("See PEP 585")},
+    {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS,
+    PyDoc_STR("Tasks are generic over the return type of their wrapped coroutines")},
     {NULL, NULL}        /* Sentinel */
 };
 

Modules/_collectionsmodule.c

@@ -1855,7 +1855,7 @@ static PyMethodDef deque_methods[] = {
     DEQUE_ROTATE_METHODDEF
     DEQUE___SIZEOF___METHODDEF
     {"__class_getitem__",       Py_GenericAlias,
-        METH_O|METH_CLASS,       PyDoc_STR("See PEP 585")},
+    METH_O|METH_CLASS,          PyDoc_STR("deques are generic over the type of their contents")},
     {NULL,              NULL}   /* sentinel */
 };
 
@@ -2331,6 +2331,12 @@ defdict_reduce(PyObject *op, PyObject *Py_UNUSED(dummy))
     return result;
 }
 
+
+PyDoc_STRVAR(defdict_class_getitem_doc,
+"defaultdicts are generic over two types, signifying (respectively) the types \
+of the dictionary's keys and values");
+
+
 static PyMethodDef defdict_methods[] = {
     {"__missing__", defdict_missing, METH_O,
      defdict_missing_doc},
@@ -2341,7 +2347,7 @@ static PyMethodDef defdict_methods[] = {
     {"__reduce__", defdict_reduce, METH_NOARGS,
      reduce_doc},
     {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS,
-     PyDoc_STR("See PEP 585")},
+     defdict_class_getitem_doc},
     {NULL}
 };
 

Modules/_ctypes/_ctypes.c

@@ -5305,7 +5305,7 @@ Array_length(PyObject *myself)
 
 static PyMethodDef Array_methods[] = {
     {"__class_getitem__",    Py_GenericAlias,
-    METH_O|METH_CLASS,       PyDoc_STR("See PEP 585")},
+    METH_O|METH_CLASS,       PyDoc_STR("Arrays are generic over the type of their elements")},
     { NULL, NULL }
 };
 

Modules/_functoolsmodule.c

@@ -860,7 +860,8 @@ static PyMethodDef partial_methods[] = {
     {"__reduce__", partial_reduce, METH_NOARGS},
     {"__setstate__", partial_setstate, METH_O},
     {"__class_getitem__",    Py_GenericAlias,
-    METH_O|METH_CLASS,       PyDoc_STR("See PEP 585")},
+    METH_O|METH_CLASS,
+    PyDoc_STR("partial is generic over the wrapped function's return type")},
     {NULL,              NULL}           /* sentinel */
 };