mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-21 16:10:33 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 6

[3.13] GH-109975: Copyedit 3.13 What's New: C API (GH-124313) (#124334)

Browse source 
* [3.13] GH-109975: Copyedit 3.13 What's New: C API (GH-124313)
(cherry picked from commit 9d0a75269c)

* gh-118915: Add/fix docs entries for some new 3.13 C API (GH-124134)

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Co-authored-by: Petr Viktorin <encukou@gmail.com>
This commit is contained in:
Adam Turner 2024-09-23 19:14:13 +01:00 • committed by GitHub
parent af8e77e245
commit 86f30dd539
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
5 changed files with 502 additions and 366 deletions
Download patch file Download diff file Expand all files Collapse all files

42
Doc/c-api/monitoring.rst
View file

@ -1,6 +1,6 @@
.. highlight:: c .. highlight:: c
.. _monitoring: .. _c-api-monitoring:
Monitoring C API Monitoring C API
================ ================
@ -133,7 +133,7 @@ Managing the Monitoring State
Monitoring states can be managed with the help of monitoring scopes. A scope Monitoring states can be managed with the help of monitoring scopes. A scope
would typically correspond to a python function. would typically correspond to a python function.
.. :c:function:: int PyMonitoring_EnterScope(PyMonitoringState *state_array, uint64_t *version, const uint8_t *event_types, Py_ssize_t length) .. c:function:: int PyMonitoring_EnterScope(PyMonitoringState *state_array, uint64_t *version, const uint8_t *event_types, Py_ssize_t length)
Enter a monitored scope. ``event_types`` is an array of the event IDs for Enter a monitored scope. ``event_types`` is an array of the event IDs for
events that may be fired from the scope. For example, the ID of a ``PY_START`` events that may be fired from the scope. For example, the ID of a ``PY_START``
@ -141,24 +141,52 @@ would typically correspond to a python function.
to the base-2 logarithm of ``sys.monitoring.events.PY_START``. to the base-2 logarithm of ``sys.monitoring.events.PY_START``.
``state_array`` is an array with a monitoring state entry for each event in ``state_array`` is an array with a monitoring state entry for each event in
``event_types``, it is allocated by the user but populated by ``event_types``, it is allocated by the user but populated by
``PyMonitoring_EnterScope`` with information about the activation state of :c:func:`!PyMonitoring_EnterScope` with information about the activation state of
the event. The size of ``event_types`` (and hence also of ``state_array``) the event. The size of ``event_types`` (and hence also of ``state_array``)
is given in ``length``. is given in ``length``.
The ``version`` argument is a pointer to a value which should be allocated The ``version`` argument is a pointer to a value which should be allocated
by the user together with ``state_array`` and initialized to 0, by the user together with ``state_array`` and initialized to 0,
and then set only by ``PyMonitoring_EnterScope`` itelf. It allows this and then set only by :c:func:`!PyMonitoring_EnterScope` itelf. It allows this
function to determine whether event states have changed since the previous call, function to determine whether event states have changed since the previous call,
and to return quickly if they have not. and to return quickly if they have not.
The scopes referred to here are lexical scopes: a function, class or method. The scopes referred to here are lexical scopes: a function, class or method.
``PyMonitoring_EnterScope`` should be called whenever the lexical scope is :c:func:`!PyMonitoring_EnterScope` should be called whenever the lexical scope is
entered. Scopes can be reentered, reusing the same *state_array* and *version*, entered. Scopes can be reentered, reusing the same *state_array* and *version*,
in situations like when emulating a recursive Python function. When a code-like's in situations like when emulating a recursive Python function. When a code-like's
execution is paused, such as when emulating a generator, the scope needs to execution is paused, such as when emulating a generator, the scope needs to
be exited and re-entered. be exited and re-entered.
The macros for *event_types* are:
.. :c:function:: int PyMonitoring_ExitScope(void) .. c:namespace:: NULL
Exit the last scope that was entered with ``PyMonitoring_EnterScope``. .. The table is here to make the docs searchable, and to allow automatic
links to the identifiers.
================================================== =====================================
Macro Event
================================================== =====================================
.. c:macro:: PY_MONITORING_EVENT_BRANCH :monitoring-event:`BRANCH`
.. c:macro:: PY_MONITORING_EVENT_CALL :monitoring-event:`CALL`
.. c:macro:: PY_MONITORING_EVENT_C_RAISE :monitoring-event:`C_RAISE`
.. c:macro:: PY_MONITORING_EVENT_C_RETURN :monitoring-event:`C_RETURN`
.. c:macro:: PY_MONITORING_EVENT_EXCEPTION_HANDLED :monitoring-event:`EXCEPTION_HANDLED`
.. c:macro:: PY_MONITORING_EVENT_INSTRUCTION :monitoring-event:`INSTRUCTION`
.. c:macro:: PY_MONITORING_EVENT_JUMP :monitoring-event:`JUMP`
.. c:macro:: PY_MONITORING_EVENT_LINE :monitoring-event:`LINE`
.. c:macro:: PY_MONITORING_EVENT_PY_RESUME :monitoring-event:`PY_RESUME`
.. c:macro:: PY_MONITORING_EVENT_PY_RETURN :monitoring-event:`PY_RETURN`
.. c:macro:: PY_MONITORING_EVENT_PY_START :monitoring-event:`PY_START`
.. c:macro:: PY_MONITORING_EVENT_PY_THROW :monitoring-event:`PY_THROW`
.. c:macro:: PY_MONITORING_EVENT_PY_UNWIND :monitoring-event:`PY_UNWIND`
.. c:macro:: PY_MONITORING_EVENT_PY_YIELD :monitoring-event:`PY_YIELD`
.. c:macro:: PY_MONITORING_EVENT_RAISE :monitoring-event:`RAISE`
.. c:macro:: PY_MONITORING_EVENT_RERAISE :monitoring-event:`RERAISE`
.. c:macro:: PY_MONITORING_EVENT_STOP_ITERATION :monitoring-event:`STOP_ITERATION`
================================================== =====================================
.. c:function:: int PyMonitoring_ExitScope(void)
Exit the last scope that was entered with :c:func:`!PyMonitoring_EnterScope`.

