pyinc

Salsa-style red-green queries, hardened for Python's mutable runtime.

pyinc is a correctness-first incremental query engine for Python. Declare keyed inputs and pure queries, and it records the dependency graph while your code runs. On the next request it reuses unaffected work, recomputes affected queries, and backdates semantically equal results so downstream work stays valid. It is pure Python and stdlib-only, with zero runtime dependencies. Python 3.11–3.14 and the free-threaded 3.14t build are tested on Linux, macOS, and Windows. It is built to replace a hand-rolled caching layer and its cache-invalidation bugs, such as the editor still underlining an error you fixed a minute ago.

python -m pip install pyinc

Quick start

from pyinc import Database, Input, query

NAMES = Input[tuple[str, ...]]("example.names")


@query
def normalized_names(db: Database) -> tuple[str, ...]:
    return tuple(sorted({name.strip() for name in NAMES.read(db)}))


db = Database(mode="strict")
db.set(NAMES, (" Grace ", "Ada", "Ada"))
assert db.get(normalized_names) == ("Ada", "Grace")

db.set(NAMES, ("Grace", "Ada"))
assert db.get(normalized_names) == ("Ada", "Grace")
assert db.inspect(normalized_names).last_decision == "backdated"

The first request computes the result. The second input is different, so the query runs again, but its result is semantically equal. pyinc backdates that node, so everything downstream stays valid.

See it on a real workspace

pyinc-tools was pointed at a pinned checkout of pytest, with nothing in it adapted for pyinc, and watched while single files were edited. In one recorded run it took 109.08 s to analyze all 270 files from cold, then 632 ms to catch up after an edit. Timings are machine-specific. The demo page has the clips, the full provenance, and the deterministic work counts.

Documentation

• Getting started: build a small graph, add a tracked file, choose a mode, inspect work, and write a first action.
• Examples: small runnable scripts, including the calc worked example.
• FAQ: how this relates to Salsa, why not lru_cache, threading, scope, and when not to use it.
• Kernel contract: the from-scratch consistency guarantee, its three conditions, modes, checkpoints, and limitations. The action contract covers declared-output reconciliation.
• Integration contract: stable entrypoints, result types, supported shapes, and limits.
• pyinc-tools guide and LSP reference: CLI, editor setup, overlays, protocol methods, and user-visible limitations.
• Documentation index: every document, the package map, and the authoring and codegen guides.
• Releases and verification: signed tags, trusted publishing, and checking a download.

One distribution ships three top-level typed packages:

• pyinc: the stable query kernel, resources, snapshots, artifact stores, and declared-output actions
• pyinc.integrations: stable analysis results and entrypoints for Python source, configuration, dependencies, symbols, and notebooks
• pyinc_tools (unstable): pyinc-tools analyze, a polling watcher, WorkspaceSession, and a stdio LSP server
• pyinc_codegen (unstable): JSON Schema to typed Python generation

Development

git clone https://github.com/Brumbelow/pyinc.git
cd pyinc
python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install -e '.[dev]'
python3 scripts/check_docs.py
pytest -q
python3 -m mypy src tests bench scripts examples
python3 -m mypy --platform win32 src tests bench scripts examples
python3 -m ruff check src tests bench scripts examples