# Usage

## Install

Base install (OOXML + openpyxl):

```bash
pip install excelminer
```

Optional extras:

- Calamine used-range/value-block scanning:

```bash
pip install "excelminer[calamine]"
```

- Windows Excel COM automation (requires Microsoft Excel):

```bash
pip install "excelminer[com]"
```

## Quickstart (JSON)

```python
from excelminer import AnalysisOptions, analyze_to_dict

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

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

## Quickstart (Graph)

```python
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

### 1) Structural inventory only (fast)

```python
from excelminer import analyze_to_dict

result = analyze_to_dict("workbook.xlsx")
```

This typically yields:

- sheet inventory (OOXML)
- defined names (OOXML)
- connections (OOXML)

### 2) Formula inventory + dependencies (no Excel required)

```python
from excelminer import AnalysisOptions, analyze_to_dict

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

Formula text is read, not evaluated.

### 2a) Formula scoping and performance controls

```python
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` (1-based workbook order) instead of `formula_sheet_names` when you prefer positional targeting.

### 2b) Post-analysis distillation (optional)

If you want a condensed view (for large graphs), you can opt into the post-analysis distillation step:

```python
from excelminer import AnalysisOptions, analyze_workbook

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

### 3) Used-range “value blocks” (optional)

```python
from excelminer import AnalysisOptions, analyze_to_dict

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

`include_cells=True` enables the calamine backend (if installed) to compute used ranges and emit `cell_block` nodes with a small sample.

### 4) COM enrichment (Windows + Excel required)

COM is opt-in for modern OOXML files (`.xlsx/.xlsm/...`).

```python
from excelminer import AnalysisOptions, analyze_to_dict

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

## Backend ordering

By default, `excelminer` runs backends in this order:

1. OOXML zip parsing (structure)
2. VBA projects (module text extraction for `.xlsm/.xltm/.xlam`)
3. Power Query (queries from OOXML, when present; mashup containers detected best-effort)
4. Pivot tables (pivots + caches from OOXML, when present)
5. Calamine (used-range/value blocks; optional)
6. openpyxl (formula text)
7. Excel COM (Windows-only enrichment; opt-in)

You can override the backend list by passing `backends=` to `analyze_workbook()` / `analyze_to_dict()`.
