Merge branch 'main' into issue-129667

Author: donbarbos

Doc/c-api/init.rst

@@ -622,7 +622,8 @@ Process-wide parameters
       It now returns ``NULL`` if called before :c:func:`Py_Initialize`.
 
    .. deprecated-removed:: 3.13 3.15
-      Get :data:`sys.executable` instead.
+      Use :c:func:`PyConfig_Get("executable") <PyConfig_Get>`
+      (:data:`sys.executable`) instead.
 
 
 .. c:function:: wchar_t* Py_GetPrefix()
@@ -644,8 +645,10 @@ Process-wide parameters
       It now returns ``NULL`` if called before :c:func:`Py_Initialize`.
 
    .. deprecated-removed:: 3.13 3.15
-      Get :data:`sys.base_prefix` instead, or :data:`sys.prefix` if
-      :ref:`virtual environments <venv-def>` need to be handled.
+      Use :c:func:`PyConfig_Get("base_prefix") <PyConfig_Get>`
+      (:data:`sys.base_prefix`) instead. Use :c:func:`PyConfig_Get("prefix")
+      <PyConfig_Get>` (:data:`sys.prefix`) if :ref:`virtual environments
+      <venv-def>` need to be handled.
 
 
 .. c:function:: wchar_t* Py_GetExecPrefix()
@@ -690,9 +693,11 @@ Process-wide parameters
       It now returns ``NULL`` if called before :c:func:`Py_Initialize`.
 
    .. deprecated-removed:: 3.13 3.15
-      Get :data:`sys.base_exec_prefix` instead, or :data:`sys.exec_prefix` if
-      :ref:`virtual environments <venv-def>` need to be handled.
-
+      Use :c:func:`PyConfig_Get("base_exec_prefix") <PyConfig_Get>`
+      (:data:`sys.base_exec_prefix`) instead. Use
+      :c:func:`PyConfig_Get("exec_prefix") <PyConfig_Get>`
+      (:data:`sys.exec_prefix`) if :ref:`virtual environments <venv-def>` need
+      to be handled.
 
 .. c:function:: wchar_t* Py_GetProgramFullPath()
 
@@ -712,7 +717,8 @@ Process-wide parameters
       It now returns ``NULL`` if called before :c:func:`Py_Initialize`.
 
    .. deprecated-removed:: 3.13 3.15
-      Get :data:`sys.executable` instead.
+      Use :c:func:`PyConfig_Get("executable") <PyConfig_Get>`
+      (:data:`sys.executable`) instead.
 
 
 .. c:function:: wchar_t* Py_GetPath()
@@ -740,8 +746,8 @@ Process-wide parameters
       It now returns ``NULL`` if called before :c:func:`Py_Initialize`.
 
    .. deprecated-removed:: 3.13 3.15
-      Get :data:`sys.path` instead.
-
+      Use :c:func:`PyConfig_Get("module_search_paths") <PyConfig_Get>`
+      (:data:`sys.path`) instead.
 
 .. c:function:: const char* Py_GetVersion()
 
@@ -926,8 +932,8 @@ Process-wide parameters
       It now returns ``NULL`` if called before :c:func:`Py_Initialize`.
 
    .. deprecated-removed:: 3.13 3.15
-      Get :c:member:`PyConfig.home` or :envvar:`PYTHONHOME` environment
-      variable instead.
+      Use :c:func:`PyConfig_Get("home") <PyConfig_Get>` or the
+      :envvar:`PYTHONHOME` environment variable instead.
 
 
 .. _threads:

Doc/c-api/module.rst

@@ -523,9 +523,6 @@ state:
 
    On success, return ``0``. On error, raise an exception and return ``-1``.
 
-   Return ``-1`` if *value* is ``NULL``. It must be called with an exception
-   raised in this case.
-
    Example usage::
 
        static int
@@ -540,6 +537,10 @@ state:
            return res;
         }
 
+   To be convenient, the function accepts ``NULL`` *value* with an exception
+   set. In this case, return ``-1`` and just leave the raised exception
+   unchanged.
+
    The example can also be written without checking explicitly if *obj* is
    ``NULL``::
 

Doc/conf.py

@@ -28,6 +28,7 @@
     'changes',
     'glossary_search',
     'lexers',
+    'misc_news',
     'pydoc_topics',
     'pyspecific',
     'sphinx.ext.coverage',

Doc/data/stable_abi.dat

@@ -10,25 +10,35 @@ Pending removal in Python 3.15
   :c:func:`PyWeakref_GetRef` on Python 3.12 and older.
 * :c:type:`Py_UNICODE` type and the :c:macro:`!Py_UNICODE_WIDE` macro:
   Use :c:type:`wchar_t` instead.
-* Python initialization functions:
+* Python initialization functions, deprecated in Python 3.13:
 
-  * :c:func:`PySys_ResetWarnOptions`:
-    Clear :data:`sys.warnoptions` and :data:`!warnings.filters` instead.
-  * :c:func:`Py_GetExecPrefix`:
-    Get :data:`sys.base_exec_prefix` and :data:`sys.exec_prefix` instead.
   * :c:func:`Py_GetPath`:
-    Get :data:`sys.path` instead.
+    Use :c:func:`PyConfig_Get("module_search_paths") <PyConfig_Get>`
+    (:data:`sys.path`) instead.
   * :c:func:`Py_GetPrefix`:
