pdfrw 0.4

2.1 所有示例

示例目录中有一些使用库的脚本。请注意，如果这些示例与您的 PDF 不兼容，您应该尝试首先使用 pdftk 解压和/或解密它们。

• 4up.py 将缩小页面并将 4 个页面放置在每个输出页面上。

• alter.py 展示了一个修改元数据但不改变 PDF 结构的示例。

• booklet.py 展示了一个适合打印和折叠（例如，在大小为对开纸的纸张上）的 2-up 输出示例。

• cat.py 展示了一个将多个 PDF 合并在一起的示例。

• extract.py 将从现有 PDF 中提取图像和表单 XObjects（嵌入的页面），以便使它们更容易在新的 PDF 中使用和引用（例如，使用 reportlab 或 rst2pdf）。

• poster.py 将PDF的大小增加，使其可以打印成海报。

• print_two.py 允许通过打印后切割8.5 X 11英寸的纸张来创建8.5 X 5.5英寸的小册子。

• rotate.py 旋转PDF中的所有或所选页面。

• subset.py 从原始PDF中创建只包含部分页面的新PDF。

• unspread.py 从2合1PDF中分离出页面。

• watermark.py 在PDF的所有页面上添加水印PDF图像。

• rl1/4up.py 另一个4合1示例，使用reportlab画布进行输出。

• rl1/booklet.py 另一个小册子示例，使用reportlab画布进行输出。

• rl1/subset.py 另一个子集示例，使用reportlab画布进行输出。

• rl1/platypus_pdf_template.py 另一个水印示例，使用reportlab画布和生成的输出文档。由用户asannes贡献。

• rl2 解析图形的实验代码。需要改进。

• subset_booklets.py 展示了以更专业和实用的方式创建完整可打印PDF版本的一个示例（请参阅 http://www.wikihow.com/Bind-a-Book ）

2.2 精选示例说明

3.1 核心库

pdfrw 库部分的哲学是提供直观的函数来读取、操作和写入 PDF 文件。抽象层之间应该有最小的泄漏，尽管完成有用的工作使得“纯”功能分离变得困难。

库支持的一个关键概念是使用 Form XObjects，它允许轻松地将一个 PDF 的一部分嵌入到另一个 PDF 中。

通常对库的核心支持进行仔细和深思熟虑的添加，以免使其过于复杂，充斥着太多的特殊案例。

有很多格式错误的 PDF 文件四处流传；在某些情况下，对这些文件的支持被添加进去。这个决定通常基于 acroread 和 okular 如何处理 PDF 文件；如果它们可以正确显示它们，那么 pdfrw 最终也应该能够，如果这不太困难或成本高昂的话。

欢迎贡献力量；一位用户贡献了一些解压缩过滤器和处理 PDF 1.5 流对象的能力。显然有用的其他功能包括额外的解压缩过滤器、处理受密码保护的 PDF 的能力以及输出线性 PDF 的能力。

3.2 示例

示例的哲学是提供小型、易于理解的示例，以展示 pdfrw 功能。

4.1 简介

通常，PDF 文件在概念上与 Python 非常吻合。需要考虑的主要对象是

• 字符串。大多数事物都是字符串。这些也通常自然地分解为

• 标记列表。标记可以组合起来创建更高层次的对象，例如

• 数组、

• 字典和

• 内容流（它可以是更多标记的流）

4.2 困难之处

将 PDF 文件映射到 Python 的主要困难之一是 PDF 文件中的“间接对象”概念。间接对象提供了允许单个数据块从多个包含对象引用的效率，但更重要的是，间接对象提供了一种在将任意数据结构映射到文件时解决循环引用的鸡生蛋问题的方式。为了平铺循环引用，间接对象是 引用 而不是 直接包含 在另一个对象中。PDF 文件有一个全局机制来定位间接对象，并且它们都有两个引用编号（一个引用编号和一个“版本”编号，以防你想追加到 PDF 文件而不是重写整个文件）。

pdfrw 自动处理读取 PDF 文件时的间接引用。当 pdfrw 遇到一个间接 PDF 文件对象时，它创建的相应 Python 对象将有一个值为 True 的 'indirect' 属性。当写入 PDF 文件时，如果你创建了任意数据，你只需确保在每个循环中至少有一个对象上的 'indirect' 属性评估为 True，以断开循环引用。

另一个不与常规 Python 完全对应的 PDF 文件概念是“流”。流是与无格式数据块相关联的字典。pdfrw 通过在子类化的字典上放置特殊属性来处理流。

