Refer to the objects which define __len__(), __*item__(), and __iter__()
as container objects rather than as mapping objects (in the index entries).
Change the section heading and intro sentence to be a little more general,
since that's how things have actually evolved.
diff --git a/Doc/ref/ref3.tex b/Doc/ref/ref3.tex
index 4f1e388..32b6de4 100644
--- a/Doc/ref/ref3.tex
+++ b/Doc/ref/ref3.tex
@@ -1122,10 +1122,12 @@
\end{methoddesc}
-\subsection{Emulating sequence and mapping types\label{sequence-types}}
+\subsection{Emulating container types\label{sequence-types}}
-The following methods can be defined to emulate sequence or mapping
-objects. The first set of methods is used either to emulate a
+The following methods can be defined to implement container
+objects. Containers usually are sequences (such as lists or tuples)
+or mappings (like dictionaries), but can represent other containers as
+well. The first set of methods is used either to emulate a
sequence or to emulate a mapping; the difference is that for a
sequence, the allowable keys should be the integers \var{k} for which
\code{0 <= \var{k} < \var{N}} where \var{N} is the length of the
@@ -1177,7 +1179,7 @@
\ttindex{__contains__()}}
\withsubitem{(numeric object method)}{\ttindex{__coerce__()}}
-\begin{methoddesc}[mapping object]{__len__}{self}
+\begin{methoddesc}[container object]{__len__}{self}
Called to implement the built-in function
\function{len()}\bifuncindex{len}. Should return the length of the
object, an integer \code{>=} 0. Also, an object that doesn't define a
@@ -1186,7 +1188,7 @@
\withsubitem{(object method)}{\ttindex{__nonzero__()}}
\end{methoddesc}
-\begin{methoddesc}[mapping object]{__getitem__}{self, key}
+\begin{methoddesc}[container object]{__getitem__}{self, key}
Called to implement evaluation of \code{\var{self}[\var{key}]}.
For sequence types, the accepted keys should be integers and slice
objects.\obindex{slice} Note that
@@ -1201,7 +1203,7 @@
proper detection of the end of the sequence.
\end{methoddesc}
-\begin{methoddesc}[mapping object]{__setitem__}{self, key, value}
+\begin{methoddesc}[container object]{__setitem__}{self, key, value}
Called to implement assignment to \code{\var{self}[\var{key}]}. Same
note as for \method{__getitem__()}. This should only be implemented
for mappings if the objects support changes to the values for keys, or
@@ -1210,7 +1212,7 @@
\var{key} values as for the \method{__getitem__()} method.
\end{methoddesc}
-\begin{methoddesc}[mapping object]{__delitem__}{self, key}
+\begin{methoddesc}[container object]{__delitem__}{self, key}
Called to implement deletion of \code{\var{self}[\var{key}]}. Same
note as for \method{__getitem__()}. This should only be implemented
for mappings if the objects support removal of keys, or for sequences
@@ -1219,6 +1221,32 @@
\method{__getitem__()} method.
\end{methoddesc}
+\begin{methoddesc}[container object]{__iter__}{self}
+This method is called when an iterator is required for a container.
+This method should return a new iterator object that can iterate over
+all the objects in the container. For mappings, it should iterate
+over the keys of the container, and should also be made available as
+the method \method{iterkeys()}.
+
+Iterator objects also need to implement this method; they are required
+to return themselves. For more information on iterator objects, see
+``\ulink{Iterator Types}{../lib/typeiter.html}'' in the
+\citetitle[../lib/lib.html]{Python Library Reference}.
+\end{methoddesc}
+
+The membership test operators (\keyword{in} and \keyword{not in}) are
+normally implemented as an iteration through a sequence. However,
+container objects can supply the following special method with a more
+efficient implementation, which also does not require the object be a
+sequence.
+
+\begin{methoddesc}[container object]{__contains__}{self, item}
+Called to implement membership test operators. Should return true if
+\var{item} is in \var{self}, false otherwise. For mapping objects,
+this should consider the keys of the mapping rather than the values or
+the key-item pairs.
+\end{methoddesc}
+
\subsection{Additional methods for emulation of sequence types
\label{sequence-methods}}
@@ -1310,16 +1338,6 @@
the \method{__*item__()} methods.
Calling \code{max(0, i)} conveniently returns the proper value.
-The membership test operators (\keyword{in} and \keyword{not in}) are
-normally implemented as an iteration through the sequence. However,
-sequence objects can supply the following special method with a more
-efficient implementation:
-
-\begin{methoddesc}[sequence object]{__contains__}{self, item}
-Called to implement membership test operators. Should return true if
-\var{item} is in \var{self}, false otherwise.
-\end{methoddesc}
-
\subsection{Emulating numeric types\label{numeric-types}}