pypinyin Documentation

pypinyin is a tool for converting Chinese characters to pinyin. It is suitable for character annotation, sorting, and retrieval.

Key features include:

• Intelligent pinyin matching based on words/phrases.
• Support for polyphones (characters with multiple pronunciations).
• Simple support for Traditional Chinese and Zhuyin (Bopomofo).
• Support for various pinyin styles.

Install the pypinyin package using easy_install.

$ easy_install pypinyin

The release process involves rebasing, generating data, testing, updating the changelog, and publishing. Use the following make commands for specific steps:

1. Prepare: Rebase master branch using make rebase_master.
2. Data Generation: Generate latest data files using make gen_data.
3. Testing: Run tests using make test.
4. Merging: Merge the develop branch into master using make merge_dev.
5. Versioning:
   • For minor changes (e.g., 1.1.x -> 1.2.x): make bump_minor
   • For patch changes (e.g., 1.1.1 -> 1.1.2): make bump_patch
6. Publishing:
   • To Test PyPI: make publish_test
   • To PyPI: make publish
7. Cleanup: Prepare for the next development cycle using make start_next.

You can run unit tests using make test for the current Python version, or use tox to run tests across multiple Python versions (this is also typically run via CI during Pull Requests).

To run tests in the current environment:

(venv) $ make test

To run tests across multiple versions using tox:

(venv) $ tox

Install the pypinyin package using pip to enable Chinese character to pinyin conversion in your Python environment.

$ pip install pypinyin

If the pinyin results are incorrect, you can improve accuracy by loading custom phrase or single-character dictionaries.

Customizing via code:

from pypinyin import load_phrases_dict, load_single_dict

# Add a custom phrase
load_phrases_dict({'桔子': [['jú'], ['zǐ']]})

# Adjust or override single character pinyin
load_single_dict({ord('还'): 'hái,huán'})

Using pypinyin-dict:

You can also use the pypinyin-dict project to load optimized data from cc_cedict.txt or kXHC1983.txt.

from pypinyin_dict.phrase_pinyin_data import cc_cedict
cc_cedict.load()

from pypinyin_dict.pinyin_data import kxhc1983
kxhc1983.load()

You can install pypinyin using pip or uv.

pip install pypinyin

Or using uv:

uv add pypinyin

Use pinyin() to get a list of lists containing pinyin for each character, or lazy_pinyin() to get a flat list of pinyin strings.

Key features:

• Heteronyms: Set heteronym=True to include multiple possible pronunciations for polyphonic characters.
• Styles: Use the style parameter with pypinyin.Style constants (e.g., Style.TONE3, Style.FIRST_LETTER, Style.BOPOMOFO).
• Ü handling: By default, ü is represented as v. Use v_to_u=True to use ü instead.
• Neutral tones: Use neutral_tone_with_five=True to represent neutral tones with the number 5 (e.g., Style.TONE3).
• Tone Sandhi: Set tone_sandhi=True to apply tone sandhi rules (e.g., converting nǐ hǎo to ní hǎo).

To develop for pypinyin, use Python 3.6+ and follow these steps to create a virtual environment, install development dependencies, and install the package in editable mode:

$ virtualenv venv
$ . venv/bin/activate
(venv) $ pip install -U -r requirements_dev.txt
(venv) $ pip install -e .
(venv) $ pre-commit install

Install the pypinyin package by running the setup script from the source directory.

$ python setup.py install

If memory consumption is a concern and high pinyin accuracy is not critical, you can set the following environment variables to reduce the footprint:

• PYPINYIN_NO_PHRASES
• PYPINYIN_NO_DICT_COPY