【Python】PyPandoc：批量文件格式转换

Pandoc 是一个强大的文档转换工具，它可以将各种标记语言（如 Markdown、HTML、LaTeX）转换为不同的格式（如 PDF、DOCX、EPUB 等）。Pandoc 支持多种输入和输出格式，并允许用户添加自定义样式、模板和过滤器。

Pandoc 的主要功能

• 格式转换：将不同的标记语言转换为多种输出格式。最常见的格式包括 Markdown、HTML、LaTeX、PDF、DOCX、EPUB 等。
• 样式和模板支持：Pandoc 允许使用自定义的 CSS 样式或 LaTeX 模板来控制输出的外观。
• 自动生成目录：可以根据文档结构自动生成目录。
• 代码高亮：支持将代码块转换为带有高亮显示的格式，适用于技术文档。

Pandoc下载与使用

Pandoc 的安装

• Windows：
  可以通过 Pandoc 官方网站 下载 Windows 安装包，安装后会自动将 Pandoc 添加到系统路径中。

• Linux：
  在大多数 Linux 发行版中，可以通过包管理器安装 Pandoc：

  sudo apt install pandoc  # 对于基于 Debian/Ubuntu 的系统
  sudo dnf install pandoc  # 对于基于 Fedora 的系统
  

• macOS：
  使用 Homebrew 安装：

  brew install pandoc
  

Pandoc 的基本用法

Pandoc 的使用非常灵活，主要通过命令行进行操作。其基本命令如下：

pandoc [输入文件] -o [输出文件] [选项]

• -o [filename]：指定输出文件。
• --toc：生成目录（table of contents）。
• --highlight-style [style]：指定代码块的高亮风格，style 可以是 pygments、kate 等。
• --standalone 或 -s：生成独立文件，比如在 HTML 中，包含完整的 和 标签。

目标文件为PDF

使用 Pandoc 将文件转换为 PDF 时，特别是涉及中文支持和复杂排版的情况，需要进行一些特殊的准备工作。以下是具体步骤：

• Pandoc 本身不能直接输出 PDF，它依赖 LaTeX 来生成 PDF 文件。因此，需要安装 Pandoc 和 LaTeX。

• 推荐安装一个完整的 LaTeX 发行版，例如：TeX Live
• 【操作与配置】基于Tex Live的VS Code编写LaTex-CSDN博客

使用自定义模板

Pandoc 允许用户通过模板定义生成文件的格式和样式。以 LaTeX PDF 为例，用户可以自定义 LaTeX 模板来控制输出 PDF 的样式。

使用 LaTeX 模板

1. 创建自定义模板 template.tex，并在其中定义格式。
2. 使用 Pandoc 时指定模板：

   pandoc example.md -o example.pdf --template=template.tex
   

Pandoc 过滤器

Pandoc 提供了扩展功能，通过过滤器可以对文档进行进一步处理，比如添加水印或修改特定格式。

使用 Python 过滤器

可以编写 Pandoc 过滤器来修改 AST（抽象语法树）。比如你想过滤掉所有二级标题，可以用 Python 来实现过滤器。

pandoc example.md --filter ./filter.py -o example.pdf

Pandoc 的输入输出格式

Pandoc 支持的输入和输出格式非常多，其中包括：

• 输入格式：Markdown (.md)、DOCX (.docx)、LaTeX (.tex)、HTML (.html)、reStructuredText (.rst)、EPUB (.epub)、ODT (.odt)、MediaWiki (.wiki)、Org-mode (.org)、Textile (.textile)等
• 输出格式：PDF (.pdf)、DOCX (.docx)、HTML (.html)、LaTeX (.tex)、EPUB (.epub)、Markdown (.md)、ODT (.odt)、RTF (.rtf)、PowerPoint (.pptx)、Plain text (.txt)等

扩展 Markdown

Pandoc 增强了 Markdown，支持表格、脚注、目录生成等。使用时可以指定不同的 Markdown 扩展：

pandoc example.md -o example.html --from markdown+footnotes+table_captions

Pypandoc的使用

Pypandoc 是 Pandoc 的 Python 接口，允许在 Python 程序中直接调用 Pandoc 进行文档格式转换。Pypandoc 提供了一个简化的 API，使得用户可以在 Python 中方便地使用 Pandoc 的所有功能，而不必通过系统命令行进行调用。

安装 Pypandoc

Pypandoc 可以通过 pip 安装：

pip install pypandoc

