sheetdelta 0.1.0__tar.gz

sheetdelta-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e ".[dev]"
+      - run: python -m ruff check src tests
+      - run: python -m mypy
+      - run: python -m pytest

sheetdelta-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,20 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # mint the OIDC token PyPI trusts
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

sheetdelta-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/

sheetdelta-0.1.0/AGENTS.md

@@ -0,0 +1,61 @@
+# AGENTS.md
+
+Repository notes for anyone (human or agent) working on sheetdelta.
+
+## What this is
+
+A headless `.xlsx` differ. It compares two workbooks cell by cell, including
+the formulas and the values Excel cached, then follows each change through the
+workbook's dependency graph to report what it reaches downstream. Read-only,
+standard library only, no Excel.
+
+## Commands
+
+```console
+python -m pip install -e ".[dev]"   # install with dev tools
+python -m pytest                     # tests
+python -m ruff check src tests       # lint
+python -m mypy                       # types (strict on src)
+python -m build                      # wheel + sdist
+```
+
+Run all three checks before pushing; CI runs them on 3.10 through 3.13.
+
+## Layout
+
+```
+src/sheetdelta/
+  model.py       dataclasses: CellRef, RangeRef, Cell, Sheet, Workbook
+  errors.py      the exception hierarchy, all under SheetDeltaError
+  references.py  pulls cell/range references out of a formula
+  reader.py      parses .xlsx (zipfile + xml.etree)
+  differ.py      compares two workbooks, builds the dependency graph
+  audit.py       checks one workbook for broken and circular references
+  report.py      text and JSON rendering, exit codes
+  cli.py         argparse entry point
+```
+
+## Things worth knowing before you change something
+
+- **The reader has no dependencies on purpose.** It is `zipfile` and
+  `xml.etree`. Do not add openpyxl as a runtime dependency; it is a dev-only
+  tool used to write reference workbooks for `tests/test_interop.py`.
+- **Formulas are never evaluated.** Only the value Excel cached is compared.
+  There is no calculation engine and adding one would defeat the point.
+- **Ranges are never expanded.** `SUM(A:A)` covers a million cells; the graph
+  asks `RangeRef.contains` instead of materialising them.
+- **The dependency graph spans the whole workbook**, not one sheet, so a change
+  in one sheet is followed into the sheet that reads it. A formula that reads
+  its own cell (a total inside its own range) is excluded from the graph.
+- **Strings are not always in `<v>`.** openpyxl writes text as
+  `<is><t>...</t></is>`. Both shapes are handled in `_raw_value`; the interop
+  test is what caught this.
+- **Shared formulas must be shifted.** Excel stores a repeated formula once and
+  refers to it from other cells with relative offsets applied. See
+  `shift_formula`.
+
+## Test fixtures
+
+`tests/xlsx_fixtures.py` writes `.xlsx` files with the standard library, so the
+suite runs with no dependencies. `tests/test_interop.py` checks the same reader
+against workbooks written by openpyxl, and skips if openpyxl is absent.

sheetdelta-0.1.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-10-07
+
+First release.
+
+### Added
+
+- `sheetdelta diff OLD NEW`: compares two `.xlsx` workbooks cell by cell,
+  including formulas and the values Excel cached, and follows each change
+  through the workbook's dependency graph to the cells it reaches.
+- `sheetdelta audit FILE`: reports formulas whose references do not resolve --
+  a missing sheet, or a range outside the used area.
+- `--fail-on {never,any,breaking}` to set the exit code, so the tool works as a
+  CI check without extra scripting.
+- `--json` output for both subcommands.
+- A standard-library `.xlsx` reader: no runtime dependencies.
+- Rename detection, so renaming a sheet does not report every cell as changed.
+- Stale-cell detection, for a formula edited without the workbook being
+  recalculated.
+
+[0.1.0]: https://github.com/sqmyou/sheetdelta/releases/tag/v0.1.0

sheetdelta-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sqm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sheetdelta-0.1.0/PKG-INFO

