feat: Introduce several new Python projects, unit testing fundamentals, and update project dependencies.

Author: blshaer

11_testing/01_test_basics.py

@@ -0,0 +1,36 @@
+"""
+================================================================================
+File: 01_test_basics.py
+Topic: Introduction to Unit Testing with pytest
+================================================================================
+
+This file introduces unit testing, a professional practice used to ensure that 
+code behaves as expected. We use 'pytest', the industry standard for Python.
+
+Key Concepts:
+- Writing test functions (starting with test_)
+- Assertions (checking if conditions are True)
+- Running tests from the terminal
+================================================================================
+"""
+
+import pytest
+
+# A simple function we want to test
+def add(a: int, b: int) -> int:
+    return a + b
+
+def test_add_positive():
+    """Test addition of positive numbers."""
+    assert add(2, 3) == 5
+
+def test_add_negative():
+    """Test addition of negative numbers."""
+    assert add(-1, -1) == -2
+
+def test_add_zero():
+    """Test addition with zero."""
+    assert add(5, 0) == 5
+
+if __name__ == "__main__":
+    print("Run this file using: pytest 11_testing/01_test_basics.py")

README.md

@@ -10,9 +10,6 @@ A practical, example-driven Python repository designed to help you learn Python
 
 Each file is self-contained and focuses on a single concept, making the repository suitable for structured learning, revision, or reference.
 
