Python Project Management

Modern Python project setup and dependency management with uv.

Before Writing Code

1. Read references/pythonic-style.md for style conventions
2. Check Python version: pyproject.toml → .python-version → .claude/python-version
3. If unknown, ask user once and store in .claude/python-version

Reference Files

Quick Start

# New project
uv init my-project && cd my-project
uv python pin 3.12
uv add fastapi pydantic
uv add --dev pytest ruff mypy

# Existing project
uv sync              # Install from pyproject.toml
uv sync --all-extras # Include optional deps

Project Structure

Source Layout (Recommended)

my-package/
├── pyproject.toml
├── README.md
├── src/
│   └── my_package/
│       ├── __init__.py
│       ├── core.py
│       └── py.typed
├── tests/
│   └── test_core.py
└── .python-version

Why src/ layout: The src/ layout prevents accidental imports from the source tree during testing. Without it, import my_package might resolve to the local directory instead of the installed package, masking missing __init__.py files or build configuration errors.

Minimal pyproject.toml

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "my-package"
version = "1.0.0"
requires-python = ">=3.10"
dependencies = ["requests>=2.28"]

[project.optional-dependencies]
dev = ["pytest>=7.0", "ruff>=0.1", "mypy>=1.0"]

[tool.setuptools.packages.find]
where = ["src"]

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

[tool.ruff.lint]
select = ["E", "F", "I", "UP"]

Dependency Management

Adding Packages

uv add requests              # Add to dependencies
uv add "django>=4.0,<5.0"    # With version constraint
uv add --dev pytest ruff     # Development dependencies
uv add --optional docs sphinx # Optional group
uv add -e ./local-package    # Editable local

Updating Packages

uv add --upgrade requests    # Upgrade specific
uv sync --upgrade            # Upgrade all
uv tree --outdated           # Show outdatable

Locking

uv lock                      # Generate uv.lock
uv lock --upgrade            # Regenerate with latest
uv sync --frozen             # Install exact versions (CI)

Python Version Management

uv python install 3.12       # Install Python
uv python pin 3.12           # Create .python-version
uv python list               # List installed

Running Code

uv run python app.py         # Run script
uv run pytest                # Run tests
uv run ruff check .          # Run linter
uv run --python 3.11 script.py  # Specific version

CLI Entry Points

With Click

# src/my_package/cli.py
import click

@click.group()
@click.version_option()
def cli():
    """My CLI tool."""

@cli.command()
@click.argument("name")
def greet(name: str):
    click.echo(f"Hello, {name}!")

def main():
    cli()

# pyproject.toml
[project.scripts]
my-tool = "my_package.cli:main"

uv sync && uv run my-tool greet World

Building and Publishing

# Build
uv build                     # Creates dist/*.whl and dist/*.tar.gz

# Test on TestPyPI first
uv publish --repository testpypi

# Publish to PyPI
uv publish

API Token Setup

# ~/.pypirc
[pypi]
username = __token__
password = pypi-...your-token...

Publishing Checklist

Before publishing:

• Tests passing (uv run pytest)
• Version updated in pyproject.toml
• CHANGELOG updated
• Build succeeds (uv build)
• Install works in clean venv
• Tested on TestPyPI first

Common Issues

# Wrong Python version
uv python pin 3.12 && uv venv --python 3.12

# Dependency conflict
uv lock --verbose

# Cache issues
uv cache clean

# Lockfile out of sync
uv lock --upgrade

Workflow Integration

Best Practices

1. Use src/ layout for libraries
2. Pin Python version with .python-version
3. Commit uv.lock for reproducibility
4. Use uv run instead of manual activation
5. Test installation in clean venv before publishing
6. Use TestPyPI before real PyPI
7. Automate publishing with GitHub Actions
8. Keep dependencies minimal
9. Use optional groups for dev/docs deps
10. Run uv sync --frozen in CI