Merge branch 'main' into binary-op-extend

Author: savannahostrowski

Doc/faq/programming.rst

@@ -1226,13 +1226,13 @@ This converts the list into a set, thereby removing duplicates, and then back
 into a list.
 
 
-How do you remove multiple items from a list
---------------------------------------------
+How do you remove multiple items from a list?
+---------------------------------------------
 
 As with removing duplicates, explicitly iterating in reverse with a
 delete condition is one possibility.  However, it is easier and faster
 to use slice replacement with an implicit or explicit forward iteration.
-Here are three variations.::
+Here are three variations::
 
    mylist[:] = filter(keep_function, mylist)
    mylist[:] = (x for x in mylist if keep_condition)

Doc/library/importlib.rst

@@ -596,172 +596,6 @@ ABC hierarchy::
         itself does not end in ``__init__``.
 
 
-.. class:: ResourceReader
-
-    *Superseded by TraversableResources*
-
-    An :term:`abstract base class` to provide the ability to read
-    *resources*.
-
-    From the perspective of this ABC, a *resource* is a binary
-    artifact that is shipped within a package. Typically this is
-    something like a data file that lives next to the ``__init__.py``
-    file of the package. The purpose of this class is to help abstract
-    out the accessing of such data files so that it does not matter if
-    the package and its data file(s) are stored e.g. in a zip file
-    versus on the file system.
-
-    For any of methods of this class, a *resource* argument is
-    expected to be a :term:`path-like object` which represents
-    conceptually just a file name. This means that no subdirectory
-    paths should be included in the *resource* argument. This is
-    because the location of the package the reader is for, acts as the
-    "directory". Hence the metaphor for directories and file
-    names is packages and resources, respectively. This is also why
-    instances of this class are expected to directly correlate to
-    a specific package (instead of potentially representing multiple
-    packages or a module).
-
-    Loaders that wish to support resource reading are expected to
-    provide a method called ``get_resource_reader(fullname)`` which
-    returns an object implementing this ABC's interface. If the module
-    specified by fullname is not a package, this method should return
-    :const:`None`. An object compatible with this ABC should only be
-    returned when the specified module is a package.
-
-    .. versionadded:: 3.7
-
-    .. deprecated-removed:: 3.12 3.14
-       Use :class:`importlib.resources.abc.TraversableResources` instead.
-
-    .. method:: open_resource(resource)
-       :abstractmethod:
-
-        Returns an opened, :term:`file-like object` for binary reading
-        of the *resource*.
-
-        If the resource cannot be found, :exc:`FileNotFoundError` is
-        raised.
-
-    .. method:: resource_path(resource)
-       :abstractmethod:
-
-        Returns the file system path to the *resource*.
-
-        If the resource does not concretely exist on the file system,
-        raise :exc:`FileNotFoundError`.
-
-    .. method:: is_resource(name)
-       :abstractmethod:
-
-        Returns ``True`` if the named *name* is considered a resource.
-        :exc:`FileNotFoundError` is raised if *name* does not exist.
-
-    .. method:: contents()
-       :abstractmethod:
-
-        Returns an :term:`iterable` of strings over the contents of
-        the package. Do note that it is not required that all names
-        returned by the iterator be actual resources, e.g. it is
-        acceptable to return names for which :meth:`is_resource` would
-        be false.
-
-        Allowing non-resource names to be returned is to allow for
-        situations where how a package and its resources are stored
-        are known a priori and the non-resource names would be useful.
-        For instance, returning subdirectory names is allowed so that
-        when it is known that the package and resources are stored on
-        the file system then those subdirectory names can be used
-        directly.
-
-        The abstract method returns an iterable of no items.
-
-
-.. class:: Traversable
-
-    An object with a subset of :class:`pathlib.Path` methods suitable for
-    traversing directories and opening files.
-
-    For a representation of the object on the file-system, use
-    :meth:`importlib.resources.as_file`.
-
-    .. versionadded:: 3.9
-
-    .. deprecated-removed:: 3.12 3.14
-       Use :class:`importlib.resources.abc.Traversable` instead.
-
-    .. attribute:: name
-
-       Abstract. The base name of this object without any parent references.
-
-    .. method:: iterdir()
-       :abstractmethod:
-
-       Yield ``Traversable`` objects in ``self``.
-
-    .. method:: is_dir()
-       :abstractmethod:
-
-       Return ``True`` if ``self`` is a directory.
-
-    .. method:: is_file()
-       :abstractmethod:
-
-       Return ``True`` if ``self`` is a file.
-
-    .. method:: joinpath(child)
-       :abstractmethod:
-
-       Return Traversable child in ``self``.
-
-    .. method:: __truediv__(child)
-       :abstractmethod:
-
-       Return ``Traversable`` child in ``self``.
-
-    .. method:: open(mode='r', *args, **kwargs)
-       :abstractmethod:
-
-       *mode* may be 'r' or 'rb' to open as text or binary. Return a handle
-       suitable for reading (same as :attr:`pathlib.Path.open`).
-
-       When opening as text, accepts encoding parameters such as those
-       accepted by :class:`io.TextIOWrapper`.
-
-    .. method:: read_bytes()
-
-       Read contents of ``self`` as bytes.
-
-    .. method:: read_text(encoding=None)
-
-       Read contents of ``self`` as text.
-
-
-.. class:: TraversableResources
-
-    An abstract base class for resource readers capable of serving
-    the :meth:`importlib.resources.files` interface. Subclasses
-    :class:`importlib.resources.abc.ResourceReader` and provides
-    concrete implementations of the :class:`importlib.resources.abc.ResourceReader`'s
-    abstract methods. Therefore, any loader supplying
-    :class:`importlib.abc.TraversableResources` also supplies ResourceReader.
-
-    Loaders that wish to support resource reading are expected to
-    implement this interface.
-
-    .. versionadded:: 3.9
-
-    .. deprecated-removed:: 3.12 3.14
-       Use :class:`importlib.resources.abc.TraversableResources` instead.
-
-    .. method:: files()
-       :abstractmethod:
-
-       Returns a :class:`importlib.resources.abc.Traversable` object for the loaded
-       package.
-
-
-
 :mod:`importlib.machinery` -- Importers and path hooks
 ------------------------------------------------------
 

