https://github.com/python/cpython/commit/3989e12d39bfe2587e5ba80873c37e0c2d449088
commit: 3989e12d39bfe2587e5ba80873c37e0c2d449088
branch: main
author: Bénédikt Tran <[email protected]>
committer: picnixz <[email protected]>
date: 2025-11-07T19:25:32+01:00
summary:
gh-141004: Document `Py_HASH_*` macros (#141205)
files:
M Doc/c-api/hash.rst
diff --git a/Doc/c-api/hash.rst b/Doc/c-api/hash.rst
index b5fe93573a1456..e74f5b4d18ebe1 100644
--- a/Doc/c-api/hash.rst
+++ b/Doc/c-api/hash.rst
@@ -11,42 +11,94 @@ See also the :c:member:`PyTypeObject.tp_hash` member and
:ref:`numeric-hash`.
.. versionadded:: 3.2
+
.. c:type:: Py_uhash_t
Hash value type: unsigned integer.
.. versionadded:: 3.2
+
+.. c:macro:: Py_HASH_ALGORITHM
+
+ A numerical value indicating the algorithm for hashing of :class:`str`,
+ :class:`bytes`, and :class:`memoryview`.
+
+ The algorithm name is exposed by :data:`sys.hash_info.algorithm`.
+
+ .. versionadded:: 3.4
+
+
+.. c:macro:: Py_HASH_FNV
+ Py_HASH_SIPHASH24
+ Py_HASH_SIPHASH13
+
+ Numerical values to compare to :c:macro:`Py_HASH_ALGORITHM` to determine
+ which algorithm is used for hashing. The hash algorithm can be configured
+ via the configure :option:`--with-hash-algorithm` option.
+
+ .. versionadded:: 3.4
+ Add :c:macro:`!Py_HASH_FNV` and :c:macro:`!Py_HASH_SIPHASH24`.
+
+ .. versionadded:: 3.13
+ Add :c:macro:`!Py_HASH_SIPHASH13`.
+
+
+.. c:macro:: Py_HASH_CUTOFF
+
+ Buffers of length in range ``[1, Py_HASH_CUTOFF)`` are hashed using DJBX33A
+ instead of the algorithm described by :c:macro:`Py_HASH_ALGORITHM`.
+
+ - A :c:macro:`!Py_HASH_CUTOFF` of 0 disables the optimization.
+ - :c:macro:`!Py_HASH_CUTOFF` must be non-negative and less or equal than 7.
+
+ 32-bit platforms should use a cutoff smaller than 64-bit platforms because
+ it is easier to create colliding strings. A cutoff of 7 on 64-bit platforms
+ and 5 on 32-bit platforms should provide a decent safety margin.
+
+ .. versionadded:: 3.4
+
+
.. c:macro:: PyHASH_MODULUS
- The `Mersenne prime <https://en.wikipedia.org/wiki/Mersenne_prime>`_ ``P =
2**n -1``, used for numeric hash scheme.
+ The `Mersenne prime <https://en.wikipedia.org/wiki/Mersenne_prime>`_ ``P =
2**n -1``,
+ used for numeric hash scheme.
+ This corresponds to the :data:`sys.hash_info.modulus` constant.
.. versionadded:: 3.13
+
.. c:macro:: PyHASH_BITS
The exponent ``n`` of ``P`` in :c:macro:`PyHASH_MODULUS`.
+ This corresponds to the :data:`sys.hash_info.hash_bits` constant.
.. versionadded:: 3.13
+
.. c:macro:: PyHASH_MULTIPLIER
Prime multiplier used in string and various other hashes.
.. versionadded:: 3.13
+
.. c:macro:: PyHASH_INF
The hash value returned for a positive infinity.
+ This corresponds to the :data:`sys.hash_info.inf` constant.
.. versionadded:: 3.13
+
.. c:macro:: PyHASH_IMAG
The multiplier used for the imaginary part of a complex number.
+ This corresponds to the :data:`sys.hash_info.imag` constant.
.. versionadded:: 3.13
+
.. c:type:: PyHash_FuncDef
Hash function definition used by :c:func:`PyHash_GetFuncDef`.
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]
