Python Password Generator

A production-grade, cryptographically secure CLI password generator built in pure Python.
Every password is entropy-scored, category-guaranteed, and visually polished — with zero heavy dependencies.

---

Screenshots

Password Configuration Prompt

The interactive CLI prompts you to choose character categories, length, and clipboard options.

Generated Password & Entropy Report

The tool displays the generated password alongside a real-time entropy score and a colour-coded strength rating.

python password_generator.py

---

Architecture

┌──────────────────────────────────────────────────────────────┐
│                   password_generator.py                      │
│                                                              │
│  ┌──────────────┐    ┌──────────────┐    ┌───────────────┐  │
│  │  UI / Display│    │  Core Engine │    │  Input Layer  │  │
│  │              │    │              │    │               │  │
│  │ print_banner │    │ build_pool   │    │ prompt_yes_no │  │
│  │ print_result │◄───│ generate_pw  │◄───│ prompt_length │  │
│  │ strength_    │    │ calc_entropy │    │ _collect_opts │  │
│  │   meter      │    │ rate_strength│    │               │  │
│  └──────────────┘    └──────────────┘    └───────────────┘  │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐   │
│  │              Clipboard (optional)                     │   │
│  │  pyperclip.copy()  ──  graceful fallback if absent   │   │
│  └──────────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────┘

secrets module (OS CSPRNG)  ──►  build_pool  ──►  generate_password
                                     │
                              guarantees list
                          (1 char per category)

---

Features

Feature	Detail
Cryptographic security	Uses Python's secrets module (OS CSPRNG) — never random
Category guarantees	Exactly ≥1 character from each chosen category (upper, lower, digits, symbols)
Ambiguity filter	Optional exclusion of visually similar characters: l, 1, I, O, 0
Entropy engine	Shannon entropy formula E = L × log₂(N) with 4-tier strength rating
Strength tiers	Weak · Moderate · Strong · Uncrackable
ANSI visuals	Color-coded output, ASCII art banner, strength progress bar — zero UI deps
Clipboard support	pyperclip integration with a graceful no-dep fallback
Input validation	Handles empty input, non-integers, Ctrl+C — never crashes
Type hints	Full typing annotations throughout
Unit tests	30+ assertions covering all functions and edge cases

---

Entropy Explained

Password strength is measured in bits of entropy:

E = Length × log₂(Pool Size)

Pool	Size	12-char entropy	20-char entropy
Digits only	10	39.9 bits ⚠️	66.4 bits ✅
Lowercase	26	56.5 bits ✅	94.1 bits ✅
Alpha + Digits	62	71.4 bits ✅	119 bits 🔥
Full ASCII	95	78.8 bits ✅	131 bits 🔥

Strength Tiers

Entropy	Rating
< 40 bits	Weak — brute-forceable
40–59 bits	Moderate — acceptable for low-risk use
60–99 bits	Strong — recommended for most uses
≥ 100 bits	Uncrackable — future-proof

---

Installation

1. Clone the repository

git clone https://github.com/codewithkinza88/password-generator.git
cd password-generator

2. (Optional) Create a virtual environment

python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

3. Install dependencies

pip install -r requirements.txt

Note: The only dependency is pyperclip for clipboard support.
The generator works fully without it — clipboard copying will display an informational note.

---

Quickstart

python password_generator.py

Follow the interactive prompts to configure:

1. ✅ Uppercase letters (A–Z)
2. ✅ Lowercase letters (a–z)
3. ✅ Digits (0–9)
4. ✅ Symbols (!@#$…)
5. ✅ Exclude ambiguous characters
6. ✅ Password length
7. ✅ Copy to clipboard

---

Running Tests

# Using pytest (recommended)
pip install pytest
python -m pytest tests/ -v

# Using built-in unittest
python -m unittest discover tests/ -v

Test coverage includes:

• calculate_entropy() — known values, edge cases, scaling behaviour
• rate_strength() — all 4 tiers, exact boundary values
• build_pool() — pool composition, guarantee correctness, ambiguity exclusion, error cases
• generate_password() — correct length, all charset guarantees, pool-only chars
• End-to-end integration pipeline tests

---

Project Structure

python-password-generator/
│
├── password_generator.py   # Main CLI application
│
├── tests/
│   └── test_generator.py   # Full unittest suite (30+ test cases)
│
├── requirements.txt        # Dependencies
├── .gitignore              # Python / OS / IDE exclusions
└── README.md               # This file

---

Security Notes

• secrets module only — backed by the OS CSPRNG (/dev/urandom on Unix, CryptGenRandom on Windows).
• No random module — random is seeded and predictable; it is never used here.
• Guarantee injection + shuffle — each selected category contributes at least one character; the list is then uniformly shuffled with secrets.SystemRandom, so no position bias is introduced.
• Clipboard safety — password is never written to disk; clipboard contents are solely under the OS's control.

---

Why This Project?

This password generator was built as a core project during a Python Developer Internship, with the goal of producing real-world, production-quality code from day one.

Learning Objectives

Objective	Outcome
Cryptographic security	Hands-on experience with Python's secrets module (OS CSPRNG)
Software architecture	Separation of concerns: UI, engine, and input layers
Defensive programming	Robust input validation and graceful error handling
Testing discipline	30+ unit tests covering edge cases and boundary values
Developer ergonomics	Clean CLI UX with ANSI colours, banners, and a strength meter
Code quality	Full PEP 8 compliance, type hints, and inline documentation

Built to demonstrate that security tooling can be approachable, well-tested, and visually polished — all without heavy dependencies.

---

Demo

🎥 A terminal recording / GIF will be added here in a future update.

In the meantime, clone the repository and run python password_generator.py to see it live.

---

Future Improvements

The following enhancements are planned for upcoming versions:

• 🖥️ GUI Version (Tkinter) — A cross-platform desktop interface for users who prefer graphical tools.
• 📋 Password History — Optional encrypted local log of recently generated passwords.
• 💡 Password Strength Suggestions — Real-time feedback guiding users toward higher-entropy configurations.
• 📤 Export Passwords — Save generated passwords to an encrypted .txt or .csv file.
• 🔐 Password Manager Integration — CLI bridge to popular managers such as Bitwarden or KeePass.

---

License

This project is licensed under the MIT License.

---

Contributing

Pull requests are welcome. Please ensure all tests pass before submitting:

python -m pytest tests/ -v

---

Author

Kinza Kareem

• 🐙 GitHub: @codewithkinza88
• 🔗Linkedin: Kinza Kareem

Built with ❤️ during a Python Developer Internship.