HTML Reports¶

The Truthound Data Docs module transforms data profile results into self-contained HTML reports.

Quick Start¶

from truthound.datadocs import generate_html_report, HTMLReportBuilder

# Simple usage
html = generate_html_report(
    profile=profile_dict,
    title="Data Quality Report",
    theme="professional",
    output_path="report.html",
)

# Generate from file
from truthound.datadocs import generate_report_from_file

html = generate_report_from_file(
    profile_path="profile.json",
    output_path="report.html",
    title="My Report",
    theme="dark",
)

HTMLReportBuilder¶

Use HTMLReportBuilder directly when fine-grained control is required.

Basic Usage¶

from truthound.datadocs import HTMLReportBuilder, ReportTheme

builder = HTMLReportBuilder(theme=ReportTheme.PROFESSIONAL)
html = builder.build(
    profile=profile_dict,
    title="My Data Report",
    subtitle="Q4 2025 Analysis",
    description="Customer dataset quality analysis",
)
builder.save(html, "report.html")

Detailed Configuration with ReportConfig¶

from truthound.datadocs import (
    HTMLReportBuilder,
    ReportConfig,
    ReportTheme,
    SectionType,
)

config = ReportConfig(
    # Theme
    theme=ReportTheme.DARK,

    # Sections to include (in order)
    sections=[
        SectionType.OVERVIEW,
        SectionType.QUALITY,
        SectionType.COLUMNS,
        SectionType.PATTERNS,
        SectionType.DISTRIBUTION,
        SectionType.CORRELATIONS,
        SectionType.RECOMMENDATIONS,
        SectionType.ALERTS,
    ],

    # Layout options
    include_toc=True,
    include_header=True,
    include_footer=True,
    include_timestamp=True,
    include_download_button=True,
    embed_resources=True,
    minify_html=False,

    # Custom content
    custom_css="",
    custom_js="",
    logo_url=None,
    logo_base64=None,
    footer_text="Generated by Truthound",

    # Localization
    language="en",
    date_format="%Y-%m-%d %H:%M:%S",
    number_format=",.2f",
)

builder = HTMLReportBuilder(config=config)
html = builder.build(profile_dict)

ProfileDataConverter¶

ProfileDataConverter transforms TableProfile data into report-ready structures.

from truthound.datadocs.builder import ProfileDataConverter

converter = ProfileDataConverter(profile_dict)

# Extract overview metrics
metrics = converter.get_overview_metrics()
# {
#     "row_count": 10000,
#     "column_count": 15,
#     "memory_bytes": 1234567,
#     "duplicate_rows": 123,
#     "null_cells": 456,
#     "quality_score": 85.5,
# }

# Column data
columns = converter.get_column_data()

# Generate chart specs
type_chart = converter.get_type_distribution()  # ChartSpec
null_chart = converter.get_null_distribution()  # ChartSpec
unique_chart = converter.get_uniqueness_distribution()  # ChartSpec

# Extract patterns
patterns = converter.get_patterns()

# Extract correlations
correlations = converter.get_correlations()  # list[tuple[str, str, float]]

# Generate alerts
alerts = converter.get_alerts()  # list[AlertSpec]

# Generate recommendations
recommendations = converter.get_recommendations()  # list[str]

Convenience Functions¶

generate_html_report¶

from truthound.datadocs import generate_html_report

html = generate_html_report(
    profile=profile_dict,        # TableProfile dict or object
    title="Data Quality Report", # Report title
    subtitle="",                 # Subtitle
    theme="professional",        # Theme name or ReportTheme
    output_path="report.html",   # Save path (optional)
)

generate_report_from_file¶

from truthound.datadocs import generate_report_from_file

html = generate_report_from_file(
    profile_path="profile.json",  # Profile JSON file path
    output_path="report.html",    # Output path (default: <input>.html)
    title="My Report",
    theme="dark",
)

export_report¶

from truthound.datadocs import export_report

# HTML export
export_report(profile_dict, "report.html", format="html")

# PDF export (requires WeasyPrint)
export_report(profile_dict, "report.pdf", format="pdf")

Complete Workflow Example¶

import truthound as th
from truthound.datadocs import generate_html_report

# 1. Load data
df = th.load("data.csv")

# 2. Generate profile
from truthound.profiler import DataProfiler
profiler = DataProfiler()
profile = profiler.profile(df)

# 3. Generate HTML report
html = generate_html_report(
    profile=profile.to_dict(),
    title="Customer Data Quality Report",
    subtitle="Q4 2025 Analysis",
    theme="professional",
    output_path="customer_report.html",
)

print(f"Report generated: {len(html):,} bytes")

CLI Usage¶

# Basic usage
truthound docs generate profile.json -o report.html

# Custom title and dark theme
truthound docs generate profile.json -o report.html \
    --title "Q4 Data Quality Report" \
    --subtitle "Customer Dataset" \
    --theme dark

# PDF export
truthound docs generate profile.json -o report.pdf --format pdf

Customization¶

Custom CSS¶

config = ReportConfig(
    custom_css="""
    .report-title {
        color: #ff6b6b;
    }
    .metric-card {
        border: 2px solid #4ecdc4;
    }
    """,
)

Custom JavaScript¶

config = ReportConfig(
    custom_js="""
    document.addEventListener('DOMContentLoaded', function() {
        console.log('Report loaded!');
    });
    """,
)

Adding a Logo¶

# Add logo via URL
config = ReportConfig(logo_url="https://example.com/logo.png")

# Add logo via Base64 (offline support)
import base64
with open("logo.png", "rb") as f:
    logo_b64 = base64.b64encode(f.read()).decode()

config = ReportConfig(logo_base64=f"data:image/png;base64,{logo_b64}")

API Reference¶

ReportConfig¶

@dataclass
class ReportConfig:
    theme: ReportTheme = ReportTheme.PROFESSIONAL
    custom_theme: ThemeConfig | None = None
    chart_library: ChartLibrary = ChartLibrary.APEXCHARTS
    sections: list[SectionType] = [
        SectionType.OVERVIEW,
        SectionType.QUALITY,
        SectionType.COLUMNS,
        SectionType.PATTERNS,
        SectionType.DISTRIBUTION,
        SectionType.CORRELATIONS,
        SectionType.RECOMMENDATIONS,
        SectionType.ALERTS,
    ]
    include_toc: bool = True
    include_header: bool = True
    include_footer: bool = True
    include_timestamp: bool = True
    include_download_button: bool = True
    embed_resources: bool = True
    minify_html: bool = False
    custom_css: str = ""
    custom_js: str = ""
    logo_url: str | None = None
    logo_base64: str | None = None
    footer_text: str = "Generated by Truthound"
    language: str = "en"
    date_format: str = "%Y-%m-%d %H:%M:%S"
    number_format: str = ",.2f"

ReportMetadata¶

@dataclass
class ReportMetadata:
    title: str
    subtitle: str = ""
    description: str = ""
    data_source: str = ""
    created_at: datetime = field(default_factory=datetime.now)
    author: str = ""
    version: str = ""