Skip to content

Document how to inspect and consume diffs programmatically - #206

Open
Shaisolaris wants to merge 1 commit into
trailofbits:masterfrom
Shaisolaris:docs/programmatic-diff-185
Open

Shaisolaris wants to merge 1 commit into
trailofbits:masterfrom
Shaisolaris:docs/programmatic-diff-185

Conversation

@Shaisolaris

@Shaisolaris Shaisolaris commented Oct 11, 2026 •

Copy link
Copy Markdown

Fixes #185.

The guide now shows how to inspect a diff without printing it. The new section explains removed subtrees, insertions stored on parents, changed scalar Match edits, string edits, replacements, and edit/edit_list. It includes a summary iterator and an example using get_all_edit_contexts to locate changes within dictionary entries.

The examples explain that the edited tree keeps source values and that context paths start at the destination root, then follow sub-edit source nodes. They cover insertion and removal endpoints and the limits on deriving list positions. The API docstrings now match this behavior and explain how to use to_obj(), including its stored values and differences between node types.

Pytest runs all 36 examples, covering insertion into an empty container, changes to root scalars and strings, removed subtrees, wholesale replacement, unchanged descendants with unset edits, and context identities. The guide is included in source distributions so the test also runs from an extracted sdist. Deliberately breaking insertion traversal, non-zero-cost detection, or destination-value lookup makes the test fail.

The branch starts from upstream master at deefed18 and is independent of #189, #190, and #205. No overlapping documentation work was found in the open PRs.

Local validation with Python 3.13.15 and dependencies installed using uv sync --frozen --extra dev --offline:

  • GRAPHTAGE_TEST_SEED=185 python -m pytest -q: 274 passed, 1,770 subtests passed; one existing BuildOptions spelling warning.
  • ruff check graphtage test docs bindist: passed with locked Ruff 0.16.7.
  • make -C docs html SPHINXOPTS="-W --keep-going": passed with locked Sphinx 8.2.3.
  • uv build --offline: sdist and wheel built; the guide regression passed from the extracted sdist.
  • uv lock --check --offline and git diff --check: passed.

@Shaisolaris
Shaisolaris marked this pull request as ready for review October 11, 2026 21:48

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document how to consume a diff programmatically

1 participant