Metadata-Version: 2.4
Name: mindoff-dataport
Version: 1.0.1
Summary: Extract xlsx templates with full visual fidelity and render data-driven reports in xlsx and PDF formats.
Project-URL: Homepage, https://github.com/mindoffwork/mindoff-dataport
Project-URL: Documentation, https://dataport.mindoff.work/
Project-URL: Source, https://github.com/mindoffwork/mindoff-dataport.git
Project-URL: Issues, https://github.com/mindoffwork/mindoff-dataport/issues
Project-URL: Changelog, https://github.com/mindoffwork/mindoff-dataport/blob/root/CHANGELOG.md
Author: Joel Samraj
License-Expression: MIT
License-File: LICENSE
Keywords: data-export,dataframe,excel,export,openpyxl,pdf,polars,report,reportlab,template,xlsx
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: openpyxl<4.0,>=3.1.0
Requires-Dist: pyarrow<25.0,>=15.0
Requires-Dist: reportlab<5.0,>=4.0
Requires-Dist: xlsxwriter<4.0,>=3.2.0
Provides-Extra: dev
Requires-Dist: polars<2.0,>=1.0; extra == 'dev'
Requires-Dist: pytest-cov<7.0,>=5.0; extra == 'dev'
Requires-Dist: pytest<9.0,>=8.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mike<3.0,>=2.0; extra == 'docs'
Requires-Dist: mkdocs-material<10.0,>=9.5; extra == 'docs'
Requires-Dist: mkdocs<2.0,>=1.6; extra == 'docs'
Requires-Dist: pymdown-extensions<11.0,>=10.0; extra == 'docs'
Provides-Extra: polars
Requires-Dist: polars<2.0,>=1.0; extra == 'polars'
Description-Content-Type: text/markdown

<h1>Mindoff Dataport</h1>

_Build high-fidelity Excel and PDF reports from reusable `.xlsx` templates._

