Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libweakref.tex @ 37850:ebe59cd18273

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Use explicit relative import for an, ehm, relative import.
author Thomas Wouters <thomas@python.org>
date Tue, 18 Apr 2006 21:41:36 +0000
parents 963a98d8fe2e
children 728c16f16267
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
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries
Martin v. Löwis <martin@v.loewis.de>
parents: 16588
diff changeset
150 \begin{classdesc}{WeakValueDictionary}{\optional{dict}}
17389
471ce0faa775 Remove the mapping() function from the documentation.
Fred Drake <fdrake@acm.org>
parents: 17243
diff changeset
151 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
152 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
153 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
154
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
155 \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
156 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
157 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
158 \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
159 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
160 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
161 \end{classdesc}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
162
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
163 \begin{datadesc}{ReferenceType}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
164 The type object for weak references objects.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
165 \end{datadesc}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
166
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
167 \begin{datadesc}{ProxyType}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
168 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
169 \end{datadesc}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
170
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
171 \begin{datadesc}{CallableProxyType}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
172 The type object for proxies of callable objects.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
173 \end{datadesc}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
174
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
175 \begin{datadesc}{ProxyTypes}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
176 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
177 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
178 on naming both proxy types.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
179 \end{datadesc}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
180
17389
471ce0faa775 Remove the mapping() function from the documentation.
Fred Drake <fdrake@acm.org>
parents: 17243
diff changeset
181 \begin{excdesc}{ReferenceError}
471ce0faa775 Remove the mapping() function from the documentation.
Fred Drake <fdrake@acm.org>
parents: 17243
diff changeset
182 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
183 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
184 \exception{ReferenceError} exception.
17389
471ce0faa775 Remove the mapping() function from the documentation.
Fred Drake <fdrake@acm.org>
parents: 17243
diff changeset
185 \end{excdesc}
471ce0faa775 Remove the mapping() function from the documentation.
Fred Drake <fdrake@acm.org>
parents: 17243
diff changeset
186
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
187
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
188 \begin{seealso}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
189 \seepep{0205}{Weak References}{The proposal and rationale for this
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
190 feature, including links to earlier implementations
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
191 and information about similar features in other
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
192 languages.}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
193 \end{seealso}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
194
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
195
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
196 \subsection{Weak Reference Objects
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
197 \label{weakref-objects}}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
198
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
199 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
200 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
201
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
202 \begin{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
203 >>> import weakref
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
204 >>> class Object:
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
205 ... pass
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
206 ...
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
207 >>> o = Object()
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
208 >>> r = weakref.ref(o)
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
209 >>> o2 = r()
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
210 >>> 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
211 True
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
212 \end{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
213
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
214 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
215 \constant{None}:
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
216
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
217 \begin{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
218 >>> del o, o2
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
219 >>> print r()
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
220 None
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
221 \end{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
222
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
223 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
224 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
225 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
226 this pattern:
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 \begin{verbatim}
20697
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
229 # 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
230 o = r()
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
231 if o is None:
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
232 # referent has been garbage collected
35195
7804bbb26492 backport doctest for weakref examples
Georg Brandl <georg@python.org>
parents: 35191
diff changeset
233 print "Object has been deallocated; can't frobnicate."
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
234 else:
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
235 print "Object is still live!"
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
236 o.do_something_useful()
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
237 \end{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
238
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
239 Using a separate test for ``liveness'' creates race conditions in
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
240 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
241 become invalidated before the weak reference is called; the
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
242 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
243 single-threaded applications.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
244
32472
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
245 Specialized versions of \class{ref} objects can be created through
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
246 subclassing. This is used in the implementation of the
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
247 \class{WeakValueDictionary} to reduce the memory overhead for each
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
248 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
249 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
250 additional processing on calls to retrieve the referent.
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
251
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
252 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
253 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
254 returned when the referent is accessed:
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
255
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
256 \begin{verbatim}
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
257 import weakref
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
258
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
259 class ExtendedRef(weakref.ref):
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
260 def __init__(self, ob, callback=None, **annotations):
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
261 super(ExtendedRef, self).__init__(ob, callback)
35191
8f7e47a0aaca backport bug [ 1228904 ] weakref example broken
Georg Brandl <georg@python.org>
parents: 32472
diff changeset
262 self.__counter = 0
8f7e47a0aaca backport bug [ 1228904 ] weakref example broken
Georg Brandl <georg@python.org>
parents: 32472
diff changeset
263 for k, v in annotations.iteritems():
32472
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
264 setattr(self, k, v)
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
265
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
266 def __call__(self):
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
267 """Return a pair containing the referent and the number of
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
268 times the reference has been called.
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
269 """
35195
7804bbb26492 backport doctest for weakref examples
Georg Brandl <georg@python.org>
parents: 35191
diff changeset
270 ob = super(ExtendedRef, self).__call__()
32472
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
271 if ob is not None:
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
272 self.__counter += 1
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
273 ob = (ob, self.__counter)
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
274 return ob
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
275 \end{verbatim}
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
276
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
277
17243
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
278 \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
279
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
280 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
281 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
282 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
283 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
284 do.
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
285
31276
1dc2659ed9fc use consistent email address for Tim
Fred Drake <fdrake@acm.org>
parents: 31029
diff changeset
286 % 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
287 \begin{verbatim}
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
288 import weakref
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
289
17389
471ce0faa775 Remove the mapping() function from the documentation.
Fred Drake <fdrake@acm.org>
parents: 17243
diff changeset
290 _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
291
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
292 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
293 oid = id(obj)
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
294 _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
295 return oid
17243
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
296
20697
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
297 def id2obj(oid):
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
298 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
299 \end{verbatim}
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
300
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
301
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
302 \subsection{Weak References in Extension Types
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
303 \label{weakref-extension}}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
304
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
305 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
306 participate in the weak reference mechanism without incurring the
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
307 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
308 (such as numbers).
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
309
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
310 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
311 \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
312 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
313 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
314 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
315 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
316 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
317 following structure:
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
318
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
319 \begin{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
320 typedef struct {
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
321 PyObject_HEAD
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
322 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
323 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
324 PyObject *in_weakreflist; /* List of weak references */
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
325 } PyInstanceObject;
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
326 \end{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
327
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
328 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
329
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
330 \begin{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
331 PyTypeObject PyInstance_Type = {
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
332 PyObject_HEAD_INIT(&PyType_Type)
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
333 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
334 "module.instance",
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
335
18223
220405c07232 Corrected an error in the information on supporting weak references in
Fred Drake <fdrake@acm.org>
parents: 17768
diff changeset
336 /* Lots of stuff omitted for brevity... */
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
337
24642
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
338 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
339 0, /* tp_doc */
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
340 0, /* tp_traverse */
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
341 0, /* tp_clear */
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
342 0, /* tp_richcompare */
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
343 offsetof(PyInstanceObject, in_weakreflist), /* tp_weaklistoffset */
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
344 };
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
345 \end{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
346
24642
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
347 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
348 list to \NULL:
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
349
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
350 \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
351 static PyObject *
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
352 instance_new() {
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
353 /* 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
354
30998
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
355 self->in_weakreflist = NULL;
24642
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
356
30998
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
357 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
358 }
24642
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
359 \end{verbatim}
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
360
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
361 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
362 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
363 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
364 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
365
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
366 \begin{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
367 static void
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
368 instance_dealloc(PyInstanceObject *inst)
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
369 {
20697
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
370 /* 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
371 destruction just yet.
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
372 */
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
373
20697
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
374 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
375 PyObject_ClearWeakRefs((PyObject *) inst);
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
376
20687
367cd8e5df47 Typo: destuction --> destruction
Fred Drake <fdrake@acm.org>
parents: 20676
diff changeset
377 /* Proceed with object destruction normally. */
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
378 }
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
379 \end{verbatim}