Merge branch 'main' into issue-102967

Author: serhiy-storchaka

Doc/library/ast.rst

@@ -806,8 +806,11 @@ Comprehensions
    List and set comprehensions, generator expressions, and dictionary
    comprehensions. ``elt`` (or ``key`` and ``value``) is a single node
    representing the part that will be evaluated for each item.
+
    For dictionary comprehensions using unpacking, for example
-   ``{**item for item in items}``, ``value`` is ``None``,
+   ``{**item for item in items}``, the expression to be expanded goes in
+   ``key`` and ``value`` is ``None``.
+
    ``generators`` is a list of :class:`comprehension` nodes.
 
    .. doctest::

Doc/library/email.compat32-message.rst

@@ -96,7 +96,7 @@ Here are the methods of the :class:`Message` class:
          text = fp.getvalue()
 
       If the message object contains binary data that is not encoded according
-      to RFC standards, the non-compliant data will be replaced by unicode
+      to RFC standards, the non-compliant data will be replaced by Unicode
       "unknown character" code points.  (See also :meth:`.as_bytes` and
       :class:`~email.generator.BytesGenerator`.)
 

Doc/library/email.contentmanager.rst

@@ -96,9 +96,9 @@ Currently the email package provides only one concrete content manager,
 
    This content manager provides only a minimum interface beyond that provided
    by :class:`~email.message.Message` itself:  it deals only with text, raw
-   byte strings, and :class:`~email.message.Message` objects.  Nevertheless, it
+   bytes, and :class:`~email.message.Message` objects.  Nevertheless, it
    provides significant advantages compared to the base API: ``get_content`` on
-   a text part will return a unicode string without the application needing to
+   a text part will return a string without the application needing to
    manually decode it, ``set_content`` provides a rich set of options for
    controlling the headers added to a part and controlling the content transfer
    encoding, and it enables the use of the various ``add_`` methods, thereby
@@ -111,7 +111,7 @@ Currently the email package provides only one concrete content manager,
       parts), or a ``bytes`` object (for all other non-multipart types).  Raise
       a :exc:`KeyError` if called on a ``multipart``.  If the part is a
       ``text`` part and *errors* is specified, use it as the error handler when
-      decoding the payload to unicode.  The default error handler is
+      decoding the payload to a string.  The default error handler is
       ``replace``.
 
    .. method:: set_content(msg, <'str'>, subtype="plain", charset='utf-8', \

Doc/library/email.examples.rst

@@ -7,7 +7,7 @@ Here are a few examples of how to use the :mod:`email` package to read, write,
 and send simple email messages, as well as more complex MIME messages.
 
 First, let's see how to create and send a simple text message (both the
-text content and the addresses may contain unicode characters):
+text content and the addresses may contain Unicode characters):
 
 .. literalinclude:: ../includes/email-simple.py
 

Doc/library/email.header.rst

@@ -49,7 +49,7 @@ For example::
 
 Notice here how we wanted the :mailheader:`Subject` field to contain a non-ASCII
 character?  We did this by creating a :class:`Header` instance and passing in
-the character set that the byte string was encoded in.  When the subsequent
+the character set to use when encoding it.  When the subsequent
 :class:`~email.message.Message` instance was flattened, the :mailheader:`Subject`
 field was properly :rfc:`2047` encoded.  MIME-aware mail readers would show this
 header using the embedded ISO-8859-1 character.
@@ -150,7 +150,7 @@ Here is the :class:`Header` class description:
    .. method:: __str__()
 
       Returns an approximation of the :class:`Header` as a string, using an
-      unlimited line length.  All pieces are converted to unicode using the
+      unlimited line length.  All pieces are decoded using the
       specified encoding and joined together appropriately.  Any pieces with a
       charset of ``'unknown-8bit'`` are decoded as ASCII using the ``'replace'``
       error handler.

Doc/library/email.headerregistry.rst

@@ -40,7 +40,7 @@ headers.
 
    *name* and *value* are passed to ``BaseHeader`` from the
    :attr:`~email.policy.EmailPolicy.header_factory` call.  The string value of
-   any header object is the *value* fully decoded to unicode.
+   any header object is the *value* fully decoded to a string.
 
    This base class defines the following read-only properties:
 
@@ -95,10 +95,10 @@ headers.
    defects to this list.  On return, the ``kwds`` dictionary *must* contain
    values for at least the keys ``decoded``, ``defects`` and ``parse_tree``.
    ``decoded`` should be the string value for the header (that is, the header
-   value fully decoded to unicode). ``parse_tree`` is set to the parse tree obtained
+   value fully decoded to a string). ``parse_tree`` is set to the parse tree obtained
    from parsing the header. The parse method should assume that *string* may
    contain content-transfer-encoded parts, but should correctly handle all valid
-   unicode characters as well so that it can parse un-encoded header values.
+   Unicode characters as well so that it can parse un-encoded header values.
 
    ``BaseHeader``'s ``__new__`` then creates the header instance, and calls its
    ``init`` method.  The specialized class only needs to provide an ``init``