Doc/library/inspect.rst

@@ -524,7 +524,7 @@ attributes (see :ref:`import-mod-attrs` for module attributes):
 
    .. versionchanged:: 3.13
       Functions wrapped in :func:`functools.partialmethod` now return ``True``
-      if the wrapped function is a :term:`coroutine function`.
+      if the wrapped function is a :term:`asynchronous generator` function.
 
 .. function:: isasyncgen(object)
 

Doc/library/msvcrt.rst

@@ -7,6 +7,8 @@
 
 .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
 
+**Source code:** :source:`PC/msvcrtmodule.c`
+
 --------------
 
 These functions provide access to some useful capabilities on Windows platforms.

Doc/library/winreg.rst

@@ -7,6 +7,8 @@
 
 .. sectionauthor:: Mark Hammond <MarkH@ActiveState.com>
 
+**Source code:** :source:`PC/winreg.c`
+
 --------------
 
 These functions expose the Windows registry API to Python.  Instead of using an
@@ -25,7 +27,7 @@ to explicitly close them.
 .. _functions:
 
 Functions
-------------------
+---------
 
 This module offers the following functions:
 
@@ -554,7 +556,7 @@ This module offers the following functions:
 .. _constants:
 
 Constants
-------------------
+---------
 
 The following constants are defined for use in many :mod:`winreg` functions.
 

Doc/library/winsound.rst

@@ -8,6 +8,8 @@
 .. moduleauthor:: Toby Dickenson <htrd90@zepler.org>
 .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
 
+**Source code:** :source:`PC/winsound.c`
+
 --------------
 
 The :mod:`winsound` module provides access to the basic sound-playing machinery
@@ -16,6 +18,9 @@ provided by Windows platforms.  It includes functions and several constants.
 .. availability:: Windows.
 
 
+Functions
+---------
+
 .. function:: Beep(frequency, duration)
 
    Beep the PC's speaker. The *frequency* parameter specifies frequency, in hertz,
@@ -46,6 +51,9 @@ provided by Windows platforms.  It includes functions and several constants.
    error, :exc:`RuntimeError` is raised.
 
 
+Constants
+---------
+
 .. data:: SND_FILENAME
 
    The *sound* parameter is the name of a WAV file. Do not use with

Doc/whatsnew/3.7.rst

