grapheme

library0.6.0pypypi✓ verified 22d ago

The `grapheme` library (current version 0.10.0) provides helpers for Unicode grapheme-aware string handling in Python. It enables accurate counting, slicing, and manipulation of strings based on user-perceived characters (graphemes) rather than Unicode code points. The library is actively maintained, supporting recent Unicode standards, and typically releases new versions a few times a year.

serialization

pip install grapheme

github ↗package ↗

INSTALL

IMPORT

SIG · GRAPHEME

grapheme

serializationpythonv0.6.0

Install

2.5s avg

Import

23ms

Disk

18MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.6.0 · 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.95 runs

installs and imports cleanly · install 0.0s · import 0.022s · 20.6MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.5s · import 0.024s · 21MB

18MB installed

● package 18MB

Code

Verified usage

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

length

✓ import grapheme grapheme.length('string')

✗ len('string')

Python's built-in `len()` counts Unicode code points, not user-perceived graphemes. For strings with combining characters or emojis, `grapheme.length()` provides the correct visual count.

slice

✓ import grapheme grapheme.slice('string', start=0, end=5)

✗ 'string'[0:5]

Native Python string slicing operates on code points and can break grapheme clusters. `grapheme.slice()` ensures slicing respects grapheme boundaries.

graphemes

✓ import grapheme list(grapheme.graphemes('string'))

`grapheme.graphemes()` returns an iterator over the grapheme clusters in a string.

This example demonstrates how to use `grapheme.length()` and `grapheme.slice()` to correctly handle user-perceived characters (graphemes) compared to Python's default string operations, which work on Unicode code points.

import grapheme rainbow_flag = "🏳️‍🌈" # An emoji represented by multiple code points # Correctly count graphemes visual_length = grapheme.length(rainbow_flag) print(f"Visual length of '{rainbow_flag}': {visual_length}") # Expected: 1 # Incorrectly count code points with built-in len() codepoint_length = len(rainbow_flag) print(f"Code point length of '{rainbow_flag}': {codepoint_length}") # Expected: 4 # Safely slice by graphemes text = "tamil நி (ni)" sliced_by_grapheme = grapheme.slice(text, end=7) print(f"Grapheme-sliced: '{sliced_by_grapheme}'") # Expected: 'tamil நி' # Unsafely slice by code points unsafely_sliced = text[:7] print(f"Codepoint-sliced: '{unsafely_sliced}'") # Expected: 'tamil ந'

Debug

Known issues

breakingPython 3.6 support was dropped with version `0.7.0`. Users on Python 3.6 should pin their `grapheme` dependency to `<0.7.0`.

fix

Upgrade to Python 3.7 or newer, or pin `grapheme<0.7.0`.

affects: >=0.7.0

breakingThe current version `0.10.0` (and `0.9.0` onwards) explicitly requires Python >=3.10. If you are using an older Python version (e.g., 3.8, 3.9), you will need to upgrade your Python environment or use an older `grapheme` version.

fix

Upgrade to Python 3.10 or newer, or pin `grapheme<0.9.0`.

affects: >=0.9.0

gotchaThe library's functions, by nature of grapheme cluster calculation, have a linear time complexity (`O(n)`) relative to string length. For performance-critical applications involving very long strings, consider the trade-off between correctness and speed.

fix

Evaluate performance needs; for extremely long strings where approximate length or codepoint-based operations are acceptable, native string methods might be faster.

affects: all

gotchaNegative indexing (e.g., `grapheme.slice(text, start=-1)`) is currently not supported for `grapheme.slice()` and will raise a `NotImplementedError`.

fix

Use positive indices for `start` and `end` arguments when using `grapheme.slice()`.

affects: all

gotchaThe `in` operator in Python performs substring checks based on Unicode code points. `grapheme.contains()` provides a grapheme-aware substring check, which may yield different results when dealing with multi-codepoint graphemes (e.g., emojis or combining characters).

fix

Always use `grapheme.contains(main_string, sub_string)` for grapheme-aware substring checks.

affects: all

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'grapheme'

The 'grapheme' package has not been installed in the active Python environment.

fix

Install the package using pip: `pip install grapheme`.

NotImplementedError: Negative indices is currently not supported

The `grapheme.slice()` function explicitly does not support negative values for its `start` or `end` arguments.

fix

Use non-negative integer values for `start` and `end` when calling `grapheme.slice()`.

AttributeError: module 'grapheme' has no attribute 'count'

The `grapheme` library provides specific functions like `grapheme.length()` and `grapheme.contains()` for grapheme-aware operations, rather than mirroring all built-in `str` methods like `count()` or `find()`.

fix

Use `grapheme.length()` to count graphemes, `grapheme.contains()` for grapheme-aware substring checks, or `list(grapheme.graphemes(your_string))` for iteration.

TypeError: expected string, bytes or os.PathLike object, not int

Functions in the `grapheme` library, such as `grapheme.length()` or `grapheme.slice()`, expect their primary string argument to be a valid string, bytes, or PathLike object, but received an incompatible type (e.g., an integer).

fix

Ensure the argument passed as the string to `grapheme` functions is a valid string type.

Upgrade

Version history

0.6.0latest on PyPI · released Mar 7, 2020

Audit

Dependencies

pythonrequiredRequired Python version as specified by PyPI metadata.

Agent activity

14 hits · last 30 days

node

Resources

githubhttps://github.com/alvinlindstam/grapheme ↗

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