This scaffold provides a production-ready starting point for any new Python project, with best practices for dependency management, CI, and collaboration baked in.
my-python-project/
├── .github/
│ └── workflows/
│ └── ci.yml
├── src/
│ └── my_python_project/
│ └── __init__.py
├── tests/
│ └── test_example.py
├── .gitignore
├── .pre-commit-config.yaml
├── CONTRIBUTING.md
├── pyproject.toml
└── README.md
# Python Project Template (uv)
[](https://github.com/your-org/your-repo/actions/workflows/ci.yml)
[](https://github.com/astral-sh/ruff)
[](https://github.com/psf/black)
[](pyproject.toml)
[](LICENSE)
A production-ready Python project starter with `uv` dependency management, linting, formatting, testing, CI, and contribution guidelines all baked in.
This template provides a standardized, best-practice foundation for building robust Python applications. The goal is to eliminate setup friction and enforce quality from the very first commit.
### ✨ Features
* **Dependency Management**: `uv` for high-performance, reproducible environments with `uv.lock` as the authoritative source.
* **Code Quality**: `Ruff` for linting and `Black` for formatting, enforced by pre-commit hooks.
* **Testing**: `Pytest` setup and ready to go.
* **CI/CD**: GitHub Actions workflow that validates lock file freshness, lints, and runs tests across multiple Python versions.
* **Collaboration**: A pre-filled `CONTRIBUTING.md` that codifies development rules.
* **Guardrails**: Pre-commit hooks to prevent committing stale lock files or unformatted code.
### 🚀 How to Use This Template
1. **Create a new repository**:
Click the "**Use this template**" button at the top of this page.
2. **Clone your new repository**:
```bash
git clone [https://github.com/your-org/your-new-repo.git](https://github.com/your-org/your-new-repo.git)
cd your-new-repo
```
3. **Run the setup script** (or perform a find-and-replace):
Replace all instances of `my-python-project` with your new project's name.
4. **Follow the Quick Start**:
The `README.md` below contains the quick start guide for setting up your virtual environment and getting started.
---
# My Python Project
A brief description of your project.
## 🛠️ Environment and Dependency Management
This project uses **[uv](https://github.com/astral-sh/uv)** for high-performance Python packaging and dependency management. The `uv.lock` file is the single source of truth for reproducible environments.
[](CONTRIBUTING.md#dependency-management)
### Quick Start
1. **Install `uv`**:
Follow the [official installation instructions](https://github.com/astral-sh/uv#installation).
2. **Create and sync your environment**:
```bash
# Create and activate the virtual environment
uv venv
# Activate on macOS/Linux
source .venv/bin/activate
# Activate on Windows
.venv\Scripts\activate
# Install all dependencies from the lock file
uv sync --group dev --group test
```
3. **Run commands**:
Use `uv run` to execute scripts or tools within the managed environment.
```bash
uv run pytest
```
For detailed rules on how to add, remove, or update dependencies, please see our **[Contributing Guide](CONTRIBUTING.md#dependency-management)**.# Contributing to [Project Name]
First off, thank you for considering contributing! This document outlines our development process and guidelines to make contributing as easy and transparent as possible.
## Getting Started
1. **Create a virtual environment:**
We use `uv` to manage our environment and dependencies.
```bash
# Create the virtual environment
uv venv
# Activate it (macOS/Linux)
source .venv/bin/activate
# Activate it (Windows)
.venv\Scripts\activate
```
2. **Install dependencies:**
Sync your environment with the project's lock file. This command installs all dependencies, including those for testing and linting.
```bash
uv sync --group test --group lint
```
## Dependency Management
This project uses **uv** for fast, reproducible dependency management. To maintain stability, all collaborators **must** adhere to the following rules.
**Key Rule**: **DO NOT** edit the `[project.dependencies]` section of `pyproject.toml` or the `uv.lock` file manually. Use the `uv` command-line tool for all changes.
* **To add a dependency:**
```bash
# Add to main dependencies
uv add <package-name>
# Add to a development or test group
uv add --group dev <package-name>
```
* **To remove a dependency:**
```bash
uv remove <package-name>
```
* **To update a dependency:**
```bash
# This updates the lock file to the latest version allowed by pyproject.toml
uv lock --upgrade-package <package-name>
```
## Code Style & Quality
* **Linting**: We use `Ruff` to check for code quality.
```bash
uv run ruff check .
```
* **Formatting**: We use `Black` to format our code.
```bash
uv run black .
```
## Running Tests
All pull requests must include tests for new features or bug fixes.
* **Run the full test suite:**
```bash
uv run pytest
```
## Submitting a Pull Request
1. Fork the repository and create a new branch from `main`.
2. Make your changes and add/update tests as appropriate.
3. Ensure the test suite passes (`uv run pytest`).
4. Ensure your code is formatted and linted (`uv run black .` and `uv run ruff check .`).
5. Push your branch and open a pull request, linking any relevant issues.[project]
name = "my-python-project"
version = "0.1.0"
description = "A short description of the project."
requires-python = ">=3.11,<3.13"
dependencies = [
# Add your main dependencies here, e.g., "fastapi>=0.110"
]
[project.urls]
Homepage = "https://github.com/your-org/my-python-project"
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[dependency-groups]
dev = [
"ruff",
"black",
]
test = [
"pytest",
]
lint = [
"ruff",
]repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.6.0
hooks:
- id: check-yaml
- id: end-of-file-fixer
- id: trailing-whitespace
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.5.0
hooks:
- id: ruff
args: [--fix]
- id: ruff-format
- repo: local
hooks:
- id: uv-lock-check
name: Check uv.lock freshness
entry: uv lock --check
language: python
types: [toml]
files: ^pyproject\.toml$name: CI
on:
push:
branches: [ "main" ]
pull_request:
branches: [ "main" ]
jobs:
build-and-test:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: ["3.11", "3.12"]
steps:
- uses: actions/checkout@v4
- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python-version }}
- name: Install uv
run: curl -LsSf https://astral.sh/uv/install.sh | sh
- name: Check lock file freshness
run: ~/.local/bin/uv lock --check
- name: Install dependencies
run: ~/.local/bin/uv sync --group dev --group test
- name: Lint with Ruff
run: ~/.local/bin/uv run ruff check .
- name: Run tests
run: ~/.local/bin/uv run pytest# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
share/python-wheels/
*.egg-info/
.installed.cfg
*.egg
MANIFEST
# Virtual Environment
.venv/
venv/
ENV/
env/
env.bak/
venv.bak/
# uv
.uv_cache/