hash

Documentation

Overview

Package hash holds the hashing primitives ported from cpython/Python/pyhash.c and cpython/Python/bootstrap_hash.c.

In v0.1 only the secret-bootstrap half is implemented. The full SipHash-1-3, FNV, and x86_aes hashers land with pyhash.c in v0.4.

Index

• Constants
• Variables
• func Buffer(src []byte) int64
• func BufferFNV(src []byte) int64
• func Double(v float64, nanFallback int64) int64
• func KeyedHash(key uint64, src []byte) uint64
• func Pointer(p unsafe.Pointer) int64
• func Reset()
• type Config
• type FuncDef
  • func GetFuncDef() FuncDef
• type SecretMode
  • func Init(cfg *Config) (SecretMode, error)

Constants

const HashBits = 61

HashBits mirrors PyHASH_BITS on 64-bit builds: the exponent of the Mersenne prime modulus used by numeric hashes.

CPython: Include/cpython/pyhash.h:L13 PyHASH_BITS

const HashImag int64 = hashMultiplier

HashImag mirrors PyHASH_IMAG, the multiplier for the imaginary part of complex numbers.

CPython: Include/cpython/pyhash.h:L20 PyHASH_IMAG

const HashInf int64 = 314159

HashInf mirrors PyHASH_INF, the hash of +inf.

CPython: Include/cpython/pyhash.h:L19 PyHASH_INF

const HashModulus = (uint64(1) << HashBits) - 1

HashModulus mirrors PyHASH_MODULUS = 2**HashBits - 1.

CPython: Include/cpython/pyhash.h:L18 PyHASH_MODULUS

const SecretSize = 24

SecretSize is the size of the hash secret. Matches sizeof(_Py_HashSecret_t) in CPython 3.14: 16 bytes of SipHash key followed by 8 bytes of FNV salt.

CPython: Include/internal/pycore_pyhash.h:L42 _Py_HashSecret_t

Variables

var ErrInvalidSeed = errors.New("hash: PYTHONHASHSEED must be \"random\", \"0\", or a non-negative integer in [1, 4294967295]")

ErrInvalidSeed is returned by Init when PYTHONHASHSEED is set to a value that is neither "random", "0", nor a non-negative 32-bit integer.

var Secret [SecretSize]byte

Secret is the per-process hash secret. v0.4 will read it from the hashers; until then, callers only seed it.

CPython: Include/internal/pycore_pyhash.h:L67 _Py_HashSecret

Functions

func Buffer

func Buffer(src []byte) int64

Buffer mirrors Py_HashBuffer. Returns the hash of src under the runtime hash secret, with the -1 sentinel remapped to -2.

CPython: Python/pyhash.c:L148 Py_HashBuffer

func BufferFNV

func BufferFNV(src []byte) int64

BufferFNV mirrors the FNV path of Py_HashBuffer for builds that select Py_HASH_FNV. Default builds use Buffer; this stays callable for parity tests.

CPython: Python/pyhash.c:L148 Py_HashBuffer (Py_HASH_FNV branch)

func Double

func Double(v float64, nanFallback int64) int64

Double mirrors _Py_HashDouble. Reduces v modulo HashModulus following the strategy documented in pyhash.c. NaNs return the pointer hash of inst (left to the caller); pass 0 for the NaN-fallback to receive 0 and let the type's tp_hash supply identity.

CPython: Python/pyhash.c:L86 _Py_HashDouble

func KeyedHash

func KeyedHash(key uint64, src []byte) uint64

KeyedHash mirrors _Py_KeyedHash. SipHash with the second key set to 0.

CPython: Python/pyhash.c:L471 _Py_KeyedHash

func Pointer

func Pointer(p unsafe.Pointer) int64

Pointer mirrors Py_HashPointer. Rotates the address right by 4 to dilute alignment patterns, then remaps the -1 sentinel.

CPython: Python/pyhash.c:L132 Py_HashPointer

func Reset

func Reset()

Reset clears the init guard. Tests use this to re-seed the secret; production code must not call it.

CPython: Python/bootstrap_hash.c:L593 _Py_HashRandomization_Fini (adapted from)

Types

type Config

type Config struct {
	UseHashSeed bool
	HashSeed    uint32
}

Config carries the subset of PyConfig that bootstrap_hash.c reads. The full PyConfig lands in v0.7 (initconfig).

CPython: Python/bootstrap_hash.c:L553 _Py_HashRandomization_Init (adapted from)

type FuncDef

type FuncDef struct {
	Name     string
	HashBits int
	SeedBits int
}

FuncDef mirrors PyHash_FuncDef. Describes the active hash algorithm.

CPython: Include/cpython/pyhash.h:L34 PyHash_FuncDef

func GetFuncDef

func GetFuncDef() FuncDef

GetFuncDef mirrors PyHash_GetFuncDef. The active algorithm is SipHash-1-3, matching CPython 3.14's default build.

CPython: Python/pyhash.c:L214 PyHash_GetFuncDef

type SecretMode

type SecretMode int

SecretMode classifies how Init resolved the hash secret.

CPython: Python/bootstrap_hash.c:L553 _Py_HashRandomization_Init (adapted from)

const (
	// SecretRandom means the secret was filled from OS entropy.
	SecretRandom SecretMode = iota
	// SecretZeroed means PYTHONHASHSEED=0 was honored: the secret is
	// all zero so hashes are deterministic for debugging.
	SecretZeroed
	// SecretSeeded means PYTHONHASHSEED was a positive integer and the
	// secret was filled deterministically via lcg_urandom.
	SecretSeeded
)

func Init

func Init(cfg *Config) (SecretMode, error)

Init seeds Secret. If cfg is nil, the PYTHONHASHSEED environment variable is consulted. Init is safe to call concurrently; only the first call performs work, matching CPython's _Py_HashSecret_Initialized guard.

CPython: Python/bootstrap_hash.c:L553 _Py_HashRandomization_Init