Python之richtypo包语法、参数和实际应用案例

Python richtypo 完整使用手册

一、包基础概述

1. 核心功能

richtypo是专门用于西文印刷标点规范化、排版美化的轻量级Python库，解决英文/多语言文本排版中引号、破折号、空格、缩写、符号、连字符等不规范问题，实现出版级标准排版校正。
核心能力：

1. 智能替换直引号" '为弯引号（印刷引号）“ ” ‘ ’，区分单双引、嵌套引号；
2. 修正短横-、减号、en破折号–、em破折号—，区分区间、停顿、解释语义；
3. 清除冗余空格、单词前后多余空白、标点前后非法空格；
4. 规范化省略号...→…，小数、千位分隔空格处理；
5. 语言本地化排版规则：英语、德语、法语、俄语、西班牙语等多国标点规则切换；
6. 数字、单位、缩写、版权符号、度符号、角标自动替换；
7. 可自定义过滤规则、禁用指定修正项、自定义替换映射；
8. 支持纯文本、Markdown、HTML片段兼容处理，不破坏基础标记。

2. 适用场景

电子书排版、网站文章格式化、爬虫文本清洗、论文预处理、文案批量美化、多语言内容标准化。

3. 安装方式

标准pip安装

pipinstallrichtypo

指定版本安装

pipinstallrichtypo==3.0.0

国内镜像加速

pipinstallrichtypo-ihttps://pypi.tuna.tsinghua.edu.cn/simple

源码安装（最新开发版）

gitclone https://github.com/richtypo/richtypo-py.gitcdrichtypo-py pipinstall.

依赖：仅Python标准库，无额外第三方依赖，兼容 Python3.7–3.12。

二、核心语法、类与参数详解

1. 核心入口类RichTypo

所有排版规则由RichTypo实例控制，基础构造语法：

fromrichtypoimportRichTypo typo=RichTypo(lang="en",rules=None,disable_rules=[],enable_rules=[],html=False)result=typo.process(raw_text)

2. 构造函数参数完整说明

3. 内置规则ID（可启用/禁用）

1. quotes：弯引号转换
2. dashes：破折号/短横标准化
3. ellipsis：省略号替换
4. spaces：冗余空格清理
5. numbers：数字、单位、千分位空格
6. symbols：版权©、度数°、乘号×、角标
7. hyphens：复合词连字符修正
8. abbreviations：缩写点规范化（Mr. / U.S.A.）

4. 实例方法

1. .process(text: str) -> str
   主处理函数，输入原始文本，返回排版美化后字符串。
2. .get_active_rules() -> list
   查询当前实例启用的所有规则ID，用于调试。
3. .add_custom_rule(pattern: str, replacement: str, priority=50)
   添加自定义正则替换规则，priority数值越小越先执行。
4. .reset()
   重置实例配置，恢复语言默认规则。

5. 极简单行语法（快速工具函数）

包内置快捷函数，无需创建实例：

fromrichtypoimporttypograph# 单行处理英文文本clean_text=typograph(raw_text,lang="en",html=False)

三、8个完整可运行实际应用案例

案例1：英文普通文章基础标点美化（最常用）

需求：将爬虫获取的直引号、省略号、多余空格文本标准化出版英文格式

fromrichtypoimporttypograph raw='He said: "It\'s just... a 9 - 5 job -- boring!" "Don\'t worry", she replied.'# 英文默认规则处理formatted=typograph(raw,lang="en")print("原始：",raw)print("美化：",formatted)

输出效果：直引号变弯引号、...→…、区间9 - 5→9–5、双横杠--→em破折号—

案例2：德语文本本地化排版（特殊引号« »）

德语使用低引号+高引号，规则与英文完全不同

fromrichtypoimportRichTypo typo_de=RichTypo(lang="de")text_de='Er sagte: "Ich habe gestern 10 - 20 Bücher gekauft..."'res=typo_de.process(text_de)print(res)# 输出带德语印刷引号、德语空格分隔数字区间

案例3：HTML网页文本排版（不破坏标签）

场景：清洗网页正文，避免<p> <b>标签内部符号被错误修改

fromrichtypoimporttypograph html_raw='<p>"Hello world" -- price: 100 ...</p><b>9 - 19 USD</b>'# html=True开启标签保护clean_html=typograph(html_raw,lang="en",html=True)print(clean_html)# <p>“Hello world” — price: 100 …</p><b>9–19 USD</b>

案例4：Markdown文档处理（跳过代码块）

场景：批量格式化Markdown文章，不修改```代码块、行内代码

fromrichtypoimportRichTypo md_text='''# ArticleThe valueis"40 - 60"...`print("raw text -- test")` ```python s="raw quote -- 1-10"

‘’’
typo_md = RichTypo(lang=“en”, markdown=True)
result = typo_md.process(md_text)
print(result)

仅正文修正，代码块内引号、破折号保持原样

### 案例5：禁用指定规则，仅清理空格和省略号 需求：不想修改引号，只清除多余空格、替换三点省略号 ```python from richtypo import RichTypo raw = ' "Test" ... 5 - 10 -- ' # 禁用引号、破折号规则，只启用spaces、ellipsis typo = RichTypo(lang="en", disable_rules=["quotes", "dashes"]) out = typo.process(raw) print(out) # 输出： "Test" … 5 - 10 --

案例6：自定义替换规则（添加版权、注册商标符号）

内置规则无商标替换，通过add_custom_rule扩展自定义排版逻辑

