1 \section{Built-in Functions
\label{built-in-funcs
}}
3 The Python interpreter has a number of functions built into it that
4 are always available. They are listed here in alphabetical order.
7 \setindexsubitem{(built-in function)
}
9 \begin{funcdesc
}{__import__
}{name
\optional{, globals
\optional{, locals
\optional{, fromlist
}}}}
10 This function is invoked by the
11 \keyword{import
}\stindex{import
} statement. It mainly
12 exists so that you can replace it with another function that has a
13 compatible interface, in order to change the semantics of the
14 \keyword{import
} statement. For examples of why and how you would do
15 this, see the standard library modules
16 \module{ihooks
}\refstmodindex{ihooks
} and
17 \refmodule{rexec
}\refstmodindex{rexec
}. See also the built-in module
18 \refmodule{imp
}\refbimodindex{imp
}, which defines some useful
19 operations out of which you can build your own
20 \function{__import__()
} function.
22 For example, the statement
\samp{import spam
} results in the
24 \code{__import__('spam',
} \code{globals(),
} \code{locals(),
[])
};
25 the statement
\samp{from spam.ham import eggs
} results
26 in
\samp{__import__('spam.ham', globals(), locals(),
['eggs'
])
}.
27 Note that even though
\code{locals()
} and
\code{['eggs'
]} are passed
28 in as arguments, the
\function{__import__()
} function does not set the
29 local variable named
\code{eggs
}; this is done by subsequent code that
30 is generated for the import statement. (In fact, the standard
31 implementation does not use its
\var{locals
} argument at all, and uses
32 its
\var{globals
} only to determine the package context of the
33 \keyword{import
} statement.)
35 When the
\var{name
} variable is of the form
\code{package.module
},
36 normally, the top-level package (the name up till the first dot) is
37 returned,
\emph{not
} the module named by
\var{name
}. However, when a
38 non-empty
\var{fromlist
} argument is given, the module named by
39 \var{name
} is returned. This is done for compatibility with the
40 bytecode generated for the different kinds of import statement; when
41 using
\samp{import spam.ham.eggs
}, the top-level package
\code{spam
}
42 must be placed in the importing namespace, but when using
\samp{from
43 spam.ham import eggs
}, the
\code{spam.ham
} subpackage must be used to
44 find the
\code{eggs
} variable.
45 As a workaround for this behavior, use
\function{getattr()
} to extract
46 the desired components. For example, you could define the following
53 mod = __import__(name)
54 components = string.split(name, '.')
55 for comp in components
[1:
]:
56 mod = getattr(mod, comp)
62 \begin{funcdesc
}{abs
}{x
}
63 Return the absolute value of a number. The argument may be a plain
64 or long integer or a floating point number. If the argument is a
65 complex number, its magnitude is returned.
68 \begin{funcdesc
}{apply
}{function, args
\optional{, keywords
}}
69 The
\var{function
} argument must be a callable object (a user-defined or
70 built-in function or method, or a class object) and the
\var{args
}
71 argument must be a sequence (if it is not a tuple, the sequence is
72 first converted to a tuple). The
\var{function
} is called with
73 \var{args
} as the argument list; the number of arguments is the the length
74 of the tuple. (This is different from just calling
75 \code{\var{func
}(
\var{args
})
}, since in that case there is always
76 exactly one argument.)
77 If the optional
\var{keywords
} argument is present, it must be a
78 dictionary whose keys are strings. It specifies keyword arguments to
79 be added to the end of the the argument list.
82 \begin{funcdesc
}{buffer
}{object
\optional{, offset
\optional{, size
}}}
83 The
\var{object
} argument must be an object that supports the
84 buffer call interface (such as strings, arrays, and buffers). A new
85 buffer object will be created which references the
\var{object
} argument.
86 The buffer object will be a slice from the beginning of
\var{object
}
87 (or from the specified
\var{offset
}). The slice will extend to the
88 end of
\var{object
} (or will have a length given by the
\var{size
}
92 \begin{funcdesc
}{callable
}{object
}
93 Return true if the
\var{object
} argument appears callable, false if
94 not. If this returns true, it is still possible that a call fails,
95 but if it is false, calling
\var{object
} will never succeed. Note
96 that classes are callable (calling a class returns a new instance);
97 class instances are callable if they have a
\method{__call__()
} method.
100 \begin{funcdesc
}{chr
}{i
}
101 Return a string of one character whose
\ASCII{} code is the integer
102 \var{i
}. For example,
\code{chr(
97)
} returns the string
\code{'a'
}.
103 This is the inverse of
\function{ord()
}. The argument must be in
104 the range
[0.
.255], inclusive;
\exception{ValueError
} will be raised
105 if
\var{i
} is outside that range.
108 \begin{funcdesc
}{cmp
}{x, y
}
109 Compare the two objects
\var{x
} and
\var{y
} and return an integer
110 according to the outcome. The return value is negative if
\code{\var{x
}
111 <
\var{y
}}, zero if
\code{\var{x
} ==
\var{y
}} and strictly positive if
112 \code{\var{x
} >
\var{y
}}.
115 \begin{funcdesc
}{coerce
}{x, y
}
116 Return a tuple consisting of the two numeric arguments converted to
117 a common type, using the same rules as used by arithmetic
121 \begin{funcdesc
}{compile
}{string, filename, kind
}
122 Compile the
\var{string
} into a code object. Code objects can be
123 executed by an
\keyword{exec
} statement or evaluated by a call to
124 \function{eval()
}. The
\var{filename
} argument should
125 give the file from which the code was read; pass same recognizable value
126 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).
135 \begin{funcdesc
}{complex
}{real
\optional{, imag
}}
136 Create a complex number with the value
\var{real
} +
\var{imag
}*j or
137 convert a string or number to a complex number.
138 Each argument may be any numeric type (including complex).
139 If
\var{imag
} is omitted, it defaults to zero and the function
140 serves as a numeric conversion function like
\function{int()
},
141 \function{long()
} and
\function{float()
}; in this case it also
142 accepts a string argument which should be a valid complex number.
145 \begin{funcdesc
}{delattr
}{object, name
}
146 This is a relative of
\function{setattr()
}. The arguments are an
147 object and a string. The string must be the name
148 of one of the object's attributes. The function deletes
149 the named attribute, provided the object allows it. For example,
150 \code{delattr(
\var{x
}, '
\var{foobar
}')
} is equivalent to
151 \code{del
\var{x
}.
\var{foobar
}}.
154 \begin{funcdesc
}{dir
}{\optional{object
}}
155 Without arguments, return the list of names in the current local
156 symbol table. With an argument, attempts to return a list of valid
157 attribute for that object. This information is gleaned from the
158 object's
\member{__dict__
},
\member{__methods__
} and
\member{__members__
}
159 attributes, if defined. The list is not necessarily complete. For
160 example, for classes, attributes defined in base classes are not
161 included, and for class instances, methods are not included.
162 The resulting list is sorted alphabetically. For example:
169 ['argv', 'exit', 'modules', 'path', 'stderr', 'stdin', 'stdout'
]
173 \begin{funcdesc
}{divmod
}{a, b
}
174 Take two numbers as arguments and return a pair of numbers consisting
175 of their quotient and remainder when using long division. With mixed
176 operand types, the rules for binary arithmetic operators apply. For
177 plain and long integers, the result is the same as
178 \code{(
\var{a
} /
\var{b
},
\var{a
} \%
{} \var{b
})
}.
179 For floating point numbers the result is
\code{(
\var{q
},
\var{a
} \%
{}
180 \var{b
})
}, where
\var{q
} is usually
\code{math.floor(
\var{a
} /
181 \var{b
})
} but may be
1 less than that. In any case
\code{\var{q
} *
182 \var{b
} +
\var{a
} \%
{} \var{b
}} is very close to
\var{a
}, if
183 \code{\var{a
} \%
{} \var{b
}} is non-zero it has the same sign as
184 \var{b
}, and
\code{0 <= abs(
\var{a
} \%
{} \var{b
}) < abs(
\var{b
})
}.
187 \begin{funcdesc
}{eval
}{expression
\optional{, globals
\optional{, locals
}}}
188 The arguments are a string and two optional dictionaries. The
189 \var{expression
} argument is parsed and evaluated as a Python
190 expression (technically speaking, a condition list) using the
191 \var{globals
} and
\var{locals
} dictionaries as global and local name
192 space. If the
\var{locals
} dictionary is omitted it defaults to
193 the
\var{globals
} dictionary. If both dictionaries are omitted, the
194 expression is executed in the environment where
\keyword{eval
} is
195 called. The return value is the result of the evaluated expression.
196 Syntax errors are reported as exceptions. Example:
200 >>> print eval('x+
1')
204 This function can also be used to execute arbitrary code objects
205 (such as those created by
\function{compile()
}). In this case pass
206 a code object instead of a string. The code object must have been
207 compiled passing
\code{'eval'
} as the
\var{kind
} argument.
209 Hints: dynamic execution of statements is supported by the
210 \keyword{exec
} statement. Execution of statements from a file is
211 supported by the
\function{execfile()
} function. The
212 \function{globals()
} and
\function{locals()
} functions returns the
213 current global and local dictionary, respectively, which may be
214 useful to pass around for use by
\function{eval()
} or
215 \function{execfile()
}.
218 \begin{funcdesc
}{execfile
}{file
\optional{, globals
\optional{, locals
}}}
219 This function is similar to the
220 \keyword{exec
} statement, but parses a file instead of a string. It
221 is different from the
\keyword{import
} statement in that it does not
222 use the module administration --- it reads the file unconditionally
223 and does not create a new module.
\footnote{It is used relatively
224 rarely so does not warrant being made into a statement.
}
226 The arguments are a file name and two optional dictionaries. The
227 file is parsed and evaluated as a sequence of Python statements
228 (similarly to a module) using the
\var{globals
} and
\var{locals
}
229 dictionaries as global and local namespace. If the
\var{locals
}
230 dictionary is omitted it defaults to the
\var{globals
} dictionary.
231 If both dictionaries are omitted, the expression is executed in the
232 environment where
\function{execfile()
} is called. The return value is
236 \begin{funcdesc
}{filter
}{function, list
}
237 Construct a list from those elements of
\var{list
} for which
238 \var{function
} returns true.
\var{list
} may be either a sequence, a
239 container which supports iteration, or an iterator, If
\var{list
}
240 is a string or a tuple, the result also has that type; otherwise it
241 is always a list. If
\var{function
} is
\code{None
}, the identity
242 function is assumed, that is, all elements of
\var{list
} that are false
243 (zero or empty) are removed.
246 \begin{funcdesc
}{float
}{x
}
247 Convert a string or a number to floating point. If the argument is a
248 string, it must contain a possibly signed decimal or floating point
249 number, possibly embedded in whitespace; this behaves identical to
250 \code{string.atof(
\var{x
})
}. Otherwise, the argument may be a plain
251 or long integer or a floating point number, and a floating point
252 number with the same value (within Python's floating point
253 precision) is returned.
255 \strong{Note:
} When passing in a string, values for NaN
\index{NaN
}
256 and Infinity
\index{Infinity
} may be returned, depending on the
257 underlying C library. The specific set of strings accepted which
258 cause these values to be returned depends entirely on the C library
259 and is known to vary.
262 \begin{funcdesc
}{getattr
}{object, name
\optional{, default
}}
263 Return the value of the named attributed of
\var{object
}.
\var{name
}
264 must be a string. If the string is the name of one of the object's
265 attributes, the result is the value of that attribute. For example,
266 \code{getattr(x, 'foobar')
} is equivalent to
\code{x.foobar
}. If the
267 named attribute does not exist,
\var{default
} is returned if provided,
268 otherwise
\exception{AttributeError
} is raised.
271 \begin{funcdesc
}{globals
}{}
272 Return a dictionary representing the current global symbol table.
273 This is always the dictionary of the current module (inside a
274 function or method, this is the module where it is defined, not the
275 module from which it is called).
278 \begin{funcdesc
}{hasattr
}{object, name
}
279 The arguments are an object and a string. The result is
1 if the
280 string is the name of one of the object's attributes,
0 if not.
281 (This is implemented by calling
\code{getattr(
\var{object
},
282 \var{name
})
} and seeing whether it raises an exception or not.)
285 \begin{funcdesc
}{hash
}{object
}
286 Return the hash value of the object (if it has one). Hash values
287 are integers. They are used to quickly compare dictionary
288 keys during a dictionary lookup. Numeric values that compare equal
289 have the same hash value (even if they are of different types, as is
290 the case for
1 and
1.0).
293 \begin{funcdesc
}{hex
}{x
}
294 Convert an integer number (of any size) to a hexadecimal string.
295 The result is a valid Python expression. Note: this always yields
296 an unsigned literal. For example, on a
32-bit machine,
297 \code{hex(-
1)
} yields
\code{'
0xffffffff'
}. When evaluated on a
298 machine with the same word size, this literal is evaluated as -
1; at
299 a different word size, it may turn up as a large positive number or
300 raise an
\exception{OverflowError
} exception.
303 \begin{funcdesc
}{id
}{object
}
304 Return the `identity' of an object. This is an integer (or long
305 integer) which is guaranteed to be unique and constant for this
306 object during its lifetime. Two objects whose lifetimes are
307 disjunct may have the same
\function{id()
} value. (Implementation
308 note: this is the address of the object.)
311 \begin{funcdesc
}{input
}{\optional{prompt
}}
312 Equivalent to
\code{eval(raw_input(
\var{prompt
}))
}.
313 \strong{Warning:
} This function is not safe from user errors! It
314 expects a valid Python expression as input; if the input is not
315 syntactically valid, a
\exception{SyntaxError
} will be raised.
316 Other exceptions may be raised if there is an error during
317 evaluation. (On the other hand, sometimes this is exactly what you
318 need when writing a quick script for expert use.)
320 If the
\module{readline
} module was loaded, then
321 \function{input()
} will use it to provide elaborate line editing and
324 Consider using the
\function{raw_input()
} function for general input
328 \begin{funcdesc
}{int
}{x
\optional{, radix
}}
329 Convert a string or number to a plain integer. If the argument is a
330 string, it must contain a possibly signed decimal number
331 representable as a Python integer, possibly embedded in whitespace;
332 this behaves identical to
\code{string.atoi(
\var{x
}\optional{,
333 \var{radix
}})
}. The
\var{radix
} parameter gives the base for the
334 conversion and may be any integer in the range
[2,
36], or zero. If
335 \var{radix
} is zero, the proper radix is guessed based on the
336 contents of string; the interpretation is the same as for integer
337 literals. If
\var{radix
} is specified and
\var{x
} is not a string,
338 \exception{TypeError
} is raised.
339 Otherwise, the argument may be a plain or
340 long integer or a floating point number. Conversion of floating
341 point numbers to integers is defined by the C semantics; normally
342 the conversion truncates towards zero.
\footnote{This is ugly --- the
343 language definition should require truncation towards zero.
}
346 \begin{funcdesc
}{intern
}{string
}
347 Enter
\var{string
} in the table of ``interned'' strings and return
348 the interned string -- which is
\var{string
} itself or a copy.
349 Interning strings is useful to gain a little performance on
350 dictionary lookup -- if the keys in a dictionary are interned, and
351 the lookup key is interned, the key comparisons (after hashing) can
352 be done by a pointer compare instead of a string compare. Normally,
353 the names used in Python programs are automatically interned, and
354 the dictionaries used to hold module, class or instance attributes
355 have interned keys. Interned strings are immortal (never get
359 \begin{funcdesc
}{isinstance
}{object, class
}
360 Return true if the
\var{object
} argument is an instance of the
361 \var{class
} argument, or of a (direct or indirect) subclass thereof.
362 Also return true if
\var{class
} is a type object and
\var{object
} is
363 an object of that type. If
\var{object
} is not a class instance or a
364 object of the given type, the function always returns false. If
365 \var{class
} is neither a class object nor a type object, a
366 \exception{TypeError
} exception is raised.
369 \begin{funcdesc
}{issubclass
}{class1, class2
}
370 Return true if
\var{class1
} is a subclass (direct or indirect) of
371 \var{class2
}. A class is considered a subclass of itself. If either
372 argument is not a class object, a
\exception{TypeError
} exception is
376 \begin{funcdesc
}{len
}{s
}
377 Return the length (the number of items) of an object. The argument
378 may be a sequence (string, tuple or list) or a mapping (dictionary).
381 \begin{funcdesc
}{list
}{sequence
}
382 Return a list whose items are the same and in the same order as
383 \var{sequence
}'s items.
\var{sequence
} may be either a sequence, a
384 container that supports iteration, or an iterator object. If
385 \var{sequence
} is already a list, a copy is made and returned,
386 similar to
\code{\var{sequence
}[:
]}. For instance,
387 \code{list('abc')
} returns
\code{['a', 'b', 'c'
]} and
\code{list(
388 (
1,
2,
3) )
} returns
\code{[1,
2,
3]}.
391 \begin{funcdesc
}{locals
}{}
392 Return a dictionary representing the current local symbol table.
393 \strong{Warning:
} The contents of this dictionary should not be
394 modified; changes may not affect the values of local variables used by
398 \begin{funcdesc
}{long
}{x
\optional{, radix
}}
399 Convert a string or number to a long integer. If the argument is a
400 string, it must contain a possibly signed number of
401 arbitrary size, possibly embedded in whitespace;
402 this behaves identical to
\code{string.atol(
\var{x
})
}. The
403 \var{radix
} argument is interpreted in the same way as for
404 \function{int()
}, and may only be given when
\var{x
} is a string.
405 Otherwise, the argument may be a plain or
406 long integer or a floating point number, and a long integer with
407 the same value is returned. Conversion of floating
408 point numbers to integers is defined by the C semantics;
409 see the description of
\function{int()
}.
412 \begin{funcdesc
}{map
}{function, list, ...
}
413 Apply
\var{function
} to every item of
\var{list
} and return a list
414 of the results. If additional
\var{list
} arguments are passed,
415 \var{function
} must take that many arguments and is applied to the
416 items of all lists in parallel; if a list is shorter than another it
417 is assumed to be extended with
\code{None
} items. If
\var{function
}
418 is
\code{None
}, the identity function is assumed; if there are
419 multiple list arguments,
\function{map()
} returns a list consisting
420 of tuples containing the corresponding items from all lists (a kind
421 of transpose operation). The
\var{list
} arguments may be any kind
422 of sequence; the result is always a list.
425 \begin{funcdesc
}{max
}{s
\optional{, args...
}}
426 With a single argument
\var{s
}, return the largest item of a
427 non-empty sequence (such as a string, tuple or list). With more
428 than one argument, return the largest of the arguments.
431 \begin{funcdesc
}{min
}{s
\optional{, args...
}}
432 With a single argument
\var{s
}, return the smallest item of a
433 non-empty sequence (such as a string, tuple or list). With more
434 than one argument, return the smallest of the arguments.
437 \begin{funcdesc
}{oct
}{x
}
438 Convert an integer number (of any size) to an octal string. The
439 result is a valid Python expression. Note: this always yields an
440 unsigned literal. For example, on a
32-bit machine,
\code{oct(-
1)
}
441 yields
\code{'
037777777777'
}. When evaluated on a machine with the
442 same word size, this literal is evaluated as -
1; at a different word
443 size, it may turn up as a large positive number or raise an
444 \exception{OverflowError
} exception.
447 \begin{funcdesc
}{open
}{filename
\optional{, mode
\optional{, bufsize
}}}
448 Return a new file object (described earlier under Built-in Types).
449 The first two arguments are the same as for
\code{stdio
}'s
450 \cfunction{fopen()
}:
\var{filename
} is the file name to be opened,
451 \var{mode
} indicates how the file is to be opened:
\code{'r'
} for
452 reading,
\code{'w'
} for writing (truncating an existing file), and
453 \code{'a'
} opens it for appending (which on
\emph{some
} \UNIX{}
454 systems means that
\emph{all
} writes append to the end of the file,
455 regardless of the current seek position).
457 Modes
\code{'r+'
},
\code{'w+'
} and
\code{'a+'
} open the file for
458 updating (note that
\code{'w+'
} truncates the file). Append
459 \code{'b'
} to the mode to open the file in binary mode, on systems
460 that differentiate between binary and text files (else it is
461 ignored). If the file cannot be opened,
\exception{IOError
} is
464 If
\var{mode
} is omitted, it defaults to
\code{'r'
}. When opening a
465 binary file, you should append
\code{'b'
} to the
\var{mode
} value
466 for improved portability. (It's useful even on systems which don't
467 treat binary and text files differently, where it serves as
469 \index{line-buffered I/O
}\index{unbuffered I/O
}\index{buffer size, I/O
}
470 \index{I/O control!buffering
}
471 The optional
\var{bufsize
} argument specifies the
472 file's desired buffer size:
0 means unbuffered,
1 means line
473 buffered, any other positive value means use a buffer of
474 (approximately) that size. A negative
\var{bufsize
} means to use
475 the system default, which is usually line buffered for for tty
476 devices and fully buffered for other files. If omitted, the system
477 default is used.
\footnote{
478 Specifying a buffer size currently has no effect on systems that
479 don't have
\cfunction{setvbuf()
}. The interface to specify the
480 buffer size is not done using a method that calls
481 \cfunction{setvbuf()
}, because that may dump core when called
482 after any I/O has been performed, and there's no reliable way to
483 determine whether this is the case.
}
486 \begin{funcdesc
}{ord
}{c
}
487 Return the
\ASCII{} value of a string of one character or a Unicode
488 character. E.g.,
\code{ord('a')
} returns the integer
\code{97},
489 \code{ord(u'\
\u2020')
} returns
\code{8224}. This is the inverse of
490 \function{chr()
} for strings and of
\function{unichr()
} for Unicode
494 \begin{funcdesc
}{pow
}{x, y
\optional{, z
}}
495 Return
\var{x
} to the power
\var{y
}; if
\var{z
} is present, return
496 \var{x
} to the power
\var{y
}, modulo
\var{z
} (computed more
497 efficiently than
\code{pow(
\var{x
},
\var{y
}) \%\
\var{z
}}). The
498 arguments must have numeric types. With mixed operand types, the
499 coercion rules for binary arithmetic operators apply. For int and
500 long int operands, the result has the same type as the operands
501 (after coercion) unless the second argument is negative; in that
502 case, all arguments are converted to float and a float result is
503 delivered. For example,
\code{10**
2} returns
\code{100}, but
504 \code{10**-
2} returns
\code{0.01}. (This last feature was added in
505 Python
2.2. In Python
2.1 and before, a negative second argument
506 would raise an exception.)
509 \begin{funcdesc
}{range
}{\optional{start,
} stop
\optional{, step
}}
510 This is a versatile function to create lists containing arithmetic
511 progressions. It is most often used in
\keyword{for
} loops. The
512 arguments must be plain integers. If the
\var{step
} argument is
513 omitted, it defaults to
\code{1}. If the
\var{start
} argument is
514 omitted, it defaults to
\code{0}. The full form returns a list of
515 plain integers
\code{[\var{start
},
\var{start
} +
\var{step
},
516 \var{start
} +
2 *
\var{step
},
\ldots]}. If
\var{step
} is positive,
517 the last element is the largest
\code{\var{start
} +
\var{i
} *
518 \var{step
}} less than
\var{stop
}; if
\var{step
} is negative, the last
519 element is the largest
\code{\var{start
} +
\var{i
} *
\var{step
}}
520 greater than
\var{stop
}.
\var{step
} must not be zero (or else
521 \exception{ValueError
} is raised). Example:
525 [0,
1,
2,
3,
4,
5,
6,
7,
8,
9]
527 [1,
2,
3,
4,
5,
6,
7,
8,
9,
10]
529 [0,
5,
10,
15,
20,
25]
532 >>> range(
0, -
10, -
1)
533 [0, -
1, -
2, -
3, -
4, -
5, -
6, -
7, -
8, -
9]
541 \begin{funcdesc
}{raw_input
}{\optional{prompt
}}
542 If the
\var{prompt
} argument is present, it is written to standard output
543 without a trailing newline. The function then reads a line from input,
544 converts it to a string (stripping a trailing newline), and returns that.
545 When
\EOF{} is read,
\exception{EOFError
} is raised. Example:
548 >>> s = raw_input('--> ')
549 --> Monty Python's Flying Circus
551 "Monty Python's Flying Circus"
554 If the
\module{readline
} module was loaded, then
555 \function{raw_input()
} will use it to provide elaborate
556 line editing and history features.
559 \begin{funcdesc
}{reduce
}{function, sequence
\optional{, initializer
}}
560 Apply
\var{function
} of two arguments cumulatively to the items of
561 \var{sequence
}, from left to right, so as to reduce the sequence to
562 a single value. For example,
563 \code{reduce(lambda x, y: x+y,
[1,
2,
3,
4,
5])
} calculates
564 \code{((((
1+
2)+
3)+
4)+
5)
}.
565 If the optional
\var{initializer
} is present, it is placed before the
566 items of the sequence in the calculation, and serves as a default when
567 the sequence is empty.
570 \begin{funcdesc
}{reload
}{module
}
571 Re-parse and re-initialize an already imported
\var{module
}. The
572 argument must be a module object, so it must have been successfully
573 imported before. This is useful if you have edited the module source
574 file using an external editor and want to try out the new version
575 without leaving the Python interpreter. The return value is the
576 module object (the same as the
\var{module
} argument).
578 There are a number of caveats:
580 If a module is syntactically correct but its initialization fails, the
581 first
\keyword{import
} statement for it does not bind its name locally,
582 but does store a (partially initialized) module object in
583 \code{sys.modules
}. To reload the module you must first
584 \keyword{import
} it again (this will bind the name to the partially
585 initialized module object) before you can
\function{reload()
} it.
587 When a module is reloaded, its dictionary (containing the module's
588 global variables) is retained. Redefinitions of names will override
589 the old definitions, so this is generally not a problem. If the new
590 version of a module does not define a name that was defined by the old
591 version, the old definition remains. This feature can be used to the
592 module's advantage if it maintains a global table or cache of objects
593 --- with a
\keyword{try
} statement it can test for the table's presence
594 and skip its initialization if desired.
596 It is legal though generally not very useful to reload built-in or
597 dynamically loaded modules, except for
\module{sys
},
\module{__main__
}
598 and
\module{__builtin__
}. In many cases, however, extension
599 modules are not designed to be initialized more than once, and may
600 fail in arbitrary ways when reloaded.
602 If a module imports objects from another module using
\keyword{from
}
603 \ldots{} \keyword{import
} \ldots{}, calling
\function{reload()
} for
604 the other module does not redefine the objects imported from it ---
605 one way around this is to re-execute the
\keyword{from
} statement,
606 another is to use
\keyword{import
} and qualified names
607 (
\var{module
}.
\var{name
}) instead.
609 If a module instantiates instances of a class, reloading the module
610 that defines the class does not affect the method definitions of the
611 instances --- they continue to use the old class definition. The same
612 is true for derived classes.
615 \begin{funcdesc
}{repr
}{object
}
616 Return a string containing a printable representation of an object.
617 This is the same value yielded by conversions (reverse quotes).
618 It is sometimes useful to be able to access this operation as an
619 ordinary function. For many types, this function makes an attempt
620 to return a string that would yield an object with the same value
621 when passed to
\function{eval()
}.
624 \begin{funcdesc
}{round
}{x
\optional{, n
}}
625 Return the floating point value
\var{x
} rounded to
\var{n
} digits
626 after the decimal point. If
\var{n
} is omitted, it defaults to zero.
627 The result is a floating point number. Values are rounded to the
628 closest multiple of
10 to the power minus
\var{n
}; if two multiples
629 are equally close, rounding is done away from
0 (so. for example,
630 \code{round(
0.5)
} is
\code{1.0} and
\code{round(-
0.5)
} is
\code{-
1.0}).
633 \begin{funcdesc
}{setattr
}{object, name, value
}
634 This is the counterpart of
\function{getattr()
}. The arguments are an
635 object, a string and an arbitrary value. The string may name an
636 existing attribute or a new attribute. The function assigns the
637 value to the attribute, provided the object allows it. For example,
638 \code{setattr(
\var{x
}, '
\var{foobar
}',
123)
} is equivalent to
639 \code{\var{x
}.
\var{foobar
} =
123}.
642 \begin{funcdesc
}{slice
}{\optional{start,
} stop
\optional{, step
}}
643 Return a slice object representing the set of indices specified by
644 \code{range(
\var{start
},
\var{stop
},
\var{step
})
}. The
\var{start
}
645 and
\var{step
} arguments default to None. Slice objects have
646 read-only data attributes
\member{start
},
\member{stop
} and
\member{step
}
647 which merely return the argument values (or their default). They have
648 no other explicit functionality; however they are used by Numerical
649 Python
\index{Numerical Python
} and other third party extensions.
650 Slice objects are also generated when extended indexing syntax is
651 used. For example:
\samp{a
[start:stop:step
]} or
\samp{a
[start:stop, i
]}.
654 \begin{funcdesc
}{str
}{object
}
655 Return a string containing a nicely printable representation of an
656 object. For strings, this returns the string itself. The difference
657 with
\code{repr(
\var{object
})
} is that
\code{str(
\var{object
})
} does not
658 always attempt to return a string that is acceptable to
\function{eval()
};
659 its goal is to return a printable string.
662 \begin{funcdesc
}{tuple
}{sequence
}
663 Return a tuple whose items are the same and in the same order as
664 \var{sequence
}'s items. If
\var{sequence
} is already a tuple, it
665 is returned unchanged. For instance,
\code{tuple('abc')
} returns
666 returns
\code{('a', 'b', 'c')
} and
\code{tuple(
[1,
2,
3])
} returns
670 \begin{funcdesc
}{type
}{object
}
671 Return the type of an
\var{object
}. The return value is a type
672 object. The standard module
\module{types
} defines names for all
674 \refstmodindex{types
}
680 >>> if type(x) == types.StringType: print "It's a string"
684 \begin{funcdesc
}{unichr
}{i
}
685 Return the Unicode string of one character whose Unicode code is the
686 integer
\var{i
}. For example,
\code{unichr(
97)
} returns the string
687 \code{u'a'
}. This is the inverse of
\function{ord()
} for Unicode
688 strings. The argument must be in the range
[0.
.65535], inclusive.
689 \exception{ValueError
} is raised otherwise.
693 \begin{funcdesc
}{unicode
}{string
\optional{, encoding
\optional{, errors
}}}
694 Create a Unicode string from an
8-bit string
\var{string
} using the
695 codec for
\var{encoding
}. The
\var{encoding
} parameter is a string
696 giving the name of an encoding. Error handling is done according to
697 \var{errors
}; this specifies the treatment of characters which are
698 invalid in the input encoding. If
\var{errors
} is
\code{'strict'
}
699 (the default), a
\exception{ValueError
} is raised on errors, while a
700 value of
\code{'ignore'
} causes errors to be silently ignored, and a
701 value of
\code{'replace'
} causes the official Unicode replacement
702 character,
\code{U+FFFD
}, to be used to replace input characters which
703 cannot be decoded. The default behavior is to decode UTF-
8 in strict
704 mode, meaning that encoding errors raise
\exception{ValueError
}. See
705 also the
\refmodule{codecs
} module.
709 \begin{funcdesc
}{vars
}{\optional{object
}}
710 Without arguments, return a dictionary corresponding to the current
711 local symbol table. With a module, class or class instance object as
712 argument (or anything else that has a
\member{__dict__
} attribute),
713 returns a dictionary corresponding to the object's symbol table.
714 The returned dictionary should not be modified: the effects on the
715 corresponding symbol table are undefined.
\footnote{
716 In the current implementation, local variable bindings cannot
717 normally be affected this way, but variables retrieved from
718 other scopes (such as modules) can be. This may change.
}
721 \begin{funcdesc
}{xrange
}{\optional{start,
} stop
\optional{, step
}}
722 This function is very similar to
\function{range()
}, but returns an
723 ``xrange object'' instead of a list. This is an opaque sequence type
724 which yields the same values as the corresponding list, without
725 actually storing them all simultaneously. The advantage of
726 \function{xrange()
} over
\function{range()
} is minimal (since
727 \function{xrange()
} still has to create the values when asked for
728 them) except when a very large range is used on a memory-starved
729 machine or when all of the range's elements are never used (such as
730 when the loop is usually terminated with
\keyword{break
}).
733 \begin{funcdesc
}{zip
}{seq1,
\moreargs}
734 This function returns a list of tuples, where each tuple contains the
735 \var{i
}-th element from each of the argument sequences. At least one
736 sequence is required, otherwise a
\exception{TypeError
} is raised.
737 The returned list is truncated in length to the length of the shortest
738 argument sequence. When there are multiple argument sequences which
739 are all of the same length,
\function{zip()
} is similar to
740 \function{map()
} with an initial argument of
\code{None
}. With a
741 single sequence argument, it returns a list of
1-tuples.
