gh-105927: Add PyWeakref_GetRef() function

[vstinner]

• Issue: C API: Add PyWeakref_GetRef() function #105927

---

📚 Documentation preview 📚: https://cpython-previews--105932.org.readthedocs.build/

[vstinner]

Once this PR will be merged, I will create a follow PR to replace PyWeakref_GET_OBJECT() with PyWeakref_GetRef(). I have it locally, but GitHub doesn't let me create a "patch serie".

[encukou]

In new API, please don't return NULL without an exception set.

[vstinner]

It doesn't return NULL with an exception set.

[vstinner]

I changed the API to:

int PyWeakref_GetRef(PyObject *ref, PyObject **pobj) 

I also added tests.

@erlend-aasland@encukou: Please review the updated PR.

[erlend-aasland]

Using an int return aligns error checking with the well-known C idiom of if (fn() < 0){/* err handler */; IMO, that makes for a better API. Thanks!

[vstinner]

@erlend-aasland: I addressed your review.

[erlend-aasland]

@erlend-aasland: I addressed your review.

Thanks! Looks good.

[erlend-aasland]

LGTM; I'm interested in Petr's review, though :)

[erlend-aasland]

2de3897 is in itself a nice docs update that could be backported through 3.11! :)

[encukou]

Thank you! This looks good.

[vstinner]

I dislike "3 states" return value: error, case 1 or case 2. It forces to store the return value in a variable and uses 2 if to cover the 3 code paths.

Also, IMO the API is more error prone since someone may write the wrong test for the error case.

Well, I don't know how much is just m personal taste and what is objective here 😁

I prefer to only return -1 on error, and 0 for the other cases. So I don't need an extra variable.