Merge branch 'main' into gh-119186-joining

Author: barneygale

.github/CODEOWNERS

@@ -72,6 +72,7 @@ Include/internal/pycore_freelist.h  @ericsnowcurrently
 Include/internal/pycore_global_objects.h  @ericsnowcurrently
 Include/internal/pycore_obmalloc.h  @ericsnowcurrently
 Include/internal/pycore_pymem.h     @ericsnowcurrently
+Include/internal/pycore_stackref.h  @Fidget-Spinner
 Modules/main.c                @ericsnowcurrently
 Programs/_bootstrap_python.c  @ericsnowcurrently
 Programs/python.c             @ericsnowcurrently

Doc/c-api/object.rst

@@ -52,6 +52,7 @@ Object Protocol
 
    The reference is borrowed from the interpreter, and is valid until the
    interpreter finalization.
+
    .. versionadded:: 3.13
 
 

Doc/library/os.path.rst

@@ -389,7 +389,7 @@ the :mod:`glob` module.)
    that contains symbolic links.  On Windows, it converts forward slashes to
    backward slashes. To normalize case, use :func:`normcase`.
 
-  .. note::
+   .. note::
       On POSIX systems, in accordance with `IEEE Std 1003.1 2013 Edition; 4.13
       Pathname Resolution <https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_13>`_,
       if a pathname begins with exactly two slashes, the first component

Doc/library/pathlib.rst

@@ -1539,7 +1539,7 @@ Creating files and directories
 Copying, renaming and deleting
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. method:: Path.copy(target, *, follow_symlinks=True)
+.. method:: Path.copy(target, *, follow_symlinks=True, preserve_metadata=False)
 
    Copy the contents of this file to the *target* file. If *target* specifies
    a file that already exists, it will be replaced.
@@ -1548,11 +1548,11 @@ Copying, renaming and deleting
    will be created as a symbolic link. If *follow_symlinks* is true and this
    file is a symbolic link, *target* will be a copy of the symlink target.
 
-   .. note::
-      This method uses operating system functionality to copy file content
-      efficiently. The OS might also copy some metadata, such as file
-      permissions. After the copy is complete, users may wish to call
-      :meth:`Path.chmod` to set the permissions of the target file.
+   If *preserve_metadata* is false (the default), only the file data is
+   guaranteed to be copied. Set *preserve_metadata* to true to ensure that the
+   file mode (permissions), flags, last access and modification times, and
+   extended attributes are copied where supported. This argument has no effect
+   on Windows, where metadata is always preserved when copying.
 
    .. versionadded:: 3.14
 

Doc/requirements-oldest-sphinx.txt

@@ -14,7 +14,7 @@ python-docs-theme>=2022.1
 
 alabaster==0.7.16
 Babel==2.15.0
-certifi==2024.6.2
+certifi==2024.7.4
 charset-normalizer==3.3.2
 docutils==0.19
 idna==3.7

Lib/asyncio/__main__.py

@@ -116,7 +116,7 @@ def run(self):
                 if err := check():
                     raise RuntimeError(err)
             except Exception as e:
-                console.interact(banner="", exitmsg=exit_message)
+                console.interact(banner="", exitmsg="")
             else:
                 try:
                     run_multiline_interactive_console(console=console)

Lib/os.py

@@ -373,61 +373,45 @@ def walk(top, topdown=True, onerror=None, followlinks=False):
         # minor reason when (say) a thousand readable directories are still
         # left to visit.
         try:
-            scandir_it = scandir(top)
+            with scandir(top) as entries:
+                for entry in entries:
+                    try:
+                        if followlinks is _walk_symlinks_as_files:
+                            is_dir = entry.is_dir(follow_symlinks=False) and not entry.is_junction()
+                        else:
+                            is_dir = entry.is_dir()
+                    except OSError:
+                        # If is_dir() raises an OSError, consider the entry not to
+                        # be a directory, same behaviour as os.path.isdir().
+                        is_dir = False
+
+                    if is_dir:
+                        dirs.append(entry.name)
+                    else:
+                        nondirs.append(entry.name)
+
+                    if not topdown and is_dir:
+                        # Bottom-up: traverse into sub-directory, but exclude
+                        # symlinks to directories if followlinks is False
+                        if followlinks:
+                            walk_into = True
+                        else:
+                            try:
+                                is_symlink = entry.is_symlink()
+                            except OSError:
+                                # If is_symlink() raises an OSError, consider the
+                                # entry not to be a symbolic link, same behaviour
+                                # as os.path.islink().
+                                is_symlink = False
+                            walk_into = not is_symlink
+
+                        if walk_into:
+                            walk_dirs.append(entry.path)
         except OSError as error:
             if onerror is not None:
                 onerror(error)
             continue
 
