Metadata-Version: 2.4
Name: pyinc
Version: 3.1.0
Summary: A correctness-first incremental query engine for Python.
Project-URL: Homepage, https://github.com/Brumbelow/pyinc
Project-URL: Documentation, https://github.com/Brumbelow/pyinc/blob/main/docs/README.md
Project-URL: Repository, https://github.com/Brumbelow/pyinc
Project-URL: Issues, https://github.com/Brumbelow/pyinc/issues
Author-email: Andrew Brumbelow <andrew.brumbelow@gmail.com>
License: Apache-2.0
License-File: LICENSE
Keywords: backdating,incremental-computation,provenance,query-kernel,red-green,salsa
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Provides-Extra: bench
Requires-Dist: joblib>=1.3; extra == 'bench'
Provides-Extra: dev
Requires-Dist: hypothesis>=6.0; extra == 'dev'
Requires-Dist: joblib>=1.3; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: packaging>=24.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# pyinc

[![CI](https://github.com/Brumbelow/pyinc/actions/workflows/ci.yml/badge.svg)](https://github.com/Brumbelow/pyinc/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/pyinc)](https://pypi.org/project/pyinc/)
[![Python versions](https://img.shields.io/pypi/pyversions/pyinc)](https://pypi.org/project/pyinc/)
[![PyPI license](https://img.shields.io/pypi/l/pyinc)](https://pypi.org/project/pyinc/)
[![Lint: Ruff](https://img.shields.io/badge/lint-Ruff-D7FF64.svg)](https://docs.astral.sh/ruff/)

`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.

```console
python -m pip install pyinc
```

## Quick start

```python docs-check
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](https://github.com/Brumbelow/pyinc/blob/main/docs/getting-started.md)
walks through inputs, resources, modes, inspection, and a first declared-output
action.

## See it on a real workspace

![Editing pytest under pyinc's watcher](https://raw.githubusercontent.com/Brumbelow/pyinc/main/docs/assets/demo.gif)

`pyinc-tools` was pointed at a pinned checkout of pytest — nothing in it adapted
for `pyinc` — and watched while single files were edited;
[the demo page](https://github.com/Brumbelow/pyinc/blob/main/docs/demo.md) has
the clips.

## 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](https://github.com/Brumbelow/pyinc/blob/main/docs/kernel-contract.md)
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`:

| Package | Purpose | Start here |
|---|---|---|
| `pyinc` | Stable query kernel, resources, snapshots, artifact stores, and declared-output actions. | [Kernel contract](https://github.com/Brumbelow/pyinc/blob/main/docs/kernel-contract.md) |
| `pyinc.integrations` | Stable, frozen analysis results and high-level entrypoints for Python source, configuration, dependencies, symbols, and notebooks. | [Integration contract](https://github.com/Brumbelow/pyinc/blob/main/docs/integration-contract.md) |
| `pyinc_tools` | `pyinc-tools analyze`, a polling watcher, `WorkspaceSession`, and a stdio LSP server built on the integration API. | [Tooling guide](https://github.com/Brumbelow/pyinc/blob/main/docs/pyinc-tools-guide.md) |
| `pyinc_codegen` | JSON Schema to typed Python generation through the public query and action APIs. | [Codegen guide](https://github.com/Brumbelow/pyinc/blob/main/docs/codegen-guide.md) |

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](https://github.com/Brumbelow/pyinc/blob/main/docs/action-contract.md).

## Documentation

- [Getting started](https://github.com/Brumbelow/pyinc/blob/main/docs/getting-started.md) — build a small graph, add a tracked file, choose a mode, inspect work, and write a first action.
- [Demo](https://github.com/Brumbelow/pyinc/blob/main/docs/demo.md) — the watcher running on a real workspace.
- [Architecture](https://github.com/Brumbelow/pyinc/blob/main/docs/architecture.md) — package boundaries and how the kernel, integrations, tools, and codegen fit together.
- [Kernel contract](https://github.com/Brumbelow/pyinc/blob/main/docs/kernel-contract.md) — the normative soundness envelope.
- [Action contract](https://github.com/Brumbelow/pyinc/blob/main/docs/action-contract.md) — declared-output reconciliation.
- [Integration contract](https://github.com/Brumbelow/pyinc/blob/main/docs/integration-contract.md) — stable entrypoints, result types, supported shapes, and limits.
- [`pyinc-tools` guide](https://github.com/Brumbelow/pyinc/blob/main/docs/pyinc-tools-guide.md) and [LSP reference](https://github.com/Brumbelow/pyinc/blob/main/docs/lsp-reference.md) — CLI, editor setup, overlays, protocol methods, and user-visible limitations.
- [Integration authoring](https://github.com/Brumbelow/pyinc/blob/main/docs/integration-authoring.md) — the three-layer integration pattern.
- [Migrating from 2.x](https://github.com/Brumbelow/pyinc/blob/main/docs/migration-v3.md) — state cleanup and 3.0 API changes.

## Development

```console
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.
