当前位置： 首页 > news >正文

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

news 2025/6/21 14:15:05

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 中，包含完整的 <html> 和 <body> 标签。

目标文件为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 pypandoctry:# 检查 Pandoc 是否可用pypandoc.get_pandoc_version()
except OSError:# 如果未安装，则自动下载 Pandocpypandoc.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_formatdst_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，以及指定源文件扩展名和目标文件格式。

http://www.mrgr.cn/news/22739.html

相关文章：

  • 9月9日听IoT讲座
  • stack,queue的模拟实现,deque的模拟实现和小知识点的杂糅
  • PID控制算法（二）
  • 【脊线图】：附Origin详细画图流程
  • 优化销售流程，领先市场趋势！企元数智赠送小程序合规分销系统！
  • 《语文新读写》是知网收录吗？语文新读写编辑部查询
  • How to handle the response OpenAI Text-To-Speech API in Node.js?
  • 基于单片机的盲人智能水杯系统（论文+源码）
  • 声音克隆工具CosyVoice
  • 极狐GiLab 17.3 重点功能解读 升级指南
  • 基于微信小程序+Java+SSM+Vue+MySQL的考研论坛
  • ESP32 UDP 05
  • SpringBoot集成MyBatis-Plus
  • 电商数据API接口|唯品会商品详情数据的接入说明【附测试实例】
  • 并网光伏发电对电网电能质量的影响和治理方案
  • 解决：web of science文献检索点不动，只能用作者检索的情况
  • 还不会数据恢复？试试这4款软件吧！
  • 一、java基础面试题
  • 变量与命名
  • 盘点10款顶级加密软件，让企业数据安全得到保障！