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.
HashManagerBuilder provides a fluent, chainable interface for constructing a HashManager instance. Instead of instantiating hashers manually, you declare the algorithms and their parameters step by step, then call build() to receive a fully configured HashManager. The builder is especially useful when you need fine-grained, per-algorithm parameter control that from_algorithms cannot express in a single call.
You can obtain a builder either by importing HashManagerBuilder directly or by calling HashManager.builder():
from hash_forge import HashManagerBuilder
builder = HashManagerBuilder()
from hash_forge import HashManager
builder = HashManager.builder()
HashManager.builder() is a convenience alias.
Methods
with_algorithm
def with_algorithm(self, algorithm: AlgorithmType, **kwargs: Any) -> HashManagerBuilder
HasherFactory, passing any supplied keyword arguments directly to the hasher’s constructor. The hasher is appended to the internal list in the order this method is called.
The algorithm identifier to add, e.g. "argon2", "pbkdf2_sha256". See AlgorithmType for all valid values. Algorithm-specific constructor parameters. For example, time_cost and memory_cost for Argon2, rounds for bcrypt, or iterations for PBKDF2.
HashManagerBuilder — the same builder instance for chaining.
builder.with_algorithm("argon2", time_cost=4, memory_cost=131072)
with_hasher
def with_hasher(self, hasher: PHasher) -> HashManagerBuilder
PHasher protocol. Use this when you have a custom hasher implementation or need to reuse a hasher created elsewhere.
A fully initialised hasher instance. Its algorithm attribute is used as the registration key.
HashManagerBuilder — the same builder instance for chaining.
from hash_forge.hashers.pbkdf2_hasher import PBKDF2Sha256Hasher
custom_hasher = PBKDF2Sha256Hasher(iterations=300_000)
builder.with_hasher(custom_hasher)
with_preferred
def with_preferred(self, algorithm: AlgorithmType) -> HashManagerBuilder
with_algorithm or with_hasher is used as the preferred hasher automatically.
The algorithm identifier to promote to preferred. This algorithm must have already been added to the builder.
HashManagerBuilder — the same builder instance for chaining.
Calling with_preferred with an algorithm that has not been added first causes build() to raise ValueError: Preferred algorithm '...' was not added to the builder.
builder.with_preferred("argon2")
build
def build(self) -> HashManager
HashManager instance. If with_preferred was called, the designated hasher is moved to the front of the internal list so it becomes the preferred hasher.
Returns: HashManager — a fully configured instance ready for use.
Raises:
| Exception | Condition |
|---|
ValueError | No hashers were added before calling build(). |
ValueError | The algorithm passed to with_preferred was not added to the builder. |
Full Example
from hash_forge import HashManager
manager = (
HashManager.builder()
.with_algorithm("argon2", time_cost=4, memory_cost=131_072, parallelism=2)
.with_algorithm("pbkdf2_sha256", iterations=300_000, salt_length=32)
.with_algorithm("bcrypt", rounds=13)
.with_preferred("argon2")
.build()
)
# 'argon2' is the preferred hasher; pbkdf2_sha256 and bcrypt are
# available for verifying and migrating legacy hashes.
hashed = manager.hash("correct-horse-battery-staple")
print(manager.list_algorithms())
# ['argon2', 'pbkdf2_sha256', 'bcrypt']
Prefer with_preferred explicitly over relying on insertion order whenever the preferred algorithm changes between environments — it makes the intention clear and prevents subtle bugs during refactors.
Using with_hasher for Custom Implementations
from hash_forge import HashManager
from hash_forge.hashers.argon2_hasher import Argon2Hasher
# Construct a custom Argon2 hasher outside the builder
argon2 = Argon2Hasher(time_cost=5, memory_cost=262_144, parallelism=4, hash_len=64)
manager = (
HashManager.builder()
.with_hasher(argon2)
.with_algorithm("pbkdf2_sha256", iterations=200_000)
.build()
)
