Document Cython's freethreading_compatible directive

[lysnikolaou]

No description provided.

[rgommers]

Thanks @lysnikolaou! A few suggested tweaks

[lysnikolaou]

Thanks for the review @rgommers! Feedback addressed.

[ngoldbaum]

Here's some example code to do this via build configuration with setuptools and meson:

compiler_directives = {'freethreading_compatible': True}

setup(
    ext_modules=cythonize(
        extensions,
        compiler_directives=compiler_directives)
)

cython_args = []
if cy.version().version_compare('>=3.1.0')
  cython_args += ['-Xfreethreading_compatible=True']
endif

Meson compiler versions don't include alpha or beta qualifiers, so no need to check that for cython.

For the setuptools one, you could note that you can use e.g. packaging.version to check for a minimum Cython version.

[rgommers]

I like the idea of including example build config code - that'll definitely be helpful for users.

The Meson code should include an extension_module call as well I think, something like:

py.extension_module('modulename'
    'source.pyx',
    cython_args: cython_args,
    ...
)

Even nicer if we had a CMake/scikit-build-core version of it as well. Maybe @henryiii could suggest an idiomatic snippet?

[lysnikolaou]

Thanks both for the suggestions! I added setuptools and Meson examples, but I don't know enough about CMake/scikit-build-core to do that as well.

[rgommers]

Re scikit-build-core, I think this is a good example: https://github.com/scikit-build/scikit-build-sample-projects/tree/main/projects/hello-free-threading (or the hello-cython next to it). However, it doesn't have the code yet to mark extension modules as compatible and I'm not sure what the idiomatic way to do it is, so let's do this as a follow-up.

[henryiii]

This will be better once we finish scikit-build/cython-cmake#19. Will try to do that this week and then update here.

[rgommers]

Almost there!

[rgommers]

Merged, thanks @lysnikolaou and @ngoldbaum.