Merge branch 'main' into scanfix-stringio-mphgx2fl

Author: gpshead

.github/workflows/reusable-emscripten.yml

@@ -79,3 +79,5 @@ jobs:
       run: python3 Platforms/emscripten run --test
     - name: "Test Repl"
       run: Platforms/emscripten/browser_test/run_test.sh
+    - name: "Test embedding"
+      run: Platforms/emscripten/web_embed_test/run_test.sh

.github/workflows/reusable-wasi.yml

@@ -16,7 +16,6 @@ jobs:
     timeout-minutes: 60
     env:
       WASMTIME_VERSION: 48.0.2
-      CROSS_BUILD_WASI: cross-build/wasm32-wasip1
     steps:
     - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       with:
@@ -65,4 +64,6 @@ jobs:
     - name: "Display build info of the host/WASI Python"
       run: python3 Platforms/WASI pythoninfo-host
     - name: "Test"
-      run: make --directory "${CROSS_BUILD_WASI}" test
+      run: |
+        CROSS_BUILD_WASI=$(python3 Platforms/WASI path)
+        make --directory "${CROSS_BUILD_WASI}" test

Doc/README.rst

@@ -21,6 +21,7 @@ tree but are maintained separately and are available from
 * `Sphinx <https://pypi.org/project/Sphinx/>`_
 * `blurb <https://pypi.org/project/blurb/>`_
 * `python-docs-theme <https://pypi.org/project/python-docs-theme/>`_
+* `sphinx-linklint <https://pypi.org/project/sphinx-linklint/>`_
 
 The easiest way to install these tools is to create a virtual environment and
 install the tools into there.
@@ -57,6 +58,8 @@ Available make targets are:
 * "venv", which creates a virtual environment with all necessary tools
   installed.
 
+* "lock", which regenerates the pinned dependencies in ``pylock.toml``.
+
 * "html", which builds standalone HTML files for offline viewing.
 
 * "htmlview", which re-uses the "html" builder, but then opens the main page
@@ -79,6 +82,9 @@ Available make targets are:
 
 * "text", which builds a plain text file for each source file.
 
+* "texinfo", which builds Texinfo source files as input to ``makeinfo`` to
+  produce Info documents.
+
 * "epub", which builds an EPUB document, suitable to be viewed on e-book
   readers.
 
@@ -97,6 +103,10 @@ Available make targets are:
   plain text documentation for the labels defined in
   ``tools/pyspecific.py`` -- pydoc needs these to show topic and keyword help.
 
+* "doctest", which runs doctests in the documentation.
+
+* "gettext", which generates gettext message catalog templates.
+
 * "check", which checks for frequent markup errors.
 
 * "dist", (Unix only) which creates distributable archives of HTML, text,

Doc/library/argparse.rst

@@ -789,6 +789,9 @@ how the command-line arguments should be handled. The supplied actions are:
     >>> parser.parse_args('--foo --bar'.split())
     Namespace(foo=True, bar=False, baz=True)
 
+  These defaults apply when the options are absent. They can be overridden
+  by default_ or argument_default_.
+
 * ``'append'`` - This appends each argument value to a list.
   It is useful for allowing an option to be specified multiple times.
   If the default value is a non-empty list, the parsed value for the option
@@ -1016,10 +1019,8 @@ default
 
 All optional arguments and some positional arguments may be omitted at the
 command line.  The ``default`` keyword argument of
-:meth:`~ArgumentParser.add_argument`, whose value defaults to ``None``,
-specifies what value should be used if the command-line argument is not present.
-For optional arguments, the ``default`` value is used when the option string
-was not present at the command line::
+:meth:`~ArgumentParser.add_argument` specifies what value should be used if the
+command-line argument is not present. For example::
 
    >>> parser = argparse.ArgumentParser()
    >>> parser.add_argument('--foo', default=42)
@@ -1028,6 +1029,11 @@ was not present at the command line::
    >>> parser.parse_args([])
    Namespace(foo=42)
 
+If ``default`` is omitted, :meth:`~ArgumentParser.add_argument` uses a value
+previously set for the dest_ with :meth:`~ArgumentParser.set_defaults`, or
+otherwise a non-``None`` argument_default_. If neither is set, the action's
+own default is used.
+
 If the target namespace already has an attribute set, the action *default*
 will not overwrite it::
 

