Merge branch 'main' into fix-gh-153962-internal-poll-oserror

Author: fedonman

Doc/c-api/exceptions.rst

@@ -499,12 +499,12 @@ Querying the error indicator
 .. c:function:: void PyErr_SetRaisedException(PyObject *exc)
 
    Set *exc* as the exception currently being raised,
-   clearing the existing exception if one is set.
+   clearing the existing exception if one is set.  If *exc* is ``NULL``,
+   just clear the existing exception.
 
-   .. warning::
+   *exc* must be a valid exception or ``NULL``.
 
-      This call ":term:`steals <steal>`" a reference to *exc*,
-      which must be a valid exception.
+   This call ":term:`steals <steal>`" a reference to *exc*.
 
    .. versionadded:: 3.12
 

Doc/c-api/frame.rst

@@ -243,3 +243,62 @@ Unless using :pep:`523`, you will not need this.
    Return the currently executing line number, or -1 if there is no line number.
 
    .. versionadded:: 3.12
+
+
+.. c:var:: const PyTypeObject *PyUnstable_ExecutableKinds
+
+   An array of executable kinds (executor types) for frames, used for internal
+   debugging and tracing.
+
+   Tools like debuggers and profilers can use this to identify the type of execution
+   context associated with a frame (such as to filter out internal frames).
+   The entries are indexed by the following constants:
+
+   .. list-table::
+      :header-rows: 1
+      :widths: auto
+
+      * - Constant
+        - Description
+      * - .. c:macro:: PyUnstable_EXECUTABLE_KIND_SKIP
+        - The frame is internal (For example: inlined) and should be skipped by tools.
+      * - .. c:macro:: PyUnstable_EXECUTABLE_KIND_PY_FUNCTION
+        - The frame corresponds to a standard Python function.
+      * - .. c:macro:: PyUnstable_EXECUTABLE_KIND_BUILTIN_FUNCTION
+        - The frame corresponds to a function defined in native code.
+      * - .. c:macro:: PyUnstable_EXECUTABLE_KIND_METHOD_DESCRIPTOR
+        - The frame corresponds to a method on a class instance.
+
+   However, Python's C API lacks a function to read the executable kind from
+   a frame. Instead, use this recipe:
+
+   .. code-block:: c
+
+      int
+      get_executable_kind(PyFrameObject *frame)
+      {
+         _PyInterpreterFrame *f = frame->f_frame;
+         PyObject *exec = PyStackRef_AsPyObjectBorrow(f->f_executable);
+
+         if (PyCode_Check(exec)) {
+            return PyUnstable_EXECUTABLE_KIND_PY_FUNCTION;
+         }
+         if (PyMethod_Check(exec)) {
+            return PyUnstable_EXECUTABLE_KIND_BUILTIN_FUNCTION;
+         }
+         if (Py_IS_TYPE(exec, &PyMethodDescr_Type)) {
+            return PyUnstable_EXECUTABLE_KIND_METHOD_DESCRIPTOR;
+         }
+
+         return PyUnstable_EXECUTABLE_KIND_SKIP;
+      }
+
+   .. versionadded:: 3.13
+
+
+.. c:macro:: PyUnstable_EXECUTABLE_KINDS
+
+   The number of entries in :c:data:`PyUnstable_ExecutableKinds`.
+
+   .. versionadded:: 3.13
+

Doc/c-api/veryhigh.rst

@@ -343,11 +343,125 @@ the same library that the Python runtime is using.
       :py:mod:`!ast` Python module, which exports these constants under
       the same names.
 