Pypandoc 只是 Pandoc 的 Python 封装，因此你仍然需要安装 Pandoc。你可以按照 Pandoc 官方网站 提供的说明进行安装。

自动下载 Pandoc

如果 Pandoc 未安装，Pypandoc 提供了一个函数 pypandoc.download_pandoc()，可以自动下载并安装 Pandoc。这在没有管理员权限或者需要快速部署的场景下特别有用。

import pypandoc

# 自动下载 Pandoc 并安装
pypandoc.download_pandoc()

此方法会下载适用于当前操作系统的 Pandoc 二进制文件，并将其存放在 Pypandoc 可以访问的目录中。

• pypandoc.download_pandoc() 默认下载的 Pandoc 二进制文件是从网络上获取的。因此，在离线环境下无法使用此功能。
• 自动安装的 Pandoc 仅限于 Pypandoc 使用，并不会影响系统的其他程序。

检查 Pandoc 安装

在使用 Pypandoc 时，可以先检查 Pandoc 是否已安装：

import pypandoc

try:
    # 检查 Pandoc 是否可用
    pypandoc.get_pandoc_version()
except OSError:
    # 如果未安装，则自动下载 Pandoc
    pypandoc.download_pandoc()

Pypandoc 的基本用法与详细参数

Pypandoc 是 Pandoc 的 Python 接口，提供了两种主要的转换方式：

• pypandoc.convert_text()：用于转换字符串内容。

• pypandoc.convert_file()：用于转换文件。

pypandoc.convert_text()

用于将一个字符串的文本从一种格式转换为另一种格式。

语法：

pypandoc.convert_text(source_text, to, format=None, extra_args=None, encoding='utf-8')

参数：

• source_text：要转换的文本内容（字符串）。
• to：目标格式，例如 'html'、'pdf'、'docx' 等。
• format：源文本格式。例如 'md'（Markdown）、'rst'（reStructuredText）、'latex'（LaTeX）等。如果不指定，默认会尝试根据内容自动检测。
• extra_args：可以传递给 Pandoc 的额外命令行参数。例如，['--toc'] 可以生成目录，['--highlight-style=pygments'] 可以设置代码高亮风格。
• encoding：文本编码，默认为 'utf-8'。

示例：

import pypandoc

# 将 Markdown 字符串转换为 HTML
output = pypandoc.convert_text('# Hello World', 'html', format='md')
print(output)

pypandoc.convert_file()

用于将一个文件从一种格式转换为另一种格式。

语法：

pypandoc.convert_file(source_file, to, format=None, outputfile=None, extra_args=None, filters=None)

参数：

• source_file：要转换的源文件路径，可以是字符串或文件路径列表。
• to：目标格式，例如 'pdf'、'html'、'docx' 等。
• format：源文件格式。例如 'md'（Markdown）、'rst'（reStructuredText）、'latex'（LaTeX）等。如果不指定，默认根据文件扩展名检测。
• outputfile：输出文件的路径。如果指定该参数，转换结果会直接写入文件，而不是返回字符串。若未指定，将返回转换结果的字符串内容。
• extra_args：传递给 Pandoc 的额外命令行参数（列表形式）。
• filters：Pandoc 过滤器的路径或名称，用于对文档进一步处理。可选参数。

示例：

# 将 Markdown 文件转换为 DOCX
output = pypandoc.convert_file('example.md', 'docx', outputfile='example.docx')

# 将 LaTeX 文件转换为 PDF，使用特定的 LaTeX 引擎
output = pypandoc.convert_file('example.tex', 'pdf', extra_args=['--pdf-engine=xelatex'])

错误处理

Pypandoc 会抛出 RuntimeError，如果 Pandoc 命令执行失败，用户可以捕获并处理错误：

try:
    output = pypandoc.convert_file('nonexistent.md', 'pdf')
except RuntimeError as e:
    print(f"转换失败：{e}")

批量文档转换源码剖析

这段代码的主要目的是将指定目录中的特定类型文件（例如 .md 文件）批量转换为另一种格式（例如 pdf 或 docx），并且保留原有的目录结构。下面是逐段讲解：

导入必要的库

import os
import pypandoc

• os: 用于处理文件和目录的操作，比如遍历文件夹，检查目录是否存在，创建目录等。
• pypandoc: 这是 Pandoc 的 Python 包装器，用于将各种格式的文件进行转换。

获取指定扩展名的文件列表