Doc/library/ctypes.rst

@@ -1337,6 +1337,31 @@ write::
    :class:`threading.local` will *not* survive across different callbacks, even when
    those calls are made from the same C thread.
 
+Callback functions can return structures and unions by value, in addition to
+the simple types:
+
+.. code-block:: python
+
+   class Point(Structure):
+       _fields_ = [("x", c_int), ("y", c_int)]
+
+   @CFUNCTYPE(Point)
+   def get_origin():
+       return Point(0, 0)
+
+.. note::
+
+   A structure or union returned from a callback is copied *by value*, and
+   :mod:`!ctypes` does not keep the returned object alive after the callback
+   returns. If the structure contains a pointer field (such as
+   :class:`c_char_p` or a :func:`POINTER` type), you must ensure that the
+   memory it refers to stays valid for as long as the C code uses it -- the
+   same requirement C itself imposes. Returning a pointer to memory owned by
+   a temporary Python object will leave the C caller with a dangling pointer.
+
+.. versionchanged:: next
+   Callback functions can now return structures and unions.
+
 .. _ctypes-accessing-values-exported-from-dlls:
 
 Accessing values exported from dlls

Doc/library/curses.rst

@@ -274,9 +274,11 @@ Input options
 
    Used for half-delay mode, which is similar to cbreak mode in that characters
    typed by the user are immediately available to the program. However, after
-   blocking for *tenths* tenths of seconds, raise an exception if nothing has
-   been typed.  The value of *tenths* must be a number between ``1`` and ``255``.  Use
-   :func:`nocbreak` to leave half-delay mode.
+   blocking for *tenths* tenths of seconds, if nothing has been typed,
+   :meth:`~window.getch` returns ``-1``, while :meth:`~window.getkey` and
+   :meth:`~window.get_wch` raise :exc:`curses.error`.
+   The value of *tenths* must be a number between ``1`` and ``255``.
+   Use :func:`nocbreak` to leave half-delay mode.
 
 .. function:: meta(flag)
 
@@ -893,8 +895,10 @@ Querying the terminal
 
 .. function:: termname()
 
-   Return the value of the environment variable :envvar:`TERM`, as a bytes object,
-   truncated to 14 characters.
+   Return the name of the terminal in use, as a bytes object.
+   This is the name passed to :func:`newterm` or
+   :func:`setupterm`, or the value of the :envvar:`TERM` environment variable
+   if none was given.  Some curses libraries truncate it to 14 characters.
 
 .. function:: longname()
 
@@ -1227,7 +1231,8 @@ Adding and inserting text
    Insert character *ch* with attributes *attr* before the character under the
    cursor, or at ``(y, x)`` if specified.  All characters to the right of the
    cursor are shifted one position right, with the rightmost character on the
-   line being lost.  The cursor position does not change.
+   line being lost.
+   The cursor position does not change (after moving to *y*, *x*, if specified).
 
    .. versionchanged:: 3.16
       Wide and combining characters, and :class:`complexchar` cells, are now
@@ -1251,8 +1256,8 @@ Adding and inserting text
             window.insnstr(y, x, str, n[, attr])
 
    Insert a character string (as many characters as will fit on the line) before
-   the character under the cursor, up to *n* characters.   If *n* is zero or
-   negative, the entire string is inserted. All characters to the right of the
+   the character under the cursor, up to *n* characters.   If *n* is negative,
+   the entire string is inserted. All characters to the right of the
    cursor are shifted right, with the rightmost characters on the line being lost.
    The cursor position does not change (after moving to *y*, *x*, if specified).
 
@@ -1871,8 +1876,9 @@ Output options
 .. method:: window.scroll([lines=1])
 
    Scroll the screen or scrolling region.  Scroll upward by *lines* lines if
-   *lines* is positive, or downward if it is negative.  Scrolling has no effect
-   unless it has been enabled for the window with :meth:`scrollok`.
+   *lines* is positive, or downward if it is negative.
+   Raise :exc:`curses.error` unless scrolling has been enabled for the window
+   with :meth:`scrollok`.
 
 .. method:: window.setscrreg(top, bottom)
 

