Add PyUnstable_Object_IsUniquelyReferenced

[ngoldbaum]

Adds a shim for PyUnstable_Object_IsUniquelyReferenced and a test for the shim.

I'd like to use this function in a few libraries but don't want to have to have a thread-unsafe check in 3.13 or add new uses of internal headers outside of the compat header here.

I'm not sure whether the using stuff from internal headers is ok in a shim like this. I'm also not sure if you want to avoid PyUnstable functions in the compat headers.

The implementation is copy/pasted from the implementation of _PyObject_IsUniquelyReferenced.

[vstinner]

Can you please rebase your PR on the updated main branch to get tests on Free Threaded builds?

[vstinner]

The function doesn't make sense on PyPy?

[ngoldbaum]

Apparently not, maybe an interned string? I rewrote it to use an empty tuple and that seems to work on PyPy.

[ngoldbaum]

I rewrote it to use an empty tuple and that seems to work on PyPy.

but that seems to have broken other builds, let me see if I can get it working everywhere...

[vstinner]

Tests fail on Python 2:

python2.7: test_pythoncapi_compat_cext.c:1983: test_uniquely_referenced: Assertion `PyUnstable_Object_IsUniquelyReferenced(obj)' failed.

[ngoldbaum]

Tests fail on Python 2

I guess empty tuples have had reference counting optimizations for a long time!

[vstinner]

Please update also the doc:

• docs/changelog.rst
• docs/api.rst

[vstinner]

Merged, thanks for your contribution.

I'm not very excited by adding PyUnstable functions to pythoncapi-compat, but I'm fine with this specific function.