pdfplumber说明文档翻译
以下是第一次翻译的内容,如果要看到最新的请看我的github: hbh112233abc/pdfplumber
pdfplumber
解析PDF文件,获取相关的文本字符、矩形和线条的详细信息。 额外功能：表格提取和可视化调试。
用于电脑生成的PDF上效果最好，不支持扫描的PDF，基于pdfminer.six实现.
当前版本 测试用例 已经在 Python 3.6, 3.7, 3.8 验证通过.
目录
- 安装
- 命令行
- Python包
- 可视化调试
- 提取表格
- 提取表单域值
- 用例演示
- 与其他库比较
安装
pip install pdfplumber
命令行
基础示例
curl "https://raw.githubusercontent.com/jsvine/pdfplumber/stable/examples/pdfs/background-checks.pdf" > background-checks.pdf
pdfplumber < background-checks.pdf > background-checks.csv
输出将是一个CSV，包含PDF中每个字符、行和矩形的信息。
配置项
| 参数 | 说明 |
|---|---|
--format [输出格式] |
csv 或 json. json 返回信息包括PDF文件级和页面级元数据，以及字典嵌套属性。 |
--pages [页码] |
1-页面索引或页面范围. 举例: 1, 11-15, 指定的页面范围: 1, 11, 12, 13, 14, 15. |
--types [提取对象类型列表] |
可选值: char, rect, line, curve, image, annot等,默认全部提取 |
--laparams |
json格式字符串 (例: '{"detect_vertical": true}') PDF打开的传参 pdfplumber.open(..., laparams=...). |
--precision [整数] |
浮点数四舍五入的小数位数。默认为无舍入。 |
Python库
基础示例
import pdfplumber
with pdfplumber.open("path/to/file.pdf") as pdf:
first_page = pdf.pages[0]
print(first_page.chars[0])
加载PDF
调用pdfplumber.open(x)加载PDF, 其中x可以有以下几种格式:
- PDF文件路径
- 文件对象, 以字节流形式加载
- 类文件对象, 以字节流形式加载
open方法加载文件后返回一个 pdfplumber.PDF 实例.
传入 password 参数用于加载已加密的PDF文件, 例: pdfplumber.open("file.pdf", password = "test").
传入 laparams 参数可以使用pdfminer.six的布局引擎用于布局分析, 例: pdfplumber.open("file.pdf", laparams = { "line_overlap": 0.7 }).
Invalid metadata values are treated as a warning by default. If that is not intended, pass strict_metadata=True to the open method and pdfplumber.open will raise an exception if it is unable to parse the metadata.
默认情况下，无效元数据值只是被视为警告。如果设置strict_metadata=True。当加载PDF后无法分析元数据，将抛出异常。
pdfplumber.PDF 类
pdfplumber.PDF 类代表一个PDF文件,主要有以下两个属性:
| 属性 | 说明 |
|---|---|
.metadata |
元数据键/值对字典，摘自PDF的“信息”。通常包括“CreationDate”(创建日期)、“ModDate”(修改日期)、“Producer”(创建者)等。 |
.pages |
包含pdfplumber.Page(页实例)的列表。 |
pdfplumber.Page 类
pdfplumber.Page是pdfplumber核心. 大部分的操作都是围绕此类进行.主要包含以下属性:
| 属性 | 说明 |
|---|---|
.page_number |
页码, 1第一页, 2第二页, 以此类推. |
.width |
页面宽. |
.height |
页面高. |
.objects / .chars / .lines / .rects / .curves / .images |
这些属性中的每一个都是一个列表，每个列表都为嵌入在页面上的每个此类对象包含一个字典。有关详细信息，请参见 “Objects”. |
… pdfplumber.Page的主要方法:
| 方法 | 说明 |
|---|---|
.crop(bounding_box, relative=False) |
返回裁剪边界框中的页面内容，边界框应表示为4元组，值为 (x0, top, x1, bottom)。裁剪的页面保留至少部分位于边界框内的对象。如果对象仅部分落在长方体中，则将剖切其被边界框包含的部分。如果relative=True，则边界框计算为距页面左上角的偏移量，而不是绝对位置。 (参考 Issue #245 给出的直观示例和说明.) |
.within_bbox(bounding_box, relative=False) |
类似.crop,但仅保留完全落在边界框内的对象。 |
.filter(test_function) |
过滤对象.objects,仅提取当过滤函数test_function(obj)返回True的对象. |
.dedupe_chars(tolerance=1) |
删除重复的字符-与其他字符共享相同的文本、字体名称、大小和位置（在“公差”x/y范围内）-已删除. (参考 Issue #71了解该机制) |
.extract_text(x_tolerance=3, y_tolerance=3, layout=False, x_density=7.25, y_density=13, **kwargs) |
将页面的所有字符对象整理为单个字符串.
|
.extract_words(x_tolerance=3, y_tolerance=3, keep_blank_chars=False, use_text_flow=False, horizontal_ltr=True, vertical_ttb=True, extra_attrs=[]) |
返回词块的内容及边框. 如果（“垂直”字符）一个字符的x1与下一个字符的x0之间的差值小于或等于x_tolerance 并且 一个字符的 doctop与下一个字符的 doctop小于或等于 y_tolerance，则单词被视为字符序列.对于非垂直字符，也采用类似的方法，但测量它们之间的垂直距离，而不是水平距离。参数 horizontal_ltr 和 vertical_ttb 表示阅读顺序为水平由左至右的顺序及垂直由上而下的顺序. 设置 keep_blank_chars为 True将空格作为单词的一部分而不是分隔符. 设置 use_text_flow 为 True将使用PDF的基本字符流作为单词排序和分段的指南，而不是按x/y位置对字符进行预排序。 (这模仿了拖动光标如何突出显示PDF中的文本；因此，顺序并不总是符合逻辑的。) 设置extra_attrs额外属性列表 (例: ["fontname", "size"] 将每个单词限制为每个单词共享完全相同值的字符 字符属性, 查看单词属性字典 |
.search(pattern, regex=True, case=True, **kwargs) |
实验特性 它允许您搜索页面的文本，返回与查询匹配的所有实例的列表。对于每个实例，返回对象都包含匹配的文本、任何正则表达式组匹配项、边界框坐标以及char对象本身 pattern可以是已编译的正则表达式、未编译的正则表达式或非正则表达式字符串。如果regex为 False，则该模式将被视为非regex字符串。如果 case为False，则以不区分大小写的方式执行搜索。 其他参数 **kwargs 参考 .extract_text(layout=True, ...). |
.extract_tables(table_settings) |
提取页面表格数据. 详情参考 “Extracting tables”. |
.to_image(**conversion_kwargs) |
返回 PageImage 实例. 详情参见 “可视化调试” . 转换参数参见 here. |
.close() |
默认Page 对象会缓存其布局和对象信息，以避免重新处理。然而，在解析大型PDF时，这些缓存属性可能需要大量内存。可以使用此方法刷新缓存并释放内存 (旧版本 <= 0.5.25, 请使用 .flush_cache().) |
对象
pdfplumber.PDF 和 pdfplumber.Page实例均提供各种类型的对象, 对象来自 pdfminer.sixPDF解析。以下属性分别返回匹配对象的Python列表：
.chars, 代表单个文本字符..lines, 代表一条一维线..rects, 代表单个二维矩形..curves, 代表一序列pdfminer.six无法识别成线或矩形的连接点,..images, 代表图像..annots, 代表一个PDF批注 (详见第8.4节 官方PDF规范).hyperlinks, 代表链接注释Link包含URI属性
以上每个对象都是字典形式,其包含以下属性:
char 属性
| 属性 | 说明 |
|---|---|
page_number |
找到此字符的页码。 |
text |
文本内容 例: “z”, 或 “Z” 或 " ". |
fontname |
字体 |
size |
字号 |
adv |
等于文本宽度字体大小比例因子。 |
upright |
是否垂直 |
height |
文本高度 |
width |
文本高度 |
x0 |
其左侧与页面左侧的距离。 |
x1 |
其右侧与页面左侧的距离。 |
y0 |
其下侧与页面底部的距离。 |
y1 |
其上侧与页面底部的距离。 |
top |
其上侧与页面顶部的距离。 |
bottom |
其下侧与页面顶部的距离。 |
doctop |
其顶部与文档顶部的距离。 |
matrix |
其“变换矩阵”。（详见下文） |
stroking_color |
笔划的颜色，表示为元组或整数，具体取决于使用的“颜色空间”。 |
non_stroking_color |
字体填充颜色 |
object_type |
对象类型:“char” |
备注: 文本变换矩阵(matrix)说明请参见章节4.2.2PDF参考 (第6版). 矩阵控制角色的缩放、倾斜和位置平移。旋转是缩放和倾斜的组合，但在大多数情况下可以认为等于x轴倾斜。 pdfplumber.ctm子模块定义了一个类 CTM，该类可以帮助进行这些计算。例如：
from pdfplumber.ctm import CTM
my_char = pdf.pages[0].chars[3]
my_char_ctm = CTM(*my_char["matrix"])
my_char_rotation = my_char_ctm.skew_x
line 属性
| 属性 | 说明 |
|---|---|
page_number |
其所在的页码 |
height |
高度 |
width |
宽度 |
x0 |
其左侧与页面左侧的距离。 |
x1 |
其右侧与页面左侧的距离。 |
y0 |
其下侧与页面底部的距离。 |
y1 |
其上侧与页面底部的距离。 |
top |
其上侧与页面顶部的距离。 |
bottom |
其下侧与页面顶部的距离。 |
doctop |
其顶部与文档顶部的距离。 |
linewidth |
线粗 |
stroking_color |
线条颜色,表示为元组或整数，具体取决于使用的“颜色空间” |
non_stroking_color |
线条填充颜色。 |
object_type |
对象类型:“line” |
rect 属性
| 属性 | 说明 |
|---|---|
page_number |
其所在的页码 |
height |
高度 |
width |
宽度 |
x0 |
其左侧与页面左侧的距离。 |
x1 |
其右侧与页面左侧的距离。 |
y0 |
其下侧与页面底部的距离。 |
y1 |
其上侧与页面底部的距离。 |
top |
其上侧与页面顶部的距离。 |
bottom |
其下侧与页面顶部的距离。 |
doctop |
其顶部与文档顶部的距离。 |
linewidth |
线粗 |
stroking_color |
线条颜色,表示为元组或整数，具体取决于使用的“颜色空间” |
non_stroking_color |
线条填充颜色。 |
object_type |
对象类型:“rect” |
curve 属性
| 属性 | 说明 |
|---|---|
page_number |
其所在的页码 |
points |
Points — 描述曲线的点列表包含 (x, top) 元组 |
height |
曲线边界框的高度。 |
width |
曲线边界框的宽度。 |
x0 |
曲线最左侧点与页面左侧的距离。 |
x1 |
曲线最右侧点与页面左侧的距离。 |
y0 |
曲线最低点到页面底部的距离。 |
y1 |
曲线最高点到页面底部的距离。 |
top |
曲线最高点到页面顶部的距离。 |
bottom |
曲线最低点到页面底部的距离。 |
doctop |
曲线最高点到文档顶部的距离。 |
linewidth |
线粗 |
fill |
是否填充曲线路径定义的形状. |
stroking_color |
曲线轮廓的颜色，表示为元组或整数，具体取决于使用的“颜色空间”。 |
non_stroking_color |
曲线填充颜色 |
object_type |
对象类型:“curve” |
此外， pdfplumber.PDF 和 pdfplumber.Page还提供以下两个对象：
.rect_edges （将每个矩形分解为四条线）
.edges（将 .rect_edges与 .lines组合在一起）。
image 属性
[待完善.]
获取pdfminer.six高级布局对象
加载PDF( pdfplumber.open(...))时通过传参laparams打开PDF后,每个页面对象将包含 pdfminer.six高级布局对象, 例如: "textboxhorizontal".
可视化调试
备注: 使用pdfplumber的可视化调试工具, 需要先安装以下两个软件:
ImageMagick. Installation instructions here.ghostscript. Installation instructions here,或者apt install ghostscript(Ubuntu) /brew install ghostscript(Mac).
输出页面图像对象 PageImage
使用 my_page.to_image()获取页面(包括裁剪页面)的图像对象 PageImage .设置分辨率resolution={integer}, 默认分辨率:72 例:
im = my_pdf.pages[0].to_image(resolution=150)
PageImage 对象可以很好地与IPython/Jupyter笔记本电脑配合使用；它们会自动渲染为单元格输出。例如：
[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-cyHzvImi-1656484509420)(examples/screenshots/visual-debugging-in-jupyter.png “Visual debugging in Jupyter”)]
PageImage 基础方法
| 方法 | 说明 |
|---|---|
im.reset() |
重置,清除已绘制的所有内容。 |
im.copy() |
将图像复制到新的“PageImage”对象。 |
im.save(path_or_fileobject, format="PNG") |
保存已标记的图片 |
绘制方法
你可以传递坐标或pdfplumberPDF对象 (例: char, line, rect)进行绘图.
| 单对象绘制 | 批量绘制 | 说明 |
|---|---|---|
im.draw_line(line, stroke={color}, stroke_width=1) |
im.draw_lines(list_of_lines, **kwargs) |
绘制线条根据line, curve, 或起止点坐标元组(例: ((x, y), (x, y))). |
im.draw_vline(location, stroke={color}, stroke_width=1) |
im.draw_vlines(list_of_locations, **kwargs) |
在location处x坐标处绘制一条垂直线 |
im.draw_hline(location, stroke={color}, stroke_width=1) |
im.draw_hlines(list_of_locations, **kwargs) |
在location处y坐标处绘制一条水平线 |
im.draw_rect(bbox_or_obj, fill={color}, stroke={color}, stroke_width=1) |
im.draw_rects(list_of_rects, **kwargs) |
绘制矩形rect, char, 等, 或4坐标元组边界框. |
im.draw_circle(center_or_obj, radius=5, fill={color}, stroke={color}) |
im.draw_circles(list_of_circles, **kwargs) |
以(x, y)为圆心画圆 char, rect, 等. |
备注:以上绘图方法是基于Pillow实现的 ImageDraw methods, 但是为了与SVG的一致性，调整了fill/stroke/stroke_width参数命名.
Debian系统修复ImageMagick问题
如果你在Debian系统使用pdfplumber遇到了PolicyError错误,你需要修改 /etc/ImageMagick-6/policy.xml:
<policy domain="coder" rights="none" pattern="PDF" />
修改为:
<policy domain="coder" rights="read|write" pattern="PDF" />
(policy.xml详细说明.)
提取表格
pdfplumber提取表格大部分借鉴 Anssi Nurminen的硕士论文, 灵感来源于 Tabula. 工作流程如下:
- 针对PDF页面, 查找（a）明确定义的行和/或（b）页面上单词对齐所隐含的行。
- 合并重叠或接近重叠的线条.
- 找出这些线条的交点.
- 找到使用这些交点作为顶点的最细粒度的矩形集（即单元格）。
- 将连续单元格分组到表中。
表格提取方法
pdfplumber.Page页面对象支持以下方法:
| 方法 | 说明 |
|---|---|
.find_tables(table_settings={}) |
返回表格 Table 对象列表. Table包含.cells, .rows,.bbox 属性, 以及方法.extract(x_tolerance=3, y_tolerance=3) |
.extract_tables(table_settings={}) |
返回从页面上找到的所有表中提取的文本，表示为列表列表列表，其结构为“表->行->单元格”。 |
.extract_table(table_settings={}) |
返回从页面上最大表中提取的文本，该表表示为列表列表，其结构为“行->单元格”。（如果多个表的大小相同（以单元格数衡量），则此方法将返回最靠近页面顶部的表。） |
.debug_tablefinder(table_settings={}) |
返回TableFinder类的实例，该类可以访问.edges(边), .intersections(交点), .cells(单元格)和.tables(表格)属性. |
举例:
pdf = pdfplumber.open("path/to/my.pdf")
page = pdf.pages[0]
page.extract_table()
查看更多示例
表格提取配置
默认情况下， extract_tables使用页面的垂直线和水平线（或矩形边）作为单元格分隔符。但该方法可以通过 table_settings参数进行高度自定义。以下是设置参数及默认值：
{
"vertical_strategy": "lines",
"horizontal_strategy": "lines",
"explicit_vertical_lines": [],
"explicit_horizontal_lines": [],
"snap_tolerance": 3,
"snap_x_tolerance": 3,
"snap_y_tolerance": 3,
"join_tolerance": 3,
"join_x_tolerance": 3,
"join_y_tolerance": 3,
"edge_min_length": 3,
"min_words_vertical": 3,
"min_words_horizontal": 1,
"keep_blank_chars": False,
"text_tolerance": 3,
"text_x_tolerance": 3,
"text_y_tolerance": 3,
"intersection_tolerance": 3,
"intersection_x_tolerance": 3,
"intersection_y_tolerance": 3,
}
| 配置项 | 说明 |
|---|---|
"vertical_strategy" |
垂直策略,可选值 "lines", "lines_strict", "text", "explicit".见后续说明 |
"horizontal_strategy" |
水平策略,可选值 "lines", "lines_strict", "text", "explicit". 见后续说明 |
"explicit_vertical_lines" |
明确划分表中单元格的垂直线列表。可与上述任何策略结合使用。列表中的项目应该是数字（表示一条直线的x坐标，即页面的全高）或 line/rect/curve对象。 |
"explicit_horizontal_lines" |
明确划分表中单元格的水平线列表。可与上述任何策略结合使用。列表中的项目应该是数字（表示一条直线的y坐标即页面的全高）或 line/rect/curve对象。 |
"snap_tolerance", "snap_x_tolerance", "snap_y_tolerance" |
snap_tolerance像素内的平行线将“捕捉”到相同的水平或垂直位置。 |
"join_tolerance", "join_x_tolerance", "join_y_tolerance" |
同一条无限线上的线段，其端点在彼此的join_tolerance范围内，将“连接”为一条线段 |
"edge_min_length" |
在尝试重建表之前，将丢弃小于edge_min_length的边 |
"min_words_vertical" |
使用 "horizontal_strategy": "text"时，至少 min_words_horizontal单词必须共享相同的对齐方式。 |
"min_words_horizontal" |
使用 "horizontal_strategy": "text"时,至少min_words_horizontal单词必须共享相同的对齐方式。 |
"keep_blank_chars" |
使用 text 策略时, 空格符" "将视为单词的一部分而不是单词分隔符 |
"text_tolerance", "text_x_tolerance", "text_y_tolerance" |
当 text 策略搜索单词时，期望每个单词中的单个字母之间的距离不超过text_tolerance像素。 |
"intersection_tolerance", "intersection_x_tolerance", "intersection_y_tolerance" |
将边组合到单元格中时，正交边必须在intersection_tolerance 像素范围内才能视为相交。 |
表格提取策略
vertical_strategy(垂直策略) 及 horizontal_strategy(水平策略)均包含以下选项:
| 策略 | 说明 |
|---|---|
"lines" |
使用页面的图形线（包括矩形对象的边）作为潜在表格单元格的边框。 |
"lines_strict" |
使用页面的图形线（而不是矩形对象的边）作为潜在表格单元格的边框。 |
"text" |
对于vertical_strategy（垂直策略）：推导连接页面上单词的左、右或中心的（假想的）行，并将这些行用作潜在表格单元格的边框。对于horizontal_strategy，相同操作，但使用单词的顶部。 |
"explicit" |
仅使用explicit_vertical_lines / explicit_horizontal_lines中明确定义的线。 |
备注
- 在尝试提取表之前裁剪页面通常很有帮助 —
Page.crop(bounding_box) v0.5.0版本的pdfplumber针对表格提取功能进行了彻底的重新设计，并引入了突破性的更改。
提取表单值
有时PDF文件可以包含表单，包含了人们可以填写和保存的输入。虽然表单字段中的值与PDF文件中的其他文本类似，但表单数据的处理方式不同。如果您想彻底了解详细信息，请参阅本手册第671页 specification.
pdfplumber没有用于处理表单数据的接口，但您可以使用pdfplumber对pdfminer的封装组件来访问。
例如，此代码段将检索表单字段名和值，并将它们存储在字典中。您可能需要修改此脚本以处理嵌套字段之类的情况（请参见规范第676页）。
pdf = pdfplumber.open("document_with_form.pdf")
fields = pdf.doc.catalog["AcroForm"].resolve()["Fields"]
form_data = {}
for field in fields:
field_name = field.resolve()["T"]
field_value = field.resolve()["V"]
form_data[field_name] = field_value
用例演示
- 提取加利福尼亚工人调整和再培训通知（WARN）报告中的表格. 演示基本的可视化调试和表提取。
- 提取FBI的国家即时刑事背景调查系统PDF文件中的表格. 演示如何使用可视化调试查找最佳的表提取设置。还演示了
Page.crop(...)(页面裁剪) 及Page.extract_text(...).(文本导出) - 检查和可视化“curve”曲线对象.
- 从圣何塞警察局枪支搜索报告中提取等宽数据,
Page.extract_text(...)示例.
与其他库的比较
其他几个Python库帮助用户从PDF中提取信息。综上所述，pdfplumber通过结合以下功能而区别于其他PDF处理库：
- 可以轻松访问每个PDF对象的详细信息
- 拥有用于提取文本和表格的更高级、可自定义的方法
- 集成了可视化调试
- 其他有用的实用功能，例如通过裁剪框过滤对象
了解pdfplumber无法提供的功能也很有帮助：
- 创建PDF
- 修改PDF
- 文字识别(OCR)
- 完全支持从OCR识别过的PDF提取表格
特性比较
-
pdfminer.sixpdfplumber是基于该库实现的。它主要关注解析PDF、分析PDF布局和对象定位，以及提取文本。但它不提供用于表提取或可视化调试的工具。 -
pymupdf运行速度比pdfminer快。可以生成和修改PDF，但该库需要安装非Python软件（MuPDF）。它无法轻松访问形状对象（矩形、直线等），并且不提供表提取或可视化调试工具。 -
camelot,tabula-py, andpdftables这些库主要关注表格提取。在某些情况下，它们可能更适合提取特定的表格。 -
PyPDF2该库似乎不再维护。