python

Files (2)

• SKILL.md
• python-patterns.md · references/

SKILL.md (first lines)

# ABOUTME: Complete Python development with uv package manager, quality tools, and Docker
# ABOUTME: Modern workflow with uv, ruff, ty, pytest, Pydantic, and containerization

# Python Development

## Quick Reference

```bash
uv init myproject && cd myproject
uv add requests pydantic httpx
uv add --dev pytest ruff
uv sync --locked
uv run python main.py
uv run ruff check . && uv run ruff format --check . && uvx ty check && uv run pytest
```

**See also:** `_AST_GREP.md`, `_PATTERNS.md`, `source-control`

---

## Version (determine, don't assume)

See `../_LANG_COMMON.md`. Fetch the truth:

```bash
python3 --version                                                      # local interpreter
cat .python-version 2>/dev/null                                        # pin file (if present)
grep -E '^python' pyproject.toml 2>/dev/null                           # project manifest
curl -s https://endoflife.date/api/python.json | jq -r '.[0].latest'   # latest upstream stable
```

---

## Pre-Commit Verification (MANDATORY)

`make check && make test-e2e` must pass (enforced by the `pre-commit-gate` hook; see `../_LANG_COMMON.md`). What `make check` expands to for Python:

```bash
uv run ruff check .
uv run ruff format --check .
uvx ty check
uv run pytest --cov=myproject
```

---

## Package Management (uv)

**Use uv for all dependency management and execution, not pip, poetry or pipenv:** universal lockfile, fast resolver.

### pyproject.toml
```toml
[project]
name = "myproject"
requires-python = ">=<project floor>"   # from .python-version / endoflife.date, do not hardcode from memory
dependencies = ["httpx", "pydantic"]     # `uv add` writes the resolved lower bounds

[dependency-groups]
dev = ["pytest", "ruff"]

[tool.pytest.ini_options]
testpaths = ["tests"]
asyncio_mode = "auto"
```

---

## Code Quality

**Ruff config:**

```toml
[tool.ruff]
line-length = 100

[tool.ruff.lint]
select = ["E", "F", "I", "N", "W", "UP", "B", "C4", "SIM", "TCH", "RUF", "PERF"]
```

**Testing:** pytest with fixtures, AAA pattern, parametrize. Coverage via `--cov`.

---

## Pydantic v2

Use Pydantic for all external data boundaries (API I/O, config, queue payloads). Prefer `model_validate_json` over parse-then-validate. `Field(...)` for constraints, `@field_validator` for custom rules.

---

## Code Review Checklist

- [ ] Public functions have type hints, no unjustified `Any`
- [ ] Pydantic for external data, `X | None` not `Optional[X]`
- [ ] Ruff/type checker pass, no bare `except:`
- [ ] Context managers, `asyncio.gather()` for concurrency
- [ ] **Async is not concurrent**: no single stateful client (e.g. SQLAlchemy `AsyncSession`) shared across `gather()` tasks; one session per task via a factory. A shared session corrupts under concurrent use.
- [ ] **No CPU-bound work inside `async def`** without `asyncio.to_thread` (parsing, hashing, rendering): it blocks the event loop and serializes every concurrent task. Rule of thumb: a function that `await`s nothing probably needs `to_thread`.
- [ ] AAA tests, parametrized

For Docker, CI/CD, async patterns, and detailed testing examples, see `references/python-patterns.md`.

---

## Resources

**Astral**: [uv](https://docs.astral.sh/uv/), [Ruff](https://docs.astral.sh/ruff/), [ty](https://docs.astral.sh/ty/)
**Python**: [pytest](https://docs.pytest.org/), [Pydantic](https://docs.pydantic.dev/)

From maroffo/claude-forge, MIT.

More from maroffo/claude-forge