# 🍫 Cacao Password Generator
**Generate secure, customizable passwords with confidence**
[](https://badge.fury.io/py/cacao-password-generator)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/psf/black)
---
## 🚀 Quick Overview
Cacao Password Generator is a **secure, highly configurable Python package** for generating strong passwords with fine-grained control over character requirements. Whether you need a simple random password or one that meets specific security policies, Cacao has you covered.
✨ **Perfect for developers, security professionals, and anyone who takes password security seriously.**
---
## 🌟 Key Features
- 🔒 **Cryptographically Secure** - Uses Python's `secrets` module for true randomness
- ⚙️ **Highly Configurable** - Control length, character types, and minimum requirements
- 📊 **Integrated Strength Rating** - Built-in password strength assessment with entropy calculation
- 🛡️ **Shell Safety Aware** - Understands potentially problematic characters for shell environments
- 🔧 **Multiple Interfaces** - Use via CLI (`cacao-pass`) or Python API
- 🌐 **Environment Variable Support** - Configure defaults via `CACAO_PW_*` environment variables
- 📦 **Zero Dependencies** - No runtime dependencies, minimal footprint
- 🐍 **Modern Python** - Supports Python 3.8+
---
## 📦 Installation
Install from PyPI using pip:
```bash
pip install cacao-password-generator
```
---
## ⚡ Quick Start
### CLI Usage
Generate a secure password with default settings:
```bash
cacao-pass
```
Generate a custom password:
```bash
cacao-pass --length 16 --minuchars 2 --minlchars 2 --minnumbers 2 --minschars 2
```
### Python API Usage
```python
from cacao_password_generator.core import generate
# Simple generation
password = generate(length=12)
print(password) # e.g., "Kp9$mL2@Wq3z"
# With custom constraints
password = generate({
'minuchars': 3,
'minlchars': 3,
'minnumbers': 2,
'minschars': 2
}, length=16)
```
---
## 📚 Detailed Usage
### 🖥️ Command Line Interface
The `cacao-pass` command provides a full-featured CLI:
```bash
# Basic usage with length
cacao-pass --length 20
# Full constraint specification
cacao-pass \
--length 16 \
--minuchars 2 \
--minlchars 3 \
--minnumbers 2 \
--minschars 1
# Get help
cacao-pass --help
```
#### CLI Options
| Option | Short | Description | Default |
|--------|-------|-------------|---------|
| `--length` | `-l` | Password length | 12 |
| `--minuchars` | `-u` | Minimum uppercase letters | 1 |
| `--minlchars` | `-lc` | Minimum lowercase letters | 1 |
| `--minnumbers` | `-n` | Minimum numbers | 1 |
| `--minschars` | `-s` | Minimum special characters | 1 |
### 🐍 Python API
#### Basic Generation
```python
from cacao_password_generator.core import generate
# Default secure password (length 12)
password = generate()
# Custom length
password = generate(length=20)
# With character requirements
password = generate({
'minuchars': 3, # At least 3 uppercase
'minlchars': 3, # At least 3 lowercase
'minnumbers': 2, # At least 2 numbers
'minschars': 2 # At least 2 special chars
}, length=16)
```
#### Advanced Usage with Validation
```python
from cacao_password_generator.core import generate
from cacao_password_generator.rating import rating
from cacao_password_generator.validate import validate
# Generate and validate
password = generate(length=16, minschars=3)
# Check if password meets requirements
is_valid, errors = validate(password, length=16, minschars=3)
print(f"Valid: {is_valid}")
# Get strength rating
strength_rating = rating(password)
print(f"Strength: {strength_rating}") # e.g., "strong"
```
---
## ⚙️ Configuration
### Default Settings
| Parameter | Default | Description |
|-----------|---------|-------------|
| `length` | 12 | Password length |
| `minlen` | 6 | Minimum allowed length |
| `maxlen` | 128 | Maximum allowed length |
| `minuchars` | 1 | Minimum uppercase letters |
| `minlchars` | 1 | Minimum lowercase letters |
| `minnumbers` | 1 | Minimum numbers |
| `minschars` | 1 | Minimum special characters |
### Environment Variables
Override defaults using environment variables with the `CACAO_PW_` prefix:
```bash
export CACAO_PW_MINLEN=8
export CACAO_PW_MAXLEN=32
export CACAO_PW_MINUCHARS=2
export CACAO_PW_MINLCHARS=4
export CACAO_PW_MINNUMBERS=3
export CACAO_PW_MINSCHARS=2
# Now cacao-pass uses these defaults
cacao-pass
```
### Character Sets
- **Uppercase**: A-Z (26 characters)
- **Lowercase**: a-z (26 characters)
- **Numbers**: 0-9 (10 characters)
- **Special**: `!@#$%^&*()_+-=[]{}|;:,.<>?` (25 characters)
---
## 💡 Examples
### Web Application Passwords
```python
# Strong password for user accounts
user_password = generate(length=14, minuchars=2, minlchars=6, minnumbers=2, minschars=4)
# API key style (longer, more entropy)
api_key = generate(length=32, minuchars=4, minlchars=8, minnumbers=8, minschars=4)
```
### System Administration
```bash
# Database password (shell-safe considerations)
cacao-pass --length 20 --minschars 2
# SSH key passphrase
cacao-pass --length 25 --minuchars 3 --minlchars 8 --minnumbers 4
```
### Batch Generation
```python
from cacao_password_generator.core import generate
# Generate multiple passwords
passwords = [generate(length=16) for _ in range(10)]
# Generate with consistent strength
strong_passwords = [
generate(length=18, minuchars=3, minlchars=6, minnumbers=3, minschars=6)
for _ in range(5)
]
```
### Password Strength Analysis
```python
from cacao_password_generator.core import generate
from cacao_password_generator.rating import rating, detailed_rating
password = generate(length=20)
strength_rating = rating(password)
detailed_analysis = detailed_rating(password)
print(f"Password: {password}")
print(f"Strength: {strength_rating}")
print(f"Entropy: {detailed_analysis['entropy']:.2f} bits")
print(f"Character Space: {detailed_analysis['character_set_size']}")
print(f"Estimated Crack Time: {detailed_analysis['crack_time_formatted']}")
```
---
## 📋 Requirements
- **Python**: 3.8 or higher
- **Dependencies**: None (pure Python, uses only standard library)
- **Operating System**: Cross-platform (Windows, macOS, Linux)
---
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
```
MIT License
Copyright (c) 2024 Cacao Password Generator Contributors
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
```
---
## 🙏 Acknowledgments
- Built with Python's `secrets` module for cryptographically secure random generation
- Inspired by the need for configurable, secure password generation in modern applications
---
**Made with 🍫 by the Cacao team**
*For more information, visit our [GitHub repository](https://github.com/cacao-research/cacao-password-generator) or [report issues](https://github.com/cacao-research/cacao-password-generator/issues).*
Raw data
{
"_id": null,
"home_page": null,
"name": "cacao-password-generator",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "password, generator, security, cryptography",
"author": null,
"author_email": "Juan Denis <juan@vene.co>",
"download_url": "https://files.pythonhosted.org/packages/a3/5c/9589fd78e86a634d0bab518a4ee4cd77fac738873b711c183b73c229aca0/cacao_password_generator-1.0.2.tar.gz",
"platform": null,
"description": "# \ud83c\udf6b Cacao Password Generator\r\n\r\n**Generate secure, customizable passwords with confidence** \r\n\r\n[](https://badge.fury.io/py/cacao-password-generator)\r\n[](https://www.python.org/downloads/)\r\n[](https://opensource.org/licenses/MIT)\r\n[](https://github.com/psf/black)\r\n\r\n---\r\n\r\n## \ud83d\ude80 Quick Overview\r\n\r\nCacao Password Generator is a **secure, highly configurable Python package** for generating strong passwords with fine-grained control over character requirements. Whether you need a simple random password or one that meets specific security policies, Cacao has you covered.\r\n\r\n\u2728 **Perfect for developers, security professionals, and anyone who takes password security seriously.**\r\n\r\n---\r\n\r\n## \ud83c\udf1f Key Features\r\n\r\n- \ud83d\udd12 **Cryptographically Secure** - Uses Python's `secrets` module for true randomness\r\n- \u2699\ufe0f **Highly Configurable** - Control length, character types, and minimum requirements\r\n- \ud83d\udcca **Integrated Strength Rating** - Built-in password strength assessment with entropy calculation\r\n- \ud83d\udee1\ufe0f **Shell Safety Aware** - Understands potentially problematic characters for shell environments\r\n- \ud83d\udd27 **Multiple Interfaces** - Use via CLI (`cacao-pass`) or Python API\r\n- \ud83c\udf10 **Environment Variable Support** - Configure defaults via `CACAO_PW_*` environment variables\r\n- \ud83d\udce6 **Zero Dependencies** - No runtime dependencies, minimal footprint\r\n- \ud83d\udc0d **Modern Python** - Supports Python 3.8+\r\n\r\n---\r\n\r\n## \ud83d\udce6 Installation\r\n\r\nInstall from PyPI using pip:\r\n\r\n```bash\r\npip install cacao-password-generator\r\n```\r\n\r\n---\r\n\r\n## \u26a1 Quick Start\r\n\r\n### CLI Usage\r\n\r\nGenerate a secure password with default settings:\r\n\r\n```bash\r\ncacao-pass\r\n```\r\n\r\nGenerate a custom password:\r\n\r\n```bash\r\ncacao-pass --length 16 --minuchars 2 --minlchars 2 --minnumbers 2 --minschars 2\r\n```\r\n\r\n### Python API Usage\r\n\r\n```python\r\nfrom cacao_password_generator.core import generate\r\n\r\n# Simple generation\r\npassword = generate(length=12)\r\nprint(password) # e.g., \"Kp9$mL2@Wq3z\"\r\n\r\n# With custom constraints\r\npassword = generate({\r\n 'minuchars': 3,\r\n 'minlchars': 3,\r\n 'minnumbers': 2,\r\n 'minschars': 2\r\n}, length=16)\r\n```\r\n\r\n---\r\n\r\n## \ud83d\udcda Detailed Usage\r\n\r\n### \ud83d\udda5\ufe0f Command Line Interface\r\n\r\nThe `cacao-pass` command provides a full-featured CLI:\r\n\r\n```bash\r\n# Basic usage with length\r\ncacao-pass --length 20\r\n\r\n# Full constraint specification\r\ncacao-pass \\\r\n --length 16 \\\r\n --minuchars 2 \\\r\n --minlchars 3 \\\r\n --minnumbers 2 \\\r\n --minschars 1\r\n\r\n# Get help\r\ncacao-pass --help\r\n```\r\n\r\n#### CLI Options\r\n\r\n| Option | Short | Description | Default |\r\n|--------|-------|-------------|---------|\r\n| `--length` | `-l` | Password length | 12 |\r\n| `--minuchars` | `-u` | Minimum uppercase letters | 1 |\r\n| `--minlchars` | `-lc` | Minimum lowercase letters | 1 |\r\n| `--minnumbers` | `-n` | Minimum numbers | 1 |\r\n| `--minschars` | `-s` | Minimum special characters | 1 |\r\n\r\n### \ud83d\udc0d Python API\r\n\r\n#### Basic Generation\r\n\r\n```python\r\nfrom cacao_password_generator.core import generate\r\n\r\n# Default secure password (length 12)\r\npassword = generate()\r\n\r\n# Custom length\r\npassword = generate(length=20)\r\n\r\n# With character requirements\r\npassword = generate({\r\n 'minuchars': 3, # At least 3 uppercase\r\n 'minlchars': 3, # At least 3 lowercase\r\n 'minnumbers': 2, # At least 2 numbers\r\n 'minschars': 2 # At least 2 special chars\r\n}, length=16)\r\n\r\n\r\n```\r\n\r\n#### Advanced Usage with Validation\r\n\r\n```python\r\nfrom cacao_password_generator.core import generate\r\nfrom cacao_password_generator.rating import rating\r\nfrom cacao_password_generator.validate import validate\r\n\r\n# Generate and validate\r\npassword = generate(length=16, minschars=3)\r\n\r\n# Check if password meets requirements\r\nis_valid, errors = validate(password, length=16, minschars=3)\r\nprint(f\"Valid: {is_valid}\")\r\n\r\n# Get strength rating\r\nstrength_rating = rating(password)\r\nprint(f\"Strength: {strength_rating}\") # e.g., \"strong\"\r\n```\r\n\r\n---\r\n\r\n## \u2699\ufe0f Configuration\r\n\r\n### Default Settings\r\n\r\n| Parameter | Default | Description |\r\n|-----------|---------|-------------|\r\n| `length` | 12 | Password length |\r\n| `minlen` | 6 | Minimum allowed length |\r\n| `maxlen` | 128 | Maximum allowed length |\r\n| `minuchars` | 1 | Minimum uppercase letters |\r\n| `minlchars` | 1 | Minimum lowercase letters |\r\n| `minnumbers` | 1 | Minimum numbers |\r\n| `minschars` | 1 | Minimum special characters |\r\n\r\n### Environment Variables\r\n\r\nOverride defaults using environment variables with the `CACAO_PW_` prefix:\r\n\r\n```bash\r\nexport CACAO_PW_MINLEN=8\r\nexport CACAO_PW_MAXLEN=32\r\nexport CACAO_PW_MINUCHARS=2\r\nexport CACAO_PW_MINLCHARS=4\r\nexport CACAO_PW_MINNUMBERS=3\r\nexport CACAO_PW_MINSCHARS=2\r\n\r\n# Now cacao-pass uses these defaults\r\ncacao-pass\r\n```\r\n\r\n### Character Sets\r\n\r\n- **Uppercase**: A-Z (26 characters)\r\n- **Lowercase**: a-z (26 characters) \r\n- **Numbers**: 0-9 (10 characters)\r\n- **Special**: `!@#$%^&*()_+-=[]{}|;:,.<>?` (25 characters)\r\n\r\n---\r\n\r\n## \ud83d\udca1 Examples\r\n\r\n### Web Application Passwords\r\n\r\n```python\r\n# Strong password for user accounts\r\nuser_password = generate(length=14, minuchars=2, minlchars=6, minnumbers=2, minschars=4)\r\n\r\n# API key style (longer, more entropy)\r\napi_key = generate(length=32, minuchars=4, minlchars=8, minnumbers=8, minschars=4)\r\n```\r\n\r\n### System Administration\r\n\r\n```bash\r\n# Database password (shell-safe considerations)\r\ncacao-pass --length 20 --minschars 2\r\n\r\n# SSH key passphrase\r\ncacao-pass --length 25 --minuchars 3 --minlchars 8 --minnumbers 4\r\n```\r\n\r\n### Batch Generation\r\n\r\n```python\r\nfrom cacao_password_generator.core import generate\r\n\r\n# Generate multiple passwords\r\npasswords = [generate(length=16) for _ in range(10)]\r\n\r\n# Generate with consistent strength\r\nstrong_passwords = [\r\n generate(length=18, minuchars=3, minlchars=6, minnumbers=3, minschars=6)\r\n for _ in range(5)\r\n]\r\n```\r\n\r\n### Password Strength Analysis\r\n\r\n```python\r\nfrom cacao_password_generator.core import generate\r\nfrom cacao_password_generator.rating import rating, detailed_rating\r\n\r\npassword = generate(length=20)\r\nstrength_rating = rating(password)\r\ndetailed_analysis = detailed_rating(password)\r\n\r\nprint(f\"Password: {password}\")\r\nprint(f\"Strength: {strength_rating}\")\r\nprint(f\"Entropy: {detailed_analysis['entropy']:.2f} bits\")\r\nprint(f\"Character Space: {detailed_analysis['character_set_size']}\")\r\nprint(f\"Estimated Crack Time: {detailed_analysis['crack_time_formatted']}\")\r\n```\r\n\r\n---\r\n\r\n## \ud83d\udccb Requirements\r\n\r\n- **Python**: 3.8 or higher\r\n- **Dependencies**: None (pure Python, uses only standard library)\r\n- **Operating System**: Cross-platform (Windows, macOS, Linux)\r\n\r\n---\r\n\r\n## \ud83d\udcc4 License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n```\r\nMIT License\r\n\r\nCopyright (c) 2024 Cacao Password Generator Contributors\r\n\r\nPermission is hereby granted, free of charge, to any person obtaining a copy\r\nof this software and associated documentation files (the \"Software\"), to deal\r\nin the Software without restriction, including without limitation the rights\r\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\r\ncopies of the Software, and to permit persons to whom the Software is\r\nfurnished to do so, subject to the following conditions:\r\n\r\nThe above copyright notice and this permission notice shall be included in all\r\ncopies or substantial portions of the Software.\r\n```\r\n\r\n---\r\n\r\n## \ud83d\ude4f Acknowledgments\r\n\r\n- Built with Python's `secrets` module for cryptographically secure random generation\r\n- Inspired by the need for configurable, secure password generation in modern applications\r\n\r\n---\r\n\r\n**Made with \ud83c\udf6b by the Cacao team**\r\n\r\n*For more information, visit our [GitHub repository](https://github.com/cacao-research/cacao-password-generator) or [report issues](https://github.com/cacao-research/cacao-password-generator/issues).*\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A secure password generator with configurable constraints and strength rating",
"version": "1.0.2",
"project_urls": {
"Bug Reports": "https://github.com/cacao-research/cacao-password-generator/issues",
"Homepage": "https://github.com/cacao-research/cacao-password-generator",
"Source": "https://github.com/cacao-research/cacao-password-generator"
},
"split_keywords": [
"password",
" generator",
" security",
" cryptography"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "de775003126d84fcddd106c5023748207481011db270e2d47538e97801cfb419",
"md5": "95fd39626de7269f637e2786188c1011",
"sha256": "a6b565bddff4372a7b88ba6ed00c0b2796658578ba3de08fab72a2d22a9c6ad6"
},
"downloads": -1,
"filename": "cacao_password_generator-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "95fd39626de7269f637e2786188c1011",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 24552,
"upload_time": "2025-07-23T04:46:28",
"upload_time_iso_8601": "2025-07-23T04:46:28.981203Z",
"url": "https://files.pythonhosted.org/packages/de/77/5003126d84fcddd106c5023748207481011db270e2d47538e97801cfb419/cacao_password_generator-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a35c9589fd78e86a634d0bab518a4ee4cd77fac738873b711c183b73c229aca0",
"md5": "cd06f54236562032da71fc54c1ad5240",
"sha256": "7a08c692b3c281dcd072df57a73cede07d153be23b067cabe01598444e2f5324"
},
"downloads": -1,
"filename": "cacao_password_generator-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "cd06f54236562032da71fc54c1ad5240",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 57334,
"upload_time": "2025-07-23T04:46:30",
"upload_time_iso_8601": "2025-07-23T04:46:30.124224Z",
"url": "https://files.pythonhosted.org/packages/a3/5c/9589fd78e86a634d0bab518a4ee4cd77fac738873b711c183b73c229aca0/cacao_password_generator-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-23 04:46:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cacao-research",
"github_project": "cacao-password-generator",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "cacao-password-generator"
}
JSON
