excelminer Usage

## Install

### Base install

    pip install excelminer

Includes OOXML parsing + openpyxl.

### Optional extras

    pip install "excelminer[calamine]"

    pip install "excelminer[com]"

Calamine enables used-range blocks; COM enables Windows Excel automation.

## Quickstart (JSON)

    from excelminer import AnalysisOptions, analyze_to_dict

    result = analyze_to_dict(
        "workbook.xlsx",
        options=AnalysisOptions(include_formulas=True),
    )

    print(result["graph"]["stats"])

## Quickstart (Graph)

    from excelminer import AnalysisOptions, analyze_workbook

    graph, reports, ctx = analyze_workbook(
        "workbook.xlsx",
        options=AnalysisOptions(include_formulas=True),
    )

    print(graph.stats())
    print(reports)
    print(ctx.issues)

## Typical patterns

### Structural inventory (fast)

    from excelminer import analyze_to_dict

    result = analyze_to_dict("workbook.xlsx")

- Sheets, defined names, connections.

### Formula inventory

    from excelminer import AnalysisOptions, analyze_to_dict

    result = analyze_to_dict(
        "workbook.xlsx",
        options=AnalysisOptions(include_formulas=True),
    )

Formula text is extracted without evaluation.

### Formula scoping + performance

    from excelminer import AnalysisOptions, analyze_to_dict

    result = analyze_to_dict(
        "workbook.xlsx",
        options=AnalysisOptions(
            include_formulas=True,
            formula_sheet_names=["Inputs", "Model"],
            formula_scan_mode="auto",
            formula_large_sheet_cells=10_000,
            formula_skip_pivot_cells=True,
        ),
    )

Use `formula_sheet_indexes` for 1-based positions.

### Used-range blocks

    from excelminer import AnalysisOptions, analyze_to_dict

    result = analyze_to_dict(
        "workbook.xlsx",
        options=AnalysisOptions(include_cells=True, max_cells_per_sheet=50_000),
    )

Requires `excelminer[calamine]`.

### COM enrichment

    from excelminer import AnalysisOptions, analyze_to_dict

    result = analyze_to_dict(
        "workbook.xlsx",
        options=AnalysisOptions(include_com=True, include_formulas=True),
    )

Windows + Excel required. Opt-in for modern formats.

## Backend ordering

1. OOXML zip parsing (structure).
2. VBA projects (module text extraction).
3. Power Query + source inference.
4. Pivot tables + caches.
5. Calamine (used-range blocks).
6. Openpyxl (formula text).
7. Excel COM (Windows-only).

Override by passing `backends=` to `analyze_workbook()`.