# Hash Forge
[](https://pypi.org/project/hash-forge/)  [](https://opensource.org/licenses/MIT) [](https://pypi.org/project/hash-forge/) [](https://pepy.tech/project/hash-forge) [](https://github.com/Zozi96/hash-forge/issues)  [](https://github.com/psf/black) [](https://github.com/Zozi96/hash-forge/issues)
**Hash Forge** is a lightweight Python library designed to simplify the process of hashing and verifying data using a variety of secure hashing algorithms.
## Overview
Hash Forge is a flexible and secure hash management tool that supports multiple hashing algorithms. This tool allows you to hash and verify data using popular hash algorithms, making it easy to integrate into projects where password hashing or data integrity is essential.
## Features
- **Multiple Hashing Algorithms**: Supports bcrypt, Scrypt, Argon2, Blake2, Blake3, PBKDF2, Whirlpool and RIPEMD-160.
- **Hashing and Verification**: Easily hash strings and verify their integrity.
- **Rehash Detection**: Automatically detects if a hash needs to be rehashed based on outdated parameters or algorithms.
- **Type-Safe API**: Full TypeScript-like type hints with `AlgorithmType` for better IDE support.
- **Factory Pattern**: Create hashers dynamically by algorithm name.
- **Performance Optimized**: O(1) hasher lookup with internal caching.
- **Security Focused**: Enforces minimum security parameters and uses cryptographically secure random generation.
- **Flexible Integration**: Extendible to add new hashing algorithms as needed.
## Installation
```bash
pip install hash-forge
```
### Optional Dependencies
Hash Forge provides optional dependencies for specific hashing algorithms. To install these, use:
- **bcrypt** support:
```bash
pip install "hash-forge[bcrypt]"
```
- **Argon2** support:
```bash
pip install "hash-forge[argon2]"
```
- **Whirlpool and RIPEMD-160** support:
```bash
pip install "hash-forge[crypto]"
```
- **Blake3** support:
```bash
pip install "hash-forge[blake3]"
```
## Usage
### Basic Example
```python
from hash_forge import HashManager, AlgorithmType
from hash_forge.hashers import PBKDF2Sha256Hasher
# Initialize HashManager with PBKDF2Hasher
hash_manager = HashManager(PBKDF2Sha256Hasher())
# Hash a string
hashed_value = hash_manager.hash("my_secure_password")
# Verify the string against the hashed value
is_valid = hash_manager.verify("my_secure_password", hashed_value)
print(is_valid) # Outputs: True
# Check if the hash needs rehashing
needs_rehash = hash_manager.needs_rehash(hashed_value)
print(needs_rehash) # Outputs: False
```
### Quick Hash (New in v2.1.0)
For simple hashing without creating a HashManager instance:
```python
from hash_forge import HashManager, AlgorithmType
# Quick hash with default algorithm (PBKDF2-SHA256)
hashed = HashManager.quick_hash("my_password")
# Quick hash with specific algorithm (with IDE autocomplete!)
algorithm: AlgorithmType = "argon2"
hashed = HashManager.quick_hash("my_password", algorithm=algorithm)
# Quick hash with algorithm-specific parameters
hashed = HashManager.quick_hash("my_password", algorithm="pbkdf2_sha256", iterations=200_000)
hashed = HashManager.quick_hash("my_password", algorithm="bcrypt", rounds=14)
hashed = HashManager.quick_hash("my_password", algorithm="argon2", time_cost=4)
```
### Factory Pattern (New in v2.1.0)
Create HashManager instances using algorithm names:
```python
from hash_forge import HashManager, AlgorithmType
# Create HashManager from algorithm names
hash_manager = HashManager.from_algorithms("pbkdf2_sha256", "argon2", "bcrypt")
# With type safety
algorithms: list[AlgorithmType] = ["pbkdf2_sha256", "bcrypt_sha256"]
hash_manager = HashManager.from_algorithms(*algorithms)
# Note: from_algorithms() creates hashers with default parameters
# For custom parameters, create hashers individually
hash_manager = HashManager.from_algorithms("pbkdf2_sha256", "bcrypt", "argon2")
```
> **Note:** The first hasher provided during initialization of `HashManager` will be the **preferred hasher** used for hashing operations, though any available hasher can be used for verification.
### Available Algorithms
Currently supported algorithms with their `AlgorithmType` identifiers:
| Algorithm | Identifier | Security Level | Notes |
|-----------|------------|----------------|-------|
| **PBKDF2-SHA256** | `"pbkdf2_sha256"` | High | Default, 150K iterations minimum |
| **PBKDF2-SHA1** | `"pbkdf2_sha1"` | Medium | Legacy support |
| **bcrypt** | `"bcrypt"` | High | 12 rounds minimum |
| **bcrypt-SHA256** | `"bcrypt_sha256"` | High | With SHA256 pre-hashing |
| **Argon2** | `"argon2"` | Very High | Memory-hard function |
| **Scrypt** | `"scrypt"` | High | Memory-hard function |
| **Blake2** | `"blake2"` | High | Fast cryptographic hash |
| **Blake3** | `"blake3"` | Very High | Latest Blake variant |
| **Whirlpool** | `"whirlpool"` | Medium | 512-bit hash |
| **RIPEMD-160** | `"ripemd160"` | Medium | 160-bit hash |
### Algorithm-Specific Parameters
Different algorithms support different parameters. Use `quick_hash()` for algorithm-specific customization:
```python
from hash_forge import HashManager
# PBKDF2 algorithms
HashManager.quick_hash("password", algorithm="pbkdf2_sha256", iterations=200_000, salt_length=16)
HashManager.quick_hash("password", algorithm="pbkdf2_sha1", iterations=150_000)
# BCrypt algorithms
HashManager.quick_hash("password", algorithm="bcrypt", rounds=14)
HashManager.quick_hash("password", algorithm="bcrypt_sha256", rounds=12)
# Argon2
HashManager.quick_hash("password", algorithm="argon2", time_cost=4, memory_cost=65536, parallelism=1)
# Scrypt
HashManager.quick_hash("password", algorithm="scrypt", n=32768, r=8, p=1)
# Blake2 (with optional key)
HashManager.quick_hash("password", algorithm="blake2", key="secret_key")
# Blake3 (with optional key)
HashManager.quick_hash("password", algorithm="blake3", key="secret_key")
# Other algorithms (use defaults)
HashManager.quick_hash("password", algorithm="whirlpool")
HashManager.quick_hash("password", algorithm="ripemd160")
```
### Traditional Initialization
For complete control over parameters, initialize `HashManager` with individual hasher instances:
```python
from hash_forge import HashManager
from hash_forge.hashers import (
Argon2Hasher,
BCryptSha256Hasher,
Blake2Hasher,
PBKDF2Sha256Hasher,
Ripemd160Hasher,
ScryptHasher,
WhirlpoolHasher,
Blake3Hasher
)
hash_manager = HashManager(
PBKDF2Sha256Hasher(iterations=200_000), # Higher iterations
BCryptSha256Hasher(rounds=14), # Higher rounds
Argon2Hasher(time_cost=4), # Custom parameters
ScryptHasher(),
Ripemd160Hasher(),
Blake2Hasher('MySecretKey'),
WhirlpoolHasher(),
Blake3Hasher()
)
```
### Verifying a Hash
Use the `verify` method to compare a string with its hashed counterpart:
```python
is_valid = hash_manager.verify("my_secure_password", hashed_value)
```
### Checking for Rehashing
You can check if a hash needs to be rehashed (e.g., if the hashing algorithm parameters are outdated):
```python
needs_rehash = hash_manager.needs_rehash(hashed_value)
```
## What's New in v2.1.0
### 🚀 Performance Improvements
- **O(1) Hasher Lookup**: Internal hasher mapping for faster algorithm detection
- **Optimized Memory Usage**: Reduced object creation overhead
### 🛠️ Developer Experience
- **Type Safety**: `AlgorithmType` literal for IDE autocomplete and error detection
- **Factory Pattern**: Create hashers by algorithm name with `HasherFactory`
- **Convenience Methods**: `quick_hash()` and `from_algorithms()` for simpler usage
### 🔐 Security Enhancements
- **Parameter Validation**: Enforces minimum security thresholds (150K PBKDF2 iterations, 12 BCrypt rounds)
- **Custom Exceptions**: More specific error types (`InvalidHasherError`, `UnsupportedAlgorithmError`)
- **Centralized Configuration**: Security defaults in one place
### 🧪 Better Testing
- **Enhanced Test Suite**: 81 tests covering new functionality
- **Type Checking Tests**: Validates `AlgorithmType` usage
- **Configuration Validation**: Tests security parameter enforcement
### 📚 API Improvements
**Before v2.1.0:**
```python
# Manual hasher imports and creation
from hash_forge.hashers.pbkdf2_hasher import PBKDF2Sha256Hasher
hasher = PBKDF2Sha256Hasher(iterations=150000)
hash_manager = HashManager(hasher)
```
**v2.1.0+:**
```python
# Simplified with factory pattern and type safety
from hash_forge import HashManager, AlgorithmType
algorithm: AlgorithmType = "pbkdf2_sha256" # IDE autocomplete!
hash_manager = HashManager.from_algorithms(algorithm)
# or with custom parameters
hashed = HashManager.quick_hash("password", algorithm=algorithm, iterations=200_000)
```
## Contributing
Contributions are welcome! Please feel free to submit issues or pull requests to help improve the project.
## License
This project is licensed under the MIT License.
Raw data
{
"_id": null,
"home_page": null,
"name": "hash-forge",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "RIPEMD-160, Whirlpool, argon2, bcrypt, blake2, blake3, hash, pbkdf2, scrypt, security",
"author": null,
"author_email": "Zozi <zozi.fer96@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/17/59/4f270b08870e1a541889e7ad0f96a3dbbf22193a62cb10e4216e3ab30aba/hash_forge-2.1.0.tar.gz",
"platform": null,
"description": "# Hash Forge\n\n[](https://pypi.org/project/hash-forge/)  [](https://opensource.org/licenses/MIT) [](https://pypi.org/project/hash-forge/) [](https://pepy.tech/project/hash-forge) [](https://github.com/Zozi96/hash-forge/issues)  [](https://github.com/psf/black) [](https://github.com/Zozi96/hash-forge/issues)\n\n**Hash Forge** is a lightweight Python library designed to simplify the process of hashing and verifying data using a variety of secure hashing algorithms.\n\n## Overview\n\nHash Forge is a flexible and secure hash management tool that supports multiple hashing algorithms. This tool allows you to hash and verify data using popular hash algorithms, making it easy to integrate into projects where password hashing or data integrity is essential.\n\n## Features\n\n- **Multiple Hashing Algorithms**: Supports bcrypt, Scrypt, Argon2, Blake2, Blake3, PBKDF2, Whirlpool and RIPEMD-160.\n- **Hashing and Verification**: Easily hash strings and verify their integrity.\n- **Rehash Detection**: Automatically detects if a hash needs to be rehashed based on outdated parameters or algorithms.\n- **Type-Safe API**: Full TypeScript-like type hints with `AlgorithmType` for better IDE support.\n- **Factory Pattern**: Create hashers dynamically by algorithm name.\n- **Performance Optimized**: O(1) hasher lookup with internal caching.\n- **Security Focused**: Enforces minimum security parameters and uses cryptographically secure random generation.\n- **Flexible Integration**: Extendible to add new hashing algorithms as needed.\n\n## Installation\n\n```bash\npip install hash-forge\n```\n\n### Optional Dependencies\n\nHash Forge provides optional dependencies for specific hashing algorithms. To install these, use:\n\n- **bcrypt** support:\n\n ```bash\n pip install \"hash-forge[bcrypt]\"\n ```\n- **Argon2** support:\n\n ```bash\n pip install \"hash-forge[argon2]\"\n ```\n- **Whirlpool and RIPEMD-160** support:\n\n ```bash\n pip install \"hash-forge[crypto]\"\n ```\n- **Blake3** support:\n\n ```bash\n pip install \"hash-forge[blake3]\"\n ```\n\n## Usage\n\n### Basic Example\n\n```python\nfrom hash_forge import HashManager, AlgorithmType\nfrom hash_forge.hashers import PBKDF2Sha256Hasher\n\n# Initialize HashManager with PBKDF2Hasher\nhash_manager = HashManager(PBKDF2Sha256Hasher())\n\n# Hash a string\nhashed_value = hash_manager.hash(\"my_secure_password\")\n\n# Verify the string against the hashed value\nis_valid = hash_manager.verify(\"my_secure_password\", hashed_value)\nprint(is_valid) # Outputs: True\n\n# Check if the hash needs rehashing\nneeds_rehash = hash_manager.needs_rehash(hashed_value)\nprint(needs_rehash) # Outputs: False\n```\n\n### Quick Hash (New in v2.1.0)\n\nFor simple hashing without creating a HashManager instance:\n\n```python\nfrom hash_forge import HashManager, AlgorithmType\n\n# Quick hash with default algorithm (PBKDF2-SHA256)\nhashed = HashManager.quick_hash(\"my_password\")\n\n# Quick hash with specific algorithm (with IDE autocomplete!)\nalgorithm: AlgorithmType = \"argon2\"\nhashed = HashManager.quick_hash(\"my_password\", algorithm=algorithm)\n\n# Quick hash with algorithm-specific parameters\nhashed = HashManager.quick_hash(\"my_password\", algorithm=\"pbkdf2_sha256\", iterations=200_000)\nhashed = HashManager.quick_hash(\"my_password\", algorithm=\"bcrypt\", rounds=14)\nhashed = HashManager.quick_hash(\"my_password\", algorithm=\"argon2\", time_cost=4)\n```\n\n### Factory Pattern (New in v2.1.0)\n\nCreate HashManager instances using algorithm names:\n\n```python\nfrom hash_forge import HashManager, AlgorithmType\n\n# Create HashManager from algorithm names\nhash_manager = HashManager.from_algorithms(\"pbkdf2_sha256\", \"argon2\", \"bcrypt\")\n\n# With type safety\nalgorithms: list[AlgorithmType] = [\"pbkdf2_sha256\", \"bcrypt_sha256\"]\nhash_manager = HashManager.from_algorithms(*algorithms)\n\n# Note: from_algorithms() creates hashers with default parameters\n# For custom parameters, create hashers individually\nhash_manager = HashManager.from_algorithms(\"pbkdf2_sha256\", \"bcrypt\", \"argon2\")\n```\n\n> **Note:** The first hasher provided during initialization of `HashManager` will be the **preferred hasher** used for hashing operations, though any available hasher can be used for verification.\n\n### Available Algorithms\n\nCurrently supported algorithms with their `AlgorithmType` identifiers:\n\n| Algorithm | Identifier | Security Level | Notes |\n|-----------|------------|----------------|-------|\n| **PBKDF2-SHA256** | `\"pbkdf2_sha256\"` | High | Default, 150K iterations minimum |\n| **PBKDF2-SHA1** | `\"pbkdf2_sha1\"` | Medium | Legacy support |\n| **bcrypt** | `\"bcrypt\"` | High | 12 rounds minimum |\n| **bcrypt-SHA256** | `\"bcrypt_sha256\"` | High | With SHA256 pre-hashing |\n| **Argon2** | `\"argon2\"` | Very High | Memory-hard function |\n| **Scrypt** | `\"scrypt\"` | High | Memory-hard function |\n| **Blake2** | `\"blake2\"` | High | Fast cryptographic hash |\n| **Blake3** | `\"blake3\"` | Very High | Latest Blake variant |\n| **Whirlpool** | `\"whirlpool\"` | Medium | 512-bit hash |\n| **RIPEMD-160** | `\"ripemd160\"` | Medium | 160-bit hash |\n\n### Algorithm-Specific Parameters\n\nDifferent algorithms support different parameters. Use `quick_hash()` for algorithm-specific customization:\n\n```python\nfrom hash_forge import HashManager\n\n# PBKDF2 algorithms\nHashManager.quick_hash(\"password\", algorithm=\"pbkdf2_sha256\", iterations=200_000, salt_length=16)\nHashManager.quick_hash(\"password\", algorithm=\"pbkdf2_sha1\", iterations=150_000)\n\n# BCrypt algorithms \nHashManager.quick_hash(\"password\", algorithm=\"bcrypt\", rounds=14)\nHashManager.quick_hash(\"password\", algorithm=\"bcrypt_sha256\", rounds=12)\n\n# Argon2\nHashManager.quick_hash(\"password\", algorithm=\"argon2\", time_cost=4, memory_cost=65536, parallelism=1)\n\n# Scrypt\nHashManager.quick_hash(\"password\", algorithm=\"scrypt\", n=32768, r=8, p=1)\n\n# Blake2 (with optional key)\nHashManager.quick_hash(\"password\", algorithm=\"blake2\", key=\"secret_key\")\n\n# Blake3 (with optional key) \nHashManager.quick_hash(\"password\", algorithm=\"blake3\", key=\"secret_key\")\n\n# Other algorithms (use defaults)\nHashManager.quick_hash(\"password\", algorithm=\"whirlpool\")\nHashManager.quick_hash(\"password\", algorithm=\"ripemd160\")\n```\n\n### Traditional Initialization\n\nFor complete control over parameters, initialize `HashManager` with individual hasher instances:\n\n```python\nfrom hash_forge import HashManager\nfrom hash_forge.hashers import (\n Argon2Hasher,\n BCryptSha256Hasher,\n Blake2Hasher,\n PBKDF2Sha256Hasher,\n Ripemd160Hasher,\n ScryptHasher,\n WhirlpoolHasher,\n Blake3Hasher\n)\n\nhash_manager = HashManager(\n PBKDF2Sha256Hasher(iterations=200_000), # Higher iterations\n BCryptSha256Hasher(rounds=14), # Higher rounds\n Argon2Hasher(time_cost=4), # Custom parameters\n ScryptHasher(),\n Ripemd160Hasher(),\n Blake2Hasher('MySecretKey'),\n WhirlpoolHasher(),\n Blake3Hasher()\n)\n```\n\n### Verifying a Hash\n\nUse the `verify` method to compare a string with its hashed counterpart:\n\n```python\nis_valid = hash_manager.verify(\"my_secure_password\", hashed_value)\n```\n\n### Checking for Rehashing\n\nYou can check if a hash needs to be rehashed (e.g., if the hashing algorithm parameters are outdated):\n\n```python\nneeds_rehash = hash_manager.needs_rehash(hashed_value)\n```\n\n## What's New in v2.1.0\n\n### \ud83d\ude80 Performance Improvements\n- **O(1) Hasher Lookup**: Internal hasher mapping for faster algorithm detection\n- **Optimized Memory Usage**: Reduced object creation overhead\n\n### \ud83d\udee0\ufe0f Developer Experience \n- **Type Safety**: `AlgorithmType` literal for IDE autocomplete and error detection\n- **Factory Pattern**: Create hashers by algorithm name with `HasherFactory`\n- **Convenience Methods**: `quick_hash()` and `from_algorithms()` for simpler usage\n\n### \ud83d\udd10 Security Enhancements\n- **Parameter Validation**: Enforces minimum security thresholds (150K PBKDF2 iterations, 12 BCrypt rounds)\n- **Custom Exceptions**: More specific error types (`InvalidHasherError`, `UnsupportedAlgorithmError`)\n- **Centralized Configuration**: Security defaults in one place\n\n### \ud83e\uddea Better Testing\n- **Enhanced Test Suite**: 81 tests covering new functionality\n- **Type Checking Tests**: Validates `AlgorithmType` usage\n- **Configuration Validation**: Tests security parameter enforcement\n\n### \ud83d\udcda API Improvements\n\n**Before v2.1.0:**\n```python\n# Manual hasher imports and creation\nfrom hash_forge.hashers.pbkdf2_hasher import PBKDF2Sha256Hasher\nhasher = PBKDF2Sha256Hasher(iterations=150000)\nhash_manager = HashManager(hasher)\n```\n\n**v2.1.0+:**\n```python\n# Simplified with factory pattern and type safety\nfrom hash_forge import HashManager, AlgorithmType\n\nalgorithm: AlgorithmType = \"pbkdf2_sha256\" # IDE autocomplete!\nhash_manager = HashManager.from_algorithms(algorithm)\n# or with custom parameters\nhashed = HashManager.quick_hash(\"password\", algorithm=algorithm, iterations=200_000)\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit issues or pull requests to help improve the project.\n\n## License\n\nThis project is licensed under the MIT License.\n",
"bugtrack_url": null,
"license": null,
"summary": "Hash Forge is a lightweight Python library designed to simplify the process of hashing and verifying data using a variety of secure hashing algorithms.",
"version": "2.1.0",
"project_urls": {
"Homepage": "https://github.com/Zozi96/hash-forge",
"Issue Tracker": "https://github.com/Zozi96/hash-forge/issues",
"Repository": "https://github.com/Zozi96/hash-forge"
},
"split_keywords": [
"ripemd-160",
" whirlpool",
" argon2",
" bcrypt",
" blake2",
" blake3",
" hash",
" pbkdf2",
" scrypt",
" security"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d72515e865dc5b922c4e1304488797468239cb31229d919aea9f78bac9dbea6d",
"md5": "9fca8db3275f73934e3e6f3390445ba4",
"sha256": "cf42125b1de70d878338af3f22e8b6fba397408e2d60fc5ed0f81d2c64c2c7b4"
},
"downloads": -1,
"filename": "hash_forge-2.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9fca8db3275f73934e3e6f3390445ba4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 20168,
"upload_time": "2025-08-31T03:47:28",
"upload_time_iso_8601": "2025-08-31T03:47:28.282219Z",
"url": "https://files.pythonhosted.org/packages/d7/25/15e865dc5b922c4e1304488797468239cb31229d919aea9f78bac9dbea6d/hash_forge-2.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "17594f270b08870e1a541889e7ad0f96a3dbbf22193a62cb10e4216e3ab30aba",
"md5": "7b46546d9659ab43c1db994c9152ac19",
"sha256": "cb125b1ef9320dba1ca26bad5539c4515c5a49451d6033821c0cd6ac0e9a15ca"
},
"downloads": -1,
"filename": "hash_forge-2.1.0.tar.gz",
"has_sig": false,
"md5_digest": "7b46546d9659ab43c1db994c9152ac19",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 40525,
"upload_time": "2025-08-31T03:47:29",
"upload_time_iso_8601": "2025-08-31T03:47:29.303327Z",
"url": "https://files.pythonhosted.org/packages/17/59/4f270b08870e1a541889e7ad0f96a3dbbf22193a62cb10e4216e3ab30aba/hash_forge-2.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-31 03:47:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Zozi96",
"github_project": "hash-forge",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "hash-forge"
}
JSON
