GeezerVison

I think "may be safe" doesn't quite convey what we want here. We don't want people to be in doubt about whether it's safe from the interpreter's point of view. Maybe something along the lines of "it is guaranteed that the current code owns the only reference to the object"?

It's probably also worth mentioning why a refcount of 1 isn't enough to guarantee it's a unique temporary, something about the interpreter borrowing references internally, similar to the whatsnew entry.

I think this just demonstrates that _PyObject_IsUniquelyReferenced is badly named, otherwise we wouldn't need a new function.

We need to check that the following are true:

• The object has an explicit (not borrowed) reference count of 1
• It is mortal
• It does not support deferred reclamation.

I think _PyObject_IsUniquelyReferenced does that, but it isn't clear from the name.

Let's discuss the name for _PyObject_IsUniquelyReferenced in #133144

The fallout of this is a bit wider than the need for this function, e.g. the Pandas check that broke was looking at if sys.refcount(obj) <= 3. There were also some NumPy and nanobind tests that failed because the absolute values of reference counts changed.

https://github.com/pandas-dev/pandas/blob/main/pandas/core/frame.py#L4156-L4161

(c.f. pandas-dev/pandas#61368).

I'm actually not totally sure why Pandas was checking for <= 3 in particular and if there's a way for them to implement that check in pure Python still.

In NumPy we switched all the refcount tests to check changes in refcounts before and after an operation rather than absolute refcount values. That works across Python versions.

Maybe a separate paragraph advising against using the absolute values of reference counts in tests or runtime sanity checks? Could be a followup too.

Yeah, I think we should do another pass over this and the Py_REFCNT docs after we add PyUnstable_Object_IsUniquelyReferenced in #133144

👌