Learn-Python Mini Projects

A collection of beginner-friendly Python mini projects that is being upgraded from notebook proofs-of-concept into a structured, testable package.

Quick Start

For full documentation navigation, start with docs/README.md.

Prerequisites

• Python 3.11+
• pip

Setup

python -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt

Run TicTacToe (Phase 1 feature)

PYTHONPATH=src python -m mini_projects.cli tictactoe --difficulty hard

Run Expansion Capstone Demo

PYTHONPATH=src python -m mini_projects.cli curriculum-demo

Run World Bank Real-Data Sync

PYTHONPATH=src python -m mini_projects.cli world-bank-sync --countries US CA GB DE JP --indicators NY.GDP.MKTP.KD.ZG FP.CPI.TOTL.ZG SL.UEM.TOTL.ZS

Check World Bank Freshness Status

PYTHONPATH=src python -m mini_projects.cli world-bank-status

Available difficulty levels:

• easy: random legal moves
• medium: mixed random + shallow minimax
• hard: full minimax with alpha-beta pruning

Project Structure

Learn-Python/
  src/
    mini_projects/
      cli.py
      features/
        advanced_python/
        dsa/
        async_concurrency/
        backend_api/
        data_stack/
        dashboard/
        big_data/
        capstone/
        tictactoe/
          domain/
          application/
          presentation/
  tests/
    features/
      tictactoe/
  .github/workflows/ci.yml
  requirements.txt
  requirements-dev.txt

Development

Run tests

PYTHONPATH=src pytest -q

CI

GitHub Actions runs test checks on every push and pull request through .github/workflows/ci.yml.

Current Modules

• TicTacToe (modernized package): src/mini_projects/features/tictactoe with CLI + alpha-beta AI difficulty levels.
• Advanced Python: decorators, generators, context managers, protocols, dataclasses.
• DSA Deepening: trie, union-find, Dijkstra shortest path, LIS dynamic programming pattern.
• Async/Concurrency: retry, bounded concurrency, timeout fanout, model-selection helper.
• Backend API: FastAPI notes service with validation and SQLite adapter.
• Data Stack: normalized indicator schema and KPI/category analysis workflow.
• Dashboard Building: payload builder for KPI cards and trend/category views from indicator data.
• Big Data Analysis: chunked processing and scaling strategy selector.
• Capstone Integration: World Bank ingestion + cache freshness + dashboard + big-data strategy in one runnable flow.

World Bank Data Pipeline

• Source: World Bank Indicators API v2 (free and open, no API key).
• Adapter path: src/mini_projects/features/capstone/infrastructure/world_bank_client.py
• Cache/freshness path: src/mini_projects/features/capstone/infrastructure/cache_store.py
• Orchestration path: src/mini_projects/features/capstone/application/pipeline.py
• API endpoints:
  • POST /world-bank/refresh
  • GET /world-bank/latest
  • GET /world-bank/status
• Runbook index: docs/pipelines/world-bank/overview.md

Python Expansion Curriculum

• Curriculum guide: docs/curriculum/overview.md
• New tests live under tests/features/ for each added module.
• This expansion demonstrates language depth, algorithms, async systems, backend services, data analysis, dashboard thinking, and big-data scaling decisions.

Notebook Projects (Upgraded In Place)

• Hangman.ipynb: categories, hint recommendation, multiplayer helper, JSON score persistence.
• Minesweeper.ipynb: flags, timer, SQLite leaderboard, solver-hint mode.
• sudoku.ipynb: constraint propagation + backtracking + puzzle generation.
• Rock Paper Scissors.ipynb: input normalization, best-of rounds, adaptive opponent model.
• Binary Search.ipynb: expanded to visualizer-style algorithms notebook (binary search, BFS, DFS, quicksort, mergesort).
• Guess the number.ipynb: robust validation, attempts tracking, reverse mode.
• madlib.ipynb: multi-template system with validation and deterministic selection support.
• Simple Calculator.ipynb: expression parser, safe errors, history session runner.
• Find the month.ipynb: normalized lookup, fallback handling, fuzzy suggestion helper.

AI/ML-Enabled Notebook Features

• Hangman letter recommendation.
• Minesweeper safe-cell hinting.
• Sudoku step ranking via constraint-first candidate flow.
• Rock Paper Scissors Markov-style opponent prediction.
• Binary Search notebook includes empirical timing trend comparisons.
• Guess the Number adaptive mode helper via binary-search strategy.

Usage Notes

• Notebooks now follow a consistent pattern: intro -> helpers -> runner -> assertions/demo.
• New code should be added under src/mini_projects and verified with tests in tests/.
• Some interactive notebook runners require user input and are intended to be executed cell-by-cell.

Remaining Scripts Pending Migration

• compose.py, compose_template.py, graph.py, graph_template.py
• image.py, transform.py, transform_empty.py, png.py
• lyrics.py, words.py

Modernization notes and contracts for these scripts are documented in docs/migration/script-modernization.md.

Screenshots

Place screenshots or GIFs in a future docs/assets/ folder and reference them here.

Roadmap

• Minesweeper GUI with timer, flags, SQLite leaderboard, and solver mode.
• Sudoku with constraint propagation, visualization, and puzzle generation.
• Hangman with categories, persistent scores, and multiplayer mode.
• Algorithms visualizer (binary search, BFS, DFS, quicksort, mergesort, and more).
• Optional TicTacToe Monte Carlo Tree Search (MCTS) mode.