@@ -0,0 +1,250 @@
+Metadata-Version: 2.5
+Name: sheetdelta
+Version: 0.1.0
+Summary: Diff Excel workbooks without Excel: formulas, values and dependency impact.
+Project-URL: Homepage, https://github.com/sqmyou/sheetdelta
+Project-URL: Repository, https://github.com/sqmyou/sheetdelta
+Project-URL: Changelog, https://github.com/sqmyou/sheetdelta/blob/main/CHANGELOG.md
+Author: sqm
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ci,cli,dependency-graph,diff,excel,spreadsheet,xlsx,xlsx-diff
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: openpyxl>=3.1; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# sheetdelta
+
+Compare two Excel workbooks and find out what actually changed.
+
+`sheetdelta` reads two `.xlsx` files, shows you the difference cell by cell, and
+then tells you which of those changes reach other cells. It runs on Linux, in
+CI, with no copy of Excel anywhere near it.
+
+```console
+$ sheetdelta diff budget_v1.xlsx budget_v2.xlsx
+budget_v1.xlsx  ->  budget_v2.xlsx
+
+Sheet 'Revenue'  (1 change, 1 breaking)
+  !! D12    formula changed
+          -  =SUM(D2:D11)
+          +  =SUM(D2:D13)
+        affects 3 cells downstream: Revenue!E12, Revenue!F12, Summary!B4
+
+Sheet 'Summary'  (1 change)
+  !  B7     value changed
+          -  1200
+          +  1450
+
+1 formula; 1 value across 2 edited sheet(s). 1 breaking change reaching 3 downstream cells.
+```
+
+## Why
+
+Two things go wrong when a spreadsheet changes and nobody looks closely.
+
+The first is the change itself. `git diff` on an `.xlsx` gives you binary
+noise, so the usual answer is to open both files side by side and squint.
+
+The second is worse. A formula edit looks harmless on the sheet you are
+looking at, but the cell feeds a summary three sheets away. The number that
+matters is now wrong, and nothing tells you.
+
+`sheetdelta` answers both. Every change is followed through the dependency
+graph, so a formula edit reports the cells it reaches, and a CI job can fail
+the build on exactly that.
+
+## Install
+
+```console
+pip install sheetdelta
+```
+
+No dependencies. The reader is `zipfile` and `xml.etree` from the standard
+library, so it drops into any environment, including a build container that
+has nothing but Python.
+
+## Usage
+
+### Compare two workbooks
+
+```console
+sheetdelta diff old.xlsx new.xlsx
+```
+
+Exit status is `0` when nothing breaking changed, `1` when something did, `2`
+on an error. That makes it a CI check without any extra scripting:
+
+```yaml
+- run: pip install sheetdelta
+- run: sheetdelta diff before.xlsx after.xlsx --fail-on breaking
+```
+
+`--fail-on` takes three values:
+
+| Value | Fails when |
+|---|---|
+| `breaking` (default) | a change reaches another cell |
+| `any` | anything changed at all |
+| `never` | never; useful for a report-only run |
+
+### Machine-readable output
+
+```console
+sheetdelta diff old.xlsx new.xlsx --json
+```
+
+```json
+{
+  "old": "budget_v1.xlsx",
+  "new": "budget_v2.xlsx",
+  "has_changes": true,
+  "summary": {
+    "cell_changes": {"formula": 1, "value": 1},
+    "breaking": 1
+  },
+  "sheets": [
+    {
+      "kind": "changed",
+      "name": "Revenue",
+      "old_name": "Revenue",
+      "changes": [
+        {
+          "cell": "Revenue!D12",
+          "a1": "D12",
+          "kind": "formula",
+          "severity": "breaking",
+          "detail": "formula changed",
+          "old": "=SUM(D2:D11)",
+          "new": "=SUM(D2:D13)",
+          "affected": ["Revenue!E12", "Revenue!F12", "Summary!B4"]
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Check one workbook
+
+```console
+sheetdelta audit workbook.xlsx
+```
+
+An audit looks for the two defects that make a workbook unsound:
+
+- a formula pointing at a sheet that does not exist, which Excel turns into
+  `#REF!` when it recalculates; and
+- a circular reference, a cell that depends on itself through a chain of other
+  cells, which Excel refuses to calculate at all.
+
+```console
+$ sheetdelta audit model.xlsx
+model.xlsx
+  3 sheet(s), 412 cell(s), 118 formula(s)
+
+1 broken reference(s):
+  !! C4     Removed Sheet!B2
+        sheet 'Removed Sheet' does not exist
+        ='Removed Sheet'!B2*1.2
+
+1 circular reference(s):
+  !! Revenue!D12 -> Revenue!E12 -> Summary!B4 -> Revenue!D12
+```
+
+A reference to a cell that is simply empty is not reported. That is normal in
+a spreadsheet, and flagging it would make the audit useless on real files.
+
+## What it reports
+
+| Change | Severity |
+|---|---|
+| Formula changed, and other cells read it | breaking |
+| Value changed, and other cells read it | breaking |
+| Cell deleted, and other cells read it | breaking |
+| Formula or value changed, nothing reads it | warning |
+| Formula changed but the cached value did not move | stale |
+| New cell | info |
+| Sheet added, removed or renamed | info |
+
+The **stale** case is worth explaining. Excel stores both a formula and the
+last value it calculated for it. When a file is edited by something that does
+not recalculate, the two disagree. Excel will happily show you the new
+formula next to the old number, which is a quiet way to ship a wrong total.
+`sheetdelta` flags it.
+
+A **rename** is detected by matching the contents of a removed sheet against
+an added one. Without that, renaming a sheet would look like every cell in it
+changed and bury the real diff.
+
+## What it does not do
+
+Being clear about this saves you time.
+
+- **It does not evaluate formulas.** There is no calculation engine, and
+  there will not be one. Excel already stored the value it last computed, and
+  that is what gets compared. This is why the tool needs no Excel and no
+  dependencies, and why it is fast on large files.
+- **It does not write or edit workbooks.** Read-only, by design.
+- **It only reads `.xlsx` and `.xlsm`.** The old `.xls` and binary `.xlsb`
+  formats are rejected with a clear message rather than half-parsed.
+- **It does not align rows across an insertion.** If a row is inserted near
+  the top, every cell below it reports as changed. Matching rows by content
+  is the hard part of spreadsheet diffing and is not implemented yet.
+- **It does not read VBA macros** inside `.xlsm` files.
+
+## Using it as a library
+
+```python
+from sheetdelta import diff_workbooks, read_workbook
+
+result = diff_workbooks(read_workbook("old.xlsx"), read_workbook("new.xlsx"))
+
+for change in result.breaking:
+    print(change.ref, "->", change.affected)
+    print("  was", change.old)
+    print("  now", change.new)
+```
+
+Every type is exported from the package root, and the whole thing is typed.
+
+## How it works
+
+An `.xlsx` file is a zip containing XML. `sheetdelta` reads the sheet list, the
+shared string table, the number formats and each sheet's cells, then stops.
+
+Each formula is scanned for the cells and ranges it mentions. That scan is
+more careful than it looks: `LOG10(...)` looks exactly like a reference to
+column LOG row 10, and `"see A1"` looks like a reference to A1. Both are
+handled, because a dependency graph built on false references is worse than
+no graph.
+
+References are kept as ranges rather than expanded. `SUM(A:A)` covers a
+million cells, and expanding it would cost more than the entire diff; the
+graph asks whether a range contains a cell instead.
+
+## Requirements
+
+Python 3.10 or newer. No runtime dependencies.
+
+## License
+
+MIT.

