[HaukurPall]

What is the problem?

Icegrams didn't build on free-threaded Python. Its supported versions and wheels had also drifted from mideind/BinPackage:

• it still supported Python 3.9;
• CI didn't test Python 3.15;
• it had no PyPy 7.3, PyPy 3.12 or Linux aarch64 wheels.

What is the solution?

• Free-threaded builds: free-threaded CPython gets a regular extension, since it has no abi3. cffi 2.x keeps the GIL off.
• Tests: a new test_threads.py has threads query one Ngrams and compares the results with serial ones: 8 threads over all queries on free-threaded Python, 2 threads with half the queries each when the GIL is on.
• -O2 safeguard: trie.cpp is built with -O2 when the interpreter records no optimization level. Gentoo's Python records none, so trie.cpp ran at -O0, 2.6× slower.
• Versions, the same as BinPackage:
  • Python 3.10+, with a cp310-abi3 wheel. Python 3.9 has been end of life since October 2025.
  • cffi>=2.0.0, declared in pyproject.toml only: setup.py keeps just what pyproject can't express (cffi_modules, zip_safe, the abi3 option).
  • The Free Threading classifier and the 3.15 classifier.
  • A CI matrix of 3.10–3.15, 3.14t, 3.15t, and PyPy 3.11 and 3.12. The free-threaded jobs also run every test in 8 threads at once.
• Wheels, the same as BinPackage:
  • cibuildwheel is pinned.
  • New cp314t, cp315t, PyPy 7.3 (pp73), PyPy 3.12 and Linux aarch64 wheels.
  • Every wheel is checked to import, and to keep the GIL off on free-threaded Python.
  • A last step checks that every expected wheel was built.
• close(): on CPython it no longer fails halfway with BufferError when a query in another thread still holds the memory map; the map is unmapped when that query is done. PyPy unmaps at close() regardless, so close() must still be called only when no other thread uses the instance.
• CI: pushes are tested on master only (other branches through their pull requests, so jobs no longer run twice), and ruff runs once, in the 3.10 job.
• Docs:
  • An Ngrams can be shared by threads. Call close() only when no other thread is using it.
  • With the GIL, use processes rather than threads for parallel queries. cffi releases the GIL around every C call, so 8 busy threads take 25 times as long as one.
  • The Prerequisites section lists the platforms that get wheels.
  • A 2.1.0 changelog entry, marked unreleased.

No locks were needed. The C++ trie only reads the memory map, and the one lazily computed value is computed the same way by any thread.

How was this tested?

• CI: all jobs pass, including 3.14t and 3.15t serially and in 8 threads.
• Wheels: a dry run of wheels.yml on the test tag 2.1.0-test1 built all 30 expected wheels (6 kinds × Linux x86_64 and aarch64, macOS x86_64 and arm64, Windows), and each passed its import and GIL test. The publish job was skipped. The Linux x86_64 build was also reproduced locally with the same cibuildwheel versions.
• Locally: the suite passes on 3.10, 3.14, 3.14t, 3.15t and PyPy 3.12. setup.py builds the same sdist and wheel contents as before.
• Thread test: caught a deliberately planted race in 5 out of 5 runs. A new test reproduces the close() failure on CPython without the fix.
• Speed: trigram logprob on real text, 8 threads sharing one Ngrams on 3.14t, against 8 processes on the GIL build: 139k lookups/s each. One worker does 26k.

The pypi environment now only accepts tags of the form *.*.*, as in BinPackage.

Releasing this should be 2.1.0, since it drops Python 3.9; the version bump and the changelog date come with the release, possibly together with #11. Users on 3.9 keep 2.0.0.

🤖 Generated with Claude Code

[vthorsteinsson]

Reviewed against mideind/BinPackage's free-threading setup; parity confirmed, wheels dry run (2.1.0-test1) green on all platforms. Thanks!