document Py_HASH_* macros

Author: picnixz

Doc/c-api/hash.rst

@@ -17,15 +17,66 @@ See also the :c:member:`PyTypeObject.tp_hash` member and :ref:`numeric-hash`.
 
    .. 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`.
+
+.. c:macro:: Py_HASH_FNV
+             Py_HASH_SIPHASH13
+             Py_HASH_SIPHASH24
+
+   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.
+
+.. c:macro:: Py_HASH_EXTERNAL
+
+   If :c:macro:`Py_HASH_ALGORITHM` is set to that value, this means that
+   the hash function is externally implemented, that is, embedders must
+   provide a definition for ``extern PyHash_FuncDef PyHash_Func`` when
+   building Python:
+
+   .. code-block:: c
+
+      static Py_hash_t
+      my_siphash24(const void *src, Py_ssize_t src_sz) { ... }
+
+      PyHash_FuncDef PyHash_Func = {
+         .hash = my_siphash24,
+         .name = "my_siphash24",
+         .hash_bits = 64,
+         .seed_bits = 128,
+      };
+
+   .. availability:: Unix
+
+.. 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 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.
+
 .. 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
 
@@ -38,12 +89,14 @@ See also the :c:member:`PyTypeObject.tp_hash` member and :ref:`numeric-hash`.
 .. 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