TheFuzz

TheFuzz is SeatGeek’s small, battle-tested library for fuzzy string matching in Python. It wraps Levenshtein-distance-based comparisons in a handful of simple functions — ratio, partial ratio, token sort, and token set — so callers can score how similar two strings are without hand-rolling edit-distance logic. Since version 0.19 it delegates its numeric core to rapidfuzz, keeping the same familiar API while gaining a large speed boost over the original pure-Python implementation.

What You Get

• Simple ratio, partial ratio, token sort ratio, and token set ratio scoring functions in the fuzz module
• process.extract and process.extractOne for ranking the best matches out of a list of candidate strings
• Pluggable scorer support so process matching can use any of the fuzz functions, or a custom scorer
• rapidfuzz-backed performance without changing the public API surface used by existing callers
• MIT-licensed, dependency-light package with typed stubs (.pyi) for editor autocomplete

Common Use Cases

• Deduplicating user-submitted records (names, companies, addresses) that differ by typos or formatting
• Matching a search query against a list of known entities, like matching ‘new york jets’ to a canonical team name
• Reconciling file paths or song metadata that vary in punctuation, case, or word order
• Building lightweight autocomplete or ‘did you mean’ suggestions without a full search engine

Under The Hood

Architecture TheFuzz is a thin two-module facade — fuzz.py for pairwise scoring and process.py for ranking candidates — with utils.py providing shared string normalization used by both, and all numeric work delegated to the rapidfuzz C extension. Tech Stack It is a pure Python package with a single runtime dependency, rapidfuzz>=3.0.0,<4.0.0, tested with pytest and a hypothesis-based property test suite, and packaged with plain setuptools. Code Quality Coverage comes from test_thefuzz.py, test_thefuzz_pytest.py, and test_thefuzz_hypothesis.py; type stubs (.pyi files) ship alongside the untyped implementation for editor support. API Design The consistent fuzz/process split and uniform 0-100 scoring convention make the library approachable within minutes, though its surface area has stayed essentially frozen for years.