[pull] main from python:main

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/library/calendar.rst

@@ -400,9 +400,9 @@ For simple text calendars this module provides the following functions.
    *month* (``1``--``12``), *day* (``1``--``31``).
 
 
-.. function:: weekheader(n)
+.. function:: weekheader(width)
 
-   Return a header containing abbreviated weekday names. *n* specifies the width in
+   Return a header containing abbreviated weekday names. *width* specifies the width in
    characters for one weekday.
 
 
@@ -430,12 +430,12 @@ For simple text calendars this module provides the following functions.
    of the :class:`TextCalendar` class.
 
 
-.. function:: prcal(year, w=0, l=0, c=6, m=3)
+.. function:: prcal(theyear, w=0, l=0, c=6, m=3)
 
    Prints the calendar for an entire year as returned by  :func:`calendar`.
 
 
-.. function:: calendar(year, w=2, l=1, c=6, m=3)
+.. function:: calendar(theyear, w=2, l=1, c=6, m=3)
 
    Returns a 3-column calendar for an entire year as a multi-line string using
    the :meth:`~TextCalendar.formatyear` of the :class:`TextCalendar` class.

Doc/library/ctypes.rst

@@ -694,6 +694,46 @@ through the :attr:`~_CFuncPtr.errcheck` attribute;
 see the reference manual for details.
 
 
+Specifying function pointers using type annotations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. decorator:: wrap_dll_function(dll)
+   :module: ctypes.util
+
+   A :term:`decorator` that generates :attr:`~ctypes._CFuncPtr.argtypes` and
+   :attr:`~ctypes._CFuncPtr.restype` from a function signature, using the
+   :attr:`~function.__name__` of the function and its :term:`type annotations <annotation>`.
+
+   The decorated function should look like this::
+
+      @wrap_dll_function(dll_to_wrap)
+      def function_ptr_name(arg_name: ctypes_type, ...) -> ctypes_type:
+         # There should be no body
+         pass
+
+   The body of the decorated function is ignored, and any parameters that are
+   missing type annotations are skipped. The names of the parameters are ignored
+   and do not have to match the underlying C implementation.
+
+   If the decorated function does not have a return type annotation, a
+   :exc:`ValueError` is raised. If the name of the function does not exist
+   in *dll*, an :exc:`AttributeError` is raised.
+
+   For example::
+
+      import ctypes
+      from ctypes.util import wrap_dll_function
+
+      @wrap_dll_function(ctypes.pythonapi)
+      def PyObject_GetAttrString(op: ctypes.py_object, attr: ctypes.c_char_p) -> ctypes.py_object:
+         pass
+
+      PyObject_GetAttrString(42, b"real")
+
+
+   .. versionadded:: next
+
+
 .. _ctypes-passing-pointers:
 
 Passing pointers (or: passing parameters by reference)

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/functions.rst

@@ -611,9 +611,10 @@ are always available.  They are listed here in alphabetical order.
       untrusted user-supplied input will lead to security vulnerabilities.
 
    The *source* argument is parsed and evaluated as a Python expression
-   (technically speaking, a condition list) using the *globals* and *locals*
-   mappings as global and local namespace.  If the *globals* dictionary is
-   present and does not contain a value for the key ``__builtins__``, a
+   (technically speaking, an :ref:`expression list <exprlists>`)
+   using the *globals* and *locals* mappings as global and local namespace.
+   If the *globals* dictionary is present and does not contain a value for the
+   key ``__builtins__``, a
    reference to the dictionary of the built-in module :mod:`builtins` is
    inserted under that key before *source* is parsed.
    Overriding ``__builtins__`` can be used to restrict or change the available
@@ -633,6 +634,9 @@ are always available.  They are listed here in alphabetical order.
       >>> eval('x+1')
       2
 
+      >>> eval("1, 2")
+      (1, 2)
+
    This function can also be used to execute arbitrary code objects (such as
    those created by :func:`compile`).  In this case, pass a code object instead
    of a string.  If the code object has been compiled with ``'exec'`` as the

Doc/library/inspect.rst

@@ -635,19 +635,18 @@ attributes (see :ref:`import-mod-attrs` for module attributes):
 .. function:: ismethoddescriptor(object)
 
    Return ``True`` if the object is a method descriptor, but not if
