zhon

library2.1.1pypypi✓ verified 88d ago

Zhon is a Python library that provides constants commonly used in Chinese text processing, such as CJK characters, Chinese punctuation marks, and patterns for Pinyin and Zhuyin. The library is currently active, with version 2.1.1 released in November 2024, and generally follows an infrequent release cadence.

data

pip install zhon

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · ZHON

zhon

datapythonv2.1.1

Install

1.6s avg

Import

8ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.1.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.008s · 18MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.6s · import 0.003s · 19MB

16MB installed

● package 16MB

Code

Verified usage

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

hanzi

✓ import zhon.hanzi

pinyin

✓ import zhon.pinyin

zhuyin

✓ import zhon.zhuyin

cedict

✓ import zhon.cedict

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}")

Debug

Known issues

gotchaThe `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.

affects: All versions

breakingOlder 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.

affects: >=2.0.0

deprecatedEarlier 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)`.

affects: <2.x examples, but applies to all Python 3 versions

Errors

Common errors & fixes

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

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'

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`.

Upgrade

Version history

2.1.1latest on PyPI · released Nov 20, 2024

Audit

Dependencies

pythonrequiredRequires Python 3.9 or newer.

Agent activity

44 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/tsroten/zhon ↗

packagehttps://pypi.org/project/zhon/ ↗

docshttps://tsroten.github.io/zhon ↗

changeloghttps://tsroten.github.io/zhon/history.html ↗