+   .. rubric:: Low-level flags
+
+   The following flags and masks serve narrow needs of the standard
+   library and interactive interpreters.  Code outside the standard
+   library rarely has a reason to use them.  They are considered
+   implementation details and may change at any time.
+
+   .. c:macro:: PyCF_ALLOW_INCOMPLETE_INPUT
+
+      This flag is a private interface between the compiler and the
+      :mod:`codeop` module.  Do not use it; its behavior is unsupported
+      and may change without warning.
+
+      With this flag set, when compilation fails because the source text
+      ends where more input is expected, for example in the middle of an
+      indented block or an unterminated string literal, the error raised
+      is the undocumented ``_IncompleteInputError``, a subclass of
+      :exc:`SyntaxError`.  The :mod:`codeop` module sets this flag,
+      together with :c:macro:`PyCF_DONT_IMPLY_DEDENT`, to tell input
+      that is incomplete apart from input with a real syntax error, so
+      that interactive interpreters know when to prompt for another
+      line instead of reporting an error.
+
+      .. versionadded:: 3.11
+
+   .. c:macro:: PyCF_DONT_IMPLY_DEDENT
+
+      By default, when compiling with the :c:var:`Py_single_input` start
+      symbol, reaching the end of the source text implicitly closes any
+      open indented blocks.  With this flag set, open blocks are only
+      closed if the last line of the source ends with a newline; otherwise,
+      compilation fails with a :exc:`SyntaxError`:
+
+      .. code-block:: c
+
+         PyCompilerFlags flags = {
+             .cf_flags = 0,
+             .cf_feature_version = PY_MINOR_VERSION,
+         };
+         const char *source = "if a:\n    pass";
+
+         /* The "if" block is closed implicitly;
+            this returns a code object: */
+         Py_CompileStringFlags(source, "<input>", Py_single_input, &flags);
+
+         /* With the flag, this fails with a SyntaxError,
+            because the last line does not end with a newline: */
+         flags.cf_flags = PyCF_DONT_IMPLY_DEDENT;
+         Py_CompileStringFlags(source, "<input>", Py_single_input, &flags);
+
+      The :mod:`codeop` module uses this flag to detect incomplete
+      interactive input.  While the user is still typing inside an
+      indented block, the source does not yet end with a newline, so it
+      fails to compile and the user is prompted for another line.
+
+   .. c:macro:: PyCF_IGNORE_COOKIE
+
+      Read the source text as UTF-8, ignoring its :pep:`263` encoding
+      declaration ("coding cookie"), if any:
+
+      .. code-block:: c
+
+         PyCompilerFlags flags = {
+             .cf_flags = 0,
+             .cf_feature_version = PY_MINOR_VERSION,
+         };
+         const char *source = "# coding: latin-1\ns = '\xe9'\n";
+
+         /* The coding cookie is honored: byte 0xE9 is decoded as
+            Latin-1, and this returns a code object that sets s to "é": */
+         Py_CompileStringFlags(source, "<input>", Py_file_input, &flags);
+
+         /* With the flag, the cookie is ignored and compilation fails
+            with a SyntaxError, because 0xE9 is not valid UTF-8: */
+         flags.cf_flags = PyCF_IGNORE_COOKIE;
+         Py_CompileStringFlags(source, "<input>", Py_file_input, &flags);
+
+      The :func:`compile`, :func:`eval` and :func:`exec` built-in functions
+      set this flag when the source is a :class:`str` object, because they
+      pass the text to the parser encoded as UTF-8.
+
+   .. c:macro:: PyCF_SOURCE_IS_UTF8
+
+      Mark the source text as known to be UTF-8 encoded.
+      The :func:`compile`, :func:`eval` and :func:`exec` built-in functions
+      set this flag, but it currently has no effect.
+
    The "``PyCF``" flags above can be combined with "``CO_FUTURE``" flags such
    as :c:macro:`CO_FUTURE_ANNOTATIONS` to enable features normally
    selectable using :ref:`future statements <future>`.
    See :ref:`c_codeobject_flags` for a complete list.
 