def get_files(source_dir, source_ext):
    """
    遍历源目录，获取符合指定扩展名的文件列表，并返回源文件路径。

    参数:
    source_dir (str): 源文件目录路径。
    source_ext (str): 要查找的源文件扩展名（如 '.md'）。

    返回:
    list: 一个包含源文件路径的列表。
    """
    file_pairs = []

    # 遍历源目录及其子目录中的所有文件
    for src_root, _, files in os.walk(source_dir):
        for filename in files:
            # 检查文件扩展名是否符合源文件要求
            if filename.endswith(source_ext):
                # 构建源文件路径
                src_path = os.path.join(src_root, filename)
                file_pairs.append(src_path)
    
    return file_pairs

• get_files 函数用于遍历指定的 source_dir 目录，寻找符合特定扩展名（source_ext）的文件，并返回一个包含这些文件路径的列表。
• 使用了 os.walk() 遍历目录及其子目录，查找特定扩展名的文件。

转换单个文件

def convert_file(src_path, dst_path, target_format):
    """
    将单个源文件转换为指定格式的目标文件。
    """
    try:
        if target_format == "pdf":
            extra_args = [
                "--pdf-engine=xelatex",
                "--variable",
                'mainfont="SimSun"',  # 使用 SimSun 字体，或其他已安装字体
                "--variable",
                'CJKmainfont="SimSun"',  # 设置 CJK 字体
                "--variable",
                'fontenc="T1"',  # 字体编码
                "--variable",
                "geometry:margin=1in",  # 设置边距
            ]

            pypandoc.convert_file(
                src_path, target_format, outputfile=dst_path, extra_args=extra_args
            )
        else:
            pypandoc.convert_file(src_path, target_format, outputfile=dst_path)

        print(f"已成功转换 {src_path} 到 {dst_path}.")
    except Exception as e:
        print(f"无法转换 {src_path}: {e}")

• 该函数用于将单个文件从 src_path 转换为目标格式 target_format，并将输出保存到 dst_path。
• 如果目标格式是 pdf，使用 xelatex 引擎，并添加支持中文字体和适当的 LaTeX 参数。
• 对于其他格式，直接使用 pypandoc 进行转换。
• 使用 try-except 块捕获异常，避免程序崩溃并输出错误信息。

批量转换文件

def convert_files(source_dir, output_dir, source_ext, target_format):
    """
    将源目录中的指定类型文件批量转换为目标格式，并保持原目录结构。

    参数:
    source_dir (str): 源文件目录路径。
    output_dir (str): 转换后文件的输出目录路径。
    source_ext (str): 要转换的源文件的扩展名（例如 '.md'）。
    target_format (str): 目标文件格式（例如 'pdf', 'docx' 等）。
    """
    # 确保输出目录存在
    if not os.path.exists(output_dir):
        os.makedirs(output_dir)

    # 获取源文件及其目标路径的列表
    files_to_convert = get_files(source_dir, source_ext)
    
    for src_path in files_to_convert:
        # 构建目标文件名和路径
        rel_path = os.path.relpath(src_path, source_dir)
        target_name = rel_path.rsplit('.', 1)[0] + '.' + target_format
        dst_path = os.path.join(output_dir, target_name)

        # 确保目标目录结构存在
        dst_root = os.path.dirname(dst_path)
        if not os.path.exists(dst_root):
            os.makedirs(dst_root)
        
        # 转换单个文件
        convert_file(src_path, dst_path, target_format)

• 该函数批量将 source_dir 目录中的指定类型文件转换为目标格式 target_format。
• 它确保目标输出目录存在，并保持原始文件目录结构。
• 调用 convert_file 函数来处理每个文件的转换。

程序主入口

if __name__ == "__main__":
    # 自动下载并安装 Pandoc，避免手动安装
    try:
        pypandoc.get_pandoc_version()
    except OSError:
        pypandoc.download_pandoc()

    # 示例路径，用户需根据实际情况修改
    source_dir = 'path/to/your/source/files'  # 源文件目录
    output_dir = 'path/to/your/output/files'  # 输出文件目录
    source_ext = '.md'  # 源文件扩展名
    target_format = 'pdf'  # 目标格式（例如 'pdf', 'docx'）

    # 调用文件转换函数
    convert_files(source_dir, output_dir, source_ext, target_format)

• 这是程序的主入口，用于自动下载 Pandoc（如果还没有安装）并调用 convert_files 函数进行批量文件转换。
• 需要用户根据实际路径修改 source_dir 和 output_dir，以及指定源文件扩展名和目标文件格式。