sheetdelta-0.1.0/README.md

@@ -0,0 +1,217 @@
+# sheetdelta
+
+Compare two Excel workbooks and find out what actually changed.
+
+`sheetdelta` reads two `.xlsx` files, shows you the difference cell by cell, and
+then tells you which of those changes reach other cells. It runs on Linux, in
+CI, with no copy of Excel anywhere near it.
+
+```console
+$ sheetdelta diff budget_v1.xlsx budget_v2.xlsx
+budget_v1.xlsx  ->  budget_v2.xlsx
+
+Sheet 'Revenue'  (1 change, 1 breaking)
+  !! D12    formula changed
+          -  =SUM(D2:D11)
+          +  =SUM(D2:D13)
+        affects 3 cells downstream: Revenue!E12, Revenue!F12, Summary!B4
+
+Sheet 'Summary'  (1 change)
+  !  B7     value changed
+          -  1200
+          +  1450
+
+1 formula; 1 value across 2 edited sheet(s). 1 breaking change reaching 3 downstream cells.
+```
+
+## Why
+
+Two things go wrong when a spreadsheet changes and nobody looks closely.
+
+The first is the change itself. `git diff` on an `.xlsx` gives you binary
+noise, so the usual answer is to open both files side by side and squint.
+
+The second is worse. A formula edit looks harmless on the sheet you are
+looking at, but the cell feeds a summary three sheets away. The number that
+matters is now wrong, and nothing tells you.
+
+`sheetdelta` answers both. Every change is followed through the dependency
+graph, so a formula edit reports the cells it reaches, and a CI job can fail
+the build on exactly that.
+
+## Install
+
+```console
+pip install sheetdelta
+```
+
+No dependencies. The reader is `zipfile` and `xml.etree` from the standard
+library, so it drops into any environment, including a build container that
+has nothing but Python.
+
+## Usage
+
+### Compare two workbooks
+
+```console
+sheetdelta diff old.xlsx new.xlsx
+```
+
+Exit status is `0` when nothing breaking changed, `1` when something did, `2`
+on an error. That makes it a CI check without any extra scripting:
+
+```yaml
+- run: pip install sheetdelta
+- run: sheetdelta diff before.xlsx after.xlsx --fail-on breaking
+```
+
+`--fail-on` takes three values:
+
+| Value | Fails when |
+|---|---|
+| `breaking` (default) | a change reaches another cell |
+| `any` | anything changed at all |
+| `never` | never; useful for a report-only run |
+
+### Machine-readable output
+
+```console
+sheetdelta diff old.xlsx new.xlsx --json
+```
+
+```json
+{
+  "old": "budget_v1.xlsx",
+  "new": "budget_v2.xlsx",
+  "has_changes": true,
+  "summary": {
+    "cell_changes": {"formula": 1, "value": 1},
+    "breaking": 1
+  },
+  "sheets": [
+    {
+      "kind": "changed",
+      "name": "Revenue",
+      "old_name": "Revenue",
+      "changes": [
+        {
+          "cell": "Revenue!D12",
+          "a1": "D12",
+          "kind": "formula",
+          "severity": "breaking",
+          "detail": "formula changed",
+          "old": "=SUM(D2:D11)",
+          "new": "=SUM(D2:D13)",
+          "affected": ["Revenue!E12", "Revenue!F12", "Summary!B4"]
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Check one workbook
+
+```console
+sheetdelta audit workbook.xlsx
+```
+
+An audit looks for the two defects that make a workbook unsound:
+
+- a formula pointing at a sheet that does not exist, which Excel turns into
+  `#REF!` when it recalculates; and
+- a circular reference, a cell that depends on itself through a chain of other
+  cells, which Excel refuses to calculate at all.
+
+```console
+$ sheetdelta audit model.xlsx
+model.xlsx
+  3 sheet(s), 412 cell(s), 118 formula(s)
+
+1 broken reference(s):
+  !! C4     Removed Sheet!B2
+        sheet 'Removed Sheet' does not exist
+        ='Removed Sheet'!B2*1.2
+
+1 circular reference(s):
+  !! Revenue!D12 -> Revenue!E12 -> Summary!B4 -> Revenue!D12
+```
+
+A reference to a cell that is simply empty is not reported. That is normal in
+a spreadsheet, and flagging it would make the audit useless on real files.
+
+## What it reports
+
+| Change | Severity |
+|---|---|
+| Formula changed, and other cells read it | breaking |
+| Value changed, and other cells read it | breaking |
+| Cell deleted, and other cells read it | breaking |
+| Formula or value changed, nothing reads it | warning |
+| Formula changed but the cached value did not move | stale |
+| New cell | info |
+| Sheet added, removed or renamed | info |
+
+The **stale** case is worth explaining. Excel stores both a formula and the
+last value it calculated for it. When a file is edited by something that does
+not recalculate, the two disagree. Excel will happily show you the new
+formula next to the old number, which is a quiet way to ship a wrong total.
+`sheetdelta` flags it.
+
+A **rename** is detected by matching the contents of a removed sheet against
+an added one. Without that, renaming a sheet would look like every cell in it
+changed and bury the real diff.
+
+## What it does not do
+
+Being clear about this saves you time.
+
+- **It does not evaluate formulas.** There is no calculation engine, and
+  there will not be one. Excel already stored the value it last computed, and
+  that is what gets compared. This is why the tool needs no Excel and no
+  dependencies, and why it is fast on large files.
+- **It does not write or edit workbooks.** Read-only, by design.
+- **It only reads `.xlsx` and `.xlsm`.** The old `.xls` and binary `.xlsb`
+  formats are rejected with a clear message rather than half-parsed.
+- **It does not align rows across an insertion.** If a row is inserted near
+  the top, every cell below it reports as changed. Matching rows by content
+  is the hard part of spreadsheet diffing and is not implemented yet.
+- **It does not read VBA macros** inside `.xlsm` files.
+
+## Using it as a library
+
+```python
+from sheetdelta import diff_workbooks, read_workbook
+
+result = diff_workbooks(read_workbook("old.xlsx"), read_workbook("new.xlsx"))
+
+for change in result.breaking:
+    print(change.ref, "->", change.affected)
+    print("  was", change.old)
+    print("  now", change.new)
+```
+
+Every type is exported from the package root, and the whole thing is typed.
+
+## How it works
+
+An `.xlsx` file is a zip containing XML. `sheetdelta` reads the sheet list, the
+shared string table, the number formats and each sheet's cells, then stops.
+
+Each formula is scanned for the cells and ranges it mentions. That scan is
+more careful than it looks: `LOG10(...)` looks exactly like a reference to
+column LOG row 10, and `"see A1"` looks like a reference to A1. Both are
+handled, because a dependency graph built on false references is worse than
+no graph.
+
+References are kept as ranges rather than expanded. `SUM(A:A)` covers a
+million cells, and expanding it would cost more than the entire diff; the
+graph asks whether a range contains a cell instead.
+
+## Requirements
+
+Python 3.10 or newer. No runtime dependencies.
+
+## License
+
+MIT.