[pull] main from python:main

Doc/c-api/import.rst

@@ -314,6 +314,13 @@ Importing Modules
    initialization.
 
 
+.. c:var:: struct _inittab *PyImport_Inittab
+
+   The table of built-in modules used by Python initialization. Do not use this directly;
+   use :c:func:`PyImport_AppendInittab` and :c:func:`PyImport_ExtendInittab`
+   instead.
+
+
 .. c:function:: PyObject* PyImport_ImportModuleAttr(PyObject *mod_name, PyObject *attr_name)
 
    Import the module *mod_name* and get its attribute *attr_name*.

Doc/c-api/intro.rst

@@ -322,6 +322,19 @@ complete listing.
       PyDoc_VAR(python_doc) = PyDoc_STR("A genus of constricting snakes in the Pythonidae family native "
                                         "to the tropics and subtropics of the Eastern Hemisphere.");
 
+.. c:macro:: Py_ARRAY_LENGTH(array)
+
+   Compute the length of a statically allocated C array at compile time.
+
+   The *array* argument must be a C array with a size known at compile time.
+   Passing an array with an unknown size, such as a heap-allocated array,
+   will result in a compilation error on some compilers, or otherwise produce
+   incorrect results.
+
+   This is roughly equivalent to::
+
+      sizeof(array) / sizeof((array)[0])
+
 
 .. _api-objects:
 

Doc/c-api/veryhigh.rst

@@ -396,3 +396,43 @@ Available start symbols
       * :pep:`484`
 
    .. versionadded:: 3.8
+
+
+Stack Effects
+^^^^^^^^^^^^^
+
+.. seealso::
+   :py:func:`dis.stack_effect`
+
+
+.. c:macro:: PY_INVALID_STACK_EFFECT
+
+   Sentinel value representing an invalid stack effect.
+
+   This is currently equivalent to ``INT_MAX``.
+
+   .. versionadded:: 3.8
+
+
+.. c:function:: int PyCompile_OpcodeStackEffect(int opcode, int oparg)
+
+   Compute the stack effect of *opcode* with argument *oparg*.
+
+   On success, this function returns the stack effect; on failure, this
+   returns :c:macro:`PY_INVALID_STACK_EFFECT`.
+
+   .. versionadded:: 3.4
+
+
+.. c:function:: int PyCompile_OpcodeStackEffectWithJump(int opcode, int oparg, int jump)
+
+   Similar to :c:func:`PyCompile_OpcodeStackEffect`, but don't include the
+   stack effect of jumping if *jump* is zero.
+
+   If *jump* is ``0``, this will not include the stack effect of jumping, but
+   if *jump* is ``1`` or ``-1``, this will include it.
+
+   On success, this function returns the stack effect; on failure, this
+   returns :c:macro:`PY_INVALID_STACK_EFFECT`.
+
+   .. versionadded:: 3.8

Doc/extending/extending.rst

