Consider restoring _PyHASH_INF/BITS/MODULUS/IMAG as public

[skirpichev]

This is used to implement CPython-like hashing of numeric types e.g. in Sage or in gmpy2. Actually, the same info is available via sys.hash_info, so I don't see reasons to hide this in Python.h.

See #106320 and #107026.

Linked PRs

• gh-111389: expose _PyHASH_INF/BITS/MODULUS/IMAG macros as public #111418
• gh-111389: Add PyHASH_MULTIPLIER constant #119214
• [3.13] gh-111389: Add PyHASH_MULTIPLIER constant (GH-119214) #119334
• gh-111389: replace deprecated occurrences of _PyHASH_* macros #141236

[sobolevn]

CC @vstinner

[vstinner]

Python 3.12 has 5 constants implemented as macros:

• _PyHASH_BITS
• _PyHASH_IMAG
• _PyHASH_INF
• _PyHASH_MODULUS
• _PyHASH_MULTIPLIER

Significant commits related to these constants:

• commit 985ecdc: new Include/pyhash.h header file
• commit 27cbcd6: in Include/pyport.h, use unsigned integer, replace Py_hash_t with Py_uhash_t
• commit 63e6c32: add _PyHASH_MULTIPLIER constant
• commit 8035bc5: add Py_uhash_t type, replace unsigned long with size_t
• commit dc787d2: add _PyHASH_BITS, _PyHASH_IMAG, _PyHASH_INF and _PyHASH_MODULUS constants

the same info is available via sys.hash_info, so I don't see reasons to hide this in Python.h.

Right, it makes sense to make them public. I'm not sure why it was private before.

We can keep them as macros, but maybe we should consider declaring them as variables (using with dlsym for example) to make them usable in programming languages and use cases which cannot use macros.

[vstinner]

We can keep them as macros, but maybe we should consider declaring them as variables (using with dlsym for example) to make them usable in programming languages and use cases which cannot use macros.

I created capi-workgroup/api-evolution#37 to discuss that.

[skirpichev]

@vstinner, I did a quick reversion in #111418

[vstinner]

Should we also add some functions like Py_HashPointer()?

[vstinner]

@skirpichev:

are you about documenting these macroses somewhere (I propose https://docs.python.org/3/library/sys.html#sys.hash_info, where we could mention them in descriptions for different fields) AND about renaming them too (add PyUnstable_ aliases)?

If constants are made public, yes, they must be documented.

I don't think that PyUnstable prefix is needed, these constants seem stable.

[skirpichev]

Should we also add some functions like Py_HashPointer()?

Maybe others (I don't know examples), but not this function. It's used currently in the gmpy2, but this could be replaced by PyBaseObject_Type.tp_hash. And this is a documented replacement:

cpython/Doc/library/stdtypes.rst

Lines 789 to 790 in 63acf78

	if math.isnan(x):
	return object.__hash__(x)

If constants are made public, yes, they must be documented.

Ok, I'll go with suggested above sys.hash_info. Let me know if you have in mind a better place to put the docs.

these constants seem stable

Yep. But can be removed in any minor release, as _PyHASH_NAN.

[vstinner]

https://docs.python.org/dev/library/sys.html is the Python API.

For the C API, I would prefer to create a new page under https://docs.python.org/dev/c-api/ category.