-        cont = False
-        with scandir_it:
-            while True:
-                try:
-                    try:
-                        entry = next(scandir_it)
-                    except StopIteration:
-                        break
-                except OSError as error:
-                    if onerror is not None:
-                        onerror(error)
-                    cont = True
-                    break
-
-                try:
-                    if followlinks is _walk_symlinks_as_files:
-                        is_dir = entry.is_dir(follow_symlinks=False) and not entry.is_junction()
-                    else:
-                        is_dir = entry.is_dir()
-                except OSError:
-                    # If is_dir() raises an OSError, consider the entry not to
-                    # be a directory, same behaviour as os.path.isdir().
-                    is_dir = False
-
-                if is_dir:
-                    dirs.append(entry.name)
-                else:
-                    nondirs.append(entry.name)
-
-                if not topdown and is_dir:
-                    # Bottom-up: traverse into sub-directory, but exclude
-                    # symlinks to directories if followlinks is False
-                    if followlinks:
-                        walk_into = True
-                    else:
-                        try:
-                            is_symlink = entry.is_symlink()
-                        except OSError:
-                            # If is_symlink() raises an OSError, consider the
-                            # entry not to be a symbolic link, same behaviour
-                            # as os.path.islink().
-                            is_symlink = False
-                        walk_into = not is_symlink
-
-                    if walk_into:
-                        walk_dirs.append(entry.path)
-        if cont:
-            continue
-
         if topdown:
             # Yield before sub-directory traversal if going top down
             yield top, dirs, nondirs

Lib/pathlib/_abc.py

@@ -781,7 +781,32 @@ def mkdir(self, mode=0o777, parents=False, exist_ok=False):
         """
         raise UnsupportedOperation(self._unsupported_msg('mkdir()'))
 
-    def copy(self, target, follow_symlinks=True):
+    # Metadata keys supported by this path type.
+    _readable_metadata = _writable_metadata = frozenset()
+
+    def _read_metadata(self, keys=None, *, follow_symlinks=True):
+        """
+        Returns path metadata as a dict with string keys.
+        """
+        raise UnsupportedOperation(self._unsupported_msg('_read_metadata()'))
+
+    def _write_metadata(self, metadata, *, follow_symlinks=True):
+        """
+        Sets path metadata from the given dict with string keys.
+        """
+        raise UnsupportedOperation(self._unsupported_msg('_write_metadata()'))
+
+    def _copy_metadata(self, target, *, follow_symlinks=True):
+        """
+        Copies metadata (permissions, timestamps, etc) from this path to target.
+        """
+        # Metadata types supported by both source and target.
+        keys = self._readable_metadata & target._writable_metadata
+        if keys:
+            metadata = self._read_metadata(keys, follow_symlinks=follow_symlinks)
+            target._write_metadata(metadata, follow_symlinks=follow_symlinks)
+
+    def copy(self, target, *, follow_symlinks=True, preserve_metadata=False):
         """
         Copy the contents of this file to the given target. If this file is a
         symlink and follow_symlinks is false, a symlink will be created at the
@@ -793,6 +818,8 @@ def copy(self, target, follow_symlinks=True):
             raise OSError(f"{self!r} and {target!r} are the same file")
         if not follow_symlinks and self.is_symlink():
             target.symlink_to(self.readlink())
+            if preserve_metadata:
+                self._copy_metadata(target, follow_symlinks=False)
             return
         with self.open('rb') as source_f:
             try:
@@ -805,6 +832,8 @@ def copy(self, target, follow_symlinks=True):
                         f'Directory does not exist: {target}') from e
                 else:
                     raise
+        if preserve_metadata:
+            self._copy_metadata(target)
 
     def copytree(self, target, *, follow_symlinks=True, dirs_exist_ok=False,
                  ignore=None, on_error=None):

Lib/pathlib/_local.py

@@ -17,7 +17,8 @@
 except ImportError:
     grp = None
 
-from ._os import UnsupportedOperation, copyfile
+from ._os import (UnsupportedOperation, copyfile, file_metadata_keys,
+                  read_file_metadata, write_file_metadata)
 from ._abc import PurePathBase, PathBase
 
 
@@ -781,8 +782,12 @@ def mkdir(self, mode=0o777, parents=False, exist_ok=False):
             if not exist_ok or not self.is_dir():
                 raise
 
+    _readable_metadata = _writable_metadata = file_metadata_keys
+    _read_metadata = read_file_metadata
+    _write_metadata = write_file_metadata
+
     if copyfile:
-        def copy(self, target, follow_symlinks=True):
+        def copy(self, target, *, follow_symlinks=True, preserve_metadata=False):
             """
             Copy the contents of this file to the given target. If this file is a
             symlink and follow_symlinks is false, a symlink will be created at the
@@ -799,7 +804,8 @@ def copy(self, target, follow_symlinks=True):
                     return
                 except UnsupportedOperation:
                     pass  # Fall through to generic code.
-            PathBase.copy(self, target, follow_symlinks=follow_symlinks)
+            PathBase.copy(self, target, follow_symlinks=follow_symlinks,
+                          preserve_metadata=preserve_metadata)
 
     def chmod(self, mode, *, follow_symlinks=True):
         """

Lib/pathlib/_os.py

@@ -2,7 +2,7 @@
 Low-level OS functionality wrappers used by pathlib.
 """
 
-from errno import EBADF, EOPNOTSUPP, ETXTBSY, EXDEV
+from errno import *
 import os
 import stat
 import sys
@@ -178,3 +178,100 @@ def copyfileobj(source_f, target_f):
     write_target = target_f.write
     while buf := read_source(1024 * 1024):
         write_target(buf)
+
+
+# Kinds of metadata supported by the operating system.
+file_metadata_keys = {'mode', 'times_ns'}
+if hasattr(os.stat_result, 'st_flags'):
+    file_metadata_keys.add('flags')
+if hasattr(os, 'listxattr'):
+    file_metadata_keys.add('xattrs')
+file_metadata_keys = frozenset(file_metadata_keys)
+
+
+def read_file_metadata(path, keys=None, *, follow_symlinks=True):
+    """
+    Returns local path metadata as a dict with string keys.
+    """
+    if keys is None:
+        keys = file_metadata_keys
+    assert keys.issubset(file_metadata_keys)
+    result = {}
+    for key in keys:
+        if key == 'xattrs':
+            try:
+                result['xattrs'] = [
+                    (attr, os.getxattr(path, attr, follow_symlinks=follow_symlinks))
+                    for attr in os.listxattr(path, follow_symlinks=follow_symlinks)]
+            except OSError as err:
+                if err.errno not in (EPERM, ENOTSUP, ENODATA, EINVAL, EACCES):
+                    raise
+            continue
+        st = os.stat(path, follow_symlinks=follow_symlinks)
+        if key == 'mode':
+            result['mode'] = stat.S_IMODE(st.st_mode)
+        elif key == 'times_ns':
+            result['times_ns'] = st.st_atime_ns, st.st_mtime_ns
+        elif key == 'flags':
+            result['flags'] = st.st_flags
+    return result
+
+
+def write_file_metadata(path, metadata, *, follow_symlinks=True):
+    """
+    Sets local path metadata from the given dict with string keys.
+    """
+    assert frozenset(metadata.keys()).issubset(file_metadata_keys)
+
+    def _nop(*args, ns=None, follow_symlinks=None):
+        pass
+
+    if follow_symlinks:
+        # use the real function if it exists
+        def lookup(name):
+            return getattr(os, name, _nop)
+    else:
+        # use the real function only if it exists
+        # *and* it supports follow_symlinks
+        def lookup(name):
+            fn = getattr(os, name, _nop)
+            if fn in os.supports_follow_symlinks:
+                return fn
+            return _nop
+
+    times_ns = metadata.get('times_ns')
+    if times_ns is not None:
+        lookup("utime")(path, ns=times_ns, follow_symlinks=follow_symlinks)
+    # We must copy extended attributes before the file is (potentially)
+    # chmod()'ed read-only, otherwise setxattr() will error with -EACCES.
+    xattrs = metadata.get('xattrs')
+    if xattrs is not None:
+        for attr, value in xattrs:
+            try:
+                os.setxattr(path, attr, value, follow_symlinks=follow_symlinks)
+            except OSError as e:
+                if e.errno not in (EPERM, ENOTSUP, ENODATA, EINVAL, EACCES):
+                    raise
+    mode = metadata.get('mode')
+    if mode is not None:
+        try:
+            lookup("chmod")(path, mode, follow_symlinks=follow_symlinks)
+        except NotImplementedError:
+            # if we got a NotImplementedError, it's because
+            #   * follow_symlinks=False,
+            #   * lchown() is unavailable, and
+            #   * either
+            #       * fchownat() is unavailable or
+            #       * fchownat() doesn't implement AT_SYMLINK_NOFOLLOW.
+            #         (it returned ENOSUP.)
+            # therefore we're out of options--we simply cannot chown the
+            # symlink.  give up, suppress the error.
+            # (which is what shutil always did in this circumstance.)
+            pass
+    flags = metadata.get('flags')
+    if flags is not None:
+        try:
+            lookup("chflags")(path, flags, follow_symlinks=follow_symlinks)
+        except OSError as why:
+            if why.errno not in (EOPNOTSUPP, ENOTSUP):
+                raise