python

name	python
description	Python conventions for this repo: virtual environments, type hints, pyproject.toml, and pytest patterns.
user-invocable	false
allowed-tools	["Bash(python *)","Bash(python3 *)","Bash(pip *)","Bash(uv *)","Bash(pytest *)"]

Python Project Guide

This repo uses Python. Apply these conventions.

Environment

• Always work inside a virtual environment — never install to the global interpreter.
• Prefer uv for speed (uv venv, uv pip install); fall back to python -m venv + pip.
• Activate before running: source .venv/bin/activate (Linux/macOS) or .venv\Scripts\activate (Windows).
• pyproject.toml is the single source of truth for dependencies and tool config.

Type Hints

• All function signatures must have type hints.
• Use from __future__ import annotations for forward references.
• Run mypy or pyright in CI — treat type errors as build failures.
• Use TypedDict for structured dict shapes; dataclass for mutable value objects.

Code Style

• Use ruff for linting and formatting: ruff check . and ruff format ..
• Maximum line length: 100 characters (configured in pyproject.toml).
• f-strings for interpolation — not % or .format().
• No bare except: — always name the exception: except ValueError as e:.

Testing

• Tests in tests/ directory; test files prefixed with test_.
• pytest -q for compact output; pytest -x to stop on first failure.
• Use pytest.fixture for setup/teardown — not setUp/tearDown (unittest style).
• Mock with unittest.mock.patch or pytest-mock's mocker fixture.
• Parametrize with @pytest.mark.parametrize rather than writing loop-based test cases.

Packaging

• Declare all dependencies in [project.dependencies] in pyproject.toml.
• Dev dependencies in [project.optional-dependencies] dev = [...].
• Do not use setup.py for new projects — pyproject.toml only.