path: root/devdocs/python~3.12/c-api%2Fweakref.html

 <span id="weakrefobjects"></span><h1>Weak Reference Objects</h1> <p>Python supports <em>weak references</em> 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.</p> <dl class="c function"> <dt class="sig sig-object c" id="c.PyWeakref_Check">
<code>int PyWeakref_Check(PyObject *ob)</code> </dt> <dd>
<p>Return true if <em>ob</em> is either a reference or proxy object. This function always succeeds.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyWeakref_CheckRef">
<code>int PyWeakref_CheckRef(PyObject *ob)</code> </dt> <dd>
<p>Return true if <em>ob</em> is a reference object. This function always succeeds.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyWeakref_CheckProxy">
<code>int PyWeakref_CheckProxy(PyObject *ob)</code> </dt> <dd>
<p>Return true if <em>ob</em> is a proxy object. This function always succeeds.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyWeakref_NewRef">
<code>PyObject *PyWeakref_NewRef(PyObject *ob, PyObject *callback)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return a weak reference object for the object <em>ob</em>. 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, <em>callback</em>, can be a callable object that receives notification when <em>ob</em> is garbage collected; it should accept a single parameter, which will be the weak reference object itself. <em>callback</em> may also be <code>None</code> or <code>NULL</code>. If <em>ob</em> is not a weakly referencable object, or if <em>callback</em> is not callable, <code>None</code>, or <code>NULL</code>, this will return <code>NULL</code> and raise <a class="reference internal" href="../library/exceptions#TypeError" title="TypeError"><code>TypeError</code></a>.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyWeakref_NewProxy">
<code>PyObject *PyWeakref_NewProxy(PyObject *ob, PyObject *callback)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return a weak reference proxy object for the object <em>ob</em>. 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, <em>callback</em>, can be a callable object that receives notification when <em>ob</em> is garbage collected; it should accept a single parameter, which will be the weak reference object itself. <em>callback</em> may also be <code>None</code> or <code>NULL</code>. If <em>ob</em> is not a weakly referencable object, or if <em>callback</em> is not callable, <code>None</code>, or <code>NULL</code>, this will return <code>NULL</code> and raise <a class="reference internal" href="../library/exceptions#TypeError" title="TypeError"><code>TypeError</code></a>.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyWeakref_GetObject">
<code>PyObject *PyWeakref_GetObject(PyObject *ref)</code> </dt> <dd>
<em class="refcount">Return value: Borrowed reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return the referenced object from a weak reference, <em>ref</em>. If the referent is no longer live, returns <code>Py_None</code>.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>This function returns a <a class="reference internal" href="../glossary#term-borrowed-reference"><span class="xref std std-term">borrowed reference</span></a> to the referenced object. This means that you should always call <a class="reference internal" href="refcounting#c.Py_INCREF" title="Py_INCREF"><code>Py_INCREF()</code></a> on the object except when it cannot be destroyed before the last usage of the borrowed reference.</p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyWeakref_GET_OBJECT">
<code>PyObject *PyWeakref_GET_OBJECT(PyObject *ref)</code> </dt> <dd>
<em class="refcount">Return value: Borrowed reference.</em><p>Similar to <a class="reference internal" href="#c.PyWeakref_GetObject" title="PyWeakref_GetObject"><code>PyWeakref_GetObject()</code></a>, but does no error checking.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_ClearWeakRefs">
<code>void PyObject_ClearWeakRefs(PyObject *object)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>This function is called by the <a class="reference internal" href="typeobj#c.PyTypeObject.tp_dealloc" title="PyTypeObject.tp_dealloc"><code>tp_dealloc</code></a> handler to clear weak references.</p> <p>This iterates through the weak references for <em>object</em> and calls callbacks for those references which have one. It returns when all callbacks have been attempted.</p> </dd>
</dl> <div class="_attribution">
  <p class="_attribution-p">
    &copy; 2001&ndash;2023 Python Software Foundation<br>Licensed under the PSF License.<br>
    <a href="https://docs.python.org/3.12/c-api/weakref.html" class="_attribution-link">https://docs.python.org/3.12/c-api/weakref.html</a>
  </p>
</div>