* The :doc:`PyTime C API </c-api/time>` has been added,
providing access to system clocks.
* :c:type:`PyMutex` is a new lightweight mutex that occupies a single byte.
-* :doc:`C-API support </c-api/monitoring>` was added for generating :pep:`669` monitoring events.
+* There is a new :ref:`suite of functions <c-api-monitoring>`
+ for generating :pep:`669` monitoring events in the C API.
New typing features:
New Features
------------
-* You no longer have to define the ``PY_SSIZE_T_CLEAN`` macro before including
- :file:`Python.h` when using ``#`` formats in
- :ref:`format codes <arg-parsing-string-and-buffers>`.
- APIs accepting the format codes always use ``Py_ssize_t`` for ``#`` formats.
- (Contributed by Inada Naoki in :gh:`104922`.)
+* Add the :ref:`PyMonitoring C API <c-api-monitoring>`
+ for generating :pep:`669` monitoring events:
+
+ * :c:type:`PyMonitoringState`
+ * :c:func:`PyMonitoring_FirePyStartEvent`
+ * :c:func:`PyMonitoring_FirePyResumeEvent`
+ * :c:func:`PyMonitoring_FirePyReturnEvent`
+ * :c:func:`PyMonitoring_FirePyYieldEvent`
+ * :c:func:`PyMonitoring_FireCallEvent`
+ * :c:func:`PyMonitoring_FireLineEvent`
+ * :c:func:`PyMonitoring_FireJumpEvent`
+ * :c:func:`PyMonitoring_FireBranchEvent`
+ * :c:func:`PyMonitoring_FireCReturnEvent`
+ * :c:func:`PyMonitoring_FirePyThrowEvent`
+ * :c:func:`PyMonitoring_FireRaiseEvent`
+ * :c:func:`PyMonitoring_FireCRaiseEvent`
+ * :c:func:`PyMonitoring_FireReraiseEvent`
+ * :c:func:`PyMonitoring_FireExceptionHandledEvent`
+ * :c:func:`PyMonitoring_FirePyUnwindEvent`
+ * :c:func:`PyMonitoring_FireStopIterationEvent`
+ * :c:func:`PyMonitoring_EnterScope`
+ * :c:func:`PyMonitoring_ExitScope`
-* The *keywords* parameter of :c:func:`PyArg_ParseTupleAndKeywords` and
- :c:func:`PyArg_VaParseTupleAndKeywords` now has type :c:expr:`char * const *`
- in C and :c:expr:`const char * const *` in C++, instead of :c:expr:`char **`.
- It makes these functions compatible with arguments of type
- :c:expr:`const char * const *`, :c:expr:`const char **` or
- :c:expr:`char * const *` in C++ and :c:expr:`char * const *` in C
- without an explicit type cast.
- This can be overridden with the :c:macro:`PY_CXX_CONST` macro.
- (Contributed by Serhiy Storchaka in :gh:`65210`.)
+ (Contributed by Irit Katriel in :gh:`111997`).
-* Add :c:func:`PyImport_AddModuleRef`: similar to
- :c:func:`PyImport_AddModule`, but return a :term:`strong reference` instead
- of a :term:`borrowed reference`.
- (Contributed by Victor Stinner in :gh:`105922`.)
+* Add :c:type:`PyMutex`, a lightweight mutex that occupies a single byte,
+ and the new :c:func:`PyMutex_Lock` and :c:func:`PyMutex_Unlock` functions.
+ :c:func:`!PyMutex_Lock` will release the :term:`GIL` (if currently held)
+ if the operation needs to block.
+ (Contributed by Sam Gross in :gh:`108724`.)
-* Add :c:func:`PyWeakref_GetRef` function: similar to
- :c:func:`PyWeakref_GetObject` but returns a :term:`strong reference`, or
- ``NULL`` if the referent is no longer live.
- (Contributed by Victor Stinner in :gh:`105927`.)
+* Add the :ref:`PyTime C API <c-api-time>` to provide access to system clocks:
-* Add :c:func:`PyObject_GetOptionalAttr` and
- :c:func:`PyObject_GetOptionalAttrString`, variants of
- :c:func:`PyObject_GetAttr` and :c:func:`PyObject_GetAttrString` which
- don't raise :exc:`AttributeError` if the attribute is not found.
- These variants are more convenient and faster if the missing attribute
- should not be treated as a failure.
- (Contributed by Serhiy Storchaka in :gh:`106521`.)
+ * :c:type:`PyTime_t`.
+ * :c:var:`PyTime_MIN` and :c:var:`PyTime_MAX`.
+ * :c:func:`PyTime_AsSecondsDouble`.
+ * :c:func:`PyTime_Monotonic`.
+ * :c:func:`PyTime_MonotonicRaw`.
+ * :c:func:`PyTime_PerfCounter`.
+ * :c:func:`PyTime_PerfCounterRaw`.
+ * :c:func:`PyTime_Time`.
+ * :c:func:`PyTime_TimeRaw`.
-* Add :c:func:`PyMapping_GetOptionalItem` and
- :c:func:`PyMapping_GetOptionalItemString`: variants of
- :c:func:`PyObject_GetItem` and :c:func:`PyMapping_GetItemString` which don't
- raise :exc:`KeyError` if the key is not found.
- These variants are more convenient and faster if the missing key should not
- be treated as a failure.
- (Contributed by Serhiy Storchaka in :gh:`106307`.)
+ (Contributed by Victor Stinner and Petr Viktorin in :gh:`110850`.)
-* Add fixed variants of functions which silently ignore errors:
+* Add the :c:func:`PyDict_ContainsString` function
+ with the same behaviour as :c:func:`PyDict_Contains`,
+ but *key* is specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
+ rather than a :c:expr:`PyObject*`.
+ (Contributed by Victor Stinner in :gh:`108314`.)
+
+* Add the :c:func:`PyDict_GetItemRef` and :c:func:`PyDict_GetItemStringRef`
+ functions,
+ which behave similarly to :c:func:`PyDict_GetItemWithError`,
+ but return a :term:`strong reference` instead of a :term:`borrowed reference`.
+ Moreover, these functions return ``-1`` on error,
+ removing the need to check :c:func:`!PyErr_Occurred`.
+ (Contributed by Victor Stinner in :gh:`106004`.)
- - :c:func:`PyObject_HasAttrWithError` replaces :c:func:`PyObject_HasAttr`.
- - :c:func:`PyObject_HasAttrStringWithError` replaces :c:func:`PyObject_HasAttrString`.
- - :c:func:`PyMapping_HasKeyWithError` replaces :c:func:`PyMapping_HasKey`.
- - :c:func:`PyMapping_HasKeyStringWithError` replaces :c:func:`PyMapping_HasKeyString`.
+* Add the :c:func:`PyDict_SetDefaultRef` function,
+ which behaves similarly to :c:func:`PyDict_SetDefault`,
+ but returns a :term:`strong reference` instead of a :term:`borrowed reference`.
+ This function returns ``-1`` on error,
+ ``0`` on insertion,
+ and ``1`` if the key was already present in the dictionary.
+ (Contributed by Sam Gross in :gh:`112066`.)
- New functions return not only ``1`` for true and ``0`` for false, but also
- ``-1`` for error.
+* Add the :c:func:`PyDict_Pop` and :c:func:`PyDict_PopString` functions
+ to remove a key from a dictionary and optionally return the removed value.
+ This is similar to :meth:`dict.pop`,
+ though there is no default value,
+ and :exc:`KeyError` is not raised for missing keys.
+ (Contributed by Stefan Behnel and Victor Stinner in :gh:`111262`.)
- (Contributed by Serhiy Storchaka in :gh:`108511`.)
+* Add the :c:func:`PyMapping_GetOptionalItem`
+ and :c:func:`PyMapping_GetOptionalItemString` functions
+ as alternatives to :c:func:`PyObject_GetItem`
+ and :c:func:`PyMapping_GetItemString` respectively.
+ The new functions do not raise :exc:`KeyError`
+ if the requested key is missing from the mapping.
+ These variants are more convenient and faster
+ if a missing key should not be treated as a failure.
+ (Contributed by Serhiy Storchaka in :gh:`106307`.)
-* If Python is built in :ref:`debug mode <debug-build>` or :option:`with
- assertions <--with-assertions>`, :c:func:`PyTuple_SET_ITEM` and
- :c:func:`PyList_SET_ITEM` now check the index argument with an assertion.
- (Contributed by Victor Stinner in :gh:`106168`.)
+* Add the :c:func:`PyObject_GetOptionalAttr`
+ and :c:func:`PyObject_GetOptionalAttrString` functions
+ as alternatives to :c:func:`PyObject_GetAttr`
+ and :c:func:`PyObject_GetAttrString` respectively.
+ The new functions do not raise :exc:`AttributeError`
+ if the requested attribute is not found on the object.
+ These variants are more convenient and faster
+ if the missing attribute should not be treated as a failure.
+ (Contributed by Serhiy Storchaka in :gh:`106521`.)
-* Add :c:func:`PyModule_Add` function: similar to
- :c:func:`PyModule_AddObjectRef` and :c:func:`PyModule_AddObject` but
- always steals a reference to the value.
- (Contributed by Serhiy Storchaka in :gh:`86493`.)
+* Add the :c:func:`PyErr_FormatUnraisable` function
+ as an extension to :c:func:`PyErr_WriteUnraisable`
+ that allows customizing the warning message.
+ (Contributed by Serhiy Storchaka in :gh:`108082`.)
-* Add :c:func:`PyDict_GetItemRef` and :c:func:`PyDict_GetItemStringRef`
- functions: similar to :c:func:`PyDict_GetItemWithError` but returning a
- :term:`strong reference` instead of a :term:`borrowed reference`. Moreover,
- these functions return -1 on error and so checking ``PyErr_Occurred()`` is
- not needed.
- (Contributed by Victor Stinner in :gh:`106004`.)
+* Add new functions that return a :term:`strong reference` instead of
+ a :term:`borrowed reference` for frame locals, globals, and builtins,
+ as part of :ref:`PEP 667 <whatsnew313-locals-semantics>`:
-* Added :c:func:`PyDict_SetDefaultRef`, which is similar to
- :c:func:`PyDict_SetDefault` but returns a :term:`strong reference` instead of
- a :term:`borrowed reference`. This function returns ``-1`` on error, ``0`` on
- insertion, and ``1`` if the key was already present in the dictionary.
- (Contributed by Sam Gross in :gh:`112066`.)
+ * :c:func:`PyEval_GetFrameBuiltins` replaces :c:func:`PyEval_GetBuiltins`
+ * :c:func:`PyEval_GetFrameGlobals` replaces :c:func:`PyEval_GetGlobals`
+ * :c:func:`PyEval_GetFrameLocals` replaces :c:func:`PyEval_GetLocals`
-* Add :c:func:`PyDict_ContainsString` function: same as
- :c:func:`PyDict_Contains`, but *key* is specified as a :c:expr:`const char*`
- UTF-8 encoded bytes string, rather than a :c:expr:`PyObject*`.
- (Contributed by Victor Stinner in :gh:`108314`.)
+ (Contributed by Mark Shannon and Tian Gao in :gh:`74929`.)
-* Added :c:func:`PyList_GetItemRef` function: similar to
- :c:func:`PyList_GetItem` but returns a :term:`strong reference` instead of
- a :term:`borrowed reference`.
+* Add the :c:func:`Py_GetConstant` and :c:func:`Py_GetConstantBorrowed`
+ functions to get :term:`strong <strong reference>`
+ or :term:`borrowed <borrowed reference>` references to constants.
+ For example, ``Py_GetConstant(Py_CONSTANT_ZERO)`` returns a strong reference
+ to the constant zero.
+ (Contributed by Victor Stinner in :gh:`115754`.)
+
+* Add the :c:func:`PyImport_AddModuleRef` function
+ as a replacement for :c:func:`PyImport_AddModule`
+ that returns a :term:`strong reference` instead of a :term:`borrowed reference`.
+ (Contributed by Victor Stinner in :gh:`105922`.)
-* Add :c:func:`Py_IsFinalizing` function: check if the main Python interpreter is
+* Add the :c:func:`Py_IsFinalizing` function to check
+ whether the main Python interpreter is
:term:`shutting down <interpreter shutdown>`.
(Contributed by Victor Stinner in :gh:`108014`.)
-* Add :c:func:`PyLong_AsInt` function: similar to :c:func:`PyLong_AsLong`, but
- store the result in a C :c:expr:`int` instead of a C :c:expr:`long`.
- Previously, it was known as the private function :c:func:`!_PyLong_AsInt`
- (with an underscore prefix).
+* Add the :c:func:`PyList_GetItemRef` function
+ as a replacement for :c:func:`PyList_GetItem`
+ that returns a :term:`strong reference` instead of a :term:`borrowed reference`.
+ (Contributed by Sam Gross in :gh:`114329`.)
+
+* Add the :c:func:`PyList_Extend` and :c:func:`PyList_Clear` functions,
+ mirroring the Python :meth:`!list.extend` and :meth:`!list.clear` methods.
+ (Contributed by Victor Stinner in :gh:`111138`.)
+
+* Add the :c:func:`PyLong_AsInt` function.
+ It behaves similarly to :c:func:`PyLong_AsLong`,
+ but stores the result in a C :c:expr:`int` instead of a C :c:expr:`long`.
(Contributed by Victor Stinner in :gh:`108014`.)
-* Python built with :file:`configure` :option:`--with-trace-refs` (tracing
- references) now supports the :ref:`Limited API <limited-c-api>`.
- (Contributed by Victor Stinner in :gh:`108634`.)
+* Add the :c:func:`PyLong_AsNativeBytes`, :c:func:`PyLong_FromNativeBytes`,
+ and :c:func:`PyLong_FromUnsignedNativeBytes` functions
+ to simplify converting between native integer types
+ and Python :class:`int` objects.
+ (Contributed by Steve Dower in :gh:`111140`.)
-* Add :c:func:`PyObject_VisitManagedDict` and
- :c:func:`PyObject_ClearManagedDict` functions which must be called by the
- traverse and clear functions of a type using
- :c:macro:`Py_TPFLAGS_MANAGED_DICT` flag. The `pythoncapi-compat project
- <https://github.com/python/pythoncapi-compat/>`__ can be used to get these
- functions on Python 3.11 and 3.12.
+* Add :c:func:`PyModule_Add` function, which is similar to
+ :c:func:`PyModule_AddObjectRef` and :c:func:`PyModule_AddObject`,
+ but always steals a reference to the value.
+ (Contributed by Serhiy Storchaka in :gh:`86493`.)
+
+* Add the :c:func:`PyObject_GenericHash` function
+ that implements the default hashing function of a Python object.
+ (Contributed by Serhiy Storchaka in :gh:`113024`.)
+
+* Add the :c:func:`Py_HashPointer` function to hash a raw pointer.
+ (Contributed by Victor Stinner in :gh:`111545`.)
+
+* Add the :c:func:`PyObject_VisitManagedDict` and
+ :c:func:`PyObject_ClearManagedDict` functions.
+ which must be called by the traverse and clear functions of a type using
+ the :c:macro:`Py_TPFLAGS_MANAGED_DICT` flag.
+ The `pythoncapi-compat project`_ can be used to
+ use these functions with Python 3.11 and 3.12.
(Contributed by Victor Stinner in :gh:`107073`.)
-* Add :c:func:`PyUnicode_EqualToUTF8AndSize` and :c:func:`PyUnicode_EqualToUTF8`
- functions: compare Unicode object with a :c:expr:`const char*` UTF-8 encoded
- string and return true (``1``) if they are equal, or false (``0``) otherwise.
+* Add the :c:func:`PyRefTracer_SetTracer`
+ and :c:func:`PyRefTracer_GetTracer` functions,
+ which enable tracking object creation and destruction
+ in the same way that the :mod:`tracemalloc` module does.
+ (Contributed by Pablo Galindo in :gh:`93502`.)
+
+* Add the :c:func:`PySys_AuditTuple` function
+ as an alternative to :c:func:`PySys_Audit`
+ that takes event arguments as a Python :class:`tuple` object.
+ (Contributed by Victor Stinner in :gh:`85283`.)
+
+* Add the :c:func:`PyThreadState_GetUnchecked()` function
+ as an alternative to :c:func:`PyThreadState_Get()`
+ that doesn't kill the process with a fatal error if it is ``NULL``.
+ The caller is responsible for checking if the result is ``NULL``.
+ (Contributed by Victor Stinner in :gh:`108867`.)
+
+* Add the :c:func:`PyType_GetFullyQualifiedName` function
+ to get the type's fully qualified name.
+ The module name is prepended if ``type.__module__`` is a string
+ and is not equal to either ``'builtins'`` or ``'__main__'``.
+ (Contributed by Victor Stinner in :gh:`111696`.)
+
+* Add the :c:func:`PyType_GetModuleName` function
+ to get the type's module name.
+ This is equivalent to getting the ``type.__module__`` attribute.
+ (Contributed by Eric Snow and Victor Stinner in :gh:`111696`.)
+
+* Add the :c:func:`PyUnicode_EqualToUTF8AndSize`
+ and :c:func:`PyUnicode_EqualToUTF8` functions
+ to compare a Unicode object with a :c:expr:`const char*` UTF-8 encoded string
+ and ``1`` if they are equal or ``0`` otherwise.
These functions do not raise exceptions.
(Contributed by Serhiy Storchaka in :gh:`110289`.)
-* Add :c:func:`PyThreadState_GetUnchecked()` function: similar to
- :c:func:`PyThreadState_Get()`, but don't kill the process with a fatal error
- if it is NULL. The caller is responsible to check if the result is NULL.
- Previously, the function was private and known as
- ``_PyThreadState_UncheckedGet()``.
- (Contributed by Victor Stinner in :gh:`108867`.)
+* Add the :c:func:`PyWeakref_GetRef` function
+ as an alternative to :c:func:`PyWeakref_GetObject`
+ that returns a :term:`strong reference`
+ or ``NULL`` if the referent is no longer live.
+ (Contributed by Victor Stinner in :gh:`105927`.)
-* Add :c:func:`PySys_AuditTuple` function: similar to :c:func:`PySys_Audit`,
- but pass event arguments as a Python :class:`tuple` object.
- (Contributed by Victor Stinner in :gh:`85283`.)
+* Add fixed variants of functions which silently ignore errors:
+
+ * :c:func:`PyObject_HasAttrWithError` replaces :c:func:`PyObject_HasAttr`.
+ * :c:func:`PyObject_HasAttrStringWithError`
+ replaces :c:func:`PyObject_HasAttrString`.
+ * :c:func:`PyMapping_HasKeyWithError` replaces :c:func:`PyMapping_HasKey`.
+ * :c:func:`PyMapping_HasKeyStringWithError`
+ replaces :c:func:`PyMapping_HasKeyString`.
+
+ The new functions return ``-1`` for errors
+ and the standard ``1`` for true and ``0`` for false.
+
+ (Contributed by Serhiy Storchaka in :gh:`108511`.)
-* :c:func:`PyArg_ParseTupleAndKeywords` now supports non-ASCII keyword
- parameter names.
+
+Changed C APIs
+--------------
+
+* The *keywords* parameter of :c:func:`PyArg_ParseTupleAndKeywords`
+ and :c:func:`PyArg_VaParseTupleAndKeywords`
+ now has type :c:expr:`char * const *` in C
+ and :c:expr:`const char * const *` in C++,
+ instead of :c:expr:`char **`.
+ In C++, this makes these functions compatible with arguments
+ of type :c:expr:`const char * const *`, :c:expr:`const char **`,
+ or :c:expr:`char * const *` without an explicit type cast.
+ In C, the functions only support arguments of type :c:expr:`char * const *`.
+ This can be overridden with the :c:macro:`PY_CXX_CONST` macro.
+ (Contributed by Serhiy Storchaka in :gh:`65210`.)
+
+* :c:func:`PyArg_ParseTupleAndKeywords` now supports
+ non-ASCII keyword parameter names.
(Contributed by Serhiy Storchaka in :gh:`110815`.)
-* Add :c:func:`PyMem_RawMalloc`, :c:func:`PyMem_RawCalloc`,
- :c:func:`PyMem_RawRealloc` and :c:func:`PyMem_RawFree` to the limited C API
- (version 3.13).
- (Contributed by Victor Stinner in :gh:`85283`.)
+* Add support for the ``%T``, ``%#T``, ``%N`` and ``%#N`` formats
+ to :c:func:`PyUnicode_FromFormat`:
-* Add :c:func:`PySys_Audit` and :c:func:`PySys_AuditTuple` functions to the
- limited C API.
- (Contributed by Victor Stinner in :gh:`85283`.)
+ * ``%T``: Get the fully qualified name of an object type
+ * ``%#T``: As above, but use a colon as the separator
+ * ``%N``: Get the fully qualified name of a type
+ * ``%#N``: As above, but use a colon as the separator
-* Add :c:func:`PyErr_FormatUnraisable` function: similar to
- :c:func:`PyErr_WriteUnraisable`, but allow customizing the warning message.
- (Contributed by Serhiy Storchaka in :gh:`108082`.)
+ See :pep:`737` for more information.
+ (Contributed by Victor Stinner in :gh:`111696`.)
-* Add :c:func:`PyList_Extend` and :c:func:`PyList_Clear` functions: similar to
- Python ``list.extend()`` and ``list.clear()`` methods.
- (Contributed by Victor Stinner in :gh:`111138`.)
+* You no longer have to define the ``PY_SSIZE_T_CLEAN`` macro before
+ including :file:`Python.h` when using ``#`` formats in
+ :ref:`format codes <arg-parsing-string-and-buffers>`.
+ APIs accepting the format codes always use ``Py_ssize_t`` for ``#`` formats.
+ (Contributed by Inada Naoki in :gh:`104922`.)
-* Add :c:func:`PyDict_Pop` and :c:func:`PyDict_PopString` functions: remove a
- key from a dictionary and optionally return the removed value. This is
- similar to :meth:`dict.pop`, but without the default value and not raising
- :exc:`KeyError` if the key is missing.
- (Contributed by Stefan Behnel and Victor Stinner in :gh:`111262`.)
+* If Python is built in :ref:`debug mode <debug-build>`
+ or :option:`with assertions <--with-assertions>`,
+ :c:func:`PyTuple_SET_ITEM` and :c:func:`PyList_SET_ITEM`
+ now check the index argument with an assertion.
+ (Contributed by Victor Stinner in :gh:`106168`.)
-* Add :c:func:`Py_HashPointer` function to hash a pointer.
- (Contributed by Victor Stinner in :gh:`111545`.)
-* Add :c:func:`PyObject_GenericHash` function that implements the default
- hashing function of a Python object.
- (Contributed by Serhiy Storchaka in :gh:`113024`.)
+Limited C API Changes
+---------------------
-* Add PyTime C API:
+* The following functions are now included in the Limited C API:
- * :c:type:`PyTime_t` type.
- * :c:var:`PyTime_MIN` and :c:var:`PyTime_MAX` constants.
- * Add functions:
+ * :c:func:`PyMem_RawMalloc`
+ * :c:func:`PyMem_RawCalloc`
+ * :c:func:`PyMem_RawRealloc`
+ * :c:func:`PyMem_RawFree`
+ * :c:func:`PySys_Audit`
+ * :c:func:`PySys_AuditTuple`
+ * :c:func:`PyType_GetModuleByDef`
- * :c:func:`PyTime_AsSecondsDouble`.
- * :c:func:`PyTime_Monotonic`.
- * :c:func:`PyTime_MonotonicRaw`.
- * :c:func:`PyTime_PerfCounter`.
- * :c:func:`PyTime_PerfCounterRaw`.
- * :c:func:`PyTime_Time`.
- * :c:func:`PyTime_TimeRaw`.
+ (Contributed by Victor Stinner in :gh:`85283`, :gh:`85283`, and :gh:`116936`.)
- (Contributed by Victor Stinner and Petr Viktorin in :gh:`110850`.)
+* Python built with :option:`--with-trace-refs` (tracing references)
+ now supports the :ref:`Limited API <limited-c-api>`.
+ (Contributed by Victor Stinner in :gh:`108634`.)
-* Add :c:func:`PyLong_AsNativeBytes`, :c:func:`PyLong_FromNativeBytes` and
- :c:func:`PyLong_FromUnsignedNativeBytes` functions to simplify converting
- between native integer types and Python :class:`int` objects.
- (Contributed by Steve Dower in :gh:`111140`.)
-* Add :c:func:`PyType_GetFullyQualifiedName` function to get the type's fully
- qualified name. Equivalent to ``f"{type.__module__}.{type.__qualname__}"``,
- or ``type.__qualname__`` if ``type.__module__`` is not a string or is equal
- to ``"builtins"``.
- (Contributed by Victor Stinner in :gh:`111696`.)
+Removed C APIs
+--------------
-* Add :c:func:`PyType_GetModuleName` function to get the type's module name.
- Equivalent to getting the ``type.__module__`` attribute.
- (Contributed by Eric Snow and Victor Stinner in :gh:`111696`.)
+* Remove several functions, macros, variables, etc
+ with names prefixed by ``_Py`` or ``_PY`` (which are considered private).
+ If your project is affected by one of these removals
+ and you believe that the removed API should remain available,
+ please :ref:`open a new issue <using-the-tracker>` to request a public C API
+ and add ``cc: @vstinner`` to the issue to notify Victor Stinner.
+ (Contributed by Victor Stinner in :gh:`106320`.)
-* Add support for ``%T``, ``%#T``, ``%N`` and ``%#N`` formats to
- :c:func:`PyUnicode_FromFormat`: format the fully qualified name of an object
- type and of a type: call :c:func:`PyType_GetModuleName`. See :pep:`737` for
- more information.
- (Contributed by Victor Stinner in :gh:`111696`.)
+* Remove old buffer protocols deprecated in Python 3.0.
+ Use :ref:`bufferobjects` instead.
-* Add :c:func:`Py_GetConstant` and :c:func:`Py_GetConstantBorrowed` functions
- to get constants. For example, ``Py_GetConstant(Py_CONSTANT_ZERO)`` returns a
- :term:`strong reference` to the constant zero.
- (Contributed by Victor Stinner in :gh:`115754`.)
+ * :c:func:`!PyObject_CheckReadBuffer`:
+ Use :c:func:`PyObject_CheckBuffer` to test
+ whether the object supports the buffer protocol.
+ Note that :c:func:`PyObject_CheckBuffer` doesn't guarantee
+ that :c:func:`PyObject_GetBuffer` will succeed.
+ To test if the object is actually readable,
+ see the next example of :c:func:`PyObject_GetBuffer`.
-* Add :c:func:`PyType_GetModuleByDef` to the limited C API
- (Contributed by Victor Stinner in :gh:`116936`.)
+ * :c:func:`!PyObject_AsCharBuffer`, :c:func:`!PyObject_AsReadBuffer`:
+ Use :c:func:`PyObject_GetBuffer` and :c:func:`PyBuffer_Release` instead:
-* Add two new functions to the C-API, :c:func:`PyRefTracer_SetTracer` and
- :c:func:`PyRefTracer_GetTracer`, that allow to track object creation and
- destruction the same way the :mod:`tracemalloc` module does. (Contributed
- by Pablo Galindo in :gh:`93502`.)
+ .. code-block:: c
-* Add :c:func:`PyEval_GetFrameBuiltins`, :c:func:`PyEval_GetFrameGlobals`, and
- :c:func:`PyEval_GetFrameLocals` to the C API. These replacements for
- :c:func:`PyEval_GetBuiltins`, :c:func:`PyEval_GetGlobals`, and
- :c:func:`PyEval_GetLocals` return :term:`strong references <strong reference>`
- rather than borrowed references. (Added as part of :pep:`667`.)
+ Py_buffer view;
+ if (PyObject_GetBuffer(obj, &view, PyBUF_SIMPLE) < 0) {
+ return NULL;
+ }
+ // Use `view.buf` and `view.len` to read from the buffer.
+ // You may need to cast buf as `(const char*)view.buf`.
+ PyBuffer_Release(&view);
-* Add :c:type:`PyMutex` API, a lightweight mutex that occupies a single byte.
- The :c:func:`PyMutex_Lock` function will release the GIL (if currently held)
- if the operation needs to block.
- (Contributed by Sam Gross in :gh:`108724`.)
+ * :c:func:`!PyObject_AsWriteBuffer`:
+ Use :c:func:`PyObject_GetBuffer` and :c:func:`PyBuffer_Release` instead:
-* Add C API functions for generating :pep:`669` monitoring events.
- (Contributed by Irit Katriel in :gh:`111997`).
+ .. code-block:: c
+
+ Py_buffer view;
+ if (PyObject_GetBuffer(obj, &view, PyBUF_WRITABLE) < 0) {
+ return NULL;
+ }
+ // Use `view.buf` and `view.len` to write to the buffer.
+ PyBuffer_Release(&view);
+
+ (Contributed by Inada Naoki in :gh:`85275`.)
+
+* Remove various functions deprecated in Python 3.9:
+
+ * :c:func:`!PyEval_CallObject`, :c:func:`!PyEval_CallObjectWithKeywords`:
+ Use :c:func:`PyObject_CallNoArgs` or :c:func:`PyObject_Call` instead.
+
+ .. warning::
+
+ In :c:func:`PyObject_Call`, positional arguments must be a :class:`tuple`
+ and must not be ``NULL``,
+ and keyword arguments must be a :class:`dict` or ``NULL``,
+ whereas the removed functions checked argument types
+ and accepted ``NULL`` positional and keyword arguments.
+ To replace ``PyEval_CallObjectWithKeywords(func, NULL, kwargs)`` with
+ :c:func:`PyObject_Call`,
+ pass an empty tuple as positional arguments using
+ :c:func:`PyTuple_New(0) <PyTuple_New>`.
+
+ * :c:func:`!PyEval_CallFunction`:
+ Use :c:func:`PyObject_CallFunction` instead.
+ * :c:func:`!PyEval_CallMethod`:
+ Use :c:func:`PyObject_CallMethod` instead.
+ * :c:func:`!PyCFunction_Call`:
+ Use :c:func:`PyObject_Call` instead.
+
+ (Contributed by Victor Stinner in :gh:`105107`.)
+
+* Remove the following old functions to configure the Python initialization,
+ deprecated in Python 3.11:
+
+ * :c:func:`!PySys_AddWarnOptionUnicode`:
+ Use :c:member:`PyConfig.warnoptions` instead.
+ * :c:func:`!PySys_AddWarnOption`:
+ Use :c:member:`PyConfig.warnoptions` instead.
+ * :c:func:`!PySys_AddXOption`:
+ Use :c:member:`PyConfig.xoptions` instead.
+ * :c:func:`!PySys_HasWarnOptions`:
+ Use :c:member:`PyConfig.xoptions` instead.
+ * :c:func:`!PySys_SetPath`:
+ Set :c:member:`PyConfig.module_search_paths` instead.
+ * :c:func:`!Py_SetPath`:
+ Set :c:member:`PyConfig.module_search_paths` instead.
+ * :c:func:`!Py_SetStandardStreamEncoding`:
+ Set :c:member:`PyConfig.stdio_encoding` instead,
+ and set also maybe :c:member:`PyConfig.legacy_windows_stdio` (on Windows).
+ * :c:func:`!_Py_SetProgramFullPath`:
+ Set :c:member:`PyConfig.executable` instead.
+
+ Use the new :c:type:`PyConfig` API of the :ref:`Python Initialization
+ Configuration <init-config>` instead (:pep:`587`), added to Python 3.8.
+ (Contributed by Victor Stinner in :gh:`105145`.)
+
+* Remove :c:func:`!PyEval_AcquireLock` and :c:func:`!PyEval_ReleaseLock` functions,
+ deprecated in Python 3.2.
+ They didn't update the current thread state.
+ They can be replaced with:
+
+ * :c:func:`PyEval_SaveThread` and :c:func:`PyEval_RestoreThread`;
+ * low-level :c:func:`PyEval_AcquireThread` and :c:func:`PyEval_RestoreThread`;
+ * or :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release`.
+
+ (Contributed by Victor Stinner in :gh:`105182`.)
+
+* Remove the :c:func:`!PyEval_ThreadsInitialized` function,
+ deprecated in Python 3.9.
+ Since Python 3.7, :c:func:`!Py_Initialize` always creates the GIL:
+ calling :c:func:`!PyEval_InitThreads` does nothing and
+ :c:func:`!PyEval_ThreadsInitialized` always returns non-zero.
+ (Contributed by Victor Stinner in :gh:`105182`.)
+
+* Remove the :c:func:`!_PyInterpreterState_Get` alias to
+ :c:func:`PyInterpreterState_Get()`
+ which was kept for backward compatibility with Python 3.8.
+ The `pythoncapi-compat project`_ can be used to get
+ :c:func:`PyInterpreterState_Get()` on Python 3.8 and older.
+ (Contributed by Victor Stinner in :gh:`106320`.)
+
+* Remove the private :c:func:`!_PyObject_FastCall` function:
+ use :c:func:`!PyObject_Vectorcall` which is available since Python 3.8
+ (:pep:`590`).
+ (Contributed by Victor Stinner in :gh:`106023`.)
+
+* Remove the ``cpython/pytime.h`` header file,
+ which only contained private functions.
+ (Contributed by Victor Stinner in :gh:`106316`.)
+
+* Remove the undocumented ``PY_TIMEOUT_MAX`` constant from the limited C API.
+ (Contributed by Victor Stinner in :gh:`110014`.)
+
+* Remove the old trashcan macros ``Py_TRASHCAN_SAFE_BEGIN``
+ and ``Py_TRASHCAN_SAFE_END``.
+ Replace both with the new macros ``Py_TRASHCAN_BEGIN``
+ and ``Py_TRASHCAN_END``.
+ (Contributed by Irit Katriel in :gh:`105111`.)
+
+Deprecated C APIs
+-----------------
+
+* Deprecate old Python initialization functions:
+
+ * :c:func:`PySys_ResetWarnOptions`:
+ Clear :data:`sys.warnoptions` and :data:`!warnings.filters` instead.
+ * :c:func:`Py_GetExecPrefix`:
+ Get :data:`sys.exec_prefix` instead.
+ * :c:func:`Py_GetPath`:
+ Get :data:`sys.path` instead.
+ * :c:func:`Py_GetPrefix`:
+ Get :data:`sys.prefix` instead.
+ * :c:func:`Py_GetProgramFullPath`:
+ Get :data:`sys.executable` instead.
+ * :c:func:`Py_GetProgramName`:
+ Get :data:`sys.executable` instead.
+ * :c:func:`Py_GetPythonHome`:
+ Get :c:member:`PyConfig.home`
+ or the :envvar:`PYTHONHOME` environment variable instead.
+
+ (Contributed by Victor Stinner in :gh:`105145`.)
+
+* :term:`Soft deprecate <soft deprecated>` the
+ :c:func:`PyEval_GetBuiltins`, :c:func:`PyEval_GetGlobals`,
+ and :c:func:`PyEval_GetLocals` functions,
+ which return a :term:`borrowed reference`.
+ (Soft deprecated as part of :pep:`667`.)
+
+* Deprecate the :c:func:`PyImport_ImportModuleNoBlock` function,
+ which is just an alias to :c:func:`PyImport_ImportModule` since Python 3.3.
+ (Contributed by Victor Stinner in :gh:`105396`.)
+
+* :term:`Soft deprecate <soft deprecated>` the
+ :c:func:`PyModule_AddObject` function.
+ It should be replaced with :c:func:`PyModule_Add`
+ or :c:func:`PyModule_AddObjectRef`.
+ (Contributed by Serhiy Storchaka in :gh:`86493`.)
+
+* Deprecate the old ``Py_UNICODE`` and ``PY_UNICODE_TYPE`` types.
+ Use the :c:type:`wchar_t` type directly instead.
+ Since Python 3.3, ``Py_UNICODE`` and ``PY_UNICODE_TYPE``
+ are just aliases to :c:type:`!wchar_t`.
+ (Contributed by Victor Stinner in :gh:`105156`.)
+
+* Deprecate the :c:func:`PyWeakref_GetObject` and
+ :c:func:`PyWeakref_GET_OBJECT` functions,
+ which return a :term:`borrowed reference`.
+ Replace them with the new :c:func:`PyWeakref_GetRef` function,
+ which returns a :term:`strong reference`.
+ The `pythoncapi-compat project`_ can be used to get
+ :c:func:`PyWeakref_GetRef` on Python 3.12 and older.
+ (Contributed by Victor Stinner in :gh:`105927`.)
+
+.. Add deprecations above alphabetically, not here at the end.
+
+.. include:: ../deprecations/c-api-pending-removal-in-3.14.rst
+
+.. include:: ../deprecations/c-api-pending-removal-in-3.15.rst
+
+.. include:: ../deprecations/c-api-pending-removal-in-future.rst
+
+.. _pythoncapi-compat project: https://github.com/python/pythoncapi-compat/
Build Changes
=============
main interpreter.
Any library or application that provides a custom ``_thread`` module
- must provide ``_is_main_interpreter()``, just like the module's
+ must provide :func:`!_is_main_interpreter`, just like the module's
other "private" attributes.
(See :gh:`112826`.)
--------------------
* ``Python.h`` no longer includes the ``<ieeefp.h>`` standard header. It was
- included for the ``finite()`` function which is now provided by the
+ included for the :c:func:`!finite` function which is now provided by the
``<math.h>`` header. It should now be included explicitly if needed. Remove
also the ``HAVE_IEEEFP_H`` macro.
(Contributed by Victor Stinner in :gh:`108765`.)
* ``Python.h`` no longer includes these standard header files: ``<time.h>``,
``<sys/select.h>`` and ``<sys/time.h>``. If needed, they should now be
- included explicitly. For example, ``<time.h>`` provides the ``clock()`` and
- ``gmtime()`` functions, ``<sys/select.h>`` provides the ``select()``
- function, and ``<sys/time.h>`` provides the ``futimes()``, ``gettimeofday()``
- and ``setitimer()`` functions.
+ included explicitly. For example, ``<time.h>`` provides the :c:func:`!clock` and
+ :c:func:`!gmtime` functions, ``<sys/select.h>`` provides the :c:func:`!select`
+ function, and ``<sys/time.h>`` provides the :c:func:`!futimes`, :c:func:`!gettimeofday`
+ and :c:func:`!setitimer` functions.
(Contributed by Victor Stinner in :gh:`108765`.)
* On Windows, ``Python.h`` no longer includes the ``<stddef.h>`` standard
header file. If needed, it should now be included explicitly. For example, it
- provides ``offsetof()`` function, and ``size_t`` and ``ptrdiff_t`` types.
+ provides :c:func:`!offsetof` function, and ``size_t`` and ``ptrdiff_t`` types.
Including ``<stddef.h>`` explicitly was already needed by all other
platforms, the ``HAVE_STDDEF_H`` macro is only defined on Windows.
(Contributed by Victor Stinner in :gh:`108765`.)
is redundant now that :c:func:`PyFrame_GetLocals` returns a write-through proxy
for :term:`optimized scopes <optimized scope>`. (Changed as part of :pep:`667`.)
-Removed C APIs
---------------
-
-* Remove many APIs (functions, macros, variables) with names prefixed by
- ``_Py`` or ``_PY`` (considered as private API). If your project is affected
- by one of these removals and you consider that the removed API should remain
- available, please open a new issue to request a public C API and
- add ``cc @vstinner`` to the issue to notify Victor Stinner.
- (Contributed by Victor Stinner in :gh:`106320`.)
-
-* Remove functions deprecated in Python 3.9:
-
- * ``PyEval_CallObject()``, ``PyEval_CallObjectWithKeywords()``: use
- :c:func:`PyObject_CallNoArgs` or :c:func:`PyObject_Call` instead.
- Warning: :c:func:`PyObject_Call` positional arguments must be a
- :class:`tuple` and must not be ``NULL``, keyword arguments must be a
- :class:`dict` or ``NULL``, whereas removed functions checked arguments type
- and accepted ``NULL`` positional and keyword arguments.
- To replace ``PyEval_CallObjectWithKeywords(func, NULL, kwargs)`` with
- :c:func:`PyObject_Call`, pass an empty tuple as positional arguments using
- :c:func:`PyTuple_New(0) <PyTuple_New>`.
- * ``PyEval_CallFunction()``: use :c:func:`PyObject_CallFunction` instead.
- * ``PyEval_CallMethod()``: use :c:func:`PyObject_CallMethod` instead.
- * ``PyCFunction_Call()``: use :c:func:`PyObject_Call` instead.
-
- (Contributed by Victor Stinner in :gh:`105107`.)
-
-* Remove old buffer protocols deprecated in Python 3.0. Use :ref:`bufferobjects` instead.
-
- * :c:func:`!PyObject_CheckReadBuffer`: Use :c:func:`PyObject_CheckBuffer` to
- test if the object supports the buffer protocol.
- Note that :c:func:`PyObject_CheckBuffer` doesn't guarantee that
- :c:func:`PyObject_GetBuffer` will succeed.
- To test if the object is actually readable, see the next example
- of :c:func:`PyObject_GetBuffer`.
-
- * :c:func:`!PyObject_AsCharBuffer`, :c:func:`!PyObject_AsReadBuffer`:
- :c:func:`PyObject_GetBuffer` and :c:func:`PyBuffer_Release` instead:
-
- .. code-block:: c
-
- Py_buffer view;
- if (PyObject_GetBuffer(obj, &view, PyBUF_SIMPLE) < 0) {
- return NULL;
- }
- // Use `view.buf` and `view.len` to read from the buffer.
- // You may need to cast buf as `(const char*)view.buf`.
- PyBuffer_Release(&view);
-
- * :c:func:`!PyObject_AsWriteBuffer`: Use
- :c:func:`PyObject_GetBuffer` and :c:func:`PyBuffer_Release` instead:
-
- .. code-block:: c
-
- Py_buffer view;
- if (PyObject_GetBuffer(obj, &view, PyBUF_WRITABLE) < 0) {
- return NULL;
- }
- // Use `view.buf` and `view.len` to write to the buffer.
- PyBuffer_Release(&view);
-
- (Contributed by Inada Naoki in :gh:`85275`.)
-
-* Remove the following old functions to configure the Python initialization,
- deprecated in Python 3.11:
-
- * ``PySys_AddWarnOptionUnicode()``: use :c:member:`PyConfig.warnoptions` instead.
- * ``PySys_AddWarnOption()``: use :c:member:`PyConfig.warnoptions` instead.
- * ``PySys_AddXOption()``: use :c:member:`PyConfig.xoptions` instead.
- * ``PySys_HasWarnOptions()``: use :c:member:`PyConfig.xoptions` instead.
- * ``PySys_SetPath()``: set :c:member:`PyConfig.module_search_paths` instead.
- * ``Py_SetPath()``: set :c:member:`PyConfig.module_search_paths` instead.
- * ``Py_SetStandardStreamEncoding()``: set :c:member:`PyConfig.stdio_encoding`
- instead, and set also maybe :c:member:`PyConfig.legacy_windows_stdio` (on
- Windows).
- * ``_Py_SetProgramFullPath()``: set :c:member:`PyConfig.executable` instead.
-
- Use the new :c:type:`PyConfig` API of the :ref:`Python Initialization
- Configuration <init-config>` instead (:pep:`587`), added to Python 3.8.
- (Contributed by Victor Stinner in :gh:`105145`.)
-
-* Remove ``PyEval_ThreadsInitialized()``
- function, deprecated in Python 3.9. Since Python 3.7, ``Py_Initialize()``
- always creates the GIL: calling ``PyEval_InitThreads()`` does nothing and
- ``PyEval_ThreadsInitialized()`` always returned non-zero.
- (Contributed by Victor Stinner in :gh:`105182`.)
-
-* Remove ``PyEval_AcquireLock()`` and ``PyEval_ReleaseLock()`` functions,
- deprecated in Python 3.2. They didn't update the current thread state.
- They can be replaced with:
-
- * :c:func:`PyEval_SaveThread` and :c:func:`PyEval_RestoreThread`;
- * low-level :c:func:`PyEval_AcquireThread` and :c:func:`PyEval_RestoreThread`;
- * or :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release`.
-
- (Contributed by Victor Stinner in :gh:`105182`.)
-
-* Remove private ``_PyObject_FastCall()`` function:
- use ``PyObject_Vectorcall()`` which is available since Python 3.8
- (:pep:`590`).
- (Contributed by Victor Stinner in :gh:`106023`.)
-
-* Remove ``cpython/pytime.h`` header file: it only contained private functions.
- (Contributed by Victor Stinner in :gh:`106316`.)
-
-* Remove ``_PyInterpreterState_Get()`` alias to
- :c:func:`PyInterpreterState_Get()` which was kept for backward compatibility
- with Python 3.8. The `pythoncapi-compat project
- <https://github.com/python/pythoncapi-compat/>`__ can be used to get
- :c:func:`PyInterpreterState_Get()` on Python 3.8 and older.
- (Contributed by Victor Stinner in :gh:`106320`.)
-
-* The :c:func:`PyModule_AddObject` function is now :term:`soft deprecated`:
- :c:func:`PyModule_Add` or :c:func:`PyModule_AddObjectRef` functions should
- be used instead.
- (Contributed by Serhiy Storchaka in :gh:`86493`.)
-
-* Remove undocumented ``PY_TIMEOUT_MAX`` constant from the limited C API.
- (Contributed by Victor Stinner in :gh:`110014`.)
-
-Deprecated C APIs
------------------
-
-* Deprecate the old ``Py_UNICODE`` and ``PY_UNICODE_TYPE`` types: use directly
- the :c:type:`wchar_t` type instead. Since Python 3.3, ``Py_UNICODE`` and
- ``PY_UNICODE_TYPE`` are just aliases to :c:type:`wchar_t`.
- (Contributed by Victor Stinner in :gh:`105156`.)
-
-* Deprecate old Python initialization functions:
-
- * :c:func:`PySys_ResetWarnOptions`:
- clear :data:`sys.warnoptions` and :data:`!warnings.filters` instead.
- * :c:func:`Py_GetExecPrefix`: get :data:`sys.exec_prefix` instead.
- * :c:func:`Py_GetPath`: get :data:`sys.path` instead.
- * :c:func:`Py_GetPrefix`: get :data:`sys.prefix` instead.
- * :c:func:`Py_GetProgramFullPath`: get :data:`sys.executable` instead.
- * :c:func:`Py_GetProgramName`: get :data:`sys.executable` instead.
- * :c:func:`Py_GetPythonHome`: get :c:member:`PyConfig.home` or
- :envvar:`PYTHONHOME` environment variable instead.
-
- Functions scheduled for removal in Python 3.15.
- (Contributed by Victor Stinner in :gh:`105145`.)
-
-* Deprecate the :c:func:`PyImport_ImportModuleNoBlock` function which is just
- an alias to :c:func:`PyImport_ImportModule` since Python 3.3.
- Scheduled for removal in Python 3.15.
- (Contributed by Victor Stinner in :gh:`105396`.)
-
-* Deprecate the :c:func:`PyWeakref_GetObject` and
- :c:func:`PyWeakref_GET_OBJECT` functions, which return a :term:`borrowed
- reference`: use the new :c:func:`PyWeakref_GetRef` function instead, it
- returns a :term:`strong reference`. The `pythoncapi-compat project
- <https://github.com/python/pythoncapi-compat/>`__ can be used to get
- :c:func:`PyWeakref_GetRef` on Python 3.12 and older.
- (Contributed by Victor Stinner in :gh:`105927`.)
-
-* Deprecate the :c:func:`PyEval_GetBuiltins`, :c:func:`PyEval_GetGlobals`, and
- :c:func:`PyEval_GetLocals` functions, which return a :term:`borrowed reference`.
- Refer to the deprecation notices on each function for their recommended replacements.
- (Soft deprecated as part of :pep:`667`.)
-
-.. Add deprecations above alphabetically, not here at the end.
-
-.. include:: ../deprecations/c-api-pending-removal-in-3.14.rst
-
-.. include:: ../deprecations/c-api-pending-removal-in-3.15.rst
-
-.. include:: ../deprecations/c-api-pending-removal-in-future.rst
-
Regression Test Changes
=======================
projects / thirdparty / Python / cpython.git / commitdiff
