# Python Conventions

> Python code conventions covering type hints, Ruff formatting/linting, mypy/pyright, pytest, async I/O, uv packaging, and dependency security scanning. Load when writing or reviewing Python code.

- Skill: `goldziher/python-conventions` (Agent Skill)
- Install (CLI): `npx skillmds@latest add goldziher/python-conventions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/goldziher/python-conventions/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: goldziher (https://skillmd.com/u/goldziher)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/goldziher/python-conventions

---


- Python 3.10+, type hints on all public APIs, avoid `Any` — use precise types, generics, or `typing.Protocol`.
- Formatting/linting: a fast linter/formatter (e.g., Ruff), zero warnings; strict static type checking (e.g., mypy or pyright). Security: a SAST tool (e.g., Bandit).
- Testing: `pytest` with function-based tests, `pytest-cov` (80%+), `hypothesis` for property-based.
- Error handling: specific exceptions only, never bare `except:`, `contextlib.suppress` for intentional ignoring.
- Dataclasses or Pydantic for structured data — avoid raw dicts for known schemas.
- `pathlib.Path` over `os.path` for filesystem operations. Google-style docstrings on public APIs.
- Async: `async`/`await` for I/O, never mix blocking and async, `asyncio.gather()` for concurrency.
- Package management: a fast, lockfile-based package manager (e.g., uv) with the lockfile committed, build with a PEP 517 backend (e.g., maturin or hatchling).
- Security: `pip-audit` for dependency CVE scanning. Zero tolerance for critical/high vulnerabilities.
- Logging: structured logging (key=value / JSON) — never f-strings in log calls.
- Pattern matching (`match`/`case`) for multi-branch type dispatch (3.10+).
- Anti-patterns: mutable default args, `import *`, global state, `time.sleep` in async.