report-generator

报告生成器

创建包含图表、表格和叙述文本的专业数据驱动报告。非常适合业务报告、分析仪表板、状态更新和自动化报告流水线。

快速入门

from scripts.report_gen import ReportGenerator

# Create a simple report
report = ReportGenerator("Monthly Sales Report")
report.add_text("This report summarizes sales performance for Q4 2024.")
report.add_table(sales_data, title="Sales by Region")
report.add_chart(sales_data, chart_type="bar", title="Revenue by Month")
report.add_text("Key findings: Revenue increased 25% quarter-over-quarter.")
report.generate().save("sales_report.pdf")

# From template
report = ReportGenerator.from_template("executive_summary")
report.set_data(data_dict)
report.generate().save("exec_summary.pdf")

功能

• 多种输出格式：PDF、HTML
• 丰富的内容：文本、表格、图表、图片、标题
• 图表类型：柱状图、折线图、饼图、散点图、面积图、热力图
• 表格格式：自动样式设置、条件格式
• 模板：预构建报告模板
• 品牌设计：徽标、颜色、字体、页眉/页脚
• 章节：目录、页码、附录
• 数据集成：CSV、DataFrame、字典输入

API 参考

初始化

# New report
report = ReportGenerator("Report Title")
report = ReportGenerator("Report Title", subtitle="Q4 2024 Analysis")

# From template
report = ReportGenerator.from_template("quarterly_review")

# With config
report = ReportGenerator("Title", config={
    "page_size": "letter",
    "orientation": "portrait",
    "margins": {"top": 1, "bottom": 1, "left": 0.75, "right": 0.75}
})

报告元数据

# Title and subtitle
report.set_title("Annual Report 2024")
report.set_subtitle("Financial Performance Analysis")

# Author and date
report.set_author("Analytics Team")
report.set_date("December 2024")
report.set_date_auto()  # Use today

# Organization
report.set_organization("Acme Corporation")
report.set_logo("logo.png")

添加内容

文本内容

# Simple paragraph
report.add_text("This is a paragraph of analysis text.")

# Styled text
report.add_text("Important finding!", style="highlight")
report.add_text("Key metric: 42%", style="metric")

# Headers
report.add_heading("Executive Summary", level=1)
report.add_heading("Revenue Analysis", level=2)
report.add_heading("By Region", level=3)

# Bullet points
report.add_bullets([
    "Revenue increased 25% YoY",
    "Customer acquisition up 15%",
    "Churn rate decreased to 3%"
])

# Numbered list
report.add_numbered_list([
    "Expand to European markets",
    "Launch mobile application",
    "Implement AI-driven analytics"
])

表格

# From DataFrame
import pandas as pd
df = pd.DataFrame({
    'Region': ['North', 'South', 'East', 'West'],
    'Revenue': [100000, 85000, 92000, 78000],
    'Growth': ['12%', '8%', '15%', '5%']
})
report.add_table(df, title="Regional Performance")

# From dict/list
data = [
    {'Product': 'A', 'Sales': 1000, 'Profit': 200},
    {'Product': 'B', 'Sales': 1500, 'Profit': 350}
]
report.add_table(data, title="Product Summary")

# With styling
report.add_table(df, title="Sales Data",
    highlight_max=['Revenue'],       # Highlight max values
    highlight_min=['Growth'],        # Highlight min values
    currency_cols=['Revenue'],       # Format as currency
    percent_cols=['Growth'],         # Format as percent
    align={'Region': 'left', 'Revenue': 'right'}
)

图表

# Bar chart
report.add_chart(
    data=df,
    chart_type="bar",
    x="Region",
    y="Revenue",
    title="Revenue by Region"
)

# Line chart
report.add_chart(
    data=time_series_df,
    chart_type="line",
    x="Month",
    y=["Sales", "Forecast"],
    title="Sales Trend"
)

# Pie chart
report.add_chart(
    data=category_df,
    chart_type="pie",
    values="Amount",
    labels="Category",
    title="Budget Allocation"
)

# Chart options
report.add_chart(
    data=df,
    chart_type="bar",
    x="Region",
    y="Revenue",
    title="Revenue Analysis",
    color="#3498db",
    width=6,           # inches
    height=4,
    show_values=True,
    show_legend=True
)

图片

# Add image
report.add_image("screenshot.png", caption="Dashboard View")
report.add_image("diagram.png", width=5, caption="Architecture Diagram")

特殊元素

# Page break
report.add_page_break()

# Horizontal line
report.add_divider()

# Spacer
report.add_spacer(height=0.5)  # inches

# Callout box
report.add_callout(
    "Key Insight: Customer retention improved 20% after implementing the new onboarding flow.",
    style="info"  # info, warning, success, error
)

# Quote
report.add_quote(
    "Data is the new oil.",
    attribution="Clive Humby"
)

章节和结构

# Start a new section
report.start_section("Financial Analysis")

# Add content to section
report.add_text("...")
report.add_table(...)

# End section
report.end_section()

# Table of contents (auto-generated)
report.enable_toc()

# Appendix
report.start_appendix()
report.add_heading("Raw Data", level=2)
report.add_table(raw_data)

品牌设计和样式

# Logo and organization
report.set_logo("logo.png", width=150)
report.set_organization("Acme Corp")

# Colors
report.set_colors(
    primary="#1e40af",      # Headers, accents
    secondary="#6b7280",    # Secondary text
    background="#ffffff"    # Background
)

# Fonts
report.set_fonts(
    heading="Helvetica-Bold",
    body="Helvetica"
)

# Header and footer
report.set_header("Confidential - Internal Use Only")
report.set_footer("Page {page} of {total}")

# Watermark
report.set_watermark("DRAFT")

模板

# Available templates
report = ReportGenerator.from_template("executive_summary")
report = ReportGenerator.from_template("quarterly_review")
report = ReportGenerator.from_template("project_status")
report = ReportGenerator.from_template("analytics_dashboard")

# Template with data
report = ReportGenerator.from_template("monthly_metrics")
report.set_data({
    "period": "December 2024",
    "revenue": 1500000,
    "growth": 0.15,
    "customers": 5000,
    "charts": {"revenue_trend": trend_df}
})
report.generate()

生成和导出

# Generate report
report.generate()

# Save as PDF
report.save("report.pdf")

# Save as HTML
report.save("report.html")

# Get bytes
pdf_bytes = report.to_bytes()
html_string = report.to_html()

模板

执行摘要

• 标题页
• 关键指标亮点
• 摘要要点
• 图表部分
• 建议

季度回顾

• 业绩概览
• 财务指标
• 与上一季度对比
• 目标进度
• 下一季度展望

项目状态

• 项目概览
• 时间线/里程碑
• 风险和问题
• 团队更新
• 后续步骤

分析仪表板

• KPI 卡片
• 多个图表
• 趋势分析
• 数据表格
• 洞察

CLI 用法

# Generate from JSON config
python report_gen.py --config report_config.json --output report.pdf

# With template
python report_gen.py --template executive_summary --data data.json --output summary.pdf

# Quick report from CSV
python report_gen.py --csv data.csv --title "Data Report" --output report.pdf

CLI 参数

参数	说明	默认值
--config	报告配置 JSON	-
--template	模板名称	-
--data	数据 JSON 文件	-
--csv	CSV 数据文件	-
--title	报告标题	Report
--output	输出文件路径	report.pdf
--format	输出格式（pdf/html）	pdf

示例

销售报告

report = ReportGenerator("Q4 Sales Report")
report.set_subtitle("October - December 2024")
report.set_organization("Sales Department")
report.set_logo("company_logo.png")

report.add_heading("Executive Summary", level=1)
report.add_text(
    "Q4 2024 showed strong performance across all regions, "
    "with total revenue reaching $4.2M, a 23% increase over Q3."
)

report.add_callout(
    "Total Revenue: $4.2M (+23% QoQ)",
    style="success"
)

report.add_heading("Regional Performance", level=2)
report.add_chart(regional_data, "bar", x="Region", y="Revenue",
                 title="Revenue by Region")
report.add_table(regional_data, title="Detailed Metrics")

report.add_heading("Trends", level=2)
report.add_chart(monthly_data, "line", x="Month", y="Revenue",
                 title="Monthly Revenue Trend")

report.add_heading("Recommendations", level=1)
report.add_bullets([
    "Increase investment in high-growth East region",
    "Address declining West region performance",
    "Launch Q1 promotional campaign"
])

report.generate().save("q4_sales_report.pdf")

分析仪表板

report = ReportGenerator("Marketing Analytics")
report.set_date_auto()

# KPI Summary
report.add_heading("Key Metrics", level=1)
kpis = [
    ["Visitors", "125,000", "+15%"],
    ["Conversions", "3,750", "+22%"],
    ["Revenue", "$187,500", "+18%"],
    ["CAC", "$45", "-8%"]
]
report.add_table(kpis, headers=["Metric", "Value", "Change"])

# Traffic Sources
report.add_heading("Traffic Sources", level=2)
report.add_chart(traffic_df, "pie", values="Sessions", labels="Source",
                 title="Traffic Distribution")

# Conversion Funnel
report.add_heading("Conversion Funnel", level=2)
report.add_chart(funnel_df, "bar", x="Stage", y="Users",
                 title="Funnel Analysis", horizontal=True)

# Trend Analysis
report.add_heading("Trends", level=2)
report.add_chart(daily_df, "line", x="Date", y=["Visitors", "Conversions"],
                 title="Daily Performance")

report.generate().save("marketing_dashboard.pdf")

依赖项

reportlab>=4.0.0
Pillow>=10.0.0
pandas>=2.0.0
matplotlib>=3.7.0

限制

• PDF 中的图表会渲染为静态图片
• 复杂布局可能需要手动调整
• 大型数据集可能会影响性能
• HTML 输出仅提供基本样式（不含交互式图表）