Merge branch 'main' into 131769-wasi-bebug-main

Author: brettcannon

.github/workflows/build.yml

@@ -15,7 +15,13 @@ permissions:
   contents: read
 
 concurrency:
-  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}-reusable
+  # https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#concurrency
+  # 'group' must be a key uniquely representing a PR or push event.
+  # github.workflow is the workflow name
+  # github.actor is the user invoking the workflow
+  # github.head_ref is the source branch of the PR or otherwise blank
+  # github.run_id is a unique number for the current run
+  group: ${{ github.workflow }}-${{ github.actor }}-${{ github.head_ref || github.run_id }}
   cancel-in-progress: true
 
 env:

Doc/howto/annotations.rst

@@ -248,4 +248,9 @@ quirks by using :func:`annotationlib.get_annotations` on Python 3.14+ or
 :func:`inspect.get_annotations` on Python 3.10+. On earlier versions of
 Python, you can avoid these bugs by accessing the annotations from the
 class's :attr:`~type.__dict__`
-(e.g., ``cls.__dict__.get('__annotations__', None)``).
+(for example, ``cls.__dict__.get('__annotations__', None)``).
+
+In some versions of Python, instances of classes may have an ``__annotations__``
+attribute. However, this is not supported functionality. If you need the
+annotations of an instance, you can use :func:`type` to access its class
+(for example, ``annotationlib.get_annotations(type(myinstance))`` on Python 3.14+).

Doc/howto/isolating-extensions.rst

@@ -215,21 +215,36 @@ multiple interpreters correctly. If this is not yet the case for your
 module, you can explicitly make your module loadable only once per
 process. For example::
 
+   // A process-wide flag
    static int loaded = 0;
 
+   // Mutex to provide thread safety (only needed for free-threaded Python)
+   static PyMutex modinit_mutex = {0};
+
    static int
    exec_module(PyObject* module)
    {
+       PyMutex_Lock(&modinit_mutex);
        if (loaded) {
+           PyMutex_Unlock(&modinit_mutex);
            PyErr_SetString(PyExc_ImportError,
                            "cannot load module more than once per process");
            return -1;
        }
        loaded = 1;
+       PyMutex_Unlock(&modinit_mutex);
        // ... rest of initialization
    }
 
 
+If your module's :c:member:`PyModuleDef.m_clear` function is able to prepare
+for future re-initialization, it should clear the ``loaded`` flag.
+In this case, your module won't support multiple instances existing
+*concurrently*, but it will, for example, support being loaded after
+Python runtime shutdown (:c:func:`Py_FinalizeEx`) and re-initialization
+(:c:func:`Py_Initialize`).
+
+
 Module State Access from Functions
 ----------------------------------
 

Doc/tools/templates/customsourcelink.html

@@ -1,11 +1,11 @@
 {%- if show_source and has_source and sourcename %}
   <div role="note" aria-label="source link">
-    <h3>{{ _('This Page') }}</h3>
+    <h3>{{ _('This page') }}</h3>
     <ul class="this-page-menu">
-      <li><a href="{{ pathto('bugs') }}">{% trans %}Report a Bug{% endtrans %}</a></li>
+      <li><a href="{{ pathto('bugs') }}">{% trans %}Report a bug{% endtrans %}</a></li>
       <li>
         <a href="https://github.com/python/cpython/blob/main/Doc/{{ sourcename|replace('.rst.txt', '.rst') }}"
-            rel="nofollow">{{ _('Show Source') }}
+            rel="nofollow">{{ _('Show source') }}
         </a>
       </li>
     </ul>

Doc/tools/templates/download.html

@@ -27,7 +27,7 @@
 {%- endblock -%}
 
 {% block body %}
-<h1>{% trans %}Download Python {{ dl_version }} Documentation{% endtrans %}</h1>
+<h1>{% trans %}Download Python {{ dl_version }} documentation{% endtrans %}</h1>
 
 {% if last_updated %}<p><b>{% trans %}Last updated on: {{ last_updated }}.{% endtrans %}</b></p>{% endif %}
 

Doc/tools/templates/indexcontent.html

@@ -72,7 +72,7 @@ <h1>{{ docstitle|e }}</h1>
   <table class="contentstable" align="center"><tr>
     <td width="50%">
       <p class="biglink"><a class="biglink" href="{{ pathto("bugs") }}">{% trans %}Reporting issues{% endtrans %}</a></p>
