jellyfish soundex, metaphone and Jaro-Winkler for name matching: working versions (tested 2026-10-16)

jellyfish==1.3.0
pytest==9.1.1

import unicodedata

import jellyfish


def normalize(name):
    # NFKD + ascii drop makes matching accent and case insensitive
    ascii_name = unicodedata.normalize("NFKD", name).encode("ascii", "ignore").decode()
    return " ".join(ascii_name.upper().split())


def soundex_key(name):
    # soundex is a fixed 4-char code, so unrelated surnames often collide
    return jellyfish.soundex(normalize(name))


def metaphone_key(name):
    # metaphone is variable length and collapses non-letters to an empty string
    return jellyfish.metaphone(normalize(name))


def similarity(a, b):
    return jellyfish.jaro_winkler_similarity(normalize(a), normalize(b))


def is_match(a, b, threshold=0.9):
    na, nb = normalize(a), normalize(b)
    if not na or not nb:
        return False
    if na == nb:
        return True
    ma, mb = metaphone_key(na), metaphone_key(nb)
    if ma and ma == mb:
        return True
    return similarity(na, nb) >= threshold


def best_match(query, candidates):
    scored = ((c, similarity(query, c)) for c in candidates)
    choice, score = max(scored, key=lambda pair: pair[1], default=(None, 0.0))
    return {"choice": choice, "score": score}

import jellyfish
import pytest

from matcher import best_match, is_match, metaphone_key, normalize, similarity, soundex_key


def test_jaro_winkler_needs_normalized_input():
    # jellyfish does no cleaning: a raw case mismatch scores zero, accents drag it down
    assert jellyfish.jaro_winkler_similarity("smith", "SMITH") == 0.0
    assert normalize("  Jose\u0301  ") == "JOSE"
    assert similarity("smith", "SMITH") == 1.0
    assert similarity("José", "Jose") == 1.0


def test_prefix_boost_on_transposition():
    # Jaro-Winkler adds a bonus for the shared MAR- prefix
    assert round(similarity("MARTHA", "MARHTA"), 3) == 0.961


def test_soundex_collides_but_matcher_rejects():
    # both names share soundex R163, a classic false positive
    assert soundex_key("Robert") == soundex_key("Rupert") == "R163"
    assert not is_match("Robert", "Rupert")


def test_metaphone_bridges_spelling_variants():
    assert metaphone_key("Catherine") == metaphone_key("Katherine") == "K0RN"
    assert is_match("Catherine", "Katherine")


def test_empty_phonetic_keys_are_guarded():
    # digits and non-Latin names reduce to an empty key, so guard against it
    assert metaphone_key("123") == ""
    assert not is_match("", "")
    assert not is_match("\u674e", "")


def test_best_match_picks_closest_candidate():
    result = best_match("Jon", ["Jane", "John", "Jason"])
    assert result["choice"] == "John"
    assert result["score"] == pytest.approx(0.933, abs=1e-3)

[pytest]
pythonpath = .