---
name: excel-grapher
description: >
  Build and analyze dependency graphs from Excel workbooks. Use when writing Python code that uses the excel_grapher package.
license: Proprietary
compatibility: Requires Python >=3.11.
---

# excel_grapher

Build and analyze dependency graphs from Excel workbooks

## Installation

```bash
pip install excel-grapher
```

## API overview

### Public Modules

Namespaced public API surfaces

- `exporter.GoogleSeriesDocstringRenderer`
- `exporter.NumpySeriesDocstringRenderer`
- `exporter.PlainSeriesDocstringRenderer`
- `exporter.RstSeriesDocstringRenderer`
- `exporter.CodeGenerator`
- `exporter.IdentityTransitCompression`
- `exporter.FieldDoc`
- `exporter.SeriesBindingDocstringContext`
- `exporter.SeriesBindingDocstringContract`
- `exporter.SeriesFunctionDoc`
- `exporter.BaseProjectionManifest`
- `exporter.CollapsedGroup`
- `exporter.CompositeProjectionManifest`
- `exporter.FormulaRewrite`
- `exporter.ProjectedNodeSnapshot`
- `exporter.ProjectionResult`
- `exporter.SeriesDocstringRenderCallable`
- `exporter.SeriesDocstringRenderer`
- `exporter.SeriesBindingDocstringCallback`
- `exporter.ProjectionManifest`
- `exporter.ProjectionStep`
- `exporter.WebVizLayoutPlugin`
- `exporter.resolve_series_docstring_renderer`
- `exporter.list_series_docstring_callbacks`
- `exporter.register_series_docstring_callback`
- `exporter.resolve_series_docstring_callback`
- `exporter.unregister_series_docstring_callback`
- `exporter.to_web_viz_payload`
- `exporter.apply_projection`
- `exporter.build_forwarding_projection_manifest`
- `exporter.register_projection_manifest`
- `exporter.resolve_projection_manifest`
- `exporter.unregister_projection_manifest`
- `exporter.list_web_viz_layouts`
- `exporter.register_web_viz_layout`
- `exporter.resolve_web_viz_layout`
- `exporter.unregister_web_viz_layout`
- `exporter.SeriesDocstringRendererName`
- `exporter.SeriesDocstringRendererSpec`
- `exporter.SeriesBindingDocstringCallbackSpec`
- `exporter.WebVizPayload`
- `exporter.LAYOUT_FORCEATLAS2`
- `exporter.LAYOUT_GRAPHVIZ_DOT`
- `exporter.LAYOUT_GRAPHVIZ_SFDP`
- `exporter.LAYOUT_MULTIPARTITE`
- `exporter.LAYOUT_SPRING`
- `exporter.LAYOUT_STRATIFIED_MULTIPARTITE`
- `exporter.WebVizLayoutSpec`
- `grapher.GreaterThanCell`
- `grapher.NotEqualCell`
- `grapher.RealBetween`
- `grapher.RealIntervalDomain`
- `grapher.EdgeProvenance`
- `grapher.DynamicRefConfig`
- `grapher.DynamicRefLimits`
- `grapher.DynamicRefTraceEvent`
- `grapher.FromWorkbook`
- `grapher.LightweightVizLocalEdges`
- `grapher.LightweightVizModule`
- `grapher.LightweightVizModuleEdge`
- `grapher.LightweightVizNodeColumns`
- `grapher.LightweightVizPayload`
- `grapher.LightweightVizStats`
- `grapher.LocalForceSubgraph`
- `grapher.CycleReport`
- `grapher.DependencyGraph`
- `grapher.And`
- `grapher.Compare`
- `grapher.GuardExpr`
- `grapher.Literal`
- `grapher.Not`
- `grapher.Or`
- `grapher.GuardCellRef`
- `grapher.Node`
- `grapher.WorkbookCalcSettings`
- `grapher.GraphReadView`
- `grapher.CacheValidationPolicy`
- `grapher.DependencyCause`
- `grapher.DynamicRefError`
- `grapher.CycleError`
- `grapher.ValidationResult`
- `grapher.normalize_blank_range_specs`
- `grapher.create_dependency_graph`
- `grapher.list_dynamic_ref_constraint_candidates`
- `grapher.build_graph_cache_meta`
- `grapher.build_graph_cache_meta_portable`
- `grapher.save_graph_cache`
- `grapher.try_load_graph_cache`
- `grapher.infer_dynamic_index_targets`
- `grapher.infer_dynamic_indirect_targets`
- `grapher.infer_dynamic_offset_targets`
- `grapher.trace_dynamic_refs`
- `grapher.select_local_force_subgraph`
- `grapher.select_path_induced_subgraph`
- `grapher.to_graphviz`
- `grapher.to_mermaid`
- `grapher.to_networkx`
- `grapher.write_lightweight_viz_data`
- `grapher.write_lightweight_viz_html`
- `grapher.write_web_viz_html`
- `grapher.format_cell_key`
- `grapher.needs_quoting`
- `grapher.get_calc_settings`
- `grapher.validate_graph`
- `grapher.GRAPH_CACHE_SCHEMA_VERSION`
- `grapher.DynamicRefTraceFn`
- `grapher.NodeHook`
- `grapher.NodeKey`
- `grapher.format_key`
- `series_bindings.GoogleSeriesDocstringRenderer`
- `series_bindings.NumpySeriesDocstringRenderer`
- `series_bindings.PlainSeriesDocstringRenderer`
- `series_bindings.RstSeriesDocstringRenderer`
- `series_bindings.ResolutionIssue`
- `series_bindings.FieldDoc`
- `series_bindings.SeriesBindingDocstringContext`
- `series_bindings.SeriesBindingDocstringContract`
- `series_bindings.SeriesFunctionDoc`
- `series_bindings.SeriesDocstringRenderCallable`
- `series_bindings.SeriesDocstringRenderer`
- `series_bindings.SeriesBindingDocstringCallback`
- `series_bindings.SeriesBindingsLoadError`
- `series_bindings.SeriesBindingsSchemaError`
- `series_bindings.InputSeries`
- `series_bindings.InputSeriesCell`
- `series_bindings.LeafResolution`
- `series_bindings.OutputSeries`
- `series_bindings.OutputSeriesCell`
- `series_bindings.ResolutionReport`
- `series_bindings.SeriesResolution`
- `series_bindings.ValidationIssue`
- `series_bindings.ValidationReport`
- `series_bindings.WorkbookSeriesBindings`
- `series_bindings.emit_series_bindings_block`
- `series_bindings.bindings_canonical_sha256`
- `series_bindings.emit_compute_function`
- `series_bindings.emit_computes_block`
- `series_bindings.generate_computes_module`
- `series_bindings.resolve_series_docstring_renderer`
- `series_bindings.list_series_docstring_callbacks`
- `series_bindings.register_series_docstring_callback`
- `series_bindings.resolve_series_docstring_callback`
- `series_bindings.unregister_series_docstring_callback`
- `series_bindings.derive_input_series`
- `series_bindings.load_series_bindings`
- `series_bindings.merge_series_binding_documents`
- `series_bindings.parse_bindings_file`
- `series_bindings.has_input_direction`
- `series_bindings.has_output_direction`
- `series_bindings.merge_series_entries`
- `series_bindings.normalize_bindings_document`
- `series_bindings.normalize_series_entry`
- `series_bindings.derive_output_series`
- `series_bindings.expand_data_range`
- `series_bindings.expand_data_range_for_graph`
- `series_bindings.resolve_series_binding`
- `series_bindings.resolve_series_bindings`
- `series_bindings.format_schema_errors`
- `series_bindings.validate_bindings_document`
- `series_bindings.emit_setter_function`
- `series_bindings.emit_setter_helpers`
- `series_bindings.emit_setters_block`
- `series_bindings.generate_setters_module`
- `series_bindings.validate_series_bindings`
- `series_bindings.is_bind_implemented`
- `series_bindings.is_layout_implemented`
- `series_bindings.SeriesDocstringRendererName`
- `series_bindings.SeriesDocstringRendererSpec`
- `series_bindings.SeriesBindingDocstringCallbackSpec`
- `series_bindings.Record`
- `series_bindings.Records`
- `series_bindings.Scalar`
- `series_bindings.ValidationLevel`
- `series_bindings.IMPLEMENTED_BIND_KINDS`
- `series_bindings.IMPLEMENTED_LAYOUTS`
- `series_bindings.PLANNED_BIND_KINDS`
- `series_bindings.PLANNED_LAYOUTS`
- `series_bindings.SUPPORTED_SCHEMA_VERSIONS`

