python

name	python
description	Python scripting with uv package manager, stdlib-first, type hints, and error handling. Use when writing or editing .py files, working with uv, pyproject.toml, or venv.

Python

UV Package Manager (REQUIRED)

• Use uv for ALL Python project setup: uv init, uv add, uv run
• Never use pip install directly - use uv add <package>
• Lock dependencies: uv lock after adding packages
• Run scripts: uv run script.py
• Creating venv: uv venv (do NOT commit .venv/ to templates)
• pyproject.toml is the single source of truth for dependencies

UV Quick Reference

• uv run script.py - run a script
• uv run --with requests script.py - run with an ad-hoc dependency
• uv add requests - add a dependency to the project
• uv init --script foo.py - create a standalone script with inline metadata
• uv run python -m ast foo.py >/dev/null - verify syntax without writing __pycache__

Inline Script Metadata

For standalone scripts, declare deps inline in a # /// script block at the top of the file. uv reads it, sets up a venv on demand, and runs the script with the declared deps available.

# /// script
# requires-python = ">=3.12"
# dependencies = ["requests"]
# ///

This means a single .py file with its declared deps can be uv run script.py’d without any surrounding project - useful for throw-away scripts, samples, and CI tooling.

Build Backend

For pure-Python packages, use uv_build in pyproject.toml:

[build-system]
requires = ["uv_build>=0.9.28,<0.10.0"]
build-backend = "uv_build"

Faster and more reliable than legacy setuptools/hatchling for pure-Python projects.

Stdlib First

• PREFER standard library modules - only add external packages when stdlib can't do the job
• Common stdlib modules: os, sys, json, csv, pathlib, argparse, hashlib, base64, sqlite3, datetime, subprocess, shutil, tempfile, logging, urllib, http.server, xml, re, collections, itertools, functools, typing, dataclasses
• Only add packages when needed: requests (complex HTTP), Pillow (images), pyyaml (YAML), qrcode (QR codes), rich (fancy terminal)
• Document WHY each external dependency is needed in README.md

Script Structure

• Start with #!/usr/bin/env python3 shebang
• Use """docstring""" at module level describing purpose
• Use if __name__ == "__main__": guard
• Use argparse for command-line arguments (not sys.argv directly)
• Use type hints on function signatures
• Use pathlib.Path instead of os.path for file paths
• Return exit codes: sys.exit(0) for success, sys.exit(1) for failure

Error Handling

• Use try/except for file I/O, network, and external operations
• Never use bare except: - always specify exception types
• Use logging module instead of print() for diagnostics
• Log errors with logger.error() to stderr
• Use FileNotFoundError, PermissionError, json.JSONDecodeError specifically

Safety Rules

• Never use eval() or exec() on user input
• Validate all file paths before reading/writing
• Use pathlib.Path.resolve() to prevent path traversal
• Never store secrets in code - use environment variables
• Hash passwords with hashlib + salt, never store plaintext
• Use subprocess.run() with shell=False (never shell=True with user input)

Testing

• Use assert statements for simple validation
• Use doctest for embedded tests in docstrings
• Use unittest or pytest for structured tests
• Smoke test pattern: run script with --help, check exit code 0
• Test with sample input files in a test-data/ directory

Template Integration

• Each template has: README.md, script.py, smoke-test.py, pyproject.toml (if deps needed)
• NO .venv/ in templates - it's in .gitignore
• .python-version file specifies Python version
• Templates go in templates/python/<name>/