Doc/library/dis.rst

@@ -1436,10 +1436,14 @@ iterations of the loop.
 .. opcode:: LOAD_GLOBAL (namei)
 
    Loads the global named ``co_names[namei>>1]`` onto the stack.
+   If the low bit of ``namei`` is set, a ``NULL`` is pushed onto the stack
+   after the global variable.
 
    .. versionchanged:: 3.11
-      If the low bit of ``namei`` is set, then a ``NULL`` is pushed to the
-      stack before the global variable.
+      The low bit of ``namei`` indicates whether a ``NULL`` is pushed.
+
+   .. versionchanged:: 3.13
+      The ``NULL`` is pushed after the global variable, rather than before it.
 
 .. opcode:: LOAD_FAST (var_num)
 

Doc/library/shutil.rst

@@ -242,7 +242,7 @@ Directory and files operations
 
 .. function:: copytree(src, dst, symlinks=False, ignore=None, \
               copy_function=copy2, ignore_dangling_symlinks=False, \
-              dirs_exist_ok=False)
+              dirs_exist_ok=False, *, copy_dir_stat=True)
 
    Recursively copy an entire directory tree rooted at *src* to a directory
    named *dst* and return the destination directory.  All intermediate
@@ -251,6 +251,12 @@ Directory and files operations
    Permissions and times of directories are copied with :func:`copystat`,
    individual files are copied using :func:`~shutil.copy2`.
 
+   If *copy_dir_stat* is false, directory metadata is not copied with
+   :func:`copystat`, e.g. to copy a read-only tree into a writable one.
+   It defaults to true.  Note that file metadata is always handled by
+   *copy_function*: use e.g. ``copy_function=shutil.copyfile`` to skip
+   that as well.
+
    If *symlinks* is true, symbolic links in the source tree are represented as
    symbolic links in the new tree and the metadata of the original links will
    be copied as far as the platform allows; if false or omitted, the contents
@@ -306,6 +312,9 @@ Directory and files operations
    .. versionchanged:: 3.8
       Added the *dirs_exist_ok* parameter.
 
+   .. versionchanged:: 3.16
+      Added the *copy_dir_stat* parameter.
+
 .. function:: rmtree(path, ignore_errors=False, onerror=None, *, onexc=None, dir_fd=None)
 
    .. index:: single: directory; deleting
@@ -316,6 +325,12 @@ Directory and files operations
    handled by calling a handler specified by *onexc* or *onerror* or, if both
    are omitted, exceptions are propagated to the caller.
 
+   If *path* is a symbolic link to a directory followed by a trailing path
+   separator, such as ``'link/'``, the operating system resolves the link, so
+   :func:`!rmtree` deletes the contents of the directory it points to and then
+   fails to remove *path* itself.  :class:`pathlib.Path` strips trailing
+   separators, so ``rmtree(Path('link/'))`` refuses the link as usual.
+
    This function can support :ref:`paths relative to directory descriptors
    <dir_fd>`.
 

Doc/library/tarfile.rst

@@ -1131,6 +1131,11 @@ reused in custom filters:
   - :ref:`Refuse <tarfile-extraction-refuse>` to extract files whose absolute
     path (after following symlinks) would end up outside the destination.
     This raises :class:`~tarfile.OutsideDestinationError`.
+  - :ref:`Refuse <tarfile-extraction-refuse>` to extract links (hard or soft)
+    whose name refers to the destination directory itself.
+    This raises :class:`~tarfile.OutsideDestinationError`.
+    Note that such files are refused even on platforms that do not support
+    symbolic links.
   - Clear high mode bits (setuid, setgid, sticky) and group/other write bits
     (:const:`~stat.S_IWGRP` | :const:`~stat.S_IWOTH`).
 

Doc/library/zipfile.rst

@@ -722,6 +722,10 @@ Path objects are traversable using the ``/`` operator or ``joinpath``.
 
    Enumerate the children of the current directory.
 
+   .. versionchanged:: 3.16
+      Raises :exc:`NotADirectoryError` when the current context does not
+      reference a directory. Previously, it raised :exc:`ValueError`.
+
 .. method:: Path.is_dir()
 
    Return ``True`` if the current context references a directory.