Confused between Python::attach and Python::try_attach

[WSH032]

Hi, I'm confused about the docs for Python::attach in pyo3 v0.26. The docs mention that it will panic if:

in the middle of GC traversal

So, when should we use Python::attach and when should we use Python::try_attach?

I'm not sure if I understand correctly: in free-threaded Python, multiple threads can execute in parallel. If one thread calls Python::attach, isn't it always possible that another thread is currently performing GC traversal? Does this mean that migrating from Python::with_gil in 0.25 to Python::attach could result in uncontrolled, random panics?

If that's the case, even if we migrate from Python::with_gil to Python::try_attach, what should we do when try_attach returns None? Should we just poll try_attach again?

Thanks!

[Icxolu]

Python::attach is exactly the same as Python::with_gil. It was just renamed. The implementation did not change and this panic condition was there before as well, it just was not documented on with_gil it self, but only in the guide. So there will not be any new panics by migrating here. What we mean by "in the middle of GC traversal" is calling attach within __traverse__ (directly or indirectly).

[WSH032]

Thanks!

I would find it clearer if the documentation were changed to:

- If the middle of GC traversal.
+ If current thread is currently in the middle of a GC traversal (e.g., called from within a `__traverse__` method).