### Exporter API

Export and extension APIs under excel_grapher.exporter

- `exporter.CodeGenerator`
- `exporter.IdentityTransitCompression`
- `exporter.ProjectionStep`
- `exporter.ProjectionResult`
- `exporter.ProjectionManifest`
- `exporter.BaseProjectionManifest`
- `exporter.CompositeProjectionManifest`
- `exporter.ProjectedNodeSnapshot`
- `exporter.FormulaRewrite`
- `exporter.CollapsedGroup`
- `exporter.apply_projection`
- `exporter.build_forwarding_projection_manifest`
- `exporter.register_projection_manifest`
- `exporter.resolve_projection_manifest`
- `exporter.unregister_projection_manifest`
- `exporter.WebVizPayload`
- `exporter.to_web_viz_payload`
- `exporter.LAYOUT_FORCEATLAS2`
- `exporter.LAYOUT_GRAPHVIZ_DOT`
- `exporter.LAYOUT_GRAPHVIZ_SFDP`
- `exporter.LAYOUT_MULTIPARTITE`
- `exporter.LAYOUT_SPRING`
- `exporter.LAYOUT_STRATIFIED_MULTIPARTITE`
- `exporter.WebVizLayoutPlugin`
- `exporter.WebVizLayoutSpec`
- `exporter.list_web_viz_layouts`
- `exporter.register_web_viz_layout`
- `exporter.resolve_web_viz_layout`
- `exporter.unregister_web_viz_layout`
- `exporter.FieldDoc`
- `exporter.GoogleSeriesDocstringRenderer`
- `exporter.NumpySeriesDocstringRenderer`
- `exporter.PlainSeriesDocstringRenderer`
- `exporter.RstSeriesDocstringRenderer`
- `exporter.SeriesDocstringRenderCallable`
- `exporter.SeriesDocstringRenderer`
- `exporter.SeriesDocstringRendererName`
- `exporter.SeriesDocstringRendererSpec`
- `exporter.SeriesBindingDocstringCallback`
- `exporter.SeriesBindingDocstringCallbackSpec`
- `exporter.SeriesBindingDocstringContext`
- `exporter.SeriesBindingDocstringContract`
- `exporter.SeriesFunctionDoc`
- `exporter.list_series_docstring_callbacks`
- `exporter.register_series_docstring_callback`
- `exporter.resolve_series_docstring_callback`
- `exporter.unregister_series_docstring_callback`
- `exporter.resolve_series_docstring_renderer`

