Patch #403985: Add support for weak-keyed dictionaries
diff --git a/Doc/lib/libweakref.tex b/Doc/lib/libweakref.tex
index 61ed9fe..97f624d 100644
--- a/Doc/lib/libweakref.tex
+++ b/Doc/lib/libweakref.tex
@@ -3,6 +3,8 @@
\declaremodule{extension}{weakref}
\moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
+\moduleauthor{Neil Schemenauer}{nas@arctrix.com}
+\moduleauthor{Martin von L\o"wis}{martin@loewis.home.cs.tu-berlin.de}
\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
\versionadded{2.1}
@@ -18,13 +20,6 @@
be made to support weak references; see section \ref{weakref-extension},
``Weak References in Extension Types,'' for more information.
-
-\strong{Warning:}
-The weak dictionaries provided in the current implementation and
-described below are subject to change. They are included to solicit
-feedback and usage experience, and may be changed or removed in the
-final version.
-
\strong{Warning:}
The desired semantics of weak-reference proxy objects are not
completely clear; it is very difficult to create proxies which behave
@@ -32,9 +27,6 @@
are likely to change to some degree before the final release as
experience reports become available.
-Please send specific feedback on this module to Fred Drake at
-\email{fdrake@acm.org}.
-
\begin{funcdesc}{ref}{object\optional{, callback}}
Return a weak reference to \var{object}. If \var{callback} is
@@ -53,15 +45,36 @@
error output, but cannot be propagated; they are handled in exactly
the same way as exceptions raised from an object's
\method{__del__()} method.
+
+ Weak references are hashable if the \var{object} is hashable. They
+ will maintain their hash value even after the \var{object} was
+ deleted. If \function{hash()} is called the first time only after
+ the \var{object} was deleted, the call will raise
+ \exception{TypeError}.
+
+ Weak references support test for equality, but not ordering. If the
+ \var{object} is still alive, to references are equal if the objects
+ are equal (regardless of the \var{callback}). If the \var{object}
+ has been deleted, they are equal iff they are identical.
+
\end{funcdesc}
-\begin{funcdesc}{mapping}{\optional{dict}}
+\begin{funcdesc}{mapping}{\optional{dict\optional{, weakkeys=0}}}
Return a weak dictionary. If \var{dict} is given and not
\code{None}, the new dictionary will contain the items contained in
\var{dict}. The values from \var{dict} must be weakly referencable;
if any values which would be inserted into the new mapping are not
weakly referencable, \exception{TypeError} will be raised and the
new mapping will be empty.
+
+ If the \var{weakkeys} argument is not given or zero, the values in
+ the dictionary are weak. That means the entries in the dictionary
+ will be discarded when no strong reference to the value exists
+ anymore.
+
+ If the \var{weakkeys} argument is nonzero, the keys in the
+ dictionary are weak, i.e. the entry in the dictionary is discarded
+ when the last strong reference to the key is discarded.
\end{funcdesc}
\begin{funcdesc}{proxy}{object\optional{, callback}}
@@ -87,9 +100,16 @@
\var{object}.
\end{funcdesc}
-\begin{classdesc}{WeakDictionary}{\optional{dict}}
- The class of the mapping objects returned by \function{mapping()}.
- This can be used for subclassing the implementation if needed.
+\begin{classdesc}{WeakKeyDictionary}{\optional{dict}}
+ The class of the mapping objects returned by \function{mapping()}
+ when \var{weakkeys} is true. This can be used for subclassing the
+ implementation if needed.
+\end{classdesc}
+
+\begin{classdesc}{WeakValueDictionary}{\optional{dict}}
+ The class of the mapping objects returned by \function{mapping()}
+ when \var{weakkeys} if false. This can be used for subclassing the
+ implementation if needed.
\end{classdesc}
\begin{datadesc}{ReferenceType}
@@ -187,8 +207,8 @@
typedef struct {
PyObject_HEAD
PyClassObject *in_class; /* The class object */
- PyObject *in_dict; /* A dictionary */
- PyObject *in_weakreflist; /* List of weak references */
+ PyObject *in_dict; /* A dictionary */
+ PyObject *in_weakreflist; /* List of weak references */
} PyInstanceObject;
\end{verbatim}