+   The following masks combine several flags:
+
+   .. c:macro:: PyCF_MASK
+
+      Bitmask of all ``CO_FUTURE`` flags (see :ref:`c_codeobject_flags`),
+      which select features normally enabled by
+      :ref:`future statements <future>`.
+      When code compiled with a ``PyCompilerFlags *flags`` argument
+      contains a ``from __future__ import`` statement, the flag for the
+      imported feature is added to *flags*, so that code executed later
+      in the same context inherits it.
+
+   .. c:macro:: PyCF_MASK_OBSOLETE
+
+      Do not use this mask in new code.  It is kept only so that old
+      code passing its flags to :func:`compile` keeps working.
+
+      Bitmask of flags for obsolete future features that no longer
+      have any effect.
+
+   .. c:macro:: PyCF_COMPILE_MASK
+
+      Bitmask of all ``PyCF`` flags that change how the source is
+      compiled, such as :c:macro:`PyCF_ONLY_AST`.
+      The :func:`compile` built-in function uses this mask to validate
+      its *flags* argument.
+
 
 .. _start-symbols:
 

Doc/howto/abi3t-migration.rst

@@ -8,14 +8,14 @@ Migrating to Stable ABI for free threading (``abi3t``)
 
 Starting with the 3.15 release, CPython supports a variant of the Stable ABI
 that supports :term:`free-threaded <free threading>` Python:
-Stable ABI for Free-Threaded Builds, or ``abi3t`` for short.
+the Stable ABI for Free-Threaded Builds, or ``abi3t`` for short.
 This document describes how to adapt C API extensions to support free threading.
 
 Why do this
 ===========
 
-The typical reason to use Stable ABI is to reduce the number of artifacts that
-you need to build and distribute for each version of your library.
+The typical reason to use the Stable ABI is to reduce the number of artifacts
+that you need to build and distribute for each version of your library.
 
 Without the Stable ABI, you must build a separate shared library, and typically
 a *wheel* distribution, for each feature version of CPython you wish
@@ -87,16 +87,16 @@ builds; even the 3.15+ ones that this table "attributes" to ``abi3t``.)
 Why *not* do this
 -----------------
 
-There are two main downsides to Stable ABI.
+There are two main downsides to the Stable ABI.
 
-First, you extension may become slower, since Stable ABI prioritizes
+First, your extension may become slower, since the Stable ABI prioritizes
 compatibility over performance.
 The difference is usually not noticeable, and often can be mitigated by
 using the same source to build both a Stable ABI build and a few
 version-specific ones for "tier 1" CPython versions.
 
 Second, not all of the C API is available.
-Extensions need to be ported to build for Stable ABI, which may be difficult
+Extensions need to be ported to build for the Stable ABI, which may be difficult
 or, in rare cases, impossible.
 
 Specifically, ``abi3t`` requires APIs added in CPython 3.15.
@@ -127,15 +127,15 @@ Prerequisites
 This guide assumes that you have an extension written directly in C (or C++),
 which you want to port to ``abi3t``.
 
-If your extenstion uses a code generator (like Cython) or language binding
+If your extension uses a code generator (like Cython) or language binding
 (like PyO3), it's best to wait until that tool has support for ``abi3t``.
 If you maintain such a tool, you might be able to adapt the instructions
 here for your tool.
 
 Non-free-threaded Stable ABI
 ----------------------------
 
-Your extension should support the Stable ABI (``abi3t``).
+Your extension should support the non-free-threaded Stable ABI (``abi3``).
 If not, either port it first, or follow this guide but be prepared to fix
 issues it does not mention.
 
@@ -183,7 +183,7 @@ following just after ``#include <Python.h>``::
    #error "abi3t define is not set!"
    #endif
 
-This should result in a different error than "``abt3t`` define is not set".
+This should result in a different error than "``abi3t`` define is not set".
 
 .. note::
 
@@ -705,7 +705,7 @@ Testing
 Note that when you build an extension compatible with multiple versions of
 CPython, you should always *test* it with each version it supports (for
 example, 3.15, 3.16, and so on).
