Add support for free threaded Python

[maxbachmann]

Look into what's required to support the free threaded Python build.

[henryiii]

See https://py-free-threading.github.io for some info on free-threaded support.

[ngoldbaum]

As of May 2025, seems to build successfully:

goldbaum at Nathans-MacBook-Pro in ~/Documents/
± pip install rapidfuzz
Collecting rapidfuzz
  Downloading rapidfuzz-3.13.0.tar.gz (57.9 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 57.9/57.9 MB 1.3 MB/s eta 0:00:00
  Installing build dependencies ... done
  Getting requirements to build wheel ... done
  Preparing metadata (pyproject.toml) ... done
Building wheels for collected packages: rapidfuzz
  Building wheel for rapidfuzz (pyproject.toml) ... done
  Created wheel for rapidfuzz: filename=rapidfuzz-3.13.0-py3-none-any.whl size=64298 sha256=5506d371575899ad28c4f77cca7dfd2fd8d73921f70967017110b236f9818732
  Stored in directory: /Users/goldbaum/Library/Caches/pip/wheels/f9/ce/39/de6c257a8d74a23d756e9dc70ec28bac819fba1bf45ac2052d
Successfully built rapidfuzz
Installing collected packages: rapidfuzz
Successfully installed rapidfuzz-3.13.0

[notice] A new release of pip is available: 25.0.1 -> 25.1.1
[notice] To update, run: pip install --upgrade pip

goldbaum at Nathans-MacBook-Pro in ~/Documents
± python -VV
Python 3.13.3 experimental free-threading build (main, May 14 2025, 08:53:19) [Clang 17.0.0 (clang-1700.0.13.3)]

[maxbachmann]

Right now it fails to compile. You can see this if you attempt to install in verbose. It simply installs the pure Python fallback version.

Now the compilation is fixed if I upgrade to Cython 3.1. However the module itself is still not marked as thread safe.
The problem there is that I have absolutely no clue what kind of guarantees free threaded Python gives me and which it doesn't. In cases where I have to do manual synchronisation it's not completely clear to me what I should use for the synchronisation.

Really I don't do a ton of things that could be thread unsafe, but there are a couple:

Lazy Pandas Init

pandas_NA = None

def setupPandas():
    global pandas_NA  # noqa: PLW0603
    if pandas_NA is None:
        pandas = sys.modules.get("pandas")
        if hasattr(pandas, "NA"):
            pandas_NA = pandas.NA

is done both in Python and Cython. It's unclear to me whether I need to guard the global read/write. Really I don't care about it being set multiple times as long as the read/write itself behaves in an atomic manner (so reads while the write is happening only either return None or the value, but not garbage or crash)

Reads from input values

In theory a user could e.g. change the length of a list he passes to me while I am using it. Is this something Cpython accepts as an issue of the user? Or am I supposed to guard against this? If I was supposed to guard against this I would need to lock basically everything making free threaded fairly useless. So I assume it's considered as the users responsibility not to do this.

class modifiers + readers

The Editops / Opcodes / ... classes have various functions that modify their members. Without synchronisation it wouldn't be safe to call a modifying function multiple times in parallel or call a function making use of these members while also making use of them. Calling multiple functions that make use of it would be safe.
Until which point is this a classes responsibility to make this thread safe vs the resposibility of the user not to call e.g. multiple functions that modify a class at the same time? If it was the classes responsibility I again couldn't imagine a ton of classes that don't have to take a lock in virtually any method

Again virtually all of those would apply to any pure Python code as well. @henryiii / @ngoldbaum are you aware what the "official" guidelines on these topics are, or what the ecosystem is settling on for them?

[ngoldbaum]

Lazy pandas init

For this you're going to need to use a single-initialization API. We had to do something similar over in ndindex. IMO this pattern should be documented better in the Cython docs (ping @dawoods in case you have any opinions too...) or even have a full-fledged Cython API for it: cython/cython#6826

Be careful using standard library synchronization primitives, since any blocking call can deadlock with the interpreter, so you have to do e.g. with nogil before any possibly blocking call (even on the free-threaded build, the naming is unfortunate...).

Reads from input values

You can take a critical section on the input list, but that isn't bullet-proof because critical sections are suspended whenever a new critical section is entered. That means if you hold a critical section on the input list and call into the CPython C API, there's a chance the lock on the list might be released. This is actually a similar level of protection to what the the GIL provided, so maybe it's "good enough".

I agree it's a weird thing to do. I'm aware of a couple of places in NumPy where you can break things if you mutate inputs while NumPy is processing them. Eventually I'll fix them but it's a low priority.

class modifiers + readers

IMO it's perfectly fine for a library to not add synchronization and leave it up to users of the library to add locks if they want to share and mutate a data structure provided by a library.

Adding locking is a trade-off IMO it's a good thing that users can choose to pay the cost of synchronization if they need it.

That said, IMO you should clearly document what thread safety guarantees you would like to provide. I don't know to what extent you already have multithreaded tests, but also it's a good idea to add tests for the kind of multithreaded workflows you'd like to support.

[da-woods]

@ngoldbaum - my username has a - in it so I think you pinged the wrong person. Hopefully they know about freethreading ;)

Lazy Pandas Init

If pandas_NA is not cdef then should be OK in both Python and Cython because it's set in a Python dictionary. If it's cdef then you should probably lock on something - the pattern Nathan's linked to is reasonable.

lists and changing the length

From both a Python and Cython point of view this is "shouldn't crash but may be inconsistent". Probably isn't worth worrying about too much (at least initially)

IMO it's perfectly fine for a library to not add synchronization and leave it up to users of the library to add locks if they want to share and mutate a data structure provided by a library.

Agree with this. Based on a very quick skim-read of your docs that's probably what I'd do in your place. It seems reasonable that you want multiple threads to use your library independent but they probably should have their own copy of all the objects involved.

[ngoldbaum]

Ugh, sorry other random person 🙃

[da-woods]

@maxbachmann In your place, here's what I'd do:

1. Fix anything obvious and global like your lazy Panda's init (copying Nathan's approach is probably the easiest way to do it).
2. Update the documentation to explain that it's experimental and explain the assumptions you're making (e.g. RapidFuzz objects should be accessed from one thread at once, don't modify data that's actively being worked on, use multiple threads for multiple operations).
3. Turn on the freethreading_compatible flag in Cython (assuming everything else works with otherwise Cython 3.1; if not please report the regressions...)
4. See if anyone reports any bugs
5. Turn on parallel tests on pytest (if you use that). That's mostly just show up any hidden global state that you've forgotten about but it's likely still useful.