jarowinkler

library2.0.1pypypi✓ verified 85d ago

JaroWinkler is a high-performance Python library for approximate string matching, implementing Jaro and Jaro-Winkler similarity algorithms. Currently at version 2.0.1, it leverages the `rapidfuzz` library for its core implementations, offering significant speed advantages over alternatives. The project maintains an active development cycle, with a focus on optimization and ease of integration.

serialization data ai-ml

pip install jarowinkler

github ↗package ↗

INSTALL

IMPORT

SIG · JAROWINKLER

jarowinkler

serializationpythonv2.0.1

Install

2.5s avg

Import

130ms

Disk

30MB

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.0.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.136s · 33.7MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 2.5s · import 0.123s · 30MB

30MB installed

● package 30MB

Code

Verified usage

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

jarowinkler_similarity

✓ from jarowinkler import jarowinkler_similarity

jaro_similarity

✓ from jarowinkler import jaro_similarity

jarowinkler_metric

✓ from jarowinkler import jarowinkler_similarity

✗ from jarowinkler import jarowinkler_metric

Older or other Jaro-Winkler libraries might use 'jarowinkler_metric'. The `jarowinkler` library (maxbachmann) uses 'jarowinkler_similarity'.

Demonstrates how to calculate Jaro and Jaro-Winkler similarity scores between strings, including the use of an optional `score_cutoff` and its application to sequences of hashable objects.

from jarowinkler import jaro_similarity, jarowinkler_similarity # Calculate Jaro Similarity sim_jaro = jaro_similarity("Johnathan", "Jonathan") print(f"Jaro Similarity: {sim_jaro:.4f}") # Calculate Jaro-Winkler Similarity sim_jw = jarowinkler_similarity("Johnathan", "Jonathan") print(f"Jaro-Winkler Similarity: {sim_jw:.4f}") # Using with a score cutoff sim_jw_cutoff = jarowinkler_similarity("apple", "aple", score_cutoff=0.9) print(f"Jaro-Winkler with cutoff (0.9): {sim_jw_cutoff:.4f}") # Can also be used with sequences of hashable objects list1 = ["this", "is", "an", "example"] list2 = ["this", "is", "a", "example"] sim_list = jarowinkler_similarity(list1, list2) print(f"Similarity of lists: {sim_list:.4f}")

Debug

Known issues

breakingVersion 2.0.0 dropped support for Python 3.6 and Python 3.7. Users on these Python versions must either upgrade Python or pin `jarowinkler` to `<2.0.0`.

fix

Upgrade to Python 3.8 or newer, or use `pip install 'jarowinkler<2.0.0'`.

affects: >=2.0.0

breakingSince v2.0.0, the library's internal implementations are deduplicated and now rely on `rapidfuzz`. While the API aims to be consistent, `rapidfuzz` is effectively a required runtime dependency. This change might subtly alter behavior or performance characteristics from pre-2.0.0 versions which used standalone C++ implementations.

fix

Ensure `rapidfuzz` is installed alongside `jarowinkler`. Review performance benchmarks if migrating from older versions.

affects: >=2.0.0

gotchaJaro-Winkler similarity, by design, gives a higher weight to matching prefixes. This can sometimes lead to unexpectedly high similarity scores for strings that share a long common prefix but are otherwise quite different, or lower scores if there's no common prefix, even if the strings are otherwise similar.

fix

Be aware of the prefix bias in Jaro-Winkler. For applications where prefix matching is less critical, consider using Jaro similarity or other string metrics. The `prefix_weight` parameter can be adjusted in `jarowinkler_similarity` (default 0.1) if using `rapidfuzz.distance.JaroWinkler.similarity` directly.

affects: all

gotchaThe functions `jaro_similarity` and `jarowinkler_similarity` can operate on any sequence of hashable objects, not just strings. While powerful, comparing sequences of mixed types or non-comparable hashables can yield unexpected results or `TypeError`s if `__hash__` or `__eq__` methods are not consistently defined.

fix

When using `jarowinkler` with sequences, ensure that elements within the sequences are consistently hashable and comparable. If comparing custom objects, verify their `__hash__` and `__eq__` implementations.

affects: all

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'jarowinkler'

The `jarowinkler` library is not installed in the active Python environment.

fix

Run `pip install jarowinkler` to install the library.

AttributeError: module 'jarowinkler' has no attribute 'jaro_winkler_metric'

Attempting to use an API call (`jaro_winkler_metric`) from a different Jaro-Winkler library (e.g., `jaro-winkler` or `pyjarowinkler`) that is not part of this specific `jarowinkler` package.

fix

The correct function in this library is `jarowinkler_similarity`. Update your code to `from jarowinkler import jarowinkler_similarity` and use `jarowinkler_similarity(str1, str2)`.

TypeError: 'float' object cannot be interpreted as an integer (when passing non-string/non-sequence to similarity function)

One of the input arguments to `jaro_similarity` or `jarowinkler_similarity` is not a string or a sequence of hashable objects.

fix

Ensure both arguments passed to `jaro_similarity` or `jarowinkler_similarity` are strings or iterable sequences of hashable objects (e.g., lists of strings/numbers). For example, `jarowinkler_similarity('test', 123)` will fail, it should be `jarowinkler_similarity('test', '123')` or `jarowinkler_similarity('test', ['1','2','3'])`.

ValueError: prefix_weight has to be between 0 and 0.25 (inclusive)

The `prefix_weight` parameter, when used with `jarowinkler_similarity` (or underlying `rapidfuzz` calls), was provided with a value outside its valid range.

fix

Ensure `prefix_weight` is set to a float between 0.0 and 0.25, inclusive. For example: `jarowinkler_similarity('foo', 'bar', prefix_weight=0.15)`.

Upgrade

Version history

2.0.1latest on PyPI · released Nov 3, 2023

Audit

Dependencies

rapidfuzzrequiredCore dependency since v2.0.0 for underlying string metric implementations and performance optimizations.

cmakeoptionalRequired for building from source distribution (sdist), though pre-compiled wheels are typically available.

ninjaoptionalRecommended build tool for source distributions to optimize compilation speed.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/maxbachmann/JaroWinkler ↗

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