@@ -604,7 +604,7 @@ new ABC for access to, opening, and reading *resources* inside packages.
 Resources are roughly similar to files inside packages, but they needn't
 be actual files on the physical file system.  Module loaders can provide a
 :meth:`!get_resource_reader` function which returns
-a :class:`importlib.abc.ResourceReader` instance to support this
+a :class:`!importlib.abc.ResourceReader` instance to support this
 new API.  Built-in file path loaders and zip file loaders both support this.
 
 Contributed by Barry Warsaw and Brett Cannon in :issue:`32248`.
@@ -1043,7 +1043,7 @@ window are shown and hidden in the Options menu.
 importlib
 ---------
 
-The :class:`importlib.abc.ResourceReader` ABC was introduced to
+The :class:`!importlib.abc.ResourceReader` ABC was introduced to
 support the loading of resources from packages.  See also
 :ref:`whatsnew37_importlib_resources`.
 (Contributed by Barry Warsaw, Brett Cannon in :issue:`32248`.)
@@ -2032,7 +2032,7 @@ both deprecated in Python 3.4 now emit :exc:`DeprecationWarning`.
 (Contributed by Matthias Bussonnier in :issue:`29576`.)
 
 The :class:`importlib.abc.ResourceLoader` ABC has been deprecated in
-favour of :class:`importlib.abc.ResourceReader`.
+favour of :class:`!importlib.abc.ResourceReader`.
 
 
 locale

Lib/email/generator.py

@@ -22,6 +22,7 @@
 NLCRE = re.compile(r'\r\n|\r|\n')
 fcre = re.compile(r'^From ', re.MULTILINE)
 NEWLINE_WITHOUT_FWSP = re.compile(r'\r\n[^ \t]|\r[^ \n\t]|\n[^ \t]')
+NEWLINE_WITHOUT_FWSP_BYTES = re.compile(br'\r\n[^ \t]|\r[^ \n\t]|\n[^ \t]')
 
 
 class Generator:
@@ -429,7 +430,16 @@ def _write_headers(self, msg):
         # This is almost the same as the string version, except for handling
         # strings with 8bit bytes.
         for h, v in msg.raw_items():
-            self._fp.write(self.policy.fold_binary(h, v))
+            folded = self.policy.fold_binary(h, v)
+            if self.policy.verify_generated_headers:
+                linesep = self.policy.linesep.encode()
+                if not folded.endswith(linesep):
+                    raise HeaderWriteError(
+                        f'folded header does not end with {linesep!r}: {folded!r}')
+                if NEWLINE_WITHOUT_FWSP_BYTES.search(folded.removesuffix(linesep)):
+                    raise HeaderWriteError(
+                        f'folded header contains newline: {folded!r}')
+            self._fp.write(folded)
         # A blank line always separates headers from body
         self.write(self._NL)
 

Lib/test/test_email/test_generator.py

@@ -313,7 +313,7 @@ def test_flatten_unicode_linesep(self):
         self.assertEqual(s.getvalue(), self.typ(expected))
 
     def test_verify_generated_headers(self):
-        """gh-121650: by default the generator prevents header injection"""
+        # gh-121650: by default the generator prevents header injection
         class LiteralHeader(str):
             name = 'Header'
             def fold(self, **kwargs):
@@ -334,6 +334,8 @@ def fold(self, **kwargs):
 
                 with self.assertRaises(email.errors.HeaderWriteError):
                     message.as_string()
+                with self.assertRaises(email.errors.HeaderWriteError):
+                    message.as_bytes()
 
 
 class TestBytesGenerator(TestGeneratorBase, TestEmailBase):

Lib/test/test_email/test_policy.py

@@ -296,7 +296,7 @@ def test_short_maxlen_error(self):
                     policy.fold("Subject", subject)
 
     def test_verify_generated_headers(self):
-        """Turning protection off allows header injection"""
+        # Turning protection off allows header injection
         policy = email.policy.default.clone(verify_generated_headers=False)
         for text in (
             'Header: Value\r\nBad: Injection\r\n',
@@ -319,6 +319,10 @@ def fold(self, **kwargs):
                     message.as_string(),
                     f"{text}\nBody",
                 )
+                self.assertEqual(
+                    message.as_bytes(),
+                    f"{text}\nBody".encode(),
+                )
 
     # XXX: Need subclassing tests.
     # For adding subclassed objects, make sure the usual rules apply (subclass