Metadata-Version: 2.4
Name: exportkit
Version: 0.1.1
Summary: Render declarative tabular reports to Excel, Word and PDF from plain Python data.
Author-email: codewithmugisha <bright001it@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/ivanbright/exportkit
Project-URL: Repository, https://github.com/ivanbright/exportkit
Project-URL: Issues, https://github.com/ivanbright/exportkit/issues
Keywords: export,excel,xlsx,word,docx,pdf,report,openpyxl,python-docx,fpdf2,table,data-export
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: xlsx
Requires-Dist: openpyxl>=3.1; extra == "xlsx"
Provides-Extra: docx
Requires-Dist: python-docx>=1.1; extra == "docx"
Provides-Extra: pdf
Requires-Dist: fpdf2>=2.7.6; extra == "pdf"
Provides-Extra: all
Requires-Dist: openpyxl>=3.1; extra == "all"
Requires-Dist: python-docx>=1.1; extra == "all"
Requires-Dist: fpdf2>=2.7.6; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Dynamic: license-file

# exportkit

**exportkit** renders declarative tabular reports to **Excel (.xlsx)**, **Word
(.docx)** and **PDF** from plain Python data. Define a report once — a title,
columns and rows — and export it to any format with the same code.

It has **no required dependencies**: install only the format backends you need.

```bash
pip install "exportkit[xlsx]"      # Excel  (openpyxl)
pip install "exportkit[docx]"      # Word   (python-docx)
pip install "exportkit[pdf]"       # PDF    (fpdf2)
pip install "exportkit[all]"       # everything
```

## Quick start

```python
from exportkit import Column, Format, Report, render

report = Report(
    title="Waiting list",
    subtitle="I&M Bank · Nairobi CBD Branch",
    meta={"Service": "Teller", "Queue": "Main"},
    columns=[
        Column("Ticket", align="right"),
        Column("Customer"),
        Column("Status"),
        Column("Wait", align="right"),
    ],
    rows=[
        [1201, "Amina Otieno", "Waiting", "~6 min"],
        [1202, "Brian Kamau", "Called", "now"],
        [1203, "Cynthia Wanjiru", "Served", "—"],
    ],
    summary={"Total tickets": 3},
    footer="Generated by Don't Queue",
)

pdf = render(report, Format.PDF)          # -> bytes
xlsx = render(report, "xlsx")             # format names, extensions and MIME types all work
docx = render(report, "word")

with open("waiting-list.pdf", "wb") as fh:
    fh.write(pdf)
```

### Writing straight to a file or stream

```python
from exportkit import render_to

render_to(report, "xlsx", "waiting-list.xlsx")   # path
render_to(report, "pdf", request)                # any object with .write(bytes)
```

## Rows: sequences or mappings

Rows can be positional sequences, or mappings selected by each column's `key`:

```python
from exportkit import Column, Report

report = Report(
    title="Tickets",
    columns=[Column("Ticket", key="number"), Column("Customer", key="name")],
    rows=[
        {"number": 1, "name": "Amina"},
        {"number": 2, "name": "Brian"},
    ],
)
```

Columns can format raw values for display:

```python
Column("Joined", key="joined_at", format=lambda dt: dt.strftime("%H:%M"))
```

## API

| Name | Purpose |
| --- | --- |
| `Report` | title, subtitle, meta, columns, rows, summary, footer |
| `Column` | header, optional `key`, `align`, `width`, `format` |
| `Format` | `XLSX`, `DOCX`, `PDF` (with `.content_type`, `.extension`, `Format.coerce`) |
| `render(report, fmt, options=None) -> bytes` | render to bytes |
| `render_to(report, fmt, target, options=None)` | render to a path or file-like object |

`options` is passed to the writer:

- `accent_color` — hex header colour for XLSX/DOCX (default `"242426"`).
- `font` — path to a Unicode `.ttf` for PDF (default core Helvetica, Latin-1 only).

## Using it from Django

```python
from django.http import HttpResponse
from exportkit import Column, Format, Report, render

def export_waiting_list(request):
    report = Report(
        title="Waiting list",
        columns=[Column("Ticket"), Column("Customer"), Column("Status")],
        rows=[[e.number, e.customer.full_name, e.get_status_display()] for e in waiting],
    )
    fmt = Format.coerce("xlsx")
    response = HttpResponse(render(report, fmt), content_type=fmt.content_type)
    response["Content-Disposition"] = f'attachment; filename="{fmt.filename("waiting-list")}"'
    return response
```

The package never imports Django; your project maps its data into a `Report`.

## License

MIT © codewithmugisha