### Grapher Namespaced API

Public grapher APIs available under excel_grapher.grapher

- `grapher.DependencyCause`
- `grapher.EdgeProvenance`
- `grapher.LightweightVizLocalEdges`
- `grapher.LightweightVizModule`
- `grapher.LightweightVizModuleEdge`
- `grapher.LightweightVizNodeColumns`
- `grapher.LightweightVizStats`
- `grapher.GRAPH_CACHE_SCHEMA_VERSION`
- `grapher.DynamicRefTraceFn`
- `grapher.GraphReadView`
- `grapher.NodeHook`
- `grapher.NodeKey`
- `grapher.infer_dynamic_index_targets`
- `grapher.infer_dynamic_indirect_targets`
- `grapher.infer_dynamic_offset_targets`

### Series Bindings API

Series binding manifest and codegen APIs

- `series_bindings.InputSeries`
- `series_bindings.InputSeriesCell`
- `series_bindings.OutputSeries`
- `series_bindings.OutputSeriesCell`
- `series_bindings.Record`
- `series_bindings.Records`
- `series_bindings.Scalar`
- `series_bindings.FieldDoc`
- `series_bindings.GoogleSeriesDocstringRenderer`
- `series_bindings.NumpySeriesDocstringRenderer`
- `series_bindings.PlainSeriesDocstringRenderer`
- `series_bindings.RstSeriesDocstringRenderer`
- `series_bindings.SeriesDocstringRenderCallable`
- `series_bindings.SeriesDocstringRenderer`
- `series_bindings.SeriesDocstringRendererName`
- `series_bindings.SeriesDocstringRendererSpec`
- `series_bindings.SeriesBindingDocstringCallback`
- `series_bindings.SeriesBindingDocstringCallbackSpec`
- `series_bindings.SeriesBindingDocstringContext`
- `series_bindings.SeriesBindingDocstringContract`
- `series_bindings.SeriesFunctionDoc`
- `series_bindings.LeafResolution`
- `series_bindings.ResolutionIssue`
- `series_bindings.ResolutionReport`
- `series_bindings.SeriesResolution`
- `series_bindings.ValidationIssue`
- `series_bindings.ValidationLevel`
- `series_bindings.ValidationReport`
- `series_bindings.WorkbookSeriesBindings`
- `series_bindings.IMPLEMENTED_BIND_KINDS`
- `series_bindings.IMPLEMENTED_LAYOUTS`
- `series_bindings.PLANNED_BIND_KINDS`
- `series_bindings.PLANNED_LAYOUTS`
- `series_bindings.SUPPORTED_SCHEMA_VERSIONS`
- `series_bindings.bindings_canonical_sha256`
- `series_bindings.derive_input_series`
- `series_bindings.derive_output_series`
- `series_bindings.emit_compute_function`
- `series_bindings.emit_computes_block`
- `series_bindings.emit_series_bindings_block`
- `series_bindings.emit_setter_function`
- `series_bindings.emit_setter_helpers`
- `series_bindings.emit_setters_block`
- `series_bindings.generate_computes_module`
- `series_bindings.generate_setters_module`
- `series_bindings.has_input_direction`
- `series_bindings.has_output_direction`
- `series_bindings.merge_series_entries`
- `series_bindings.normalize_bindings_document`
- `series_bindings.normalize_series_entry`
- `series_bindings.expand_data_range`
- `series_bindings.expand_data_range_for_graph`
- `series_bindings.format_schema_errors`
- `series_bindings.list_series_docstring_callbacks`
- `series_bindings.load_series_bindings`
- `series_bindings.merge_series_binding_documents`
- `series_bindings.parse_bindings_file`
- `series_bindings.register_series_docstring_callback`
- `series_bindings.resolve_series_docstring_callback`
- `series_bindings.unregister_series_docstring_callback`
- `series_bindings.resolve_series_binding`
- `series_bindings.resolve_series_bindings`
- `series_bindings.resolve_series_docstring_renderer`
- `series_bindings.validate_bindings_document`
- `series_bindings.validate_series_bindings`
- `series_bindings.is_bind_implemented`
- `series_bindings.is_layout_implemented`

