cn_sort
Fast, accurate Chinese word sorting by Pinyin or stroke order
快速、精确地按拼音或笔顺排序简体中文词组
Installation · Quick Start · API · How It Works · Contributing
Overview
cn_sort sorts Simplified Chinese word lists by Pinyin (with stroke order as tiebreaker) or stroke order alone. It handles polyphonic characters correctly using context-aware pinyin detection, and scales to millions of words via a multi-process pipeline.
支持百万量级中文词组排序，多音字自动识别，中英混排均可处理。
from cn_sort import sort_text_list, Mode
sort_text_list(['唯依', '唯衣', '唯一', '啊'])
# → ['啊', '唯一', '唯衣', '唯依']
sort_text_list(['重要', '重庆'])
# → ['重庆', '重要'] ✓ polyphonic: chóng vs zhòng
Features
| Feature | Details |
|---|---|
| 🔤 Pinyin sort | Tone-aware, uses context to pick correct reading for polyphonic chars |
| ✍️ Stroke-order sort | Pure stroke-count ordering (Mode.BIHUA) |
| ⚡ Scales to 1M+ words | Auto-switches to multiprocess producer-consumer pipeline |
| 🔡 Mixed content | Latin / numeric / CJK all handled; non-CJK sorts before CJK |
| 📦 Zero config | pip install cn-sort — no extra data downloads needed |
Installation
pip install cn-sort
Requirements: Python 3.6+, pypinyin, jieba (installed automatically)
Quick Start
from cn_sort import sort_text_list, Mode
# --- Pinyin mode (default) ---
sort_text_list(['唯依', '唯衣', '唯一', '啊'])
# ['啊', '唯一', '唯衣', '唯依']
# --- Stroke-order mode ---
sort_text_list(['三', '二', '一', '一二'], mode=Mode.BIHUA)
# ['一', '一二', '二', '三']
# --- Polyphonic character handling ---
sort_text_list(['重要', '重庆'])
# ['重庆', '重要'] (chóng < zhòng)
# --- Mixed Chinese / English ---
sort_text_list(['中国', 'abc', '啊'])
# ['abc', '啊', '中国']
# --- Large-scale: multiprocess kicks in automatically ---
sort_text_list(my_million_word_list) # threshold=100000 by default
API Reference
sort_text_list(text_list, freeze=False, threshold=100000, mode=Mode.PINYIN) → list[str]
| Parameter | Type | Default | Description |
|---|---|---|---|
text_list |
list[str] |
required | Words to sort |
mode |
Mode |
Mode.PINYIN |
PINYIN or BIHUA |
threshold |
int |
100_000 |
Switch to multiprocess above this count |
freeze |
bool |
False |
Set True when calling outside if __name__ == '__main__' on Windows |
set_stdout_level(level: str) → bool
Set console log verbosity. level ∈ {"DEBUG", "INFO", "WARN", "ERROR", "CRITICAL"}.
Mode (enum)
| Value | Meaning |
|---|---|
Mode.PINYIN |
Sort by Pinyin reading, stroke order as tiebreaker |
Mode.BIHUA |
Sort by stroke count only |
How It Works
cn_sort uses LSD Radix Sort — each word is converted to a tuple of integer priorities, then sorted column-by-column (last character first) using Python's stable timsort.
Step-by-step (Pinyin mode)
- Priority table — 20 000+ characters pre-ranked by pinyin + stroke order, stored in
all_word.jsonfor O(1) hash lookup - Word → tuple — each character maps to
char_pinyinsignature (e.g.人_ren2), looked up in the table - LSD radix sort — sort from least-significant column to most-significant using
operator.itemgetterfor speed - Polyphonic chars —
pypinyinuses surrounding context to pick the correct reading automatically
Stroke-order mode
Characters are ranked by their stroke increment level instead of pinyin signature. No jieba dependency needed.
Large-scale multiprocess pipeline
When len(words) > threshold, cn_sort spawns a producer-consumer process pool:
- N producer processes (one per CPU − 1): segment text with jieba, deduplicate, push to independent queues
- 1 consumer process: reads all queues, builds a priority-tuple cache for every unique token
- Main process: reassembles segments using the cache, applies final radix sort
Priority table schema
Performance
| Scale | Mode | Time |
|---|---|---|
| < 1 000 words | single-process | < 5 ms |
| 10 000 words | single-process | ~180 ms |
| 1 000 000 words | multiprocess | ~20 s (4-core) |
README note: the jieba segmentation step dominates large-scale runs. Replacing jieba with a faster segmenter would be the highest-leverage future optimisation.
Polyphonic example
Dependencies
| Package | Purpose |
|---|---|
| pypinyin | Context-aware hanzi → pinyin conversion |
| jieba | Chinese word segmentation (multiprocess mode only) |
Contributing
Contributions are welcome! Here's how to get started:
git clone https://github.com/bmxbmx3/cn_sort.git
cd cn_sort
pip install pypinyin jieba
- Fork the repo and create a feature branch:
git checkout -b feat/your-feature - Make your changes and add tests if applicable
- Open a Pull Request — describe what you changed and why
Good first issues: improving large-scale performance, adding Traditional Chinese support, writing a test suite.
License
MIT © bmxbmx3
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file cn_sort-0.11.0.tar.gz.
File metadata
- Download URL: cn_sort-0.11.0.tar.gz
- Upload date:
- Size: 473.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.12.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
1442b0fab2c9fbe0813339734b24b07a45ee43f20a33714ff724848d24503faa
|
|
| MD5 |
e4abd7c0ee41681dd0c4bba6dce5395a
|
|
| BLAKE2b-256 |
b473f401dfd90214c48c788b57cb3d6591a52e1b61ed8d35a85688e0547814df
|
File details
Details for the file cn_sort-0.11.0-py3-none-any.whl.
File metadata
- Download URL: cn_sort-0.11.0-py3-none-any.whl
- Upload date:
- Size: 495.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.12.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
e878244fbaadccb9f044e340e1b1f4ab30ab382ea75e824c2f38b23cd3fb4afe
|
|
| MD5 |
c4ae74e5f0e76d603bcb1fd0475cc629
|
|
| BLAKE2b-256 |
d7ea2948a882ea7bf05958f0b2a61115afbc74f15b0e787ac4e9794e6c75a99e
|
