pypandoc

Pypandoc 为 pandoc（一个通用文档转换器）提供了一个轻量级的封装。

安装

Pypandoc 使用 pandoc，因此需要可用的 pandoc 安装。Pypandoc 提供了两个包："pypandoc" 和 "pypandoc_binary"，后者包含了开箱即用的 pandoc。 这两个包完全相同，唯一的区别是一个包含 pandoc，而另一个不包含。

如果已经安装了 pandoc（即 pandoc 在 PATH 中），pypandoc 会使用版本号较高的版本，如果版本号相同，则使用已安装的版本。有关更多信息，请参阅指定 pandoc 二进制文件的位置。

要使用 pandoc 过滤器，您必须在机器上安装相关的过滤器。

通过 pip 安装

如果您想自己安装 pandoc 或使用不受支持的平台，您需要安装 "pypandoc" 并手动安装 pandoc

pip install pypandoc

如果您想要开箱即用的 pandoc，可以使用我们的 pypandoc_binary 包，它与 "pypandoc" 包完全相同，但包含了 pandoc。

pip install pypandoc_binary

Windows 和 Mac OS X 的预构建 wheel

如果您使用 Linux 并有自己的 wheelhouse， 您可以构建一个包含 pandoc 的 wheel，使用 python setup_binary.py download_pandoc; python setup.py bdist_wheel。请注意，这仅适用于 64 位 Intel 系统，因为我们只从官方发布下载。

通过 conda 安装

Pypandoc 包含在 conda-forge 中。conda 包也会 安装 pandoc 包，因此 pandoc 在安装中可用。

通过 conda install -c conda-forge pypandoc 安装。

您还可以通过 conda config --add channels conda-forge 将该频道添加到您的 conda 配置中。这样就可以 直接使用 conda install pypandoc，并通过 conda update pypandoc 进行更新。

安装 pandoc

如果您的系统上还没有 pandoc，或者没有安装包含 pandoc 的 pypandoc_binary 包，您需要自己安装 pandoc。

通过 pypandoc 安装 pandoc

在 Windows、Mac OS X 或 Linux（基于 Intel，64 位）上可以通过 pypandoc 安装：

pip install pypandoc
from pypandoc.pandoc_download import download_pandoc
# 请参阅文档了解如何自定义安装路径
# 但请注意，您需要将其包含在 `PATH` 中
download_pandoc()

默认安装位置已包含在 pandoc 的搜索路径中，因此您 不需要将其添加到 PATH 中。

默认情况下，会安装最新的 pandoc 版本。如果您想指定自己的版本，比如 1.19.1，请使用 download_pandoc(version='1.19.1') 替代。

手动安装 pandoc

也可以通过系统机制手动安装。这种安装机制 使 pandoc 在更多平台上可用：

• Ubuntu/Debian：sudo apt-get install pandoc
• Fedora/Red Hat：sudo yum install pandoc
• Arch：sudo pacman -S pandoc
• Mac OS X 使用 Homebrew：brew install pandoc pandoc-citeproc Caskroom/cask/mactex
• 带有 Haskell 的机器：cabal-install pandoc
• Windows：有一个安装程序可用 这里
• FreeBSD 使用 pkg: pkg install hs-pandoc
• 或参见 Pandoc - 安装 pandoc

请注意，并非所有安装机制都会将 pandoc 放入 PATH 中，因此您需要 自己更改 PATH 或在 PYPANDOC_PANDOC 中设置 pandoc 的完整 PATH。 有关更多信息，请参阅下一节。

指定 pandoc 二进制文件的位置

您可以通过设置环境变量 PYPANDOC_PANDOC 来指向特定的 pandoc 版本， 将其设置为 pandoc 二进制文件的完整 PATH （PYPANDOC_PANDOC=/home/x/whatever/pandoc 或 PYPANDOC_PANDOC=c:\pandoc\pandoc.exe）。 如果设置了此环境变量，这将是唯一搜索 pandoc 的地方。

在某些情况下，例如安装了 pandoc 但具有自己用户的 Web 服务器 无法找到二进制文件，在运行时指定位置会很有用：

