Metadata-Version: 2.4
Name: cidian
Version: 0.1.0
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Rust
Classifier: Typing :: Typed
License-File: LICENSE
Summary: Fast parser for Chinese input method dictionaries
Keywords: chinese,dictionary,input-method,pinyin
Home-Page: https://github.com/Yousa-Mirage/py-cidian
Author-email: Yousa-Mirage <Yousa-Mirage@foxmail.com>
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# py-cidian

<div align="center">

[![Python >= 3.10](https://img.shields.io/badge/python-%3E%3D3.10-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

</div>

`py-cidian` 读取中文输入法词库，并把不同格式转换成统一的 Python 数据模型。目前支持以下格式：

| 格式  | 扩展名   | 来源    |
| ----- | -------- | ------- |
| SCEL  | `.scel`  | 搜狗    |
| QCEL  | `.qcel`  | QQ 拼音 |
| QPYD  | `.qpyd`  | QQ 拼音 |
| BDICT | `.bdict` | 百度    |
| BCD   | `.bcd`   | 百度    |

底层解析由 Rust 库 [`cidian-rs`](https://github.com/Yousa-Mirage/cidian-rs) 完成。解析结果保持词条在源文件中的顺序，不会自动规范化、排序或去重。

`py-cidian` 与 [`r-cidian`](https://github.com/Yousa-Mirage/r-cidian) 提供相近的数据模型，适合把输入法词库转换为中文分词工具可使用的自定义词表。

## 安装

使用 uv 从 PyPI 安装：

```sh
uv pip install cidian
```

如需从源码构建，可以克隆仓库后生成 wheel：

```sh
git clone https://github.com/Yousa-Mirage/py-cidian.git
cd py-cidian
uv sync --locked
uv build --no-sources
```

从源码构建需要 Rust 1.85 或更高版本。生成的 wheel 使用 Python 3.10+ 稳定 ABI。

## 使用说明

### 从文件读取

`read_cidian()` 默认根据文件扩展名识别格式：

```python
from cidian import read_cidian

dictionary = read_cidian("计算机科技.qcel")

print(dictionary.format)
# qcel

print(dictionary.metadata.name)
# 计算机名词

print(len(dictionary))
# 9646

print(dictionary.entries[0])
# Entry(word='阿里通', code=('a', 'li', 'tong'), weight=8)
```

当路径没有正确的扩展名时，可以显式指定格式。格式名不区分大小写，也可以带有开头的点：

```python
dictionary = read_cidian("dictionary.bin", format=".QCEL")
```

### 从 bytes 加载

`load_cidian()` 把内存中的 `bytes` 直接交给 Rust 解析，不经过临时文件：

```python
from pathlib import Path

from cidian import load_cidian

data = Path("计算机科技.qcel").read_bytes()
dictionary = load_cidian(data, format="qcel")
```

与文件读取不同，内存数据没有扩展名，因此必须提供 `format`。

### 访问词条和元信息

解析结果由 `Dictionary`、`Metadata` 和 `Entry` 数据类组成：

```python
metadata = dictionary.metadata
print(metadata.name)
print(metadata.category)
print(metadata.description)
print(metadata.extra)

for entry in dictionary:
    print(entry.word, entry.code, entry.weight)
```

其中：

- `Entry.word` 是原始词语；
- `Entry.code` 是由编码组件组成的元组，例如拼音音节；
- `Entry.weight` 是来源格式提供的可选权重；
- `Metadata.extra` 保存无法归入通用字段的来源特有元信息。

### 导出词语

`write_words()` 按原始顺序把所有词语写入 UTF-8 文本文件，每行一个：

```python
from cidian import write_words

write_words(dictionary, "words.txt")
```

目标文件已存在时默认抛出 `FileExistsError`。需要覆盖时显式传入：

```python
write_words(dictionary, "words.txt", overwrite=True)
```

## 致谢

- 感谢 nopdan 的[输入法词库解析系列文章](https://nopdan.com/series/lexicon/)以及
  [nopdan/rose](https://github.com/nopdan/rose) 蔷薇词库转换库；`cidian-rs` 的开发大量参考了这些资料。
- 感谢 qinwf/cidian 项目提供开发动机。
- `py-cidian` 的公开 API 和文档结构参考了 [`r-cidian`](https://github.com/Yousa-Mirage/r-cidian)。
- Python 绑定使用 [PyO3](https://github.com/PyO3/pyo3) 实现。

## 许可证

MIT License

