python-tooling

name	python-tooling
description	Detailed Python/uv conversion reference. Core conventions auto-loaded via SessionStart hook; invoke /dev-conventions:python-tooling for full conversion tables. Use when you need the complete uv command mapping, version pinning strategy, or lock file workflow.
metadata	{"author":"Fred Bliss","version":"0.6.0","last_verified":"2026-07-05T00:00:00.000Z"}

Python Tooling Conventions

Package management: uv

Always use uv for Python package and environment management. Never use pip, pip3, python -m pip, or bare python/python3.

Instead of	Use
pip install X	uv add X
pip install -r requirements.txt	uv sync (with pyproject.toml)
python script.py	uv run script.py
python -m pytest	uv run pytest
python -m venv .venv	uv venv
pip freeze > requirements.txt	uv lock (use pyproject.toml + uv.lock)

Version pinning

Project type	Strategy	Example
Application (deployed service, CLI, script)	Exact pin	uv add httpx==0.27.2
Library (published package, workspace member)	Floor pin	uv add 'httpx>=0.27'
Dev/test dependency	Floor pin	uv add --group dev 'pytest>=7.0'

When in doubt, pin exact. After adding any dependency, run uv lock --check to verify the lock file is consistent.

Lock file

uv.lock is machine-generated. Never hand-edit it. Update it only through uv lock or uv sync, and commit it alongside pyproject.toml. Use pyproject.toml + uv.lock, not requirements.txt.

JSON library choice (stdlib json vs orjson, etc.) is a per-project preference, not a universal convention — set it in the project's own CLAUDE.md or .claude/rules/ rather than assuming it here.