Metadata-Version: 2.4
Name: tabularix
Version: 0.3.2
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: License :: OSI Approved :: MIT License
Classifier: License :: OSI Approved :: Apache Software License
Requires-Dist: pyarrow>=24.0.0
License-File: LICENSE-APACHE
License-File: LICENSE-MIT
Summary: High-performance framework for layout-resilient Excel table extraction
Keywords: excel,pyarrow,arrow,pandas,polars,layout-resilient,data-extraction
Author-email: Pascal Castéran <15686972+pcasteran@users.noreply.github.com>
License: MIT OR Apache-2.0
Requires-Python: >=3.12
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://github.com/pcasteran/tabularix/blob/main/CHANGELOG.md
Project-URL: Documentation, https://pcasteran.github.io/tabularix
Project-URL: Homepage, https://github.com/pcasteran/tabularix
Project-URL: Issues, https://github.com/pcasteran/tabularix/issues
Project-URL: Repository, https://github.com/pcasteran/tabularix

<div align="center">
  <img src="docs/assets/logo_2.png" alt="Tabularix Logo" width="250"/>
  <p><strong>Smart, layout-resilient data extraction from Excel documents.</strong></p>
</div>

---

# Tabularix

Tabularix is a high-performance framework designed to identify, extract, and organize "hidden data" trapped in fragmented, messy Excel files. It transforms highly variable visual spreadsheets into clean, structured formats (such as Apache Arrow tables, Pandas DataFrames, or Polars DataFrames) at native speeds.

Developed as a direct continuation of the [Archery](https://github.com/RomualdRousseau/Archery) framework, it combines a blazing-fast **Rust core engine** with ergonomic **Python scripting bindings** to enable powerful "Configuration as Code" recipes.

---

## 🚀 Installation

Install the stable package directly from PyPI:

```bash
pip install tabularix
```

### Build from Source

To compile the native Rust extension and install the package locally, make sure you have [mise](https://mise.jdx.dev/) and [just](https://github.com/casey/just) installed:

```bash
# Clone the repository
git clone https://github.com/pcasteran/tabularix.git
cd tabularix

# Set up toolchains
mise install

# Compile the native bindings
just build
```

---

## 💡 Quick Example

### The Scenario

Suppose we have a spreadsheet containing a sales report table surrounded by empty rows, headers, and metadata, as shown in the layout analysis below:

![Visual Structure of the Spreadsheet](docs/assets/sheet_complex.svg)

Instead of hardcoding static cell coordinates (e.g., `A3:E8`) which break when columns or rows are added, deleted, or shifted, Tabularix uses **Range Matchers** to dynamically locate table boundaries relative to their visual markers.

The following example shows how to define the header and data patterns, locate the table, and export it:

```python
import polars as pl
from tabularix import (
    extract_table_with_header_and_data,
    grid,
    group,
    load_workbook,
    non_empty,
    regex,
    value,
)

# 1. Load the workbook and get the target worksheet.
workbook = load_workbook("tests/data/sample.xlsx")
sheet = workbook.get_sheet("complex")

# 2. Define the header row pattern (starts with "Region", then 4 Quarters matching Q1-Q4 regex).
header_pattern = group(
    value("Region"),
    regex(r"^Q[1-4]$").repeat(min=4, max=4)
)

# 3. Define the data row pattern (region name, then 4 non-empty numeric quarter cells).
data_pattern = grid(
    group(
        regex(r"^(?!Total).*$"),  # Match any string except "Total" (the footer marker).
        non_empty().repeat(min=4, max=4)
    ).one_or_more()
)

# 4. Extract the structured Table with dynamic coordinate scanning.
table = extract_table_with_header_and_data(
    sheet,
    header_pattern,
    data_pattern,
    clean_names=True
)

# 5. Export zero-copy to a Polars or Pandas DataFrame.
df = pl.from_arrow(table.to_arrow())
print(df)
```

---

## 📖 Documentation

For full guides, detailed tutorials, and API reference, please visit our **[Official Documentation Site](https://pcasteran.github.io/tabularix)**.

---

## ⚡ Core Features

- **High-Performance Rust Core**: Performs CPU-heavy Excel manipulation, boundary scanning, and cell matching at native speeds.
- **Privacy-First & Secure**: Runs entirely locally on your hardware. No external APIs or third-party servers are queried.
- **Python Ergonomics**: Natural integration with standard Python tools, dynamic typing support, and full PEP 8 compliance.
- **Zero-Copy FFI**: Seamless exports to Apache Arrow tables, Pandas, Polars, and DuckDB.

---

## 🤝 Contributing

Contributions are welcome! Please read our **[Development Guidelines](docs/contributing.md)** (or the root [CONTRIBUTING.md](CONTRIBUTING.md)) for details on local environment setup, testing, formatting checks, and repository workflows.

---

## ⚖️ License

Tabularix is dual-licensed under the Apache 2.0 and MIT licenses.

- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT License ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Tabularix by you, as defined in the Apache-2.0 license, shall be dually licensed as above, without any additional terms or conditions.

