Add doc content on environment markers and Py_GIL_disabled configvar (

#124)

docs/ci.md

@@ -115,3 +115,16 @@ disabled during tests, at least until you can register that your extension
 modules support disabling the GIL via `Py_mod_gil` and all of your runtime test
 dependencies do the same. See [the porting guide](porting.md) for more
 information about declaring support for free-threaded python in your extension.
+
+!!! info
+    If a dependency of your package does not support free-threading or has not
+    yet done a release which includes `cp313t` wheels, this can be tricky to
+    work around because an environment marker for free-threading does not exist
+    (see [this Discourse thread](https://discuss.python.org/t/environment-marker-for-free-threading/60007)).
+    Hence it is not possible to special-case free-threading with static metadata
+    in `pyproject.toml`. It's fine to still upload `cp313t` wheels for your
+    package to PyPI; the user may then be responsible for getting the
+    dependency installed (e.g., from a nightly wheel or building the
+    dependency's `main` branch from source) if the last release of the
+    dependency doesn't cleanly build from source or doesn't work under
+    free-threading.

docs/running-gil-disabled.md

@@ -17,7 +17,7 @@
     free-threaded binary, that means the free-threaded option was not selected
     during installation.
 
-You can verify your build of CPython itself has the GIL disabled with the
+You can verify if your build of CPython itself has the GIL disabled with the
 following incantation:
 
 ```bash
@@ -30,12 +30,20 @@ If you are using Python 3.13b1 or newer, you should see a message like:
 Python 3.13.0b1+ experimental free-threading build (heads/3.13:d93c4f9, May 21 2024, 10:54:14) [Clang 15.0.0 (clang-1500.1.0.2.5)]
 ```
 
-Verify that the GIL is disabled at runtime with the following incantation:
+To verify whether the GIL is disabled at runtime or not, you can use this in
+your code:
 
-```bash
-python -c "import sys; print(sys._is_gil_enabled())"
+```python
+import sys
+
+sys._is_gil_enabled()
 ```
 
+This will be `True` on the free-threaded build when the GIL is re-enabled at
+runtime, but should be `False` before importing any packages. Note that
+`sys._is_gil_enabled()` is only available on Python 3.13 and newer, you will
+see an `AttributeError` on older Python versions.
+
 To force Python to keep the GIL disabled even after importing a module
 that does not support running without it, use the `PYTHON_GIL` environment
 variable or the `-X gil` command line option:
@@ -45,3 +53,13 @@ variable or the `-X gil` command line option:
 PYTHON_GIL=0 python
 python -Xgil=0
 ```
+
+To check whether the Python interpreter you're using is a free-threaded build,
+irrespective of whether the GIL was re-enabled at runtime or not, you can use
+this within your code:
+
+```python
+import sysconfig
+
+is_freethreaded = bool(sysconfig.get_config_var("Py_GIL_DISABLED"))
+```