Contributing to vgi-rpc¶

Prerequisites¶

Python 3.13+
uv package manager

Dev Setup¶

git clone https://github.com/Query-farm/vgi-rpc-python.git
cd vgi-rpc-python
uv sync --all-extras

This installs the package in editable mode with all optional dependencies (HTTP, S3, GCS, CLI, external storage, OpenTelemetry) plus dev tools (pytest, mypy, ruff, ty, mutmut).

If you change entry points or add new modules, reinstall:

uv sync --all-extras --reinstall-package vgi-rpc

Running Tests¶

# Full suite (includes mypy type checking and ruff linting via pytest plugins)
uv run pytest

# Single test
uv run pytest tests/test_rpc.py::test_name -v

# Skip mypy/ruff checks for faster iteration
uv run pytest tests/test_rpc.py -v -o "addopts="

# Coverage report (80% minimum, branch coverage)
uv run pytest --cov=vgi_rpc

Tests must complete in 50 seconds or less.

Pre-Commit Checklist¶

Run all four checks before committing:

# 1. Static type checking (strict mode)
uv run mypy vgi_rpc/

# 2. ty type checking
uv run ty check

# 3. Tests (includes mypy + ruff via pytest plugins)
uv run pytest

# 4. Format
uv run ruff format vgi_rpc/ tests/

All four must pass. Do not skip any.

Code Style¶

Rule	Value
Line length	120
Quote style	Double quotes
Python target	3.13+
Type checking	mypy strict + ty
Linter	ruff (E, F, I, UP, B, SIM, D, RUF, PERF)
Docstrings	Google style with Args/Returns/Raises

Avoid Any types. Strict mypy is enforced and must stay clean.

Lint and format manually¶

uv run ruff check vgi_rpc/ tests/
uv run ruff format vgi_rpc/ tests/

Pull Request Expectations¶

One concern per PR. Keep changes focused: a bug fix, a feature, or a refactor -- not all three.
Tests required. New features need tests. Bug fixes need a regression test.
Type-safe. All new code must pass mypy --strict and ty check cleanly.
Docstrings. Public APIs need Google-style docstrings.
No unrelated changes. Don't re-format files you didn't change or add drive-by refactors.
PR description. Explain what changed and why. Link related issues.