:mod:weakref -- Python object lifetime management

.. module:: weakref :synopsis: Create weak references to Python objects

|see_cpython_module| :mod:python:weakref.

This module allows creation of weak references to Python objects. A weak reference is a non-traceable reference to a heap-allocated Python object, so the garbage collector can still reclaim the object even though the weak reference refers to it.

Python callbacks can be registered to be called when an object is reclaimed by the garbage collector. This provides a safe way to clean up when objects are no longer needed.

Availability: the weakref module requires MICROPY_PY_WEAKREF to be enabled at compile time. It is enabled on the unix coverage variant and the webassembly pyscript variant.

ref objects

A ref object is the simplest way to make a weak reference.

.. class:: ref(object [, callback], /)

Return a weak reference to the given object.

If callback is given and is not None then, when object is reclaimed by the garbage collector and if the weak reference object is still alive, the callback will be called. The callback will be passed the weak reference object as its single argument.

.. method:: ref.call()

Calling the weak reference object will return its referenced object if that object is still alive. Otherwise None will be returned.

finalize objects

A finalize object is an extended version of a ref object that is more convenient to use, and allows more control over the callback.

.. class:: finalize(object, callback, /, *args, **kwargs)

Return a weak reference to the given object. In contrast to weakref.ref objects, finalize objects are held onto internally and will not be collected until object is collected.

A finalize object starts off alive. It transitions to the dead state when the finalize object is called, either explicitly or when object is collected. It also transitions to dead if the finalize.detach() method is called.

When object is reclaimed by the garbage collector (or the finalize object is explicitly called by user code) and the finalize object is still in the alive state, the callback will be called. The callback will be passed arguments as: callback(*args, **kwargs).

.. method:: finalize.call()

If the finalize object is alive then it transitions to the dead state and returns the value of callback(*args, **kwargs). Otherwise None will be returned.

.. method:: finalize.alive

Read-only boolean attribute that indicates if the finalizer is in the alive state.

.. method:: finalize.peek()

If the finalize object is alive then return (object, callback, args, kwargs). Otherwise return None.

.. method:: finalize.detach()

If the finalize object is alive then it transitions to the dead state and returns (object, callback, args, kwargs). Otherwise None will be returned.