Python Project Template

A modern, fast, cross-platform Python project template powered by uv, Ruff, Pyright, and pytest.

Features

• ⚡ Blazing Fast Environment & Packaging: Managed with uv (.python-version, uv.lock, PEP 517 hatchling builds).
• 🐍 Modern Python Baseline: Targeted for Python >=3.12.
• 🔍 Ultra-Fast Linting & Formatting: Configured with ruff for linting, code style, and imports.
• 🎯 Strict Static Typing: Configured with pyright for robust type checking.
• 🧪 Comprehensive Testing: pytest + pytest-cov with branch coverage.
• 🖥️ Modern Desktop GUI: Optional PySide6 / Qt desktop interface (template-python --gui or template-python-gui).
• 🛠️ Cross-Platform Task Runner: Run commands seamlessly via just or python scripts/run.py.
• 🔄 Quick Template Initializer: Rename package and bootstrap metadata in one command with scripts/init_project.py.

---

Directory Structure

template-python/
├── .python-version             # Pinned Python version (3.13 default)
├── .editorconfig               # Editor whitespace/formatting consistency
├── .gitignore                  # Standard Python gitignore
├── pyproject.toml              # Build config, dependencies, ruff, pyright & pytest settings
├── Justfile                    # Just task runner recipe file
├── README.md                   # Project documentation
├── src/
│   └── template_python/        # Source code (src layout)
│       ├── __init__.py
│       ├── __main__.py
│       ├── cli.py              # CLI entry point
│       ├── core.py             # Core module logic
│       └── gui.py              # PySide6 GUI interface (optional extra)
├── tests/                      # Pytest unit tests
│   ├── __init__.py
│   ├── conftest.py
│   ├── test_cli.py
│   ├── test_core.py
│   ├── test_gui.py             # Headless pytest-qt GUI tests
│   └── test_main.py
└── scripts/
    ├── run.py                  # Cross-platform fallback task runner
    └── init_project.py         # Project rename / bootstrap script

---

Quickstart

1. Prerequisites

uv (Required)

Install uv to manage Python versions, environments, dependencies, and builds:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

just (Optional, Recommended Task Runner)

If you prefer using just commands (just test, just check, etc.) instead of the pure Python fallback (python scripts/run.py), install it using one of the following methods:

Option A: Prebuilt Binaries & System Package Managers

• Windows:

  winget install Casey.Just
  # or: scoop install just
  # or: choco install just

• macOS:

  brew install just

• Linux:

  # Prebuilt binary installer script (all Linux distributions)
  curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin
  
  # Distribution package managers:
  # Ubuntu/Debian:
  sudo apt install just
  # Arch Linux:
  sudo pacman -S just
  # Fedora:
  sudo dnf install just

• Direct Binary Download: Download standalone precompiled binaries for your architecture directly from the Just GitHub Releases.

Option B: Via Rust / Cargo

If you have Rust/Cargo installed:

# Build from crates.io
cargo install just

# Or install precompiled binary quickly via cargo-binstall
cargo binstall just

2. Environment Setup

Clone this template and sync dependencies:

# Sync core environment and dev tools
uv sync

# Or sync with optional GUI support (PySide6)
uv sync --all-extras

uv will automatically download and install the required Python version if it's not already installed on your system.

To install as a package with optional GUI support via pip:

pip install "template-python[gui]"

---

Common Development Tasks

You can use just or the built-in pure Python task runner python scripts/run.py:

Action	With just	With python scripts/run.py	With direct uv
Install / Sync venv	just install	python scripts/run.py sync	uv sync --all-groups --all-extras
Lint & Style Check	just lint	python scripts/run.py lint	uv run ruff check . && uv run ruff format --check .
Auto-Format Code	just format	python scripts/run.py format	uv run ruff format . && uv run ruff check --fix .
Type Check	just typecheck	python scripts/run.py typecheck	uv run pyright
Run Tests	just test	python scripts/run.py test	uv run pytest
Run All Quality Checks	just check	python scripts/run.py check	(Runs lint, typecheck, test)
Build Wheel & Sdist	just build	python scripts/run.py build	uv build
Clean Artifacts	just clean	python scripts/run.py clean	(Removes dist/, cache, coverage)
Run CLI Application	just run	uv run template-python	uv run template-python
Run GUI Application	just gui	python scripts/run.py gui	uv run template-python-gui (or uv run template-python --gui)

---

Initializing a New Project

To rename this template into your own project:

uv run python scripts/init_project.py --name "my-tool" --description "My awesome CLI tool" --author "Your Name" --email "you@example.com"

This will automatically rename the src/template_python directory, adjust imports, update pyproject.toml, and update README.md.