grapheme

What it is and what it does

grapheme is a Python library for working with grapheme clusters—the user-perceived characters that the Unicode Standard defines—rather than raw Unicode code points. Standard Python string functions treat each Unicode code point as a separate unit, which breaks strings containing combining marks (like underlines or accents), emoji with skin-tone modifiers, Korean Hangul, and other multi-codepoint sequences. This library implements the Unicode default rules for extended grapheme clusters and provides functions like `length()`, `substr()`, `slice()`, and `contains()` that operate on graphemes instead.

The package is useful when you need to count, truncate, or format text the way users actually see it—for example, when building text-based tables in monospaced fonts or ensuring that user input doesn't corrupt multi-codepoint characters. Performance scales linearly with string length, and the library is designed for short strings or the beginning of long strings; the documentation notes that grapheme calculation is notably slower than counting code points and recommends using standard Python functions when performance is prioritized over correctness.

Use it for:

• Count user-perceived character length in strings with combining marks or emoji modifiers without overcounting code points.
• Truncate or slice text at user-perceived boundaries to avoid splitting multi-codepoint characters and corrupting display.
• Format text-based tables or monospaced output by actual visible character width rather than Unicode code point count.
• Validate user input length constraints based on what users actually see rather than internal Unicode representation.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Provides string manipulation functions that work with grapheme clusters—user-perceived characters—rather than individual Unicode code points, enabling correct length calculations and slicing for strings with combining marks, emoji modifiers, and other multi-codepoint characters.

No. The package is abandoned (last release 2020-03-07, last commit 2022-03-21) and carries high installation friction due to compilation requirements. While it solves a real problem—correct grapheme handling—the lack of maintenance means compatibility issues with newer Python versions or Unicode standards will not be fixed. Consider it only if you are locked into an older Python environment and have no alternative; otherwise, seek an actively maintained grapheme library or implement grapheme logic inline if your use case is narrow.

Install

grapheme on PyPI

pip install grapheme

uv add grapheme

poetry add grapheme

Installing grapheme

Before you install

Installation requires compilation (high friction). The package is abandoned—last release was 2020-03-07, last commit 2022-03-21—and classifiers indicate Alpha status. No runtime dependencies, but no active maintenance means security or compatibility issues will not be addressed.

License in practice

MIT license is permissive and poses no restrictions on use, modification, or distribution.

Quickstart

pip install grapheme

import grapheme

string = 'u̲n̲d̲e̲r̲l̲i̲n̲e̲d̲'
print(grapheme.length(string))  # 10 (user-perceived characters)
print(grapheme.substr(string, 0, 3))  # 'u̲n̲d̲'

Requires compilation during installation; no explicit Python version requirement stated, but classifiers list support through Python 3.8.

Verify before relying

• Whether the package works reliably with Python versions beyond 3.8 (classifiers stop there, but no explicit upper bound is documented).
• Current Unicode Standard Annex #29 compliance status—the package targets Unicode 13.0.0, but no statement on whether later Unicode versions are supported.

Package facts

Evidence: grapheme-0.6.0.tar.gz

Tags

More Linguistic packages