import os
os.environ.setdefault('PYPANDOC_PANDOC', '/home/x/whatever/pandoc')

使用方法

使用 pypandoc 有两种基本方式：使用输入文件或使用输入 字符串。

import pypandoc

# 使用输入文件：它会从文件名推断输入格式
output = pypandoc.convert_file('somefile.md', 'rst')

# ...但您可以通过 `format` 参数覆盖格式：
output = pypandoc.convert_file('somefile.txt', 'rst', format='md')

# 或者您也可以直接传递一些字符串。在这种情况下，您需要
# 定义输入格式：
output = pypandoc.convert_text('# some title', 'rst', format='md')
# output == 'some title\r\n==========\r\n\r\n'

convert_text 期望这个字符串是 unicode 或 utf-8 编码的字节。convert_* 将始终 返回一个 unicode 字符串。

也可以直接让 pandoc 将输出写入文件。这是转换为某些输出格式的唯一方法 （例如 odt、docx、epub、epub3、pdf）。在这种情况下，convert_*() 将 返回一个空字符串。

import pypandoc

output = pypandoc.convert_file('somefile.md', 'docx', outputfile="somefile.docx")
assert output == ""

还可以指定多个输入文件给 pandoc，可以是绝对路径、相对路径或文件模式。

import pypandoc

# 转换 chapters/ 子目录中的所有 markdown 文件。
pypandoc.convert_file('chapters/*.md', 'docx', outputfile="somefile.docx")

# 转换 book1 和 book2 目录中的所有 markdown 文件。
pypandoc.convert_file(['book1/*.md', 'book2/*.md'], 'docx', outputfile="somefile.docx")

# 转换另一个驱动器上的前言，以及 chapter 目录中的所有 markdown 文件。
pypandoc.convert_file(['D:/book_front.md', 'book2/*.md'], 'docx', outputfile="somefile.docx")

也支持 pathlib。

import pypandoc
from pathlib import Path

# 单个文件
input = Path('somefile.md')
output = input.with_suffix('.docx')
pypandoc.convert_file(input, 'docx', outputfile=output)

# 转换 chapters/ 子目录中的所有 markdown 文件。
pypandoc.convert_file(Path('chapters').glob('*.md'), 'docx', outputfile="somefile.docx")

# 转换 book1 和 book2 目录中的所有 markdown 文件。
pypandoc.convert_file([*Path('book1').glob('*.md'), *Path('book2').glob('*.md')], 'docx', outputfile="somefile.docx")
# 如果 pathlib globs 在列表内部，必须解包。

除了 format，还可以传递 extra_args。 这使得可以轻松访问各种 pandoc 选项。

output = pypandoc.convert_text(
    '<h1>Primary Heading</h1>',
    'md', format='html',
    extra_args=['--atx-headers'])
# output == '# Primary Heading\r\n'
output = pypandoc.convert_text(
    '# Primary Heading',
    'html', format='md',
    extra_args=['--base-header-level=2'])
# output == '<h2 id="primary-heading">Primary Heading</h2>\r\n'

pypandoc 现在支持轻松添加 pandoc 过滤器。

filters = ['pandoc-citeproc']
pdoc_args = ['--mathjax',
             '--smart']
output = pypandoc.convert_file(filename,
                               to='html5',
                               format='md',
                               extra_args=pdoc_args,
                               filters=filters)

请将任何过滤器作为列表传递，而不是作为字符串。

请参阅 pandoc -h 和 官方文档 以了解更多详情。

处理格式化参数

Pandoc 支持通过 -V 参数进行自定义格式化。要通过 pypandoc 使用它，请使用如下代码：

output = pypandoc.convert_file('demo.md', 'pdf', outputfile='demo.pdf',
  extra_args=['-V', 'geometry:margin=1.5cm'])

注意：将 -V 及其参数在列表中分开很重要，否则 它将无法工作。这个陷阱与 subprocess.Popen 的工作方式有关。

记录消息

Pypandoc 使用 Python 日志库 记录消息。 默认情况下，它会将消息发送到控制台，包括 Pandoc 生成的任何消息。 如果需要，可以通过在调用任何函数之前向 pypandoc 日志记录器添加 处理程序来更改此行为。 例如，要静音所有日志记录，请添加一个空处理程序：

