grapher.create_dependency_graph()

Build a dependency graph starting from target cells.

Usage

Source

grapher.create_dependency_graph(
    workbook,
    targets,
    *,
    max_depth=50,
    expand_ranges=True,
    max_range_cells=5000,
    hooks=None,
    load_values=True,
    dynamic_refs=None,
    use_cached_dynamic_refs=False,
    capture_dependency_provenance=False,
    blank_ranges=None,
    type_analysis_cache=None
)

targets accepts any mix of:

  • sheet-qualified single cells ("Sheet1!A1", "'My Sheet'!B2");
  • sheet-qualified rectangular ranges ("Sheet1!B12:F12", "Sheet1!A1:Sheet1!B2", "'My Sheet'!A1:B2"); and
  • defined names that resolve to a single cell or a rectangular range ("MyInput", "DataRange").

Range and named-range targets are expanded to one BFS root per cell (subject to max_range_cells); the deduplicated union seeds traversal. Targets that are neither sheet-qualified nor a known defined name raise ValueError.

Supports basic A1 references, sheet-qualified references, and dynamic references (OFFSET/INDIRECT). For OFFSET/INDIRECT:

  • use_cached_dynamic_refs=True: Resolve using cached workbook values (existing path). dynamic_refs is ignored.
  • use_cached_dynamic_refs=False (default), dynamic_refs=None: On any formula that contains OFFSET or INDIRECT requiring resolution, raise DynamicRefError. Callers can pass a DynamicRefConfig or set use_cached_dynamic_refs=True to avoid.
  • use_cached_dynamic_refs=False, dynamic_refs set: Resolve OFFSET/INDIRECT via the config’s cell_type_env and limits; missing or invalid domains raise DynamicRefError.

To build a config from a dict[str, type] constraints schema, use DynamicRefConfig.from_constraints.

When capture_dependency_provenance is True, each edge stores merged excel_grapher.grapher.dependency_provenance.EdgeProvenance under the \"provenance\" key in DependencyGraph.edge_attrs (how the dependency arises: direct reference, static range, dynamic OFFSET/INDIRECT).

blank_ranges is an optional iterable of sheet-qualified A1 rectangles (e.g. \"Sheet1!B2:D10\") treated as structurally empty: no nodes are created for those cells (edges into them are kept), and dynamic-ref leaf constraints are not required for addresses inside these ranges. Pair with the same declarations on excel_grapher.FormulaEvaluator and excel_grapher.exporter.codegen.CodeGenerator.generate for evaluator <-> export parity (consistent behavior between evaluation and generated code).

Cost model: constraint-based dynamic-ref expansion (dynamic_refs set, use_cached_dynamic_refs=False) runs expand_leaf_env_to_argument_env once per formula regardless of capture_dependency_provenance. A shared per-graph cache ensures provenance collection reuses the already-computed expansion instead of repeating it. Callers doing iterative constraint-tuning workflows can still set capture_dependency_provenance=False to avoid any provenance overhead (formula-string span collection, branch-union merging, etc.).