Merge branch 'main' into kde_rand

.github/workflows/build.yml

@@ -137,6 +137,7 @@ jobs:
  uses: actions/cache@v4
  with:
  path: config.cache
+ # Include env.pythonLocation in key to avoid changes in environment when setup-python updates Python
  key: ${{ github.job }}-${{ runner.os }}-${{ env.IMAGE_VERSION }}-${{ needs.check_source.outputs.config_hash }}-${{ env.pythonLocation }}
  - name: Install Dependencies
  run: sudo ./.github/workflows/posix-deps-apt.sh
@@ -492,6 +493,7 @@ jobs:
  with:
  config_hash: ${{ needs.check_source.outputs.config_hash }}
  options: ./configure --config-cache --with-thread-sanitizer --with-pydebug
+ suppressions_path: Tools/tsan/supressions.txt
 
  build_tsan_free_threading:
  name: 'Thread sanitizer (free-threading)'
@@ -501,6 +503,7 @@ jobs:
  with:
  config_hash: ${{ needs.check_source.outputs.config_hash }}
  options: ./configure --config-cache --disable-gil --with-thread-sanitizer --with-pydebug
+ suppressions_path: Tools/tsan/suppressions_free_threading.txt
 
  # CIFuzz job based on https://google.github.io/oss-fuzz/getting-started/continuous-integration/
  cifuzz:

.github/workflows/jit.yml

@@ -12,6 +12,9 @@ on:
  - 'Python/optimizer*.c'
  workflow_dispatch:
 
+permissions:
+ contents: read
+
 concurrency:
  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
  cancel-in-progress: true

.github/workflows/reusable-tsan.yml

@@ -7,6 +7,10 @@ on:
  options:
  required: true
  type: string
+ suppressions_path:
+ description: 'A repo relative path to the suppressions file'
+ required: true
+ type: string
 
 jobs:
  build_tsan_reusable:
@@ -30,7 +34,7 @@ jobs:
  sudo sysctl -w vm.mmap_rnd_bits=28
  - name: TSAN Option Setup
  run: |
- echo "TSAN_OPTIONS=suppressions=${GITHUB_WORKSPACE}/Tools/tsan/supressions.txt" >> $GITHUB_ENV
+ echo "TSAN_OPTIONS=suppressions=${GITHUB_WORKSPACE}/${{ inputs.suppressions_path }}" >> $GITHUB_ENV
  echo "CC=clang" >> $GITHUB_ENV
  echo "CXX=clang++" >> $GITHUB_ENV
  - name: Add ccache to PATH

.github/workflows/reusable-wasi.yml

@@ -50,7 +50,8 @@ jobs:
  uses: actions/cache@v4
  with:
  path: ${{ env.CROSS_BUILD_PYTHON }}/config.cache
- key: ${{ github.job }}-${{ runner.os }}-${{ env.IMAGE_VERSION }}-${{ inputs.config_hash }}
+ # Include env.pythonLocation in key to avoid changes in environment when setup-python updates Python
+ key: ${{ github.job }}-${{ runner.os }}-${{ env.IMAGE_VERSION }}-${{ inputs.config_hash }}-${{ env.pythonLocation }}
  - name: "Configure build Python"
  run: python3 Tools/wasm/wasi.py configure-build-python -- --config-cache --with-pydebug
  - name: "Make build Python"
@@ -59,7 +60,8 @@ jobs:
  uses: actions/cache@v4
  with:
  path: ${{ env.CROSS_BUILD_WASI }}/config.cache
- key: ${{ github.job }}-${{ runner.os }}-${{ env.IMAGE_VERSION }}-wasi-sdk-${{ env.WASI_SDK_VERSION }}-${{ inputs.config_hash }}
+ # Include env.pythonLocation in key to avoid changes in environment when setup-python updates Python
+ key: ${{ github.job }}-${{ runner.os }}-${{ env.IMAGE_VERSION }}-wasi-sdk-${{ env.WASI_SDK_VERSION }}-${{ inputs.config_hash }}-${{ env.pythonLocation }}
  - name: "Configure host"
  # `--with-pydebug` inferred from configure-build-python
  run: python3 Tools/wasm/wasi.py configure-host -- --config-cache

