Modern Python Template

A fast, modern Python project template using the latest Rust-based tooling for maximum developer productivity.

✨ Features

• 🚀 uv - Lightning-fast Python package manager
• 🔧 ruff - Extremely fast Python linter and formatter
• 🧪 ty - Rust-based type checker (by Astral)
• 🐳 Docker support with live reload for development
• ⚡ GitHub Actions CI/CD with separate lint/typecheck/test workflows
• 📋 just for task automation
• 🎯 VS Code integration with recommended extensions
• 🔒 Python 3.12+ - Modern Python features

🚀 Quick Start

Using this template

1. Click "Use this template" on GitHub or clone:

   git clone <your-repo-url>
   cd <your-project>

2. Install dependencies:

   just install

3. Run the application:

   just run

4. Customize for your project:

   • Update pyproject.toml with your project details
   • Rename/modify main.py
   • Update this README

📋 Available Commands

Install just for task automation:

# Development
just install          # Install dependencies
just run              # Run the application
just test             # Run tests with pytest
just format           # Format code with ruff
just lint             # Lint code with ruff (use --fix to auto-fix)
just typecheck        # Type check with ty
just check            # Run lint + typecheck
just clean            # Clean cache files

# Docker
just build-docker     # Build Docker image
just run-docker       # Run with docker-compose (live reload)
just stop-docker      # Stop docker services

# Help
just help             # Show all available commands

🛠️ Development Setup

Prerequisites

• Python 3.12+
• uv (package manager)
• just (task runner)
• Docker (optional, for containerization)

Local Development

# Clone and setup
git clone <your-repo>
cd <your-project>
just install

# Start developing
just run              # Run locally
just test             # Run tests
just format           # Format before committing
just check            # Lint and type check

VS Code Setup

This template includes VS Code configuration:

1. Install recommended extensions (VS Code will prompt you)
2. Automatic formatting on save with ruff
3. Type checking with ty/pyrefly
4. Syntax highlighting for justfiles and TOML

🐳 Docker Development

For containerized development with live reload:

just build-docker     # Build the image
just run-docker       # Start with live reload

# Your code changes will be reflected immediately
# No need to rebuild for code changes

🧪 Testing

This template includes pytest for testing:

# Run tests
just test

# Run tests with verbose output
just test-verbose

# Run tests with coverage
just test-cov

Add your tests in test_*.py files:

# test_main.py
def test_basic():
    """Verify pytest is working."""
    assert True

def test_your_function():
    """Test your actual code."""
    from main import your_function
    assert your_function() == expected_result

🔄 CI/CD

This template includes GitHub Actions workflows:

• Lint (lint.yml) - Fast code style checking
• Type Check (typecheck.yml) - Type safety validation
• Test (test.yml) - Run your test suite

All workflows run on push/PR and provide fast feedback.

📁 Project Structure

.
├── .github/
│   └── workflows/           # CI/CD workflows
├── .vscode/
│   └── extensions.json      # Recommended VS Code extensions
├── .dockerignore           # Docker ignore rules
├── .gitignore              # Git ignore rules
├── Dockerfile              # Container definition
├── docker-compose.yaml     # Development container setup
├── justfile                # Task automation
├── main.py                 # Your application entry point
├── pyproject.toml          # Project configuration
├── README.md               # This file
└── uv.lock                # Dependency lock file

⚙️ Configuration

Python Dependencies

Add dependencies using uv:

# Add runtime dependencies
uv add requests pydantic

# Add development dependencies  
uv add --dev pytest-xdist black

# Add optional dependencies
uv add --optional web fastapi uvicorn

Then run:

just install

Code Quality

Configuration in pyproject.toml:

• ruff: Linting and formatting rules
• Python version: 3.12+ required

🚢 Deployment

Building for Production

# Build optimized Docker image
docker build -t your-app .

# Run in production mode
docker run -p 8000:8000 your-app

Environment Variables

Create .env file for local development:

# .env (not committed to git)
DATABASE_URL=sqlite:///local.db
DEBUG=true

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run quality checks: just check
5. Commit changes: git commit -m 'Add amazing feature'
6. Push to branch: git push origin feature/amazing-feature
7. Open a Pull Request

📝 Customization

For Your Project

1. Update pyproject.toml:

   [project]
   name = "your-project-name"
   description = "Your project description"
   authors = [{name = "Your Name", email = "your.email@example.com"}]

2. Rename main.py to match your application structure

3. Add your dependencies:

   uv add requests fastapi pytest

4. Update this README with your project-specific information

Project Structure Options

Consider organizing larger projects:

src/
└── your_package/
    ├── __init__.py
    ├── main.py
    ├── models/
    ├── api/
    └── utils/

🏆 Why This Stack?

• ⚡ uv: 10-100x faster than pip, handles virtual environments automatically
• 🦀 ruff: 10-100x faster than flake8/black, handles both linting and formatting
• 🔍 ty: Rust-based type checker by the same team as uv/ruff
• 🐳 Docker: Consistent environments, easy deployment
• 📋 just: Simple, fast alternative to make/npm scripts
• 🔄 GitHub Actions: Industry standard CI/CD

All core tools are written in Rust for maximum performance and reliability.

📄 License

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

🙏 Acknowledgments

• Astral for creating uv, ruff, and ty
• Casey Rodarmor for just
• The Rust and Python communities for amazing tooling

---

Happy coding! 🎉

Remember to:

• Replace yourusername/python-template in the badge URLs with your actual GitHub username/repo
• The workflow badges will show green ✅ once your GitHub Actions are running