2
Doc/c-api/time.rst
View file

@ -1,5 +1,7 @@
.. highlight:: c .. highlight:: c
.. _c-api-time:
PyTime C API PyTime C API
============ ============

1
Doc/conf.py
View file

@ -141,6 +141,7 @@ nitpick_ignore = [
('c:type', 'size_t'), ('c:type', 'size_t'),
('c:type', 'ssize_t'), ('c:type', 'ssize_t'),
('c:type', 'time_t'), ('c:type', 'time_t'),
('c:type', 'uint8_t'),
('c:type', 'uint64_t'), ('c:type', 'uint64_t'),
('c:type', 'uintmax_t'), ('c:type', 'uintmax_t'),
('c:type', 'uintptr_t'), ('c:type', 'uintptr_t'),

2
Doc/library/sys.monitoring.rst
View file

@ -258,7 +258,7 @@ Per code object events
Events can also be controlled on a per code object basis. The functions Events can also be controlled on a per code object basis. The functions
defined below which accept a :class:`types.CodeType` should be prepared defined below which accept a :class:`types.CodeType` should be prepared
to accept a look-alike object from functions which are not defined to accept a look-alike object from functions which are not defined
in Python (see :ref:`monitoring`). in Python (see :ref:`c-api-monitoring`).
.. function:: get_local_events(tool_id: int, code: CodeType, /) -> int .. function:: get_local_events(tool_id: int, code: CodeType, /) -> int

821
Doc/whatsnew/3.13.rst
View file

@ -159,6 +159,8 @@ C API improvements:
* The :doc:`PyTime C API </c-api/time>` has been added, * The :doc:`PyTime C API </c-api/time>` has been added,
providing access to system clocks. providing access to system clocks.
* :c:type:`PyMutex` is a new lightweight mutex that occupies a single byte. * :c:type:`PyMutex` is a new lightweight mutex that occupies a single byte.
* 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 typing features:
@ -2005,225 +2007,497 @@ C API Changes
New Features New Features
------------ ------------
* You no longer have to define the ``PY_SSIZE_T_CLEAN`` macro before including * Add the :ref:`PyMonitoring C API <c-api-monitoring>`
:file:`Python.h` when using ``#`` formats in 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`
(Contributed by Irit Katriel in :gh:`111997`).
* 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 the :ref:`PyTime C API <c-api-time>` to provide access to system clocks:
* :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`.
(Contributed by Victor Stinner and Petr Viktorin in :gh:`110850`.)
* 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`.)
* 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`.)
* 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`.)
* 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`.)
* 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 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 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>`:
* :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`
(Contributed by Mark Shannon and Tian Gao in :gh:`74929`.)
* 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 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 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`.)
* 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:`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 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 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 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`.)
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 support for the ``%T``, ``%#T``, ``%N`` and ``%#N`` formats
to :c:func:`PyUnicode_FromFormat`:
* ``%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
See :pep:`737` for more information.
(Contributed by Victor Stinner in :gh:`111696`.)
* 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>`. :ref:`format codes <arg-parsing-string-and-buffers>`.
APIs accepting the format codes always use ``Py_ssize_t`` for ``#`` formats. APIs accepting the format codes always use ``Py_ssize_t`` for ``#`` formats.
(Contributed by Inada Naoki in :gh:`104922`.) (Contributed by Inada Naoki in :gh:`104922`.)
* The *keywords* parameter of :c:func:`PyArg_ParseTupleAndKeywords` and * If Python is built in :ref:`debug mode <debug-build>`
:c:func:`PyArg_VaParseTupleAndKeywords` now has type :c:expr:`char * const *` or :option:`with assertions <--with-assertions>`,
in C and :c:expr:`const char * const *` in C++, instead of :c:expr:`char **`. :c:func:`PyTuple_SET_ITEM` and :c:func:`PyList_SET_ITEM`
It makes these functions compatible with arguments of type now check the index argument with an assertion.
: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`.)
* 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: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 :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`.)
* 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`.)
* 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`.
New functions return not only ``1`` for true and ``0`` for false, but also
``-1`` for error.
(Contributed by Serhiy Storchaka in :gh:`108511`.)
* 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`.) (Contributed by Victor Stinner in :gh:`106168`.)
* 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 :c:func:`PyDict_GetItemRef` and :c:func:`PyDict_GetItemStringRef` Limited C API Changes
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`.)
* Added :c:func:`PyDict_SetDefaultRef`, which is similar to * The following functions are now included in the Limited C API:
: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`.)
* Add :c:func:`PyDict_ContainsString` function: same as * :c:func:`PyMem_RawMalloc`
:c:func:`PyDict_Contains`, but *key* is specified as a :c:expr:`const char*` * :c:func:`PyMem_RawCalloc`
UTF-8 encoded bytes string, rather than a :c:expr:`PyObject*`. * :c:func:`PyMem_RawRealloc`
(Contributed by Victor Stinner in :gh:`108314`.) * :c:func:`PyMem_RawFree`
* :c:func:`PySys_Audit`
* :c:func:`PySys_AuditTuple`
* :c:func:`PyType_GetModuleByDef`
* Added :c:func:`PyList_GetItemRef` function: similar to (Contributed by Victor Stinner in :gh:`85283`, :gh:`85283`, and :gh:`116936`.)
:c:func:`PyList_GetItem` but returns a :term:`strong reference` instead of
a :term:`borrowed reference`.
* Add :c:func:`Py_IsFinalizing` function: check if the main Python interpreter is * Python built with :option:`--with-trace-refs` (tracing references)
:term:`shutting down <interpreter shutdown>`. now supports the :ref:`Limited API <limited-c-api>`.
(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).
(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`.) (Contributed by Victor Stinner in :gh:`108634`.)
* 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.
(Contributed by Victor Stinner in :gh:`107073`.)
* Add :c:func:`PyUnicode_EqualToUTF8AndSize` and :c:func:`PyUnicode_EqualToUTF8` Removed C APIs
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.
These functions do not raise exceptions.
(Contributed by Serhiy Storchaka in :gh:`110289`.)
* Add :c:func:`PyThreadState_GetUnchecked()` function: similar to * Remove several functions, macros, variables, etc
:c:func:`PyThreadState_Get()`, but don't kill the process with a fatal error with names prefixed by ``_Py`` or ``_PY`` (which are considered private).
if it is NULL. The caller is responsible to check if the result is NULL. If your project is affected by one of these removals
Previously, the function was private and known as and you believe that the removed API should remain available,
``_PyThreadState_UncheckedGet()``. please :ref:`open a new issue <using-the-tracker>` to request a public C API
(Contributed by Victor Stinner in :gh:`108867`.) and add ``cc: @vstinner`` to the issue to notify Victor Stinner.
(Contributed by Victor Stinner in :gh:`106320`.)
* Add :c:func:`PySys_AuditTuple` function: similar to :c:func:`PySys_Audit`, * Remove old buffer protocols deprecated in Python 3.0.
but pass event arguments as a Python :class:`tuple` object. Use :ref:`bufferobjects` instead.
(Contributed by Victor Stinner in :gh:`85283`.)
* :c:func:`PyArg_ParseTupleAndKeywords` now supports non-ASCII keyword * :c:func:`!PyObject_CheckReadBuffer`:
parameter names. Use :c:func:`PyObject_CheckBuffer` to test
(Contributed by Serhiy Storchaka in :gh:`110815`.) 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:`PyMem_RawMalloc`, :c:func:`PyMem_RawCalloc`, * :c:func:`!PyObject_AsCharBuffer`, :c:func:`!PyObject_AsReadBuffer`:
:c:func:`PyMem_RawRealloc` and :c:func:`PyMem_RawFree` to the limited C API Use :c:func:`PyObject_GetBuffer` and :c:func:`PyBuffer_Release` instead:
(version 3.13).
(Contributed by Victor Stinner in :gh:`85283`.)
* Add :c:func:`PySys_Audit` and :c:func:`PySys_AuditTuple` functions to the .. code-block:: c
limited C API.
(Contributed by Victor Stinner in :gh:`85283`.)
* Add :c:func:`PyErr_FormatUnraisable` function: similar to Py_buffer view;
:c:func:`PyErr_WriteUnraisable`, but allow customizing the warning message. if (PyObject_GetBuffer(obj, &view, PyBUF_SIMPLE) < 0) {
(Contributed by Serhiy Storchaka in :gh:`108082`.) 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:func:`PyList_Extend` and :c:func:`PyList_Clear` functions: similar to * :c:func:`!PyObject_AsWriteBuffer`:
Python ``list.extend()`` and ``list.clear()`` methods. Use :c:func:`PyObject_GetBuffer` and :c:func:`PyBuffer_Release` instead:
(Contributed by Victor Stinner in :gh:`111138`.)
* Add :c:func:`PyDict_Pop` and :c:func:`PyDict_PopString` functions: remove a .. code-block:: c
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`.)
* Add :c:func:`Py_HashPointer` function to hash a pointer. Py_buffer view;
(Contributed by Victor Stinner in :gh:`111545`.) if (PyObject_GetBuffer(obj, &view, PyBUF_WRITABLE) < 0) {
return NULL;
}
// Use `view.buf` and `view.len` to write to the buffer.
PyBuffer_Release(&view);
* Add :c:func:`PyObject_GenericHash` function that implements the default (Contributed by Inada Naoki in :gh:`85275`.)
hashing function of a Python object.
(Contributed by Serhiy Storchaka in :gh:`113024`.)
* Add PyTime C API: * Remove various functions deprecated in Python 3.9:
* :c:type:`PyTime_t` type. * :c:func:`!PyEval_CallObject`, :c:func:`!PyEval_CallObjectWithKeywords`:
* :c:var:`PyTime_MIN` and :c:var:`PyTime_MAX` constants. Use :c:func:`PyObject_CallNoArgs` or :c:func:`PyObject_Call` instead.
* Add functions:
* :c:func:`PyTime_AsSecondsDouble`. .. warning::
* :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 and Petr Viktorin in :gh:`110850`.) 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>`.
* Add :c:func:`PyLong_AsNativeBytes`, :c:func:`PyLong_FromNativeBytes` and * :c:func:`!PyEval_CallFunction`:
:c:func:`PyLong_FromUnsignedNativeBytes` functions to simplify converting Use :c:func:`PyObject_CallFunction` instead.
between native integer types and Python :class:`int` objects. * :c:func:`!PyEval_CallMethod`:
(Contributed by Steve Dower in :gh:`111140`.) Use :c:func:`PyObject_CallMethod` instead.
* :c:func:`!PyCFunction_Call`:
Use :c:func:`PyObject_Call` instead.
* Add :c:func:`PyType_GetFullyQualifiedName` function to get the type's fully (Contributed by Victor Stinner in :gh:`105107`.)
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`.)
* Add :c:func:`PyType_GetModuleName` function to get the type's module name. * Remove the following old functions to configure the Python initialization,
Equivalent to getting the ``type.__module__`` attribute. deprecated in Python 3.11:
(Contributed by Eric Snow and Victor Stinner in :gh:`111696`.)
* Add support for ``%T``, ``%#T``, ``%N`` and ``%#N`` formats to * :c:func:`!PySys_AddWarnOptionUnicode`:
:c:func:`PyUnicode_FromFormat`: format the fully qualified name of an object Use :c:member:`PyConfig.warnoptions` instead.
type and of a type: call :c:func:`PyType_GetModuleName`. See :pep:`737` for * :c:func:`!PySys_AddWarnOption`:
more information. Use :c:member:`PyConfig.warnoptions` instead.
(Contributed by Victor Stinner in :gh:`111696`.) * :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.
* Add :c:func:`Py_GetConstant` and :c:func:`Py_GetConstantBorrowed` functions Use the new :c:type:`PyConfig` API of the :ref:`Python Initialization
to get constants. For example, ``Py_GetConstant(Py_CONSTANT_ZERO)`` returns a Configuration <init-config>` instead (:pep:`587`), added to Python 3.8.
:term:`strong reference` to the constant zero. (Contributed by Victor Stinner in :gh:`105145`.)
(Contributed by Victor Stinner in :gh:`115754`.)
* Add :c:func:`PyType_GetModuleByDef` to the limited C API * Remove :c:func:`!PyEval_AcquireLock` and :c:func:`!PyEval_ReleaseLock` functions,
(Contributed by Victor Stinner in :gh:`116936`.) deprecated in Python 3.2.
They didn't update the current thread state.
They can be replaced with:
* Add two new functions to the C-API, :c:func:`PyRefTracer_SetTracer` and * :c:func:`PyEval_SaveThread` and :c:func:`PyEval_RestoreThread`;
:c:func:`PyRefTracer_GetTracer`, that allow to track object creation and * low-level :c:func:`PyEval_AcquireThread` and :c:func:`PyEval_RestoreThread`;
destruction the same way the :mod:`tracemalloc` module does. (Contributed * or :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release`.
by Pablo Galindo in :gh:`93502`.)
* Add :c:func:`PyEval_GetFrameBuiltins`, :c:func:`PyEval_GetFrameGlobals`, and (Contributed by Victor Stinner in :gh:`105182`.)
: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`.)
* Add :c:type:`PyMutex` API, a lightweight mutex that occupies a single byte. * Remove the :c:func:`!PyEval_ThreadsInitialized` function,
The :c:func:`PyMutex_Lock` function will release the GIL (if currently held) deprecated in Python 3.9.
if the operation needs to block. Since Python 3.7, :c:func:`!Py_Initialize` always creates the GIL:
(Contributed by Sam Gross in :gh:`108724`.) 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 Build Changes
============= =============
@ -2289,7 +2563,7 @@ Changes in the Python API
main interpreter. main interpreter.
Any library or application that provides a custom ``_thread`` module 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. other "private" attributes.
(See :gh:`112826`.) (See :gh:`112826`.)
@ -2341,22 +2615,22 @@ Changes in the C API
-------------------- --------------------
* ``Python.h`` no longer includes the ``<ieeefp.h>`` standard header. It was * ``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 ``<math.h>`` header. It should now be included explicitly if needed. Remove
also the ``HAVE_IEEEFP_H`` macro. also the ``HAVE_IEEEFP_H`` macro.
(Contributed by Victor Stinner in :gh:`108765`.) (Contributed by Victor Stinner in :gh:`108765`.)
* ``Python.h`` no longer includes these standard header files: ``<time.h>``, * ``Python.h`` no longer includes these standard header files: ``<time.h>``,
``<sys/select.h>`` and ``<sys/time.h>``. If needed, they should now be ``<sys/select.h>`` and ``<sys/time.h>``. If needed, they should now be
included explicitly. For example, ``<time.h>`` provides the ``clock()`` and included explicitly. For example, ``<time.h>`` provides the :c:func:`!clock` and
``gmtime()`` functions, ``<sys/select.h>`` provides the ``select()`` :c:func:`!gmtime` functions, ``<sys/select.h>`` provides the :c:func:`!select`
function, and ``<sys/time.h>`` provides the ``futimes()``, ``gettimeofday()`` function, and ``<sys/time.h>`` provides the :c:func:`!futimes`, :c:func:`!gettimeofday`
and ``setitimer()`` functions. and :c:func:`!setitimer` functions.
(Contributed by Victor Stinner in :gh:`108765`.) (Contributed by Victor Stinner in :gh:`108765`.)
* On Windows, ``Python.h`` no longer includes the ``<stddef.h>`` standard * On Windows, ``Python.h`` no longer includes the ``<stddef.h>`` standard
header file. If needed, it should now be included explicitly. For example, it 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 Including ``<stddef.h>`` explicitly was already needed by all other
platforms, the ``HAVE_STDDEF_H`` macro is only defined on Windows. platforms, the ``HAVE_STDDEF_H`` macro is only defined on Windows.
(Contributed by Victor Stinner in :gh:`108765`.) (Contributed by Victor Stinner in :gh:`108765`.)
@ -2437,175 +2711,6 @@ Changes in the C API
is redundant now that :c:func:`PyFrame_GetLocals` returns a write-through proxy 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`.) 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 Regression Test Changes
======================= =======================