RapidFuzz/api_differences.md

API differences to fuzzywuzzy

Rapidfuzz does provide a very similar API to fuzzywuzzy/thefuzz making it a drop in replacement for a large amount of projects. However there are some differences which are listed below:

ratio implementation

fuzzywuzzy provides two implementations of the algorithm:

1. a pure Python version implemented using difflib (Ratcliff and Obershelp algorithm)
2. an accelerated version using the Indel similarity (similar to the Levenshtein distance but only allows for Insertions / Deletions)

This leads to different results depending on the version in use. RapidFuzz always uses the Indel similarity both in the pure Python fallback implementation and the C++ based implementation to provide consistent matching results.

partial_ratio implementation

fuzzywuzzy searches for the optimal matching substring and then calculates the similarity using ratio. This substring is searches using either:

1. difflib.SequenceMatcher.get_matching_blocks (based on Ratcliff and Obershelp algorithm)
2. Levenshtein.matching_blocks (backtracks Levenshtein matrix)

This implementation has a couple of issues:

1. in the pure Python implementation the automatic junk heuristic of difflib is not deactivated. This heuristic improves the performance for long strings, but can lead to completely incorrect results.
2. the accelerated version backtracks the Levenshtein matrix to find the same alignment found by the Python implementation. However the algorithm just uses one of multiple optimal alignment. There is no guarantee for this alignment to include the longest common substring.
3. the optimal substring is assumed to start at one of these matching_blocks. However this is not guaranteed.

RapidFuzz uses a sliding window approach (with some optimizations to skip impossible alignments) to find the optimal alignment. This approach is guaranteed to find the optimal alignment.

differences in preprocessing

fuzzywuzzy provides the function utils.full_process to preprocess strings. This function is called utils.default_process in RapidFuzz. It behaves similar with the only exception that it does not provide the optional argument force_ascii which removes any non ascii characters from a string.

differences in scorers

fuzzywuzzy has the following scorers which preprocess strings by default:

• fuzz.token_sort_ratio
• fuzz.token_set_ratio
• fuzz.partial_token_sort_ratio
• fuzz.partial_token_set_ratio
• fuzz.WRatio
• fuzz.QRatio
• fuzz.UWRatio
• fuzz.UQRatio

With the exception fuzz.UWRatio and fuzz.UQRatio of all have force_ascii enabled forthe peprocessing function by default.

In RapidFuzz no scorer preprocesses strings by default to keep the interface consistent. However a preprocessing function can be provided using the processor argument. In addition the functions fuzz.UWRatio and fuzz.UQRatio do not exist, since they are the same as fuzz.WRatio / fuzz.QRatio with force_ascii disabled. Since in RapidFuzz the force_ascii argument does not exist these functions do not provide any value.

differences in processor functions

In fuzzywuzzy the process module includes the following functions:

• extractWithoutOrder (generator over unsorted results)
• extract (find the N best matches in a sorted list)
• extractBests (same as extract but with an addition score_cutoff parameter to filter bad matches)
• extractOne (find best match)
• dedupe (deduplicate list)

In RapidFuzz these functions are sometimes available under different names:

• extractWithoutOrder is called extract_iter
• extract / extractBests are a single function called extract which povides the optional score_cutoff argument
• extractOne is available under the same name
• dedupe is not available

In addition these functions do not preprocess strings by default. However preprocessing can be enabled using the processor argument.