使用Python和PyPandoc实现批量文件格式的高效转换

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

Pandoc 的主要功能

Pandoc下载与使用

Pandoc 的安装

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

brew install pandoc

Pandoc 的基本用法

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

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

目标文件为PDF

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

使用自定义模板

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

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 可以访问的目录中。

检查 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_text(source_text, to, format=None, extra_args=None, 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)

参数：

示例：

# 将 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

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

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

转换单个文件

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}")

批量转换文件

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)

程序主入口

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)

作者：T0uken