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.

Hash Forge uses a small, focused exception hierarchy rooted at HashForgeError. All library-specific errors are subclasses of this base, making it easy to write broad except HashForgeError clauses when you want to handle any Hash Forge error generically, or to catch individual subclasses when you need fine-grained control. All exceptions are defined in hash_forge.exceptions and re-exported from the top-level hash_forge package.

​
Import

from hash_forge import (
    HashForgeError,
    InvalidHasherError,
    InvalidHashFormatError,
    UnsupportedAlgorithmError,
    HasherNotFoundError,
)

​
Exception hierarchy

Exception
└── HashForgeError
    ├── InvalidHasherError
    ├── InvalidHashFormatError
    ├── UnsupportedAlgorithmError
    └── HasherNotFoundError

​
HashForgeError

Base exception for all Hash Forge errors. Inherits directly from Python’s built-in Exception. Catch HashForgeError when you want a single handler that covers every error the library can raise — for example in a top-level error handler or when wrapping Hash Forge calls in a service boundary. 
from hash_forge import HashForgeError

try:
    hashed = hasher.hash(password)
except HashForgeError as exc:
    # Handles any Hash Forge error
    logger.error("Hashing failed: %s", exc)
    raise

​
InvalidHasherError

Raised when hasher configuration is invalid. This exception is raised at construction time when the caller passes parameters that violate enforced security minimums (e.g., too few PBKDF2 iterations, bcrypt rounds below 12, scrypt work_factor not a power of two). It is also raised by HashManager when it is instantiated with an empty list of hashers, and by WhirlpoolHasher.hash() when allow_legacy_hashing is False. 
from hash_forge import InvalidHasherError
from hash_forge.hashers import PBKDF2Sha256Hasher

try:
    # Minimum is 150,000 — this will raise
    hasher = PBKDF2Sha256Hasher(iterations=10_000)
except InvalidHasherError as exc:
    print(f"Configuration error: {exc}")
    # Configuration error: PBKDF2 iterations must be at least 150000

​
InvalidHashFormatError

Raised when a hash string has an invalid or unrecognised format. This exception signals that a string passed to a hashing operation (such as verify or needs_rehash) does not conform to the expected algorithm$... structure, or that the fields within the hash are malformed. Callers should treat this as a data integrity issue rather than a credentials mismatch. 
from hash_forge import InvalidHashFormatError
from hash_forge.hashers import PBKDF2Sha256Hasher

hasher = PBKDF2Sha256Hasher()

try:
    hasher.verify("password", "not_a_valid_hash")
except InvalidHashFormatError as exc:
    print(f"Malformed hash: {exc}")

​
UnsupportedAlgorithmError

Raised by HasherFactory.create when the requested algorithm is not registered. When you ask the factory to create a hasher for an algorithm name that has not been registered, UnsupportedAlgorithmError is raised. This can occur if a typo is made in the algorithm name, or if an optional hasher (e.g., argon2) has not been installed and registered. 
from hash_forge import UnsupportedAlgorithmError
from hash_forge.factory import HasherFactory

try:
    hasher = HasherFactory.create("unknown_algorithm")
except UnsupportedAlgorithmError as exc:
    print(f"Algorithm not available: {exc}")

​
HasherNotFoundError

Raised when no registered hasher can handle a given hash string. When HashManager (or similar dispatch logic) iterates over all registered hashers and none of them returns True from can_handle() for a given hash string, HasherNotFoundError is raised. This typically means the hash was produced by an algorithm that is not included in the current HashManager configuration. 
from hash_forge import HasherNotFoundError
from hash_forge.hashers import PBKDF2Sha256Hasher

try:
    # HashManager configured only with PBKDF2, but hash is from a different algorithm
    result = manager.verify("password", "argon2$some_argon2_hash")
except HasherNotFoundError as exc:
    print(f"No hasher available for this hash: {exc}")
Catch the base HashForgeError in top-level error handlers or integration tests to ensure you handle any new exceptions added in future library versions without modifying existing except clauses. Reserve catches of the specific subclasses for places where you need to distinguish between, say, a configuration error (InvalidHasherError) and a missing hasher (HasherNotFoundError) to take different recovery actions.

Build docs developers (and LLMs) love

Get started for freeTalk to us