@@ -426,7 +426,7 @@ A pointer to the module definition must be returned via :c:func:`PyModuleDef_Ini
 so that the import machinery can create the module and store it in ``sys.modules``.
 
 When embedding Python, the :c:func:`!PyInit_spam` function is not called
-automatically unless there's an entry in the :c:data:`!PyImport_Inittab` table.
+automatically unless there's an entry in the :c:data:`PyImport_Inittab` table.
 To add the module to the initialization table, use :c:func:`PyImport_AppendInittab`,
 optionally followed by an import of the module::
 

Doc/howto/a-conceptual-overview-of-asyncio.rst

@@ -175,9 +175,12 @@ Creating a task automatically schedules it for execution (by adding a
 callback to run it in the event loop's to-do list, that is, collection of jobs).
 The recommended way to create tasks is via :func:`asyncio.create_task`.
 
-Since there's only one event loop (in each thread), :mod:`!asyncio` takes
-care of associating the task with the event loop for you.
-As such, there's no need to specify the event loop.
+:mod:`!asyncio` automatically associates tasks with the event loop for you.
+This automatic association was purposely designed into :mod:`!asyncio` for
+the sake of simplicity.
+Without it, you'd have to keep track of the event loop object and pass it to
+any coroutine function that wants to create tasks, adding redundant clutter
+to your code.
 
 ::
 

Doc/howto/unicode.rst

@@ -352,6 +352,8 @@ If you don't include such a comment, the default encoding used will be UTF-8 as
 already mentioned.  See also :pep:`263` for more information.
 
 
+.. _unicode-properties:
+
 Unicode Properties
 ------------------
 

Doc/library/functools.rst

@@ -57,6 +57,10 @@ The :mod:`functools` module defines the following functions:
    another thread makes an additional call before the initial call has been
    completed and cached.
 
+   Call-once behavior is not guaranteed because locks are not held during the
+   function call. Potentially another call with the same arguments could
+   occur while the first call is still running.
+
    .. versionadded:: 3.9
 
 

Doc/library/profile.rst

@@ -347,81 +347,6 @@ The statistical profiler produces output similar to deterministic profilers but
 
 .. _profile-cli:
 
-:mod:`!profiling.sampling` Module Reference
-=======================================================
-
-.. module:: profiling.sampling
-   :synopsis: Python statistical profiler.
-
-This section documents the programmatic interface for the :mod:`!profiling.sampling` module.
-For command-line usage, see :ref:`sampling-profiler-cli`. For conceptual information
-about statistical profiling, see :ref:`statistical-profiling`
-
-.. function:: sample(pid, *, sort=2, sample_interval_usec=100, duration_sec=10, filename=None, all_threads=False, limit=None, show_summary=True, output_format="pstats", realtime_stats=False, native=False, gc=True)
-
-   Sample a Python process and generate profiling data.
-
-   This is the main entry point for statistical profiling. It creates a
-   :class:`SampleProfiler`, collects stack traces from the target process, and
-   outputs the results in the specified format.
-
-   :param int pid: Process ID of the target Python process
-   :param int sort: Sort order for pstats output (default: 2 for cumulative time)
-   :param int sample_interval_usec: Sampling interval in microseconds (default: 100)
-   :param int duration_sec: Duration to sample in seconds (default: 10)
-   :param str filename: Output filename (None for stdout/default naming)
-   :param bool all_threads: Whether to sample all threads (default: False)
-   :param int limit: Maximum number of functions to display (default: None)
-   :param bool show_summary: Whether to show summary statistics (default: True)
-   :param str output_format: Output format - 'pstats' or 'collapsed' (default: 'pstats')
-   :param bool realtime_stats: Whether to display real-time statistics (default: False)
-   :param bool native: Whether to include ``<native>`` frames (default: False)
-   :param bool gc: Whether to include ``<GC>`` frames (default: True)
-
-   :raises ValueError: If output_format is not 'pstats' or 'collapsed'
-
-   Examples::
-
-       # Basic usage - profile process 1234 for 10 seconds
-       import profiling.sampling
-       profiling.sampling.sample(1234)
-
-       # Profile with custom settings
-       profiling.sampling.sample(1234, duration_sec=30, sample_interval_usec=50, all_threads=True)
-
-       # Generate collapsed stack traces for flamegraph.pl
-       profiling.sampling.sample(1234, output_format='collapsed', filename='profile.collapsed')
-
-.. class:: SampleProfiler(pid, sample_interval_usec, all_threads)
-
-   Low-level API for the statistical profiler.
-
-   This profiler uses periodic stack sampling to collect performance data
-   from running Python processes with minimal overhead. It can attach to
-   any Python process by PID and collect stack traces at regular intervals.
-
-   :param int pid: Process ID of the target Python process
-   :param int sample_interval_usec: Sampling interval in microseconds
-   :param bool all_threads: Whether to sample all threads or just the main thread
-
-   .. method:: sample(collector, duration_sec=10)
-
-      Sample the target process for the specified duration.
-
-      Collects stack traces from the target process at regular intervals
-      and passes them to the provided collector for processing.
-
-      :param collector: Object that implements ``collect()`` method to process stack traces
-      :param int duration_sec: Duration to sample in seconds (default: 10)
-
-      The method tracks sampling statistics and can display real-time
-      information if realtime_stats is enabled.
-
-.. seealso::
-
-   :ref:`sampling-profiler-cli`
-      Command-line interface documentation for the statistical profiler.
-
 Deterministic Profiler Command Line Interface
 =============================================
 

Doc/library/stdtypes.rst

@@ -1994,10 +1994,16 @@ expression support in the :mod:`re` module).
    ``{}``.  Each replacement field contains either the numeric index of a
    positional argument, or the name of a keyword argument.  Returns a copy of
    the string where each replacement field is replaced with the string value of
-   the corresponding argument.
+   the corresponding argument. For example:
+
+   .. doctest::
 
       >>> "The sum of 1 + 2 is {0}".format(1+2)
       'The sum of 1 + 2 is 3'
+      >>> "The sum of {a} + {b} is {answer}".format(answer=1+2, a=1, b=2)
+      'The sum of 1 + 2 is 3'
+      >>> "{1} expects the {0} Inquisition!".format("Spanish", "Nobody")
+      'Nobody expects the Spanish Inquisition!'
 
    See :ref:`formatstrings` for a description of the various formatting options
    that can be specified in format strings.
@@ -2057,13 +2063,32 @@ expression support in the :mod:`re` module).
    from the `Alphabetic property defined in the section 4.10 'Letters, Alphabetic, and
    Ideographic' of the Unicode Standard
    <https://www.unicode.org/versions/Unicode17.0.0/core-spec/chapter-4/#G91002>`__.
