Weak Reference Objects

Python supports weak references as first-class objects. There are two specific object types which directly implement weak references. The first is a simple reference object, and the second acts as a proxy for the original object as much as it can.

int PyWeakref_Check(PyObject *ob)

Return non-zero if ob is either a reference or proxy object. This function always succeeds.

int PyWeakref_CheckRef(PyObject *ob)

Return non-zero if ob is a reference object or a subclass of the reference type. This function always succeeds.

int PyWeakref_CheckRefExact(PyObject *ob)

Return non-zero if ob is a reference object, but not a subclass of the reference type. This function always succeeds.

int PyWeakref_CheckProxy(PyObject *ob)

Return non-zero if ob is a proxy object. This function always succeeds.

PyObject *PyWeakref_NewRef(PyObject *ob, PyObject *callback)
Return value: New reference. Part of the Stable ABI.

Return a weak reference object for the object ob. This will always return a new reference, but is not guaranteed to create a new object; an existing reference object may be returned. The second parameter, callback, can be a callable object that receives notification when ob is garbage collected; it should accept a single parameter, which will be the weak reference object itself. callback may also be None or NULL. If ob is not a weakly referenceable object, or if callback is not callable, None, or NULL, this will raise TypeError and return NULL.

Changed in version 3.16: Raise TypeError if callback is not callable, None, or NULL.

See also

PyType_SUPPORTS_WEAKREFS() for checking if ob is weakly referenceable.

PyObject *PyWeakref_NewProxy(PyObject *ob, PyObject *callback)
Return value: New reference. Part of the Stable ABI.

Return a weak reference proxy object for the object ob. This will always return a new reference, but is not guaranteed to create a new object; an existing proxy object may be returned. The second parameter, callback, can be a callable object that receives notification when ob is garbage collected; it should accept a single parameter, which will be the weak reference object itself. callback may also be None or NULL. If ob is not a weakly referenceable object, or if callback is not callable, NULL, this will raise TypeError and return NULL.

Changed in version 3.16: Raise TypeError if callback is not callable, None, or NULL.

See also

PyType_SUPPORTS_WEAKREFS() for checking if ob is weakly referenceable.

int PyWeakref_GetRef(PyObject *ref, PyObject **pobj)
Part of the Stable ABI since version 3.13.

Get a strong reference to the referenced object from a weak reference, ref, into *pobj.

  • On success, set *pobj to a new strong reference to the referenced object and return 1.

  • If the reference is dead, set *pobj to NULL and return 0.

  • On error, raise an exception and return -1.

Added in version 3.13.

int PyWeakref_IsDead(PyObject *ref)

Test if the weak reference ref is dead. Returns 1 if the reference is dead, 0 if it is alive, and -1 with an error set if ref is not a weak reference object.

Added in version 3.14.