blob: 210fec4c157e38b10e37fbd56c6590ab5636fbdd [file] [log] [blame]
Fred Drake295da241998-08-10 19:42:37 +00001\section{Built-in Functions \label{built-in-funcs}}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +00002
3The Python interpreter has a number of functions built into it that
4are always available. They are listed here in alphabetical order.
5
6
Fred Drake19479911998-02-13 06:58:54 +00007\setindexsubitem{(built-in function)}
Guido van Rossum7974b0f1997-10-05 18:53:00 +00008
9\begin{funcdesc}{__import__}{name\optional{, globals\optional{, locals\optional{, fromlist}}}}
Fred Drake53525371998-03-03 21:56:15 +000010This function is invoked by the \keyword{import} statement. It
Guido van Rossum7974b0f1997-10-05 18:53:00 +000011mainly exists so that you can replace it with another
12function that has a compatible interface, in order to change the
Fred Drake53525371998-03-03 21:56:15 +000013semantics of the \keyword{import} statement. For examples of why and
Fred Drake0a73d4d1998-04-02 18:46:44 +000014how you would do this, see the standard library modules
Fred Drake53525371998-03-03 21:56:15 +000015\module{ihooks} and \module{rexec}. See also the built-in module
16\module{imp}, which defines some useful operations out of which you can
17build your own \function{__import__()} function.
Guido van Rossum7974b0f1997-10-05 18:53:00 +000018\stindex{import}
Fred Drakee14388c1997-12-15 22:28:38 +000019\refstmodindex{ihooks}
20\refstmodindex{rexec}
21\refbimodindex{imp}
Guido van Rossum7974b0f1997-10-05 18:53:00 +000022
Fred Drake53525371998-03-03 21:56:15 +000023For example, the statement `\code{import} \code{spam}' results in the
Fred Drake315b5d81998-02-13 21:26:35 +000024following call:
25\code{__import__('spam',} \code{globals(),} \code{locals(), [])};
26the statement \code{from} \code{spam.ham import} \code{eggs} results
27in \code{__import__('spam.ham',} \code{globals(),} \code{locals(),}
28\code{['eggs'])}.
Guido van Rossum7974b0f1997-10-05 18:53:00 +000029Note that even though \code{locals()} and \code{['eggs']} are passed
Fred Drake53525371998-03-03 21:56:15 +000030in as arguments, the \function{__import__()} function does not set the
Guido van Rossum7974b0f1997-10-05 18:53:00 +000031local variable named \code{eggs}; this is done by subsequent code that
32is generated for the import statement. (In fact, the standard
33implementation does not use its \var{locals} argument at all, and uses
34its \var{globals} only to determine the package context of the
Fred Drake53525371998-03-03 21:56:15 +000035\keyword{import} statement.)
Guido van Rossum7974b0f1997-10-05 18:53:00 +000036
37When the \var{name} variable is of the form \code{package.module},
38normally, the top-level package (the name up till the first dot) is
39returned, \emph{not} the module named by \var{name}. However, when a
40non-empty \var{fromlist} argument is given, the module named by
41\var{name} is returned. This is done for compatibility with the
42bytecode generated for the different kinds of import statement; when
Fred Drake53525371998-03-03 21:56:15 +000043using \samp{import spam.ham.eggs}, the top-level package \code{spam}
44must be placed in the importing namespace, but when using \samp{from
Guido van Rossum7974b0f1997-10-05 18:53:00 +000045spam.ham import eggs}, the \code{spam.ham} subpackage must be used to
46find the \code{eggs} variable.
Guido van Rossum8c2da611998-12-04 15:32:17 +000047As a workaround for this behavior, use \function{getattr()} to extract
48the desired components. For example, you could define the following
49helper:
50
51\begin{verbatim}
52import string
53
54def my_import(name):
55 mod = __import__(name)
56 components = string.split(name, '.')
57 for comp in components[1:]:
58 mod = getattr(mod, comp)
59 return mod
60\end{verbatim}
61
Guido van Rossum7974b0f1997-10-05 18:53:00 +000062\end{funcdesc}
63
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000064\begin{funcdesc}{abs}{x}
65 Return the absolute value of a number. The argument may be a plain
Guido van Rossum921f32c1997-06-02 17:21:20 +000066 or long integer or a floating point number. If the argument is a
Guido van Rossum7974b0f1997-10-05 18:53:00 +000067 complex number, its magnitude is returned.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000068\end{funcdesc}
69
Fred Drakecce10901998-03-17 06:33:25 +000070\begin{funcdesc}{apply}{function, args\optional{, keywords}}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000071The \var{function} argument must be a callable object (a user-defined or
72built-in function or method, or a class object) and the \var{args}
Barry Warsawb2031f71998-10-01 15:35:43 +000073argument must be a sequence (if it is not a tuple, the sequence is
74first converted to a tuple). The \var{function} is called with
75\var{args} as the argument list; the number of arguments is the the length
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000076of the tuple. (This is different from just calling
77\code{\var{func}(\var{args})}, since in that case there is always
78exactly one argument.)
Guido van Rossum0568d5e1995-10-08 01:06:46 +000079If the optional \var{keywords} argument is present, it must be a
80dictionary whose keys are strings. It specifies keyword arguments to
81be added to the end of the the argument list.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000082\end{funcdesc}
83
Guido van Rossum7974b0f1997-10-05 18:53:00 +000084\begin{funcdesc}{callable}{object}
85Return true if the \var{object} argument appears callable, false if
86not. If this returns true, it is still possible that a call fails,
87but if it is false, calling \var{object} will never succeed. Note
88that classes are callable (calling a class returns a new instance);
Fred Drake53525371998-03-03 21:56:15 +000089class instances are callable if they have a \method{__call__()} method.
Guido van Rossum7974b0f1997-10-05 18:53:00 +000090\end{funcdesc}
91
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000092\begin{funcdesc}{chr}{i}
93 Return a string of one character whose \ASCII{} code is the integer
94 \var{i}, e.g., \code{chr(97)} returns the string \code{'a'}. This is the
Fred Drake53525371998-03-03 21:56:15 +000095 inverse of \function{ord()}. The argument must be in the range [0..255],
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000096 inclusive.
97\end{funcdesc}
98
Fred Drakecce10901998-03-17 06:33:25 +000099\begin{funcdesc}{cmp}{x, y}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000100 Compare the two objects \var{x} and \var{y} and return an integer
101 according to the outcome. The return value is negative if \code{\var{x}
102 < \var{y}}, zero if \code{\var{x} == \var{y}} and strictly positive if
103 \code{\var{x} > \var{y}}.
104\end{funcdesc}
105
Fred Drakecce10901998-03-17 06:33:25 +0000106\begin{funcdesc}{coerce}{x, y}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000107 Return a tuple consisting of the two numeric arguments converted to
108 a common type, using the same rules as used by arithmetic
109 operations.
110\end{funcdesc}
111
Fred Drakecce10901998-03-17 06:33:25 +0000112\begin{funcdesc}{compile}{string, filename, kind}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000113 Compile the \var{string} into a code object. Code objects can be
Fred Drake53525371998-03-03 21:56:15 +0000114 executed by an \keyword{exec} statement or evaluated by a call to
115 \function{eval()}. The \var{filename} argument should
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000116 give the file from which the code was read; pass e.g. \code{'<string>'}
117 if it wasn't read from a file. The \var{kind} argument specifies
118 what kind of code must be compiled; it can be \code{'exec'} if
Guido van Rossumfb502e91995-07-07 22:58:28 +0000119 \var{string} consists of a sequence of statements, \code{'eval'}
120 if it consists of a single expression, or \code{'single'} if
121 it consists of a single interactive statement (in the latter case,
122 expression statements that evaluate to something else than
123 \code{None} will printed).
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000124\end{funcdesc}
125
Guido van Rossum1cd26f21997-04-02 06:04:02 +0000126\begin{funcdesc}{complex}{real\optional{, imag}}
127 Create a complex number with the value \var{real} + \var{imag}*j.
128 Each argument may be any numeric type (including complex).
129 If \var{imag} is omitted, it defaults to zero and the function
Fred Drake53525371998-03-03 21:56:15 +0000130 serves as a numeric conversion function like \function{int()},
131 \function{long()} and \function{float()}.
Guido van Rossum1cd26f21997-04-02 06:04:02 +0000132\end{funcdesc}
133
Fred Drakecce10901998-03-17 06:33:25 +0000134\begin{funcdesc}{delattr}{object, name}
Fred Drake53525371998-03-03 21:56:15 +0000135 This is a relative of \function{setattr()}. The arguments are an
Guido van Rossum1efbb0f1994-08-16 22:15:11 +0000136 object and a string. The string must be the name
137 of one of the object's attributes. The function deletes
138 the named attribute, provided the object allows it. For example,
Guido van Rossum6c4f0031995-03-07 10:14:09 +0000139 \code{delattr(\var{x}, '\var{foobar}')} is equivalent to
Guido van Rossum1efbb0f1994-08-16 22:15:11 +0000140 \code{del \var{x}.\var{foobar}}.
141\end{funcdesc}
142
Fred Drake6b303b41998-04-16 22:10:27 +0000143\begin{funcdesc}{dir}{\optional{object}}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000144 Without arguments, return the list of names in the current local
Guido van Rossumeb0f0661997-12-30 20:38:16 +0000145 symbol table. With an argument, attempts to return a list of valid
146 attribute for that object. This information is gleaned from the
Fred Drake53525371998-03-03 21:56:15 +0000147 object's \member{__dict__}, \member{__methods__} and \member{__members__}
Guido van Rossumeb0f0661997-12-30 20:38:16 +0000148 attributes, if defined. The list is not necessarily complete; e.g.,
149 for classes, attributes defined in base classes are not included,
150 and for class instances, methods are not included.
151 The resulting list is sorted alphabetically. For example:
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000152
Fred Drake19479911998-02-13 06:58:54 +0000153\begin{verbatim}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000154>>> import sys
155>>> dir()
156['sys']
157>>> dir(sys)
158['argv', 'exit', 'modules', 'path', 'stderr', 'stdin', 'stdout']
159>>>
Fred Drake19479911998-02-13 06:58:54 +0000160\end{verbatim}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000161\end{funcdesc}
162
Fred Drakecce10901998-03-17 06:33:25 +0000163\begin{funcdesc}{divmod}{a, b}
Guido van Rossumeb0f0661997-12-30 20:38:16 +0000164 Take two numbers as arguments and return a pair of numbers consisting
165 of their quotient and remainder when using long division. With mixed
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000166 operand types, the rules for binary arithmetic operators apply. For
167 plain and long integers, the result is the same as
168 \code{(\var{a} / \var{b}, \var{a} \%{} \var{b})}.
169 For floating point numbers the result is the same as
170 \code{(math.floor(\var{a} / \var{b}), \var{a} \%{} \var{b})}.
171\end{funcdesc}
172
Fred Drakecce10901998-03-17 06:33:25 +0000173\begin{funcdesc}{eval}{expression\optional{, globals\optional{, locals}}}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000174 The arguments are a string and two optional dictionaries. The
Guido van Rossumf8601621995-01-10 10:50:24 +0000175 \var{expression} argument is parsed and evaluated as a Python
176 expression (technically speaking, a condition list) using the
177 \var{globals} and \var{locals} dictionaries as global and local name
Guido van Rossum470be141995-03-17 16:07:09 +0000178 space. If the \var{locals} dictionary is omitted it defaults to
179 the \var{globals} dictionary. If both dictionaries are omitted, the
Fred Drake53525371998-03-03 21:56:15 +0000180 expression is executed in the environment where \keyword{eval} is
Guido van Rossumf8601621995-01-10 10:50:24 +0000181 called. The return value is the result of the evaluated expression.
182 Syntax errors are reported as exceptions. Example:
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000183
Fred Drake19479911998-02-13 06:58:54 +0000184\begin{verbatim}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000185>>> x = 1
186>>> print eval('x+1')
1872
Fred Drake19479911998-02-13 06:58:54 +0000188\end{verbatim}
Fred Drake53525371998-03-03 21:56:15 +0000189
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000190 This function can also be used to execute arbitrary code objects
Fred Drake53525371998-03-03 21:56:15 +0000191 (e.g.\ created by \function{compile()}). In this case pass a code
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000192 object instead of a string. The code object must have been compiled
193 passing \code{'eval'} to the \var{kind} argument.
194
Guido van Rossum6c4f0031995-03-07 10:14:09 +0000195 Hints: dynamic execution of statements is supported by the
Fred Drake53525371998-03-03 21:56:15 +0000196 \keyword{exec} statement. Execution of statements from a file is
197 supported by the \function{execfile()} function. The
198 \function{globals()} and \function{locals()} functions returns the
199 current global and local dictionary, respectively, which may be
200 useful to pass around for use by \function{eval()} or
201 \function{execfile()}.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000202\end{funcdesc}
203
Fred Drakecce10901998-03-17 06:33:25 +0000204\begin{funcdesc}{execfile}{file\optional{, globals\optional{, locals}}}
Guido van Rossum470be141995-03-17 16:07:09 +0000205 This function is similar to the
Fred Drake53525371998-03-03 21:56:15 +0000206 \keyword{exec} statement, but parses a file instead of a string. It
207 is different from the \keyword{import} statement in that it does not
208 use the module administration --- it reads the file unconditionally
209 and does not create a new module.\footnote{It is used relatively
210 rarely so does not warrant being made into a statement.}
Guido van Rossumf8601621995-01-10 10:50:24 +0000211
212 The arguments are a file name and two optional dictionaries. The
213 file is parsed and evaluated as a sequence of Python statements
214 (similarly to a module) using the \var{globals} and \var{locals}
Guido van Rossum470be141995-03-17 16:07:09 +0000215 dictionaries as global and local name space. If the \var{locals}
216 dictionary is omitted it defaults to the \var{globals} dictionary.
Guido van Rossumf8601621995-01-10 10:50:24 +0000217 If both dictionaries are omitted, the expression is executed in the
Fred Drake53525371998-03-03 21:56:15 +0000218 environment where \function{execfile()} is called. The return value is
Guido van Rossum470be141995-03-17 16:07:09 +0000219 \code{None}.
Guido van Rossumf8601621995-01-10 10:50:24 +0000220\end{funcdesc}
221
Fred Drakecce10901998-03-17 06:33:25 +0000222\begin{funcdesc}{filter}{function, list}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000223Construct a list from those elements of \var{list} for which
224\var{function} returns true. If \var{list} is a string or a tuple,
225the result also has that type; otherwise it is always a list. If
226\var{function} is \code{None}, the identity function is assumed,
Guido van Rossum6c4f0031995-03-07 10:14:09 +0000227i.e.\ all elements of \var{list} that are false (zero or empty) are
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000228removed.
229\end{funcdesc}
230
231\begin{funcdesc}{float}{x}
Guido van Rossum1cd26f21997-04-02 06:04:02 +0000232 Convert a string or a number to floating point. If the argument is a
Fred Draked83675f1998-12-07 17:13:18 +0000233 string, it must contain a possibly signed decimal or floating point
Fred Drake70a66c91999-02-18 16:08:36 +0000234 number, possibly embedded in whitespace; this behaves identical to
235 \code{string.atof(\var{x})}. Otherwise, the argument may be a plain
236 or long integer or a floating point number, and a floating point
237 number with the same value (within Python's floating point
238 precision) is returned.
239
240 \strong{Note:} When passing in a string, values for NaN\index{NaN}
241 and Infinity\index{Infinity} may be returned, depending on the
242 underlying C library. The specific set of strings accepted which
243 cause these values to be returned depends entirely on the C library
244 and is known to vary.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000245\end{funcdesc}
246
Fred Drakecce10901998-03-17 06:33:25 +0000247\begin{funcdesc}{getattr}{object, name}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000248 The arguments are an object and a string. The string must be the
Fred Drake53525371998-03-03 21:56:15 +0000249 name of one of the object's attributes. The result is the value of
250 that attribute. For example, \code{getattr(\var{x},
251 '\var{foobar}')} is equivalent to \code{\var{x}.\var{foobar}}.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000252\end{funcdesc}
253
Guido van Rossumfb502e91995-07-07 22:58:28 +0000254\begin{funcdesc}{globals}{}
255Return a dictionary representing the current global symbol table.
256This is always the dictionary of the current module (inside a
257function or method, this is the module where it is defined, not the
258module from which it is called).
259\end{funcdesc}
260
Fred Drakecce10901998-03-17 06:33:25 +0000261\begin{funcdesc}{hasattr}{object, name}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000262 The arguments are an object and a string. The result is 1 if the
263 string is the name of one of the object's attributes, 0 if not.
Fred Drake53525371998-03-03 21:56:15 +0000264 (This is implemented by calling \code{getattr(\var{object},
265 \var{name})} and seeing whether it raises an exception or not.)
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000266\end{funcdesc}
267
268\begin{funcdesc}{hash}{object}
269 Return the hash value of the object (if it has one). Hash values
Guido van Rossumeb0f0661997-12-30 20:38:16 +0000270 are integers. They are used to quickly compare dictionary
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000271 keys during a dictionary lookup. Numeric values that compare equal
272 have the same hash value (even if they are of different types, e.g.
273 1 and 1.0).
274\end{funcdesc}
275
276\begin{funcdesc}{hex}{x}
Guido van Rossum470be141995-03-17 16:07:09 +0000277 Convert an integer number (of any size) to a hexadecimal string.
Guido van Rossum5cd75201997-01-14 18:44:23 +0000278 The result is a valid Python expression. Note: this always yields
279 an unsigned literal, e.g. on a 32-bit machine, \code{hex(-1)} yields
280 \code{'0xffffffff'}. When evaluated on a machine with the same
281 word size, this literal is evaluated as -1; at a different word
282 size, it may turn up as a large positive number or raise an
Fred Drake53525371998-03-03 21:56:15 +0000283 \exception{OverflowError} exception.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000284\end{funcdesc}
285
286\begin{funcdesc}{id}{object}
287 Return the `identity' of an object. This is an integer which is
288 guaranteed to be unique and constant for this object during its
289 lifetime. (Two objects whose lifetimes are disjunct may have the
Fred Drake53525371998-03-03 21:56:15 +0000290 same \function{id()} value.) (Implementation note: this is the
291 address of the object.)
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000292\end{funcdesc}
293
Guido van Rossum16d6e711994-08-08 12:30:22 +0000294\begin{funcdesc}{input}{\optional{prompt}}
Guido van Rossum777dcc61998-06-17 15:16:40 +0000295 Equivalent to \code{eval(raw_input(\var{prompt}))}.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000296\end{funcdesc}
297
Guido van Rossum3978d751997-03-03 16:03:27 +0000298\begin{funcdesc}{intern}{string}
299 Enter \var{string} in the table of ``interned'' strings and return
300 the interned string -- which is \var{string} itself or a copy.
301 Interning strings is useful to gain a little performance on
302 dictionary lookup -- if the keys in a dictionary are interned, and
303 the lookup key is interned, the key comparisons (after hashing) can
304 be done by a pointer compare instead of a string compare. Normally,
305 the names used in Python programs are automatically interned, and
306 the dictionaries used to hold module, class or instance attributes
307 have interned keys. Interned strings are immortal (i.e. never get
308 garbage collected).
309\end{funcdesc}
310
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000311\begin{funcdesc}{int}{x}
Guido van Rossum1cd26f21997-04-02 06:04:02 +0000312 Convert a string or number to a plain integer. If the argument is a
Fred Draked83675f1998-12-07 17:13:18 +0000313 string, it must contain a possibly signed decimal number
Guido van Rossum1cd26f21997-04-02 06:04:02 +0000314 representable as a Python integer, possibly embedded in whitespace;
315 this behaves identical to \code{string.atoi(\var{x})}.
316 Otherwise, the argument may be a plain or
Guido van Rossum470be141995-03-17 16:07:09 +0000317 long integer or a floating point number. Conversion of floating
318 point numbers to integers is defined by the C semantics; normally
Guido van Rossumecde7811995-03-28 13:35:14 +0000319 the conversion truncates towards zero.\footnote{This is ugly --- the
320 language definition should require truncation towards zero.}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000321\end{funcdesc}
322
Guido van Rossum7974b0f1997-10-05 18:53:00 +0000323\begin{funcdesc}{isinstance}{object, class}
324Return true if the \var{object} argument is an instance of the
325\var{class} argument, or of a (direct or indirect) subclass thereof.
Guido van Rossum3593e5c1997-12-02 19:15:01 +0000326Also return true if \var{class} is a type object and \var{object} is
327an object of that type. If \var{object} is not a class instance or a
328object of the given type, the function always returns false. If
329\var{class} is neither a class object nor a type object, a
Fred Drake53525371998-03-03 21:56:15 +0000330\exception{TypeError} exception is raised.
Guido van Rossum7974b0f1997-10-05 18:53:00 +0000331\end{funcdesc}
332
333\begin{funcdesc}{issubclass}{class1, class2}
334Return true if \var{class1} is a subclass (direct or indirect) of
335\var{class2}. A class is considered a subclass of itself. If either
Fred Drake53525371998-03-03 21:56:15 +0000336argument is not a class object, a \exception{TypeError} exception is
337raised.
Guido van Rossum7974b0f1997-10-05 18:53:00 +0000338\end{funcdesc}
339
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000340\begin{funcdesc}{len}{s}
341 Return the length (the number of items) of an object. The argument
342 may be a sequence (string, tuple or list) or a mapping (dictionary).
343\end{funcdesc}
344
Guido van Rossum921f32c1997-06-02 17:21:20 +0000345\begin{funcdesc}{list}{sequence}
346Return a list whose items are the same and in the same order as
347\var{sequence}'s items. If \var{sequence} is already a list,
348a copy is made and returned, similar to \code{\var{sequence}[:]}.
349For instance, \code{list('abc')} returns
350returns \code{['a', 'b', 'c']} and \code{list( (1, 2, 3) )} returns
351\code{[1, 2, 3]}.
352\end{funcdesc}
353
Guido van Rossumfb502e91995-07-07 22:58:28 +0000354\begin{funcdesc}{locals}{}
355Return a dictionary representing the current local symbol table.
Guido van Rossum7b7f6681998-06-18 16:45:34 +0000356\strong{Warning:} the contents of this dictionary should not be
357modified; changes may not affect the values of local variables used by
358the interpreter.
Guido van Rossumfb502e91995-07-07 22:58:28 +0000359\end{funcdesc}
360
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000361\begin{funcdesc}{long}{x}
Guido van Rossum1cd26f21997-04-02 06:04:02 +0000362 Convert a string or number to a long integer. If the argument is a
Fred Draked83675f1998-12-07 17:13:18 +0000363 string, it must contain a possibly signed decimal number of
Guido van Rossum1cd26f21997-04-02 06:04:02 +0000364 arbitrary size, possibly embedded in whitespace;
365 this behaves identical to \code{string.atol(\var{x})}.
366 Otherwise, the argument may be a plain or
Guido van Rossumeb0f0661997-12-30 20:38:16 +0000367 long integer or a floating point number, and a long integer with
Guido van Rossum1cd26f21997-04-02 06:04:02 +0000368 the same value is returned. Conversion of floating
369 point numbers to integers is defined by the C semantics;
Fred Drake53525371998-03-03 21:56:15 +0000370 see the description of \function{int()}.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000371\end{funcdesc}
372
Fred Drakecce10901998-03-17 06:33:25 +0000373\begin{funcdesc}{map}{function, list, ...}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000374Apply \var{function} to every item of \var{list} and return a list
375of the results. If additional \var{list} arguments are passed,
376\var{function} must take that many arguments and is applied to
377the items of all lists in parallel; if a list is shorter than another
378it is assumed to be extended with \code{None} items. If
379\var{function} is \code{None}, the identity function is assumed; if
Fred Drake53525371998-03-03 21:56:15 +0000380there are multiple list arguments, \function{map()} returns a list
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000381consisting of tuples containing the corresponding items from all lists
382(i.e. a kind of transpose operation). The \var{list} arguments may be
383any kind of sequence; the result is always a list.
384\end{funcdesc}
385
Guido van Rossum5eabf381998-11-25 18:53:05 +0000386\begin{funcdesc}{max}{s\optional{, args...}}
387With a single argument \var{s}, return the largest item of a
388non-empty sequence (e.g., a string, tuple or list). With more than
389one argument, return the largest of the arguments.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000390\end{funcdesc}
391
Guido van Rossum5eabf381998-11-25 18:53:05 +0000392\begin{funcdesc}{min}{s\optional{, args...}}
393With a single argument \var{s}, return the smallest item of a
394non-empty sequence (e.g., a string, tuple or list). With more than
395one argument, return the smallest of the arguments.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000396\end{funcdesc}
397
398\begin{funcdesc}{oct}{x}
Guido van Rossum470be141995-03-17 16:07:09 +0000399 Convert an integer number (of any size) to an octal string. The
Guido van Rossum5cd75201997-01-14 18:44:23 +0000400 result is a valid Python expression. Note: this always yields
401 an unsigned literal, e.g. on a 32-bit machine, \code{oct(-1)} yields
402 \code{'037777777777'}. When evaluated on a machine with the same
403 word size, this literal is evaluated as -1; at a different word
404 size, it may turn up as a large positive number or raise an
Fred Drake53525371998-03-03 21:56:15 +0000405 \exception{OverflowError} exception.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000406\end{funcdesc}
407
Fred Drakecce10901998-03-17 06:33:25 +0000408\begin{funcdesc}{open}{filename\optional{, mode\optional{, bufsize}}}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000409 Return a new file object (described earlier under Built-in Types).
Guido van Rossum041be051994-05-03 14:46:50 +0000410 The first two arguments are the same as for \code{stdio}'s
Fred Drake53525371998-03-03 21:56:15 +0000411 \cfunction{fopen()}: \var{filename} is the file name to be opened,
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000412 \var{mode} indicates how the file is to be opened: \code{'r'} for
413 reading, \code{'w'} for writing (truncating an existing file), and
Fred Drakeaf8a0151998-01-14 14:51:31 +0000414 \code{'a'} opens it for appending (which on \emph{some} \UNIX{}
415 systems means that \emph{all} writes append to the end of the file,
Guido van Rossum59b328e1996-05-02 15:16:59 +0000416 regardless of the current seek position).
Guido van Rossum5fdd1191998-07-29 21:05:35 +0000417
418 Modes \code{'r+'}, \code{'w+'} and \code{'a+'} open the file for
419 updating (note that \code{'w+'} truncates the file). Append
420 \code{'b'} to the mode to open the file in binary mode, on systems
421 that differentiate between binary and text files (else it is
422 ignored). If the file cannot be opened, \exception{IOError} is
423 raised.
424
Guido van Rossum041be051994-05-03 14:46:50 +0000425If \var{mode} is omitted, it defaults to \code{'r'}.
426The optional \var{bufsize} argument specifies the file's desired
427buffer size: 0 means unbuffered, 1 means line buffered, any other
428positive value means use a buffer of (approximately) that size. A
429negative \var{bufsize} means to use the system default, which is
430usually line buffered for for tty devices and fully buffered for other
Fred Drake2510d221998-11-02 18:57:34 +0000431files. If omitted, the system default is used.%
Guido van Rossum041be051994-05-03 14:46:50 +0000432\footnote{Specifying a buffer size currently has no effect on systems
Fred Drake53525371998-03-03 21:56:15 +0000433that don't have \cfunction{setvbuf()}. The interface to specify the buffer
434size is not done using a method that calls \cfunction{setvbuf()}, because
Guido van Rossum041be051994-05-03 14:46:50 +0000435that may dump core when called after any I/O has been performed, and
436there's no reliable way to determine whether this is the case.}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000437\end{funcdesc}
438
439\begin{funcdesc}{ord}{c}
440 Return the \ASCII{} value of a string of one character. E.g.,
441 \code{ord('a')} returns the integer \code{97}. This is the inverse of
Fred Drake53525371998-03-03 21:56:15 +0000442 \function{chr()}.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000443\end{funcdesc}
444
Fred Drakecce10901998-03-17 06:33:25 +0000445\begin{funcdesc}{pow}{x, y\optional{, z}}
Guido van Rossumb8b264b1994-08-12 13:13:50 +0000446 Return \var{x} to the power \var{y}; if \var{z} is present, return
447 \var{x} to the power \var{y}, modulo \var{z} (computed more
Fred Drake6251c161998-04-03 07:15:54 +0000448 efficiently than \code{pow(\var{x}, \var{y}) \%\ \var{z}}).
Guido van Rossumb8b264b1994-08-12 13:13:50 +0000449 The arguments must have
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000450 numeric types. With mixed operand types, the rules for binary
451 arithmetic operators apply. The effective operand type is also the
452 type of the result; if the result is not expressible in this type, the
Guido van Rossum16d6e711994-08-08 12:30:22 +0000453 function raises an exception; e.g., \code{pow(2, -1)} or \code{pow(2,
454 35000)} is not allowed.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000455\end{funcdesc}
456
Fred Drakecce10901998-03-17 06:33:25 +0000457\begin{funcdesc}{range}{\optional{start,} stop\optional{, step}}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000458 This is a versatile function to create lists containing arithmetic
Fred Drake53525371998-03-03 21:56:15 +0000459 progressions. It is most often used in \keyword{for} loops. The
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000460 arguments must be plain integers. If the \var{step} argument is
461 omitted, it defaults to \code{1}. If the \var{start} argument is
462 omitted, it defaults to \code{0}. The full form returns a list of
463 plain integers \code{[\var{start}, \var{start} + \var{step},
464 \var{start} + 2 * \var{step}, \ldots]}. If \var{step} is positive,
465 the last element is the largest \code{\var{start} + \var{i} *
Guido van Rossum7974b0f1997-10-05 18:53:00 +0000466 \var{step}} less than \var{stop}; if \var{step} is negative, the last
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000467 element is the largest \code{\var{start} + \var{i} * \var{step}}
Fred Drake6251c161998-04-03 07:15:54 +0000468 greater than \var{stop}. \var{step} must not be zero (or else
469 \exception{ValueError} is raised). Example:
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000470
Fred Drake19479911998-02-13 06:58:54 +0000471\begin{verbatim}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000472>>> range(10)
473[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
474>>> range(1, 11)
475[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
476>>> range(0, 30, 5)
477[0, 5, 10, 15, 20, 25]
478>>> range(0, 10, 3)
479[0, 3, 6, 9]
480>>> range(0, -10, -1)
481[0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
482>>> range(0)
483[]
484>>> range(1, 0)
485[]
486>>>
Fred Drake19479911998-02-13 06:58:54 +0000487\end{verbatim}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000488\end{funcdesc}
489
Guido van Rossum16d6e711994-08-08 12:30:22 +0000490\begin{funcdesc}{raw_input}{\optional{prompt}}
491 If the \var{prompt} argument is present, it is written to standard output
492 without a trailing newline. The function then reads a line from input,
493 converts it to a string (stripping a trailing newline), and returns that.
Fred Drake53525371998-03-03 21:56:15 +0000494 When \EOF{} is read, \exception{EOFError} is raised. Example:
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000495
Fred Drake19479911998-02-13 06:58:54 +0000496\begin{verbatim}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000497>>> s = raw_input('--> ')
498--> Monty Python's Flying Circus
499>>> s
Guido van Rossum470be141995-03-17 16:07:09 +0000500"Monty Python's Flying Circus"
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000501>>>
Fred Drake19479911998-02-13 06:58:54 +0000502\end{verbatim}
Guido van Rossum921f32c1997-06-02 17:21:20 +0000503
Fred Drake53525371998-03-03 21:56:15 +0000504If the \module{readline} module was loaded, then
505\function{raw_input()} will use it to provide elaborate
Guido van Rossum921f32c1997-06-02 17:21:20 +0000506line editing and history features.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000507\end{funcdesc}
508
Guido van Rossum87e611e1999-01-06 23:10:51 +0000509\begin{funcdesc}{reduce}{function, sequence\optional{, initializer}}
510Apply \var{function} of two arguments cumulatively to the items of
511\var{sequence}, from left to right, so as to reduce the sequence to
512a single value. For example,
513\code{reduce(lambda x, y: x+y, [1, 2, 3, 4, 5])} calculates
514\code{((((1+2)+3)+4)+5)}.
515If the optional \var{initializer} is present, it is placed before the
516items of the sequence in the calculation, and serves as a default when
517the sequence is empty.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000518\end{funcdesc}
519
520\begin{funcdesc}{reload}{module}
Guido van Rossum470be141995-03-17 16:07:09 +0000521Re-parse and re-initialize an already imported \var{module}. The
522argument must be a module object, so it must have been successfully
523imported before. This is useful if you have edited the module source
524file using an external editor and want to try out the new version
525without leaving the Python interpreter. The return value is the
526module object (i.e.\ the same as the \var{module} argument).
527
528There are a number of caveats:
529
530If a module is syntactically correct but its initialization fails, the
Fred Drake53525371998-03-03 21:56:15 +0000531first \keyword{import} statement for it does not bind its name locally,
Guido van Rossum470be141995-03-17 16:07:09 +0000532but does store a (partially initialized) module object in
533\code{sys.modules}. To reload the module you must first
Fred Drake53525371998-03-03 21:56:15 +0000534\keyword{import} it again (this will bind the name to the partially
535initialized module object) before you can \function{reload()} it.
Guido van Rossum470be141995-03-17 16:07:09 +0000536
537When a module is reloaded, its dictionary (containing the module's
538global variables) is retained. Redefinitions of names will override
539the old definitions, so this is generally not a problem. If the new
540version of a module does not define a name that was defined by the old
541version, the old definition remains. This feature can be used to the
542module's advantage if it maintains a global table or cache of objects
Fred Drake53525371998-03-03 21:56:15 +0000543--- with a \keyword{try} statement it can test for the table's presence
Guido van Rossum470be141995-03-17 16:07:09 +0000544and skip its initialization if desired.
545
546It is legal though generally not very useful to reload built-in or
Fred Drake53525371998-03-03 21:56:15 +0000547dynamically loaded modules, except for \module{sys}, \module{__main__}
548and \module{__builtin__}. In certain cases, however, extension
549modules are not designed to be initialized more than once, and may
550fail in arbitrary ways when reloaded.
Guido van Rossum470be141995-03-17 16:07:09 +0000551
Fred Drake53525371998-03-03 21:56:15 +0000552If a module imports objects from another module using \keyword{from}
553\ldots{} \keyword{import} \ldots{}, calling \function{reload()} for
554the other module does not redefine the objects imported from it ---
555one way around this is to re-execute the \keyword{from} statement,
556another is to use \keyword{import} and qualified names
557(\var{module}.\var{name}) instead.
Guido van Rossum470be141995-03-17 16:07:09 +0000558
559If a module instantiates instances of a class, reloading the module
560that defines the class does not affect the method definitions of the
561instances --- they continue to use the old class definition. The same
562is true for derived classes.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000563\end{funcdesc}
564
565\begin{funcdesc}{repr}{object}
566Return a string containing a printable representation of an object.
567This is the same value yielded by conversions (reverse quotes).
568It is sometimes useful to be able to access this operation as an
569ordinary function. For many types, this function makes an attempt
570to return a string that would yield an object with the same value
Fred Drake53525371998-03-03 21:56:15 +0000571when passed to \function{eval()}.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000572\end{funcdesc}
573
Fred Drake607f8021998-08-24 20:30:07 +0000574\begin{funcdesc}{round}{x\optional{, n}}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000575 Return the floating point value \var{x} rounded to \var{n} digits
576 after the decimal point. If \var{n} is omitted, it defaults to zero.
577 The result is a floating point number. Values are rounded to the
578 closest multiple of 10 to the power minus \var{n}; if two multiples
579 are equally close, rounding is done away from 0 (so e.g.
580 \code{round(0.5)} is \code{1.0} and \code{round(-0.5)} is \code{-1.0}).
581\end{funcdesc}
582
Fred Drakecce10901998-03-17 06:33:25 +0000583\begin{funcdesc}{setattr}{object, name, value}
Fred Drake53525371998-03-03 21:56:15 +0000584 This is the counterpart of \function{getattr()}. The arguments are an
Fred Drake607f8021998-08-24 20:30:07 +0000585 object, a string and an arbitrary value. The string may name an
586 existing attribute or a new attribute. The function assigns the
587 value to the attribute, provided the object allows it. For example,
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000588 \code{setattr(\var{x}, '\var{foobar}', 123)} is equivalent to
589 \code{\var{x}.\var{foobar} = 123}.
590\end{funcdesc}
591
Fred Drakecce10901998-03-17 06:33:25 +0000592\begin{funcdesc}{slice}{\optional{start,} stop\optional{, step}}
Guido van Rossum7974b0f1997-10-05 18:53:00 +0000593Return a slice object representing the set of indices specified by
594\code{range(\var{start}, \var{stop}, \var{step})}. The \var{start}
595and \var{step} arguments default to None. Slice objects have
Fred Drake53525371998-03-03 21:56:15 +0000596read-only data attributes \member{start}, \member{stop} and \member{step}
Guido van Rossum7974b0f1997-10-05 18:53:00 +0000597which merely return the argument values (or their default). They have
598no other explicit functionality; however they are used by Numerical
Fred Drake6251c161998-04-03 07:15:54 +0000599Python\index{Numerical Python} and other third party extensions.
600Slice objects are also generated when extended indexing syntax is
601used, e.g. for \samp{a[start:stop:step]} or \samp{a[start:stop, i]}.
Guido van Rossum7974b0f1997-10-05 18:53:00 +0000602\end{funcdesc}
603
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000604\begin{funcdesc}{str}{object}
605Return a string containing a nicely printable representation of an
606object. For strings, this returns the string itself. The difference
Guido van Rossum6c4f0031995-03-07 10:14:09 +0000607with \code{repr(\var{object})} is that \code{str(\var{object})} does not
Fred Drake53525371998-03-03 21:56:15 +0000608always attempt to return a string that is acceptable to \function{eval()};
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000609its goal is to return a printable string.
610\end{funcdesc}
611
Guido van Rossum470be141995-03-17 16:07:09 +0000612\begin{funcdesc}{tuple}{sequence}
Guido van Rossumb8b264b1994-08-12 13:13:50 +0000613Return a tuple whose items are the same and in the same order as
Guido van Rossum921f32c1997-06-02 17:21:20 +0000614\var{sequence}'s items. If \var{sequence} is already a tuple, it
Guido van Rossumb8b264b1994-08-12 13:13:50 +0000615is returned unchanged. For instance, \code{tuple('abc')} returns
616returns \code{('a', 'b', 'c')} and \code{tuple([1, 2, 3])} returns
617\code{(1, 2, 3)}.
618\end{funcdesc}
619
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000620\begin{funcdesc}{type}{object}
Guido van Rossum470be141995-03-17 16:07:09 +0000621Return the type of an \var{object}. The return value is a type
Fred Drake53525371998-03-03 21:56:15 +0000622object. The standard module \module{types} defines names for all
Guido van Rossum470be141995-03-17 16:07:09 +0000623built-in types.
Fred Drakee14388c1997-12-15 22:28:38 +0000624\refstmodindex{types}
Guido van Rossum470be141995-03-17 16:07:09 +0000625\obindex{type}
626For instance:
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000627
Fred Drake19479911998-02-13 06:58:54 +0000628\begin{verbatim}
Guido van Rossum470be141995-03-17 16:07:09 +0000629>>> import types
Guido van Rossuma7874d11998-06-22 14:07:36 +0000630>>> if type(x) == types.StringType: print "It's a string"
Fred Drake19479911998-02-13 06:58:54 +0000631\end{verbatim}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000632\end{funcdesc}
Guido van Rossum68cfbe71994-02-24 11:28:27 +0000633
Guido van Rossum6bb1adc1995-03-13 10:03:32 +0000634\begin{funcdesc}{vars}{\optional{object}}
Guido van Rossum17383111994-04-21 10:32:28 +0000635Without arguments, return a dictionary corresponding to the current
636local symbol table. With a module, class or class instance object as
Fred Drake53525371998-03-03 21:56:15 +0000637argument (or anything else that has a \member{__dict__} attribute),
Guido van Rossum17383111994-04-21 10:32:28 +0000638returns a dictionary corresponding to the object's symbol table.
639The returned dictionary should not be modified: the effects on the
640corresponding symbol table are undefined.%
641\footnote{In the current implementation, local variable bindings
642cannot normally be affected this way, but variables retrieved from
Guido van Rossum6c4f0031995-03-07 10:14:09 +0000643other scopes (e.g. modules) can be. This may change.}
Guido van Rossum17383111994-04-21 10:32:28 +0000644\end{funcdesc}
645
Fred Drakecce10901998-03-17 06:33:25 +0000646\begin{funcdesc}{xrange}{\optional{start,} stop\optional{, step}}
Fred Drake53525371998-03-03 21:56:15 +0000647This function is very similar to \function{range()}, but returns an
Guido van Rossum68cfbe71994-02-24 11:28:27 +0000648``xrange object'' instead of a list. This is an opaque sequence type
649which yields the same values as the corresponding list, without
650actually storing them all simultaneously. The advantage of
Fred Drake53525371998-03-03 21:56:15 +0000651\function{xrange()} over \function{range()} is minimal (since
652\function{xrange()} still has to create the values when asked for
653them) except when a very large range is used on a memory-starved
654machine (e.g. MS-DOS) or when all of the range's elements are never
655used (e.g. when the loop is usually terminated with \keyword{break}).
Guido van Rossum68cfbe71994-02-24 11:28:27 +0000656\end{funcdesc}