Python Project Boilerplate

A minimal Python project boilerplate with modern tooling setup.

Features

• 🛠️ Modern development tools (black, isort, ruff, mypy)
• 📦 Simple dependency management
• 🧪 Testing setup with pytest
• 🔧 Environment variable support
• 🎨 Rich console output
• ✨ VSCode integration with auto-formatting
• 📋 Comprehensive coding standards (see .cursorrules)

Requirements

• Python 3.8+
• Make (optional, for using Makefile commands)
• VSCode (recommended)

Installation

1. Clone the repository:

git clone https://github.com/abuusama/python-boilerplate.git
cd python-boilerplate

2. Create and activate a virtual environment:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install the package with development dependencies:

make install  # or: uv pip install -e ".[dev]"

Environment Setup

1. Copy the sample environment file:

cp .env.sample .env

2. Edit .env with your configuration:

ENV=development
DEBUG=true

Scripts

The project includes several scripts for common development tasks:

Development Tools

# Install dependencies
make install

# Format code
make format

# Run linting checks
make lint

# Run tests
make test

# Run the application
make run

# Clean build artifacts
make clean

Individual Commands

You can also run the tools directly:

# Format code with black
python -m black src tests

# Sort imports with isort
python -m isort src tests

# Lint with ruff
python -m ruff check src tests

# Type check with mypy
python -m mypy src tests

# Run tests with pytest
python -m pytest tests -v

# Run the application
python -m src.main

Development Commands

The project includes a Makefile with common development tasks:

• make install: Install the package and development dependencies
• make format: Format code with black and isort
• make lint: Run all linting checks (ruff, black, isort, mypy)
• make test: Run tests with pytest
• make run: Run the main application
• make clean: Clean up build artifacts and cache files

Project Structure

python-boilerplate/
├── src/
│   ├── __init__.py
│   ├── main.py
│   ├── config.py
│   └── console.py
├── tests/
│   ├── __init__.py
│   ├── test_main.py
│   ├── test_config.py
│   └── test_console.py
├── .vscode/
│   ├── settings.json
│   └── extensions.json
├── .env.sample
├── .gitignore
├── LICENSE
├── Makefile
├── README.md
└── pyproject.toml

License

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

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Acknowledgments

• black - The uncompromising code formatter
• ruff - An extremely fast Python linter
• rich - Rich text and beautiful formatting in the terminal
• pytest - Testing framework