Skip to content
Snowpack

Code Quality

All code merged into Snowpack must pass linting, formatting, and strict type checking with zero violations. This page covers the tools and conventions enforced across the project.

Ruff — linting and formatting

Snowpack uses Ruff for both linting and code formatting. The configuration lives in pyproject.toml.

Terminal window
uv run ruff check .         # Lint the entire codebase
uv run ruff check --fix .   # Lint and auto-fix safe violations
uv run ruff format .        # Format all files

Key settings:

SettingValue
Line length120
Python target3.12
Enabled rule setsE, F, I, N, W, UP, B, SIM, TCH, RUF

All code must pass both ruff check and ruff format --check with zero violations before it can be merged.

mypy — strict type checking

Snowpack runs mypy in strict mode. Every function must have complete type annotations for all parameters and the return type.

Terminal window
uv run mypy snowpack/

Conventions:

  • Add from __future__ import annotations at the top of every module.
  • Use Protocol for interfaces (e.g., the QueryEngine protocol), not abstract base classes.
  • Use TYPE_CHECKING blocks for imports that are only needed at type-check time.

pytest — testing conventions

Tests live in the tests/ directory and mirror the snowpack/ package structure. For example, tests for snowpack/analyzer.py go in tests/unit/test_analyzer.py.

Terminal window
uv run pytest                   # Full suite
uv run pytest -x                # Stop on first failure
uv run pytest tests/unit/       # Unit tests only
uv run pytest --cov=snowpack    # With coverage

Mocking strategy:

  • AWS (Glue) — use moto to mock Glue API calls.
  • Spark / Thrift — use unittest.mock to mock SparkQueryEngine and Thrift connections.

Every new module must have corresponding tests before it can be merged.

Commit conventions

Snowpack follows Conventional Commits. Every commit message must start with one of these prefixes:

PrefixUse for
feat:New features or capabilities.
fix:Bug fixes.
refactor:Code restructuring with no behavior change.
test:Adding or updating tests.
docs:Documentation changes.
chore:Dependency updates, CI config, tooling.

Keep commits focused — each commit should represent one logical change. Avoid mixing unrelated changes in a single commit.