python-quality

Python Quality

A consistent, low-friction baseline for new Python projects. Optimised for fast iteration plus principal-level quality signals (typed strictness on src/, ruff for everything else, tests that don't lie).

Throughout this skill, myapp is a placeholder for your package name. Replace it (and the myapp CLI / env / project names) with your own.

When To Use

• Scaffolding a new Python project (sections 1-4).
• Upgrading an older project's tooling (sections 2, 5-6).
• Adding CI (section 7).
• Setting up tests for an agentic / LLM project (section 6 has LLM-specific patterns).

1. Bootstrap the environment

Pick one environment manager and stay consistent across the team and CI. Both options below keep the dependency declaration in one place (pyproject.toml) and install the project itself in editable mode.

• uv: fastest resolver/installer; the modern default for pure-Python and most agentic/LLM projects.
• conda + pip: preferred when you need mixed-binary scientific stacks (CUDA, MKL, GDAL, etc.) or a non-pip-managed interpreter.

Option A: uv (recommended default)

# Create and use a project-local virtual env, pinned to a Python version
uv venv --python 3.11
source .venv/bin/activate          # Windows: .venv\Scripts\activate

# Install the project in editable mode with dev extras
uv pip install -e ".[dev]"

# Run anything inside the activated env
python -V
pytest
ruff check .
mypy src

uv reads the same pyproject.toml as everything else, resolves fast, and produces a reproducible uv.lock you can commit (uv lock).

Option B: conda + pip

Conda manages the Python interpreter and isolated environment; pip installs the project itself (editable) and all Python deps from pyproject.toml. This pairs well with mixed-binary scientific stacks while keeping the dependency declaration in one place.

# Create an isolated conda env (one-time, from the committed env file)
conda env create -f environment.yml

# Or, if you prefer to bootstrap before committing environment.yml:
#   conda create -y -n myapp python=3.11 pip

conda activate myapp

# Install the project in editable mode with dev extras
pip install -e ".[dev]"

# Run anything inside the activated env (no prefix needed)
python -V
pytest
ruff check .
mypy src