Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Zozi96/hash-forge/llms.txt

Use this file to discover all available pages before exploring further.

HashForgeConfig is a dataclass that centralises algorithm tuning parameters — iteration counts, memory costs, round factors — in a single, serialisable object. Rather than scattering **kwargs across multiple from_algorithms calls, you load a config once (from environment variables, a JSON file, or a plain dict) and hand it to HashManager.from_config. This keeps production tuning outside your source code and makes parameter management reproducible across deployments. 
from hash_forge.config.config_loader import HashForgeConfig

​
Class Methods (Loaders)

​
from_env

@classmethod
def from_env(cls, prefix: str = "HASH_FORGE_") -> HashForgeConfig
Reads integer configuration values from environment variables. Each field maps to an environment variable formed by uppercasing the field name and prepending prefix. Unset variables fall back to the library defaults.
​
prefix
str
Prefix applied to all environment variable names. Defaults to "HASH_FORGE_".
Returns: HashForgeConfig Environment variable mapping:
FieldEnvironment Variable
pbkdf2_iterationsHASH_FORGE_PBKDF2_ITERATIONS
pbkdf2_salt_lengthHASH_FORGE_PBKDF2_SALT_LENGTH
bcrypt_roundsHASH_FORGE_BCRYPT_ROUNDS
argon2_time_costHASH_FORGE_ARGON2_TIME_COST
argon2_memory_costHASH_FORGE_ARGON2_MEMORY_COST
argon2_parallelismHASH_FORGE_ARGON2_PARALLELISM
argon2_hash_lenHASH_FORGE_ARGON2_HASH_LEN
scrypt_nHASH_FORGE_SCRYPT_N
scrypt_rHASH_FORGE_SCRYPT_R
scrypt_pHASH_FORGE_SCRYPT_P
export HASH_FORGE_PBKDF2_ITERATIONS=300000
export HASH_FORGE_BCRYPT_ROUNDS=14
export HASH_FORGE_ARGON2_TIME_COST=4

config = HashForgeConfig.from_env()

​
from_json

@classmethod
def from_json(cls, path: str | Path) -> HashForgeConfig
Loads configuration from a JSON file. Keys in the JSON object must match HashForgeConfig field names exactly.
​
path
str | Path
required
Path to the JSON configuration file.
Returns: HashForgeConfig 
{
  "pbkdf2_iterations": 300000,
  "pbkdf2_salt_length": 32,
  "bcrypt_rounds": 14,
  "argon2_time_cost": 4,
  "argon2_memory_cost": 131072,
  "argon2_parallelism": 2,
  "argon2_hash_len": 32,
  "scrypt_n": 65536,
  "scrypt_r": 8,
  "scrypt_p": 1,
  "custom": {"app_name": "MyApp"}
}

config = HashForgeConfig.from_json("config/hash_forge.json")

​
from_dict

@classmethod
def from_dict(cls, data: dict[str, Any]) -> HashForgeConfig
Constructs a HashForgeConfig directly from a Python dictionary. Useful for programmatic configuration in tests, factories, or application bootstrapping.
​
data
dict[str, Any]
required
A dictionary whose keys correspond to HashForgeConfig field names.
Returns: HashForgeConfig 
config = HashForgeConfig.from_dict({
    "pbkdf2_iterations": 200_000,
    "bcrypt_rounds": 13,
    "argon2_time_cost": 4,
})

​
Instance Methods (Exporters)

​
to_dict

def to_dict(self) -> dict[str, Any]
Serialises all configuration fields to a plain Python dictionary. Suitable for logging, persisting to a database, or passing to from_dict elsewhere. Returns: dict[str, Any] 
data = config.to_dict()
# {
#   'pbkdf2_iterations': 150000,
#   'pbkdf2_salt_length': 16,
#   'bcrypt_rounds': 12,
#   ...
# }

​
to_json

def to_json(self, path: str | Path) -> None
Writes the configuration to a JSON file at the given path, indented for readability. Creates or overwrites the file.
​
path
str | Path
required
Destination path for the JSON file.
config.to_json("config/hash_forge.json")

​
get_hasher_config

def get_hasher_config(self, algorithm: str) -> dict[str, Any]
Returns a dictionary of constructor keyword arguments for the specified algorithm, drawn from this config instance. This is the method HashManager.from_config calls internally for each algorithm.
​
algorithm
str
required
The algorithm name to look up, e.g. "pbkdf2_sha256", "argon2", "bcrypt", "scrypt".
Returns: dict[str, Any] — algorithm-specific kwargs ready to pass to a hasher constructor. Returns {} for algorithms not explicitly supported (e.g. blake2, sha3_256).
AlgorithmReturned keys
pbkdf2_sha256 / pbkdf2_sha1iterations, salt_length
bcrypt / bcrypt_sha256rounds
argon2time_cost, memory_cost, parallelism, hash_len
scryptwork_factor, block_size, parallelism
pbkdf2_opts = config.get_hasher_config("pbkdf2_sha256")
# {'iterations': 150000, 'salt_length': 16}

argon2_opts = config.get_hasher_config("argon2")
# {'time_cost': 3, 'memory_cost': 65536, 'parallelism': 1, 'hash_len': 32}

​
Dataclass Fields

All fields are mutable (not frozen) and carry sensible defaults matching Hash Forge’s built-in constants.
FieldTypeDefaultDescription
pbkdf2_iterationsint150_000PBKDF2 iteration count.
pbkdf2_salt_lengthint16PBKDF2 salt length in bytes.
bcrypt_roundsint12bcrypt cost factor (work rounds).
argon2_time_costint3Argon2 time cost (number of passes).
argon2_memory_costint65_536Argon2 memory cost in KiB.
argon2_parallelismint1Argon2 degree of parallelism.
argon2_hash_lenint32Argon2 output hash length in bytes.
scrypt_nint32_768Scrypt CPU/memory cost parameter (N).
scrypt_rint8Scrypt block size parameter (r).
scrypt_pint1Scrypt parallelization parameter (p).
customdict[str, Any]{}Arbitrary application-specific metadata.
The pbkdf2_iterations default of 150,000 is the NIST-recommended minimum as of 2023. For new deployments, consider setting a higher value (e.g. 300,000) or using PasswordHashPolicy.calibrate() to tune for your hardware.

​
Usage Example

Load configuration from environment variables and create a HashManager: 
import os
from hash_forge import HashManager
from hash_forge.config.config_loader import HashForgeConfig

# In your environment (or .env file):
# HASH_FORGE_ARGON2_TIME_COST=4
# HASH_FORGE_ARGON2_MEMORY_COST=131072
# HASH_FORGE_PBKDF2_ITERATIONS=300000

config = HashForgeConfig.from_env()

manager = HashManager.from_config(config, "argon2", "pbkdf2_sha256")

hashed = manager.hash("super-secret-password")
assert manager.verify("super-secret-password", hashed)
Round-trip a config through JSON for audit logging: 
config = HashForgeConfig.from_env()
config.to_json("/var/log/hash_forge_config.json")

# Later, reconstruct it:
restored = HashForgeConfig.from_json("/var/log/hash_forge_config.json")
assert restored.to_dict() == config.to_dict()

Build docs developers (and LLMs) love

Get started for freeTalk to us