Zhon

Common errors

• ERROR: Package 'zhon' requires a different Python: ...

  cause Attempting to install or run `zhon` version 2.1.1 or higher with a Python version older than 3.9.
  fix Ensure your Python environment is version 3.9 or newer. Use `python --version` to check. If needed, create a new virtual environment with a compatible Python version.

• AttributeError: module 'zhon' has no attribute 'characters'

  cause Trying to access constants directly from the top-level `zhon` module instead of its submodules (e.g., `zhon.hanzi`, `zhon.pinyin`).
  fix Constants are organized into thematic submodules. Correctly import and access them, for example: `import zhon.hanzi` then `zhon.hanzi.characters`.

Warnings

• gotcha The `zhon.hanzi.characters` constant represents all Han ideographs, which includes characters used in Chinese, Japanese, and Korean. It does not strictly filter for 'Chinese only' characters and should not be solely relied upon for language identification.
  Fix: Be aware of the scope of Han ideographs. For language-specific filtering, additional logic or libraries may be required.
• breaking Older versions of Zhon (prior to 2.x) supported Python 2.7. Version 2.1.1 and newer explicitly require Python >= 3.9. Attempting to use Zhon 2.x on older Python environments will result in installation or runtime errors.
  Fix: Upgrade your Python environment to 3.9 or newer. If compatibility with older Python is strictly necessary, consider pinning to an older Zhon version (e.g., `<2.0.0`), though these versions may be unmaintained.
• deprecated Earlier documentation and examples for regex pattern building sometimes used the `%s` operator for string formatting (e.g., `re.findall('[%s]' % zhon.hanzi.characters)`). While still functional in some cases, the f-string or `.format()` method is the modern and recommended approach in Python 3 for clarity and safety.
  Fix: Update regex pattern formatting to use f-strings or `.format()`: `re.findall(f'[{zhon.hanzi.characters}]', text)` or `re.findall('[{}]'.format(zhon.hanzi.characters), text)`.

Install

• pip install zhon Install stable version

Imports

• hanzi

  import zhon.hanzi

• pinyin

  import zhon.pinyin

• zhuyin

  import zhon.zhuyin

• cedict

  import zhon.cedict

Quickstart

This quickstart demonstrates how to use `zhon.hanzi.characters` to find CJK characters in a string and `zhon.pinyin.word` to extract Pinyin words, leveraging Python's `re` module.

import re
import zhon.hanzi

text = 'I broke a plate: 我打破了一个盘子.'
cjk_characters = re.findall('[{}]'.format(zhon.hanzi.characters), text)

print(f"Original text: {text}")
print(f"Found CJK characters: {cjk_characters}")

# Example with Pinyin
import zhon.pinyin
pinyin_text = 'Yuànzi lǐ tíngzhe yí liàng chē.'
pinyin_words = re.findall(zhon.pinyin.word, pinyin_text, re.I)

print(f"Original Pinyin text: {pinyin_text}")
print(f"Found Pinyin words: {pinyin_words}")