Metadata-Version: 2.4
Name: report_creator
Version: 1.2.6
Summary: Create self-contained HTML reports from Python.
Home-page: https://gitlab.com/darenr/report_creator
Author: Daren Race
Author-email: daren.race@gmail.com
Maintainer: Daren Race
Maintainer-email: daren.race@gmail.com
License: MIT
Keywords: python,html,reports,report,creator,generator,markdown,yaml,plot,chart,table,blog
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
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: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: pandas
Requires-Dist: pyarrow
Requires-Dist: numpy
Requires-Dist: matplotlib
Requires-Dist: mistune>=3.0.2
Requires-Dist: pyyaml
Requires-Dist: plotly
Requires-Dist: plotly-express
Requires-Dist: Jinja2
Requires-Dist: humanize
Requires-Dist: beautifulsoup4
Requires-Dist: python-dateutil
Requires-Dist: requests
Requires-Dist: pillow
Requires-Dist: md4mathjax
Requires-Dist: emoji
Requires-Dist: setuptools
Requires-Dist: tabulate
Requires-Dist: loguru
Requires-Dist: rich
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: maintainer
Dynamic: maintainer-email
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Report Creator

> Build polished, self-contained HTML reports from Python in minutes.

[![PyPI Version](https://img.shields.io/pypi/v/report_creator.svg?style=for-the-badge&logo=pypi&color=blue)](https://pypi.org/project/report_creator)
[![Python Versions](https://img.shields.io/pypi/pyversions/report_creator.svg?style=for-the-badge&logo=pypi&color=blue)](https://pypi.org/project/report_creator)
![Read the Docs](https://img.shields.io/readthedocs/report_creator?style=for-the-badge&logo=readthedocs&color=blue)
[![License](https://img.shields.io/badge/license-MIT-blue.svg?style=for-the-badge&color=blue)](https://www.apache.org/licenses/LICENSE-2.0)

Report Creator helps you turn DataFrames, charts, markdown, metrics, and diagrams into a single professional HTML file.
No web app or frontend stack required.

- **Website**: [GitLab](https://gitlab.com/darenr/report_creator)
- **Package**: [PyPI](https://pypi.org/project/report_creator/)
- **Docs**: [Read the Docs](https://report-creator.readthedocs.io)
- **Examples**: [`examples/`](https://report-creator-1c4362.gitlab.io/)

## Table of Contents

- [Why Report Creator](#why-report-creator)
- [Quickstart](#quickstart)
- [Common Patterns](#common-patterns)
- [Feature Highlights](#feature-highlights)
- [Examples](#examples)
- [Development](#development)
- [Contributing](#contributing)

## Why Report Creator

Use Report Creator when you want to:

- Keep report generation in **pure Python**.
- Combine **data + narrative + charts** in one deliverable.
- Share outputs that are **self-contained HTML files**.
- Build reusable internal reporting workflows quickly.

This project is not trying to replace custom web apps. It gives you a fast, structured path to clean reporting output with minimal code.

## Quickstart

### 1) Install

```bash
python -m pip install report_creator -U
```

### 2) Create your first report

```python
import plotly.express as px
import report_creator as rc

with rc.ReportCreator(
    title="My First Report",
    description="A quick report generated from Python",
    footer="Built with report_creator",
) as report:
    view = rc.Block(
        rc.Markdown("## Hello report"),
        rc.Group(
            rc.Metric(heading="Rows", value=len(px.data.iris())),
            rc.Metric(heading="Source", value="Plotly datasets"),
        ),
        rc.Scatter(
            px.data.iris(),
            x="sepal_width",
            y="sepal_length",
            dimension="species",
            label="Iris overview",
        ),
    )

    report.save(view, "report.html")
```

### 3) Open the output

```bash
python my_report.py
open report.html  # macOS
# xdg-open report.html  # Linux
```

### 4) Explore complete examples

```bash
PYTHONPATH=. python examples/kitchen_sink.py
```

See [examples/README.md](examples/README.md) for a guided map of all example scripts.

## Common Patterns

### Dashboard-style layout

```python
view = rc.Block(
    rc.Heading("Executive Summary", level=2),
    rc.Group(
        rc.Metric(heading="Revenue", value="$1.2M"),
        rc.Metric(heading="Growth", value="+14%"),
        rc.Metric(heading="Churn", value="2.1%"),
    ),
    rc.Separator(),
    rc.Line(df, x="date", y="revenue", label="Revenue Trend"),
)
```

### Chart + details tab view

```python
view = rc.Select(
    blocks=[
        rc.Bar(df, x="team", y="score", label="Chart"),
        rc.DataTable(df, label="Data", index=False),
    ],
    label="Performance",
)
```

### Presentation mode with slides

```python
view = rc.Deck(
    rc.Slide(rc.Block(rc.Heading("QBR"), rc.Markdown("### Highlights")), theme="modern:#3b82f6"),
    rc.Slide(rc.Block(rc.Widget(fig), rc.Markdown("### Forecast")), theme="circles:#0ea5e9"),
)
```

## Feature Highlights

- **Layout system** with `rc.Block()` (vertical) and `rc.Group()` (horizontal)
- **Interactive data components** like `rc.DataTable()` and `rc.Select()` tabs
- **Rich text support** via GFM markdown, code blocks, and Mermaid diagrams
- **Visualization support** for Plotly, Matplotlib, Seaborn, Radar, Timeline, Gauge, Bullet, and more
- **Self-contained output** that bundles required assets into a single HTML file

## Examples

- Browse generated outputs in `examples/*.html`
- Run all example scripts:

```bash
make examples
```

- Run one example script:

```bash
PYTHONPATH=. python examples/workflow_example.py
```

For details, see [examples/README.md](examples/README.md).

## Development

```bash
conda create -n rc -c conda-forge python=3.13
conda activate rc
make setup

# recommended for code hygiene
make format

# run tests
make tests

# build docs
make doc
```