4.3 使用模型

pdfrw的用法模型将大多数对象视为字符串（在写入文件时，它会使用它们的字符串表示形式）。两个主要例外是PdfArray对象和PdfDict对象。

PdfArray是列表的子类，具有两个特殊功能。首先，一个“间接”属性允许PdfArray以间接PDF对象的形式写入。其次，pdfrw按需读取文件，因此PdfArray会根据需要了解并解析对其他间接对象的引用。

PdfDict是具有间接属性和按需引用解析功能的字典的子类。子类化的IndirectPdfDict会将间接属性自动设置为True）。

但是，PdfDict还有一个可选的关联流。流对象默认为None，但如果您将流分配给字典，它将自动设置字典的PDF /Length属性。

最后，由于PdfDict实例是通过PdfName对象索引的（这些对象始终以“/”开头），并且大多数（所有？）标准Adobe PdfName对象都使用类似“/CamelCase”的格式命名，因此允许通过对象属性访问以及对象索引访问来访问字典元素是有意义的。因此，通常通过属性访问来使用PdfDict对象，尽管可以通过字典索引查找来访问非标准名称（尽管仍然以斜杠开头）。

>>> from pdfrw import PdfReader
>>> x = PdfReader('source.pdf')
>>> x.keys()
['/Info', '/Size', '/Root']
>>> x.Info
{'/Producer': '(cairo 1.8.6 (http://cairographics.org))',
 '/Creator': '(cairo 1.8.6 (http://cairographics.org))'}
>>> x.Root.keys()
['/Type', '/Pages']