![Mindoff Dataport cover image](https://raw.githubusercontent.com/mindoffwork/mindoff.work/refs/heads/root/public/images/projects/mindoff_dataport/mindoff-dataport-cover-with-name.png)

Mindoff Dataport turns styled Excel workbooks into reusable report templates, compiles runtime data into a portable `ReportBundle`, and exports `.xlsx` and `.pdf` outputs while preserving the layout, structure, and styling you designed.

[![Coverage Status](https://codecov.io/gh/mindoffwork/mindoff-dataport/branch/root/graph/badge.svg)](https://codecov.io/gh/mindoffwork/mindoff-dataport)
[![PyPI version](https://img.shields.io/pypi/v/mindoff-dataport.svg?logo=pypi&logoColor=white)](https://pypi.org/project/mindoff-dataport/)
[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-3776AB?logo=python&logoColor=white)](https://github.com/mindoffwork/mindoff-dataport/actions/workflows/root_ci.yml)

**Documentation**: [https://dataport.mindoff.work](https://dataport.mindoff.work)

**Source**: [https://github.com/mindoffwork/mindoff-dataport](https://github.com/mindoffwork/mindoff-dataport)

**Roadmap**: [https://dataport.mindoff.work/latest-release/community/roadmap/](https://dataport.mindoff.work/latest-release/community/roadmap/)

**Case Study**: [https://mindoff.work/projects/mindoff-dataport/](https://mindoff.work/projects/mindoff-dataport/)

## Key Features

1. **Template-First Report Generation**   
   Turn real Excel workbooks into reusable report templates without rebuilding layouts in code.

2. **One Bundle, Two Formats**   
   The same compiled bundle renders to both `.xlsx` and `.pdf`. No second pipeline, no separate styling pass.

3. **Dataframes Plug Directly Into Templates**   
   Connect dataframe inputs directly to templates so report generation fits naturally into modern data workflows.

4. **Streaming for Large Exports**   
   In streaming mode, Parquet sources are read in batches and rows are written incrementally. Peak memory stays roughly flat as row count grows, instead of climbing with the dataset.

5. **Flexible Repeating and Dynamic Sheets**   
   Generate repeated sections and dynamic sheets for customer-wise, region-wise, or report-wise output from a single template.

6. **Adjustable Layout at Export Time**   
   Column occupation, alignment, and collision shifting are configurable at runtime, without touching the original template.

## Why Not Just openpyxl, ReportLab, or XlsxWriter?

Those tools still matter here. `mindoff-dataport` builds on them instead of pretending they do not exist. The difference is where the work lives.

| If you build with... | You usually own... | What `mindoff-dataport` changes |
|---|---|---|
| `openpyxl` | Cell-by-cell layout code, style copying, merge handling, row/column shifting, and workbook assembly | You keep the layout in Excel and compile data into a reusable bundle before export |
| `reportlab` | A second PDF-specific layout system, plus duplicated styling decisions that drift from Excel over time | The same compiled bundle exports to PDF, so the PDF path follows the template-driven plan instead of a separate document build |
| `xlsxwriter` | Fast XLSX writing, but still your responsibility to recreate template structure and styling rules in code | Streaming export keeps the write path efficient while the template and compile steps carry the layout contract |
| `mindoff-dataport` | An extra extract-and-compile step, plus some streaming constraints for very large exports | In return, you get one template-driven workflow for `.xlsx` and `.pdf`, with less layout logic living in application code |

If your report is simple enough that raw workbook or PDF code stays readable, the lower-level libraries may be enough. This project is for the point where template fidelity, repeated exports, and layout drift start costing more than an extra compile step.

## Quick Start

Think of it like a mail merge for spreadsheets: you design the layout once in Excel, then the library fills in the data. Every report follows four steps: **extract -> inspect -> compile -> export**.

### 1. Install the Package

```bash
pip install mindoff-dataport
```

For dataframe support (Polars DataFrames or LazyFrames):

```bash
pip install "mindoff-dataport[polars]"
```

### 2. Extract the Template

Read your `.xlsx` file into a schema. This captures the layout, every style, and the `{{key:type}}` placeholders you marked in cells. You run this once per template, not once per report.

```python
import polars as pl
from mindoff_dataport import mo_dataport

template = mo_dataport.extract("invoice_template.xlsx")
```

### 3. Inspect What the Template Needs

Before you build a payload, ask the template what it expects. Useful when working with a template someone else designed, or coming back to one after a while.

```python
required_inputs = mo_dataport.inputs(template)
# {'Invoice': {'customer_name': 'string', 'invoice_number': 'number', 'line_items': 'dataframe'}}
```

The result is sheet-scoped: the outer key is the sheet name, and the inner keys are the placeholders on that sheet with their expected types.

### 4. Compile: Bind Your Data

Hand the template your real data, keyed by sheet name. The library validates it against the contract from step 3 and produces a `ReportBundle`: a portable artifact you can export immediately or save to disk and export later.

```python
line_items = pl.DataFrame({"item": ["Widget A", "Widget B"], "amount": [125, 275]})

bundle = mo_dataport.compile(
    template,
    data={
        "Invoice": {
            "customer_name": "Acme Industries",
            "invoice_number": 1024,
            "line_items": line_items,
        }
    },
)
```

### 5. Export

Render the bundle to a file. The same bundle drives both formats. No second pipeline.

```python
mo_dataport.export(bundle, "invoice_filled.xlsx")
mo_dataport.export(bundle, "invoice_filled.pdf", format="pdf")
```

When you're ready to go further (placeholders, the data contract, streaming, repeats, dynamic sheets, custom fonts, and the full API reference), head to the [developer guide](https://dataport.mindoff.work/latest-release/developer_guide/).

If you want to see what is already covered and what is planned next, check the [roadmap](ROADMAP.md).

## Performance

Streaming mode holds near-constant peak memory regardless of dataset size. These benchmarks compare it against raw openpyxl, xlsxwriter, and ReportLab loops with equivalent layout and styling (the most direct alternative).

![XLSX export: export time and peak memory at scale](https://raw.githubusercontent.com/mindoffwork/mindoff-dataport/refs/heads/root/examples/benchmark/charts/benchmark_xlsx.png)

**Fig. 1: XLSX export.** Left: wall-clock time for all Mindoff modes; both streaming and fidelity scale O(n) linearly. Right: peak RSS; Mindoff streaming holds near-constant while openpyxl and xlsxwriter raw loops grow with dataset size.

![PDF export: export time and peak memory at scale](https://raw.githubusercontent.com/mindoffwork/mindoff-dataport/refs/heads/root/examples/benchmark/charts/benchmark_pdf.png)

**Fig. 2: PDF export.** Left: wall-clock time; linear O(n) scaling. Right: peak RSS; Mindoff streaming vs. ReportLab raw loop.

| Scenario | Mode | Why |
|---|---|---|
| <= 50K rows, full style fidelity | `export_mode="fidelity"` | Full merged-cell and style support; no streaming constraints |
| > 50K rows, XLSX | `export_mode="streaming"` | Near-constant memory regardless of row count |
| Any size, PDF | automatic | PDF always paginates; no `export_mode` setting needed |
| > 1M rows, split output | `streaming` + `max_rows_per_workbook` | Splits output across multiple workbook files |

Full methodology, fairness notes, and instructions to reproduce the numbers yourself are in the [Benchmarking guide](https://dataport.mindoff.work/latest-release/architecture/benchmarking/).

## License

Released under the [MIT License](https://github.com/mindoffwork/mindoff-dataport/blob/root/LICENSE).