-### 🌐 **Visit the Interactive Website**
-Want to follow your progress? Visit the website at [pythonbyexample.page.gd](https://pythonbyexample.page.gd/)
-
 > **If you like this project, please hit the ⭐ Star button and follow me on GitHub [@blshaer](https://github.com/blshaer)!**
 
 ---
@@ -25,6 +22,7 @@ Want to follow your progress? Visit the website at [pythonbyexample.page.gd](htt
 - [Prerequisites](#-prerequisites)
 - [File Structure](#-file-structure)
 - [Learning Path](#-learning-path)
+- [Projects](#-projects)
 
 ---
 
@@ -119,21 +117,50 @@ This repository contains a complete Python tutorial designed for both beginners
 
 ## Getting Started
 
+Follow these steps to clone the repository and set it up in your local editor:
+
 1. **Clone the repository**
+   Open your terminal and run:
+   ```bash
+   git clone https://github.com/blshaer/python-by-example.git
+   cd python-by-example
+   ```
+
+2. **Set up a Virtual Environment (Recommended)**
+   It's best practice to keep your projects isolated. Run these commands:
+   ```bash
+   python -m venv venv
+   # On Windows:
+   .\venv\Scripts\activate
+   # On macOS/Linux:
+   source venv/bin/activate
+   ```
+
+3. **Install Dependencies**
+   Install the necessary tools for testing and formatting:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+4. **Open in your code editor**
+   We recommend [Visual Studio Code](https://code.visualstudio.com/). Open the project directly:
    ```bash
-   git clone https://github.com/blshaer/python_review.git
-   cd python_review
+   code .
    ```
 
-2. **Start from basics**
+5. **Explore and Run**
+   Navigate to any example, like `01_basics`, and run the file:
    ```bash
    cd 01_basics
    python 01_print.py
    ```
 
-3. **Read the comments** — Each section is thoroughly explained
+6. **Read the comments** — Detailed explanations are provided inline for every concept!
 
-4. **Experiment** — Modify the code and observe the results
+7. **Try the Tests** — Go to the new testing module to see how professional code is verified:
+   ```bash
+   pytest 11_testing/01_test_basics.py
+   ```
 
 ---
 
@@ -219,6 +246,7 @@ Key Concepts:
 <td>
 
 10. [Best Practices](./10_best_practices/)
+11. [Testing](./11_testing/)
 
 </td>
 </tr>
@@ -229,11 +257,26 @@ Key Concepts:
 Beginner     →  01_basics → 02_control_flow → 03_loops
 Intermediate →  04_data_structures → 05_functions → 06_modules
 Advanced     →  07_error_handling → 08_oop → 09_advanced
-Professional →  10_best_practices
+Professional →  10_best_practices → 11_testing
 ```
 
 ---
 
+## Projects
+
+Put your skills to the test! Each project includes a **challenge description** (`README.md`) so you can try building it yourself before looking at the solution.
+
+| # | Project | Difficulty | Concepts Applied |
+|:--|:--------|:-----------|:-----------------|
+| 01 | [**Number Guessing Game**](./projects/01_number_guessing_game/) | 🟢 Beginner | Loops, Conditionals, Random module |
+| 02 | [**Expense Tracker**](./projects/02_expense_tracker/) | 🟡 Intermediate | Dicts, File I/O (JSON), Functions |
+| 03 | [**Library Management System**](./projects/03_library_management/) | 🟠 Advanced | OOP, Inheritance, Custom Exceptions |
+| 04 | [**Real-time Weather CLI**](./projects/04_weather_cli/) | 🚀 Professional | API Requests, Decorators, Type Hints |
+
+> 💡 **Tip:** Read the project `README.md` first and try to build it on your own before looking at `solution.py`!
+
+---
+
 ## Progress Tracker
 
 Use this checklist to track your learning progress:
@@ -248,6 +291,13 @@ Use this checklist to track your learning progress:
 - [ ] **08. OOP** — Classes, Init, Inheritance, Polymorphism
 - [ ] **09. Advanced Python** — Comprehensions, Generators, Decorators
 - [ ] **10. Best Practices** — PEP8, Type Hints, Virtual Environments
+- [ ] **11. Testing** — Unit Tests, Pytest, Assertions
+
+### 🏗️ Projects
+- [ ] **Project 01** — Number Guessing Game (Beginner)
+- [ ] **Project 02** — Expense Tracker (Intermediate)
+- [ ] **Project 03** — Library Management System (Advanced)
+- [ ] **Project 04** — Real-time Weather CLI (Professional)
 
 ---
 

projects/01_number_guessing_game/README.md

@@ -0,0 +1,58 @@
+# 🎯 Project 01: Number Guessing Game
+
+## Difficulty: 🟢 Beginner
+
+## Description
+Build a command-line number guessing game where the computer picks a random number
+and the player tries to guess it. The game should provide hints like "Too high!" or
+"Too low!" after each guess.
+
+## Requirements
+
+1. Generate a random number between 1 and 100
+2. Ask the user for guesses until they get the correct number
+3. After each guess, tell the user if their guess is too high, too low, or correct
+4. Track the number of attempts and display it at the end
+5. Handle invalid input gracefully (non-numeric input)
+6. Ask the player if they want to play again after winning
+
+## Concepts You'll Practice
+
+- `while` loops
+- `if/elif/else` conditionals
+- `random` module
+- `try/except` error handling
+- `input()` function
+- f-strings
+
+## Example Output
+
+```
+🎯 Welcome to the Number Guessing Game!
+I'm thinking of a number between 1 and 100...
+
+Enter your guess: 50
+📉 Too low! Try again.
+
+Enter your guess: 75
+📈 Too high! Try again.
+
+Enter your guess: 63
+🎉 Congratulations! You guessed it in 3 attempts!
+
+Play again? (yes/no): no
+Thanks for playing! Goodbye! 👋
+```
+
+## How to Run
+
+```bash
+cd projects/01_number_guessing_game
+python solution.py
+```
+
+## Bonus Challenges
+
+- [ ] Add difficulty levels (Easy: 1-50, Medium: 1-100, Hard: 1-500)
+- [ ] Add a scoreboard that tracks best scores across games
+- [ ] Set a maximum number of attempts based on difficulty

projects/01_number_guessing_game/solution.py

@@ -0,0 +1,159 @@
+"""
+================================================================================
+Project 01: Number Guessing Game
+Difficulty: 🟢 Beginner
+================================================================================
+
+A command-line number guessing game where the computer picks a random number
+and the player tries to guess it with hints provided after each attempt.
+
+Concepts Used:
+- while loops
+- if/elif/else conditionals
+- random module
+- try/except error handling
+- input() function
+- f-strings
+
+================================================================================
+"""
+
+import random
+
+
+# -----------------------------------------------------------------------------
+# Game Configuration
+# -----------------------------------------------------------------------------
+
+DIFFICULTIES = {
+    "easy": {"min": 1, "max": 50, "attempts": 10},
+    "medium": {"min": 1, "max": 100, "attempts": 7},
+    "hard": {"min": 1, "max": 500, "attempts": 10},
+}
+
+
+# -----------------------------------------------------------------------------
+# Helper Functions
+# -----------------------------------------------------------------------------
+
+def display_welcome():
+    """Display the welcome banner."""
+    print("""
+╔══════════════════════════════════════════╗
+║       🎯 NUMBER GUESSING GAME 🎯        ║
+╚══════════════════════════════════════════╝
+    """)
+
+
+def choose_difficulty() -> dict:
+    """Let the player choose a difficulty level."""
+    print("Choose your difficulty:")
+    print("  [1] 🟢 Easy   (1-50,  10 attempts)")
+    print("  [2] 🟡 Medium (1-100,  7 attempts)")
+    print("  [3] 🔴 Hard   (1-500, 10 attempts)")
+
+    while True:
+        choice = input("\nYour choice (1/2/3): ").strip()
+        if choice == "1":
+            return DIFFICULTIES["easy"]
+        elif choice == "2":
+            return DIFFICULTIES["medium"]
+        elif choice == "3":
+            return DIFFICULTIES["hard"]
+        else:
+            print("❌ Invalid choice. Please enter 1, 2, or 3.")
+
+
+def get_guess(min_val: int, max_val: int) -> int:
+    """Get a valid integer guess from the player."""
+    while True:
+        try:
+            guess = int(input(f"\nEnter your guess ({min_val}-{max_val}): "))
+            if min_val <= guess <= max_val:
+                return guess
+            else:
+                print(f"⚠️  Please enter a number between {min_val} and {max_val}.")
+        except ValueError:
+            print("⚠️  That's not a valid number. Try again!")
+
+
+def play_round():
+    """Play a single round of the guessing game."""
+    # Setup
+    config = choose_difficulty()
+    min_val = config["min"]
+    max_val = config["max"]
+    max_attempts = config["attempts"]
+    secret = random.randint(min_val, max_val)
+    attempts = 0
+
+    print(f"\n🤔 I'm thinking of a number between {min_val} and {max_val}...")
+    print(f"   You have {max_attempts} attempts. Good luck!\n")
+
+    # Game loop
+    while attempts < max_attempts:
+        guess = get_guess(min_val, max_val)
+        attempts += 1
+        remaining = max_attempts - attempts
+
+        if guess < secret:
+            print(f"📉 Too low! ({remaining} attempts remaining)")
+        elif guess > secret:
+            print(f"📈 Too high! ({remaining} attempts remaining)")
+        else:
+            print(f"\n🎉 Congratulations! You guessed it in {attempts} attempt(s)!")
+            if attempts <= 3:
+                print("🏆 Amazing! You're a natural!")
+            elif attempts <= 5:
+                print("👏 Well done!")
+            else:
+                print("😅 That was close!")
+            return True
+
+    # Out of attempts
+    print(f"\n💀 Game over! The number was {secret}.")
+    return False
+
+
+def play_again() -> bool:
+    """Ask the player if they want to play again."""
+    while True:
+        answer = input("\n🔄 Play again? (yes/no): ").strip().lower()
+        if answer in ("yes", "y"):
+            print()
+            return True
+        elif answer in ("no", "n"):
+            return False
+        else:
+            print("Please enter 'yes' or 'no'.")
+
+
+# -----------------------------------------------------------------------------
+# Main Game Loop
+# -----------------------------------------------------------------------------
+
+def main():
+    """Main entry point for the game."""
+    display_welcome()
+
+    wins = 0
+    total = 0
+
+    while True:
+        total += 1
+        if play_round():
+            wins += 1
+
+        print(f"\n📊 Score: {wins} wins out of {total} games")
+
+        if not play_again():
+            break
+
+    print(f"\n{'='*40}")
+    print(f"  Final Score: {wins}/{total} games won")
+    print(f"  Thanks for playing! Goodbye! 👋")
+    print(f"{'='*40}\n")
+
+
+if __name__ == "__main__":
+    main()