python-project

What this skill does

# 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

| Topic | When to Load | File |
|-------|--------------|------|
| Pythonic style, conventions | Before generating code | `../references/pythonic-style.md` |
| Version-specific features | When adapting to Python version | `../references/version-features.md` |
| GitHub Actions, Docker, monorepo | CI/CD and advanced workflows | `references/ci-cd-workflows.md` |
| Full pyproject.toml templates | Complete configuration examples | `references/pyproject-templates.md` |

## Quick Start

```bash
# 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

```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

```bash
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

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

### Locking

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

## Python Version Management

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

## Running Code

```bash
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

```python
# 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()
```

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

```bash
uv sync && uv run my-tool greet World
```

## Building and Publishing

```bash
# 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

```ini
# ~/.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

```bash
# 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

| Task | Skill |
|------|-------|
| Writing tests | `python:python-testing` |
| Profiling, async | `python:python-performance` |
| Before claiming done | `core:verification` |

## 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