import logging
logging.getLogger('pypandoc').addHandler(logging.NullHandler())

获取 Pandoc 版本

有时检查系统中可用的 pandoc 版本或 pypandoc 使用的特定 pandoc 二进制文件会很有用。为此，pypandoc 提供了以下实用函数。示例：

print(pypandoc.get_pandoc_version())
print(pypandoc.get_pandoc_path())
print(pypandoc.get_pandoc_formats())

相关项目

• pydocverter 是一个名为 Docverter 的服务的客户端，该服务提供 pandoc 作为服务（外加一些额外功能）。
• 查看 pyandoc，这是 Kenneth Reitz 实现的另一个 pandoc 封装器。不过这个项目已经有一段时间没有活跃了。
• 查看 panflute，它提供了类似于 pypandoc 的 convert_text 功能。不过它的重点是编写和运行 pandoc 过滤器。

贡献

欢迎贡献。在开启 PR 时，请注意以下准则：

1. 在实施之前，请先开一个 issue 进行讨论。
2. 确保为新逻辑编写测试。
3. 确保你的代码通过 flake8 pypandoc/*.py tests.py 检查。
4. 如果你还不在贡献者列表中，请将自己添加到 README.md 的贡献者部分。如果已经在列表中，请更新你的贡献内容。

请注意，要通过 citeproc 测试，你需要安装 pandoc-citeproc。如果你安装了预构建的 wheel 或 conda 包，它已经包含在内。

贡献者

• Jessica Tegner - 自 2021 年 7 月 1 日起的新维护者
• Valentin Haenel - 字符串转换修复
• Daniel Sanchez - 输入/输出格式的自动解析
• Thomas G. - Python 3 支持
• Ben Jao Ming - 在 pandoc 缺失时优雅地失败
• Ross Crawford-d'Heureuse - 以 UTF-8 编码输入并添加 Django 示例
• Michael Chow - 以 UTF-8 解码输出
• Janusz Skonieczny - 支持 Windows 换行符并允许指定编码
• gabeos - 修复帮助解析
• Marc Abramowitz - 在 pandoc 缺失时使 setup.py 强制失败，Travis，Dockerfile，PyPI 徽章，Tox，PEP-8，改进文档
• Daniel L. - 在 README 中添加 extra_args 示例
• Amy Guy - Unicode 错误的异常处理
• Florian Eßer - 允许在输出格式中使用 Markdown 扩展
• Philipp Wendler - 允许在输入格式中使用 Markdown 扩展
• Jan Katins - 处理输出到文件，使 Travis 在较新版本的 pandoc 上工作，返回代码检查，get_pandoc_version。帮助修复 Travis 构建，新的 convert_* API。pypandoc 的前任维护者
• Aaron Gonzales - 添加了更好的过滤器处理
• David Lukes - 启用非纯文本文件的输入，并确保测试在失败时正确清理模板文件
• valholl - 正确设置许可信息并在发布版本中包含示例
• Cyrille Rossant - 通过删除 pandoc 格式列表中的星号来修复错误。帮助修复 Travis 构建。
• Paul Osborne - 不要求安装 pandoc 来安装 pypandoc
• Felix Yan - 添加了 Arch Linux 的安装说明
• Kolen Cheung - 实现 _get_pandoc_urls 以安装任意版本以及最新版本的 pandoc。次要：README，Travis，setup.py
• Rebecca Heineman - 添加了在 Windows 中查找 pandoc 的扫描代码
• Andrew Barraford - 下载目标
• Jesse Widner 和 Dominic Thorn - 添加对 lua 过滤器的支持
• Alex Kneisel - 为 convert_file 添加 pathlib.Path 支持
• Juho Vepsäläinen - pypandoc 的创建者和前任维护者
• Connor - 将 Dockerfile 更新为 Python 3.9 镜像并添加 docker compose 文件

许可

Pypandoc 使用 MIT 许可证。有关更多详细信息，请参阅 LICENSE。Pandoc 本身使用 GPL2 许可证。