Python Starter Template

⚠️ TEMPLATE FILE - This is a template. After running make init NAME=your-project, update this file with your project's specific information.

A modern Python 3.13 project template with best practices, tooling, and CI/CD preconfigured.

Features

• Python 3.13 with type hints throughout
• uv for fast dependency management
• pytest with 96% minimum test coverage
• ruff for linting and formatting
• pyright for static type checking
• Pre-commit hooks to enforce code quality
• GitHub Actions CI for automated testing
• Project initialization via make init

Quick Start

# Clone the repository
git clone https://github.com/JoshCLWren/python-starter-template.git
cd python-starter-template

# Initialize with your project name
make init NAME=my-awesome-project

# Install dependencies
uv sync --group dev

# Activate the virtual environment (do this once per session)
source .venv/bin/activate

# Run tests
pytest

# Run your application (if main.py exists)
python main.py --name World --value 42

Development Workflow

First Time Setup

1. Rename the project:

   make init NAME=your-project-name

2. Install dependencies:

   uv sync --group dev

3. Activate the virtual environment:

   source .venv/bin/activate

Daily Development

Once the virtual environment is activated:

# Run the application (if main.py exists)
python main.py --name World --value 42

# Run tests
pytest

# Run tests with coverage report
pytest --cov-report=term-missing

# Run linting
make lint

# Format code with ruff
ruff format .

Make Commands

• make init NAME=your-project - Initialize with new project name
• make lint - Run all linting checks (ruff + pyright)
• make pytest - Run the test suite
• make venv - Create virtual environment
• make sync - Install/update dependencies

Project Structure

.
├── [[MODULE_NAME]]/          # Main package (replace [[MODULE_NAME]] manually as described in the init checklist)
│   ├── __init__.py
│   └── core.py             # Core business logic
├── tests/                   # Test suite
│   ├── conftest.py         # pytest fixtures
│   └── test_example.py     # Example tests
├── .github/
│   ├── actions/setup/       # CI setup action
│   └── workflows/ci.yml    # CI pipeline
├── scripts/
│   └── lint.sh            # Linting script
├── main.py                # Application entrypoint (removed for library packages)
├── pyproject.toml        # Project configuration
├── uv.lock               # Dependency lockfile
└── .gitignore           # Git ignore rules

Testing

The template uses pytest with coverage reporting:

# Run all tests
pytest

# Run with verbose output
pytest -v

# Run specific test file
pytest tests/test_example.py

# Run with coverage
pytest --cov=[[MODULE_NAME]] --cov-report=html

Coverage requirement: Minimum 96% (configured in pyproject.toml)

Code Quality

Linting

The project uses ruff for fast Python linting:

# Run linter
ruff check .

# Fix auto-fixable issues
ruff check --fix .

# Format code
ruff format .

Type Checking

Pyright provides static type checking:

# Run type checker
pyright .

Pre-commit Hook

A pre-commit hook is installed automatically that runs:

• Python compilation check
• Ruff linting
• Any type usage check (disallows Any type)
• Pyright type checking

The hook will block commits with issues. To test manually:

make githook

Configuration

Python Version

Default is Python 3.13. To change:

1. Update requires-python in pyproject.toml
2. Update target-version in pyproject.toml
3. Update .python-version file
4. Recreate venv: rm -rf .venv && uv venv

Coverage Threshold

Set in pyproject.toml:

[tool.pytest.ini_options]
addopts = ["--cov-fail-under=96"]

Lint Rules

Configure in pyproject.toml under [tool.ruff]:

[tool.ruff]
line-length = 100
target-version = "py313"

CI/CD

GitHub Actions runs on every push to main and on pull requests:

• Lint job: Runs ruff and pyright
• Tests job: Runs pytest with coverage

View pipeline status in the Actions tab of the repository.

Dependency Management

The project uses uv for fast dependency management:

# Add a new dependency
uv add package-name

# Add dev dependency
uv add --dev package-name

# Remove dependency
uv remove package-name

# Update dependencies
uv sync

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes
4. Run tests: pytest
5. Run linting: make lint
6. Commit with conventional commits
7. Push and create a pull request

License

MIT License - see LICENSE file for details

Credits

Template created by Josh Wren

Related

• uv Documentation
• pytest Documentation
• ruff Documentation
• pyright Documentation

📝 Post-Initialization Checklist

After running make init NAME=your-project, complete these steps to customize your project:

• Update project title and description in README.md
• Replace all [[MODULE_NAME]] references with your actual module name
• Update CI badge URLs to point to your repository (replace YOUR_USERNAME and YOUR_REPO)
• Update the features list to match your project's specific features
• Add your actual usage examples and documentation
• Update LICENSE if needed (currently MIT)
• Review and update AGENTS.md for your project's specific patterns
• Remove this checklist section from README.md