Implement, test and document "key in dict" and "key not in dict".

I know some people don't like this -- if it's really controversial,
I'll take it out again.  (If it's only Alex Martelli who doesn't like
it, that doesn't count as "real controversial" though. :-)

That's why this is a separate checkin from the iterators stuff I'm
about to check in next.

3 files changed, 20 insertions, 7 deletions

diff --git a/Doc/lib/libstdtypes.tex b/Doc/lib/libstdtypes.tex
index 79221b8..f6786a1 100644
--- a/Doc/lib/libstdtypes.tex
+++ b/Doc/lib/libstdtypes.tex
@@ -867,9 +867,15 @@ arbitrary objects):
           {(1)}
   \lineiii{\var{a}.clear()}{remove all items from \code{a}}{}
   \lineiii{\var{a}.copy()}{a (shallow) copy of \code{a}}{}
-  \lineiii{\var{a}.has_key(\var{k})}
+  \lineiii{\var{k} \code{in} \var{a}}
           {\code{1} if \var{a} has a key \var{k}, else \code{0}}
           {}
+  \lineiii{\var{k} not in \var{a}}
+          {\code{0} if \var{a} has a key \var{k}, else \code{1}}
+          {}
+  \lineiii{\var{a}.has_key(\var{k})}
+          {Equivalent to \var{k} \code{in} \var{a}}
+          {}
   \lineiii{\var{a}.items()}
           {a copy of \var{a}'s list of (\var{key}, \var{value}) pairs}
           {(2)}
@@ -879,11 +885,11 @@ arbitrary objects):
           {(3)}
   \lineiii{\var{a}.values()}{a copy of \var{a}'s list of values}{(2)}
   \lineiii{\var{a}.get(\var{k}\optional{, \var{x}})}
-          {\code{\var{a}[\var{k}]} if \code{\var{a}.has_key(\var{k})},
+          {\code{\var{a}[\var{k}]} if \code{\var{k} in \var{a}}},
            else \var{x}}
           {(4)}
   \lineiii{\var{a}.setdefault(\var{k}\optional{, \var{x}})}
-          {\code{\var{a}[\var{k}]} if \code{\var{a}.has_key(\var{k})},
+          {\code{\var{a}[\var{k}]} if \code{\var{k} in \var{a}}},
            else \var{x} (also setting it)}
           {(5)}
   \lineiii{\var{a}.popitem()}
diff --git a/Doc/ref/ref3.tex b/Doc/ref/ref3.tex
index 1f3afbf..adb619a 100644
--- a/Doc/ref/ref3.tex
+++ b/Doc/ref/ref3.tex
@@ -1134,7 +1134,10 @@ multiplication (meaning repetition) by defining the methods
 \method{__add__()}, \method{__radd__()}, \method{__iadd__()},
 \method{__mul__()}, \method{__rmul__()} and \method{__imul__()} described
 below; they should not define \method{__coerce__()} or other numerical
-operators.
+operators.  It is recommended that both mappings and sequences
+implement the \method{__contains__}, to allow efficient use of the
+\code{in} operator; for mappings, \code{in} should be equivalent of
+\method{has_key()}; for sequences, it should search through the values.
 \withsubitem{(mapping object method)}{
   \ttindex{keys()}
   \ttindex{values()}
@@ -1143,7 +1146,8 @@ operators.
   \ttindex{get()}
   \ttindex{clear()}
   \ttindex{copy()}
-  \ttindex{update()}}
+  \ttindex{update()}
+  \ttindex{__contains__()}}
 \withsubitem{(sequence object method)}{
   \ttindex{append()}
   \ttindex{count()}
@@ -1158,7 +1162,8 @@ operators.
   \ttindex{__iadd__()}
   \ttindex{__mul__()}
   \ttindex{__rmul__()}
-  \ttindex{__imul__()}}
+  \ttindex{__imul__()}
+  \ttindex{__contains__()}}
 \withsubitem{(numeric object method)}{\ttindex{__coerce__()}}
 
 \begin{methoddesc}[mapping object]{__len__}{self}
diff --git a/Doc/ref/ref5.tex b/Doc/ref/ref5.tex
index 5663daa..ec0c6b1 100644
--- a/Doc/ref/ref5.tex
+++ b/Doc/ref/ref5.tex
@@ -768,7 +768,9 @@ not in \var{s}} returns the negation of \code{\var{x} in \var{s}}.
 The set membership test has traditionally been bound to sequences; an
 object is a member of a set if the set is a sequence and contains an
 element equal to that object.  However, it is possible for an object
-to support membership tests without being a sequence.
+to support membership tests without being a sequence.  In particular,
+dictionaries support memership testing as a nicer way of spelling
+\code{\var{key} in \var{dict}}; other mapping types may follow suit.
 
 For the list and tuple types, \code{\var{x} in \var{y}} is true if and
 only if there exists an index \var{i} such that