-   :func:`ismethod`, :func:`isclass`, :func:`isfunction` or :func:`isbuiltin`
-   are true.
+   :func:`isclass`, :func:`ismethod` or :func:`isfunction` is true.
 
    This, for example, is true of ``int.__add__``.  An object passing this test
    has a :meth:`~object.__get__` method, but not a :meth:`~object.__set__`
    method or a :meth:`~object.__delete__` method.  Beyond that, the set of
    attributes varies.  A :attr:`~definition.__name__` attribute is usually
    sensible, and :attr:`~definition.__doc__` often is.
 
-   Methods implemented via descriptors that also pass one of the other tests
-   return ``False`` from the :func:`ismethoddescriptor` test, simply because the
-   other tests promise more -- you can, e.g., count on having the
-   :attr:`~method.__func__` attribute (etc) when an object passes
+   Method descriptors that also pass any of the other tests (:func:`!isclass`,
+   :func:`!ismethod` or :func:`!isfunction`) make this function return ``False``,
+   simply because those other tests promise more -- you can, for example, count
+   on having the :attr:`~method.__func__` attribute when an object passes
    :func:`ismethod`.
 
    .. versionchanged:: 3.13
@@ -658,16 +657,28 @@ attributes (see :ref:`import-mod-attrs` for module attributes):
 
 .. function:: isdatadescriptor(object)
 
-   Return ``True`` if the object is a data descriptor.
+   Return ``True`` if the object is a data descriptor, but not if
+   :func:`isclass`, :func:`ismethod` or :func:`isfunction` is true.
 
-   Data descriptors have a :attr:`~object.__set__` or a :attr:`~object.__delete__` method.
-   Examples are properties (defined in Python), getsets, and members.  The
-   latter two are defined in C and there are more specific tests available for
-   those types, which is robust across Python implementations.  Typically, data
-   descriptors will also have :attr:`~definition.__name__` and :attr:`!__doc__` attributes
-   (properties, getsets, and members have both of these attributes), but this is
-   not guaranteed.
+   Data descriptors always have a :meth:`~object.__set__` method and/or
+   a :meth:`~object.__delete__` method.  Optionally, they may also have a
+   :meth:`~object.__get__` method.
 
+   Examples of data descriptors are :func:`properties <property>`, getsets and
+   member descriptors.  Note that for the latter two (defined only in C extension
+   modules), more specific tests are available: :func:`isgetsetdescriptor` and
+   :func:`ismemberdescriptor`, respectively.
+
+   While data descriptors may also have :attr:`~definition.__name__` and
+   :attr:`!__doc__` attributes (as properties, getsets and member descriptors
+   do), this is not necessarily the case in general.
+
+   .. versionchanged:: 3.8
+      This function now reports objects with only a :meth:`~object.__set__` method
+      as being data descriptors (the presence of :meth:`~object.__get__` is no
+      longer required for that).  Moreover, objects with :meth:`~object.__delete__`,
+      but not :meth:`~object.__set__`, are now properly recognized as data
+      descriptors as well, which was not the case previously.
 
 .. function:: isgetsetdescriptor(object)
 

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)

Doc/using/windows.rst

@@ -128,7 +128,7 @@ difference between the two commands is when running without any arguments:
 help (``pymanager exec ...`` provides equivalent behaviour to ``py ...``).
 
 Each of these commands also has a windowed version that avoids creating a
-console window. These are ``pyw``, ``pythonw`` and ``pymanagerw``. A ``python3``
+console window. These are ``pyw``, ``pythonw`` and ``pywmanager``. A ``python3``
 command is also included that mimics the ``python`` command. It is intended to
 catch accidental uses of the typical POSIX command on Windows, but is not meant
 to be widely used or recommended.

Doc/whatsnew/3.15.rst

@@ -1225,7 +1225,7 @@ importlib.metadata
   would return an empty ``PackageMetadata`` object as if the file
   was present but empty. Now, a ``MetadataNotFound`` exception is raised.
   See `importlib_metadata#493 <https://github.com/python/importlib_metadata/issues/493>`_
-  for background and rationale and and :gh:`143387` for rationale on the
+  for background and rationale and :gh:`143387` for rationale on the
   compatibility concerns.
   (Contributed by Jason R. Coombs.)