fromrichtypoimportRichTypoimportre typo=RichTypo(lang="en")# 自定义正则：(R) → ® 、(C) → ©typo.add_custom_rule(r"\(R\)","®",priority=10)typo.add_custom_rule(r"\(C\)","©",priority=10)text='ProductName(R), All Right Reserved (C) 2026'res=typo.process(text)print(res)# ProductName®, All Right Reserved © 2026

案例7：批量读取TXT文件夹，批量美化输出

文件批量处理场景：小说、文案批量标准化

importosfromrichtypoimporttypograph input_dir="./raw_text/"output_dir="./formatted_text/"os.makedirs(output_dir,exist_ok=True)# 遍历所有txt文件forfilenameinos.listdir(input_dir):iffilename.endswith(".txt"):file_path=os.path.join(input_dir,filename)withopen(file_path,"r",encoding="utf-8")asf:content=f.read()# 排版处理fixed=typograph(content,lang="en")# 写入新文件out_path=os.path.join(output_dir,filename)withopen(out_path,"w",encoding="utf-8")asf:f.write(fixed)print("批量格式化完成")

案例8：多语言混合文本分段处理（英文+法语切换）

一段文本包含英法双语，分段使用不同语言规则分别校正

fromrichtypoimportRichTypo typo_en=RichTypo(lang="en")typo_fr=RichTypo(lang="fr")para_en='He shouted: "The deadline is 3 - 7 days..."'para_fr='Il dit: "le prix est 10 - 50 euros !"'fix_en=typo_en.process(para_en)fix_fr=typo_fr.process(para_fr)full=f"English:\n{fix_en}\nFrench:\n{fix_fr}"print(full)

四、常见错误、报错原因与解决方案

1. ModuleNotFoundError: No module named ‘richtypo’

• 原因：未执行pip安装、安装环境不对（多Python版本/虚拟环境隔离）
• 解决：

  pip3installrichtypo# 或指定当前解释器python-mpipinstallrichtypo

2. UnicodeEncodeError: ‘gbk’ codec can’t encode character ‘“’

• 原因：Windows默认文件编码GBK，弯引号、特殊符号无法写入
• 解决：读写文件强制指定encoding="utf-8"

  withopen("out.txt","w",encoding="utf-8")asf:f.write(result)

3. HTML标签内部文本被错误修改

• 原因：未开启html=True参数，库默认纯文本模式
• 解决：创建实例或调用typograph时添加html=True

4. Markdown代码块里的引号被转换

• 原因：未开启markdown=True，无法识别```、`行内代码标记
• 解决：RichTypo(markdown=True)

5. 自定义规则不生效

• 常见原因：
  1. 正则表达式未转义，反斜杠写成单\；
  2. priority数值过大，内置规则提前覆盖自定义替换；
• 修复示例：使用原始字符串r"pattern"，调低priority

  typo.add_custom_rule(r"\(TM\)","™",priority=5)

6. 语言参数传错导致排版错乱（lang="cn"不存在）

• 报错/异常表现：无报错，但标点完全不符合预期
• 支持语言仅：en/de/fr/ru/es，无中文专用规则；中文排版需自行加自定义规则

7. 处理超大文本卡顿

• 原因：一次性传入几万行长文本，正则全局匹配耗时
• 优化方案：按段落分割逐段处理，分段合并结果

8. 嵌套引号转换逻辑混乱（三重引号错误）

• 原因：原文引号嵌套格式不规范，库正则无法100%识别极端嵌套
• 解决：预处理先清洗残缺引号，或临时disable_rules=["quotes"]手动处理

五、使用注意事项与最佳实践

1. 编码强制统一

所有输入输出文件必须使用UTF-8，Windows环境极易出现特殊符号乱码。

2. 语言规则选择要点

• 英文写作：lang="en"；
• 德语书籍/网页：lang="de"；
• 法语文案：lang="fr"；
• 混合多语言：分段分别处理，不要混用一套语言规则。

3. 代码、代码块处理规范

处理Markdown/HTML代码片段时，必须开启对应兼容开关，否则会破坏代码语法引号。

4. 禁用规则合理搭配

• 代码文本：禁用quotes、dashes；
• 纯数字表格：开启preserve_spaces=True防止对齐空格被清除。

5. 自定义规则优先级

priority 0–20：优先执行（符号替换、商标、版权）
priority 50：默认内置规则区间
priority 80–100：后置替换（文本整体修饰）

6. 不适合中文原生排版

richtypo仅面向西文，无中文顿号、书名号、全角空格规则；中文排版建议搭配zh-typo、pangu库配合使用。

7. 爬虫文本预处理顺序建议

1. 去除HTML标签 → 2. richtypo标点美化 → 3. 自定义敏感词替换 → 4. 存储文本

8. 生产环境批量处理优化

超大文件分块读取，避免一次性加载全文至内存；批量任务添加异常捕获，防止单文件格式错误中断全部流程。

try:res=typo.process(content)exceptExceptionase:print(f"处理失败跳过文件：{filename}, 错误：{e}")res=content

9. 输出校验

处理前后对比关键标点（引号、破折号），复杂嵌套文本建议人工抽样校验，极端不规则原文可能存在少量转换偏差。

《动手学PyTorch建模与应用:从深度学习到大模型》是一本从零基础上手深度学习和大模型的PyTorch实战指南。全书共11章，前6章涵盖深度学习基础，包括张量运算、神经网络原理、数据预处理及卷积神经网络等；后5章进阶探讨图像、文本、音频建模技术，并结合Transformer架构解析大语言模型的开发实践。书中通过房价预测、图像分类等案例讲解模型构建方法，每章附有动手练习题，帮助读者巩固实战能力。内容兼顾数学原理与工程实现，适配PyTorch框架最新技术发展趋势。