Metadata-Version: 2.4
Name: SiChuan-pinyin
Version: 1.0.0
Summary: 汉字 -> 四川话拼音(蜀拼)转换: 三档口音(老派通音/成都/重庆), 声调 1-5 或装饰音
Author: SiChuan-pinyin contributors
License-Expression: GPL-3.0-or-later
Keywords: sichuan,sichuanese,pinyin,shupin,蜀拼,四川话,成都话,重庆话,linguistics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Text Processing :: Linguistic
Classifier: Natural Language :: Chinese (Simplified)
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# SiChuan-pinyin

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

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

## 安装

```bash
pip install SiChuan-pinyin
```

或从源码构建：

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

## 快速开始

```python
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')]
```

命令行：

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

## 声调

| 调值 | 调类 | 装饰音 |
|---|---|---|
| 1 | 阴平 | ā |
| 2 | 阳平 | á |
| 3 | 上声 | ǎ |
| 4 | 去声 | à |
| 5 | 入声 | â |

> 注：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>liu2` | — | ✅ | —（走 `lu5` 入派得 `lu2`） |
| 特字 的 `>le`、去 `>qie4` | ✅ | ✅ | ✅ |
| 成都 C 系特字（集 `jie2`、息 `xie2`、郭 `gue2` 等 26 字） | — | ✅ | — |
| 通入 `su5>sv5` | — | ✅ | — |
| 通入 üu 系（`ju5>juu5`、`zu5>zvu5`、`su5>svu5`、`yu5>yvu5`…） | — | — | ✅ |
| 入派阳平 `5>2` | — | ✅ | ✅ |
| 戈歌不分 `eo>o` | — | ✅ | ✅ |
| 泥来混读 `ni>li`、`nv>lv` | — | — | ✅ |
| 尖团合并（`zyi>ji`、`zi+细音>ji+`、`zv>ju`…） | — | ✅ | ✅ |
| `yv>yu` | — | — | ✅ |
| 无翘舌 `zh/ch/sh>z/c/s` | — | ✅ | ✅ |
| `hu>fu` | — | ✅ | ✅ |

示例差异：

```
老派: 六 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 摘要

```python
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 前端时如需与既有音素序列对齐，请以上述差异为预期差。

## 测试

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

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

## 已知边界

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