### Classes

Main classes provided by the package

- `CodeGenerator`: Generates Python code from Excel formulas
- `ParseError`: Raised when a formula cannot be parsed into an AST

### CodeGenerator Methods

Methods for the CodeGenerator class

- `CodeGenerator.__enter__`
- `CodeGenerator.__exit__`
- `CodeGenerator.derive_input_series`
- `CodeGenerator.classify_leaf_nodes`
- `CodeGenerator.generate`
- `CodeGenerator.generate_modules`

### Dataclasses

Dataclass definitions

- `And`: Logical AND
- `Compare`: Comparison: left op right
- `CycleReport`: Result of cycle analysis
- `DependencyGraph`: DependencyGraph(_nodes: 'dict[NodeKey, Node]' = <factory>, _edges: 'dict[NodeKey, set[NodeKey]]' = <factory>, _reverse_edges: 'dict[NodeKey, set[NodeKey]]' = <factory>, _guards: 'dict[EdgeKey, GuardExpr]' = <factory>, _edge_extra: 'dict[EdgeKey, dict[str, Any]]' = <factory>, _hooks: 'list[NodeHook]' = <factory>, leaf_classification: 'dict[str, str] | None' = None, sheet_order: 'list[str] | None' = None, sheet_bounds: 'dict[str, tuple[int, int]] | None' = None, named_ranges: 'dict[str, tuple[str, str]] | None' = None, named_range_ranges: 'dict[str, tuple[str, str, str]] | None' = None)
- `DynamicRefConfig`: Configuration for resolving OFFSET/INDIRECT via constraint-based inference
- `DynamicRefLimits`: Tuneable safety limits for dynamic-reference inference
- `DynamicRefTraceEvent`: A single trace event emitted during dynamic-ref inference
- `ExcelRange`: ExcelRange(sheet: 'str', start_row: 'int', start_col: 'int', end_row: 'int', end_col: 'int')
- `FormulaEvaluator`: FormulaEvaluator(graph: 'DependencyGraph', auto_detect_changes: 'bool' = True, eager_invalidation: 'bool' = True, on_cell_evaluated: 'Callable[[str, CellValue], None] | None' = None, iterate_enabled: 'bool' = False, iterate_count: 'int' = 100, iterate_delta: 'float' = 0.001, blank_ranges: 'tuple[str, ...] | None' = None)
- `FromWorkbook`: Metadata marker: resolve domain from the current cached workbook value
- `GreaterThanCell`: Metadata marker: the annotated cell is always greater than another cell
- `GuardCellRef`: A cell reference used in a condition
- `GuardExpr`: Base type for conditional dependency guards
- `LightweightVizPayload`: LightweightVizPayload(version: 'int', core: 'LightweightVizCore', overlays: 'tuple[LightweightVizOverlay, ...]', annotations: 'Mapping[str, Any] | None' = None, viewer_hints: 'Mapping[str, Any] | None' = None)
- `Literal`: A literal value in a condition
- `LocalForceSubgraph`: LocalForceSubgraph(node_ids: 'tuple[int, ...]', edges_from: 'tuple[int, ...]', edges_to: 'tuple[int, ...]', edges_guarded: 'tuple[bool, ...]', is_module_scope: 'bool', truncated: 'bool')
- `Node`: Workbook cell in a dependency graph
- `Not`: Logical negation
- `NotEqualCell`: Metadata marker: the annotated cell is never equal to another cell
- `Or`: Logical OR
- `RealBetween`: Real-valued interval constraint for Annotated float types (not enumerable for dynamic refs)
- `RealIntervalDomain`: Closed real-valued interval metadata; not enumerable for dynamic-ref branching
- `WorkbookCalcSettings`: WorkbookCalcSettings(iterate_enabled: 'bool', iterate_count: 'int', iterate_delta: 'float')

