pdf-report-generator 0.1.0

A flexible PDF report generator with JSON configuration support

PDF报告生成服务

一个强大、灵活的PDF报告生成系统，支持通过JSON配置文件定义报告格式，自动从多种数据源获取数据并生成专业的PDF文档。

✨ 特性

核心功能

• 📄 JSON配置驱动 - 通过JSON文件灵活定义PDF报告结构和样式
• 🔌 多种数据源 - 支持JSON、CSV、Excel、数据库、HTTP API等数据源
• 📊 丰富的元素类型 - 文本、表格、图表（柱状图、折线图、饼图等）、图片
• 🎨 自定义样式 - 完全可定制的文本和表格样式
• 🚀 两种使用方式 - Python库直接调用 或 FastAPI Web服务
• 🔄 模板变量支持 - 使用Jinja2模板引擎动态渲染内容
• 📈 专业图表 - 基于Matplotlib生成高质量图表

高级功能 ⭐

• 📑 页眉页脚 - 支持文本、图片、页码，左中右三栏布局，变量替换
• 📚 自动目录 - 自动收集标题生成可点击的目录，支持多级层级
• 🎨 封面页 - 灵活的封面设计，支持背景图片/渐变，多个预设模板
• 🔢 多种页码格式 - 阿拉伯数字、罗马数字、中文数字
• 🔗 超链接书签 - 目录自动添加跳转链接
• 📋 表格合并 - 支持复杂的单元格合并
• 🈲 中文字体 - 自动加载中文字体，完美支持中文显示

🚀 快速开始

安装

方式 1: 通过 pip 安装（推荐）

# 基础安装（仅核心 PDF 生成功能）
pip install pdf-report-generator

# 安装包含 API 服务器支持
pip install pdf-report-generator[api]

# 安装所有功能
pip install pdf-report-generator[all]

方式 2: 从源码安装（开发环境）

# 克隆项目
git clone <repository-url>
cd pdf-report

# 开发模式安装
pip install -e .

# 或安装包含 API 支持
pip install -e .[api]

方式 3: 直接使用源码

# 克隆项目
git clone <repository-url>
cd pdf-report

# 安装依赖
pip install -r requirements.txt

📖 详细安装说明请查看 INSTALLATION.md

方式1: Python库使用

from pdf_generator import PDFReportGenerator
import pandas as pd

# 方式1: 从配置文件生成
generator = PDFReportGenerator(config_path="templates/sales_report.json")
generator.save("output.pdf")

# 方式2: 使用配置字典
config = {
    "metadata": {
        "title": "销售报告",
        "pageSize": "A4"
    },
    "elements": [
        {
            "type": "text",
            "content": "{{metadata.title}}",
            "style": "title"
        }
    ]
}

generator = PDFReportGenerator(config_dict=config)
generator.save("output.pdf")

# 方式3: 动态添加数据
data = pd.DataFrame({
    "产品": ["A", "B", "C"],
    "销量": [100, 200, 150]
})

generator.add_data_source("sales", data)
pdf_bytes = generator.to_bytes()  # 获取字节流

# 方式4: 指定中文字体目录（如需显示中文）
generator = PDFReportGenerator(
    config_dict=config,
    font_dirs=['./fonts', 'C:\\Windows\\Fonts']  # 字体目录
)

方式2: Web API服务

启动服务

使用库安装后（推荐）：

# 方式1: Python 代码启动
from pdf_generator import start_api_server

start_api_server(host="localhost", port=8080)

# 方式2: 命令行启动
pdf-report-api --host localhost --port 8080

# 开发模式（热重载）
pdf-report-api --reload

# 生产模式（多进程）
pdf-report-api --workers 4

或使用传统方式：

# 直接运行
python -m api.main

# 使用 uvicorn
uvicorn api.main:app --reload --host 0.0.0.0 --port 8000

使用API

import requests

# 生成PDF
config = {
    "metadata": {"title": "API报告"},
    "elements": [
        {"type": "text", "content": "Hello PDF!"}
    ]
}

response = requests.post(
    "http://localhost:8000/api/generate",
    json={"config": config}
)

with open("output.pdf", "wb") as f:
    f.write(response.content)

API端点

• GET / - 服务状态
• POST /api/generate - 生成PDF（JSON配置）
• POST /api/generate/upload - 生成PDF（文件上传）
• POST /api/validate - 验证配置
• GET /api/templates - 获取模板列表
• GET /api/health - 健康检查

📋 配置文件结构

完整示例

{
  "metadata": {
    "title": "销售分析报告",
    "author": "系统",
    "pageSize": "A4",
    "orientation": "portrait",
    "margin": 0.75
  },
  "styles": {
    "title": {
      "fontSize": 24,
      "textColor": "#333333",
      "alignment": "center",
      "bold": true,
      "spaceBefore": 0,
      "spaceAfter": 20
    },
    "tableStyle": {
      "gridColor": "#CCCCCC",
      "headerBackground": "#4472C4",
      "headerTextColor": "#FFFFFF",
      "fontSize": 9
    }
  },
  "dataSources": [
    {
      "name": "sales_data",
      "type": "csv",
      "path": "data/sales.csv"
    },
    {
      "name": "api_data",
      "type": "api",
      "url": "https://api.example.com/data"
    }
  ],
  "elements": [
    {
      "type": "text",
      "content": "{{metadata.title}}",
      "style": "title"
    },
    {
      "type": "table",
      "dataSource": "sales_data",
      "columns": ["产品", "销量", "金额"],
      "style": "tableStyle"
    },
    {
      "type": "chart",
      "chartType": "bar",
      "dataSource": "sales_data",
      "xAxis": "产品",
      "yAxis": "销量",
      "title": "销量对比",
      "width": 6,
      "height": 4
    }
  ]
}

配置说明

Metadata（元数据）

字段	类型	说明	可选值
title	string	PDF标题	-
author	string	作者	-
pageSize	string	页面大小	A4, A3, A5, LETTER, LEGAL
orientation	string	页面方向	portrait, landscape
margin	number	页边距（英寸）	-

Styles（样式）

段落样式

• fontSize - 字体大小
• textColor - 文本颜色（#RRGGBB）
• alignment - 对齐方式（left/center/right/justify）
• bold - 是否加粗
• spaceBefore - 段前间距
• spaceAfter - 段后间距

表格样式

• gridColor - 网格线颜色
• headerBackground - 表头背景色
• headerTextColor - 表头文字颜色
• fontSize - 字体大小
• padding - 单元格内边距

Data Sources（数据源）

CSV/Excel

{
  "name": "my_data",
  "type": "csv",
  "path": "data/file.csv",
  "encoding": "utf-8"
}

JSON

{
  "name": "my_data",
  "type": "json",
  "path": "data/file.json"
}

API

{
  "name": "api_data",
  "type": "api",
  "url": "https://api.example.com/data",
  "method": "GET",
  "headers": {"Authorization": "Bearer token"}
}

数据库

{
  "name": "db_data",
  "type": "database",
  "dbType": "postgresql",
  "host": "localhost",
  "database": "mydb",
  "username": "user",
  "password": "pass",
  "query": "SELECT * FROM sales"
}

Elements（元素）

文本

{
  "type": "text",
  "content": "这是文本内容",
  "style": "body"
}

表格

{
  "type": "table",
  "dataSource": "sales_data",
  "columns": ["列1", "列2", "列3"],
  "style": "tableStyle",
  "columnWidths": [2, 1.5, 1.5]
}

图表

支持的图表类型：bar（柱状图）、line（折线图）、pie（饼图）、scatter（散点图）、area（面积图）

{
  "type": "chart",
  "chartType": "bar",
  "dataSource": "sales_data",
  "xAxis": "产品",
  "yAxis": "销量",
  "title": "销量对比图",
  "width": 6,
  "height": 4,
  "grid": true
}

图片

{
  "type": "image",
  "path": "images/logo.png",
  "width": 200,
  "alignment": "center",
  "keepAspectRatio": true
}

其他元素

• spacer - 空白间隔
• pagebreak - 分页符
• list - 列表

📚 示例

示例1: 简单报告

from pdf_generator import PDFReportGenerator

config = {
    "metadata": {"title": "简单报告"},
    "elements": [
        {
            "type": "text",
            "content": "这是一个简单的PDF报告",
            "style": "title"
        }
    ]
}

generator = PDFReportGenerator(config_dict=config)
generator.save("simple.pdf")

示例2: 数据表格和图表

import pandas as pd
from pdf_generator import PDFReportGenerator

# 准备数据
data = pd.DataFrame({
    "产品": ["A", "B", "C"],
    "销量": [150, 230, 180],
    "金额": [45000, 69000, 54000]
})

config = {
    "metadata": {"title": "销售报告"},
    "styles": {
        "title": {"fontSize": 20, "alignment": "center"},
        "table1": {
            "headerBackground": "#4472C4",
            "headerTextColor": "#FFFFFF"
        }
    },
    "elements": [
        {"type": "text", "content": "销售数据", "style": "title"},
        {"type": "spacer", "height": 0.5},
        {"type": "table", "dataSource": "sales", "style": "table1"},
        {"type": "spacer", "height": 0.5},
        {
            "type": "chart",
            "chartType": "bar",
            "dataSource": "sales",
            "xAxis": "产品",
            "yAxis": "销量",
            "title": "销量对比",
            "width": 6,
            "height": 4
        }
    ]
}

generator = PDFReportGenerator(config_dict=config)
generator.add_data_source("sales", data)
generator.save("sales_report.pdf")

示例3: 使用配置文件

查看 templates/ 目录下的示例配置：

• sales_report.json - 销售报告模板
• financial_report.json - 财务报告模板

from pdf_generator import PDFReportGenerator

generator = PDFReportGenerator(config_path="templates/sales_report.json")
generator.save("output.pdf")

运行示例代码

# 独立使用示例
python examples/standalone_usage.py

# API使用示例（需要先启动API服务）
python -m api.main  # 终端1
python examples/api_usage.py  # 终端2

🏗️ 项目结构

pdf-report/
├── pdf_generator/           # 核心库
│   ├── core/               # PDF生成引擎
│   │   ├── generator.py    # 主生成器
│   │   ├── elements.py     # PDF元素
│   │   └── styles.py       # 样式管理
│   ├── data_sources/       # 数据源适配器
│   │   ├── base.py
│   │   ├── json_source.py
│   │   ├── csv_source.py
│   │   ├── api_source.py
│   │   └── database.py
│   ├── config/             # 配置处理
│   │   ├── parser.py
│   │   └── validator.py
│   └── utils/
│       └── chart_generator.py
├── api/                    # Web API服务
│   ├── main.py
│   ├── routes.py
│   └── models.py
├── templates/              # 配置模板
│   ├── sales_report.json
│   └── financial_report.json
├── examples/               # 使用示例
│   ├── standalone_usage.py
│   └── api_usage.py
├── data/                   # 示例数据
├── requirements.txt
└── README.md

🔧 技术栈

核心库

• ReportLab - PDF生成引擎
• Pandas - 数据处理
• Matplotlib - 图表生成
• Jinja2 - 模板引擎
• Pillow - 图像处理

Web服务

• FastAPI - Web框架
• Uvicorn - ASGI服务器
• Pydantic - 数据验证

数据源支持

• JSON/CSV/Excel文件
• HTTP API
• 数据库（SQLite/PostgreSQL/MySQL）

📖 API文档

启动服务后，访问以下地址查看完整API文档：

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

🛠️ 高级用法

自定义字体

from reportlab.pdfbase import pdfmetrics
from reportlab.pdfbase.ttfonts import TTFont

# 注册自定义字体
pdfmetrics.registerFont(TTFont('CustomFont', 'path/to/font.ttf'))

# 在样式中使用
config = {
    "styles": {
        "custom": {
            "fontName": "CustomFont",
            "fontSize": 12
        }
    }
}

条件渲染

使用Jinja2模板语法：

{
  "type": "text",
  "content": "{% if revenue > 100000 %}高收入{% else %}正常{% endif %}"
}

复杂图表

{
  "type": "chart",
  "chartType": "line",
  "dataSource": "data",
  "xAxis": "month",
  "yAxis": ["revenue", "cost", "profit"],
  "title": "财务趋势",
  "width": 7,
  "height": 5,
  "grid": true,
  "showLegend": true,
  "legendPosition": "upper left"
}

📚 文档

快速入门

• 快速开始指南 - 5分钟快速上手
• 安装说明 - 详细安装步骤

功能文档

• 使用手册 - 完整使用说明
• 高级功能指南 - 页眉页脚、目录、封面 ⭐
• 高级功能快速参考 - 快速查阅手册
• 表格合并功能 - 复杂表格处理
• 图片使用指南 - 图片插入和调整

配置说明

• 中文字体配置 - 中文显示支持
• 配置示例 - JSON配置模板

其他

• 项目总结 - 项目架构和设计
• 更新日志 - 版本更新记录

🤝 贡献

欢迎提交Issue和Pull Request！

📄 许可证

MIT License

📞 支持

如有问题，请提交Issue或联系开发团队。

---

开始使用PDF报告生成服务，让数据可视化更简单！ 🚀