[Python-checkins] CVS: python/dist/src/Doc/lib libfuncs.tex,1.91,1.92
Tim Peters
tim_one@users.sourceforge.net
Thu, 25 Oct 2001 22:06:52 -0700
Update of /cvsroot/python/python/dist/src/Doc/lib
In directory usw-pr-cvs1:/tmp/cvs-serv13745/python/Doc/lib
Modified Files:
libfuncs.tex
Log Message:
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).
Index: libfuncs.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libfuncs.tex,v
retrieving revision 1.91
retrieving revision 1.92
diff -C2 -d -r1.91 -r1.92
*** libfuncs.tex 2001/10/19 12:02:28 1.91
--- libfuncs.tex 2001/10/26 05:06:50 1.92
***************
*** 176,179 ****
--- 176,201 ----
\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
***************
*** 473,477 ****
\end{funcdesc}
! \begin{funcdesc}{list}{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
--- 495,499 ----
\end{funcdesc}
! \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
***************
*** 727,731 ****
\end{funcdesc}
! \begin{funcdesc}{tuple}{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
--- 749,753 ----
\end{funcdesc}
! \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