>>> len(x.pages)
1
>>> x.pages[0]
{'/Parent': {'/Kids': [{...}], '/Type': '/Pages', '/Count': '1'},
 '/Contents': {'/Length': '11260', '/Filter': None},
 '/Resources': ... (Lots more stuff snipped)
>>> x.pages[0].Contents
{'/Length': '11260', '/Filter': None}
>>> x.pages[0].Contents.stream
'q\n1 1 1 rg /a0 gs\n0 0 0 RG 0.657436
  w\n0 J\n0 j\n[] 0.0 d\n4 M q' ... (Lots more stuff snipped)

>>> from pdfrw import PdfWriter
>>> y = PdfWriter()
>>> y.addpage(x.pages[0])
>>> y.write('result.pdf')

5.1 简介

pdfrw目前由19个模块组成，分为一个主包和一个子包。

__init__.py 模块执行了从子模块导入一些主要属性的常规操作，而 errors.py 模块支持日志记录和异常生成。

5.2 PDF 对象模型支持

objects 子包包含每个PDF文件中存在的基本对象类型的内部表示的模块，该子包中的 objects/__init__.py 模块只是将它们收集起来，使它们对主 pdfrw 包可用。

所有PDF对象类共有的一项特性是包含一个‘indirect’属性。如果‘indirect’存在并评估为True，则在对象写入时，它将作为间接对象写入。也就是说，它在PDF文件中是可寻址的，并且可以被任意数量的容器对象引用。这种间接对象功能通过允许对象（如字体）从多个页面引用来节省PDF文件的空间，并且还允许PDF文件包含内部循环引用。后者在例如每个页面对象在其字典中有一个“父”对象时被使用。

PdfName.Rotate == PdfName('Rotate') == PdfObject('/Rotate')

mydict.private.foo = 1

foo = mydict.foo

mediabox = mypage.inheritable.MediaBox

5.3 文件读取、标记化和解析

pdfreader.py 包含 PdfReader 类，它可以读取 PDF 文件（或传递文件对象或已读取的字符串）并解析它。它使用 tokens.py 中的 PdfTokens 类进行底层标记。

PdfReader 类通常不会解析到容器中（例如，在内容流内部）。在 examples/rl2 子目录中有实现该功能的原型，但这很慢，且不完善，对大多数应用程序也没有什么用。

PdfReader 类的实例是 PdfDict 的实例——确切地说是 PDF 文件的尾部字典。它将具有名为 'pages' 的私有属性，这是一个包含文件中所有页面的列表。

在实例化 PdfReader 对象时，有选项可供解压缩文件中的所有对象。pdfrw 目前没有很多解压缩选项，所以这并不那么有用，除非是针对压缩对象流的具体情况。

此外，目前还没有解密选项。如果您有加密或高度压缩的 PDF 文件，您可能会发现使用 pdftk 等其他程序来处理这些文件可以使它们可以被 pdfrw 读取。

通常，对象是按需从文件中读取的，但压缩对象流目前不是这样——当实例化 PdfReader 时，所有这些都会被解压缩并读取。

5.4 文件输出

pdfwriter.py 包含 PdfWriter 类，它可以创建和输出 PDF 文件。

在创建和使用此类时有一些可用选项。

在最简单的情况下，实例化一个 PdfWriter，然后从一个或多个源文件（或以编程方式创建）向其中添加页面，然后调用 write 方法将结果输出到文件。

如果您有一个源 PDF 并且不想对其结构造成太大破坏，则可以直接将它的尾部传递给 PdfWriter，而不是让 PdfWriter 为您构造一个。在 examples 目录中有一个这样的例子（alter.py）。

5.5 高级特性

buildxobj.py 包含从页面或页面上的矩形构建表单 XObjects 的函数。这些可以在新 PDF 中重复使用，基本上就像它们是图像一样。

buildxobj会仔细缓存任何使用过的页面，以确保它们只出现在输出中一次。

toreportlab.py提供了makerl函数，该函数可以将pdfrw对象转换为可以与reportlab一起使用的格式。它通常与buildxobj结合使用，以便在使用reportlab时能够重用现有PDF的部分。

pagemerge.py建立在buildxobj的基础之上。它包含用于使用其他页面中的一个或多个矩形创建新页面（或覆盖现有页面）的类。有一些示例展示了它的使用，例如水印、缩放、4-up输出、将每页分成两页等。

findobjs.py包含可以找到PDF文件中特定类型对象的代码。extract.py示例使用此模块创建一个新的PDF，将源PDF中的每个图像和Form XObject放置在其自己的页面上，例如，以便与其他示例或与reportlab一起轻松重用。

5.6 其他

compress.py和uncompress.py包含压缩和解压缩函数。目前支持很少的过滤器，因此如果您需要解压缩（或，就这一点而言，解密）PDF文件的能力，那么像pdftk这样的外部工具可能是个好选择。

py23_diffs.py包含帮助管理Python 2和Python 3之间差异的代码。

7.1 纯 Python

• reportlab

  如果您想编程生成任意PDF，那么reportlab是必须的软件。

• pyPdf

  在某些方面，pyPdf功能非常全面。它可以进行解压缩和解密，并且似乎对至少某些类型的PDF文件中的项目了解很多。相比之下，pdfrw对特定PDF文件功能（如元数据）的了解较少，但专注于尝试为将PDF文件容器语法映射到Python提供一个更Pythonic的API，并且（据我所知）具有更简单、更好的PDF文件解析器。pdfrw的Form XObject功能意味着在许多情况下，它实际上不需要解压缩对象——它们可以保持压缩状态。

• pdftools

  pdftools感觉很大，我在试图弄清楚它如何组合在一起时睡着了，但许多人已经用它做了有用的事情。

• pagecatcher

  我的理解是，当我在构建pdfrw时，pagecatcher会做我想做的任何事情。但我预算为零，所以我从未有幸体验过pagecatcher。然而，我确实使用并喜欢reportlab（开源，来自制作pagecatcher的人），因此我确信pagecatcher很棒，文档更完善，功能更全面，比pdfrw更好。

• pdfminer

  这看起来像是一个有用、积极开发的程序。它相当大，因为它的目标是积极理解完整的PDF文档。从网站

  “PDFMiner 是一套程序，用于提取和分析 PDF 文档中的文本数据。与其它 PDF 相关工具不同，它允许获取页面中文本的确切位置，以及其他额外信息，例如字体信息或标尺线。它包含一个 PDF 转换器，可以将 PDF 文件转换为其他文本格式（如 HTML）。它具有可扩展的 PDF 解析器，可用于其他目的，而不仅仅是文本分析。”

7.2 非纯 Python 库

• pyPoppler 可以读取 PDF 文件。

• pycairo 可以写入 PDF 文件。

• PyMuPDF 高性能渲染 PDF、(Open)XPS、CBZ 和 EPUB

7.3 其他工具

• pdftk 是一款优秀的命令行工具，用于基本的 PDF 操作。它与 pdfrw 配合得非常好，支持许多 pdfrw 无法执行的操作，例如解密和解压缩。

• MuPDF 是一个免费的、高性能的 PDF、(Open)XPS、CBZ 和 EPUB 渲染库，还附带一些命令行工具。其中之一，mutool，与 pdftk 具有较大重叠——但它快 10 倍。