spaCy integration

[kwhumphreys]

I'm attempting to use rapidfuzz directly in spaCy explosion/spaCy#11359 but am calling Python functions from Cython, requiring with gil.
Is there any way to call rapidfuzz Cython functions directly, to avoid the need to convert Python objects?

(#202 mentions [the](https://github.com/maxbachmann/rapidfuzz_capi but I wasn't able to find any docs on using it)

[maxbachmann]

Wow it is super cool to see some use of the C-API. I never got around to write docs for it, but it is not hard to use. Similar to numpy this package provides you with an include path for headers/cython files you need to specify when building.

import rapidfuzz
rapidfuzz.get_include()

The general concept of the API is that each function has an attribute which includes a pycapsule with all relevant function pointers.
The API can be used in the following way:

1. retrieve all relevant function pointers using fuzz.ratio._RF_Scorer which is a struct of type RF_Scorer:

ctypedef struct RF_Scorer:
        uint32_t version                         
        RF_KwargsInit kwargs_init
        RF_GetScorerFlags get_scorer_flags
        RF_ScorerFuncInit scorer_func_init

2. check that version is set to SCORER_STRUCT_VERSION to make sure that nobody has a version of rapidfuzz with an incompatible c-api version installed. I only break this as infrequently as possible and only on major releases. E.g. the addition of simd might need a breaking change at some point
3. prepare keyword arguments passed into scorer using the kwargs_init function. This is useful for functions like the Levenshtein distance which allows you to specify the weights. You can skip this step, since fuzz.ratio does not has any keyword arguments.
4. get scorer flags tells you some general information about the function like the best possible score and the worst. This is useful for generic programming, but you already know this, since you always use fuzz.ratio
5. steps 1-4 require the gil, but you can do them at the module level, or do not need them in your case.
6. convert your strings to RF_String. This is a very simple abstraction over a character buffer:

    ctypedef struct RF_String:
        void (*dtor) (RF_String*) nogil

        RF_StringType kind
        void* data
        int64_t length
        void* context

In your case it should be enough to set kind/data/length. context and dtor can be used in whichever way you see them fit belong to the preprocessor function which converts from the Python object to the RF_String and can be used e.g. to store a PyObject which needs to be decrefed later. They are not accessed by the scorer.
E.g. for Python strings you can just store the pointer to the internal buffer (see https://github.com/maxbachmann/RapidFuzz/blob/dcf67467677a89a8613c65956a5aadc073c918a2/src/rapidfuzz/cpp_common.hpp#L291)
7) call the scorer init function and then call the scorer. This is splitted, so one string can be compared to multiple strings.

RF_ScorerFunc scorer_func;
bool res = scorer->scorer_func_init(&scorer_func, NULL, 1, &string1)
if (res == false)
    -> raise Python exception. This is done automatically in Cython due to `except False`

// call scorer 
double score;
bool res =  scorer_func-> call.f64(&scorer_func, string2, 1, fuzzy (score_cutoff), &score)
if (res == false)
    -> raise Python exception. This is done automatically in Cython due to `except False`

// free resources
scorer_func-dtor(&scorer_func)

I do use this api myself for the implementation of the process module, so you can find my own usage in https://github.com/maxbachmann/RapidFuzz/blob/main/src/rapidfuzz/process_cpp.pyx.

I hope this helped to give a general overview of the API. I you have any additional questions feel free to ask :). In addition I am happy to help with the PR review in spacy.

[kwhumphreys]

Thanks for the overview, Max, but I think this might be beyond me right now. My cpp is rusty and I have never used Cython before.
What would be the expected performance improvement of using the capi and avoiding the need for the gil?

[maxbachmann]

I think call overhead should be around 100ns for each string comparision. How bad this is largely depends on the string lengths your working with. I can write a quick implementation using the C-API for your PR. Do you have a simple benchmark I can run to test the performance of the feature?

[kwhumphreys]

Thanks Max. I'll add some larger scale unit tests to my PR, to use for benchmarking.
I'm currently working on more flexible ways to specify where fuzzy matching should be applied in spaCy patterns, to respond to feedback from the spaCy maintainers.

[maxbachmann]

👍 just let me know when you are at a point, where I can help