python-pinyin: A Robust Python Library for Hanzi to Pinyin Conversion

Introduction

`python-pinyin` is a powerful Python library developed by mozillazg that facilitates the conversion of Chinese characters (Hanzi) into Pinyin. It is widely used for various applications, including annotating Chinese text, sorting data, and enabling efficient search functionalities. The library stands out for its intelligent phrase matching, comprehensive support for polyphonic characters, and flexibility in outputting different Pinyin and Bopomofo styles.

Installation

You can easily install `python-pinyin` using pip:

pip install pypinyin

Alternatively, if you use `uv`, you can install it with:

uv add pypinyin

Examples

Here are some examples demonstrating the versatility of `python-pinyin`:

from pypinyin import pinyin, lazy_pinyin, Style

# Basic conversion
print(pinyin('??'))
# Output: [['zh?ng'], ['x?n']]

# Enable polyphonic character mode
print(pinyin('??', heteronym=True))
# Output: [['zh?ng', 'zhòng'], ['x?n']]

# Set Pinyin style (e.g., first letter)
print(pinyin('??', style=Style.FIRST_LETTER))
# Output: [['z'], ['x']]

# Bopomofo style
print(pinyin('??', style=Style.BOPOMOFO))
# Output: [['???'], ['???']]

# Lazy Pinyin (no tone marks, single result per character)
print(lazy_pinyin('??'))
# Output: ['zhong', 'xin']

Why Use `python-pinyin`?

`python-pinyin` offers several compelling reasons for developers working with Chinese text:

• Accuracy: It intelligently matches the most correct Pinyin based on phrases and provides comprehensive support for polyphonic characters, ensuring high accuracy in conversions.
• Flexibility: The library offers a wide range of Pinyin and Bopomofo styles, including options for tone marks, first letters, and Wade-Giles, catering to diverse linguistic and application requirements.
• Customization: Users can easily customize phrase and single-character Pinyin dictionaries to correct or optimize conversion results. It also integrates seamlessly with external Pinyin data projects for enhanced accuracy.
• Comprehensive Features: Beyond basic conversion, `python-pinyin` includes utilities for Pinyin style conversion, command-line tools, and extensive documentation covering common FAQs and advanced usage scenarios.
• Robust and Maintained: Developed by mozillazg, the project benefits from active maintenance and a strong community, ensuring reliability and ongoing improvements.

Links

• Official Documentation: https://pypinyin.readthedocs.io/
• GitHub Repository: https://github.com/mozillazg/python-pinyin
• PyPI Project Page: https://pypi.org/project/pypinyin