New in version 2.1.
The weakref module allows the Python programmer to create
weak references to objects.
XXX -- need to say more here!
Not all objects can be weakly referenced; those objects which do
include class instances, functions written in Python (but not in C),
and methods (both bound and unbound). Extension types can easily
be made to support weak references; see section 3.3.3,
``Weak References in Extension Types,'' for more information.
- ref(object[, callback])
Return a weak reference to object. If callback is
provided, it will be called when the object is about to be
finalized; the weak reference object will be passed as the only
parameter to the callback; the referent will no longer be available.
The original object can be retrieved by calling the reference
object, if the referent is still alive.
It is allowable for many weak references to be constructed for the
same object. Callbacks registered for each weak reference will be
called from the most recently registered callback to the oldest
Exceptions raised by the callback will be noted on the standard
error output, but cannot be propagated; they are handled in exactly
the same way as exceptions raised from an object's
Weak references are hashable if the object is hashable. They
will maintain their hash value even after the object was
deleted. If hash() is called the first time only after
the object was deleted, the call will raise
Weak references support test for equality, but not ordering. If the
object is still alive, to references are equal if the objects
are equal (regardless of the callback). If the object
has been deleted, they are equal iff they are identical.
- proxy(object[, callback])
Return a proxy to object which uses a weak reference. This
supports use of the proxy in most contexts instead of requiring the
explicit dereferencing used with weak reference objects. The
returned object will have a type of either
CallableProxyType, depending on whether object is
callable. Proxy objects are not hashable regardless of the
referent; this avoids a number of problems related to their
fundamentally mutable nature, and prevent their use as dictionary
keys. callback is the same as the parameter of the same name
to the ref() function.
Return the number of weak references and proxies which refer to
Return a list of all weak reference and proxy objects which refer to
- class WeakKeyDictionary([dict])
Mapping class that references keys weakly. Entries in the
dictionary will be discarded when there is no longer a strong
reference to the key. This can be used to associate additional data
with an object owned by other parts of an application without adding
attributes to those objects. This can be especially useful with
objects that override attribute accesses.
- class WeakValueDictionary([dict])
Mapping class that references values weakly. Entries in the
dictionary will be discarded when no strong reference to the value
The type object for weak references objects.
The type object for proxies of objects which are not callable.
The type object for proxies of callable objects.
Sequence containing all the type objects for proxies. This can make
it simpler to test if an object is a proxy without being dependent
on naming both proxy types.
- exception ReferenceError
Exception raised when a proxy object is used but the underlying
object has been collected.
- PEP 0205, Weak References
- The proposal and rationale for this
feature, including links to earlier implementations
and information about similar features in other
See About this document... for information on suggesting changes.