excel-grapher 0.1.0__tar.gz

excel_grapher-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Coding agents
+.claude
+.codex
+*.prof.txt
+*.prof
+
+# Secrets
+.env
+# Great Docs build directory (ephemeral, do not commit)
+great-docs/
+
+# Great Docs versioned-build artifacts
+_great_docs_build/
+.great-docs-build/
+.great-docs-cache/
+.great-docs/

excel_grapher-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: excel-grapher
+Version: 0.1.0
+Summary: Build and analyze dependency graphs from Excel workbooks
+Project-URL: Homepage, https://github.com/Teal-Insights/excel-grapher
+Project-URL: Repository, https://github.com/Teal-Insights/excel-grapher
+Author-email: Teal Insights <info@tealinsights.com>
+License: Proprietary
+Keywords: dependency,excel,formula,graph,spreadsheet,transpiler
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary 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: Topic :: Office/Business :: Financial :: Spreadsheet
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: fastpyxl
+Requires-Dist: jsonschema>=4.26.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: pyyaml>=6.0.3
+Provides-Extra: all
+Requires-Dist: graphviz>=0.20; extra == 'all'
+Requires-Dist: networkx>=3.0; extra == 'all'
+Provides-Extra: networkx
+Requires-Dist: networkx>=3.0; extra == 'networkx'
+Provides-Extra: viz
+Requires-Dist: graphviz>=0.20; extra == 'viz'
+Description-Content-Type: text/markdown
+
+## `excel-grapher`
+
+Build and analyze dependency graphs from Excel workbooks, **evaluate formulas with Excel semantics**, and **export standalone Python code**.
+
+**Documentation:** [https://teal-insights.github.io/excel-grapher/](https://teal-insights.github.io/excel-grapher/)
+
+### Why this exists
+
+- **Transpilation support**: trace formula dependencies to enable Excel → Python translation.
+- **Interpretability**: visualize and sanity-check spreadsheet logic (GraphViz, Mermaid, NetworkX).
+- **Performance-minded**: focuses on targeted dependency closure from specific output cells/ranges.
+- **Excel semantics in Python**: run workbook logic in-process with a full Excel-like evaluator.
+- **Exportable**: emit standalone Python packages that embed only the runtime surface you need.
+
+---
+
+### Library layout
+
+The unified distribution is `excel-grapher` and exposes a single import package, `excel_grapher`, with five main subpackages:
+
+- `excel_grapher/core/` — shared semantic types, coercions, and scalar operators.
+- `excel_grapher/runtime/` — Excel-equivalent function implementations and runtime semantics.
+- `excel_grapher/grapher/` — workbook loading, graph extraction, and visualization logic.
+- `excel_grapher/evaluator/` — `FormulaEvaluator`: an Excel emulator for recomputing formulas in the extracted graph in Python.
+- `excel_grapher/exporter/` — `CodeGenerator`: an transpiler for exporting the extracted graph as a standalone Python library.
+
+Typical imports:
+
+```python
+from excel_grapher.grapher import create_dependency_graph, DependencyGraph
+from excel_grapher.evaluator import FormulaEvaluator
+from excel_grapher.exporter import CodeGenerator
+from excel_grapher.core import XlError  # and other shared types, if needed
+```
+
+---
+
+### Installation
+
+This is a proprietary package. Install from the private GitHub repository:
+
+**Using `uv` (recommended):**
+
+```bash
+# Basic install
+uv add git+https://github.com/Teal-Insights/excel-grapher
+
+# With NetworkX support
+uv add "excel-grapher[networkx] @ git+https://github.com/Teal-Insights/excel-grapher"
+
+# With all optional dependencies
+uv add "excel-grapher[all] @ git+https://github.com/Teal-Insights/excel-grapher"
+```
+
+**Using `pip`:**
+
+```bash
+pip install git+https://github.com/Teal-Insights/excel-grapher
+
+# With extras:
+pip install "excel-grapher[networkx] @ git+https://github.com/Teal-Insights/excel-grapher"
+```
+
+> **Note:** You must have access to the Teal-Insights GitHub organization and appropriate SSH keys or tokens configured.
+
+---
+
+### High-level usage
+
+The library supports a three-stage pipeline:
+
+1. **Build a dependency graph** from an Excel workbook (`excel_grapher.grapher`).
+2. **Evaluate formulas with Excel semantics** over that graph (`excel_grapher.evaluator.FormulaEvaluator`).
+3. **Export standalone Python code** that embeds only the required runtime surface (`excel_grapher.exporter.CodeGenerator`).
+
+A minimal end‑to‑end example:
+
+```python
+from pathlib import Path
+
+from excel_grapher.grapher import create_dependency_graph
+from excel_grapher.evaluator import FormulaEvaluator
+from excel_grapher.exporter import CodeGenerator
+
+workbook_path = Path("model.xlsx")
+targets = ["Sheet1!A10"]
+
+# 1) Build a dependency graph
+graph = create_dependency_graph(workbook_path, targets, load_values=True)
+print(len(graph))  # number of visited nodes
+
+# 2) Evaluate with Excel semantics
+with FormulaEvaluator(graph) as ev:
+    results = ev.evaluate(targets)
+
+# 3) Export standalone Python code
+code = CodeGenerator(graph).generate(targets)
+```
+
+### Series bindings
+
+Optional sidecar manifests (`.bindings.yaml`) declare structured input/output APIs for **exported**
+code — `set_*` and `compute_*` functions over `Records`. See the
+[Series bindings guide](https://teal-insights.github.io/excel-grapher/user-guide/series-bindings.html)
+and [Code export](https://teal-insights.github.io/excel-grapher/user-guide/export.html) guide.
+
+### User guide
+
+Detailed documentation lives in the [User Guide](https://teal-insights.github.io/excel-grapher/user-guide/dependency-graphs.html):
+
+| Topic | Page |
+| --- | --- |
+| Dependency graphs | [Read guide](https://teal-insights.github.io/excel-grapher/user-guide/dependency-graphs.html) |
+| Visualization | [Read guide](https://teal-insights.github.io/excel-grapher/user-guide/visualization.html) |
+| Formula evaluation | [Read guide](https://teal-insights.github.io/excel-grapher/user-guide/evaluator.html) |
+| End-to-end demo | [Read guide](https://teal-insights.github.io/excel-grapher/user-guide/end-to-end-demo.html) |
+| Series bindings | [Read guide](https://teal-insights.github.io/excel-grapher/user-guide/series-bindings.html) |
+| Code export | [Read guide](https://teal-insights.github.io/excel-grapher/user-guide/export.html) |
+| Parity testing | [Read guide](https://teal-insights.github.io/excel-grapher/user-guide/parity-testing.html) |
+| Contributing | [Read guide](https://teal-insights.github.io/excel-grapher/user-guide/contributing.html) |
+
+### Examples
+
+Hands-on walkthroughs (Markdown on GitHub):
+
+| Topic | Walkthrough |
+| --- | --- |
+| Graph extraction | [extraction_basics.md](https://github.com/Teal-Insights/excel-grapher/blob/main/examples/micro_workbooks/extraction_basics.md) |
+| Code generation | [codegen_basics.md](https://github.com/Teal-Insights/excel-grapher/blob/main/examples/micro_workbooks/codegen_basics.md) |
+| Series bindings | [series_bindings.md](https://github.com/Teal-Insights/excel-grapher/blob/main/examples/micro_workbooks/series_bindings.md) |
+| Induced graph | [induced_graph.md](https://github.com/Teal-Insights/excel-grapher/blob/main/examples/induced_graph/induced_graph.md) |

excel_grapher-0.1.0/README.md

@@ -0,0 +1,131 @@
+## `excel-grapher`
+
+Build and analyze dependency graphs from Excel workbooks, **evaluate formulas with Excel semantics**, and **export standalone Python code**.
+
+**Documentation:** [https://teal-insights.github.io/excel-grapher/](https://teal-insights.github.io/excel-grapher/)
+
+### Why this exists
+
+- **Transpilation support**: trace formula dependencies to enable Excel → Python translation.
+- **Interpretability**: visualize and sanity-check spreadsheet logic (GraphViz, Mermaid, NetworkX).
+- **Performance-minded**: focuses on targeted dependency closure from specific output cells/ranges.
+- **Excel semantics in Python**: run workbook logic in-process with a full Excel-like evaluator.
+- **Exportable**: emit standalone Python packages that embed only the runtime surface you need.
+
+---
+
+### Library layout
+
+The unified distribution is `excel-grapher` and exposes a single import package, `excel_grapher`, with five main subpackages:
+
+- `excel_grapher/core/` — shared semantic types, coercions, and scalar operators.
+- `excel_grapher/runtime/` — Excel-equivalent function implementations and runtime semantics.
+- `excel_grapher/grapher/` — workbook loading, graph extraction, and visualization logic.
+- `excel_grapher/evaluator/` — `FormulaEvaluator`: an Excel emulator for recomputing formulas in the extracted graph in Python.
+- `excel_grapher/exporter/` — `CodeGenerator`: an transpiler for exporting the extracted graph as a standalone Python library.
+
+Typical imports:
+
+```python
+from excel_grapher.grapher import create_dependency_graph, DependencyGraph
+from excel_grapher.evaluator import FormulaEvaluator
+from excel_grapher.exporter import CodeGenerator
+from excel_grapher.core import XlError  # and other shared types, if needed
+```
+
+---
+
+### Installation
+
+This is a proprietary package. Install from the private GitHub repository:
+
+**Using `uv` (recommended):**
+
+```bash
+# Basic install
+uv add git+https://github.com/Teal-Insights/excel-grapher
+
+# With NetworkX support
+uv add "excel-grapher[networkx] @ git+https://github.com/Teal-Insights/excel-grapher"
+
+# With all optional dependencies
+uv add "excel-grapher[all] @ git+https://github.com/Teal-Insights/excel-grapher"
+```
+
+**Using `pip`:**
+
+```bash
+pip install git+https://github.com/Teal-Insights/excel-grapher
+
+# With extras:
+pip install "excel-grapher[networkx] @ git+https://github.com/Teal-Insights/excel-grapher"
+```
+
+> **Note:** You must have access to the Teal-Insights GitHub organization and appropriate SSH keys or tokens configured.
+
+---
+
+### High-level usage
+
+The library supports a three-stage pipeline:
+
+1. **Build a dependency graph** from an Excel workbook (`excel_grapher.grapher`).
+2. **Evaluate formulas with Excel semantics** over that graph (`excel_grapher.evaluator.FormulaEvaluator`).
+3. **Export standalone Python code** that embeds only the required runtime surface (`excel_grapher.exporter.CodeGenerator`).
+
+A minimal end‑to‑end example:
+
+```python
+from pathlib import Path
+
+from excel_grapher.grapher import create_dependency_graph
+from excel_grapher.evaluator import FormulaEvaluator
+from excel_grapher.exporter import CodeGenerator
+
+workbook_path = Path("model.xlsx")
+targets = ["Sheet1!A10"]
+
+# 1) Build a dependency graph
+graph = create_dependency_graph(workbook_path, targets, load_values=True)
+print(len(graph))  # number of visited nodes
+
+# 2) Evaluate with Excel semantics
+with FormulaEvaluator(graph) as ev:
+    results = ev.evaluate(targets)
+
+# 3) Export standalone Python code
+code = CodeGenerator(graph).generate(targets)
+```
+
+### Series bindings
+
+Optional sidecar manifests (`.bindings.yaml`) declare structured input/output APIs for **exported**
+code — `set_*` and `compute_*` functions over `Records`. See the
+[Series bindings guide](https://teal-insights.github.io/excel-grapher/user-guide/series-bindings.html)
+and [Code export](https://teal-insights.github.io/excel-grapher/user-guide/export.html) guide.
+
+### User guide
+
+Detailed documentation lives in the [User Guide](https://teal-insights.github.io/excel-grapher/user-guide/dependency-graphs.html):
+
+| Topic | Page |
+| --- | --- |
+| Dependency graphs | [Read guide](https://teal-insights.github.io/excel-grapher/user-guide/dependency-graphs.html) |
+| Visualization | [Read guide](https://teal-insights.github.io/excel-grapher/user-guide/visualization.html) |
+| Formula evaluation | [Read guide](https://teal-insights.github.io/excel-grapher/user-guide/evaluator.html) |
+| End-to-end demo | [Read guide](https://teal-insights.github.io/excel-grapher/user-guide/end-to-end-demo.html) |
+| Series bindings | [Read guide](https://teal-insights.github.io/excel-grapher/user-guide/series-bindings.html) |
+| Code export | [Read guide](https://teal-insights.github.io/excel-grapher/user-guide/export.html) |
+| Parity testing | [Read guide](https://teal-insights.github.io/excel-grapher/user-guide/parity-testing.html) |
+| Contributing | [Read guide](https://teal-insights.github.io/excel-grapher/user-guide/contributing.html) |
+
+### Examples
+
+Hands-on walkthroughs (Markdown on GitHub):
+
+| Topic | Walkthrough |
+| --- | --- |
+| Graph extraction | [extraction_basics.md](https://github.com/Teal-Insights/excel-grapher/blob/main/examples/micro_workbooks/extraction_basics.md) |
+| Code generation | [codegen_basics.md](https://github.com/Teal-Insights/excel-grapher/blob/main/examples/micro_workbooks/codegen_basics.md) |
+| Series bindings | [series_bindings.md](https://github.com/Teal-Insights/excel-grapher/blob/main/examples/micro_workbooks/series_bindings.md) |
+| Induced graph | [induced_graph.md](https://github.com/Teal-Insights/excel-grapher/blob/main/examples/induced_graph/induced_graph.md) |

excel_grapher-0.1.0/excel_grapher/__init__.py

@@ -0,0 +1,146 @@
+"""excel_grapher: Build and analyze dependency graphs from Excel workbooks; evaluate formulas; export standalone Python.
+
+Public API is namespaced by role: excel_grapher.grapher, excel_grapher.evaluator, excel_grapher.exporter.
+Convenience re-exports below keep existing call patterns working.
+"""
+
+from . import exporter, grapher, series_bindings
+from .evaluator import (
+    CellValue,
+    ExcelRange,
+    FormulaEvaluator,
+    ParseError,
+    XlError,
+)
+from .exporter import CodeGenerator, to_web_viz_payload
+from .grapher import (
+    GRAPH_CACHE_SCHEMA_VERSION,
+    And,
+    CacheValidationPolicy,
+    Compare,
+    CycleError,
+    CycleReport,
+    DependencyGraph,
+    DynamicRefConfig,
+    DynamicRefError,
+    DynamicRefLimits,
+    DynamicRefTraceEvent,
+    DynamicRefTraceFn,
+    FromWorkbook,
+    GreaterThanCell,
+    GuardCellRef,
+    GuardExpr,
+    LightweightVizPayload,
+    Literal,
+    LocalForceSubgraph,
+    Node,
+    NodeHook,
+    NodeKey,
+    Not,
+    NotEqualCell,
+    Or,
+    RealBetween,
+    RealIntervalDomain,
+    ValidationResult,
+    WorkbookCalcSettings,
+    build_graph_cache_meta,
+    build_graph_cache_meta_portable,
+    create_dependency_graph,
+    format_cell_key,
+    format_key,
+    get_calc_settings,
+    list_dynamic_ref_constraint_candidates,
+    needs_quoting,
+    normalize_blank_range_specs,
+    save_graph_cache,
+    select_local_force_subgraph,
+    select_path_induced_subgraph,
+    to_graphviz,
+    to_mermaid,
+    to_networkx,
+    trace_dynamic_refs,
+    try_load_graph_cache,
+    validate_graph,
+    write_lightweight_viz_data,
+    write_lightweight_viz_html,
+    write_web_viz_html,
+)
+from .series_bindings import (
+    SeriesBindingsLoadError,
+    SeriesBindingsSchemaError,
+    ValidationReport,
+    bindings_canonical_sha256,
+    load_series_bindings,
+    resolve_series_bindings,
+    validate_series_bindings,
+)
+
+__all__ = [
+    "exporter",
+    "grapher",
+    "series_bindings",
+    "GreaterThanCell",
+    "NotEqualCell",
+    "RealBetween",
+    "RealIntervalDomain",
+    "And",
+    "GuardCellRef",
+    "Compare",
+    "CycleError",
+    "CycleReport",
+    "CodeGenerator",
+    "DependencyGraph",
+    "GRAPH_CACHE_SCHEMA_VERSION",
+    "CacheValidationPolicy",
+    "DynamicRefConfig",
+    "DynamicRefError",
+    "DynamicRefLimits",
+    "DynamicRefTraceEvent",
+    "DynamicRefTraceFn",
+    "FromWorkbook",
+    "trace_dynamic_refs",
+    "Literal",
+    "Node",
+    "NodeKey",
+    "Not",
+    "NodeHook",
+    "Or",
+    "GuardExpr",
+    "ValidationResult",
+    "WorkbookCalcSettings",
+    "create_dependency_graph",
+    "normalize_blank_range_specs",
+    "list_dynamic_ref_constraint_candidates",
+    "build_graph_cache_meta",
+    "build_graph_cache_meta_portable",
+    "format_cell_key",
+    "format_key",
+    "get_calc_settings",
+    "needs_quoting",
+    "LocalForceSubgraph",
+    "LightweightVizPayload",
+    "select_local_force_subgraph",
+    "select_path_induced_subgraph",
+    "to_graphviz",
+    "to_web_viz_payload",
+    "to_mermaid",
+    "to_networkx",
+    "write_lightweight_viz_data",
+    "write_lightweight_viz_html",
+    "write_web_viz_html",
+    "validate_graph",
+    "save_graph_cache",
+    "try_load_graph_cache",
+    "CellValue",
+    "ExcelRange",
+    "FormulaEvaluator",
+    "ParseError",
+    "XlError",
+    "SeriesBindingsLoadError",
+    "SeriesBindingsSchemaError",
+    "ValidationReport",
+    "bindings_canonical_sha256",
+    "load_series_bindings",
+    "resolve_series_bindings",
+    "validate_series_bindings",
+]

excel_grapher-0.1.0/excel_grapher/core/__init__.py

@@ -0,0 +1,71 @@
+"""Shared Excel semantics (types, coercions, operators).
+
+Representation-agnostic types and logic used by both the evaluator runtime
+and the standalone export runtime.
+"""
+
+from .address_keys import NormalizedAddress
+from .coercions import (
+    excel_casefold,
+    flatten,
+    get_error,
+    numeric_values,
+    to_bool,
+    to_int,
+    to_native,
+    to_number,
+    to_string,
+)
+from .operators import (
+    _xl_compare,
+    xl_add,
+    xl_concat,
+    xl_div,
+    xl_eq,
+    xl_ge,
+    xl_gt,
+    xl_iferror,
+    xl_le,
+    xl_lt,
+    xl_mul,
+    xl_ne,
+    xl_neg,
+    xl_percent,
+    xl_pos,
+    xl_pow,
+    xl_sub,
+)
+from .types import CellValue, ExcelRange, XlError
+
+__all__ = [
+    "NormalizedAddress",
+    "CellValue",
+    "ExcelRange",
+    "XlError",
+    "excel_casefold",
+    "flatten",
+    "get_error",
+    "numeric_values",
+    "to_bool",
+    "to_int",
+    "to_native",
+    "to_number",
+    "to_string",
+    "_xl_compare",
+    "xl_add",
+    "xl_concat",
+    "xl_div",
+    "xl_eq",
+    "xl_ge",
+    "xl_gt",
+    "xl_iferror",
+    "xl_le",
+    "xl_lt",
+    "xl_mul",
+    "xl_ne",
+    "xl_neg",
+    "xl_percent",
+    "xl_pos",
+    "xl_pow",
+    "xl_sub",
+]

excel_grapher-0.1.0/excel_grapher/core/address_keys.py

@@ -0,0 +1,131 @@
+"""Sheet-qualified address parsing and normalization helpers.
+
+These helpers are the single source of truth for translating between the
+external address strings that Excel users write (e.g. `'Sheet1!A1'`,
+`"'My Sheet'!B2"`) and the canonical :data:`NormalizedAddress` form stored in the
+`DependencyGraph` and emitted by generated code.
+
+They live in `excel_grapher.core` so that both the grapher and the
+evaluator/exporter can import them without violating layering rules.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Sequence
+from typing import TypeAlias
+
+from fastpyxl.utils.cell import column_index_from_string, coordinate_from_string
+
+# Canonical sheet-qualified cell (`Sheet1!B1`) or range (`Sheet1!C4:Sheet1!D4`).
+NormalizedAddress: TypeAlias = str
+
+
+def needs_quoting(sheet: str) -> bool:
+    """Return True if a sheet name must be wrapped in single quotes in a formula."""
+    return " " in sheet or "-" in sheet or "'" in sheet
+
+
+def _escape_sheet_for_formula(sheet: str) -> str:
+    """Escape apostrophes for use inside quoted sheet names."""
+    return sheet.replace("'", "''")
+
+
+def quote_sheet_if_needed(sheet: str) -> str:
+    """Return a sheet name quoted for formulas when quoting is required."""
+    if not needs_quoting(sheet):
+        return sheet
+    return "'" + _escape_sheet_for_formula(sheet) + "'"
+
+
+def parse_address(address: str) -> tuple[str, str]:
+    """Parse a sheet-qualified address into `(sheet, cell_coord)`.
+
+    The returned sheet name has any surrounding single quotes stripped and any
+    escaped apostrophes (`''`) unescaped to a single apostrophe.
+
+    Examples:
+        >>> parse_address("Sheet1!A1")
+        ('Sheet1', 'A1')
+        >>> parse_address("'My Sheet'!B2")
+        ('My Sheet', 'B2')
+        >>> parse_address("'It''s Data'!C3")
+        ("It's Data", 'C3')
+    """
+    if address.startswith("'"):
+        i = 1
+        while i < len(address):
+            if address[i] == "'":
+                if i + 1 < len(address) and address[i + 1] == "'":
+                    i += 2
+                    continue
+                break
+            i += 1
+        sheet = address[1:i].replace("''", "'")
+        rest = address[i + 1 :]
+        if rest.startswith("!"):
+            return sheet, rest[1:]
+        raise ValueError(f"Invalid address format: {address}")
+
+    if "!" in address:
+        sheet, cell = address.rsplit("!", 1)
+        return sheet, cell
+
+    raise ValueError(f"Address must be sheet-qualified: {address}")
+
+
+def format_key(sheet: str, cell: str) -> NormalizedAddress:
+    """Format a sheet and A1 cell coordinate into a canonical address string."""
+    return f"{quote_sheet_if_needed(sheet)}!{cell}"
+
+
+def format_cell_key(sheet: str, column: str, row: int) -> NormalizedAddress:
+    """Format a (sheet, column_letters, row) triple into a canonical address."""
+    return f"{quote_sheet_if_needed(sheet)}!{column}{row}"
+
+
+def normalize_key(key: str) -> NormalizedAddress:
+    """Normalize an address to canonical :data:`NormalizedAddress` form.
+
+    Unnecessary quoting is stripped; sheet names with spaces, hyphens, or
+    apostrophes are quoted. For single cells, the result matches `Node.key`.
+
+    Examples:
+        >>> normalize_key("'Sheet1'!A1")
+        'Sheet1!A1'
+        >>> normalize_key("'My Sheet'!B2")
+        "'My Sheet'!B2"
+    """
+    sheet, cell = parse_address(key)
+    return format_key(sheet, cell)
+
+
+def make_node_key_sort_key(
+    sheet_order: Sequence[str],
+) -> Callable[[NormalizedAddress], tuple[int, str, int, int]]:
+    """Build a key function for workbook-aligned `NodeKey` sorting.
+
+    Keys are ordered by:
+    1) workbook sheet order (from `sheet_order`),
+    2) row number,
+    3) column number.
+
+    Sheets not present in `sheet_order` are placed after known sheets and
+    sorted by sheet name.
+    """
+    sheet_rank = {name: idx for idx, name in enumerate(sheet_order)}
+    fallback_rank = len(sheet_rank)
+
+    def _sort_key(node_key: NormalizedAddress) -> tuple[int, str, int, int]:
+        sheet, cell = parse_address(node_key)
+        col_letters, row = coordinate_from_string(cell.replace("$", ""))
+        col = int(column_index_from_string(col_letters))
+        return (sheet_rank.get(sheet, fallback_rank), sheet, int(row), col)
+
+    return _sort_key
+
+
+def sort_node_keys(
+    node_keys: Iterable[NormalizedAddress], *, sheet_order: Sequence[str]
+) -> list[NormalizedAddress]:
+    """Return `node_keys` sorted by workbook sheet order, then row, then column."""
+    return sorted(node_keys, key=make_node_key_sort_key(sheet_order))