Stowage/cpython
2
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-12-31 04:23:37 +00:00
Code Issues Projects Releases Packages Wiki Activity

gh-115754: Add Py_GetConstant() function (#116883)

Browse source 
Add Py_GetConstant() and Py_GetConstantBorrowed() functions.

In the limited C API version 3.13, getting Py_None, Py_False,
Py_True, Py_Ellipsis and Py_NotImplemented singletons is now
implemented as function calls at the stable ABI level to hide
implementation details. Getting these constants still return borrowed
references.

Add _testlimitedcapi/object.c and test_capi/test_object.py to test
Py_GetConstant() and Py_GetConstantBorrowed() functions.
This commit is contained in:
Victor Stinner 2024-03-21 17:07:00 +01:00 • committed by GitHub
parent 5a76d1be8e
commit 8bea6c411d
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
22 changed files with 312 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

49
Doc/c-api/object.rst
View file

@ -6,6 +6,55 @@ Object Protocol
===============
.. c:function:: PyObject* Py_GetConstant(unsigned int constant_id)
Get a :term:`strong reference` to a constant.
Set an exception and return ``NULL`` if *constant_id* is invalid.
*constant_id* must be one of these constant identifiers:
.. c:namespace:: NULL
======================================== ===== =========================
Constant Identifier Value Returned object
======================================== ===== =========================
.. c:macro:: Py_CONSTANT_NONE ``0`` :py:data:`None`
.. c:macro:: Py_CONSTANT_FALSE ``1`` :py:data:`False`
.. c:macro:: Py_CONSTANT_TRUE ``2`` :py:data:`True`
.. c:macro:: Py_CONSTANT_ELLIPSIS ``3`` :py:data:`Ellipsis`
.. c:macro:: Py_CONSTANT_NOT_IMPLEMENTED ``4`` :py:data:`NotImplemented`
.. c:macro:: Py_CONSTANT_ZERO ``5`` ``0``
.. c:macro:: Py_CONSTANT_ONE ``6`` ``1``
.. c:macro:: Py_CONSTANT_EMPTY_STR ``7`` ``''``
.. c:macro:: Py_CONSTANT_EMPTY_BYTES ``8`` ``b''``
.. c:macro:: Py_CONSTANT_EMPTY_TUPLE ``9`` ``()``
======================================== ===== =========================
Numeric values are only given for projects which cannot use the constant
identifiers.
.. versionadded:: 3.13
.. impl-detail::
In CPython, all of these constants are :term:`immortal`.
.. c:function:: PyObject* Py_GetConstantBorrowed(unsigned int constant_id)
Similar to :c:func:`Py_GetConstant`, but return a :term:`borrowed
reference`.
This function is primarily intended for backwards compatibility:
using :c:func:`Py_GetConstant` is recommended for new code.
The reference is borrowed from the interpreter, and is valid until the
interpreter finalization.
.. versionadded:: 3.13
.. c:var:: PyObject* Py_NotImplemented
The ``NotImplemented`` singleton, used to signal that an operation is

2
Doc/data/stable_abi.dat generated
View file

@ -838,6 +838,8 @@ function,Py_GenericAlias,3.9,,
var,Py_GenericAliasType,3.9,,
function,Py_GetBuildInfo,3.2,,
function,Py_GetCompiler,3.2,,
function,Py_GetConstant,3.13,,
function,Py_GetConstantBorrowed,3.13,,
function,Py_GetCopyright,3.2,,
function,Py_GetExecPrefix,3.2,,
function,Py_GetPath,3.2,,

5
Doc/whatsnew/3.13.rst
View file

@ -1731,6 +1731,11 @@ New Features
more information.
(Contributed by Victor Stinner in :gh:`111696`.)
* 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`.)
Porting to Python 3.13
----------------------