pdf-processing-pro

PDF Processing Pro

生产就绪的 PDF 处理工具包，内置预构建脚本、全面的错误处理，并支持复杂工作流。

快速开始

从 PDF 中提取文本

import pdfplumber

with pdfplumber.open("document.pdf") as pdf:
    text = pdf.pages[0].extract_text()
    print(text)

分析 PDF 表单（使用内置脚本）

python scripts/analyze_form.py input.pdf --output fields.json
# Returns: JSON with all form fields, types, and positions

带验证地填写 PDF 表单

python scripts/fill_form.py input.pdf data.json output.pdf
# Validates all fields before filling, includes error reporting

从 PDF 中提取表格

python scripts/extract_tables.py report.pdf --output tables.csv
# Extracts all tables with automatic column detection

功能特性

✅ 生产就绪的脚本

所有脚本均包含：

• 错误处理：优雅失败，并提供详细错误信息
• 验证：输入验证与类型检查
• 日志记录：可配置日志，带时间戳
• 类型提示：完整的类型注解，支持 IDE
• 命令行接口：所有脚本均支持 --help 标志
• 退出码：适用于自动化的正确退出码

✅ 全面的工作流

• PDF 表单：完整的表单处理流水线
• 表格提取：高级表格检测与提取
• OCR 处理：扫描版 PDF 文本提取
• 批量操作：高效处理多个 PDF
• 验证：处理前与处理后验证

高级主题

PDF 表单处理

完整的表单工作流包括：

• 字段分析与检测
• 动态表单填写
• 验证规则
• 多页表单
• 复选框与单选按钮处理

参见 FORMS.md

表格提取

适用于复杂表格提取：

• 多页表格
• 合并单元格
• 嵌套表格
• 自定义表格检测
• 导出为 CSV/Excel

参见 TABLES.md

OCR 处理

适用于扫描版 PDF 和基于图像的文档：

• 集成 Tesseract
• 多语言支持
• 图像预处理
• 置信度评分
• 批量 OCR

参见 OCR.md

内置脚本

表单处理

analyze_form.py - 提取表单字段信息

python scripts/analyze_form.py input.pdf [--output fields.json] [--verbose]

fill_form.py - 使用数据填写 PDF 表单

python scripts/fill_form.py input.pdf data.json output.pdf [--validate]

validate_form.py - 在填写前验证表单数据

python scripts/validate_form.py data.json schema.json

表格提取

extract_tables.py - 将表格提取为 CSV/Excel

python scripts/extract_tables.py input.pdf [--output tables.csv] [--format csv|excel]

文本提取

extract_text.py - 提取文本并保留格式

python scripts/extract_text.py input.pdf [--output text.txt] [--preserve-formatting]

实用工具

merge_pdfs.py - 合并多个 PDF

python scripts/merge_pdfs.py file1.pdf file2.pdf file3.pdf --output merged.pdf

split_pdf.py - 将 PDF 拆分为单独的页面

python scripts/split_pdf.py input.pdf --output-dir pages/

validate_pdf.py - 验证 PDF 完整性

python scripts/validate_pdf.py input.pdf

常见工作流

工作流 1：处理表单提交

# 1. Analyze form structure
python scripts/analyze_form.py template.pdf --output schema.json

# 2. Validate submission data
python scripts/validate_form.py submission.json schema.json

# 3. Fill form
python scripts/fill_form.py template.pdf submission.json completed.pdf

# 4. Validate output
python scripts/validate_pdf.py completed.pdf

工作流 2：从报告中提取数据

# 1. Extract tables
python scripts/extract_tables.py monthly_report.pdf --output data.csv

# 2. Extract text for analysis
python scripts/extract_text.py monthly_report.pdf --output report.txt

工作流 3：批量处理

import glob
from pathlib import Path
import subprocess

# Process all PDFs in directory
for pdf_file in glob.glob("invoices/*.pdf"):
    output_file = Path("processed") / Path(pdf_file).name

    result = subprocess.run([
        "python", "scripts/extract_text.py",
        pdf_file,
        "--output", str(output_file)
    ], capture_output=True)

    if result.returncode == 0:
        print(f"✓ Processed: {pdf_file}")
    else:
        print(f"✗ Failed: {pdf_file} - {result.stderr}")

错误处理

所有脚本遵循一致的错误模式：

# Exit codes
# 0 - Success
# 1 - File not found
# 2 - Invalid input
# 3 - Processing error
# 4 - Validation error

# Example usage in automation
result = subprocess.run(["python", "scripts/fill_form.py", ...])

if result.returncode == 0:
    print("Success")
elif result.returncode == 4:
    print("Validation failed - check input data")
else:
    print(f"Error occurred: {result.returncode}")

依赖项

所有脚本均需要：

pip install pdfplumber pypdf pillow pytesseract pandas

OCR 可选依赖：

# Install tesseract-ocr system package
# macOS: brew install tesseract
# Ubuntu: apt-get install tesseract-ocr
# Windows: Download from GitHub releases

性能建议

• 对多个 PDF 使用批量处理
• 使用 --parallel 标志启用多进程（在支持的情况下）
• 缓存已提取的数据，避免重复处理
• 尽早验证输入，快速失败
• 对大文件使用流式处理（>50MB）

最佳实践

1. 处理前始终验证输入
2. 在自定义脚本中使用 try-except
3. 记录所有操作，便于调试
4. 在生产环境使用前用示例 PDF 进行测试
5. 为长时间运行的操作设置超时
6. 在自动化中检查退出码
7. 修改前备份原始文件

故障排除

常见问题

“Module not found” 错误：

pip install -r requirements.txt

未找到 Tesseract：

# Install tesseract system package (see Dependencies)

处理大 PDF 时出现内存错误：

# Process page by page instead of loading entire PDF
with pdfplumber.open("large.pdf") as pdf:
    for page in pdf.pages:
        text = page.extract_text()
        # Process page immediately

权限错误：

chmod +x scripts/*.py

获取帮助

所有脚本均支持 --help：

python scripts/analyze_form.py --help
python scripts/extract_tables.py --help

有关特定主题的详细文档，请参见：

• FORMS.md - 完整的表单处理指南
• TABLES.md - 高级表格提取
• OCR.md - 扫描版 PDF 处理