Doc/bugs.rst

@@ -22,6 +22,10 @@ have a suggestion on how to fix it, include that as well.
 You can also open a discussion item on our
 `Documentation Discourse forum <https://discuss.python.org/c/documentation/26>`_.
 
+If you find a bug in the theme (HTML / CSS / JavaScript) of the
+documentation, please submit a bug report on the `python-doc-theme bug
+tracker <https://github.com/python/python-docs-theme>`_.
+
 If you're short on time, you can also email documentation bug reports to
 docs@python.org (behavioral bugs can be sent to python-list@python.org).
 'docs@' is a mailing list run by volunteers; your request will be noticed,

Doc/c-api/exceptions.rst

@@ -221,13 +221,14 @@ For convenience, some of these functions will always return a
 
 .. c:function:: PyObject* PyErr_SetFromWindowsErr(int ierr)
 
- This is a convenience function to raise :exc:`WindowsError`. If called with
+ This is a convenience function to raise :exc:`OSError`. If called with
  *ierr* of ``0``, the error code returned by a call to :c:func:`!GetLastError`
  is used instead. It calls the Win32 function :c:func:`!FormatMessage` to retrieve
  the Windows description of error code given by *ierr* or :c:func:`!GetLastError`,
- then it constructs a tuple object whose first item is the *ierr* value and whose
- second item is the corresponding error message (gotten from
- :c:func:`!FormatMessage`), and then calls ``PyErr_SetObject(PyExc_WindowsError,
+ then it constructs a :exc:`OSError` object with the :attr:`~OSError.winerror`
+ attribute set to the error code, the :attr:`~OSError.strerror` attribute
+ set to the corresponding error message (gotten from
+ :c:func:`!FormatMessage`), and then calls ``PyErr_SetObject(PyExc_OSError,
  object)``. This function always returns ``NULL``.
 
  .. availability:: Windows.

Doc/c-api/init.rst

@@ -29,6 +29,8 @@ The following functions can be safely called before Python is initialized:
  * :c:func:`PyMem_SetAllocator`
  * :c:func:`PyMem_SetupDebugHooks`
  * :c:func:`PyObject_SetArenaAllocator`
+ * :c:func:`Py_SetProgramName`
+ * :c:func:`Py_SetPythonHome`
  * :c:func:`PySys_ResetWarnOptions`
 
 * Informative functions:
@@ -59,7 +61,7 @@ The following functions can be safely called before Python is initialized:
  :c:func:`Py_Initialize`: :c:func:`Py_EncodeLocale`, :c:func:`Py_GetPath`,
  :c:func:`Py_GetPrefix`, :c:func:`Py_GetExecPrefix`,
  :c:func:`Py_GetProgramFullPath`, :c:func:`Py_GetPythonHome`,
- and :c:func:`Py_GetProgramName`.
+ :c:func:`Py_GetProgramName` and :c:func:`PyEval_InitThreads`.
 
 
 .. _global-conf-vars:
@@ -326,6 +328,7 @@ Initializing and finalizing the interpreter
 .. c:function:: void Py_Initialize()
 
  .. index::
+ single: PyEval_InitThreads()
  single: modules (in module sys)
  single: path (in module sys)
  pair: module; builtins
@@ -425,6 +428,34 @@ Process-wide parameters
 =======================
 
 
+.. c:function:: void Py_SetProgramName(const wchar_t *name)
+
+ .. index::
+ single: Py_Initialize()
+ single: main()
+ single: Py_GetPath()
+
+ This API is kept for backward compatibility: setting
+ :c:member:`PyConfig.program_name` should be used instead, see :ref:`Python
+ Initialization Configuration <init-config>`.
+
+ This function should be called before :c:func:`Py_Initialize` is called for
+ the first time, if it is called at all. It tells the interpreter the value
+ of the ``argv[0]`` argument to the :c:func:`main` function of the program
+ (converted to wide characters).
+ This is used by :c:func:`Py_GetPath` and some other functions below to find
+ the Python run-time libraries relative to the interpreter executable. The
+ default value is ``'python'``. The argument should point to a
+ zero-terminated wide character string in static storage whose contents will not
+ change for the duration of the program's execution. No code in the Python
+ interpreter will change the contents of this storage.
+
+ Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
+ :c:expr:`wchar_*` string.
+
+ .. deprecated:: 3.11
+
+
 .. c:function:: wchar_t* Py_GetProgramName()
 
  Return the program name set with :c:member:`PyConfig.program_name`, or the default.
@@ -626,6 +657,106 @@ Process-wide parameters
  ``sys.version``.
 
 
+.. c:function:: void PySys_SetArgvEx(int argc, wchar_t **argv, int updatepath)
+
+ .. index::
+ single: main()
+ single: Py_FatalError()
+ single: argv (in module sys)
+
+ This API is kept for backward compatibility: setting
+ :c:member:`PyConfig.argv`, :c:member:`PyConfig.parse_argv` and
+ :c:member:`PyConfig.safe_path` should be used instead, see :ref:`Python
+ Initialization Configuration <init-config>`.
+
+ Set :data:`sys.argv` based on *argc* and *argv*. These parameters are
+ similar to those passed to the program's :c:func:`main` function with the
+ difference that the first entry should refer to the script file to be
+ executed rather than the executable hosting the Python interpreter. If there
+ isn't a script that will be run, the first entry in *argv* can be an empty
+ string. If this function fails to initialize :data:`sys.argv`, a fatal
+ condition is signalled using :c:func:`Py_FatalError`.
+
+ If *updatepath* is zero, this is all the function does. If *updatepath*
+ is non-zero, the function also modifies :data:`sys.path` according to the
+ following algorithm:
+
+ - If the name of an existing script is passed in ``argv[0]``, the absolute
+ path of the directory where the script is located is prepended to
+ :data:`sys.path`.
+ - Otherwise (that is, if *argc* is ``0`` or ``argv[0]`` doesn't point
+ to an existing file name), an empty string is prepended to
+ :data:`sys.path`, which is the same as prepending the current working
+ directory (``"."``).
+
+ Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
+ :c:expr:`wchar_*` string.
+
+ See also :c:member:`PyConfig.orig_argv` and :c:member:`PyConfig.argv`
+ members of the :ref:`Python Initialization Configuration <init-config>`.
+
+ .. note::
+ It is recommended that applications embedding the Python interpreter
+ for purposes other than executing a single script pass ``0`` as *updatepath*,
+ and update :data:`sys.path` themselves if desired.
+ See :cve:`2008-5983`.
+
+ On versions before 3.1.3, you can achieve the same effect by manually
+ popping the first :data:`sys.path` element after having called
+ :c:func:`PySys_SetArgv`, for example using::
+
+ PyRun_SimpleString("import sys; sys.path.pop(0)\n");
+
+ .. versionadded:: 3.1.3
+
+ .. XXX impl. doesn't seem consistent in allowing ``0``/``NULL`` for the params;
+ check w/ Guido.
+
+ .. deprecated:: 3.11
+
+
+.. c:function:: void PySys_SetArgv(int argc, wchar_t **argv)
+
+ This API is kept for backward compatibility: setting
+ :c:member:`PyConfig.argv` and :c:member:`PyConfig.parse_argv` should be used
+ instead, see :ref:`Python Initialization Configuration <init-config>`.
+
+ This function works like :c:func:`PySys_SetArgvEx` with *updatepath* set
+ to ``1`` unless the :program:`python` interpreter was started with the
+ :option:`-I`.
+
+ Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
+ :c:expr:`wchar_*` string.
+
+ See also :c:member:`PyConfig.orig_argv` and :c:member:`PyConfig.argv`
+ members of the :ref:`Python Initialization Configuration <init-config>`.
+
+ .. versionchanged:: 3.4 The *updatepath* value depends on :option:`-I`.
+
+ .. deprecated:: 3.11
+
+
+.. c:function:: void Py_SetPythonHome(const wchar_t *home)
+
+ This API is kept for backward compatibility: setting
+ :c:member:`PyConfig.home` should be used instead, see :ref:`Python
+ Initialization Configuration <init-config>`.
+
+ Set the default "home" directory, that is, the location of the standard
+ Python libraries. See :envvar:`PYTHONHOME` for the meaning of the
+ argument string.
+
+ The argument should point to a zero-terminated character string in static
+ storage whose contents will not change for the duration of the program's
+ execution. No code in the Python interpreter will change the contents of
+ this storage.
+
+ Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
+ :c:expr:`wchar_*` string.
+
+ .. deprecated:: 3.11
+
+
 .. c:function:: wchar_t* Py_GetPythonHome()
 
  Return the default "home", that is, the value set by
@@ -841,6 +972,33 @@ code, or when embedding the Python interpreter:
  This thread's interpreter state.
 
 
+.. c:function:: void PyEval_InitThreads()
+
+ .. index::
+ single: PyEval_AcquireThread()
+ single: PyEval_ReleaseThread()
+ single: PyEval_SaveThread()
+ single: PyEval_RestoreThread()
+
+ Deprecated function which does nothing.
+
+ In Python 3.6 and older, this function created the GIL if it didn't exist.
+
+ .. versionchanged:: 3.9
+ The function now does nothing.
+
+ .. versionchanged:: 3.7
+ This function is now called by :c:func:`Py_Initialize()`, so you don't
+ have to call it yourself anymore.
+
+ .. versionchanged:: 3.2
+ This function cannot be called before :c:func:`Py_Initialize()` anymore.
+
+ .. deprecated:: 3.9
+
+ .. index:: pair: module; _thread
+
+
 .. c:function:: PyThreadState* PyEval_SaveThread()
 
  Release the global interpreter lock (if it has been created) and reset the

Doc/c-api/tuple.rst

@@ -59,6 +59,12 @@ Tuple Objects
  Return the object at position *pos* in the tuple pointed to by *p*. If *pos* is
  negative or out of bounds, return ``NULL`` and set an :exc:`IndexError` exception.
 
+ The returned reference is borrowed from the tuple *p*
+ (that is: it is only valid as long as you hold a reference to *p*).
+ To get a :term:`strong reference`, use
+ :c:func:`Py_NewRef(PyTuple_GetItem(...)) <Py_NewRef>`
+ or :c:func:`PySequence_GetItem`.
+
 
 .. c:function:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)
 

