mirror of https://github.com/python/cpython
GH-109975: Copyedit 3.13 What's New: C API (#124313)
This commit is contained in:
Adam Turner
GitHub
parent
5f5c0b9c23
commit
9d0a75269c
|
|
@ -1,6 +1,6 @@
|
|||
.. highlight:: c
|
||||
|
||||
.. _monitoring:
|
||||
.. _c-api-monitoring:
|
||||
|
||||
Monitoring C API
|
||||
================
|
||||
|
|
@ -141,18 +141,18 @@ would typically correspond to a python function.
|
|||
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
|
||||
``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``)
|
||||
is given in ``length``.
|
||||
|
||||
The ``version`` argument is a pointer to a value which should be allocated
|
||||
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,
|
||||
and to return quickly if they have not.
|
||||
|
||||
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*,
|
||||
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
|
||||
|
|
@ -189,4 +189,4 @@ would typically correspond to a python function.
|
|||
|
||||
.. c:function:: int PyMonitoring_ExitScope(void)
|
||||
|
||||
Exit the last scope that was entered with ``PyMonitoring_EnterScope``.
|
||||
Exit the last scope that was entered with :c:func:`!PyMonitoring_EnterScope`.
|
||||
|
|
|
|||
|
|
@ -1,5 +1,7 @@
|
|||
.. highlight:: c
|
||||
|
||||
.. _c-api-time:
|
||||
|
||||
PyTime C API
|
||||
============
|
||||
|
||||
|
|
|
|||
|
|
@ -262,7 +262,7 @@ Per code object events
|
|||
Events can also be controlled on a per code object basis. The functions
|
||||
defined below which accept a :class:`types.CodeType` should be prepared
|
||||
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
|
||||
|
||||
|
|
|
|||
|
|
@ -159,7 +159,8 @@ C API improvements:
|
|||
* 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:
|
||||
|
||||
|
|
@ -2008,228 +2009,497 @@ C API Changes
|
|||
New Features
|
||||
------------
|
||||
|
||||
* You no longer have to define the ``PY_SSIZE_T_CLEAN`` macro before including
|
||||
:file:`Python.h` when using ``#`` formats in
|
||||
* 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`
|
||||
|
||||
(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>`.
|
||||
APIs accepting the format codes always use ``Py_ssize_t`` for ``#`` formats.
|
||||
(Contributed by Inada Naoki in :gh:`104922`.)
|
||||
|
||||
* 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`.)
|
||||
|
||||
* 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.
|
||||
* 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:`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`
|
||||
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`.)
|
||||
Limited C API Changes
|
||||
---------------------
|
||||
|
||||
* 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`.)
|
||||
* The following functions are now included in the Limited C API:
|
||||
|
||||
* 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`.)
|
||||
* :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`
|
||||
|
||||
* Added :c:func:`PyList_GetItemRef` function: similar to
|
||||
:c:func:`PyList_GetItem` but returns a :term:`strong reference` instead of
|
||||
a :term:`borrowed reference`.
|
||||
(Contributed by Victor Stinner in :gh:`85283`, :gh:`85283`, and :gh:`116936`.)
|
||||
|
||||
* Add :c:func:`Py_IsFinalizing` function: check if 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).
|
||||
(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>`.
|
||||
* 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:`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`
|
||||
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`.)
|
||||
Removed C APIs
|
||||
--------------
|
||||
|
||||
* 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`.)
|
||||
* 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 :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`.)
|
||||
* Remove old buffer protocols deprecated in Python 3.0.
|
||||
Use :ref:`bufferobjects` instead.
|
||||
|
||||
* :c:func:`PyArg_ParseTupleAndKeywords` now supports non-ASCII keyword
|
||||
parameter names.
|
||||
(Contributed by Serhiy Storchaka in :gh:`110815`.)
|
||||
* :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:`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`.)
|
||||
* :c:func:`!PyObject_AsCharBuffer`, :c:func:`!PyObject_AsReadBuffer`:
|
||||
Use :c:func:`PyObject_GetBuffer` and :c:func:`PyBuffer_Release` instead:
|
||||
|
||||
* Add :c:func:`PySys_Audit` and :c:func:`PySys_AuditTuple` functions to the
|
||||
limited C API.
|
||||
(Contributed by Victor Stinner in :gh:`85283`.)
|
||||
.. code-block:: c
|
||||
|
||||
* 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`.)
|
||||
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: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`.)
|
||||
* :c:func:`!PyObject_AsWriteBuffer`:
|
||||
Use :c:func:`PyObject_GetBuffer` and :c:func:`PyBuffer_Release` instead:
|
||||
|
||||
* 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`.)
|
||||
.. code-block:: c
|
||||
|
||||
* Add :c:func:`Py_HashPointer` function to hash a pointer.
|
||||
(Contributed by Victor Stinner in :gh:`111545`.)
|
||||
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);
|
||||
|
||||
* Add :c:func:`PyObject_GenericHash` function that implements the default
|
||||
hashing function of a Python object.
|
||||
(Contributed by Serhiy Storchaka in :gh:`113024`.)
|
||||
(Contributed by Inada Naoki in :gh:`85275`.)
|
||||
|
||||
* Add PyTime C API:
|
||||
* Remove various functions deprecated in Python 3.9:
|
||||
|
||||
* :c:type:`PyTime_t` type.
|
||||
* :c:var:`PyTime_MIN` and :c:var:`PyTime_MAX` constants.
|
||||
* Add functions:
|
||||
* :c:func:`!PyEval_CallObject`, :c:func:`!PyEval_CallObjectWithKeywords`:
|
||||
Use :c:func:`PyObject_CallNoArgs` or :c:func:`PyObject_Call` instead.
|
||||
|
||||
* :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`.
|
||||
.. warning::
|
||||
|
||||
(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:`PyLong_FromUnsignedNativeBytes` functions to simplify converting
|
||||
between native integer types and Python :class:`int` objects.
|
||||
(Contributed by Steve Dower in :gh:`111140`.)
|
||||
* :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.
|
||||
|
||||
* 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`.)
|
||||
(Contributed by Victor Stinner in :gh:`105107`.)
|
||||
|
||||
* 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 the following old functions to configure the Python initialization,
|
||||
deprecated in Python 3.11:
|
||||
|
||||
* 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`.)
|
||||
* :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.
|
||||
|
||||
* 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`.)
|
||||
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`.)
|
||||
|
||||
* Add :c:func:`PyType_GetModuleByDef` to the limited C API
|
||||
(Contributed by Victor Stinner in :gh:`116936`.)
|
||||
* 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:
|
||||
|
||||
* 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`.)
|
||||
* :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`.
|
||||
|
||||
* 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`.)
|
||||
(Contributed by Victor Stinner in :gh:`105182`.)
|
||||
|
||||
* 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`.)
|
||||
* 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`.)
|
||||
|
||||
* Add C API functions for generating :pep:`669` monitoring events.
|
||||
(Contributed by Irit Katriel in :gh:`111997`).
|
||||
* 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
|
||||
=============
|
||||
|
|
@ -2295,7 +2565,7 @@ Changes in the Python API
|
|||
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`.)
|
||||
|
||||
|
|
@ -2347,22 +2617,22 @@ Changes in the C API
|
|||
--------------------
|
||||
|
||||
* ``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`.)
|
||||
|
|
@ -2443,175 +2713,6 @@ Changes in the C API
|
|||
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
|
||||
=======================
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue