Install & Compatibility
Where this runs
tested against v4.0.3 · 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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 17.9MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.5s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
NGram
✓ from ngram import NGram
✗ import ngram; ngram.NGram()
The primary class for fuzzy matching is `NGram`, which should be imported directly from the `ngram` package.
Initialize an `NGram` instance with a collection of strings or objects (optionally with a `key` function for non-string items). Add items and use the `search` method to find members with high N-gram similarity to a query string. You can also use `NGram.compare` for direct string comparison.
from ngram import NGram
# Initialize an NGram object with a list of items
# N (default 3) is the size of n-grams to use for comparison
fuzzy_set = NGram(N=2, items=['apple', 'apricot', 'banana', 'orange', 'grape'])
# Add more items to the set
fuzzy_set.add('apply')
# Search for items similar to a query string
# The threshold (default 0.7) determines the minimum similarity score
results = fuzzy_set.search('appl', threshold=0.7)
print(f"Searching for 'appl': {results}")
# Expected: [('apple', 1.0), ('apply', 0.8), ('apricot', 0.75)] (scores may vary based on N)
# Directly compare two strings
similarity = NGram.compare('apple', 'apply', N=2)
print(f"Similarity between 'apple' and 'apply': {similarity}")
Debug
Known issues
gotchaThe `ngram` library is designed for character-based N-grams by default, not word-based. This means it splits strings into sequences of characters, not words. If you require word N-grams for natural language processing tasks, you will need to pre-process your text or use a different library (e.g., NLTK).fixBe aware of the character-based nature. For word N-grams, tokenize your text into words first and then apply appropriate N-gram logic, possibly with a different NLP-focused library.
affects: All versions
gotchaWhen initializing `NGram` with a `key` function to convert items to strings (e.g., `NGram(items, key=str)` or `NGram(items, key=lambda x: x.name)`), using an anonymous (lambda) function will prevent the resulting `NGram` object from being pickled (serialized).fixIf pickling `NGram` instances is required, use a named function for the `key` parameter instead of a lambda function. For example, `def get_name(obj): return obj.name; NGram(items, key=get_name)`.
affects: All versions
gotchaIn Python 2, `NGram` could behave unexpectedly with non-ASCII byte-strings due to splitting on byte boundaries. While Python 3 primarily uses Unicode strings, ensuring all inputs to `NGram` are proper Unicode strings is crucial for correct multi-byte character handling.fixAlways pass Unicode strings to `NGram` in Python 3. If dealing with raw byte data, decode it to Unicode first (e.g., `my_bytes.decode('utf-8')`) before indexing or searching. affects: Python 2.x and early Python 3.x where byte-string confusion was common. Less of an issue in modern Python 3, but still a consideration.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'ngram'
The `ngram` package has not been installed in your current Python environment.
fixRun `pip install ngram` to install the library.
AttributeError: module 'ngram' has no attribute 'NGram'
This typically occurs when your Python script is named `ngram.py`. When you try to import `NGram` from `ngram`, Python tries to import from your own script rather than the installed library, and your script does not contain the `NGram` class.
fixRename your Python script to something other than `ngram.py` (e.g., `my_ngram_app.py`) and try running it again.
Upgrade
Version history
4.0.3latest on PyPI · released Sep 15, 2021
Audit
Dependencies
No dependency data recorded yet.