使用webkit渲染引擎和qt将HTML转换为PDF的wkhtmltopdf的Python包装器
项目描述
Python 2和3的wkhtmltopdf实用工具包装器，用于使用Webkit将HTML转换为PDF。
这是ruby PDFKit库的修改版本，因此非常感谢他们！
安装
安装python-pdfkit
$ pip install pdfkit (or pip3 for python3)
安装wkhtmltopdf
Debian/Ubuntu
$ sudo apt-get install wkhtmltopdf
macOS
$ brew install homebrew/cask/wkhtmltopdf
警告！ Debian/Ubuntu仓库中的版本功能有所减少（因为它是在没有wkhtmltopdf QT补丁的情况下编译的），例如添加目录、页眉、页脚、目录等。要使用这些选项，您应从wkhtmltopdf网站安装静态二进制文件，或者您可以使用此脚本。
Windows和其他选项：请检查wkhtmltopdf 主页上的二进制安装程序
用法
对于简单任务
import pdfkit
pdfkit.from_url('http://google.com', 'out.pdf')
pdfkit.from_file('test.html', 'out.pdf')
pdfkit.from_string('Hello!', 'out.pdf')
您可以传递包含多个URL或文件的列表
pdfkit.from_url(['google.com', 'yandex.ru', 'engadget.com'], 'out.pdf') pdfkit.from_file(['file1.html', 'file2.html'], 'out.pdf')
您还可以传递一个打开的文件
with open('file.html') as f:
pdfkit.from_file(f, 'out.pdf')
如果您希望进一步处理生成的PDF，您可以将其读取到变量中
# Without output_path, PDF is returned for assigning to a variable
pdf = pdfkit.from_url('http://google.com')
您可以指定所有wkhtmltopdf 选项。您可以在选项名称中省略“–”。如果选项没有值，请使用None, False或‘’作为字典值。对于可重复的选项（包括allow、cookie、custom-header、post、postfile、run-script、replace），您可以使用列表或元组。对于需要多个值的选项（例如，–custom-header Authorization secret），我们可以使用一个二元组（请参阅下面的示例）。
options = {
'page-size': 'Letter',
'margin-top': '0.75in',
'margin-right': '0.75in',
'margin-bottom': '0.75in',
'margin-left': '0.75in',
'encoding': "UTF-8",
'custom-header': [
('Accept-Encoding', 'gzip')
],
'cookie': [
('cookie-empty-value', '""')
('cookie-name1', 'cookie-value1'),
('cookie-name2', 'cookie-value2'),
],
'no-outline': None
}
pdfkit.from_url('http://google.com', 'out.pdf', options=options)
默认情况下，PDFKit 会启用 wkhtmltopdf 的 quiet 选项，因为大多数情况下不需要输出，这可能会导致内存使用过多和结果损坏。如果您需要获取 wkhtmltopdf 的输出，应在 API 调用中传递 verbose=True。
pdfkit.from_url('google.com', 'out.pdf', verbose=True)
由于 wkhtmltopdf 命令语法，目录 和 封面 选项必须单独指定。如果您需要在目录之前使用封面，请使用 cover_first 选项。
toc = {
'xsl-style-sheet': 'toc.xsl'
}
cover = 'cover.html'
pdfkit.from_file('file.html', options=options, toc=toc, cover=cover)
pdfkit.from_file('file.html', options=options, toc=toc, cover=cover, cover_first=True)
在转换文件或字符串时，您可以通过 css 选项指定外部 CSS 文件。
警告 这是对 此bug 的一个解决方案。您应首先尝试 –user-style-sheet 选项。
# Single CSS file
css = 'example.css'
pdfkit.from_file('file.html', options=options, css=css)
# Multiple CSS files
css = ['example.css', 'example2.css']
pdfkit.from_file('file.html', options=options, css=css)
您还可以通过 HTML 中的元标签传递任何选项。
body = """
<html>
<head>
<meta name="pdfkit-page-size" content="Legal"/>
<meta name="pdfkit-orientation" content="Landscape"/>
</head>
Hello World!
</html>
"""
pdfkit.from_string(body, 'out.pdf') #with --page-size=Legal and --orientation=Landscape
配置
每个 API 调用都包含一个可选的配置参数。这应该是一个 pdfkit.configuration() API 调用的实例。它将配置选项作为初始参数。可用的选项包括：
wkhtmltopdf - wkhtmltopdf 二进制的位置。默认情况下，pdfkit 将尝试使用 which（在 UNIX 类型系统上）或 where（在 Windows 上）定位此位置。
meta_tag_prefix - pdfkit 特定元标签的前缀 - 默认情况下为 pdfkit-
示例 - 当 wkhtmltopdf 不在 $PATH 中时
config = pdfkit.configuration(wkhtmltopdf='/opt/bin/wkhtmltopdf') pdfkit.from_string(html_string, output_file, configuration=config)
您还可以使用 configuration() 调用来检查 $PATH 中是否存在 wkhtmltopdf。
try: config = pdfkit.configuration() pdfkit.from_string(html_string, output_file) except OSError: #not present in PATH
故障排除
调试 PDF 生成问题
如果您在生成正确的 PDF 时遇到困难，首先应检查 wkhtmltopdf 输出以获得一些线索，您可以通过在 API 调用中传递 verbose=True 来获取它。
pdfkit.from_url('http://google.com', 'out.pdf', verbose=True)
如果您在 PDF 中得到奇怪的结果或某些选项看起来被忽略了，您应尝试直接运行 wkhtmltopdf 以查看它是否产生相同的结果。您可以通过直接创建 pdfkit.PDFKit 类并调用其 command() 方法来获取 CLI 命令。
import pdfkit
r = pdfkit.PDFKit('html', 'string', verbose=True)
print(' '.join(r.command()))
# try running wkhtmltopdf to create PDF
output = r.to_pdf()
常见错误
IOError: '未找到wkhtmltopdf可执行文件':
确保您在 $PATH 中有 wkhtmltopdf 或通过自定义配置设置（参见前面的部分）。在 Windows 上 where wkhtmltopdf 或在 Linux 上 which wkhtmltopdf 应返回二进制文件的实际路径。
IOError: '命令失败'
此错误表示 PDFKit 无法处理输入。您可以直接运行错误消息中的命令，并查看导致失败的错误（在某些 wkhtmltopdf 版本中，这可能是由段错误引起的）。
变更日志
- 1.0.0
默认情况下，PDFKit 现在将“quiet”选项传递给 wkhtmltopdf。现在，如果您需要获取输出，您应在 API 调用中传递“verbose=True”。
修复了查找wkhtmltopdf二进制文件的不同问题
更新了wkhtmltopdf的错误处理
修复了选项处理的不同问题
更好地处理 Unicode 输入
从 Travis 切换到 GitHub Actions
更新 README
- 0.6.1
修复了在 python 3+ 中尝试解码 pdf 输出时的回归问题
- 0.6.0
支持可重复的选项
支持某些选项的多个值
修复了需要特定参数顺序的一些边缘情况
一些 Python 3+ 兼容性修复
更新 README
- 0.5.0
允许传递多个 CSS 文件
修复了外部文件编码的问题
在 *nix 系统上缺少 X 服务器时引发错误
修复了与最新wkhtmltopdf版本一起损坏的测试
更新 README
- 0.4.1
更简单的自定义配置设置
更新 README
- 0.4.0
允许传递文件对象
能够将PDF作为字符串返回
允许用户指定配置
API调用现在在成功时返回True
修复错误
- 0.3.0
Python 3支持
- 0.2.4
添加历史记录
更新setup.py
- 0.2.3
修复使用setup.py安装的问题
更新 README
下载文件
下载适用于您的平台的文件。如果您不确定选择哪个，请了解更多关于安装包的信息。