-Stable ABI only guarantees *ABI* compatibility; there may also be behavior
+The Stable ABI only guarantees *ABI* compatibility; there may also be behavior
 changes -- both intentional ones (covered by :pep:`387`) and bugs.
 
 Be sure to run tests on both free-threaded and non-free-threaded builds

Doc/howto/logging-cookbook.rst

@@ -1955,7 +1955,7 @@ Subclass ``QueueListener``
     class NNGSocketListener(logging.handlers.QueueListener):
 
         def __init__(self, uri, /, *handlers, **kwargs):
-            # Have a timeout for interruptability, and open a
+            # Have a timeout for interruptibility, and open a
             # subscriber socket
             socket = pynng.Sub0(listen=uri, recv_timeout=500)
             # The b'' subscription matches all topics

Doc/library/curses.rst

@@ -1321,6 +1321,8 @@ Reading window contents
    The bottom 8 bits are the character proper and the upper bits are the attributes;
    extract them with the :data:`A_CHARTEXT` and :data:`A_ATTRIBUTES` bit-masks,
    and the color pair with :func:`pair_number`.
+   The character byte is the locale-encoded byte of the cell's character,
+   consistent with :meth:`instr`.
    It cannot represent a cell holding combining characters, a character that does
    not fit in a single byte, or a color pair outside the :func:`color_pair`
    range; use :meth:`in_wch` for those, which returns it as a :class:`complexchar`.

Doc/library/datatypes.rst

@@ -8,9 +8,10 @@ The modules described in this chapter provide a variety of specialized data
 types such as dates and times, fixed-type arrays, heap queues, double-ended
 queues, and enumerations.
 
-Python also provides some built-in data types, in particular,
-:class:`dict`, :class:`list`, :class:`set` and :class:`frozenset`, and
-:class:`tuple`.  The :class:`str` class is used to hold
+Python also provides :ref:`some built-in data types <bltin-types>`, in particular,
+:class:`list`, :class:`tuple`, :class:`dict`, :class:`frozendict`,
+:class:`set`,  and :class:`frozenset`.
+The :class:`str` class is used to hold
 Unicode strings, and the :class:`bytes` and :class:`bytearray` classes are used
 to hold binary data.
 

Doc/library/difflib.rst

@@ -85,6 +85,11 @@ diffs. For comparing directories and files, see also, the :mod:`filecmp` module.
    with inter-line and intra-line change highlights.  The table can be generated in
    either full or contextual difference mode.
 
+   .. warning::
+
+      The trailing newlines get stripped before the diff, so the result can be
+      incomplete. See :gh:`71896` for details.
+
    The constructor for this class is:
 
 

Doc/library/getopt.rst

@@ -62,6 +62,8 @@ exception:
    option ``--fo`` will match as ``--foo``, but ``--f`` will
    not match uniquely, so :exc:`GetoptError` will be raised.
 
+   If *longopts* is a string it gets treated as a list of a single element.
+
    The return value consists of two elements: the first is a list of ``(option,
    value)`` pairs; the second is the list of program arguments left after the
    option list was stripped (this is a trailing slice of *args*).  Each

Doc/library/mimetypes.rst

@@ -116,12 +116,13 @@ behavior of the module.
       Previously, Windows registry settings were ignored.
 
 
-.. function:: read_mime_types(filename)
+.. function:: read_mime_types(file)
 
-   Load the type map given in the file *filename*, if it exists.  The type map is
-   returned as a dictionary mapping filename extensions, including the leading dot
-   (``'.'``), to strings of the form ``'type/subtype'``.  If the file *filename*
-   does not exist or cannot be read, ``None`` is returned.
+   Load the type map given in the file named by *file*, if it exists.  *file*
+   must be a string specifying the name of the file to read.  The type map is
+   returned as a dictionary mapping file extensions, including the leading dot
+   (``'.'``), to strings of the form ``'type/subtype'``.  If the file does not
+   exist or cannot be read, ``None`` is returned.
 
 
 .. function:: add_type(type, ext, strict=True)