# toucantoco/fastexcel architecture

> Architecture diagram of the GitHub repository toucantoco/fastexcel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/toucantoco/fastexcel
- Repository: https://github.com/toucantoco/fastexcel

## Overview

FastExcel reads Excel workbooks in Rust and exposes sheet and table data to Rust and Python callers. The main workflow is to open a workbook, select a sheet or named table, configure headers, rows, columns, and types, then convert the resulting data for Arrow-compatible consumers. The README also documents lazy loading and zero-copy PyCapsule exchange, plus optional Polars and Pandas/PyArrow integrations. The map follows the documented workflow and sampled module boundaries; conversion details beyond those excerpts rely on documented capabilities.

Main entry points: [`src/types/excelsheet/mod.rs`](https://github.com/toucantoco/fastexcel/blob/main/src/types/excelsheet/mod.rs) (Sheet loader), [`src/types/exceltable/mod.rs`](https://github.com/toucantoco/fastexcel/blob/main/src/types/exceltable/mod.rs) (Table loader), [`src/types/excelreader/mod.rs`](https://github.com/toucantoco/fastexcel/blob/main/src/types/excelreader/mod.rs) (Workbook reader), [`src/lib.rs`](https://github.com/toucantoco/fastexcel/blob/main/src/lib.rs) (Rust API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["User APIs"]
  node_py_api["Python facade<br/>[__init__.py]"]
  node_rust_api["Rust API<br/>[lib.rs]"]
end

subgraph group_workbook["Workbook Access"]
  node_reader["Workbook reader<br/>[mod.rs]"]
  node_sheet["Sheet loader<br/>[mod.rs]"]
  node_table["Table loader<br/>[mod.rs]"]
  node_defined_names["Defined names<br/>[mod.rs]"]
end

subgraph group_processing["Data Processing"]
  node_options["Load options<br/>[mod.rs]"]
  node_column_info["Column metadata<br/>[mod.rs]"]
  node_dtype["Type inference<br/>[mod.rs]"]
  node_cell_data["Cell extraction<br/>[mod.rs]"]
  node_series["Typed columns<br/>[mod.rs]"]
end

subgraph group_outputs["Data Interchange"]
  node_arrow["Arrow exchange<br/>[python.rs]"]
  node_capsule["PyCapsule exchange<br/>[python.rs]"]
  node_polars["Polars output<br/>[polars.rs]"]
  node_pandas["Pandas output<br/>[__init__.py]"]
end

node_caller(("Python or Rust caller"))
node_excel["Excel workbook"]
node_consumer(("Arrow-compatible consumer"))
node_polars_user(("Polars consumer"))
node_pandas_user(("Pandas consumer"))

node_caller -->|"calls"| node_py_api
node_caller -->|"calls"| node_rust_api
node_excel -->|"reads"| node_reader
node_py_api -->|"calls native API"| node_rust_api
node_rust_api -->|"opens workbook"| node_reader
node_reader -->|"loads sheet"| node_sheet
node_reader -->|"loads table"| node_table
node_reader -->|"lists names"| node_defined_names
node_sheet -->|"applies options"| node_options
node_table -->|"applies options"| node_options
node_sheet -->|"builds metadata"| node_column_info
node_table -->|"builds metadata"| node_column_info
node_column_info -->|"infers types"| node_dtype
node_sheet -->|"reads cells"| node_cell_data
node_table -->|"reads cells"| node_cell_data
node_cell_data -->|"extracts values"| node_series
node_sheet -->|"exports data"| node_arrow
node_table -->|"exports data"| node_arrow
node_sheet -->|"exports zero-copy"| node_capsule
node_table -->|"exports zero-copy"| node_capsule
node_sheet -.->|"converts data"| node_polars
node_polars -.->|"returns frame"| node_polars_user
node_arrow -->|"provides Arrow"| node_consumer
node_capsule -->|"provides capsule"| node_consumer
node_sheet -.->|"converts data"| node_pandas
node_table -.->|"converts data"| node_pandas
node_pandas -.->|"returns frame"| node_pandas_user

click node_py_api "https://github.com/toucantoco/fastexcel/blob/main/python/fastexcel/__init__.py"
click node_rust_api "https://github.com/toucantoco/fastexcel/blob/main/src/lib.rs"
click node_reader "https://github.com/toucantoco/fastexcel/blob/main/src/types/excelreader/mod.rs"
click node_sheet "https://github.com/toucantoco/fastexcel/blob/main/src/types/excelsheet/mod.rs"
click node_table "https://github.com/toucantoco/fastexcel/blob/main/src/types/exceltable/mod.rs"
click node_defined_names "https://github.com/toucantoco/fastexcel/blob/main/src/types/excelreader/mod.rs"
click node_options "https://github.com/toucantoco/fastexcel/blob/main/src/types/excelreader/mod.rs"
click node_column_info "https://github.com/toucantoco/fastexcel/blob/main/src/types/excelsheet/column_info/mod.rs"
click node_dtype "https://github.com/toucantoco/fastexcel/blob/main/src/types/dtype/mod.rs"
click node_cell_data "https://github.com/toucantoco/fastexcel/blob/main/src/data/mod.rs"
click node_series "https://github.com/toucantoco/fastexcel/blob/main/src/data/mod.rs"
click node_arrow "https://github.com/toucantoco/fastexcel/blob/main/src/types/excelsheet/python.rs"
click node_capsule "https://github.com/toucantoco/fastexcel/blob/main/src/types/excelsheet/python.rs"
click node_polars "https://github.com/toucantoco/fastexcel/blob/main/src/types/excelsheet/polars.rs"
click node_pandas "https://github.com/toucantoco/fastexcel/blob/main/python/fastexcel/__init__.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_py_api,node_rust_api toneBlue
class node_reader,node_sheet,node_table,node_defined_names toneAmber
class node_options,node_column_info,node_dtype,node_cell_data,node_series toneMint
class node_arrow,node_capsule,node_polars,node_pandas toneRose
class node_caller,node_excel,node_consumer,node_polars_user,node_pandas_user toneIndigo
```

## Components

### User APIs

- [Python facade](https://github.com/toucantoco/fastexcel/blob/main/python/fastexcel/__init__.py): `python/fastexcel/__init__.py`
- [Rust API](https://github.com/toucantoco/fastexcel/blob/main/src/lib.rs): `src/lib.rs`

### Workbook Access

- [Workbook reader](https://github.com/toucantoco/fastexcel/blob/main/src/types/excelreader/mod.rs): `src/types/excelreader/mod.rs`
- [Sheet loader](https://github.com/toucantoco/fastexcel/blob/main/src/types/excelsheet/mod.rs): `src/types/excelsheet/mod.rs`
- [Table loader](https://github.com/toucantoco/fastexcel/blob/main/src/types/exceltable/mod.rs): `src/types/exceltable/mod.rs`
- [Defined names](https://github.com/toucantoco/fastexcel/blob/main/src/types/excelreader/mod.rs): `src/types/excelreader/mod.rs`

### Data Processing

- [Load options](https://github.com/toucantoco/fastexcel/blob/main/src/types/excelreader/mod.rs): `src/types/excelreader/mod.rs`
- [Column metadata](https://github.com/toucantoco/fastexcel/blob/main/src/types/excelsheet/column_info/mod.rs): `src/types/excelsheet/column_info/mod.rs`
- [Type inference](https://github.com/toucantoco/fastexcel/blob/main/src/types/dtype/mod.rs): `src/types/dtype/mod.rs`
- [Cell extraction](https://github.com/toucantoco/fastexcel/blob/main/src/data/mod.rs): `src/data/mod.rs`
- [Typed columns](https://github.com/toucantoco/fastexcel/blob/main/src/data/mod.rs): `src/data/mod.rs`

### Data Interchange

- [Arrow exchange](https://github.com/toucantoco/fastexcel/blob/main/src/types/excelsheet/python.rs): `src/types/excelsheet/python.rs`
- [PyCapsule exchange](https://github.com/toucantoco/fastexcel/blob/main/src/types/excelsheet/python.rs): `src/types/excelsheet/python.rs`
- [Polars output](https://github.com/toucantoco/fastexcel/blob/main/src/types/excelsheet/polars.rs): `src/types/excelsheet/polars.rs`
- [Pandas output](https://github.com/toucantoco/fastexcel/blob/main/python/fastexcel/__init__.py): `python/fastexcel/__init__.py`

### Other components

- **Python or Rust caller**
- **Excel workbook**
- **Arrow-compatible consumer**
- **Polars consumer**
- **Pandas consumer**

## Connections

- Python or Rust caller → Python facade: calls
- Python or Rust caller → Rust API: calls
- Excel workbook → Workbook reader: reads
- Python facade → Rust API: calls native API
- Rust API → Workbook reader: opens workbook
- Workbook reader → Sheet loader: loads sheet
- Workbook reader → Table loader: loads table
- Workbook reader → Defined names: lists names
- Sheet loader → Load options: applies options
- Table loader → Load options: applies options
- Sheet loader → Column metadata: builds metadata
- Table loader → Column metadata: builds metadata
- Column metadata → Type inference: infers types
- Sheet loader → Cell extraction: reads cells
- Table loader → Cell extraction: reads cells
- Cell extraction → Typed columns: extracts values
- Sheet loader → Arrow exchange: exports data
- Table loader → Arrow exchange: exports data
- Sheet loader → PyCapsule exchange: exports zero-copy
- Table loader → PyCapsule exchange: exports zero-copy
- Sheet loader → Polars output: converts data
- Polars output → Polars consumer: returns frame
- Arrow exchange → Arrow-compatible consumer: provides Arrow
- PyCapsule exchange → Arrow-compatible consumer: provides capsule
- Sheet loader → Pandas output: converts data
- Table loader → Pandas output: converts data
- Pandas output → Pandas consumer: returns frame