password-generator

A secure, cryptographically-strong password generation tool with both CLI and GUI interfaces. Built with Python and designed for security-conscious users who need reliable password generation.

Features

• Multiple Password Styles:

  • random: Cryptographically secure random characters
  • passphrase: Readable word combinations (e.g., brave-eagle-runs)
  • sentence: First-character extraction with optional leetspeak

• Security: Uses Python's secrets module for cryptographically strong randomness

• Dual Interface:

  • CLI: Powerful command-line interface for automation
  • GUI: Modern, dark-themed graphical interface

• Advanced Options:

  • Customizable length and word count
  • Random capitalization for passphrases
  • Leetspeak transformation for sentence mode

• File Management: Automatically organizes saved passwords by date with unique timestamps

• Cross-Platform: Works on Windows, macOS, and Linux

Architecture

password-generator/
├── engine.py          # Core generation logic (shared library)
├── password-generator.py   # CLI interface
├── password-generator-gui.py # GUI interface
├── requirements.txt   # Python dependencies
├── tests/             # Automated test suite
└── BUILD.md           # Build instructions

Installation

Prerequisites

• Python 3.8 or higher
• pip package manager

Quick Start

# Clone or download the repository
git clone https://github.com/yourusername/password-generator.git
cd password-generator

# Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Usage

Command Line Interface (CLI)

Interactive Mode

python password-generator.py

Command Line Arguments

# Generate 5 random passwords (length 16)
python password-generator.py -s random -l 16 -n 5

# Generate 3 passphrases (4 words each) with capitalization
python password-generator.py -s passphrase -w 4 -n 3 --capitalize

# Generate 2 sentence-mode passwords with leetspeak
python password-generator.py -s sentence -w 5 --leetspeak -n 2

# Save to a specific file
python password-generator.py -s random -l 20 -n 3 -f my_passwords.txt

Available Arguments

Argument	Short	Description	Default
--number	-n	Number of passwords to generate	1
--length	-l	Password length (random mode)	16
--file	-f	Output filename	None
--style	-s	Generation style	passphrase
--words	-w	Number of words (passphrase/sentence)	4
--leetspeak	-	Enable leetspeak (sentence mode)	False
--capitalize	-	Enable capitalization (passphrase)	False

Graphical User Interface (GUI)

python password-generator-gui.py

The GUI provides:

• Clean, dark-themed interface
• Real-time password generation
• Copy to clipboard functionality
• Save to file with timestamps
• Dynamic UI updates based on selected style

Building Standalone Executables

See BUILD.md for detailed instructions on creating standalone executables using PyInstaller.

Quick Build

# Ensure dependencies are installed
pip install -r requirements.txt
pip install pyinstaller

# Build for current OS
pyinstaller --noconsole --onefile --add-data "customtkinter;customtkinter" password-generator-gui.py

Note: Build the executable on the target operating system. You cannot cross-compile.

Testing

# Run all tests
pytest tests/

# Run with verbose output
pytest tests/ -v

# Run specific test file
pytest tests/test_passgen.py

# Run with coverage
pytest tests/ --cov=engine --cov-report=html

Code Quality

# Lint with ruff
ruff check .

# Type check with mypy
mypy .

# Format with ruff (if configured)
ruff format .

Project Structure

password-generator/
├── engine.py              # Core password generation logic
│   ├── generate_password()          # Random character passwords
│   ├── generate_passphrase()        # Word-based passphrases
│   ├── generate_sentence_mode()     # Sentence-derived passwords
│   └── save_passwords()             # File saving utility
├── password-generator.py      # CLI entry point
├── password-generator-gui.py  # GUI entry point
├── requirements.txt           # Dependencies
├── tests/
│   └── test_passgen.py       # Test suite
├── BUILD.md                   # Build instructions
├── CONTRIBUTING.md           # Contribution guidelines
├── LICENSE                   # GNU GPL v3 license
└── README.md                 # This file

Development

Adding New Features

1. Add logic to engine.py (core functionality)
2. Update CLI in password-generator.py
3. Update GUI in password-generator-gui.py
4. Add tests to tests/test_passgen.py
5. Update documentation

Core Engine Functions

The engine.py module provides the foundation for all password generation:

from engine import (
    generate_password,
    generate_passphrase,
    generate_sentence_mode,
    save_passwords
)

# Generate random password
pwd = generate_password(length=20)

# Generate passphrase
phrase = generate_passphrase(num_words=4, randomize_caps=True)

# Generate sentence mode
sentence_pwd = generate_sentence_mode(num_words=5, use_leetspeak=True)

Security Considerations

• Uses Python's secrets module (cryptographically secure)
• All passwords are generated in-memory
• No passwords are transmitted or stored externally
• Date-based directory organization keeps passwords organized
• Timestamps prevent file overwrites

License

This project is licensed under the GNU General Public License v3.0 (GPLv3). See LICENSE for details.

What This Means

• ✅ You can use this software for free
• ✅ You can modify the source code
• ✅ You can distribute copies
• ✅ You must share any modifications under the same license
• ✅ You must include the original license and copyright notice

Contributing

See CONTRIBUTING.md for guidelines on how to contribute to this project.

Acknowledgments

• Python's secrets module for cryptographic randomness
• customtkinter for the modern GUI framework
• All contributors who help improve this tool

Future Enhancements

• Passphrase dictionary customization
• Password strength analysis
• More password styles
• Password history tracking
• Export to various formats (JSON, CSV)
• Keyboard shortcuts in GUI
• Custom themes in GUI

Support

For issues, feature requests, or questions, please open an issue on the GitHub repository.

---

Made with ❤️ for security-conscious users everywhere.