SiChuan-pinyin

汉字 → 四川话拼音（蜀拼 / Shupin）转换库。三种口音可选，声调支持数字调（zhang1）与装饰音调（zhāng）。

• 纯 Python 标准库实现，零依赖
• 17091 字 + 2836 词 + 471 音节（464 通音 + 7 口音扩展）内置数据
• 规则链逐条复刻 Rime 蜀拼输入法三个 schema 的启用 xform 项（见下文「口音规则」）

安装

pip install SiChuan-pinyin

或从源码构建：

python -m build   # 生成 dist/*.whl
pip install dist/*.whl

快速开始

from sichuan_pinyin import convert, SichuanPinyin

# 三档口音: laopai(老派通音) / chengdu(成都) / chongqing(重庆)
convert("成都")                                  # 'cheng2 dou1'
convert("成都", accent="chengdu")                # 'cen2 dou1'
convert("成都", accent="chongqing")              # 'cen2 dou1'

# 声调: num(数字, 默认) / mark(装饰音)
convert("国", accent="chengdu", tone="mark")     # 'gué'

# v(ü) 渲染为 ü
convert("女", accent="chongqing", umlaut=True)   # 'lü3'

# 多音字全部列出
SichuanPinyin().convert("都", heteronym=True)    # [['dou1', 'du1']]

# 逐字首选读音(供 G2P/TTS 管线)
SichuanPinyin().convert_pairs("中A国")           # [('中','zhong1'), ('A',None), ('国','gue5')]

命令行：

sichuan-pinyin "你好成都" --accent chengdu --tone mark
python -m sichuan_pinyin "你好成都" -a chongqing -t mark -u

声调

注：Rime 蜀拼输入法的 preedit 显示把上声标 â、入声标 ǎ；本库按「阴阳上去入 = 12345 / āáǎàâ」输出，与输入法显示方案不同。

元音定位规则（与 Rime preedit 重排等效）：a > e（含 eo/ei/ie/ue）> o（含 ou/uo）> iu 标 u > ui 标 i > v(ü) > u > i。蜀拼以 v 记 ü；umlaut=True 时输出 ü/ǖǘǚǜ（承载调符的 v 在 mark 样式下必然呈 ü 形，如 nv3 → nǚ）。

口音规则

三档规则链忠实复刻 shupin-master 的 shupin_tongyin / cendu / congqin 三个 schema 中启用的 xform 项（schema 里的 derive 类是输入法「两可」便利拼写，不作为转换结果）。顺序即 schema 原文顺序：

示例差异：

老派: 六 lu5  速 su5  卒 zu5  域 yu5  千 cian1  修 siu1  你 ni3  中 zhong1
成都: 六 liu2 速 xu2  卒 zu2  域 yu2  千 qian1  修 xiu1  你 ni3  中 zong1
重庆: 六 lu2  速 xuu2 卒 juu2 域 yuu2 千 qian1  修 xiu1  你 li3  中 zong1

蜀拼方案要点：尖团对立（zian/cian/sian vs jian/qian/xian）、疑母 ng-、微母 v-、入声独立调 5、ir（zhi/chi/shi/ri 韵）、i0（zi/ci/si 韵）、En（yan 韵）、E（ye 韵）、v 记 ü。

API 摘要

convert(text, accent="laopai", tone="num", umlaut=False, heteronym=False)
SichuanPinyin(accent, tone, umlaut).convert(text, heteronym=False, accent=None, tone=None, umlaut=None)
    .readings(ch, accent=None)      # 单字全部读音(已应用口音规则), 数字调
    .convert_pairs(text, ...)       # [(字符, 首选读音 or None)]
    .iter_readings(text, accent=None)  # 迭代 (字符, 数字调音节), 供管线复用
    .syllables()                    # 471 音节表
    .syllable_parts(syl)            # -> (声母符号, 韵母基座); 未登记 None
    .last_unknown                   # 上次转换的字典外汉字
normalize_accent / apply_accent / accent_diff_rules   # 口音工具
normalize_tone / render / to_mark / TONE_NAMES        # 声调工具

accent 接受 laopai/老派通音/通音、chengdu/成都/cd、chongqing/重庆/cq 等别名（大小写不敏感）；tone 接受 num/数字、mark/装饰音。

行为约定：

• 最长词优先切词（max 8 字），未登录字按单字取首选读音
• 非汉字原样保留；音节间空格分隔，标点紧贴前后音节；音节前接字母/数字时自动补空格
• 字典外汉字原样透传并记入 last_unknown

数据来源与授权

• 字典与口音规则衍生自 Rime 输入法蜀拼方案（shupin-master，作者 Ciphotis、涼風Papnas、旷_野、soenghaagong、holy19891004 等），GPL-3.0-or-later
• 中古汉语广韵字音表（疑母 ŋ- / 微母 v- 恢复）
• 因此本库整体以 GPL-3.0-or-later 分发，完整授权文本见 LICENSE

构建产物位于 src/sichuan_pinyin/data/：char_dict.tsv（17091 字）、word_dict.tsv（2836 词）、syllable_map.tsv（471 音节 → 声母/韵母符号，供音素管线重建）、special.tsv（特字表）、meta.json（来源与计数）。构建脚本见 tools/prep_data.py。

与既有语料 / TTS 管线的已知差异

以 MagicData 蜀渝语料（sc_phones.tsv，G2P 实际处理 norm_text 列）为基线的回归结论（tools/corpus_regression.py）：

• 老派通音 vs 语料 G2P：token 级差 2.24%（3769/168596），差异全部来自语料 G2P 自身状态，非本库缺陷：
  • 疑母广复（语料按 ng- 本库按通音 Rime 忠实读法）528
  • 泥来已混（语料预合并，本库仅重庆档混读）669
  • 多音字声调优先级（语料词表与 Rime 首选不同）444
  • 词级声母差异 169 / 其它 119
• 成都 vs 重庆：1.51%（两档共同规则外的差异主要为泥来与通入）
• 语料使用扩充词表（62328 条 / 476 音节），与本库内置词表（2836 条 / 471 音节）不同口径

即：本库定位为蜀拼通音/成都/重庆三档字词典与规则链的忠实实现，不是语料 G2P 的复刻；用作 TTS 前端时如需与既有音素序列对齐，请以上述差异为预期差。

测试

python -m unittest discover -s tests -v   # 52 项, 零依赖

覆盖：三档规则单测（逐条对照 schema）、特字/字级读音、API 行为、装饰音全量往返、数据全量校验（所有字 × 所有口音的变换结果必带调值且音节在表内）、CLI 冒烟。

已知边界

• 字典外汉字透传不读音（如部分生僻字），记入 last_unknown
• syllable_parts 为有损分解（如 geo 与 go 均分解为 (g, o)），音节级比对请用音节本身而非分解结果
• 蜀拼 En/E/i0/AA/Yng 等为内部/语料符号，与读音拼写不是同一套字母