Merge branch 'main' into fix-issue-118524-match-union

Author: randolf-scholz

.github/workflows/build.yml

@@ -208,7 +208,7 @@ jobs:
     with:
       config_hash: ${{ needs.check_source.outputs.config_hash }}
       # macos-14 is M1, macos-13 is Intel
-      os-matrix: '["macos-14-xlarge", "macos-13-large"]'
+      os-matrix: '["macos-14", "macos-13"]'
 
   build_macos_free_threading:
     name: 'macOS (free-threading)'
@@ -219,7 +219,7 @@ jobs:
       config_hash: ${{ needs.check_source.outputs.config_hash }}
       free-threading: true
       # macos-14-large is Intel with 12 cores (most parallelism)
-      os-matrix: '["macos-14-large"]'
+      os-matrix: '["macos-14"]'
 
   build_ubuntu:
     name: 'Ubuntu'

Doc/howto/perf_profiling.rst

@@ -162,12 +162,12 @@ the :option:`!-X` option takes precedence over the environment variable.
 
 Example, using the environment variable::
 
-   $ PYTHONPERFSUPPORT=1 python script.py
+   $ PYTHONPERFSUPPORT=1 perf record -F 9999 -g -o perf.data python script.py
    $ perf report -g -i perf.data
 
 Example, using the :option:`!-X` option::
 
-   $ python -X perf script.py
+   $ perf record -F 9999 -g -o perf.data python -X perf script.py
    $ perf report -g -i perf.data
 
 Example, using the :mod:`sys` APIs in file :file:`example.py`:
@@ -184,7 +184,7 @@ Example, using the :mod:`sys` APIs in file :file:`example.py`:
 
 ...then::
 
-   $ python ./example.py
+   $ perf record -F 9999 -g -o perf.data python ./example.py
    $ perf report -g -i perf.data
 
 
@@ -210,31 +210,57 @@ of ``perf``.
 How to work without frame pointers
 ----------------------------------
 
-If you are working with a Python interpreter that has been compiled without frame pointers
-you can still use the ``perf`` profiler but the overhead will be a bit higher because Python
-needs to generate unwinding information for every Python function call on the fly. Additionally,
-``perf`` will take more time to process the data because it will need to use the DWARF debugging
-information to unwind the stack and this is a slow process.
+If you are working with a Python interpreter that has been compiled without
+frame pointers, you can still use the ``perf`` profiler, but the overhead will be
+a bit higher because Python needs to generate unwinding information for every
+Python function call on the fly. Additionally, ``perf`` will take more time to
+process the data because it will need to use the DWARF debugging information to
+unwind the stack and this is a slow process.
 
-To enable this mode, you can use the environment variable :envvar:`PYTHON_PERF_JIT_SUPPORT` or the
-:option:`-X perf_jit <-X>` option, which will enable the JIT mode for the ``perf`` profiler.
+To enable this mode, you can use the environment variable
+:envvar:`PYTHON_PERF_JIT_SUPPORT` or the :option:`-X perf_jit <-X>` option,
+which will enable the JIT mode for the ``perf`` profiler.
 
-When using the perf JIT mode, you need an extra step before you can run ``perf report``. You need to
-call the ``perf inject`` command to inject the JIT information into the ``perf.data`` file.
+.. note::
+
+    Due to a bug in the ``perf`` tool, only ``perf`` versions higher than v6.8
+    will work with the JIT mode.  The fix was also backported to the v6.7.2
+    version of the tool.
+
+    Note that when checking the version of the ``perf`` tool (which can be done
+    by running ``perf version``) you must take into account that some distros
+    add some custom version numbers including a ``-`` character.  This means
+    that ``perf 6.7-3`` is not necessarily ``perf 6.7.3``.
+
+When using the perf JIT mode, you need an extra step before you can run ``perf
+report``. You need to call the ``perf inject`` command to inject the JIT
+information into the ``perf.data`` file.::
 
     $ perf record -F 9999 -g --call-graph dwarf -o perf.data python -Xperf_jit my_script.py
-    $ perf inject -i perf.data --jit
-    $ perf report -g -i perf.data
+    $ perf inject -i perf.data --jit --output perf.jit.data
+    $ perf report -g -i perf.jit.data
 
 or using the environment variable::
 
     $ PYTHON_PERF_JIT_SUPPORT=1 perf record -F 9999 -g --call-graph dwarf -o perf.data python my_script.py