+   For example:
+
+   .. doctest::
+
+      >>> 'Letters and spaces'.isalpha()
+      False
+      >>> 'LettersOnly'.isalpha()
+      True
+      >>> 'µ'.isalpha()  # non-ASCII characters can be considered alphabetical too
+      True
+
+   See :ref:`unicode-properties`.
 
 
 .. method:: str.isascii()
 
    Return ``True`` if the string is empty or all characters in the string are ASCII,
    ``False`` otherwise.
-   ASCII characters have code points in the range U+0000-U+007F.
+   ASCII characters have code points in the range U+0000-U+007F. For example:
+
+   .. doctest::
+
+      >>> 'ASCII characters'.isascii()
+      True
+      >>> 'µ'.isascii()
+      False
 
    .. versionadded:: 3.7
 
@@ -2073,9 +2098,18 @@ expression support in the :mod:`re` module).
    Return ``True`` if all characters in the string are decimal
    characters and there is at least one character, ``False``
    otherwise. Decimal characters are those that can be used to form
-   numbers in base 10, e.g. U+0660, ARABIC-INDIC DIGIT
+   numbers in base 10, such as U+0660, ARABIC-INDIC DIGIT
    ZERO.  Formally a decimal character is a character in the Unicode
-   General Category "Nd".
+   General Category "Nd". For example:
+
+   .. doctest::
+
+      >>> '0123456789'.isdecimal()
+      True
+      >>> '٠١٢٣٤٥٦٧٨٩'.isdecimal()  # Arabic-Indic digits zero to nine
+      True
+      >>> 'alphabetic'.isdecimal()
+      False
 
 
 .. method:: str.isdigit()
@@ -2194,7 +2228,16 @@ expression support in the :mod:`re` module).
    Return a string which is the concatenation of the strings in *iterable*.
    A :exc:`TypeError` will be raised if there are any non-string values in
    *iterable*, including :class:`bytes` objects.  The separator between
-   elements is the string providing this method.
+   elements is the string providing this method. For example:
+
+   .. doctest::
+
+      >>> ', '.join(['spam', 'spam', 'spam'])
+      'spam, spam, spam'
+      >>> '-'.join('Python')
+      'P-y-t-h-o-n'
+
+   See also :meth:`split`.
 
 
 .. method:: str.ljust(width, fillchar=' ', /)
@@ -2408,6 +2451,8 @@ expression support in the :mod:`re` module).
       >>> "   foo   ".split(maxsplit=0)
       ['foo   ']
 
+   See also :meth:`join`.
+
 
 .. index::
    single: universal newlines; str.splitlines method

Include/internal/pycore_import.h

@@ -128,11 +128,18 @@ PyAPI_FUNC(int) _PyImport_ClearExtension(PyObject *name, PyObject *filename);
 // state of the module argument:
 // - If module is NULL or a PyModuleObject with md_gil == Py_MOD_GIL_NOT_USED,
 //   call _PyEval_DisableGIL().
-// - Otherwise, call _PyEval_EnableGILPermanent(). If the GIL was not already
-//   enabled permanently, issue a warning referencing the module's name.
+// - Otherwise, call _PyImport_EnableGILAndWarn
 //
 // This function may raise an exception.
 extern int _PyImport_CheckGILForModule(PyObject *module, PyObject *module_name);
+// Assuming that the GIL is enabled from a call to
+// _PyEval_EnableGILTransient(), call _PyEval_EnableGILPermanent().
+// If the GIL was not already enabled permanently, issue a warning referencing
+// the module's name.
+// Leave a message in verbose mode.
+//
+// This function may raise an exception.
+extern int _PyImport_EnableGILAndWarn(PyThreadState *, PyObject *module_name);
 #endif
 
 #ifdef __cplusplus

Include/internal/pycore_initconfig.h

@@ -153,10 +153,8 @@ typedef enum {
 } _PyConfigInitEnum;
 
 typedef enum {
-    /* For now, this means the GIL is enabled.
-
-       gh-116329: This will eventually change to "the GIL is disabled but can
-       be re-enabled by loading an incompatible extension module." */
+    /* In free threaded builds, this means that the GIL is disabled at startup,
+       but may be enabled by loading an incompatible extension module. */
     _PyConfig_GIL_DEFAULT = -1,
 
     /* The GIL has been forced off or on, and will not be affected by module loading. */