: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.