HTML 리포트¶

실무 운영 가이드에서 Data Docs, Truthound, HTML, Data, Docs을(를) 기준으로 데이터 품질 검증, 워크플로우 자동화, 결과 해석 방법을 설명합니다.

빠른 시작¶

from truthound.datadocs import generate_html_report, HTMLReportBuilder

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

# 한국어 공공/연구 보고서 라벨
html = generate_html_report(
    profile=profile_dict,
    title="데이터 품질 분석 보고서",
    subtitle="한국 공공·연구용 A4 보고서",
    theme="light",
    language="ko",
    output_path="report-ko.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¶

실무 운영 가이드에서 HTML, HTMLReportBuilder, HTMLReportBuilder을(를) 기준으로 데이터 품질 검증, 워크플로우 자동화, 결과 해석 방법을 설명합니다.

Basic Usage¶

from truthound.datadocs import HTMLReportBuilder, ReportTheme

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

한국어 보고서가 필요하면 HTMLReportBuilder 또는 generate_html_report에 language="ko"를 전달합니다. 이 옵션은 목차, 섹션 제목, 지표 라벨, 표 header, 차트 제목, footer 문구, PDF 표지 metadata를 한국어로 렌더링합니다. 프레임워크가 자동 생성하는 경고 제목, 경고 본문, 조치 제안, 권고사항도 대시보드식 영어 문구가 아니라 보고서형 한국어 문장으로 표시됩니다.

Truthound는 원천 식별자와 기술 식별자를 기본적으로 번역하지 않습니다. 컬럼명, not_null 같은 validator id, integer 같은 추론/물리 타입 id, email 같은 pattern id, 원본 sample 값은 프로파일 및 검증 모델과의 추적성을 위해 그대로 유지됩니다. 주변 라벨과 설명 문장만 선택한 언어에 맞게 현지화됩니다.

공공/연구 보고서형 구조¶

A4 Data Docs 산출물은 단순 대시보드 덤프가 아니라 공공기관·연구용 보고서 구조를 따릅니다. HTML과 PDF는 같은 정보 구조를 공유합니다.

표지 및 메타 정보
분석 목적, 입력 데이터 개요, 주요 결과, 위험, 우선 조치, 검토 한계를 담은 요약문
PDF에서 점선 리더를 사용하는 비표(non-table) 목차
분석 개요, 데이터 품질 진단 결과, 컬럼별 상세 진단, 이상 패턴 및 위험 요인, 개선 권고사항으로 이어지는 장 단위 본문
해석 문장을 번호가 부여된 표, 그림, 부록과 연결하는 장별 도입 문단
표, 그림, 장, 부록에 대한 안정적인 보고서 객체 번호 체계
프로파일 신호가 어떤 데이터 품질 차원을 뒷받침하는지, 어떤 차원은 추가 입력이 필요한지 설명하는 품질 프레임워크 매핑
지표 정의, 산식, 실행 메타데이터, 전체 컬럼 프로파일을 담은 부록
측정된 품질 차원과 업무 규칙, 기준 데이터, 최신성 metadata가 필요한 차원을 구분하는 품질 차원별 측정 가능성 부록
높은 결측값 비율, 상수 컬럼, 낮은 고유값 비율, 중복 행, 품질 점수 해석 한계에 사용한 경고 임계값을 기록하는 진단 기준 및 임계값 부록

품질 프레임워크 매핑은 해석 계층입니다. 기존 Truthound 프로파일 및 검증 계산 의미를 변경하지 않으며, 입력 프로파일에 근거가 없는 업무상 정확성, 시의성, 도메인 일관성을 측정했다고 주장하지 않습니다.

경고 임계값은 alert 생성기가 사용하는 보고서 정책 source와 같은 기준에서 관리됩니다. 따라서 산출물에 표시되는 진단 기준 부록과 실제 경고 발생 동작이 서로 어긋나지 않습니다.

고급 연동에서는 ReportDocument를 통해 HTML/PDF builder가 사용하는 보고서 구조 adapter를 확인할 수 있습니다. 이 계층은 장, 부록, 품질 차원, 해석 rule, 보고서 객체 registry metadata를 안정적으로 제공하며 generate_html_report, HTMLReportBuilder, export_to_pdf 동작과 프로파일/검증 계산 의미는 변경하지 않습니다. 렌더링 전에 보고서 구조를 검토해야 하는 애플리케이션에서 이 계층을 사용할 수 있습니다.

생성된 부록은 패키지 버전, Python 버전, 플랫폼, 선택 테마, 언어, 데이터 출처, metadata fingerprint 같은 재현성 정보를 사용합니다. fingerprint에는 원본 입력 데이터 값을 포함하지 않습니다. 보고서 제목, 부제, 데이터 출처, 캡션, 자동 생성된 보고서 객체 문구는 렌더링 전 escape 처리됩니다. 신뢰할 수 있는 보고서 커스터마이징을 위한 custom_css와 custom_js 설정은 기존처럼 사용할 수 있습니다.

보고서 본문은 [표 1], [그림 2], 부록 C처럼 자동 생성된 보고서 객체를 참조하여 해석과 근거를 연결합니다. 본문에서 표 또는 그림 번호가 반복되는 것은 의도된 참조이며, canonical 번호는 각 표·그림 캡션에 유지됩니다. 보고서 객체 참조는 렌더링 전에 registry에 등록되므로, 자동 생성 문장이 실제 보고서 구조에 없는 표, 그림, 부록을 가리키지 않도록 검증할 수 있습니다.

샘플 bundle 계약은 공개 테마인 light, dark, minimal 각각에 대해 한국어 A4 HTML 보고서를 생성합니다. 샘플 smoke는 binary golden image를 저장하지 않고 보고서 제목, 표/그림/부록 번호 체계, 진단 기준 부록, 한국어 typography, localized alert narrative가 유지되는지 확인합니다.

Detailed 설정 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, ProfileDataConverter, TableProfile을(를) 기준으로 데이터 품질 검증, 워크플로우 자동화, 결과 해석 방법을 설명합니다.

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="light",        # 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 워크플로우 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="light",
    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 레퍼런스¶

ReportConfig¶

@dataclass
class ReportConfig:
    theme: ReportTheme = ReportTheme.LIGHT
    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 = ""

함께 보기¶

실무 운영 가이드에서 Themes, Theme을(를) 기준으로 데이터 품질 검증, 워크플로우 자동화, 결과 해석 방법을 설명합니다.
실무 운영 가이드에서 Charts, Chart을(를) 기준으로 데이터 품질 검증, 워크플로우 자동화, 결과 해석 방법을 설명합니다.
Sections - Section 설정
실무 운영 가이드에서 PDF, Export을(를) 기준으로 데이터 품질 검증, 워크플로우 자동화, 결과 해석 방법을 설명합니다.