pfzy - Fuzzy String Matching

0.3.4 · active · verified Thu Apr 09

pfzy is a Python port of the fzy fuzzy string matching algorithm, designed for efficient and accurate fuzzy searching primarily in fuzzy finder applications. It provides asynchronous fuzzy match functions, a fzy scorer, and a substring scorer that can calculate matching scores and provide corresponding indices. The library is currently at version 0.3.4 and supports Python versions `>=3.7,<4.0`. While the last PyPI release was in January 2022, its continued inclusion and updates in distributions like Arch Linux (up to January 2026) suggest it remains an active and relevant tool for specific fuzzy matching needs.

Warnings

gotcha pfzy strictly requires Python versions between `3.7` and `3.9.x` (specifically tested and uploaded with Python 3.9.5, though PyPI metadata states `<4.0`). Users on Python 3.10+ or Python 3.6 and below may encounter installation or runtime issues.
Fix: Ensure your Python environment is within the `Python >=3.7,<4.0` range for optimal compatibility.
gotcha The core `fuzzy_match` function is an `async` function. It must be called using `await` within an `async` context (e.g., inside an `async def` function) or executed directly using `asyncio.run()` in a synchronous script. Failing to do so will result in a `coroutine object` being returned, not the actual results.
Fix: Wrap calls to `fuzzy_match` with `asyncio.run(fuzzy_match(...))` for synchronous scripts, or `await fuzzy_match(...)` within existing `async` functions.
gotcha pfzy is a port of the `fzy` algorithm, primarily designed for interactive fuzzy *finder applications* where matching scores and *indices* are crucial for highlighting. It is not a general-purpose string similarity library like `fuzzywuzzy` or `rapidfuzz` and may behave differently or offer different features than expected if used as a direct replacement for those.
Fix: Understand the `fzy` algorithm's scoring characteristics and ensure it aligns with your specific fuzzy matching requirements, especially if you need matching indices for UI applications.

Install

pip install pfzy Install stable version

Imports

fuzzy_match
```
from pfzy import fuzzy_match
```
FzyScorer
```
from pfzy import FzyScorer
```
Used for direct scoring without options filtering.
SubstringScorer
```
from pfzy import SubstringScorer
```
Used for exact substring matching.

Quickstart

Demonstrates how to use the `fuzzy_match` function asynchronously to find fuzzy matches and their indices from a list of options based on a given query.

import asyncio
from pfzy import fuzzy_match

async def main():
    options = ["apple", "banana", "apricot", "grape"]
    query = "ap"
    results = await fuzzy_match(query, options)
    print(results)

if __name__ == "__main__":
    asyncio.run(main())

view raw JSON →