Doc/c-api/typeobj.rst

@@ -1034,7 +1034,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
  the type, and the type object is INCREF'ed when a new instance is created, and
  DECREF'ed when an instance is destroyed (this does not apply to instances of
  subtypes; only the type referenced by the instance's ob_type gets INCREF'ed or
- DECREF'ed).
+ DECREF'ed). Heap types should also :ref:`support garbage collection <supporting-cycle-detection>`
+ as they can form a reference cycle with their own module object.
 
  **Inheritance:**
 

Doc/conf.py

@@ -12,6 +12,8 @@
 sys.path.append(os.path.abspath('tools/extensions'))
 sys.path.append(os.path.abspath('includes'))
 
+from pyspecific import SOURCE_URI
+
 # General configuration
 # ---------------------
 
@@ -24,6 +26,7 @@
  'pyspecific',
  'sphinx.ext.coverage',
  'sphinx.ext.doctest',
+ 'sphinx.ext.extlinks',
 ]
 
 # Skip if downstream redistributors haven't installed them
@@ -513,6 +516,19 @@
  r'https://unix.org/version2/whatsnew/lp64_wp.html',
 ]
 
+# Options for sphinx.ext.extlinks
+# -------------------------------
+
+# This config is a dictionary of external sites,
+# mapping unique short aliases to a base URL and a prefix.
+# https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
+extlinks = {
+ "cve": ("https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-%s", "CVE-%s"),
+ "cwe": ("https://cwe.mitre.org/data/definitions/%s.html", "CWE-%s"),
+ "pypi": ("https://pypi.org/project/%s/", "%s"),
+ "source": (SOURCE_URI, "%s"),
+}
+extlinks_detect_hardcoded_links = True
 
 # Options for extensions
 # ----------------------