blob: a7508752713f6b5f6a268b907dd3668238a48580 [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 Drakee0063d22001-10-09 19:31:08 +000010 This function is invoked by the \keyword{import}\stindex{import}
11 statement. It mainly exists so that you can replace it with another
12 function that has a compatible interface, in order to change the
13 semantics of the \keyword{import} statement. For examples of why
14 and how you would do this, see the standard library modules
15 \module{ihooks}\refstmodindex{ihooks} and
16 \refmodule{rexec}\refstmodindex{rexec}. See also the built-in
17 module \refmodule{imp}\refbimodindex{imp}, which defines some useful
18 operations out of which you can build your own
19 \function{__import__()} function.
Guido van Rossum7974b0f1997-10-05 18:53:00 +000020
Fred Drakee0063d22001-10-09 19:31:08 +000021 For example, the statement \samp{import spam} results in the
22 following call: \code{__import__('spam',} \code{globals(),}
23 \code{locals(), [])}; the statement \samp{from spam.ham import eggs}
24 results in \samp{__import__('spam.ham', globals(), locals(),
25 ['eggs'])}. Note that even though \code{locals()} and
26 \code{['eggs']} are passed in as arguments, the
27 \function{__import__()} function does not set the local variable
28 named \code{eggs}; this is done by subsequent code that is generated
29 for the import statement. (In fact, the standard implementation
30 does not use its \var{locals} argument at all, and uses its
31 \var{globals} only to determine the package context of the
32 \keyword{import} statement.)
Guido van Rossum7974b0f1997-10-05 18:53:00 +000033
Fred Drakee0063d22001-10-09 19:31:08 +000034 When the \var{name} variable is of the form \code{package.module},
35 normally, the top-level package (the name up till the first dot) is
36 returned, \emph{not} the module named by \var{name}. However, when
37 a non-empty \var{fromlist} argument is given, the module named by
38 \var{name} is returned. This is done for compatibility with the
39 bytecode generated for the different kinds of import statement; when
40 using \samp{import spam.ham.eggs}, the top-level package \code{spam}
41 must be placed in the importing namespace, but when using \samp{from
42 spam.ham import eggs}, the \code{spam.ham} subpackage must be used
43 to find the \code{eggs} variable. As a workaround for this
44 behavior, use \function{getattr()} to extract the desired
45 components. For example, you could define the following helper:
Guido van Rossum8c2da611998-12-04 15:32:17 +000046
47\begin{verbatim}
48import string
49
50def my_import(name):
51 mod = __import__(name)
52 components = string.split(name, '.')
53 for comp in components[1:]:
54 mod = getattr(mod, comp)
55 return mod
56\end{verbatim}
Guido van Rossum7974b0f1997-10-05 18:53:00 +000057\end{funcdesc}
58
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000059\begin{funcdesc}{abs}{x}
60 Return the absolute value of a number. The argument may be a plain
Guido van Rossum921f32c1997-06-02 17:21:20 +000061 or long integer or a floating point number. If the argument is a
Guido van Rossum7974b0f1997-10-05 18:53:00 +000062 complex number, its magnitude is returned.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000063\end{funcdesc}
64
Fred Drakecce10901998-03-17 06:33:25 +000065\begin{funcdesc}{apply}{function, args\optional{, keywords}}
Fred Drakee0063d22001-10-09 19:31:08 +000066 The \var{function} argument must be a callable object (a
67 user-defined or built-in function or method, or a class object) and
Fred Drake66ded522001-11-07 06:22:25 +000068 the \var{args} argument must be a sequence. The \var{function} is
Fred Drakee0063d22001-10-09 19:31:08 +000069 called with \var{args} as the argument list; the number of arguments
Fred Drake66ded522001-11-07 06:22:25 +000070 is the the length of the tuple.
Fred Drakee0063d22001-10-09 19:31:08 +000071 If the optional \var{keywords} argument is present, it must be a
72 dictionary whose keys are strings. It specifies keyword arguments
73 to be added to the end of the the argument list.
Fred Drake66ded522001-11-07 06:22:25 +000074 Calling \function{apply()} is different from just calling
Fred Drake0b663102001-11-07 06:28:47 +000075 \code{\var{function}(\var{args})}, since in that case there is always
Fred Drake66ded522001-11-07 06:22:25 +000076 exactly one argument. The use of \function{apply()} is equivalent
77 to \code{\var{function}(*\var{args}, **\var{keywords})}.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000078\end{funcdesc}
79
Guido van Rossum8be22961999-03-19 19:10:14 +000080\begin{funcdesc}{buffer}{object\optional{, offset\optional{, size}}}
Fred Drakee0063d22001-10-09 19:31:08 +000081 The \var{object} argument must be an object that supports the buffer
82 call interface (such as strings, arrays, and buffers). A new buffer
83 object will be created which references the \var{object} argument.
84 The buffer object will be a slice from the beginning of \var{object}
85 (or from the specified \var{offset}). The slice will extend to the
86 end of \var{object} (or will have a length given by the \var{size}
87 argument).
Guido van Rossum8be22961999-03-19 19:10:14 +000088\end{funcdesc}
89
Guido van Rossum7974b0f1997-10-05 18:53:00 +000090\begin{funcdesc}{callable}{object}
Fred Drakee0063d22001-10-09 19:31:08 +000091 Return true if the \var{object} argument appears callable, false if
92 not. If this returns true, it is still possible that a call fails,
93 but if it is false, calling \var{object} will never succeed. Note
94 that classes are callable (calling a class returns a new instance);
95 class instances are callable if they have a \method{__call__()}
96 method.
Guido van Rossum7974b0f1997-10-05 18:53:00 +000097\end{funcdesc}
98
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000099\begin{funcdesc}{chr}{i}
100 Return a string of one character whose \ASCII{} code is the integer
Fred Drake91f2f262001-07-06 19:28:48 +0000101 \var{i}. For example, \code{chr(97)} returns the string \code{'a'}.
102 This is the inverse of \function{ord()}. The argument must be in
103 the range [0..255], inclusive; \exception{ValueError} will be raised
104 if \var{i} is outside that range.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000105\end{funcdesc}
106
Fred Drakecce10901998-03-17 06:33:25 +0000107\begin{funcdesc}{cmp}{x, y}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000108 Compare the two objects \var{x} and \var{y} and return an integer
109 according to the outcome. The return value is negative if \code{\var{x}
110 < \var{y}}, zero if \code{\var{x} == \var{y}} and strictly positive if
111 \code{\var{x} > \var{y}}.
112\end{funcdesc}
113
Fred Drakecce10901998-03-17 06:33:25 +0000114\begin{funcdesc}{coerce}{x, y}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000115 Return a tuple consisting of the two numeric arguments converted to
116 a common type, using the same rules as used by arithmetic
117 operations.
118\end{funcdesc}
119
Tim Peters32f453e2001-09-03 08:35:41 +0000120\begin{funcdesc}{compile}{string, filename, kind\optional{,
Michael W. Hudson53da3172001-08-27 20:02:17 +0000121 flags\optional{, dont_inherit}}}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000122 Compile the \var{string} into a code object. Code objects can be
Fred Drake53525371998-03-03 21:56:15 +0000123 executed by an \keyword{exec} statement or evaluated by a call to
124 \function{eval()}. The \var{filename} argument should
Guido van Rossum0d682462001-09-29 14:28:52 +0000125 give the file from which the code was read; pass some recognizable value
Fred Drake91f2f262001-07-06 19:28:48 +0000126 if it wasn't read from a file (\code{'<string>'} is commonly used).
127 The \var{kind} argument specifies what kind of code must be
128 compiled; it can be \code{'exec'} if \var{string} consists of a
129 sequence of statements, \code{'eval'} if it consists of a single
130 expression, or \code{'single'} if it consists of a single
131 interactive statement (in the latter case, expression statements
132 that evaluate to something else than \code{None} will printed).
Michael W. Hudson53da3172001-08-27 20:02:17 +0000133
Guido van Rossum0d682462001-09-29 14:28:52 +0000134 When compiling multi-line statements, two caveats apply: line
135 endings must be represented by a single newline character
136 (\code{'\e n'}), and the input must be terminated by at least one
137 newline character. If line endings are represented by
138 \code{'\e r\e n'}, use the string \method{replace()} method to
139 change them into \code{'\e n'}.
140
141 The optional arguments \var{flags} and \var{dont_inherit}
Michael W. Hudson53da3172001-08-27 20:02:17 +0000142 (which are new in Python 2.2) control which future statements (see
143 \pep{236}) affect the compilation of \var{string}. If neither is
144 present (or both are zero) the code is compiled with those future
145 statements that are in effect in the code that is calling compile.
146 If the \var{flags} argument is given and \var{dont_inherit} is not
147 (or is zero) then the future statements specified by the \var{flags}
148 argument are used in addition to those that would be used anyway.
149 If \var{dont_inherit} is a non-zero integer then the \var{flags}
150 argument is it -- the future statements in effect around the call to
151 compile are ignored.
152
153 Future statemants are specified by bits which can be bitwise or-ed
154 together to specify multiple statements. The bitfield required to
155 specify a given feature can be found as the \member{compiler_flag}
156 attribute on the \class{_Feature} instance in the
157 \module{__future__} module.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000158\end{funcdesc}
159
Guido van Rossum1cd26f21997-04-02 06:04:02 +0000160\begin{funcdesc}{complex}{real\optional{, imag}}
Guido van Rossumcb1f2421999-03-25 21:23:26 +0000161 Create a complex number with the value \var{real} + \var{imag}*j or
162 convert a string or number to a complex number.
Guido van Rossum1cd26f21997-04-02 06:04:02 +0000163 Each argument may be any numeric type (including complex).
164 If \var{imag} is omitted, it defaults to zero and the function
Fred Drake53525371998-03-03 21:56:15 +0000165 serves as a numeric conversion function like \function{int()},
Guido van Rossumcb1f2421999-03-25 21:23:26 +0000166 \function{long()} and \function{float()}; in this case it also
167 accepts a string argument which should be a valid complex number.
Guido van Rossum1cd26f21997-04-02 06:04:02 +0000168\end{funcdesc}
169
Fred Drakecce10901998-03-17 06:33:25 +0000170\begin{funcdesc}{delattr}{object, name}
Fred Drake53525371998-03-03 21:56:15 +0000171 This is a relative of \function{setattr()}. The arguments are an
Guido van Rossum1efbb0f1994-08-16 22:15:11 +0000172 object and a string. The string must be the name
173 of one of the object's attributes. The function deletes
174 the named attribute, provided the object allows it. For example,
Guido van Rossum6c4f0031995-03-07 10:14:09 +0000175 \code{delattr(\var{x}, '\var{foobar}')} is equivalent to
Guido van Rossum1efbb0f1994-08-16 22:15:11 +0000176 \code{del \var{x}.\var{foobar}}.
177\end{funcdesc}
178
Tim Petersa427a2b2001-10-29 22:25:45 +0000179\begin{funcdesc}{dict}{\optional{mapping-or-sequence}}
Tim Peters1fc240e2001-10-26 05:06:50 +0000180 Return a new dictionary initialized from the optional argument.
181 If an argument is not specified, return a new empty dictionary.
182 If the argument is a mapping object, return a dictionary mapping the
183 same keys to the same values as does the mapping object.
184 Else the argument must be a sequence, a container that supports
185 iteration, or an iterator object. The elements of the argument must
186 each also be of one of those kinds, and each must in turn contain
187 exactly two objects. The first is used as a key in the new dictionary,
188 and the second as the key's value. If a given key is seen more than
189 once, the last value associated with it is retained in the new
190 dictionary.
191 For example, these all return a dictionary equal to
192 \code{\{1: 2, 2: 3\}}:
Fred Drakeef7d08a2001-10-26 15:04:33 +0000193
194 \begin{itemize}
Tim Petersa427a2b2001-10-29 22:25:45 +0000195 \item \code{dict(\{1: 2, 2: 3\})}
196 \item \code{dict(\{1: 2, 2: 3\}.items())}
197 \item \code{dict(\{1: 2, 2: 3\}.iteritems())}
198 \item \code{dict(zip((1, 2), (2, 3)))}
199 \item \code{dict([[2, 3], [1, 2]])}
200 \item \code{dict([(i-1, i) for i in (2, 3)])}
Fred Drakeef7d08a2001-10-26 15:04:33 +0000201 \end{itemize}
Tim Peters1fc240e2001-10-26 05:06:50 +0000202\end{funcdesc}
203
Fred Drake6b303b41998-04-16 22:10:27 +0000204\begin{funcdesc}{dir}{\optional{object}}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000205 Without arguments, return the list of names in the current local
Guido van Rossumeb0f0661997-12-30 20:38:16 +0000206 symbol table. With an argument, attempts to return a list of valid
207 attribute for that object. This information is gleaned from the
Fred Drake35705512001-12-03 17:32:27 +0000208 object's \member{__dict__} attribute, if defined, and from the class
209 or type object. The list is not necessarily complete. For
Fred Drake91f2f262001-07-06 19:28:48 +0000210 example, for classes, attributes defined in base classes are not
211 included, and for class instances, methods are not included.
Guido van Rossumeb0f0661997-12-30 20:38:16 +0000212 The resulting list is sorted alphabetically. For example:
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000213
Fred Drake19479911998-02-13 06:58:54 +0000214\begin{verbatim}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000215>>> import sys
216>>> dir()
217['sys']
218>>> dir(sys)
219['argv', 'exit', 'modules', 'path', 'stderr', 'stdin', 'stdout']
Fred Drake19479911998-02-13 06:58:54 +0000220\end{verbatim}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000221\end{funcdesc}
222
Fred Drakecce10901998-03-17 06:33:25 +0000223\begin{funcdesc}{divmod}{a, b}
Guido van Rossumeb0f0661997-12-30 20:38:16 +0000224 Take two numbers as arguments and return a pair of numbers consisting
225 of their quotient and remainder when using long division. With mixed
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000226 operand types, the rules for binary arithmetic operators apply. For
227 plain and long integers, the result is the same as
228 \code{(\var{a} / \var{b}, \var{a} \%{} \var{b})}.
Fred Drake1ea7c751999-05-06 14:46:35 +0000229 For floating point numbers the result is \code{(\var{q}, \var{a} \%{}
230 \var{b})}, where \var{q} is usually \code{math.floor(\var{a} /
231 \var{b})} but may be 1 less than that. In any case \code{\var{q} *
232 \var{b} + \var{a} \%{} \var{b}} is very close to \var{a}, if
233 \code{\var{a} \%{} \var{b}} is non-zero it has the same sign as
234 \var{b}, and \code{0 <= abs(\var{a} \%{} \var{b}) < abs(\var{b})}.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000235\end{funcdesc}
236
Fred Drakecce10901998-03-17 06:33:25 +0000237\begin{funcdesc}{eval}{expression\optional{, globals\optional{, locals}}}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000238 The arguments are a string and two optional dictionaries. The
Guido van Rossumf8601621995-01-10 10:50:24 +0000239 \var{expression} argument is parsed and evaluated as a Python
240 expression (technically speaking, a condition list) using the
241 \var{globals} and \var{locals} dictionaries as global and local name
Guido van Rossum470be141995-03-17 16:07:09 +0000242 space. If the \var{locals} dictionary is omitted it defaults to
243 the \var{globals} dictionary. If both dictionaries are omitted, the
Fred Drake53525371998-03-03 21:56:15 +0000244 expression is executed in the environment where \keyword{eval} is
Guido van Rossumf8601621995-01-10 10:50:24 +0000245 called. The return value is the result of the evaluated expression.
246 Syntax errors are reported as exceptions. Example:
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000247
Fred Drake19479911998-02-13 06:58:54 +0000248\begin{verbatim}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000249>>> x = 1
250>>> print eval('x+1')
2512
Fred Drake19479911998-02-13 06:58:54 +0000252\end{verbatim}
Fred Drake53525371998-03-03 21:56:15 +0000253
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000254 This function can also be used to execute arbitrary code objects
Fred Drake91f2f262001-07-06 19:28:48 +0000255 (such as those created by \function{compile()}). In this case pass
256 a code object instead of a string. The code object must have been
257 compiled passing \code{'eval'} as the \var{kind} argument.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000258
Guido van Rossum6c4f0031995-03-07 10:14:09 +0000259 Hints: dynamic execution of statements is supported by the
Fred Drake53525371998-03-03 21:56:15 +0000260 \keyword{exec} statement. Execution of statements from a file is
261 supported by the \function{execfile()} function. The
262 \function{globals()} and \function{locals()} functions returns the
263 current global and local dictionary, respectively, which may be
264 useful to pass around for use by \function{eval()} or
265 \function{execfile()}.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000266\end{funcdesc}
267
Fred Drakecce10901998-03-17 06:33:25 +0000268\begin{funcdesc}{execfile}{file\optional{, globals\optional{, locals}}}
Guido van Rossum470be141995-03-17 16:07:09 +0000269 This function is similar to the
Fred Drake53525371998-03-03 21:56:15 +0000270 \keyword{exec} statement, but parses a file instead of a string. It
271 is different from the \keyword{import} statement in that it does not
272 use the module administration --- it reads the file unconditionally
273 and does not create a new module.\footnote{It is used relatively
274 rarely so does not warrant being made into a statement.}
Guido van Rossumf8601621995-01-10 10:50:24 +0000275
276 The arguments are a file name and two optional dictionaries. The
277 file is parsed and evaluated as a sequence of Python statements
278 (similarly to a module) using the \var{globals} and \var{locals}
Fred Drake13494372000-09-12 16:23:48 +0000279 dictionaries as global and local namespace. If the \var{locals}
Guido van Rossum470be141995-03-17 16:07:09 +0000280 dictionary is omitted it defaults to the \var{globals} dictionary.
Guido van Rossumf8601621995-01-10 10:50:24 +0000281 If both dictionaries are omitted, the expression is executed in the
Fred Drake53525371998-03-03 21:56:15 +0000282 environment where \function{execfile()} is called. The return value is
Guido van Rossum470be141995-03-17 16:07:09 +0000283 \code{None}.
Tim Petersaf5910f2001-09-30 06:32:59 +0000284
Fred Drakee0063d22001-10-09 19:31:08 +0000285 \warning{The default \var{locals} act as described for function
Tim Petersaf5910f2001-09-30 06:32:59 +0000286 \function{locals()} below: modifications to the default \var{locals}
287 dictionary should not be attempted. Pass an explicit \var{locals}
288 dictionary if you need to see effects of the code on \var{locals} after
289 function \function{execfile()} returns. \function{execfile()} cannot
Fred Drakee0063d22001-10-09 19:31:08 +0000290 be used reliably to modify a function's locals.}
Guido van Rossumf8601621995-01-10 10:50:24 +0000291\end{funcdesc}
292
Tim Peters2e29bfb2001-09-20 19:55:29 +0000293\begin{funcdesc}{file}{filename\optional{, mode\optional{, bufsize}}}
294 Return a new file object (described earlier under Built-in Types).
295 The first two arguments are the same as for \code{stdio}'s
296 \cfunction{fopen()}: \var{filename} is the file name to be opened,
297 \var{mode} indicates how the file is to be opened: \code{'r'} for
298 reading, \code{'w'} for writing (truncating an existing file), and
299 \code{'a'} opens it for appending (which on \emph{some} \UNIX{}
300 systems means that \emph{all} writes append to the end of the file,
301 regardless of the current seek position).
302
303 Modes \code{'r+'}, \code{'w+'} and \code{'a+'} open the file for
304 updating (note that \code{'w+'} truncates the file). Append
305 \code{'b'} to the mode to open the file in binary mode, on systems
306 that differentiate between binary and text files (else it is
307 ignored). If the file cannot be opened, \exception{IOError} is
308 raised.
309
310 If \var{mode} is omitted, it defaults to \code{'r'}. When opening a
311 binary file, you should append \code{'b'} to the \var{mode} value
312 for improved portability. (It's useful even on systems which don't
313 treat binary and text files differently, where it serves as
314 documentation.)
315 \index{line-buffered I/O}\index{unbuffered I/O}\index{buffer size, I/O}
316 \index{I/O control!buffering}
317 The optional \var{bufsize} argument specifies the
318 file's desired buffer size: 0 means unbuffered, 1 means line
319 buffered, any other positive value means use a buffer of
320 (approximately) that size. A negative \var{bufsize} means to use
321 the system default, which is usually line buffered for for tty
322 devices and fully buffered for other files. If omitted, the system
323 default is used.\footnote{
324 Specifying a buffer size currently has no effect on systems that
325 don't have \cfunction{setvbuf()}. The interface to specify the
326 buffer size is not done using a method that calls
327 \cfunction{setvbuf()}, because that may dump core when called
328 after any I/O has been performed, and there's no reliable way to
329 determine whether this is the case.}
330
331 The \function{file()} constructor is new in Python 2.2. The previous
332 spelling, \function{open()}, is retained for compatibility, and is an
333 alias for \function{file()}.
334\end{funcdesc}
335
Fred Drakecce10901998-03-17 06:33:25 +0000336\begin{funcdesc}{filter}{function, list}
Fred Drakeeacdec62001-05-02 20:19:19 +0000337 Construct a list from those elements of \var{list} for which
338 \var{function} returns true. \var{list} may be either a sequence, a
339 container which supports iteration, or an iterator, If \var{list}
340 is a string or a tuple, the result also has that type; otherwise it
341 is always a list. If \var{function} is \code{None}, the identity
Fred Drake91f2f262001-07-06 19:28:48 +0000342 function is assumed, that is, all elements of \var{list} that are false
Fred Drakeeacdec62001-05-02 20:19:19 +0000343 (zero or empty) are removed.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000344\end{funcdesc}
345
346\begin{funcdesc}{float}{x}
Guido van Rossum1cd26f21997-04-02 06:04:02 +0000347 Convert a string or a number to floating point. If the argument is a
Fred Draked83675f1998-12-07 17:13:18 +0000348 string, it must contain a possibly signed decimal or floating point
Fred Drake70a66c91999-02-18 16:08:36 +0000349 number, possibly embedded in whitespace; this behaves identical to
350 \code{string.atof(\var{x})}. Otherwise, the argument may be a plain
351 or long integer or a floating point number, and a floating point
352 number with the same value (within Python's floating point
353 precision) is returned.
354
Fred Drakee0063d22001-10-09 19:31:08 +0000355 \note{When passing in a string, values for NaN\index{NaN}
Fred Drake70a66c91999-02-18 16:08:36 +0000356 and Infinity\index{Infinity} may be returned, depending on the
357 underlying C library. The specific set of strings accepted which
358 cause these values to be returned depends entirely on the C library
Fred Drakee0063d22001-10-09 19:31:08 +0000359 and is known to vary.}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000360\end{funcdesc}
361
Fred Drakede5d5ce1999-07-22 19:21:45 +0000362\begin{funcdesc}{getattr}{object, name\optional{, default}}
363 Return the value of the named attributed of \var{object}. \var{name}
364 must be a string. If the string is the name of one of the object's
365 attributes, the result is the value of that attribute. For example,
366 \code{getattr(x, 'foobar')} is equivalent to \code{x.foobar}. If the
367 named attribute does not exist, \var{default} is returned if provided,
368 otherwise \exception{AttributeError} is raised.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000369\end{funcdesc}
370
Guido van Rossumfb502e91995-07-07 22:58:28 +0000371\begin{funcdesc}{globals}{}
Fred Drakee0063d22001-10-09 19:31:08 +0000372 Return a dictionary representing the current global symbol table.
373 This is always the dictionary of the current module (inside a
374 function or method, this is the module where it is defined, not the
375 module from which it is called).
Guido van Rossumfb502e91995-07-07 22:58:28 +0000376\end{funcdesc}
377
Fred Drakecce10901998-03-17 06:33:25 +0000378\begin{funcdesc}{hasattr}{object, name}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000379 The arguments are an object and a string. The result is 1 if the
380 string is the name of one of the object's attributes, 0 if not.
Fred Drake53525371998-03-03 21:56:15 +0000381 (This is implemented by calling \code{getattr(\var{object},
382 \var{name})} and seeing whether it raises an exception or not.)
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000383\end{funcdesc}
384
385\begin{funcdesc}{hash}{object}
386 Return the hash value of the object (if it has one). Hash values
Guido van Rossumeb0f0661997-12-30 20:38:16 +0000387 are integers. They are used to quickly compare dictionary
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000388 keys during a dictionary lookup. Numeric values that compare equal
Fred Drake91f2f262001-07-06 19:28:48 +0000389 have the same hash value (even if they are of different types, as is
390 the case for 1 and 1.0).
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000391\end{funcdesc}
392
393\begin{funcdesc}{hex}{x}
Guido van Rossum470be141995-03-17 16:07:09 +0000394 Convert an integer number (of any size) to a hexadecimal string.
Guido van Rossum5cd75201997-01-14 18:44:23 +0000395 The result is a valid Python expression. Note: this always yields
Fred Drake91f2f262001-07-06 19:28:48 +0000396 an unsigned literal. For example, on a 32-bit machine,
397 \code{hex(-1)} yields \code{'0xffffffff'}. When evaluated on a
398 machine with the same word size, this literal is evaluated as -1; at
399 a different word size, it may turn up as a large positive number or
400 raise an \exception{OverflowError} exception.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000401\end{funcdesc}
402
403\begin{funcdesc}{id}{object}
Fred Drake8aa3bd92000-06-29 03:46:46 +0000404 Return the `identity' of an object. This is an integer (or long
405 integer) which is guaranteed to be unique and constant for this
406 object during its lifetime. Two objects whose lifetimes are
407 disjunct may have the same \function{id()} value. (Implementation
408 note: this is the address of the object.)
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000409\end{funcdesc}
410
Guido van Rossum16d6e711994-08-08 12:30:22 +0000411\begin{funcdesc}{input}{\optional{prompt}}
Guido van Rossum777dcc61998-06-17 15:16:40 +0000412 Equivalent to \code{eval(raw_input(\var{prompt}))}.
Fred Drakee0063d22001-10-09 19:31:08 +0000413 \warning{This function is not safe from user errors! It
Fred Drakef96e0d22000-09-09 03:33:42 +0000414 expects a valid Python expression as input; if the input is not
415 syntactically valid, a \exception{SyntaxError} will be raised.
416 Other exceptions may be raised if there is an error during
417 evaluation. (On the other hand, sometimes this is exactly what you
Fred Drakee0063d22001-10-09 19:31:08 +0000418 need when writing a quick script for expert use.)}
Fred Drakef96e0d22000-09-09 03:33:42 +0000419
Fred Drakee0063d22001-10-09 19:31:08 +0000420 If the \refmodule{readline} module was loaded, then
Fred Drakef96e0d22000-09-09 03:33:42 +0000421 \function{input()} will use it to provide elaborate line editing and
422 history features.
423
424 Consider using the \function{raw_input()} function for general input
425 from users.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000426\end{funcdesc}
427
Fred Drake1e862e82000-02-17 17:45:52 +0000428\begin{funcdesc}{int}{x\optional{, radix}}
429 Convert a string or number to a plain integer. If the argument is a
430 string, it must contain a possibly signed decimal number
431 representable as a Python integer, possibly embedded in whitespace;
432 this behaves identical to \code{string.atoi(\var{x}\optional{,
433 \var{radix}})}. The \var{radix} parameter gives the base for the
Fred Drake17383b92000-11-17 19:44:14 +0000434 conversion and may be any integer in the range [2, 36], or zero. If
435 \var{radix} is zero, the proper radix is guessed based on the
436 contents of string; the interpretation is the same as for integer
437 literals. If \var{radix} is specified and \var{x} is not a string,
Fred Drake1e862e82000-02-17 17:45:52 +0000438 \exception{TypeError} is raised.
439 Otherwise, the argument may be a plain or
440 long integer or a floating point number. Conversion of floating
Tim Peters7321ec42001-07-26 20:02:17 +0000441 point numbers to integers truncates (towards zero).
Fred Drake1e862e82000-02-17 17:45:52 +0000442\end{funcdesc}
443
Guido van Rossum3978d751997-03-03 16:03:27 +0000444\begin{funcdesc}{intern}{string}
445 Enter \var{string} in the table of ``interned'' strings and return
446 the interned string -- which is \var{string} itself or a copy.
447 Interning strings is useful to gain a little performance on
448 dictionary lookup -- if the keys in a dictionary are interned, and
449 the lookup key is interned, the key comparisons (after hashing) can
450 be done by a pointer compare instead of a string compare. Normally,
451 the names used in Python programs are automatically interned, and
452 the dictionaries used to hold module, class or instance attributes
Fred Drake91f2f262001-07-06 19:28:48 +0000453 have interned keys. Interned strings are immortal (never get
Guido van Rossum3978d751997-03-03 16:03:27 +0000454 garbage collected).
455\end{funcdesc}
456
Fred Drakee0063d22001-10-09 19:31:08 +0000457\begin{funcdesc}{isinstance}{object, classinfo}
458 Return true if the \var{object} argument is an instance of the
459 \var{classinfo} argument, or of a (direct or indirect) subclass
460 thereof. Also return true if \var{classinfo} is a type object and
461 \var{object} is an object of that type. If \var{object} is not a
462 class instance or a object of the given type, the function always
463 returns false. If \var{classinfo} is neither a class object nor a
464 type object, it may be a tuple of class or type objects, or may
465 recursively contain other such tuples (other sequence types are not
466 accepted). If \var{classinfo} is not a class, type, or tuple of
467 classes, types, and such tuples, a \exception{TypeError} exception
468 is raised.
469 \versionchanged[Support for a tuple of type information was added]{2.2}
Guido van Rossum7974b0f1997-10-05 18:53:00 +0000470\end{funcdesc}
471
472\begin{funcdesc}{issubclass}{class1, class2}
Fred Drakee0063d22001-10-09 19:31:08 +0000473 Return true if \var{class1} is a subclass (direct or indirect) of
474 \var{class2}. A class is considered a subclass of itself. If
475 either argument is not a class object, a \exception{TypeError}
476 exception is raised.
Guido van Rossum7974b0f1997-10-05 18:53:00 +0000477\end{funcdesc}
478
Fred Drake00bb3292001-09-06 19:04:29 +0000479\begin{funcdesc}{iter}{o\optional{, sentinel}}
480 Return an iterator object. The first argument is interpreted very
481 differently depending on the presence of the second argument.
482 Without a second argument, \var{o} must be a collection object which
483 supports the iteration protocol (the \method{__iter__()} method), or
484 it must support the sequence protocol (the \method{__getitem__()}
485 method with integer arguments starting at \code{0}). If it does not
486 support either of those protocols, \exception{TypeError} is raised.
487 If the second argument, \var{sentinel}, is given, then \var{o} must
488 be a callable object. The iterator created in this case will call
489 \var{o} with no arguments for each call to its \method{next()}
490 method; if the value returned is equal to \var{sentinel},
491 \exception{StopIteration} will be raised, otherwise the value will
492 be returned.
493 \versionadded{2.2}
494\end{funcdesc}
495
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000496\begin{funcdesc}{len}{s}
497 Return the length (the number of items) of an object. The argument
498 may be a sequence (string, tuple or list) or a mapping (dictionary).
499\end{funcdesc}
500
Tim Peters1fc240e2001-10-26 05:06:50 +0000501\begin{funcdesc}{list}{\optional{sequence}}
Fred Drakeeacdec62001-05-02 20:19:19 +0000502 Return a list whose items are the same and in the same order as
503 \var{sequence}'s items. \var{sequence} may be either a sequence, a
504 container that supports iteration, or an iterator object. If
505 \var{sequence} is already a list, a copy is made and returned,
506 similar to \code{\var{sequence}[:]}. For instance,
507 \code{list('abc')} returns \code{['a', 'b', 'c']} and \code{list(
508 (1, 2, 3) )} returns \code{[1, 2, 3]}.
Guido van Rossum921f32c1997-06-02 17:21:20 +0000509\end{funcdesc}
510
Guido van Rossumfb502e91995-07-07 22:58:28 +0000511\begin{funcdesc}{locals}{}
Fred Drakee0063d22001-10-09 19:31:08 +0000512 Return a dictionary representing the current local symbol table.
513 \warning{The contents of this dictionary should not be modified;
514 changes may not affect the values of local variables used by the
515 interpreter.}
Guido van Rossumfb502e91995-07-07 22:58:28 +0000516\end{funcdesc}
517
Fred Drake17383b92000-11-17 19:44:14 +0000518\begin{funcdesc}{long}{x\optional{, radix}}
Guido van Rossum1cd26f21997-04-02 06:04:02 +0000519 Convert a string or number to a long integer. If the argument is a
Fred Drake9c15fa72001-01-04 05:09:16 +0000520 string, it must contain a possibly signed number of
Guido van Rossum1cd26f21997-04-02 06:04:02 +0000521 arbitrary size, possibly embedded in whitespace;
Fred Drake17383b92000-11-17 19:44:14 +0000522 this behaves identical to \code{string.atol(\var{x})}. The
523 \var{radix} argument is interpreted in the same way as for
524 \function{int()}, and may only be given when \var{x} is a string.
Guido van Rossum1cd26f21997-04-02 06:04:02 +0000525 Otherwise, the argument may be a plain or
Guido van Rossumeb0f0661997-12-30 20:38:16 +0000526 long integer or a floating point number, and a long integer with
Guido van Rossum1cd26f21997-04-02 06:04:02 +0000527 the same value is returned. Conversion of floating
Tim Peters1c33daf2001-09-30 06:18:26 +0000528 point numbers to integers truncates (towards zero).
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000529\end{funcdesc}
530
Fred Drakecce10901998-03-17 06:33:25 +0000531\begin{funcdesc}{map}{function, list, ...}
Fred Drake91f2f262001-07-06 19:28:48 +0000532 Apply \var{function} to every item of \var{list} and return a list
533 of the results. If additional \var{list} arguments are passed,
534 \var{function} must take that many arguments and is applied to the
535 items of all lists in parallel; if a list is shorter than another it
536 is assumed to be extended with \code{None} items. If \var{function}
537 is \code{None}, the identity function is assumed; if there are
538 multiple list arguments, \function{map()} returns a list consisting
539 of tuples containing the corresponding items from all lists (a kind
540 of transpose operation). The \var{list} arguments may be any kind
541 of sequence; the result is always a list.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000542\end{funcdesc}
543
Guido van Rossum5eabf381998-11-25 18:53:05 +0000544\begin{funcdesc}{max}{s\optional{, args...}}
Fred Drake91f2f262001-07-06 19:28:48 +0000545 With a single argument \var{s}, return the largest item of a
546 non-empty sequence (such as a string, tuple or list). With more
547 than one argument, return the largest of the arguments.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000548\end{funcdesc}
549
Guido van Rossum5eabf381998-11-25 18:53:05 +0000550\begin{funcdesc}{min}{s\optional{, args...}}
Fred Drake91f2f262001-07-06 19:28:48 +0000551 With a single argument \var{s}, return the smallest item of a
552 non-empty sequence (such as a string, tuple or list). With more
553 than one argument, return the smallest of the arguments.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000554\end{funcdesc}
555
556\begin{funcdesc}{oct}{x}
Guido van Rossum470be141995-03-17 16:07:09 +0000557 Convert an integer number (of any size) to an octal string. The
Fred Drake91f2f262001-07-06 19:28:48 +0000558 result is a valid Python expression. Note: this always yields an
559 unsigned literal. For example, on a 32-bit machine, \code{oct(-1)}
560 yields \code{'037777777777'}. When evaluated on a machine with the
561 same word size, this literal is evaluated as -1; at a different word
Guido van Rossum5cd75201997-01-14 18:44:23 +0000562 size, it may turn up as a large positive number or raise an
Fred Drake53525371998-03-03 21:56:15 +0000563 \exception{OverflowError} exception.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000564\end{funcdesc}
565
Fred Drakecce10901998-03-17 06:33:25 +0000566\begin{funcdesc}{open}{filename\optional{, mode\optional{, bufsize}}}
Tim Peters2e29bfb2001-09-20 19:55:29 +0000567 An alias for the \function{file()} function above.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000568\end{funcdesc}
569
570\begin{funcdesc}{ord}{c}
Fred Drake33d51842000-04-06 14:43:12 +0000571 Return the \ASCII{} value of a string of one character or a Unicode
572 character. E.g., \code{ord('a')} returns the integer \code{97},
573 \code{ord(u'\\u2020')} returns \code{8224}. This is the inverse of
574 \function{chr()} for strings and of \function{unichr()} for Unicode
575 characters.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000576\end{funcdesc}
577
Fred Drakecce10901998-03-17 06:33:25 +0000578\begin{funcdesc}{pow}{x, y\optional{, z}}
Guido van Rossumb8b264b1994-08-12 13:13:50 +0000579 Return \var{x} to the power \var{y}; if \var{z} is present, return
580 \var{x} to the power \var{y}, modulo \var{z} (computed more
Guido van Rossumbf5a7742001-07-12 11:27:16 +0000581 efficiently than \code{pow(\var{x}, \var{y}) \%\ \var{z}}). The
582 arguments must have numeric types. With mixed operand types, the
583 coercion rules for binary arithmetic operators apply. For int and
584 long int operands, the result has the same type as the operands
585 (after coercion) unless the second argument is negative; in that
586 case, all arguments are converted to float and a float result is
587 delivered. For example, \code{10**2} returns \code{100}, but
588 \code{10**-2} returns \code{0.01}. (This last feature was added in
Tim Peters32f453e2001-09-03 08:35:41 +0000589 Python 2.2. In Python 2.1 and before, if both arguments were of integer
590 types and the second argument was negative, an exception was raised.)
Tim Peters2e29bfb2001-09-20 19:55:29 +0000591 If the second argument is negative, the third argument must be omitted.
Tim Peters32f453e2001-09-03 08:35:41 +0000592 If \var{z} is present, \var{x} and \var{y} must be of integer types,
593 and \var{y} must be non-negative. (This restriction was added in
594 Python 2.2. In Python 2.1 and before, floating 3-argument \code{pow()}
595 returned platform-dependent results depending on floating-point
596 rounding accidents.)
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000597\end{funcdesc}
598
Fred Drakecce10901998-03-17 06:33:25 +0000599\begin{funcdesc}{range}{\optional{start,} stop\optional{, step}}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000600 This is a versatile function to create lists containing arithmetic
Fred Drake53525371998-03-03 21:56:15 +0000601 progressions. It is most often used in \keyword{for} loops. The
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000602 arguments must be plain integers. If the \var{step} argument is
603 omitted, it defaults to \code{1}. If the \var{start} argument is
604 omitted, it defaults to \code{0}. The full form returns a list of
605 plain integers \code{[\var{start}, \var{start} + \var{step},
606 \var{start} + 2 * \var{step}, \ldots]}. If \var{step} is positive,
607 the last element is the largest \code{\var{start} + \var{i} *
Guido van Rossum7974b0f1997-10-05 18:53:00 +0000608 \var{step}} less than \var{stop}; if \var{step} is negative, the last
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000609 element is the largest \code{\var{start} + \var{i} * \var{step}}
Fred Drake6251c161998-04-03 07:15:54 +0000610 greater than \var{stop}. \var{step} must not be zero (or else
611 \exception{ValueError} is raised). Example:
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000612
Fred Drake19479911998-02-13 06:58:54 +0000613\begin{verbatim}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000614>>> range(10)
615[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
616>>> range(1, 11)
617[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
618>>> range(0, 30, 5)
619[0, 5, 10, 15, 20, 25]
620>>> range(0, 10, 3)
621[0, 3, 6, 9]
622>>> range(0, -10, -1)
623[0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
624>>> range(0)
625[]
626>>> range(1, 0)
627[]
Fred Drake19479911998-02-13 06:58:54 +0000628\end{verbatim}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000629\end{funcdesc}
630
Guido van Rossum16d6e711994-08-08 12:30:22 +0000631\begin{funcdesc}{raw_input}{\optional{prompt}}
632 If the \var{prompt} argument is present, it is written to standard output
633 without a trailing newline. The function then reads a line from input,
634 converts it to a string (stripping a trailing newline), and returns that.
Fred Drake53525371998-03-03 21:56:15 +0000635 When \EOF{} is read, \exception{EOFError} is raised. Example:
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000636
Fred Drake19479911998-02-13 06:58:54 +0000637\begin{verbatim}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000638>>> s = raw_input('--> ')
639--> Monty Python's Flying Circus
640>>> s
Guido van Rossum470be141995-03-17 16:07:09 +0000641"Monty Python's Flying Circus"
Fred Drake19479911998-02-13 06:58:54 +0000642\end{verbatim}
Guido van Rossum921f32c1997-06-02 17:21:20 +0000643
Fred Drakee0063d22001-10-09 19:31:08 +0000644 If the \refmodule{readline} module was loaded, then
645 \function{raw_input()} will use it to provide elaborate
646 line editing and history features.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000647\end{funcdesc}
648
Guido van Rossum87e611e1999-01-06 23:10:51 +0000649\begin{funcdesc}{reduce}{function, sequence\optional{, initializer}}
Fred Drakee0063d22001-10-09 19:31:08 +0000650 Apply \var{function} of two arguments cumulatively to the items of
651 \var{sequence}, from left to right, so as to reduce the sequence to
652 a single value. For example,
653 \code{reduce(lambda x, y: x+y, [1, 2, 3, 4, 5])} calculates
654 \code{((((1+2)+3)+4)+5)}.
655 If the optional \var{initializer} is present, it is placed before
656 the items of the sequence in the calculation, and serves as a
657 default when the sequence is empty.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000658\end{funcdesc}
659
660\begin{funcdesc}{reload}{module}
Fred Drakee0063d22001-10-09 19:31:08 +0000661 Re-parse and re-initialize an already imported \var{module}. The
662 argument must be a module object, so it must have been successfully
663 imported before. This is useful if you have edited the module
664 source file using an external editor and want to try out the new
665 version without leaving the Python interpreter. The return value is
666 the module object (the same as the \var{module} argument).
Guido van Rossum470be141995-03-17 16:07:09 +0000667
Fred Drakee0063d22001-10-09 19:31:08 +0000668 There are a number of caveats:
Guido van Rossum470be141995-03-17 16:07:09 +0000669
Fred Drakee0063d22001-10-09 19:31:08 +0000670 If a module is syntactically correct but its initialization fails,
671 the first \keyword{import} statement for it does not bind its name
672 locally, but does store a (partially initialized) module object in
673 \code{sys.modules}. To reload the module you must first
674 \keyword{import} it again (this will bind the name to the partially
675 initialized module object) before you can \function{reload()} it.
Guido van Rossum470be141995-03-17 16:07:09 +0000676
Fred Drakee0063d22001-10-09 19:31:08 +0000677 When a module is reloaded, its dictionary (containing the module's
678 global variables) is retained. Redefinitions of names will override
679 the old definitions, so this is generally not a problem. If the new
680 version of a module does not define a name that was defined by the
681 old version, the old definition remains. This feature can be used
682 to the module's advantage if it maintains a global table or cache of
683 objects --- with a \keyword{try} statement it can test for the
684 table's presence and skip its initialization if desired.
Guido van Rossum470be141995-03-17 16:07:09 +0000685
Fred Drakee0063d22001-10-09 19:31:08 +0000686 It is legal though generally not very useful to reload built-in or
687 dynamically loaded modules, except for \refmodule{sys},
688 \refmodule[main]{__main__} and \refmodule[builtin]{__builtin__}. In
689 many cases, however, extension modules are not designed to be
690 initialized more than once, and may fail in arbitrary ways when
691 reloaded.
Guido van Rossum470be141995-03-17 16:07:09 +0000692
Fred Drakee0063d22001-10-09 19:31:08 +0000693 If a module imports objects from another module using \keyword{from}
694 \ldots{} \keyword{import} \ldots{}, calling \function{reload()} for
695 the other module does not redefine the objects imported from it ---
696 one way around this is to re-execute the \keyword{from} statement,
697 another is to use \keyword{import} and qualified names
698 (\var{module}.\var{name}) instead.
Guido van Rossum470be141995-03-17 16:07:09 +0000699
Fred Drakee0063d22001-10-09 19:31:08 +0000700 If a module instantiates instances of a class, reloading the module
701 that defines the class does not affect the method definitions of the
702 instances --- they continue to use the old class definition. The
703 same is true for derived classes.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000704\end{funcdesc}
705
706\begin{funcdesc}{repr}{object}
Fred Drakee0063d22001-10-09 19:31:08 +0000707 Return a string containing a printable representation of an object.
708 This is the same value yielded by conversions (reverse quotes).
709 It is sometimes useful to be able to access this operation as an
710 ordinary function. For many types, this function makes an attempt
711 to return a string that would yield an object with the same value
712 when passed to \function{eval()}.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000713\end{funcdesc}
714
Fred Drake607f8021998-08-24 20:30:07 +0000715\begin{funcdesc}{round}{x\optional{, n}}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000716 Return the floating point value \var{x} rounded to \var{n} digits
717 after the decimal point. If \var{n} is omitted, it defaults to zero.
718 The result is a floating point number. Values are rounded to the
719 closest multiple of 10 to the power minus \var{n}; if two multiples
Fred Drake91f2f262001-07-06 19:28:48 +0000720 are equally close, rounding is done away from 0 (so. for example,
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000721 \code{round(0.5)} is \code{1.0} and \code{round(-0.5)} is \code{-1.0}).
722\end{funcdesc}
723
Fred Drakecce10901998-03-17 06:33:25 +0000724\begin{funcdesc}{setattr}{object, name, value}
Fred Drake53525371998-03-03 21:56:15 +0000725 This is the counterpart of \function{getattr()}. The arguments are an
Fred Drake607f8021998-08-24 20:30:07 +0000726 object, a string and an arbitrary value. The string may name an
727 existing attribute or a new attribute. The function assigns the
728 value to the attribute, provided the object allows it. For example,
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000729 \code{setattr(\var{x}, '\var{foobar}', 123)} is equivalent to
730 \code{\var{x}.\var{foobar} = 123}.
731\end{funcdesc}
732
Fred Drakecce10901998-03-17 06:33:25 +0000733\begin{funcdesc}{slice}{\optional{start,} stop\optional{, step}}
Fred Drakee0063d22001-10-09 19:31:08 +0000734 Return a slice object representing the set of indices specified by
735 \code{range(\var{start}, \var{stop}, \var{step})}. The \var{start}
736 and \var{step} arguments default to None. Slice objects have
737 read-only data attributes \member{start}, \member{stop} and
738 \member{step} which merely return the argument values (or their
739 default). They have no other explicit functionality; however they
740 are used by Numerical Python\index{Numerical Python} and other third
741 party extensions. Slice objects are also generated when extended
742 indexing syntax is used. For example: \samp{a[start:stop:step]} or
743 \samp{a[start:stop, i]}.
Guido van Rossum7974b0f1997-10-05 18:53:00 +0000744\end{funcdesc}
745
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000746\begin{funcdesc}{str}{object}
Fred Drakee0063d22001-10-09 19:31:08 +0000747 Return a string containing a nicely printable representation of an
748 object. For strings, this returns the string itself. The
749 difference with \code{repr(\var{object})} is that
750 \code{str(\var{object})} does not always attempt to return a string
751 that is acceptable to \function{eval()}; its goal is to return a
752 printable string.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000753\end{funcdesc}
754
Tim Peters1fc240e2001-10-26 05:06:50 +0000755\begin{funcdesc}{tuple}{\optional{sequence}}
Fred Drakee0063d22001-10-09 19:31:08 +0000756 Return a tuple whose items are the same and in the same order as
757 \var{sequence}'s items. \var{sequence} may be a sequence, a
758 container that supports iteration, or an iterator object.
759 If \var{sequence} is already a tuple, it
760 is returned unchanged. For instance, \code{tuple('abc')} returns
761 returns \code{('a', 'b', 'c')} and \code{tuple([1, 2, 3])} returns
762 \code{(1, 2, 3)}.
Guido van Rossumb8b264b1994-08-12 13:13:50 +0000763\end{funcdesc}
764
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000765\begin{funcdesc}{type}{object}
Fred Drakee0063d22001-10-09 19:31:08 +0000766 Return the type of an \var{object}. The return value is a
767 type\obindex{type} object. The standard module
768 \module{types}\refstmodindex{types} defines names for all built-in
769 types.
770 For instance:
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000771
Fred Drake19479911998-02-13 06:58:54 +0000772\begin{verbatim}
Guido van Rossum470be141995-03-17 16:07:09 +0000773>>> import types
Guido van Rossuma7874d11998-06-22 14:07:36 +0000774>>> if type(x) == types.StringType: print "It's a string"
Fred Drake19479911998-02-13 06:58:54 +0000775\end{verbatim}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000776\end{funcdesc}
Guido van Rossum68cfbe71994-02-24 11:28:27 +0000777
Fred Drake33d51842000-04-06 14:43:12 +0000778\begin{funcdesc}{unichr}{i}
Fred Drakee0063d22001-10-09 19:31:08 +0000779 Return the Unicode string of one character whose Unicode code is the
780 integer \var{i}. For example, \code{unichr(97)} returns the string
781 \code{u'a'}. This is the inverse of \function{ord()} for Unicode
782 strings. The argument must be in the range [0..65535], inclusive.
783 \exception{ValueError} is raised otherwise.
784 \versionadded{2.0}
Fred Drake33d51842000-04-06 14:43:12 +0000785\end{funcdesc}
786
Marc-André Lemburgb5507ec2001-10-19 12:02:29 +0000787\begin{funcdesc}{unicode}{object\optional{, encoding\optional{, errors}}}
788 Return the Unicode string version of \var{object} using one of the
789 following modes:
790
791 If \var{encoding} and/or \var{errors} are given, \code{unicode()}
792 will decode the object which can either be an 8-bit string or a
793 character buffer using the codec for \var{encoding}. The
794 \var{encoding} parameter is a string giving the name of an encoding.
795 Error handling is done according to \var{errors}; this specifies the
796 treatment of characters which are invalid in the input encoding. If
797 \var{errors} is \code{'strict'} (the default), a
798 \exception{ValueError} is raised on errors, while a value of
799 \code{'ignore'} causes errors to be silently ignored, and a value of
800 \code{'replace'} causes the official Unicode replacement character,
801 \code{U+FFFD}, to be used to replace input characters which cannot
802 be decoded. See also the \refmodule{codecs} module.
803
804 If no optional parameters are given, \code{unicode()} will mimic the
805 behaviour of \code{str()} except that it returns Unicode strings
806 instead of 8-bit strings. More precisely, if \var{object} is an
807 Unicode string or subclass it will return a Unicode string without
808 any additional decoding applied. For objects which provide a
809 \code{__unicode__} method, it will call this method without
810 arguments to create a Unicode string. For all other objects, the
811 8-bit string version or representation is requested and then
812 converted to a Unicode string using the codec for the default
813 encoding in \code{'strict'} mode.
Fred Drakee0063d22001-10-09 19:31:08 +0000814 \versionadded{2.0}
Fred Drake33d51842000-04-06 14:43:12 +0000815\end{funcdesc}
816
Guido van Rossum6bb1adc1995-03-13 10:03:32 +0000817\begin{funcdesc}{vars}{\optional{object}}
Fred Drakee0063d22001-10-09 19:31:08 +0000818 Without arguments, return a dictionary corresponding to the current
819 local symbol table. With a module, class or class instance object
820 as argument (or anything else that has a \member{__dict__}
821 attribute), returns a dictionary corresponding to the object's
822 symbol table. The returned dictionary should not be modified: the
823 effects on the corresponding symbol table are undefined.\footnote{
824 In the current implementation, local variable bindings cannot
825 normally be affected this way, but variables retrieved from
826 other scopes (such as modules) can be. This may change.}
Guido van Rossum17383111994-04-21 10:32:28 +0000827\end{funcdesc}
828
Fred Drakecce10901998-03-17 06:33:25 +0000829\begin{funcdesc}{xrange}{\optional{start,} stop\optional{, step}}
Fred Drakee0063d22001-10-09 19:31:08 +0000830 This function is very similar to \function{range()}, but returns an
831 ``xrange object'' instead of a list. This is an opaque sequence
832 type which yields the same values as the corresponding list, without
833 actually storing them all simultaneously. The advantage of
834 \function{xrange()} over \function{range()} is minimal (since
835 \function{xrange()} still has to create the values when asked for
836 them) except when a very large range is used on a memory-starved
837 machine or when all of the range's elements are never used (such as
838 when the loop is usually terminated with \keyword{break}).
Guido van Rossum68cfbe71994-02-24 11:28:27 +0000839\end{funcdesc}
Barry Warsawfaefa2a2000-08-03 15:46:17 +0000840
Fred Drake8b168ba2000-08-03 17:29:13 +0000841\begin{funcdesc}{zip}{seq1, \moreargs}
Fred Drake5172adc2001-12-03 18:35:05 +0000842 This function returns a list of tuples, where the \var{i}-th tuple contains
Fred Drakee0063d22001-10-09 19:31:08 +0000843 the \var{i}-th element from each of the argument sequences. At
844 least one sequence is required, otherwise a \exception{TypeError} is
845 raised. The returned list is truncated in length to the length of
846 the shortest argument sequence. When there are multiple argument
847 sequences which are all of the same length, \function{zip()} is
848 similar to \function{map()} with an initial argument of \code{None}.
849 With a single sequence argument, it returns a list of 1-tuples.
850 \versionadded{2.0}
Fred Drake8b168ba2000-08-03 17:29:13 +0000851\end{funcdesc}