-      <p class="biglink"><a class="biglink" href="https://devguide.python.org/documentation/help-documenting/">{% trans %}Contributing to Docs{% endtrans %}</a></p>
+      <p class="biglink"><a class="biglink" href="https://devguide.python.org/documentation/help-documenting/">{% trans %}Contributing to docs{% endtrans %}</a></p>
       <p class="biglink"><a class="biglink" href="{{ pathto("download") }}">{% trans %}Download the documentation{% endtrans %}</a></p>
     </td><td width="50%">
       <p class="biglink"><a class="biglink" href="{{ pathto("license") }}">{% trans %}History and license of Python{% endtrans %}</a></p>

Doc/tools/templates/indexsidebar.html

@@ -9,9 +9,9 @@ <h3>{% trans %}Docs by version{% endtrans %}</h3>
 <h3>{% trans %}Other resources{% endtrans %}</h3>
 <ul>
   {# XXX: many of these should probably be merged in the main docs #}
-  <li><a href="https://peps.python.org/">{% trans %}PEP Index{% endtrans %}</a></li>
-  <li><a href="https://wiki.python.org/moin/BeginnersGuide">{% trans %}Beginner's Guide{% endtrans %}</a></li>
-  <li><a href="https://wiki.python.org/moin/PythonBooks">{% trans %}Book List{% endtrans %}</a></li>
-  <li><a href="https://www.python.org/doc/av/">{% trans %}Audio/Visual Talks{% endtrans %}</a></li>
-  <li><a href="https://devguide.python.org/">{% trans %}Python Developer’s Guide{% endtrans %}</a></li>
+  <li><a href="https://peps.python.org/">{% trans %}PEP index{% endtrans %}</a></li>
+  <li><a href="https://wiki.python.org/moin/BeginnersGuide">{% trans %}Beginner's guide{% endtrans %}</a></li>
+  <li><a href="https://wiki.python.org/moin/PythonBooks">{% trans %}Book list{% endtrans %}</a></li>
+  <li><a href="https://www.python.org/doc/av/">{% trans %}Audio/visual talks{% endtrans %}</a></li>
+  <li><a href="https://devguide.python.org/">{% trans %}Python developer’s guide{% endtrans %}</a></li>
 </ul>

Doc/tutorial/index.rst

@@ -4,6 +4,10 @@
   The Python Tutorial
 ######################
 
+.. Tip:: This tutorial is designed for
+   *programmers* that are new to the Python language,
+   **not** *beginners* who are new to programming.
+
 Python is an easy to learn, powerful programming language. It has efficient
 high-level data structures and a simple but effective approach to
 object-oriented programming. Python's elegant syntax and dynamic typing,
@@ -21,7 +25,8 @@ implemented in C or C++ (or other languages callable from C). Python is also
 suitable as an extension language for customizable applications.
 
 This tutorial introduces the reader informally to the basic concepts and
-features of the Python language and system. It helps to have a Python
+features of the Python language and system. Be aware that it expects you to
+have a basic understanding of programming in general. It helps to have a Python
 interpreter handy for hands-on experience, but all examples are self-contained,
 so the tutorial can be read off-line as well.
 

Include/internal/pycore_backoff.h

@@ -95,8 +95,10 @@ backoff_counter_triggers(_Py_BackoffCounter counter)
     return counter.value_and_backoff < UNREACHABLE_BACKOFF;
 }
 
-/* Initial JUMP_BACKWARD counter.
- * This determines when we create a trace for a loop. */
+// Initial JUMP_BACKWARD counter.
+// Must be larger than ADAPTIVE_COOLDOWN_VALUE, otherwise when JIT code is
+// invalidated we may construct a new trace before the bytecode has properly
+// re-specialized:
 #define JUMP_BACKWARD_INITIAL_VALUE 4095
 #define JUMP_BACKWARD_INITIAL_BACKOFF 12
 static inline _Py_BackoffCounter

Include/internal/pycore_code.h

@@ -451,6 +451,9 @@ write_location_entry_start(uint8_t *ptr, int code, int length)
 #define ADAPTIVE_COOLDOWN_BACKOFF 0
 
 // Can't assert this in pycore_backoff.h because of header order dependencies
+#if JUMP_BACKWARD_INITIAL_VALUE <= ADAPTIVE_COOLDOWN_VALUE
+#  error  "JIT threshold value should be larger than adaptive cooldown value"
+#endif
 #if SIDE_EXIT_INITIAL_VALUE <= ADAPTIVE_COOLDOWN_VALUE
 #  error  "Cold exit value should be larger than adaptive cooldown value"
 #endif