Generalize dictionary() to accept a sequence of 2-sequences. At the

outer level, the iterator protocol is used for memory-efficiency (the
outer sequence may be very large if fully materialized); at the inner
level, PySequence_Fast() is used for time-efficiency (these should
always be sequences of length 2).

dictobject.c, new functions PyDict_{Merge,Update}FromSeq2.  These are
wholly analogous to PyDict_{Merge,Update}, but process a sequence-of-2-
sequences argument instead of a mapping object.  For now, I left these
functions file static, so no corresponding doc changes.  It's tempting
to change dict.update() to allow a sequence-of-2-seqs argument too.

Also changed the name of dictionary's keyword argument from "mapping"
to "x".  Got a better name?  "mapping_or_sequence_of_pairs" isn't
attractive, although more so than "mosop" <wink>.

abstract.h, abstract.tex:  Added new PySequence_Fast_GET_SIZE function,
much faster than going thru the all-purpose PySequence_Size.

libfuncs.tex:
- Document dictionary().
- Fiddle tuple() and list() to admit that their argument is optional.
- The long-winded repetitions of "a sequence, a container that supports
  iteration, or an iterator object" is getting to be a PITA.  Many
  months ago I suggested factoring this out into "iterable object",
  where the definition of that could include being explicit about
  generators too (as is, I'm not sure a reader outside of PythonLabs
  could guess that "an iterator object" includes a generator call).
- Please check my curly braces -- I'm going blind <0.9 wink>.

abstract.c, PySequence_Tuple():  When PyObject_GetIter() fails, leave
its error msg alone now (the msg it produces has improved since
PySequence_Tuple was generalized to accept iterable objects, and
PySequence_Tuple was also stomping on the msg in cases it shouldn't
have even before PyObject_GetIter grew a better msg).

2 files changed, 36 insertions, 7 deletions

diff --git a/Doc/api/abstract.tex b/Doc/api/abstract.tex
index 8d271df..fae8475 100644
--- a/Doc/api/abstract.tex
+++ b/Doc/api/abstract.tex
@@ -125,7 +125,7 @@ for which they do not apply, they will raise a Python exception.
   the Unicode string representation on success, \NULL{} on failure.
   This is the equivalent of the Python expression
   \samp{unistr(\var{o})}.  Called by the
-  \function{unistr()}\bifuncindex{unistr} built-in function. 
+  \function{unistr()}\bifuncindex{unistr} built-in function.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{int}{PyObject_IsInstance}{PyObject *inst, PyObject *cls}
@@ -715,10 +715,17 @@ determination.
 
 \begin{cfuncdesc}{PyObject*}{PySequence_Fast_GET_ITEM}{PyObject *o, int i}
   Return the \var{i}th element of \var{o}, assuming that \var{o} was
-  returned by \cfunction{PySequence_Fast()}, and that \var{i} is
-  within bounds.  The caller is expected to get the length of the
-  sequence by calling \cfunction{PySequence_Size()} on \var{o}, since
-  lists and tuples are guaranteed to always return their true length.
+  returned by \cfunction{PySequence_Fast()}, \var{o} is not \NULL{},
+  and that \var{i} is within bounds.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PySequence_Fast_GET_SIZE}{PyObject *o}
+  Returns the length of \var{o}, assuming that \var{o} was
+  returned by \cfunction{PySequence_Fast()} and that \var{o} is
+  not \NULL{}.  The size can also be gotten by calling
+  \cfunction{PySequence_Size()} on \var{o}, but
+  \cfunction{PySequence_Fast_GET_SIZE()} is faster because it can
+  assume \var{o} is a list or tuple.
 \end{cfuncdesc}
 
 
diff --git a/Doc/lib/libfuncs.tex b/Doc/lib/libfuncs.tex
index b19d4a6..e9baeb3 100644
--- a/Doc/lib/libfuncs.tex
+++ b/Doc/lib/libfuncs.tex
@@ -175,6 +175,28 @@ def my_import(name):
   \code{del \var{x}.\var{foobar}}.
 \end{funcdesc}
 
+\begin{funcdesc}{dictionary}{\optional{mapping-or-sequence}}
+  Return a new dictionary initialized from the optional argument.
+  If an argument is not specified, return a new empty dictionary.
+  If the argument is a mapping object, return a dictionary mapping the
+  same keys to the same values as does the mapping object.
+  Else the argument must be a sequence, a container that supports
+  iteration, or an iterator object.  The elements of the argument must
+  each also be of one of those kinds, and each must in turn contain
+  exactly two objects.  The first is used as a key in the new dictionary,
+  and the second as the key's value.  If a given key is seen more than
+  once, the last value associated with it is retained in the new
+  dictionary.
+  For example, these all return a dictionary equal to
+  \code{\{1: 2, 2: 3\}}:
+  \code{dictionary(\{1: 2, 2: 3\})},
+  \code{dictionary(\{1: 2, 2: 3\}.items()},
+  \code{dictionary(\{1: 2, 2: 3\}.iteritems()},
+  \code{dictionary(zip((1, 2), (2, 3)))},
+  \code{dictionary([[2, 3], [1, 2]])}, and
+  \code{dictionary([(i-1, i) for i in (2, 3)])}.
+\end{funcdesc}
+
 \begin{funcdesc}{dir}{\optional{object}}
   Without arguments, return the list of names in the current local
   symbol table.  With an argument, attempts to return a list of valid
@@ -472,7 +494,7 @@ def my_import(name):
   may be a sequence (string, tuple or list) or a mapping (dictionary).
 \end{funcdesc}
 
-\begin{funcdesc}{list}{sequence}
+\begin{funcdesc}{list}{\optional{sequence}}
   Return a list whose items are the same and in the same order as
   \var{sequence}'s items.  \var{sequence} may be either a sequence, a
   container that supports iteration, or an iterator object.  If
@@ -726,7 +748,7 @@ def my_import(name):
   printable string.
 \end{funcdesc}
 
-\begin{funcdesc}{tuple}{sequence}
+\begin{funcdesc}{tuple}{\optional{sequence}}
   Return a tuple whose items are the same and in the same order as
   \var{sequence}'s items.  \var{sequence} may be a sequence, a
   container that supports iteration, or an iterator object.