Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libweakref.tex @ 39042:c02fa187e0f4 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Part of SF patch #1484695. This removes dead code. The chksum was already verified in .frombuf() on the lines above. If there was a problem an exception is raised, so there was no way this condition could have been true.
author Neal Norwitz <nnorwitz@gmail.com>
date Mon, 10 Jul 2006 00:23:17 +0000
parents 728c16f16267
children 4db9d9533b16
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1 \section{\module{weakref} ---
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
2 Weak references}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
3
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
4 \declaremodule{extension}{weakref}
17414
4c497c5e72ad Include a synopsis for the chapter overview.
Fred Drake <fdrake@acm.org>
parents: 17389
diff changeset
5 \modulesynopsis{Support for weak references and weak dictionaries.}
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
6 \moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
16794
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries
Martin v. Löwis <martin@v.loewis.de>
parents: 16588
diff changeset
7 \moduleauthor{Neil Schemenauer}{nas@arctrix.com}
18348
798b5e6b4915 Correct a markup error for an accented character.
Fred Drake <fdrake@acm.org>
parents: 18223
diff changeset
8 \moduleauthor{Martin von L\"owis}{martin@loewis.home.cs.tu-berlin.de}
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
9 \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
10
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
11 \versionadded{2.1}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
12
35195
7804bbb26492 backport doctest for weakref examples
Georg Brandl <georg@python.org>
parents: 35191
diff changeset
13 % When making changes to the examples in this file, be sure to update
7804bbb26492 backport doctest for weakref examples
Georg Brandl <georg@python.org>
parents: 35191
diff changeset
14 % Lib/test/test_weakref.py::libreftest too!
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
15
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
16 The \module{weakref} module allows the Python programmer to create
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
17 \dfn{weak references} to objects.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
18
30998
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
19 In the following, the term \dfn{referent} means the
20697
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
20 object which is referred to by a weak reference.
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
21
30998
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
22 A weak reference to an object is not enough to keep the object alive:
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
23 when the only remaining references to a referent are weak references,
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
24 garbage collection is free to destroy the referent and reuse its memory
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
25 for something else. A primary use for weak references is to implement
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
26 caches or mappings holding large objects, where it's desired that a
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
27 large object not be kept alive solely because it appears in a cache or
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
28 mapping. For example, if you have a number of large binary image objects,
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
29 you may wish to associate a name with each. If you used a Python
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
30 dictionary to map names to images, or images to names, the image objects
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
31 would remain alive just because they appeared as values or keys in the
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
32 dictionaries. The \class{WeakKeyDictionary} and
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
33 \class{WeakValueDictionary} classes supplied by the \module{weakref}
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
34 module are an alternative, using weak references to construct mappings
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
35 that don't keep objects alive solely because they appear in the mapping
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
36 objects. If, for example, an image object is a value in a
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
37 \class{WeakValueDictionary}, then when the last remaining
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
38 references to that image object are the weak references held by weak
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
39 mappings, garbage collection can reclaim the object, and its corresponding
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
40 entries in weak mappings are simply deleted.
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
41
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
42 \class{WeakKeyDictionary} and \class{WeakValueDictionary} use weak
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
43 references in their implementation, setting up callback functions on
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
44 the weak references that notify the weak dictionaries when a key or value
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
45 has been reclaimed by garbage collection. Most programs should find that
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
46 using one of these weak dictionary types is all they need -- it's
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
47 not usually necessary to create your own weak references directly. The
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
48 low-level machinery used by the weak dictionary implementations is exposed
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
49 by the \module{weakref} module for the benefit of advanced uses.
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
50
29745
32f96bac2113 Grammar nit. SF bug #757822
Raymond Hettinger <python@rcn.com>
parents: 24642
diff changeset
51 Not all objects can be weakly referenced; those objects which can
17173
73f41b0ff777 Update to the most recent weakref changes.
Fred Drake <fdrake@acm.org>
parents: 16794
diff changeset
52 include class instances, functions written in Python (but not in C),
32160
aec9c98a47d2 Add weakref support to sockets and re pattern objects.
Raymond Hettinger <python@rcn.com>
parents: 31452
diff changeset
53 methods (both bound and unbound), sets, frozensets, file objects,
32330
541327cb8f8b Complete the list of weakreferencable objects.
Raymond Hettinger <python@rcn.com>
parents: 32160
diff changeset
54 generators, type objects, DBcursor objects from the \module{bsddb} module,
32160
aec9c98a47d2 Add weakref support to sockets and re pattern objects.
Raymond Hettinger <python@rcn.com>
parents: 31452
diff changeset
55 sockets, arrays, deques, and regular expression pattern objects.
aec9c98a47d2 Add weakref support to sockets and re pattern objects.
Raymond Hettinger <python@rcn.com>
parents: 31452
diff changeset
56 \versionchanged[Added support for files, sockets, arrays, and patterns]{2.4}
aec9c98a47d2 Add weakref support to sockets and re pattern objects.
Raymond Hettinger <python@rcn.com>
parents: 31452
diff changeset
57
aec9c98a47d2 Add weakref support to sockets and re pattern objects.
Raymond Hettinger <python@rcn.com>
parents: 31452
diff changeset
58 Several builtin types such as \class{list} and \class{dict} do not
aec9c98a47d2 Add weakref support to sockets and re pattern objects.
Raymond Hettinger <python@rcn.com>
parents: 31452
diff changeset
59 directly support weak references but can add support through subclassing:
aec9c98a47d2 Add weakref support to sockets and re pattern objects.
Raymond Hettinger <python@rcn.com>
parents: 31452
diff changeset
60
aec9c98a47d2 Add weakref support to sockets and re pattern objects.
Raymond Hettinger <python@rcn.com>
parents: 31452
diff changeset
61 \begin{verbatim}
aec9c98a47d2 Add weakref support to sockets and re pattern objects.
Raymond Hettinger <python@rcn.com>
parents: 31452
diff changeset
62 class Dict(dict):
aec9c98a47d2 Add weakref support to sockets and re pattern objects.
Raymond Hettinger <python@rcn.com>
parents: 31452
diff changeset
63 pass
aec9c98a47d2 Add weakref support to sockets and re pattern objects.
Raymond Hettinger <python@rcn.com>
parents: 31452
diff changeset
64
aec9c98a47d2 Add weakref support to sockets and re pattern objects.
Raymond Hettinger <python@rcn.com>
parents: 31452
diff changeset
65 obj = Dict(red=1, green=2, blue=3) # this object is weak referencable
aec9c98a47d2 Add weakref support to sockets and re pattern objects.
Raymond Hettinger <python@rcn.com>
parents: 31452
diff changeset
66 \end{verbatim}
aec9c98a47d2 Add weakref support to sockets and re pattern objects.
Raymond Hettinger <python@rcn.com>
parents: 31452
diff changeset
67
aec9c98a47d2 Add weakref support to sockets and re pattern objects.
Raymond Hettinger <python@rcn.com>
parents: 31452
diff changeset
68 Extension types can easily be made to support weak references; see section
aec9c98a47d2 Add weakref support to sockets and re pattern objects.
Raymond Hettinger <python@rcn.com>
parents: 31452
diff changeset
69 \ref{weakref-extension}, ``Weak References in Extension Types,'' for more
aec9c98a47d2 Add weakref support to sockets and re pattern objects.
Raymond Hettinger <python@rcn.com>
parents: 31452
diff changeset
70 information.
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
71
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
72
32472
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
73 \begin{classdesc}{ref}{object\optional{, callback}}
20697
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
74 Return a weak reference to \var{object}. The original object can be
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
75 retrieved by calling the reference object if the referent is still
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
76 alive; if the referent is no longer alive, calling the reference
31452
bb7146d117fb minor markup adjustments
Fred Drake <fdrake@acm.org>
parents: 31446
diff changeset
77 object will cause \constant{None} to be returned. If \var{callback} is
36154
963a98d8fe2e SF patch #1379023: document that a weakref callback is not invoked if the
Armin Rigo <arigo@tunes.org>
parents: 35195
diff changeset
78 provided and not \constant{None}, and the returned weakref object is
963a98d8fe2e SF patch #1379023: document that a weakref callback is not invoked if the
Armin Rigo <arigo@tunes.org>
parents: 35195
diff changeset
79 still alive, the callback will be called when the object is about to be
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
80 finalized; the weak reference object will be passed as the only
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
81 parameter to the callback; the referent will no longer be available.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
82
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
83 It is allowable for many weak references to be constructed for the
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
84 same object. Callbacks registered for each weak reference will be
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
85 called from the most recently registered callback to the oldest
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
86 registered callback.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
87
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
88 Exceptions raised by the callback will be noted on the standard
16588
56a8106baf63 Fix two typos
Andrew M. Kuchling <amk@amk.ca>
parents: 16381
diff changeset
89 error output, but cannot be propagated; they are handled in exactly
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
90 the same way as exceptions raised from an object's
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
91 \method{__del__()} method.
30998
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
92
16794
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries
Martin v. Löwis <martin@v.loewis.de>
parents: 16588
diff changeset
93 Weak references are hashable if the \var{object} is hashable. They
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries
Martin v. Löwis <martin@v.loewis.de>
parents: 16588
diff changeset
94 will maintain their hash value even after the \var{object} was
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries
Martin v. Löwis <martin@v.loewis.de>
parents: 16588
diff changeset
95 deleted. If \function{hash()} is called the first time only after
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries
Martin v. Löwis <martin@v.loewis.de>
parents: 16588
diff changeset
96 the \var{object} was deleted, the call will raise
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries
Martin v. Löwis <martin@v.loewis.de>
parents: 16588
diff changeset
97 \exception{TypeError}.
30998
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
98
20676
ae94b5f7dd30 Minor textual adjustment, and style-guide conformance (no use of "iff").
Fred Drake <fdrake@acm.org>
parents: 20290
diff changeset
99 Weak references support tests for equality, but not ordering. If
20697
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
100 the referents are still alive, two references have the same
21054
bcbda606d8c7 Typo, spotted by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20697
diff changeset
101 equality relationship as their referents (regardless of the
20697
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
102 \var{callback}). If either referent has been deleted, the
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
103 references are equal only if the reference objects are the same
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
104 object.
32472
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
105
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
106 \versionchanged[This is now a subclassable type rather than a
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
107 factory function; it derives from \class{object}]
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
108 {2.4}
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
109 \end{classdesc}
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
110
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
111 \begin{funcdesc}{proxy}{object\optional{, callback}}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
112 Return a proxy to \var{object} which uses a weak reference. This
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
113 supports use of the proxy in most contexts instead of requiring the
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
114 explicit dereferencing used with weak reference objects. The
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
115 returned object will have a type of either \code{ProxyType} or
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
116 \code{CallableProxyType}, depending on whether \var{object} is
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
117 callable. Proxy objects are not hashable regardless of the
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
118 referent; this avoids a number of problems related to their
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
119 fundamentally mutable nature, and prevent their use as dictionary
17768
c1880f6b3189 Fix typo in weakref.proxy() documentation.
Fred Drake <fdrake@acm.org>
parents: 17414
diff changeset
120 keys. \var{callback} is the same as the parameter of the same name
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
121 to the \function{ref()} function.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
122 \end{funcdesc}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
123
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
124 \begin{funcdesc}{getweakrefcount}{object}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
125 Return the number of weak references and proxies which refer to
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
126 \var{object}.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
127 \end{funcdesc}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
128
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
129 \begin{funcdesc}{getweakrefs}{object}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
130 Return a list of all weak reference and proxy objects which refer to
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
131 \var{object}.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
132 \end{funcdesc}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
133
16794
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries
Martin v. Löwis <martin@v.loewis.de>
parents: 16588
diff changeset
134 \begin{classdesc}{WeakKeyDictionary}{\optional{dict}}
17389
471ce0faa775 Remove the mapping() function from the documentation.
Fred Drake <fdrake@acm.org>
parents: 17243
diff changeset
135 Mapping class that references keys weakly. Entries in the
471ce0faa775 Remove the mapping() function from the documentation.
Fred Drake <fdrake@acm.org>
parents: 17243
diff changeset
136 dictionary will be discarded when there is no longer a strong
471ce0faa775 Remove the mapping() function from the documentation.
Fred Drake <fdrake@acm.org>
parents: 17243
diff changeset
137 reference to the key. This can be used to associate additional data
471ce0faa775 Remove the mapping() function from the documentation.
Fred Drake <fdrake@acm.org>
parents: 17243
diff changeset
138 with an object owned by other parts of an application without adding
471ce0faa775 Remove the mapping() function from the documentation.
Fred Drake <fdrake@acm.org>
parents: 17243
diff changeset
139 attributes to those objects. This can be especially useful with
471ce0faa775 Remove the mapping() function from the documentation.
Fred Drake <fdrake@acm.org>
parents: 17243
diff changeset
140 objects that override attribute accesses.
30998
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
141
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
142 \note{Caution: Because a \class{WeakKeyDictionary} is built on top
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
143 of a Python dictionary, it must not change size when iterating
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
144 over it. This can be difficult to ensure for a
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
145 \class{WeakKeyDictionary} because actions performed by the
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
146 program during iteration may cause items in the dictionary
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
147 to vanish "by magic" (as a side effect of garbage collection).}
16794
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries
Martin v. Löwis <martin@v.loewis.de>
parents: 16588
diff changeset
148 \end{classdesc}
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries
Martin v. Löwis <martin@v.loewis.de>
parents: 16588
diff changeset
149
38079
728c16f16267 SF #1479988: add methods to allow access to weakrefs for the
Fred Drake <fdrake@acm.org>
parents: 36154
diff changeset
150 \class{WeakKeyDictionary} objects have the following additional
728c16f16267 SF #1479988: add methods to allow access to weakrefs for the
Fred Drake <fdrake@acm.org>
parents: 36154
diff changeset
151 methods. These expose the internal references directly. The
728c16f16267 SF #1479988: add methods to allow access to weakrefs for the
Fred Drake <fdrake@acm.org>
parents: 36154
diff changeset
152 references are not guaranteed to be ``live'' at the time they are
728c16f16267 SF #1479988: add methods to allow access to weakrefs for the
Fred Drake <fdrake@acm.org>
parents: 36154
diff changeset
153 used, so the result of calling the references needs to be checked
728c16f16267 SF #1479988: add methods to allow access to weakrefs for the
Fred Drake <fdrake@acm.org>
parents: 36154
diff changeset
154 before being used. This can be used to avoid creating references that
728c16f16267 SF #1479988: add methods to allow access to weakrefs for the
Fred Drake <fdrake@acm.org>
parents: 36154
diff changeset
155 will cause the garbage collector to keep the keys around longer than
728c16f16267 SF #1479988: add methods to allow access to weakrefs for the
Fred Drake <fdrake@acm.org>
parents: 36154
diff changeset
156 needed.
728c16f16267 SF #1479988: add methods to allow access to weakrefs for the
Fred Drake <fdrake@acm.org>
parents: 36154
diff changeset
157
728c16f16267 SF #1479988: add methods to allow access to weakrefs for the
Fred Drake <fdrake@acm.org>
parents: 36154
diff changeset
158 \begin{methoddesc}{iterkeyrefs}{}
728c16f16267 SF #1479988: add methods to allow access to weakrefs for the
Fred Drake <fdrake@acm.org>
parents: 36154
diff changeset
159 Return an iterator that yields the weak references to the keys.
728c16f16267 SF #1479988: add methods to allow access to weakrefs for the
Fred Drake <fdrake@acm.org>
parents: 36154
diff changeset
160 \versionadded{2.5}
728c16f16267 SF #1479988: add methods to allow access to weakrefs for the
Fred Drake <fdrake@acm.org>
parents: 36154
diff changeset
161 \end{methoddesc}
728c16f16267 SF #1479988: add methods to allow access to weakrefs for the
Fred Drake <fdrake@acm.org>
parents: 36154
diff changeset
162
728c16f16267 SF #1479988: add methods to allow access to weakrefs for the
Fred Drake <fdrake@acm.org>
parents: 36154
diff changeset
163 \begin{methoddesc}{keyrefs}{}
728c16f16267 SF #1479988: add methods to allow access to weakrefs for the
Fred Drake <fdrake@acm.org>
parents: 36154
diff changeset
164 Return a list of weak references to the keys.
728c16f16267 SF #1479988: add methods to allow access to weakrefs for the
Fred Drake <fdrake@acm.org>
parents: 36154
diff changeset
165 \versionadded{2.5}
728c16f16267 SF #1479988: add methods to allow access to weakrefs for the
Fred Drake <fdrake@acm.org>
parents: 36154
diff changeset
166 \end{methoddesc}
728c16f16267 SF #1479988: add methods to allow access to weakrefs for the
Fred Drake <fdrake@acm.org>
parents: 36154
diff changeset
167
16794
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries
Martin v. Löwis <martin@v.loewis.de>
parents: 16588
diff changeset
168 \begin{classdesc}{WeakValueDictionary}{\optional{dict}}
17389
471ce0faa775 Remove the mapping() function from the documentation.
Fred Drake <fdrake@acm.org>
parents: 17243
diff changeset
169 Mapping class that references values weakly. Entries in the
471ce0faa775 Remove the mapping() function from the documentation.
Fred Drake <fdrake@acm.org>
parents: 17243
diff changeset
170 dictionary will be discarded when no strong reference to the value
20697
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
171 exists any more.
30998
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
172
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
173 \note{Caution: Because a \class{WeakValueDictionary} is built on top
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
174 of a Python dictionary, it must not change size when iterating
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
175 over it. This can be difficult to ensure for a
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
176 \class{WeakValueDictionary} because actions performed by the
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
177 program during iteration may cause items in the dictionary
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
178 to vanish "by magic" (as a side effect of garbage collection).}
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
179 \end{classdesc}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
180
38079
728c16f16267 SF #1479988: add methods to allow access to weakrefs for the
Fred Drake <fdrake@acm.org>
parents: 36154
diff changeset
181 \class{WeakValueDictionary} objects have the following additional
728c16f16267 SF #1479988: add methods to allow access to weakrefs for the
Fred Drake <fdrake@acm.org>
parents: 36154
diff changeset
182 methods. These method have the same issues as the
728c16f16267 SF #1479988: add methods to allow access to weakrefs for the
Fred Drake <fdrake@acm.org>
parents: 36154
diff changeset
183 \method{iterkeyrefs()} and \method{keyrefs()} methods of
728c16f16267 SF #1479988: add methods to allow access to weakrefs for the
Fred Drake <fdrake@acm.org>
parents: 36154
diff changeset
184 \class{WeakKeyDictionary} objects.
728c16f16267 SF #1479988: add methods to allow access to weakrefs for the
Fred Drake <fdrake@acm.org>
parents: 36154
diff changeset
185
728c16f16267 SF #1479988: add methods to allow access to weakrefs for the
Fred Drake <fdrake@acm.org>
parents: 36154
diff changeset
186 \begin{methoddesc}{itervaluerefs}{}
728c16f16267 SF #1479988: add methods to allow access to weakrefs for the
Fred Drake <fdrake@acm.org>
parents: 36154
diff changeset
187 Return an iterator that yields the weak references to the values.
728c16f16267 SF #1479988: add methods to allow access to weakrefs for the
Fred Drake <fdrake@acm.org>
parents: 36154
diff changeset
188 \versionadded{2.5}
728c16f16267 SF #1479988: add methods to allow access to weakrefs for the
Fred Drake <fdrake@acm.org>
parents: 36154
diff changeset
189 \end{methoddesc}
728c16f16267 SF #1479988: add methods to allow access to weakrefs for the
Fred Drake <fdrake@acm.org>
parents: 36154
diff changeset
190
728c16f16267 SF #1479988: add methods to allow access to weakrefs for the
Fred Drake <fdrake@acm.org>
parents: 36154
diff changeset
191 \begin{methoddesc}{valuerefs}{}
728c16f16267 SF #1479988: add methods to allow access to weakrefs for the
Fred Drake <fdrake@acm.org>
parents: 36154
diff changeset
192 Return a list of weak references to the values.
728c16f16267 SF #1479988: add methods to allow access to weakrefs for the
Fred Drake <fdrake@acm.org>
parents: 36154
diff changeset
193 \versionadded{2.5}
728c16f16267 SF #1479988: add methods to allow access to weakrefs for the
Fred Drake <fdrake@acm.org>
parents: 36154
diff changeset
194 \end{methoddesc}
728c16f16267 SF #1479988: add methods to allow access to weakrefs for the
Fred Drake <fdrake@acm.org>
parents: 36154
diff changeset
195
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
196 \begin{datadesc}{ReferenceType}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
197 The type object for weak references objects.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
198 \end{datadesc}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
199
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
200 \begin{datadesc}{ProxyType}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
201 The type object for proxies of objects which are not callable.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
202 \end{datadesc}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
203
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
204 \begin{datadesc}{CallableProxyType}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
205 The type object for proxies of callable objects.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
206 \end{datadesc}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
207
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
208 \begin{datadesc}{ProxyTypes}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
209 Sequence containing all the type objects for proxies. This can make
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
210 it simpler to test if an object is a proxy without being dependent
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
211 on naming both proxy types.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
212 \end{datadesc}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
213
17389
471ce0faa775 Remove the mapping() function from the documentation.
Fred Drake <fdrake@acm.org>
parents: 17243
diff changeset
214 \begin{excdesc}{ReferenceError}
471ce0faa775 Remove the mapping() function from the documentation.
Fred Drake <fdrake@acm.org>
parents: 17243
diff changeset
215 Exception raised when a proxy object is used but the underlying
20290
acd8378216c3 Update the documentation to reflect the changes to ReferenceError.
Fred Drake <fdrake@acm.org>
parents: 18951
diff changeset
216 object has been collected. This is the same as the standard
acd8378216c3 Update the documentation to reflect the changes to ReferenceError.
Fred Drake <fdrake@acm.org>
parents: 18951
diff changeset
217 \exception{ReferenceError} exception.
17389
471ce0faa775 Remove the mapping() function from the documentation.
Fred Drake <fdrake@acm.org>
parents: 17243
diff changeset
218 \end{excdesc}
471ce0faa775 Remove the mapping() function from the documentation.
Fred Drake <fdrake@acm.org>
parents: 17243
diff changeset
219
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
220
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
221 \begin{seealso}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
222 \seepep{0205}{Weak References}{The proposal and rationale for this
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
223 feature, including links to earlier implementations
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
224 and information about similar features in other
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
225 languages.}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
226 \end{seealso}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
227
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
228
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
229 \subsection{Weak Reference Objects
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
230 \label{weakref-objects}}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
231
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
232 Weak reference objects have no attributes or methods, but do allow the
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
233 referent to be obtained, if it still exists, by calling it:
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
234
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
235 \begin{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
236 >>> import weakref
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
237 >>> class Object:
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
238 ... pass
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
239 ...
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
240 >>> o = Object()
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
241 >>> r = weakref.ref(o)
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
242 >>> o2 = r()
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
243 >>> o is o2
31029
ce07118ee5d2 Patch #849350: Update to document bool return values. Backported to 2.3.
Martin v. Löwis <martin@v.loewis.de>
parents: 30998
diff changeset
244 True
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
245 \end{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
246
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
247 If the referent no longer exists, calling the reference object returns
31452
bb7146d117fb minor markup adjustments
Fred Drake <fdrake@acm.org>
parents: 31446
diff changeset
248 \constant{None}:
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
249
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
250 \begin{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
251 >>> del o, o2
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
252 >>> print r()
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
253 None
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
254 \end{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
255
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
256 Testing that a weak reference object is still live should be done
18951
f72d61b1246e Fix some of the example code; the reference objects do not support a
Fred Drake <fdrake@acm.org>
parents: 18348
diff changeset
257 using the expression \code{\var{ref}() is not None}. Normally,
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
258 application code that needs to use a reference object should follow
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
259 this pattern:
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
260
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
261 \begin{verbatim}
20697
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
262 # r is a weak reference object
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
263 o = r()
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
264 if o is None:
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
265 # referent has been garbage collected
35195
7804bbb26492 backport doctest for weakref examples
Georg Brandl <georg@python.org>
parents: 35191
diff changeset
266 print "Object has been deallocated; can't frobnicate."
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
267 else:
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
268 print "Object is still live!"
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
269 o.do_something_useful()
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
270 \end{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
271
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
272 Using a separate test for ``liveness'' creates race conditions in
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
273 threaded applications; another thread can cause a weak reference to
20697
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
274 become invalidated before the weak reference is called; the
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
275 idiom shown above is safe in threaded applications as well as
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
276 single-threaded applications.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
277
32472
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
278 Specialized versions of \class{ref} objects can be created through
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
279 subclassing. This is used in the implementation of the
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
280 \class{WeakValueDictionary} to reduce the memory overhead for each
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
281 entry in the mapping. This may be most useful to associate additional
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
282 information with a reference, but could also be used to insert
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
283 additional processing on calls to retrieve the referent.
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
284
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
285 This example shows how a subclass of \class{ref} can be used to store
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
286 additional information about an object and affect the value that's
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
287 returned when the referent is accessed:
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
288
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
289 \begin{verbatim}
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
290 import weakref
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
291
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
292 class ExtendedRef(weakref.ref):
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
293 def __init__(self, ob, callback=None, **annotations):
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
294 super(ExtendedRef, self).__init__(ob, callback)
35191
8f7e47a0aaca backport bug [ 1228904 ] weakref example broken
Georg Brandl <georg@python.org>
parents: 32472
diff changeset
295 self.__counter = 0
8f7e47a0aaca backport bug [ 1228904 ] weakref example broken
Georg Brandl <georg@python.org>
parents: 32472
diff changeset
296 for k, v in annotations.iteritems():
32472
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
297 setattr(self, k, v)
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
298
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
299 def __call__(self):
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
300 """Return a pair containing the referent and the number of
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
301 times the reference has been called.
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
302 """
35195
7804bbb26492 backport doctest for weakref examples
Georg Brandl <georg@python.org>
parents: 35191
diff changeset
303 ob = super(ExtendedRef, self).__call__()
32472
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
304 if ob is not None:
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
305 self.__counter += 1
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
306 ob = (ob, self.__counter)
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
307 return ob
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
308 \end{verbatim}
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
309
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
310
17243
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
311 \subsection{Example \label{weakref-example}}
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
312
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
313 This simple example shows how an application can use objects IDs to
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
314 retrieve objects that it has seen before. The IDs of the objects can
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
315 then be used in other data structures without forcing the objects to
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
316 remain alive, but the objects can still be retrieved by ID if they
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
317 do.
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
318
31276
1dc2659ed9fc use consistent email address for Tim
Fred Drake <fdrake@acm.org>
parents: 31029
diff changeset
319 % Example contributed by Tim Peters.
17243
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
320 \begin{verbatim}
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
321 import weakref
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
322
17389
471ce0faa775 Remove the mapping() function from the documentation.
Fred Drake <fdrake@acm.org>
parents: 17243
diff changeset
323 _id2obj_dict = weakref.WeakValueDictionary()
17243
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
324
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
325 def remember(obj):
20697
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
326 oid = id(obj)
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
327 _id2obj_dict[oid] = obj
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
328 return oid
17243
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
329
20697
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
330 def id2obj(oid):
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
331 return _id2obj_dict[oid]
17243
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
332 \end{verbatim}
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
333
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
334
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
335 \subsection{Weak References in Extension Types
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
336 \label{weakref-extension}}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
337
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
338 One of the goals of the implementation is to allow any type to
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
339 participate in the weak reference mechanism without incurring the
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
340 overhead on those objects which do not benefit by weak referencing
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
341 (such as numbers).
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
342
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
343 For an object to be weakly referencable, the extension must include a
20697
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
344 \ctype{PyObject*} field in the instance structure for the use of the
17173
73f41b0ff777 Update to the most recent weakref changes.
Fred Drake <fdrake@acm.org>
parents: 16794
diff changeset
345 weak reference mechanism; it must be initialized to \NULL{} by the
73f41b0ff777 Update to the most recent weakref changes.
Fred Drake <fdrake@acm.org>
parents: 16794
diff changeset
346 object's constructor. It must also set the \member{tp_weaklistoffset}
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
347 field of the corresponding type object to the offset of the field.
24642
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
348 Also, it needs to add \constant{Py_TPFLAGS_HAVE_WEAKREFS} to the
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
349 tp_flags slot. For example, the instance type is defined with the
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
350 following structure:
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
351
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
352 \begin{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
353 typedef struct {
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
354 PyObject_HEAD
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
355 PyClassObject *in_class; /* The class object */
16794
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries
Martin v. Löwis <martin@v.loewis.de>
parents: 16588
diff changeset
356 PyObject *in_dict; /* A dictionary */
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries
Martin v. Löwis <martin@v.loewis.de>
parents: 16588
diff changeset
357 PyObject *in_weakreflist; /* List of weak references */
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
358 } PyInstanceObject;
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
359 \end{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
360
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
361 The statically-declared type object for instances is defined this way:
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
362
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
363 \begin{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
364 PyTypeObject PyInstance_Type = {
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
365 PyObject_HEAD_INIT(&PyType_Type)
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
366 0,
21313
91dd223829c6 Patch supplied by Burton Radons for his own SF bug #487390: Modifying
Guido van Rossum <guido@python.org>
parents: 21054
diff changeset
367 "module.instance",
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
368
18223
220405c07232 Corrected an error in the information on supporting weak references in
Fred Drake <fdrake@acm.org>
parents: 17768
diff changeset
369 /* Lots of stuff omitted for brevity... */
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
370
24642
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
371 Py_TPFLAGS_DEFAULT | Py_TPFLAGS_HAVE_WEAKREFS /* tp_flags */
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
372 0, /* tp_doc */
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
373 0, /* tp_traverse */
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
374 0, /* tp_clear */
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
375 0, /* tp_richcompare */
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
376 offsetof(PyInstanceObject, in_weakreflist), /* tp_weaklistoffset */
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
377 };
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
378 \end{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
379
24642
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
380 The type constructor is responsible for initializing the weak reference
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
381 list to \NULL:
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
382
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
383 \begin{verbatim}
30998
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
384 static PyObject *
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
385 instance_new() {
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
386 /* Other initialization stuff omitted for brevity */
24642
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
387
30998
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
388 self->in_weakreflist = NULL;
24642
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
389
30998
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
390 return (PyObject *) self;
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
391 }
24642
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
392 \end{verbatim}
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
393
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
394 The only further addition is that the destructor needs to call the
18223
220405c07232 Corrected an error in the information on supporting weak references in
Fred Drake <fdrake@acm.org>
parents: 17768
diff changeset
395 weak reference manager to clear any weak references. This should be
20697
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
396 done before any other parts of the destruction have occurred, but is
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
397 only required if the weak reference list is non-\NULL:
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
398
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
399 \begin{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
400 static void
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
401 instance_dealloc(PyInstanceObject *inst)
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
402 {
20697
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
403 /* Allocate temporaries if needed, but do not begin
18223
220405c07232 Corrected an error in the information on supporting weak references in
Fred Drake <fdrake@acm.org>
parents: 17768
diff changeset
404 destruction just yet.
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
405 */
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
406
20697
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
407 if (inst->in_weakreflist != NULL)
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
408 PyObject_ClearWeakRefs((PyObject *) inst);
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
409
20687
367cd8e5df47 Typo: destuction --> destruction
Fred Drake <fdrake@acm.org>
parents: 20676
diff changeset
410 /* Proceed with object destruction normally. */
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
411 }
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
412 \end{verbatim}