-    $ perf inject -i perf.data --jit
-    $ perf report -g -i perf.data
-
-Notice that when using ``--call-graph dwarf`` the ``perf`` tool will take snapshots of the stack of
-the process being profiled and save the information in the ``perf.data`` file. By default the size of
-the stack dump is 8192 bytes but the user can change the size by passing the size after comma like
-``--call-graph dwarf,4096``. The size of the stack dump is important because if the size is too small
-``perf`` will not be able to unwind the stack and the output will be incomplete.
+    $ perf inject -i perf.data --jit --output perf.jit.data
+    $ perf report -g -i perf.jit.data
+
+``perf inject --jit`` command will read ``perf.data``,
+automatically pick up the perf dump file that Python creates (in
+``/tmp/perf-$PID.dump``), and then create ``perf.jit.data`` which merges all the
+JIT information together. It should also create a lot of ``jitted-XXXX-N.so``
+files in the current directory which are ELF images for all the JIT trampolines
+that were created by Python.
+
+.. warning::
+    Notice that when using ``--call-graph dwarf`` the ``perf`` tool will take
+    snapshots of the stack of the process being profiled and save the
+    information in the ``perf.data`` file. By default the size of the stack dump
+    is 8192 bytes but the user can change the size by passing the size after
+    comma like ``--call-graph dwarf,4096``. The size of the stack dump is
+    important because if the size is too small ``perf`` will not be able to
+    unwind the stack and the output will be incomplete. On the other hand, if
+    the size is too big, then ``perf`` won't be able to sample the process as
+    frequently as it would like as the overhead will be higher.
 

Doc/howto/urllib2.rst

@@ -594,5 +594,5 @@ This document was reviewed and revised by John Lee.
        scripts with a localhost server, I have to prevent urllib from using
        the proxy.
 .. [#] urllib opener for SSL proxy (CONNECT method): `ASPN Cookbook Recipe
-       <https://code.activestate.com/recipes/456195/>`_.
+       <https://code.activestate.com/recipes/456195-urrlib2-opener-for-ssl-proxy-connect-method/>`_.
 

Doc/library/collections.rst

@@ -134,7 +134,7 @@ The class can be used to simulate nested scopes and is useful in templating.
      :attr:`~collections.ChainMap.parents` property.
 
    * The `Nested Contexts recipe
-     <https://code.activestate.com/recipes/577434/>`_ has options to control
+     <https://code.activestate.com/recipes/577434-nested-contexts-a-chain-of-mapping-objects/>`_ has options to control
      whether writes and other mutations apply only to the first mapping or to
      any mapping in the chain.
 

Doc/library/difflib.rst

@@ -631,7 +631,7 @@ If you want to know how to change the first sequence into the second, use
      work.
 
    * `Simple version control recipe
-     <https://code.activestate.com/recipes/576729/>`_ for a small application
+     <https://code.activestate.com/recipes/576729-simple-version-control/>`_ for a small application
      built with :class:`SequenceMatcher`.
 
 

Doc/library/enum.rst

@@ -861,9 +861,15 @@ Supported ``_sunder_`` names
      For :class:`Flag` classes the next value chosen will be the next highest
      power-of-two.
 
+- While ``_sunder_`` names are generally reserved for the further development
+  of the :class:`Enum` class and can not be used, some are explicitly allowed:
+
+  - ``_repr_*`` (e.g. ``_repr_html_``), as used in `IPython's rich display`_
+
 .. versionadded:: 3.6 ``_missing_``, ``_order_``, ``_generate_next_value_``
 .. versionadded:: 3.7 ``_ignore_``
-.. versionadded:: 3.13 ``_add_alias_``, ``_add_value_alias_``
+.. versionadded:: 3.13 ``_add_alias_``, ``_add_value_alias_``, ``_repr_*``
+.. _`IPython's rich display`: https://ipython.readthedocs.io/en/stable/config/integrating.html#rich-display
 
 ---------------
 

Doc/library/math.rst

@@ -134,7 +134,7 @@ Number-theoretic and representation functions
 
    For further discussion and two alternative approaches, see the `ASPN cookbook
    recipes for accurate floating point summation
-   <https://code.activestate.com/recipes/393090/>`_\.
+   <https://code.activestate.com/recipes/393090-binary-floating-point-summation-accurate-to-full-p/>`_\.
 
 
 .. function:: gcd(*integers)

Doc/library/random.rst

@@ -55,7 +55,7 @@ from sources provided by the operating system.
 
 
    `Complementary-Multiply-with-Carry recipe
-   <https://code.activestate.com/recipes/576707/>`_ for a compatible alternative
+   <https://code.activestate.com/recipes/576707-long-period-random-number-generator/>`_ for a compatible alternative
    random number generator with a long period and comparatively simple update
    operations.
 

Doc/library/shelve.rst

@@ -86,7 +86,7 @@ Two additional methods are supported:
 
 .. seealso::
 
-   `Persistent dictionary recipe <https://code.activestate.com/recipes/576642/>`_
+   `Persistent dictionary recipe <https://code.activestate.com/recipes/576642-persistent-dict-with-multiple-standard-file-format/>`_
    with widely supported storage formats and having the speed of native
    dictionaries.
 

Doc/library/stdtypes.rst

@@ -1496,7 +1496,7 @@ objects that compare equal might have different :attr:`~range.start`,
 
 .. seealso::
 
-   * The `linspace recipe <https://code.activestate.com/recipes/579000/>`_
+   * The `linspace recipe <https://code.activestate.com/recipes/579000-equally-spaced-numbers-linspace/>`_
      shows how to implement a lazy version of range suitable for floating
      point applications.