| .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org> |
| |
| |
| .. versionadded:: 2.1 |
| |
| The :mod:`weakref` module allows the Python programmer to create :dfn:`weak |
| references` to objects. |
| |
n | .. % When making changes to the examples in this file, be sure to update |
n | .. When making changes to the examples in this file, be sure to update |
| .. % Lib/test/test_weakref.py::libreftest too! |
| Lib/test/test_weakref.py::libreftest too! |
| |
| In the following, the term :dfn:`referent` means the object which is referred to |
| by a weak reference. |
| |
| A weak reference to an object is not enough to keep the object alive: when the |
n | only remaining references to a referent are weak references, garbage collection |
n | only remaining references to a referent are weak references, |
| is free to destroy the referent and reuse its memory for something else. A |
| :term:`garbage collection` is free to destroy the referent and reuse its memory |
| primary use for weak references is to implement caches or mappings holding large |
| for something else. A primary use for weak references is to implement caches or |
| objects, where it's desired that a large object not be kept alive solely because |
| mappings holding large objects, where it's desired that a large object not be |
| it appears in a cache or mapping. For example, if you have a number of large |
| kept alive solely because it appears in a cache or mapping. |
| binary image objects, you may wish to associate a name with each. If you used a |
| |
| Python dictionary to map names to images, or images to names, the image objects |
| For example, if you have a number of large binary image objects, you may wish to |
| would remain alive just because they appeared as values or keys in the |
| associate a name with each. If you used a Python dictionary to map names to |
| images, or images to names, the image objects would remain alive just because |
| they appeared as values or keys in the dictionaries. The |
| dictionaries. The :class:`WeakKeyDictionary` and :class:`WeakValueDictionary` |
| :class:`WeakKeyDictionary` and :class:`WeakValueDictionary` classes supplied by |
| classes supplied by the :mod:`weakref` module are an alternative, using weak |
| the :mod:`weakref` module are an alternative, using weak references to construct |
| references to construct mappings that don't keep objects alive solely because |
| mappings that don't keep objects alive solely because they appear in the mapping |
| they appear in the mapping objects. If, for example, an image object is a value |
| objects. If, for example, an image object is a value in a |
| in a :class:`WeakValueDictionary`, then when the last remaining references to |
| :class:`WeakValueDictionary`, then when the last remaining references to that |
| that image object are the weak references held by weak mappings, garbage |
| image object are the weak references held by weak mappings, garbage collection |
| collection can reclaim the object, and its corresponding entries in weak |
| can reclaim the object, and its corresponding entries in weak mappings are |
| mappings are simply deleted. |
| simply deleted. |
| |
| :class:`WeakKeyDictionary` and :class:`WeakValueDictionary` use weak references |
| in their implementation, setting up callback functions on the weak references |
| that notify the weak dictionaries when a key or value has been reclaimed by |
| garbage collection. Most programs should find that using one of these weak |
| dictionary types is all they need -- it's not usually necessary to create your |
| own weak references directly. The low-level machinery used by the weak |
| dictionary implementations is exposed by the :mod:`weakref` module for the |
| benefit of advanced uses. |
| |
n | .. note:: |
| |
| Weak references to an object are cleared before the object's :meth:`__del__` |
| is called, to ensure that the weak reference callback (if any) finds the |
| object still alive. |
| |
| Not all objects can be weakly referenced; those objects which can include class |
| instances, functions written in Python (but not in C), methods (both bound and |
n | unbound), sets, frozensets, file objects, generators, type objects, DBcursor |
n | unbound), sets, frozensets, file objects, :term:`generator`\s, type objects, |
| objects from the :mod:`bsddb` module, sockets, arrays, deques, and regular |
| :class:`DBcursor` objects from the :mod:`bsddb` module, sockets, arrays, deques, |
| expression pattern objects. |
| and regular expression pattern objects. |
| |
| .. versionchanged:: 2.4 |
| Added support for files, sockets, arrays, and patterns. |
| |
| Several builtin types such as :class:`list` and :class:`dict` do not directly |
| support weak references but can add support through subclassing:: |
| |
| class Dict(dict): |
| pass |
| |
n | obj = Dict(red=1, green=2, blue=3) # this object is weak referencable |
n | obj = Dict(red=1, green=2, blue=3) # this object is weak referenceable |
| |
n | Extension types can easily be made to support weak references; see "Weak |
n | Extension types can easily be made to support weak references; see |
| Reference Support (XXX reference: ../ext/weakref-support.html)" in Extending and |
| :ref:`weakref-support`. |
| Embedding the Python Interpreter (XXX reference: ../ext/ext.html). |
| |
| .. % The referenced section used to appear in this document with the |
| .. % \label weakref-extension. It would be good to be able to generate a |
| .. % redirect for the corresponding HTML page (weakref-extension.html) |
| .. % for on-line versions of this document. |
| |
| |
| .. class:: ref(object[, callback]) |
| |
| Return a weak reference to *object*. The original object can be retrieved by |
| calling the reference object if the referent is still alive; if the referent is |
| no longer alive, calling the reference object will cause :const:`None` to be |
| returned. If *callback* is provided and not :const:`None`, and the returned |
| 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. |
| |
| .. note:: |
| |
n | Caution: Because a :class:`WeakKeyDictionary` is built on top of a Python |
n | Caution: Because a :class:`WeakKeyDictionary` is built on top of a Python |
| dictionary, it must not change size when iterating over it. This can be |
n | difficult to ensure for a :class:`WeakKeyDictionary` because actions performed |
n | difficult to ensure for a :class:`WeakKeyDictionary` because actions |
| by the program during iteration may cause items in the dictionary to vanish "by |
| performed by the program during iteration may cause items in the |
| magic" (as a side effect of garbage collection). |
| dictionary to vanish "by magic" (as a side effect of garbage collection). |
| |
| :class:`WeakKeyDictionary` objects have the following additional methods. These |
| expose the internal references directly. The references are not guaranteed to |
| be "live" at the time they are used, so the result of calling the references |
| needs to be checked before being used. This can be used to avoid creating |
| references that will cause the garbage collector to keep the keys around longer |
| than needed. |
| |
| |
| .. method:: WeakKeyDictionary.iterkeyrefs() |
| |
n | Return an iterator that yields the weak references to the keys. |
n | Return an :term:`iterator` that yields the weak references to the keys. |
| |
| .. versionadded:: 2.5 |
| |
| |
| .. method:: WeakKeyDictionary.keyrefs() |
| |
| Return a list of weak references to the keys. |
| |