🚀 Hangman

A beginner-friendly Python program that lets you play Hangman in the terminal against a randomly chosen word.

📚 Table of Contents

• Overview
• Requirements
• Setup
• Run
• Tests
• License
• Links

🧭 Overview

Day 7 of Udemy's 100 Days of Code™: The Complete Python Pro Bootcamp. The game is built in five steps that follow the course:

1. Picking a random word and checking answers
2. Replacing blanks with guesses
3. Checking if the player has won
4. Keeping track of the player's lives
5. Improving the user experience (this step)

The flowchart from the course:

flowchart TD
    A([START]) --> B[Generate a random word]
    B --> C[Generate as many blanks as letters in word]
    C --> D[Ask the user to guess a letter]
    D --> E{Is the guessed letter in the word?}
    E -- Yes --> F[Replace the blank with the letter]
    E -- No --> G[Lose a life]
    F --> H{Are all the blanks filled?}
    G --> I{Have they run out of lives?}
    H -- No --> D
    I -- No --> D
    H -- Yes --> J([GAME OVER])
    I -- Yes --> J

What each step adds:

• Step 1: pick a random word, ask for one letter and say whether it is in the word.
• Step 2: show the word as blanks (_ _ _ _ _); a correct guess replaces every matching blank.
• Step 3: keep asking for letters until every blank is filled, then print "You win!".
• Step 4: start with 6 lives; every wrong guess costs one. At 0 lives the game ends with "You lose" and reveals the word.
• Step 5: a colored ASCII-art title (colors are skipped when the output is not a terminal or the NO_COLOR environment variable is set), an ASCII-art gallows that grows with each wrong guess, a friendly message for letters you already guessed, and input validation (only a single letter is accepted). These two are additions that are not in the flowchart.

The game logic (src/hangman/game.py) is separate from the input/output (src/hangman/main.py), and all constants live in src/hangman/constants.py.

📋 Requirements

• Python 3.13 or newer
• No runtime dependencies (the standard library is enough)
• pytest (only for running the tests)
• Doxygen (optional, to build the API documentation)

🛠️ Setup

Create and activate a local virtual environment named .venv, then install the project in editable mode together with the test extra.

Windows (PowerShell):

python -m venv .venv
.\.venv\Scripts\Activate.ps1

Windows (cmd):

python -m venv .venv
.venv\Scripts\activate.bat

macOS / Linux / Git Bash:

python3 -m venv .venv
source .venv/bin/activate        # Git Bash on Windows: source .venv/Scripts/activate

Then install:

python -m pip install --upgrade pip
python -m pip install -e ".[test]"

Run deactivate to leave the environment.

The .env file (access tokens for repository tooling) is ignored by git and is not needed to run the game.

To build the API documentation with Doxygen (output in docs/api):

doxygen Doxyfile

▶️ Run

python -m hangman

or, after installing:

hangman

🧪 Tests

python -m pytest

📄 License

GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See LICENSE.

🔗 Links

• Repository
• Documentation
• Issue tracker