name: python-project
description: Set up a modern Python project with uv, pyproject.toml, and ruff. Use when creating a new Python project, package, or CLI tool.

Python Project Setup

Modern Python project setup using uv package manager and pyproject.toml.

Creating a New Project

1. Create project directory and initialize git:

mkdir myproject && cd myproject
git init

1. Copy pyproject.toml and edit:
2. Change name to your project name
3. Update description
4. Add dependencies to dependencies list

5. Update [project.scripts] for CLI entry point

6. Copy gitignore to .gitignore

7. Copy AGENTS.md to project root (AI agent instructions)

8. Create package structure:

mkdir myproject
touch myproject/__init__.py

1. Initialize uv and install:

uv sync

Project Structure

myproject/
├── myproject/
│   ├── __init__.py
│   ├── __main__.py      # For `python -m myproject`
│   └── cli.py           # CLI entry point
├── pyproject.toml
├── .gitignore
├── AGENTS.md            # AI agent instructions
└── uv.lock              # Generated by uv

Entry Points

CLI script (installed as command)

[project.scripts]
myproject = "myproject.cli:main"

main.py (for python -m)

from myproject.cli import main

if __name__ == "__main__":
    main()

Code Quality

Format and lint with ruff:

ruff format .
ruff check . --fix

Type Annotations

Required for all new code:

def greet(name: str) -> None:
    print(f"Hello, {name}")

def add(a: int, b: int) -> int:
    return a + b

Use Python 3.11+ built-in generics: list[str], dict[str, int], not List, Dict.

Structured Data

Use TypedDict for dictionary shapes (e.g., JSON, API responses):

from typing import TypedDict

class Ticket(TypedDict):
    key: str
    summary: str
    status: str
    assignee: str | None

Use dataclass for objects with behavior or defaults:

from dataclasses import dataclass

@dataclass
class Config:
    site: str
    email: str
    timeout: int = 30

Common Commands

uv sync              # Install dependencies
uv add requests      # Add dependency
uv run pytest        # Run tests
uv build             # Build package

GitHub Actions: Publish to PyPI

Setup Steps

1. Copy publish.yml to .github/workflows/publish.yml

2. Configure PyPI Trusted Publisher (no API tokens needed):

3. Go to https://pypi.org/manage/account/publishing/

4. Add new pending publisher:

   • PyPI project name: myproject
   • Owner: your GitHub username
   • Repository: your repo name
   • Workflow name: publish.yml
   • Environment: pypi

5. Create GitHub environment:

6. Go to repo Settings → Environments

7. Create environment named pypi

8. Release workflow:

9. Create a GitHub release with tag like v0.1.0
10. Action automatically extracts version from tag and publishes

Publishing a Release

Create a GitHub release using gh release create:

gh release create v0.1.0 --title "v0.1.0" --notes "Release notes here"

Or use --generate-notes to auto-generate from commits:

gh release create v0.1.0 --generate-notes

GitHub Actions will automatically update the version in pyproject.toml and publish to PyPI.

Do NOT manually edit the version in pyproject.toml - it is managed by GitHub Actions.