---
name: python-development
description: Python ecosystem defaults and workflows using uv for packaging and ruff for linting/formatting
permalink: opencode-config/skills/python-development/skill
---

# Python Development

Load this skill when a repo or lane involves Python code (presence of `pyproject.toml`, `setup.py`, `requirements*.txt`, or `.py` files as primary source).

## Defaults

| Concern | Tool | Notes |
| --- | --- | --- |
| Package/venv management | `uv` | Replaces pip, pip-tools, and virtualenv |
| Linting + formatting | `ruff` | Replaces flake8, isort, black |
| Test runner | `pytest` | Unless repo already uses another runner |
| Type checking | `pyright` or `mypy` | Use whichever the repo already configures |

## Core Workflow

1. **Bootstrap** — `uv sync` (or `uv pip install -e ".[dev]"`) to create/refresh the venv.
2. **Lint** — `ruff check .` then `ruff format --check .` before committing.
3. **Test** — `pytest` with the repo's existing config. Follow TDD default policy.
4. **Add dependencies** — `uv add <pkg>` (runtime) or `uv add --dev <pkg>` (dev). Do not edit `pyproject.toml` dependency arrays by hand.
5. **Lock** — `uv lock` after dependency changes.

## Conventions

- Prefer `pyproject.toml` over `setup.py`/`setup.cfg` for new projects.
- Keep `ruff` config in `pyproject.toml` under `[tool.ruff]`.
- Use `uv run <cmd>` to execute tools inside the managed venv without activating it.
- Pin Python version via `.python-version` or `pyproject.toml` `requires-python`.

## Docker Integration

When the repo runs Python inside Docker, install dependencies with `uv pip install` inside the container. Mount a named volume for the uv cache to speed up rebuilds.

## Red Flags

- Using `pip install` directly instead of `uv`.
- Running `black` or `isort` when `ruff` is configured.
- Missing `uv.lock` after dependency changes.
- Editing dependency arrays in `pyproject.toml` by hand instead of using `uv add`.