Metadata-Version: 2.5
Name: fillxl
Version: 0.8.0
Summary: Fill Excel templates with data from Python.
Project-URL: Homepage, https://github.com/hirolau/fillxl
Project-URL: Source, https://github.com/hirolau/fillxl
Project-URL: Issues, https://github.com/hirolau/fillxl/issues
Author-email: hirolau <hirolau@users.noreply.github.com>
License: MIT License
        
        Copyright (c) 2026 hirolau
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: automation,excel,fillxl,templates
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
Requires-Python: >=3.11
Requires-Dist: attrs>=23.0
Requires-Dist: openpyxl>=3.1.5
Requires-Dist: pywin32>=306; sys_platform == 'win32'
Provides-Extra: all
Requires-Dist: duckdb>=0.9; extra == 'all'
Requires-Dist: pandas>=2.0; extra == 'all'
Requires-Dist: polars>=0.20; extra == 'all'
Provides-Extra: dev
Requires-Dist: check-wheel-contents>=0.6; extra == 'dev'
Requires-Dist: coverage>=7; extra == 'dev'
Requires-Dist: freezegun>=1.5.5; extra == 'dev'
Requires-Dist: mypy>=2.4.0; extra == 'dev'
Requires-Dist: nox>=2023.12; extra == 'dev'
Requires-Dist: pandas-stubs>=2; extra == 'dev'
Requires-Dist: pyrefly>=1.0; extra == 'dev'
Requires-Dist: pytest-cov>=4; extra == 'dev'
Requires-Dist: pytest-gremlins>=1.9.0; extra == 'dev'
Requires-Dist: pytest-spec>=6.1.0; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff>=0.17.1; extra == 'dev'
Requires-Dist: twine>=7; extra == 'dev'
Requires-Dist: xlwings>=0.30; extra == 'dev'
Provides-Extra: duckdb
Requires-Dist: duckdb>=0.9; extra == 'duckdb'
Provides-Extra: pandas
Requires-Dist: pandas>=2.0; extra == 'pandas'
Provides-Extra: polars
Requires-Dist: polars>=0.20; extra == 'polars'
Provides-Extra: test
Requires-Dist: duckdb>=1.5.4; extra == 'test'
Requires-Dist: freezegun>=1.5.5; extra == 'test'
Requires-Dist: hypothesis>=6.156.3; extra == 'test'
Requires-Dist: pandas>=3.0.3; extra == 'test'
Requires-Dist: polars>=2.0; extra == 'test'
Description-Content-Type: text/markdown

# fillxl

