pinyinIME 0.1.5

A simple Input Method Engine, inspired by Rime.

pinyinIME

Know how to solve every problem that has been solved. -- Feynman

A simple Pinyin Input Method Engine, inspired by Rime.

Pure Python implementation, with no dependencies on any third-party libraries.

The current codebase is 800+ lines, with efforts underway to reduce it to under 500 lines.

It is the Chinese input method I currently use in my daily life.

• Author: Wenjie Wu
• PyPI: https://pypi.org/project/pinyinIME/
• Free software: MIT License

Features

• Full pinyin & abbreviation — nihao → 你好；nh → 你好（声母缩写）

• Manual syllable separation(configurable) — xi'an → 西安; ke'neng → 可能

• User learning — records your word choices and promotes them in future lookups

• Custom phrases — add your own words via ~/.config/pinyinIME/custom_phrase.txt

• Emoji input — type Chinese keywords to get emoji candidates

• Traditional Chinese — optional simplified → traditional conversion

• Python API — embed the engine directly in your own Python app

• HTTP server — local HTTP daemon for integration with native input method frameworks (e.g. macOS IMKit / Swift)

• Interactive terminal UI — optional TUI for trying the IME in your terminal (connects to the HTTP server)

Installation

pip install pinyinIME

Or with uv:

uv tool install pinyinIME

To enable traditional Chinese output, install with the optional dependency:

pip install "pinyinIME[traditional]"

Python API

from pinyinIME import PinyinEngine

engine = PinyinEngine.default()

# Get candidate words
engine.candidates("nihao")   # ['你好', ...]
engine.candidates("nh")      # ['你好', '那好', ...]
engine.candidates("n")       # ['你', '呢', '哪', ...]

# Get candidates with full pinyin and frequency score
engine.lookup("nh")
# [('你好', 'ni hao', 135314), ('那好', 'na hao', 812), ...]

# FMM syllable segmentation
engine.segment("nihao")      # ['ni', 'hao']

# Record a user selection (triggers learning)
engine.commit("你好", ["ni", "hao"])

# Select the i-th candidate on page p (also triggers learning)
engine.select("nh", index=0, page=0, page_size=5)

# Stateful paginated session
session = engine.new_session(page_size=5)
session.set_input("nihao")
print(session.current_page())   # ['你好', ...]
session.next_page()
session.select(0)               # returns ('你好', '')

CLI Usage

# Look up candidates for a pinyin string
pinyinIME lookup nihao
pinyinIME lookup nh           # abbreviation: 声母缩写
pinyinIME lookup "xi'an"      # manual syllable split → 西安

# Open debug playground in browser (requires server running)
uv run --with bottle pinyinIME serve   # start HTTP server first
pinyinIME playground                   # then open playground in browser

# Clear disk index cache
pinyinIME clear-cache

# Enable debug logging
pinyinIME --verbose lookup nihao

# Interactive terminal UI (requires bottle + rich; start server first)
uv run --with bottle pinyinIME serve         # start HTTP server
uv run --with rich pinyinIME interactive     # then launch interactive UI

Configuration

User data is stored in ~/.config/pinyinIME/:

File	Purpose
custom_phrase.txt	Custom words, one per line, loaded at startup
pinyin.userdb	User selection history (plain text log)
config.json	Engine config (see defaults below)

Default config.json

{
  "engine": {
    "segment_delimiter": "'",
    "top_n": 10,
    "max_abbrev_fanout": 10,
    "search_timeout": 0.5
  },
  "log": {
    "level": "INFO"
  }
}

Custom Phrases

Add your own words to ~/.config/pinyinIME/custom_phrase.txt, one word per line:

# 每行一个词条，格式：词[, 音节][, 权重]（后两项可选）
一丹中心
阅读场
π, pi, 100

艾伦·凯, ai lun kai
动态媒介

Pinyin is auto-annotated from the built-in character dictionary.

Development

git clone https://github.com/wwj718/pinyinIME.git
cd pinyinIME

# Install in editable mode (changes take effect immediately)
uv tool install --editable .

# Run tests
uv run pytest

# Full QA (format, lint, type check, test)
just qa

Architecture Overview

PinyinEngine
├── index/
│   ├── dict_loader.py           dictionary data
│   ├── essay_loader.py          Word frequency data
│   ├── custom_phrase_loader.py  User custom words
│   ├── builder.py               IndexBuilder → (Prism, Table); PhraseAnnotator
│   ├── prism.py                 Spelling → [(syllable_id, SpellingType)]
│   └── table.py                 Trie: syllable_id[] → DictEntry[] (sorted by score)
├── pipeline/
│   ├── types.py        SpellingType enum, SPELLING_PENALTY constants
│   ├── segmentor.py    FmmStrategy (default) + DagAllPathsStrategy; SegmentationStrategy Protocol
│   ├── translator.py   Querier: DFS over segments, Prism+Table lookup, timeout protection
│   ├── filter.py       DeduplicateFilter; TraditionalFilter (simp→trad)
│   └── session.py      InputSession: stateful pagination, NORMAL + CHAR_BY_CHAR modes
└── userdata/
    ├── user_paths.py   Config dir & file path management
    └── user_history.py UserHistory: plain-text frequency log (pinyin.userdb)

Scoring

Candidates are ranked by an adjusted score:

adjusted_score = round((log(max(raw_score, 1)) + spelling_penalty) × 1_000_000)

Weight multipliers before the log:

Source	Multiplier
User history	10,000,000
Custom phrases	1,000,0 * (1-100)
Emoji	1,000
Essay (Rime) base	1

Spelling penalties: NORMAL → 0.0, ABBREVIATION → log(0.1) ≈ −2.303

Author

pinyinIME was created in 2026 by Wenjie Wu.

Built with the cookiecutter-pypackage project template.