From cb1ffd9433411af14eb2c19a8098538ca2090b87 Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Sun, 7 Dec 2003 11:03:08 +0000 Subject: [PATCH] Backports: * Put str() in alphabetical order * Move apply(), buffer(), coerce(), and intern() to a separate section. --- Doc/lib/libfuncs.tex | 139 ++++++++++++++++++++++++------------------- 1 file changed, 78 insertions(+), 61 deletions(-) diff --git a/Doc/lib/libfuncs.tex b/Doc/lib/libfuncs.tex index c4ce201a5f7e..95657220d9a5 100644 --- a/Doc/lib/libfuncs.tex +++ b/Doc/lib/libfuncs.tex @@ -60,26 +60,6 @@ def my_import(name): complex number, its magnitude is returned. \end{funcdesc} -\begin{funcdesc}{apply}{function, args\optional{, keywords}} - The \var{function} argument must be a callable object (a - user-defined or built-in function or method, or a class object) and - the \var{args} argument must be a sequence. The \var{function} is - called with \var{args} as the argument list; the number of arguments - is the length of the tuple. - If the optional \var{keywords} argument is present, it must be a - dictionary whose keys are strings. It specifies keyword arguments - to be added to the end of the argument list. - Calling \function{apply()} is different from just calling - \code{\var{function}(\var{args})}, since in that case there is always - exactly one argument. The use of \function{apply()} is equivalent - to \code{\var{function}(*\var{args}, **\var{keywords})}. - Use of \function{apply()} is not necessary since the ``extended call - syntax,'' as used in the last example, is completely equivalent. - - \deprecated{2.3}{Use the extended call syntax instead, as described - above.} -\end{funcdesc} - \begin{funcdesc}{basestring}{} This abstract type is the superclass for \class{str} and \class{unicode}. It cannot be called or instantiated, but it can be used to test whether @@ -103,16 +83,6 @@ def my_import(name): \constant{False}]{2.3} \end{funcdesc} -\begin{funcdesc}{buffer}{object\optional{, offset\optional{, size}}} - The \var{object} argument must be an object that supports the buffer - call interface (such as strings, arrays, and buffers). A new buffer - object will be created which references the \var{object} argument. - The buffer object will be a slice from the beginning of \var{object} - (or from the specified \var{offset}). The slice will extend to the - end of \var{object} (or will have a length given by the \var{size} - argument). -\end{funcdesc} - \begin{funcdesc}{callable}{object} Return true if the \var{object} argument appears callable, false if not. If this returns true, it is still possible that a call fails, @@ -161,12 +131,6 @@ class C: \code{\var{x} > \var{y}}. \end{funcdesc} -\begin{funcdesc}{coerce}{x, y} - Return a tuple consisting of the two numeric arguments converted to - a common type, using the same rules as used by arithmetic - operations. -\end{funcdesc} - \begin{funcdesc}{compile}{string, filename, kind\optional{, flags\optional{, dont_inherit}}} Compile the \var{string} into a code object. Code objects can be @@ -570,21 +534,6 @@ class C: be returned instead. If no arguments are given, returns \code{0}. \end{funcdesc} -\begin{funcdesc}{intern}{string} - Enter \var{string} in the table of ``interned'' strings and return - the interned string -- which is \var{string} itself or a copy. - Interning strings is useful to gain a little performance on - dictionary lookup -- if the keys in a dictionary are interned, and - the lookup key is interned, the key comparisons (after hashing) can - be done by a pointer compare instead of a string compare. Normally, - the names used in Python programs are automatically interned, and - the dictionaries used to hold module, class or instance attributes - have interned keys. \versionchanged[Interned strings are not - immortal (like they used to be in Python 2.2 and before); - you must keep a reference to the return value of \function{intern()} - around to benefit from it]{2.3} -\end{funcdesc} - \begin{funcdesc}{isinstance}{object, classinfo} Return true if the \var{object} argument is an instance of the \var{classinfo} argument, or of a (direct or indirect) subclass @@ -932,6 +881,16 @@ class C: \versionadded{2.2} \end{funcdesc} +\begin{funcdesc}{str}{\optional{object}} + Return a string containing a nicely printable representation of an + object. For strings, this returns the string itself. The + difference with \code{repr(\var{object})} is that + \code{str(\var{object})} does not always attempt to return a string + that is acceptable to \function{eval()}; its goal is to return a + printable string. If no argument is given, returns the empty + string, \code{''}. +\end{funcdesc} + \begin{funcdesc}{sum}{sequence\optional{, start}} Sums \var{start} and the items of a \var{sequence}, from left to right, and returns the total. \var{start} defaults to \code{0}. @@ -960,16 +919,6 @@ class C(B): \versionadded{2.2} \end{funcdesc} -\begin{funcdesc}{str}{\optional{object}} - Return a string containing a nicely printable representation of an - object. For strings, this returns the string itself. The - difference with \code{repr(\var{object})} is that - \code{str(\var{object})} does not always attempt to return a string - that is acceptable to \function{eval()}; its goal is to return a - printable string. If no argument is given, returns the empty - string, \code{''}. -\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 @@ -1084,3 +1033,71 @@ It's a function With a single sequence argument, it returns a list of 1-tuples. \versionadded{2.0} \end{funcdesc} + + +% --------------------------------------------------------------------------- + + +\section{Non-essential Built-in Functions \label{non-essential-built-in-funcs}} + +There are several built-in functions that are no longer essential to learn, +know or use in modern Python programming. They have been kept here to +maintain backwards compatability with programs written for older versions +of Python. + +Python programmers, trainers, students and bookwriters should feel free to +bypass these functions without concerns about missing something important. + + +\setindexsubitem{(non-essential built-in functions)} + +\begin{funcdesc}{apply}{function, args\optional{, keywords}} + The \var{function} argument must be a callable object (a + user-defined or built-in function or method, or a class object) and + the \var{args} argument must be a sequence. The \var{function} is + called with \var{args} as the argument list; the number of arguments + is the length of the tuple. + If the optional \var{keywords} argument is present, it must be a + dictionary whose keys are strings. It specifies keyword arguments + to be added to the end of the argument list. + Calling \function{apply()} is different from just calling + \code{\var{function}(\var{args})}, since in that case there is always + exactly one argument. The use of \function{apply()} is equivalent + to \code{\var{function}(*\var{args}, **\var{keywords})}. + Use of \function{apply()} is not necessary since the ``extended call + syntax,'' as used in the last example, is completely equivalent. + + \deprecated{2.3}{Use the extended call syntax instead, as described + above.} +\end{funcdesc} + +\begin{funcdesc}{buffer}{object\optional{, offset\optional{, size}}} + The \var{object} argument must be an object that supports the buffer + call interface (such as strings, arrays, and buffers). A new buffer + object will be created which references the \var{object} argument. + The buffer object will be a slice from the beginning of \var{object} + (or from the specified \var{offset}). The slice will extend to the + end of \var{object} (or will have a length given by the \var{size} + argument). +\end{funcdesc} + +\begin{funcdesc}{coerce}{x, y} + Return a tuple consisting of the two numeric arguments converted to + a common type, using the same rules as used by arithmetic + operations. +\end{funcdesc} + +\begin{funcdesc}{intern}{string} + Enter \var{string} in the table of ``interned'' strings and return + the interned string -- which is \var{string} itself or a copy. + Interning strings is useful to gain a little performance on + dictionary lookup -- if the keys in a dictionary are interned, and + the lookup key is interned, the key comparisons (after hashing) can + be done by a pointer compare instead of a string compare. Normally, + the names used in Python programs are automatically interned, and + the dictionaries used to hold module, class or instance attributes + have interned keys. \versionchanged[Interned strings are not + immortal (like they used to be in Python 2.2 and before); + you must keep a reference to the return value of \function{intern()} + around to benefit from it]{2.3} +\end{funcdesc} -- 2.47.3