basic-report 0.4.4

A lightweight Python package for generating clean, professional static HTML reports.

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 (MIT licensed), datatables (MIT licensed) and cal-heatmap (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:

pip install basic-report

[!tip] We recommend using uv for faster, more reliable dependency management

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:

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

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:

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:

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:

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:

# 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:

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

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.