[![PyPI version](https://img.shields.io/pypi/v/fillxl.svg)](https://pypi.org/project/fillxl/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/hirolau/fillxl/blob/main/LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://github.com/hirolau/fillxl/blob/main/pyproject.toml)
[![CI](https://github.com/hirolau/fillxl/actions/workflows/ci.yml/badge.svg)](https://github.com/hirolau/fillxl/actions/workflows/ci.yml)
[![Docs](https://img.shields.io/badge/docs-mkdocs--material-blue)](https://hirolau.github.io/fillxl/)

**Design in Excel. Populate with Python.**

Create polished templates with named cells and Excel Tables — then fill them
from pandas, Polars, DuckDB or plain Python. Charts, formatting and formulas
stay intact.

```python
from fillxl import fill
import pandas as pd

fill(
    template="report_template.xlsx",
    output="q4_report.xlsx",
    tables={
        "Products": [
            {"Name": "Widget", "Price": 4.99, "Sold": 150},
            {"Name": "Gadget", "Price": 9.99, "Sold": 85},
        ],
        "Sales": pd.read_csv("sales_data.csv"),
    },
    values={
        "ReportTitle": "Q4 2024 Sales",
        "PreparedBy": "Alice",
    },
)
```

## Installation

```bash
pip install fillxl
```

That is all you need. Filling works with plain Python (`list[dict]`,
`dict[str, list]`) and with the pandas, Polars or DuckDB objects your own code
already creates — there is nothing else to choose:

```python
import pandas as pd
from fillxl import fill

fill(..., tables={"Sales": pd.read_csv("sales.csv")})  # works as-is
```

fillxl never imports a data library itself; it recognises the DataFrame or
relation that you pass in, so any version you already use works.

## Data you can fill from

| Input | Example |
|-------|---------|
| `list[dict]` | `[{"Name": "Widget", "Price": 4.99}]` |
| `dict[str, list]` | `{"Name": ["Widget"], "Price": [4.99]}` |
| `pandas.DataFrame` | `pd.read_csv("sales.csv")` |
| `polars.DataFrame` | `pl.read_csv("sales.csv")` |
| `duckdb.DuckDBPyRelation` | `duckdb.sql("FROM 'sales.csv'")` |

Tables are matched to your data by column name, so the DataFrame order does not
matter, and every format produces the same workbook.

## Visual example

**Before filling:**

![Before fill](https://hirolau.github.io/fillxl/screenshots/before_fill.png)

**After filling — data, chart and values populated:**

![After fill](https://hirolau.github.io/fillxl/screenshots/after_fill.png)

[See the code that produced this](https://hirolau.github.io/fillxl/#visual-example).

## Choosing an engine

`engine="auto"` (the default) picks the engine that can do the job:

| Template → output | Engine used |
|-------------------|-------------|
| `.xlsx` → `.xlsx`, `.xlsm` → `.xlsm` | `openpyxl` (no Excel needed) |
| `.xlsb`/`.xls` template, or a format conversion | `win32com` when Excel is available |
| anything else, without Excel | `openpyxl`, whose error says what is missing |

`openpyxl` runs anywhere; `win32com` drives Microsoft Excel on Windows (pywin32
installs with fillxl there) and keeps what openpyxl drops (modern charts,
slicers, macro-heavy workbooks). Both engines write the same values for the same
template and data; the
[Backends](https://hirolau.github.io/fillxl/backends/) page lists what still
differs.

## Know the edge cases

- One cell holds one value. A `list`, `dict`, `bytes` or a whole DataFrame in a
  named cell or a table cell raises `CellValueError` naming the position,
  instead of writing its text dump; put rows and columns in `tables=`.
- `None` and `NaN` are missing values and become empty cells. ±Infinity cannot
  be stored either, but it warns rather than disappearing quietly.
- Every warning is a `fillxl.FillXLWarning` subclass (`TimezoneWarning`,
  `DanglingReferenceWarning`, `LossyTemplateWarning`), so
  `warnings.simplefilter("error", fillxl.FillXLWarning)` makes data problems
  fail fast instead of quietly changing the output.
- `openpyxl` writes no cached formula results; the output asks Excel to
  recalculate on open (`engine="win32com"` saves computed values).
- `openpyxl` drops some modern chart types, slicers and similar parts, and says
  so: `on_lossy="warn"` (default) warns, `on_lossy="raise"` fails the fill.
- `delete_sheets` does not rewrite formulas, charts, names or pivots that point
  at the deleted sheet; fillxl warns with `DanglingReferenceWarning` because
  Excel shows `#REF!` there.
- `hide_underscore_sheets` is **on** by default, so a sheet named `_data` is
  hidden unless you opt out. Hiding or deleting every sheet raises, because
  Excel requires one visible sheet — set `hide_underscore_sheets=False` for a
  workbook whose only sheet is `_report`.

Dates, value types, sheet handling, warning categories, errors and all
`FillXLConfig` options are documented at
[hirolau.github.io/fillxl](https://hirolau.github.io/fillxl/).

## Development

```bash
git clone https://github.com/hirolau/fillxl.git
cd fillxl
uv sync --all-extras
uv run pytest
```

The 0.x line leaves room for breaking changes; 1.0 signals stability. Supported:
Python 3.11–3.15 on Windows and Linux (macOS best-effort), with the data
libraries above on their minimum and newest major release (pandas 2 and 3,
polars 0.20 and 2, duckdb 1 and 2). See
[Development](https://hirolau.github.io/fillxl/development/) for the test
matrix, type checks and supported data-library versions.

**License:** [MIT](https://github.com/hirolau/fillxl/blob/main/LICENSE)