@@ -126,7 +126,7 @@ headers.
    mechanism for encoding non-ASCII text as ASCII characters within a header
    value.  When a *value* containing encoded words is passed to the
    constructor, the ``UnstructuredHeader`` parser converts such encoded words
-   into unicode, following the :rfc:`2047` rules for unstructured text.  The
+   into a string, following the :rfc:`2047` rules for unstructured text.  The
    parser uses heuristics to attempt to decode certain non-compliant encoded
    words.  Defects are registered in such cases, as well as defects for issues
    such as invalid characters within the encoded words or the non-encoded text.
@@ -203,8 +203,8 @@ headers.
       the list of addresses is "flattened" into a one dimensional list).
 
    The ``decoded`` value of the header will have all encoded words decoded to
-   unicode.  :class:`~encodings.idna` encoded domain names are also decoded to
-   unicode.  The ``decoded`` value is set by :ref:`joining <meth-str-join>` the
+   a string.  :class:`~encodings.idna` encoded domain names are also decoded to
+   a string.  The ``decoded`` value is set by :ref:`joining <meth-str-join>` the
    :class:`str` value of the elements of the ``groups`` attribute with ``',
    '``.
 
@@ -392,7 +392,7 @@ construct structured values to assign to specific headers.
    *domain*, in which case *username* and *domain* will be parsed from the
    *addr_spec*.  An *addr_spec* must be a properly RFC quoted string; if it is
    not ``Address`` will raise an error.  Unicode characters are allowed and
-   will be property encoded when serialized.  However, per the RFCs, unicode is
+   will be property encoded when serialized.  However, per the RFCs, Unicode is
    *not* allowed in the username portion of the address.
 
    .. attribute:: display_name

Doc/library/email.policy.rst

@@ -505,7 +505,7 @@ added matters.  To illustrate::
       Otherwise the *name*, and the *value* with any CR or LF characters
       removed, are passed to the ``header_factory``, and the resulting
       header object is returned.  Any surrogateescaped bytes get turned into
-      the unicode unknown-character glyph.
+      the Unicode unknown-character glyph.
 
 
    .. method:: fold(name, value)
@@ -600,10 +600,10 @@ the email package is changed from the Python 3.2 API in the following ways:
 
 From the application view, this means that any header obtained through the
 :class:`~email.message.EmailMessage` is a header object with extra
-attributes, whose string value is the fully decoded unicode value of the
+attributes, whose string value is the fully decoded value of the
 header.  Likewise, a header may be assigned a new value, or a new header
-created, using a unicode string, and the policy will take care of converting
-the unicode string into the correct RFC encoded form.
+created, using a string, and the policy will take care of converting
+the string into the correct RFC encoded form.
 
 The header objects and their attributes are described in
 :mod:`~email.headerregistry`.

Doc/library/email.rst

@@ -54,7 +54,7 @@ server.
 
 The email package does its best to hide the details of the various governing
 RFCs from the application.  Conceptually the application should be able to
-treat the email message as a structured tree of unicode text and binary
+treat the email message as a structured tree of Unicode text and binary
 attachments, without having to worry about how these are represented when
 serialized.  In practice, however, it is often necessary to be aware of at
 least some of the rules governing MIME messages and their structure,
@@ -84,7 +84,7 @@ to advanced applications.
 Following those is a set of examples of using the fundamental parts of the APIs
 covered in the preceding sections.
 
-The foregoing represent the modern (unicode friendly) API of the email package.
+The foregoing represent the modern (Unicode friendly) API of the email package.
 The remaining sections, starting with the :class:`~email.message.Message`
 class, cover the legacy :data:`~email.policy.compat32` API that deals much more
 directly with the details of how email messages are represented.  The

Doc/library/email.utils.rst

@@ -212,7 +212,7 @@ of the new API.
    When a header parameter is encoded in :rfc:`2231` format,
    :meth:`Message.get_param <email.message.Message.get_param>` may return a
    3-tuple containing the character set,
-   language, and value.  :func:`collapse_rfc2231_value` turns this into a unicode
+   language, and value.  :func:`collapse_rfc2231_value` turns this into a
    string.  Optional *errors* is passed to the *errors* argument of :class:`str`'s
    :func:`~str.encode` method; it defaults to ``'replace'``.  Optional
    *fallback_charset* specifies the character set to use if the one in the

Doc/library/site.rst

@@ -449,12 +449,19 @@ Module contents
       Also processes :file:`.start` files.  See :ref:`site-start-files`.
 
 
-.. function:: getsitepackages()
+.. function:: getsitepackages(prefixes=None)
 
    Return a list containing all global site-packages directories.
 
+   For each directory present in *prefixes* (or :data:`PREFIXES` if *prefixes*
+   is ``None``), this function will find its site-packages subdirectory
+   depending on the system environment, and will return a list of full paths.
+
    .. versionadded:: 3.2
 
+   .. versionchanged:: 3.3
+      Added the optional *prefixes* parameter.
+
 
 .. function:: getuserbase()