访问官网
Github
文档
论文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
如果您使用 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 时，请注意以下准则：
- 在实施之前，请先开一个 issue 进行讨论。
- 确保为新逻辑编写测试。
- 确保你的代码通过
flake8 pypandoc/*.py tests.py检查。 - 如果你还不在贡献者列表中，请将自己添加到
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 许可证。
