GSSoC Approved Repository

🎮 Python Mini Projects Collection 🎯

Learn Python by Building Fun, Interactive Games & Tools!

🧪 New: Standardized Error Logging

A shared error logger is now available for mini-projects. It captures exception type, message, timestamp, traceback, and project name into JSONL logs under the logs folder, making failures easier to review and analyze.

Quick Start • Projects • Features • Contributing

🚀 Beginner-friendly projects | 💡 Learn by doing | 🎨 Clean UI | ⚡ Live demo available

Live Demo • Contributors

---

📚 Table of Contents

• Repo Introduction
• Repo Structure
• What's Inside
• Contributors
• License
• Connect & Share

🎯 Repo Introduction

This repository is a collection of small Python games and utility projects built to make learning Python more practical and engaging. It includes both command-line projects and a browser-based web app for trying the projects online.

📂 Repo Structure

python-mini-project/
|
├── games/
│   ├── Snake-Game/
│   ├── Rock-Paper-Scissor/
│   └── ...
├── math/
│   ├── Fibonacci-Series/
│   ├── Prime-Number-Analyzer/
│   └── ...
├── utilities/
│   ├── Text-to-Morse/
│   ├── Typing-Speed-Tester/
│   └── ...
├── web-app/
│   ├── css/
│   ├── js/
│   └── assets/
├── README.md
└── requirements.txt

🚀 Getting Started

Prerequisites

• Python 3.10, 3.11, or 3.12
• Git (for cloning the repository)
• pip (Python package manager)

Encoding Note

This repository uses UTF-8 for documentation, issue templates, and project metadata. If emoji or box-drawing characters appear as mojibake in a Windows terminal, switch the terminal to UTF-8 before viewing or running the files.

Installation Steps

1. Clone the Repository

📋 Copy

git clone https://github.com/steam-bell-92/python-mini-project.git
cd python-mini-project

2. Create a Virtual Environment

For Linux/macOS:

📋 Copy

python3 -m venv venv
source venv/bin/activate

For Windows (Command Prompt):

python -m venv venv
venv\Scripts\activate

For Windows (PowerShell):

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

3. Install Dependencies

📋 Copy

pip install --upgrade pip
pip install -r requirements.txt

The dependency set is tested on Python 3.10 through 3.12. Newer Python releases may not have compatible wheels for every pinned dependency yet.

Running Command-Line Projects

Each Python project in games/, math/, and utilities/ folders can be run independently.

Example: Running a Game

cd games/Snake-Game
python Snake-Game.py

Example: Running a Math Project

cd math/Fibonacci-Series
python Fibonacci-Series.py

Example: Running a Utility

cd utilities/Text-to-Morse
python Text-to-Morse.py

Running the Web App

The web application provides a browser-based interface for all projects.

Prerequisites for Web App

The web app requires Node.js and npm:

• Download from https://nodejs.org/ (v16 or higher recommended)
• Verify installation: node --version && npm --version

Steps to Run Web App

📋 Copy

cd web-app
npm install
npm start

The app will open at http://localhost:3000 (or your configured port).

Running Tests

To verify that the projects work correctly, run the test suite:

📋 Copy

pytest tests/ -v

For specific test file:

pytest tests/test_smoke.py -v

Development Workflow

Creating a New Project

1. Choose appropriate directory: games/, math/, or utilities/
2. Create a new folder with your project name (use PascalCase)
3. Add your .py file with the same name as the folder
4. Include a README.md in your project folder with usage instructions
5. Add tests in tests/ directory with prefix test_

Code Guidelines

• Follow PEP 8 style guide
• Write docstrings for functions and classes
• Add unit tests for your code
• Test your project before submitting a PR

Virtual Environment Reminder

Always activate your virtual environment before working:

# Linux/macOS
source venv/bin/activate

# Windows
venv\Scripts\activate

Deactivate when done:

deactivate

🧩 What’s Inside

• Games for quick interactive fun
• Math projects for learning logic and problem solving
• Utility tools for practical use cases
• A web app version for browser-based access

---

👥 Contributors

We appreciate all contributions to the Python Mini Projects Collection! Thank you to everyone who has helped make this project better.

---

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

💬 Connect & Share

Found this helpful? Show some love!

• ⭐ Star this repo if you found it useful
• 🐛 Report bugs or suggest features via Issues
• 💬 Share with friends learning Python
• 🎓 Use in your classroom or coding club

---

🎉 Happy Coding! 🎉

Made with ❤️ for Python learners everywhere

If you learned something new, don't forget to star the repo! ⭐

⬆ Back to Top