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/

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:

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

Released under the MIT license. Install from GitHub:

Using uv (recommended):

# Basic install (NumPy-free)
uv add git+https://github.com/Teal-Insights/excel-grapher

# With vectorized operator / SUMPRODUCT acceleration
uv add "excel-grapher[fast] @ 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 (includes `fast`)
uv add "excel-grapher[all] @ git+https://github.com/Teal-Insights/excel-grapher"

Using pip:

pip install git+https://github.com/Teal-Insights/excel-grapher

# With extras:
pip install "excel-grapher[fast] @ git+https://github.com/Teal-Insights/excel-grapher"
pip install "excel-grapher[networkx] @ git+https://github.com/Teal-Insights/excel-grapher"
pip install "excel-grapher[all] @ git+https://github.com/Teal-Insights/excel-grapher"

The default install is correct without NumPy. Install the fast extra when evaluating large workbooks and you want vectorized operator / SUMPRODUCT acceleration. Exported standalone code stays NumPy-free either way.

---

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:

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. Validate sidecars from the shell with excel-grapher bindings validate. See the Series bindings guide and Code export guide.

User guide

Detailed documentation lives in the User Guide:

Topic	Page
Dependency graphs	Read guide
Visualization	Read guide
Formula evaluation	Read guide
End-to-end demo	Read guide
Series bindings	Read guide
Code export	Read guide
Parity testing	Read guide
Contributing	Read guide

Examples

Hands-on walkthroughs (Markdown on GitHub):

Topic	Walkthrough
Graph extraction	extraction_basics.md
Code generation	codegen_basics.md
Series bindings	series_bindings.md
Induced graph	induced_graph.md