### DependencyGraph Methods

Methods for the DependencyGraph class

- `DependencyGraph.add_node`
- `DependencyGraph.__contains__`
- `DependencyGraph.__iter__`
- `DependencyGraph.__len__`
- `DependencyGraph.keys`
- `DependencyGraph.add_edge`
- `DependencyGraph.get_node`
- `DependencyGraph.get_dependencies`
- `DependencyGraph.get_dependents`
- `DependencyGraph.get_edge_attrs`
- `DependencyGraph.get_edge_guard`
- `DependencyGraph.set_node_value`
- `DependencyGraph.set_node_metadata`
- `DependencyGraph.register_hook`
- `DependencyGraph.leaves`
- `DependencyGraph.formula_nodes`
- `DependencyGraph.leaf_node_items`
- `DependencyGraph.formula_keys`
- `DependencyGraph.leaf_keys`
- `DependencyGraph.target_keys`
- `DependencyGraph.roots`
- `DependencyGraph.cycle_report`
- `DependencyGraph.evaluation_order`
- `DependencyGraph.compress_identity_transits`
- `DependencyGraph.__getstate__`
- `DependencyGraph.__setstate__`

### Enumerations

Enumeration types

- `CacheValidationPolicy`
- `XlError`

### Exceptions

Exception classes

- `CycleError`: Raised when a cycle prevents computing evaluation order
- `DynamicRefError`: Raised when dynamic reference analysis cannot proceed
- `SeriesBindingsLoadError`: Raised when binding files cannot be parsed or merged
- `SeriesBindingsSchemaError`: Raised when a binding manifest fails JSON Schema validation

### Named Tuples

Named tuple definitions

- `ValidationResult`: ValidationResult(is_valid, in_graph_not_in_chain, in_chain_not_in_graph, messages)

### Typed Dicts

TypedDict definitions

- `ValidationReport`

### Functions

Utility functions

- `bindings_canonical_sha256`: SHA-256 hex digest of the canonical binding manifest
- `build_graph_cache_meta`
- `build_graph_cache_meta_portable`: Build expected cache metadata without access to the workbook file
- `create_dependency_graph`: Build a dependency graph starting from target cells
- `format_cell_key`: Format a (sheet, column_letters, row) triple into a canonical address
- `get_calc_settings`: Extract calculation settings from xl/workbook.xml
- `list_dynamic_ref_constraint_candidates`: Return sorted leaf cells missing dynamic-ref constraint entries
- `load_series_bindings`: Load a binding sidecar file or directory of shards
- `needs_quoting`: Return True if a sheet name must be wrapped in single quotes in a formula
- `normalize_blank_range_specs`: Normalize a sequence of sheet-qualified range strings
- `resolve_series_bindings`: Resolve all series in a binding manifest for the given direction
- `save_graph_cache`
- `select_local_force_subgraph`
- `select_path_induced_subgraph`: Return the induced subgraph over nodes lying on directed source->target paths
- `to_graphviz`
- `to_mermaid`
- `to_networkx`: Convert a dependency graph to a NetworkX DiGraph
- `to_web_viz_payload`: Build a web-visualization payload from a NetworkX DiGraph
- `trace_dynamic_refs`: Activate *callback* as the dynamic-ref tracer for the enclosed block
- `try_load_graph_cache`
- `validate_graph`
- `validate_series_bindings`: Validate binding manifests against an extracted dependency graph
- `write_lightweight_viz_data`
- `write_lightweight_viz_html`
- `write_web_viz_html`: Write a web visualization HTML bundle from a web-viz payload

### Constants

Module-level constants and data

- `format_key`: Format a sheet and A1 cell coordinate into a canonical address string

## Resources

- [Full documentation](https://teal-insights.github.io/excel-grapher/)
- [llms.txt](llms.txt) — Indexed API reference for LLMs
- [llms-full.txt](llms-full.txt) — Comprehensive documentation for LLMs
- [Source code](https://github.com/Teal-Insights/excel-grapher)