Skip to content

README.md

Latest commit

 

History

History
155 lines (115 loc) · 5.47 KB

README.md

File metadata and controls

155 lines (115 loc) · 5.47 KB

🐍 Python Repository Template

A comprehensive, production-ready template for Python projects with modern tooling, automated code quality, and best practices baked in.

Python Code style: Ruff Type checking: mypy Testing: pytest Task runner: Taskfile

✨ Features

This template provides a complete development environment with:

  • 🏗️ Modern Build System: Uses pyproject.toml with setuptools backend
  • 📦 Dependency Management: UV for ultra-fast package management
  • 🎯 Code Quality: Ruff for linting and formatting (replaces Black + isort + flake8)
  • 🔍 Type Checking: MyPy with strict configuration
  • 🧪 Testing Framework: pytest with coverage reporting and markers
  • 🪝 Pre-commit Hooks: Automated code quality checks for Python, YAML, and JSON
  • ⚡ Task Automation: Taskfile for common development tasks
  • 🔧 Development Tools: Pre-configured for immediate productivity

📋 Prerequisites

Before using this template, ensure you have the following installed:

Required Tools

Tool Version Purpose Installation
uv >=0.8.22 Package manager uv installation
Python 3.11+ Runtime environment python.org (can also be installed with uv)
Task >=3.44.1 Task runner (better than Makefiles) Taskfile
Docker >=24.0.2 Containerization Docker
Git >=2.47.0 Version control Git

🚀 Quick Start

1. 📥 Clone or Use Template

# Using GitHub CLI
gh repo create my-awesome-project --template JVGD/python-repo-template

# Or clone directly
git clone https://github.com/JVGD/python-repo-template.git my-awesome-project
cd my-awesome-project

2. 🔧 Initialize Project

# Remove git history, create .env file and set up virtual environment with dev dependencies
task setup

# Verify installation running full quality assurance pipeline
task qa

3. ✏️ Customize Your Project

Run the task rename to automatically rename the package template to your desired name.

# This task renames the template package to your desired name, handle directories files and imports
task rename NAME=your_package

🛠️ Development Workflow

Core Commands

# 📦 Install dependencies
task install

# 🧹 Format code (runs Ruff formatter)
task format

# 🔍 Lint code (runs Ruff linter with auto-fix)
task lint

# 🏷️ Type check (runs MyPy)
task type_check

# 🧪 Run tests
task test

# ⚡ Run complete quality assurance pipeline (format, lint, type_check and tests)
task qa

# 🧽 Clean generated files
task clean

🪝 Pre-commit Hooks

This template includes comprehensive pre-commit hooks for code quality. They are installed when running task install. However if you want to run it on all files ad-hoc you can issue:

# Run hooks on all files manually
pre-commit run --all-files

Included Hooks:

  • Python: Ruff (linting & formatting)
  • General: Trailing whitespace, end-of-file-fixer, merge conflict detection
  • YAML: yamllint, prettier formatting
  • JSON: prettier formatting, syntax validation

🐳 Docker

Build and run the project in a container:

# Build Docker image
task build

# Build with custom tag
task build TAG=my-app:v1.0.0

📁 Project Structure

python-repo-template/
├── 📄 .dockerignore           # Docker ignore patterns
├── 📄 .env.example            # Environment variables template
├── 📄 .gitignore              # Git ignore patterns
├── 📄 .pre-commit-config.yaml # Pre-commit hooks configuration
├── 📄 .python-version         # Python version specification
├── 📄 Dockerfile              # Docker container definition
├── 📄 LICENSE                 # Project license
├── 📄 pyproject.toml          # Project metadata & tool configuration
├── 📄 README.md               # Project documentation
├── 📄 Taskfile.yml            # Task automation definitions
├── 📄 uv.lock                 # Dependency lock file
├── 📁 .venv/                  # Virtual environment (auto-created)
├── 📁 src/                    # Source code (importable package)
│   ├── 📄 main.py             # Main application entry point
│   └── 📁 template_package/   # Example package (rename to your package)
│       ├── 📄 __init__.py
│       └── 📄 template_module.py
└── 📁 tests/                  # Test suite
    ├── 📄 __init__.py
    ├── � test_main.py        # Tests for main.py
    └── 📁 template_package/   # Package-specific tests
        ├── 📄 __init__.py
        └── 📄 test_template_module.py

🧑‍⚖️ License

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