pyinc

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, stdlib-only, and has zero runtime dependencies. Python 3.11–3.14 are tested on Linux, macOS, and Windows.

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 instead of invalidating anything downstream.

For files, environment variables, and directories, use a Resource rather than reading ambient state directly inside a query. The getting-started guide walks through inputs, resources, modes, inspection, and a first declared-output action.

Correctness contract

pyinc guarantees from-scratch consistency: incremental evaluation matches a fresh evaluation on the same declared inputs and resources. That guarantee holds only when all three conditions hold:

1. Owned value boundaries. Query arguments, query results, and Input values are snapshot-safe or handled by a registered ValueAdapter.
2. Tracked ambient reads. External state read by a query goes through a Resource; reads the guard cannot intercept are declared with db.report_untracked_read(reason).
3. Deterministic queries. The same tracked dependencies produce a semantically equal result.

The kernel contract defines the exact value rules, intercepted operations, execution modes, durable checkpoint trust boundary, and documented limitations.

Packages

One distribution ships three top-level typed packages; the stable integration surface is a subpackage of pyinc:

Queries remain pure. Filesystem writes belong to the separate @action layer, which reconciles a complete desired output set with atomic file replacement, tamper repair, orphan cleanup, and dry-run planning. See the action contract.

Documentation

• Getting started — build a small graph, add a tracked file, choose a mode, inspect work, and write a first action.
• Architecture — package boundaries and how the kernel, integrations, tools, and codegen fit together.
• Kernel contract — the normative soundness envelope.
• Action contract — 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.
• Integration authoring — the three-layer integration pattern.
• Migrating from 2.x — state cleanup and 3.0 API changes.

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
python3 -m ruff check src tests bench scripts

Run python -m pyinc_tools --help for the installed command-line tools. The module form and the pyinc-tools console script are equivalent.