-    Get :data:`sys.base_prefix` and :data:`sys.prefix` instead.
+    Use :c:func:`PyConfig_Get("base_prefix") <PyConfig_Get>`
+    (:data:`sys.base_prefix`) instead. Use :c:func:`PyConfig_Get("prefix")
+    <PyConfig_Get>` (:data:`sys.prefix`) if :ref:`virtual environments
+    <venv-def>` need to be handled.
+  * :c:func:`Py_GetExecPrefix`:
+    Use :c:func:`PyConfig_Get("base_exec_prefix") <PyConfig_Get>`
+    (:data:`sys.base_exec_prefix`) instead. Use
+    :c:func:`PyConfig_Get("exec_prefix") <PyConfig_Get>`
+    (:data:`sys.exec_prefix`) if :ref:`virtual environments <venv-def>` need to
+    be handled.
   * :c:func:`Py_GetProgramFullPath`:
-    Get :data:`sys.executable` instead.
+    Use :c:func:`PyConfig_Get("executable") <PyConfig_Get>`
+    (:data:`sys.executable`) instead.
   * :c:func:`Py_GetProgramName`:
-    Get :data:`sys.executable` instead.
+    Use :c:func:`PyConfig_Get("executable") <PyConfig_Get>`
+    (:data:`sys.executable`) instead.
   * :c:func:`Py_GetPythonHome`:
-    Get :c:func:`PyConfig_Get("home") <PyConfig_Get>`
-    or the :envvar:`PYTHONHOME` environment variable instead.
+    Use :c:func:`PyConfig_Get("home") <PyConfig_Get>` or the
+    :envvar:`PYTHONHOME` environment variable instead.
 
-  See also the :c:func:`PyConfig_Get` function.
+  The `pythoncapi-compat project
+  <https://github.com/python/pythoncapi-compat/>`__ can be used to get
+  :c:func:`PyConfig_Get` on Python 3.13 and older.
 
 * Functions to configure Python's initialization, deprecated in Python 3.11:
 
@@ -40,6 +50,8 @@ Pending removal in Python 3.15
     Set :c:member:`PyConfig.program_name` instead.
   * :c:func:`!Py_SetPythonHome()`:
     Set :c:member:`PyConfig.home` instead.
+  * :c:func:`PySys_ResetWarnOptions`:
+    Clear :data:`sys.warnoptions` and :data:`!warnings.filters` instead.
 
   The :c:func:`Py_InitializeFromConfig` API should be used with
   :c:type:`PyConfig` instead.

Doc/deprecations/c-api-pending-removal-in-3.15.rst

@@ -43,7 +43,7 @@ Identifying free-threaded Python
 ================================
 
 To check if the current interpreter supports free-threading, :option:`python -VV <-V>`
-and :attr:`sys.version` contain "experimental free-threading build".
+and :data:`sys.version` contain "experimental free-threading build".
 The new :func:`sys._is_gil_enabled` function can be used to check whether
 the GIL is actually disabled in the running process.
 

Doc/howto/free-threading-python.rst

@@ -93,7 +93,7 @@ The :mod:`!datetime` module exports the following constants:
    The largest year number allowed in a :class:`date` or :class:`.datetime` object.
    :const:`MAXYEAR` is 9999.
 
-.. attribute:: UTC
+.. data:: UTC
 
    Alias for the UTC time zone singleton :attr:`datetime.timezone.utc`.
 
@@ -970,7 +970,7 @@ Other constructors, all class methods:
 
    .. deprecated:: 3.12
 
-      Use :meth:`datetime.now` with :attr:`UTC` instead.
+      Use :meth:`datetime.now` with :const:`UTC` instead.
 
 
 .. classmethod:: datetime.fromtimestamp(timestamp, tz=None)
@@ -1042,7 +1042,7 @@ Other constructors, all class methods:
 
    .. deprecated:: 3.12
 
-      Use :meth:`datetime.fromtimestamp` with :attr:`UTC` instead.
+      Use :meth:`datetime.fromtimestamp` with :const:`UTC` instead.
 
 
 .. classmethod:: datetime.fromordinal(ordinal)

Doc/library/datetime.rst

@@ -2262,7 +2262,7 @@ value for :attr:`~Context.prec` as well [#]_::
     Decimal('904625697166532776746648320380374280103671755200316906558262375061821325312')
 
 
-For inexact results, :attr:`MAX_PREC` is far too large on 64-bit platforms and
+For inexact results, :const:`MAX_PREC` is far too large on 64-bit platforms and
 the available memory will be insufficient::
 
    >>> Decimal(1) / 3

Doc/library/decimal.rst

@@ -562,9 +562,13 @@ The following exceptions are the exceptions that are usually raised.
 
    Raised when the interpreter finds an internal error, but the situation does not
    look so serious to cause it to abandon all hope. The associated value is a
-   string indicating what went wrong (in low-level terms).
+   string indicating what went wrong (in low-level terms). In :term:`CPython`,
+   this could be raised by incorrectly using Python's C API, such as returning
+   a ``NULL`` value without an exception set.
 
-   You should report this to the author or maintainer of your Python interpreter.
+   If you're confident that this exception wasn't your fault, or the fault of
+   a package you're using, you should report this to the author or maintainer
+   of your Python interpreter.
    Be sure to report the version of the Python interpreter (``sys.version``; it is
    also printed at the start of an interactive Python session), the exact error
    message (the exception's associated value) and if possible the source of the

Doc/library/exceptions.rst

@@ -189,7 +189,7 @@ The :class:`dircmp` class
          are the same type as *self*, if *self* is a subclass of
          :class:`dircmp`.
 
-.. attribute:: DEFAULT_IGNORES
+.. data:: DEFAULT_IGNORES
 
    .. versionadded:: 3.4