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, Excel write-back, 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.
The author-bindings agent skill is not in the library wheel. Agents load a
copied folder, not a Python extra. From a git clone or the excel-grapher sdist:
mkdir -p .agents/skills
cp -R skills/author-bindings .agents/skills/author-bindings
Cursor also loads .cursor/skills/author-bindings. Claude Code uses
.claude/skills/author-bindings. User-level installs go under
~/.agents/skills/author-bindings. The optional
excel-grapher-author-bindings package is only a file source for that copy.
High-level usage
The library supports a three-stage pipeline, plus Excel write-back of the same graph views used for Python export:
- Build a dependency graph from an Excel workbook (
excel_grapher.grapher). - Evaluate formulas with Excel semantics over that graph (
excel_grapher.evaluator.FormulaEvaluator). - Export standalone Python (
excel_grapher.exporter.CodeGenerator) and/or a new.xlsxfrom the sameGraphReadView(excel_grapher.grapher.write_workbook).
A minimal end‑to‑end example:
from pathlib import Path
from excel_grapher.grapher import create_dependency_graph, write_workbook
from excel_grapher.evaluator import FormulaEvaluator
from excel_grapher.exporter import CodeGenerator
from excel_grapher.series_bindings import load_series_bindings
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)
# 3a) Export a standalone Python package (requires series bindings)
bindings = load_series_bindings(workbook_path.with_suffix(".bindings.yaml"))
with CodeGenerator(graph) as gen:
modules = gen.generate_modules(
series_bindings=bindings,
bindings_workbook=workbook_path,
)
# 3b) Write a new workbook from the graph (or a ProjectionResult)
write_workbook(graph, Path("edited.xlsx"))
Series bindings
Optional sidecar manifests (.bindings.yaml) declare structured input/output APIs for exported
code — inverted-tree compute_* functions over named tensors and scalars (as_records for a Records
view). Validate sidecars from the shell with
excel-grapher bindings validate. Authoring agents should follow the
Authoring series bindings
skill and the same audit / burndown / upsert CLI. 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 |
| Authoring 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 |
| Graph evaluation | codegen_basics.md |
| Series bindings | series_bindings.md |
| Induced graph | induced_graph.md |
1 maintainer
Release files for excel-grapher 23.9.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| excel_grapher-23.9.0.tar.gz | 6.3 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| excel_grapher-23.9.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 7.0 MB
Release files / excel_grapher-23.9.0.tar.gz
| Download URL | excel_grapher-23.9.0.tar.gz |
|---|---|
| Size | 6.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
086273970f9a0ba5abb24f858a01d2aba7de1840fbf1fbbcccc296078b61015a
|
|
BLAKE2b-256 checksum How to use checksums |
bbebbb45a251cd3836e07bffa8337265d63540ebf9a3d1e6d42518ea4c25ec2c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 25, 2026.
Transparency logRelease files / excel_grapher-23.9.0-py3-none-any.whl
| Download URL | excel_grapher-23.9.0-py3-none-any.whl |
|---|---|
| Size | 654.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
445e57cdaff7957b01edc84c6852be9c71439043ae8914a771e8e573bd839daa
|
|
BLAKE2b-256 checksum How to use checksums |
38f97f8b9682918e9225100fab9d38ed9391d5ef696b5104048379eddc93082f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 25, 2026.
Transparency log
