mozillazg/python-pinyin

python-pinyin is a Python library that converts Chinese characters to pinyin romanization.

The tool solves the problem of translating hanzi (Chinese characters) into their phonetic pinyin representation. It uses intelligent phrase-based matching to select the most accurate pronunciation for each character, handles polyphonic characters that have multiple valid pronunciations depending on context, and supports various output styles including tone marks, numbered tones, bopomofo (zhuyin) notation, and Wade-Giles romanization. The library can also perform tone sandhi conversion to reflect natural speech patterns.

Developers should choose this tool if they need to annotate Chinese text with pronunciation, implement sorting or search functionality for Chinese content, or convert between different romanization systems. The project suits applications ranging from language learning software to text processing pipelines. It provides both a Python API and command-line tools for flexibility in integration. Users can customize pinyin results by loading custom phrase or character dictionaries to correct inaccuracies for domain-specific vocabulary.

The project maintains active development across multiple Python versions and receives regular updates to handle edge cases and improve accuracy. The codebase includes comprehensive documentation with usage examples and a command-line interface for standalone use. The tool offers straightforward installation through standard package managers and provides clear configuration options for controlling output format, tone representation, and handling of characters without pinyin data.