About the function name Py_GetConstantRef(): sometimes documentation refer to them as "constants", sometimes as "singletons":

C API:

• Py_None "object": https://docs.python.org/dev/c-api/none.html
• Py_False and Py_True "object": https://docs.python.org/dev/c-api/bool.html
• Py_NotImplemented singleton: https://docs.python.org/dev/c-api/object.html
• (Py_Ellipsis is not documented)

Python API:

• Builtin-in constants: https://docs.python.org/dev/library/constants.html "A small number of constants live in the built-in namespace."

In PyPy, are these constants guaranteed to be unique singletons? I added Py_IsNone() for PyPy and HPy.

@cfbolz wrote:

Just chiming in to say that for PyPy this API would be extremely useful, because PyPy's "is" is not implementable with a pointer comparison on the C level (due to unboxing we need to compare integers, floats, etc by value). Right now, C extension code that compares pointers is subtly broken and cannot be fixed by us.

To be more friendly with other Python implementations which will implement these functions, I would prefer to avoid being specific about "singletons" and stick to "constant" name.

See also the discussion in 2020 about per-interpreter singletons: #83692 At the end, it was decided to go with PEP 683 Immortal objects.

Thanks for trying it out!

I only have two comments about the naming. I'd rather GetConstantRef be the shorter/easier name, so that people are encouraged to get the sensible behaviour instead of borrowed references (we could make the current GetConstant into a _Py function to further discourage using it?).

I also think that we need an extra part to the enum names - Py_NONE_CONSTANT or Py_NONE_INDEX or something like that. Otherwise, I will accidentally use Py_NONE instead of Py_None at some point, and it will be embarrassing 😆

I'd rather GetConstantRef be the shorter/easier name, so that people are encouraged to get the sensible behaviour instead of borrowed references

Do you have a name to suggest? In practice, you can just use Py_None and it calls Py_GetConstant(Py_NONE) for you. It should be an uncommon operation to call it directly. And you can write code in a way to only call it once.

(we could make the current GetConstant into a _Py function to further discourage using it?).

Currently, Py_None, Py_True, etc. are borrowed references. For backward compatibility, I would prefer to keep a public function replacing them. Moreover, it looks easy to upgrade code from PyConstant() to PyConstantRef(), since you just have to add Ref suffix.

I also think that we need an extra part to the enum names - Py_NONE_CONSTANT or Py_NONE_INDEX or something like that. Otherwise, I will accidentally use Py_NONE instead of Py_None at some point, and it will be embarrassing 😆

Py_GetConstantRef(Py_NONE_CONSTANT) sounds redundant: "constant" is written twice. I'm fine with Py_GetConstantRef(Py_NONE_IDX) and Py_GetConstantRef(Py_NONE_CST).

Py_NONE_IDX is good. As you mentioned first, we're not expecting people to have to type this themselves.

As for the function naming, I think I'd be happy with Py_GetConstant returning a strong reference and Py_GetConstantBorrowed returning a borrowed reference (or _Py_GetConstantBorrowed). If we have another word we already use instead of "borrowed" then that would be fine too.

Languages other than C are going to have to use this function, as they can't use our macros. And I want them to choose the "right" function (strong reference) because it's obvious.

I updated my PR:

• Add _Py_GetConstant_Init(): initialize the array at once at startup
• Rename Py_GetConstantRef() to Py_GetConstant().
• Rename Py_GetConstant() to Py_GetConstantBorrowed() -- that name is quite long, but I suppose that the goal is also to discourage users to use borrowed references :-)
• Rename constant identifiers, add _IDX suffix. Example: Py_NONE becomes Py_NONE_IDX.

At the end, we get: PyObject *zero = Py_GetConstant(Py_ZERO_IDX).

I'm not sure that zero index is the best name. Maybe PyObject *zero = Py_GetConstant(Py_ZERO_CST) would be better? Use _CST suffix: get the "zero constant".

Please don't force-push, it makes reviewing hard.

Oh. I'm used to use git rebase to rewrite the commit message, since the API changed.

That's more productive for you, but more work for a reviewer. :-(

Maybe PyObject *zero = Py_GetConstant(Py_ZERO_CST) would be better? Use _CST suffix: get the "zero constant".

Or Py_CONSTANT_ZERO? Or Py_GETCONSTANT_ZERO to fully match the API name? Just CST makes me think of US central time, but having it before the specific constant might better suggest that it's not the constant, but an identifier for the constant.

I'm fine with Py_GetConstant(Py_CONSTANT_ZERO).

I updated the PR:

• Complete the documentation to specify where borrowed references come from (I applied Petr's suggestion). I also mentioned that constants are immortal.
• Rename Py_NONE_IDX to Py_CONSTANT_NONE
• Remove the What's New entry about Py_None becoming a function call at the ABI level, but keep it in the Changelog.

Conflicting files
Modules/Setup.stdlib.in
Modules/_testlimitedcapi.c
Modules/_testlimitedcapi/parts.h
PCbuild/_testlimitedcapi.vcxproj
PCbuild/_testlimitedcapi.vcxproj.filters

I rebased the PR to fix merge conflicts.

Thanks for mentioning immortality as an implementation detail. If it was a guarantee of the API, there'd be no difference between Py_GetConstant and Py_GetConstantBorrowed :)

I updated the PR to address @zooba's review.

About the doc, I chose to use a table to give constant values:

@zooba @encukou @gvanrossum: Would you mind to review the updated PR?

@encukou: I applied your suggestions, please review the updated PR.

The documentation has strong requirement on the function argument:

This is stable ABI; future versions of Python might add new values.

But yes, PyErr_BadInternalCall is appropriate.

Ok, thanks for reviews. Now that the PR is approved, I rebased it to solve the merge conflicts, and I enabled auto-merged.

I added the two functions to pythoncapi-commit: python/pythoncapi-compat@b16ff9a