Metadata-Version: 2.4
Name: basic-report
Version: 0.4.2
Summary: A lightweight Python package for generating clean, professional static HTML reports.
Keywords: html,report,static,responsive,website
Author: Björn Scholz
Author-email: Björn Scholz <bjorn.scholz@gmail.com>
License-Expression: MIT
License-File: LICENSE.md
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Requires-Dist: jinja2>=3.1.6
Requires-Dist: loguru>=0.7.3
Requires-Dist: pandas>=3.0.0
Requires-Dist: pyyaml>=6.0.3
Maintainer: Björn Scholz
Maintainer-email: Björn Scholz <bjorn.scholz@gmail.com>
Requires-Python: >=3.11
Project-URL: Homepage, https://basic-report.scholz-and-scholz.com
Project-URL: Documentation, https://basic-report.scholz-and-scholz.com
Project-URL: Repository, https://gitlab.com/Nablaquabla/basic-report
Project-URL: Issues, https://gitlab.com/Nablaquabla/basic-report/-/issues
Project-URL: Changelog, https://gitlab.com/Nablaquabla/basic-report/-/blob/main/CHANGELOG.md
Description-Content-Type: text/markdown

# Basic Report
**basic-report** is a lightweight Python package for generating clean, professional static HTML reports with zero
external dependencies. Built using elements of [Bootstrap 4](https://getbootstrap.com/) (MIT licensed),
[datatables](https://datatables.net/) (MIT licensed) and [cal-heatmap](https://cal-heatmap.com/)
(MIT licensed) it empowers you to create fully self-contained sites that can be served directly by any web server. The
focus is set on simplicity - no oversized web framework, no database, no setup required.

Design any reports entirely in Python using an intuitive top-to-bottom workflow. Simply add elements in the order they 
should appear, and nest them naturally, e.g., tabs within columns, columns within tabs, or any combination you need. The
API follows the logical flow of your document, making more complex layouts straightforward to build.

Perfect for data scientists, analysts, and developers who need to create shareable, standalone reports without the
overhead of modern web frameworks.

## Quickstart
### Installation

Install the package from PyPI:
```bash
pip install basic-report
```

> [!tip]
> We recommend using [uv](https://github.com/astral-sh/uv) for faster, more reliable dependency management
> 
> ```bash
> uv add basic-report
> ```

### A Minimal Working Example Report

The following example demonstrates the minimal setup required to generate a report including a report header:

```python
from basic_report import Report

# Create a new report
r = Report('output', 'Minimal Working Example', color_mode='light')
r.add_report_header()
r.add_text('This is a minimal working example')

# Generate the static site
r.dump()
```

Executing this script creates the following directory structure:
```
output/
├── css_and_scripts/
└── index.html
```

Open `index.html` in a web browser to view the report. No build step, compilation process, or server runtime is required.
The output is a fully self-contained static site ready for distribution.

**Next steps**: Follow the tutorial below to explore layouting and additional content or directly head over to the full
[https://basic-report.scholz-and-scholz.com](full documentation) for a complete overview of available components.

### Building A Proper Report

This example demonstrates a ever so slightly more realistic use case, showcasing how you actually stack components to
build your report.

#### Initialize Your Report
```python
import datetime
from pathlib import Path
from basic_report import Report

report_dir  = Path('example_report')
report_name = 'System Status Report'
report_date = datetime.date.today()

r = Report(
    report_dir,
    report_name,
    report_date,
    color_mode='dark',
)
```

#### Add a Professional Header
Create a dominant header for your report. By default this header not only shows the name of the report, but also the
date given during initialization. Additionally it also shows a sub-text which tells you when *exactly* the report
files were created. However, you can easily deactivate the date options as follows:

```python
r.add_report_header(
    include_date=False,
    include_created_at=False,
    color='steel',
)
```

#### Display Structured Status Information

Quickly surface critical information with color-coded status sections:
```python
errors = [
    'Database connection timeout on rnd-server-03'
]
warnings = [
    'Memory usage reached 75%',
    'SSL certificate expires in 14 days',
]
info = [
    'All backups completed successfully'
]

r.add_error_warning_info_section(errors=errors, warnings=warnings, info=info)
```

#### Create Multi-Column Layouts

Construct responsive, structured layouts using containers such as columns:

```python
r.add_header('Performance Metrics', color='muffin')

r.open_columns()
r.add_column()
r.add_text('Align text on the left', align='left')
r.add_column()
r.add_text('Align text in the center', color='cherry')
r.add_column()
r.add_text('Align text on the right', align='right')
r.close_columns()
```
**Layout pattern**: Open a container element (e.g., columns, tabs, accordions), add content sequentially, then
explicitly close the container. The library validates structural consistency and raises descriptive errors if elements
remain unclosed.

#### Create Multi-Page Reports

For larger reports, create and manage multiple pages:

```python
# Create and populate a second page
r.add_page('page2')
r['page2'].add_header('Detailed Metrics')

# Or set it as active and add content directly
r.set_current_page('page2')
r.add_text('Deep dive into performance trends...')
```

#### Add Navigation Links

Link pages to provide intuitive navigation:

```python
r.add_local_link_to_page('main', '← Back to Overview')

r.set_current_page('main')
r.add_local_link_to_page('page2', 'View Detailed Metrics →')
```

#### Generate Your Report
```python
r.dump()
```

The result is a multi-page, self-contained static site with structured layout, responsive design, and integrated
navigation. Everything generated entirely from Python code.

![Example Report](docs/source/_static/tutorial_report_dark.png)
