xpinyin

library0.7.7pypypi✓ verified 85d ago

A Python library to convert Chinese hanzi (汉字) to pinyin (拼音). Version 0.7.7 is the latest; the library is in maintenance mode with infrequent releases.

pip install xpinyin

github ↗homepage ↗

INSTALL

IMPORT

SIG · XPINYIN

xpinyin

searchpythonv0.7.7

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Pinyin

✓ from xpinyin import Pinyin

✗ import xpinyin

The main class is Pinyin, not the module name.

Basic usage: create a Pinyin instance and call get_pinyin(). The default separator is '-'.

from xpinyin import Pinyin p = Pinyin() # Get pinyin with tone marks (default) print(p.get_pinyin('上海')) # shàng-hǎi # Get pinyin without tones print(p.get_pinyin('上海', tone_marks=None)) # shang-hai

Debug

Known issues

deprecatedThe `show_tone_marks` parameter in `get_pinyin` is deprecated. Use `tone_marks` instead.

fix

Replace `show_tone_marks=bool` with `tone_marks='marks'` or `tone_marks=None`.

affects: >=0.5.0

gotcha`get_pinyin` returns pinyin with a hyphen separator by default. Many users expect spaces.

fix

Use `splitter=''` parameter if you want no separator, or `splitter=' '` for spaces.

affects: all

gotchaThe library does not support traditional Chinese characters (only Simplified Chinese).

fix

Convert traditional characters to simplified before calling xpinyin, or use a different library like pypinyin.

affects: all

Errors

Common errors & fixes

ImportError: No module named xpinyin

The library is not installed or the import path is wrong.

fix

Run `pip install xpinyin` and use `from xpinyin import Pinyin`.

AttributeError: module 'xpinyin' has no attribute 'Pinyin'

Importing the module instead of the class.

fix

Use `from xpinyin import Pinyin`.

TypeError: get_pinyin() got an unexpected keyword argument 'show_tone_marks'

The deprecated parameter was removed in newer versions.

fix

Use `tone_marks` instead (e.g., `tone_marks='marks'` or `tone_marks=None`).

Upgrade

Version history

0.7.7latest on PyPI · released Jun 2, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

60 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/lxneng/xpinyin ↗

homepagehttps://github.com/lxneng/xpinyin ↗