PyHash API

See also thePyTypeObject.tp_hash member andHashing of numeric types.

typePy_hash_t

Hash value type: signed integer.

Added in version 3.2.

typePy_uhash_t

Hash value type: unsigned integer.

Added in version 3.2.

Py_HASH_ALGORITHM

A numerical value indicating the algorithm for hashing ofstr,bytes, andmemoryview.

The algorithm name is exposed bysys.hash_info.algorithm.

Added in version 3.4.

Py_HASH_FNV
Py_HASH_SIPHASH24
Py_HASH_SIPHASH13

Numerical values to compare toPy_HASH_ALGORITHM to determinewhich algorithm is used for hashing. The hash algorithm can be configuredvia the configure--with-hash-algorithm option.

Added in version 3.4:AddPy_HASH_FNV andPy_HASH_SIPHASH24.

Added in version 3.11:AddPy_HASH_SIPHASH13.

Py_HASH_CUTOFF

Buffers of length in range[1,Py_HASH_CUTOFF) are hashed using DJBX33Ainstead of the algorithm described byPy_HASH_ALGORITHM.

  • APy_HASH_CUTOFF of 0 disables the optimization.

  • 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 becauseit is easier to create colliding strings. A cutoff of 7 on 64-bit platformsand 5 on 32-bit platforms should provide a decent safety margin.

This corresponds to thesys.hash_info.cutoff constant.

Added in version 3.4.

PyHASH_MODULUS

TheMersenne primeP=2**n-1,used for numeric hash scheme.

This corresponds to thesys.hash_info.modulus constant.

Added in version 3.13.

PyHASH_BITS

The exponentn ofP inPyHASH_MODULUS.

Added in version 3.13.

PyHASH_MULTIPLIER

Prime multiplier used in string and various other hashes.

Added in version 3.13.

PyHASH_INF

The hash value returned for a positive infinity.

This corresponds to thesys.hash_info.inf constant.

Added in version 3.13.

PyHASH_IMAG

The multiplier used for the imaginary part of a complex number.

This corresponds to thesys.hash_info.imag constant.

Added in version 3.13.

typePyHash_FuncDef

Hash function definition used byPyHash_GetFuncDef().

Py_hash_t(*consthash)(constvoid*,Py_ssize_t)

Hash function.

constchar*name

Hash function name (UTF-8 encoded string).

This corresponds to thesys.hash_info.algorithm constant.

constinthash_bits

Internal size of the hash value in bits.

This corresponds to thesys.hash_info.hash_bits constant.

constintseed_bits

Size of seed input in bits.

This corresponds to thesys.hash_info.seed_bits constant.

Added in version 3.4.

PyHash_FuncDef*PyHash_GetFuncDef(void)

Get the hash function definition.

See also

PEP 456 “Secure and interchangeable hash algorithm”.

Added in version 3.4.

Py_hash_tPy_HashPointer(constvoid*ptr)

Hash a pointer value: process the pointer value as an integer (cast it touintptr_t internally). The pointer is not dereferenced.

The function cannot fail: it cannot return-1.

Added in version 3.13.

Py_hash_tPy_HashBuffer(constvoid*ptr,Py_ssize_tlen)

Compute and return the hash value of a buffer oflen bytesstarting at addressptr. The hash is guaranteed to match that ofbytes,memoryview, and other built-in objectsthat implement thebuffer protocol.

Use this function to implement hashing for immutable objects whosetp_richcompare function compares to anotherobject’s buffer.

len must be greater than or equal to0.

This function always succeeds.

Added in version 3.14.

Py_hash_tPyObject_GenericHash(PyObject*obj)

Generic hashing function that is meant to be put into a typeobject’stp_hash slot.Its result only depends on the object’s identity.

CPython implementation detail: In CPython, it is equivalent toPy_HashPointer().

Added in version 3.13.