Doc/libfuncs.tex

   1 \section{Built-in Functions}
   2
   3 The Python interpreter has a number of functions built into it that
   4 are always available.  They are listed here in alphabetical order.
   5
   6
   7 \renewcommand{\indexsubitem}{(built-in function)}
   8 \begin{funcdesc}{abs}{x}
   9   Return the absolute value of a number.  The argument may be a plain
  10   or long integer or a floating point number.
  11 \end{funcdesc}
  12
  13 \begin{funcdesc}{apply}{function\, args\optional{, keywords}}
  14 The \var{function} argument must be a callable object (a user-defined or
  15 built-in function or method, or a class object) and the \var{args}
  16 argument must be a tuple.  The \var{function} is called with
  17 \var{args} as argument list; the number of arguments is the the length
  18 of the tuple.  (This is different from just calling
  19 \code{\var{func}(\var{args})}, since in that case there is always
  20 exactly one argument.)
  21 If the optional \var{keywords} argument is present, it must be a
  22 dictionary whose keys are strings.  It specifies keyword arguments to
  23 be added to the end of the the argument list.
  24 \end{funcdesc}
  25
  26 \begin{funcdesc}{chr}{i}
  27   Return a string of one character whose \ASCII{} code is the integer
  28   \var{i}, e.g., \code{chr(97)} returns the string \code{'a'}.  This is the
  29   inverse of \code{ord()}.  The argument must be in the range [0..255],
  30   inclusive.
  31 \end{funcdesc}
  32
  33 \begin{funcdesc}{cmp}{x\, y}
  34   Compare the two objects \var{x} and \var{y} and return an integer
  35   according to the outcome.  The return value is negative if \code{\var{x}
  36   < \var{y}}, zero if \code{\var{x} == \var{y}} and strictly positive if
  37   \code{\var{x} > \var{y}}.
  38 \end{funcdesc}
  39
  40 \begin{funcdesc}{coerce}{x\, y}
  41   Return a tuple consisting of the two numeric arguments converted to
  42   a common type, using the same rules as used by arithmetic
  43   operations.
  44 \end{funcdesc}
  45
  46 \begin{funcdesc}{compile}{string\, filename\, kind}
  47   Compile the \var{string} into a code object.  Code objects can be
  48   executed by an \code{exec} statement or evaluated by a call to
  49   \code{eval()}.  The \var{filename} argument should
  50   give the file from which the code was read; pass e.g. \code{'<string>'}
  51   if it wasn't read from a file.  The \var{kind} argument specifies
  52   what kind of code must be compiled; it can be \code{'exec'} if
  53   \var{string} consists of a sequence of statements, \code{'eval'}
  54   if it consists of a single expression, or \code{'single'} if
  55   it consists of a single interactive statement (in the latter case,
  56   expression statements that evaluate to something else than
  57   \code{None} will printed).
  58 \end{funcdesc}
  59
  60 \begin{funcdesc}{delattr}{object\, name}
  61   This is a relative of \code{setattr}.  The arguments are an
  62   object and a string.  The string must be the name
  63   of one of the object's attributes.  The function deletes
  64   the named attribute, provided the object allows it.  For example,
  65   \code{delattr(\var{x}, '\var{foobar}')} is equivalent to
  66   \code{del \var{x}.\var{foobar}}.
  67 \end{funcdesc}
  68
  69 \begin{funcdesc}{dir}{}
  70   Without arguments, return the list of names in the current local
  71   symbol table.  With a module, class or class instance object as
  72   argument (or anything else that has a \code{__dict__} attribute),
  73   returns the list of names in that object's attribute dictionary.
  74   The resulting list is sorted.  For example:
  75
  76 \bcode\begin{verbatim}
  77 >>> import sys
  78 >>> dir()
  79 ['sys']
  80 >>> dir(sys)
  81 ['argv', 'exit', 'modules', 'path', 'stderr', 'stdin', 'stdout']
  82 >>>
  83 \end{verbatim}\ecode
  84 \end{funcdesc}
  85
  86 \begin{funcdesc}{divmod}{a\, b}
  87   Take two numbers as arguments and return a pair of integers
  88   consisting of their integer quotient and remainder.  With mixed
  89   operand types, the rules for binary arithmetic operators apply.  For
  90   plain and long integers, the result is the same as
  91   \code{(\var{a} / \var{b}, \var{a} \%{} \var{b})}.
  92   For floating point numbers the result is the same as
  93   \code{(math.floor(\var{a} / \var{b}), \var{a} \%{} \var{b})}.
  94 \end{funcdesc}
  95
  96 \begin{funcdesc}{eval}{expression\optional{\, globals\optional{\, locals}}}
  97   The arguments are a string and two optional dictionaries.  The
  98   \var{expression} argument is parsed and evaluated as a Python
  99   expression (technically speaking, a condition list) using the
 100   \var{globals} and \var{locals} dictionaries as global and local name
 101   space.  If the \var{locals} dictionary is omitted it defaults to
 102   the \var{globals} dictionary.  If both dictionaries are omitted, the
 103   expression is executed in the environment where \code{eval} is
 104   called.  The return value is the result of the evaluated expression.
 105   Syntax errors are reported as exceptions.  Example:
 106
 107 \bcode\begin{verbatim}
 108 >>> x = 1
 109 >>> print eval('x+1')
 110 2
 111 >>>
 112 \end{verbatim}\ecode
 113
 114   This function can also be used to execute arbitrary code objects
 115   (e.g.\ created by \code{compile()}).  In this case pass a code
 116   object instead of a string.  The code object must have been compiled
 117   passing \code{'eval'} to the \var{kind} argument.
 118
 119   Hints: dynamic execution of statements is supported by the
 120   \code{exec} statement.  Execution of statements from a file is
 121   supported by the \code{execfile()} function.  The \code{globals()}
 122   and \code{locals()} functions returns the current global and local
 123   dictionary, respectively, which may be useful
 124   to pass around for use by \code{eval()} or \code{execfile()}.
 125
 126 \end{funcdesc}
 127
 128 \begin{funcdesc}{execfile}{file\optional{\, globals\optional{\, locals}}}
 129   This function is similar to the
 130   \code{exec} statement, but parses a file instead of a string.  It is
 131   different from the \code{import} statement in that it does not use
 132   the module administration --- it reads the file unconditionally and
 133   does not create a new module.\footnote{It is used relatively rarely
 134   so does not warrant being made into a statement.}
 135
 136   The arguments are a file name and two optional dictionaries.  The
 137   file is parsed and evaluated as a sequence of Python statements
 138   (similarly to a module) using the \var{globals} and \var{locals}
 139   dictionaries as global and local name space.  If the \var{locals}
 140   dictionary is omitted it defaults to the \var{globals} dictionary.
 141   If both dictionaries are omitted, the expression is executed in the
 142   environment where \code{execfile()} is called.  The return value is
 143   \code{None}.
 144 \end{funcdesc}
 145
 146 \begin{funcdesc}{filter}{function\, list}
 147 Construct a list from those elements of \var{list} for which
 148 \var{function} returns true.  If \var{list} is a string or a tuple,
 149 the result also has that type; otherwise it is always a list.  If
 150 \var{function} is \code{None}, the identity function is assumed,
 151 i.e.\ all elements of \var{list} that are false (zero or empty) are
 152 removed.
 153 \end{funcdesc}
 154
 155 \begin{funcdesc}{float}{x}
 156   Convert a number to floating point.  The argument may be a plain or
 157   long integer or a floating point number.
 158 \end{funcdesc}
 159
 160 \begin{funcdesc}{getattr}{object\, name}
 161   The arguments are an object and a string.  The string must be the
 162   name
 163   of one of the object's attributes.  The result is the value of that
 164   attribute.  For example, \code{getattr(\var{x}, '\var{foobar}')} is equivalent to
 165   \code{\var{x}.\var{foobar}}.
 166 \end{funcdesc}
 167
 168 \begin{funcdesc}{globals}{}
 169 Return a dictionary representing the current global symbol table.
 170 This is always the dictionary of the current module (inside a
 171 function or method, this is the module where it is defined, not the
 172 module from which it is called).
 173 \end{funcdesc}
 174
 175 \begin{funcdesc}{hasattr}{object\, name}
 176   The arguments are an object and a string.  The result is 1 if the
 177   string is the name of one of the object's attributes, 0 if not.
 178   (This is implemented by calling \code{getattr(object, name)} and
 179   seeing whether it raises an exception or not.)
 180 \end{funcdesc}
 181
 182 \begin{funcdesc}{hash}{object}
 183   Return the hash value of the object (if it has one).  Hash values
 184   are 32-bit integers.  They are used to quickly compare dictionary
 185   keys during a dictionary lookup.  Numeric values that compare equal
 186   have the same hash value (even if they are of different types, e.g.
 187   1 and 1.0).
 188 \end{funcdesc}
 189
 190 \begin{funcdesc}{hex}{x}
 191   Convert an integer number (of any size) to a hexadecimal string.
 192   The result is a valid Python expression.
 193 \end{funcdesc}
 194
 195 \begin{funcdesc}{id}{object}
 196   Return the `identity' of an object.  This is an integer which is
 197   guaranteed to be unique and constant for this object during its
 198   lifetime.  (Two objects whose lifetimes are disjunct may have the
 199   same id() value.)  (Implementation note: this is the address of the
 200   object.)
 201 \end{funcdesc}
 202
 203 \begin{funcdesc}{input}{\optional{prompt}}
 204   Almost equivalent to \code{eval(raw_input(\var{prompt}))}.  Like
 205   \code{raw_input()}, the \var{prompt} argument is optional.  The difference
 206   is that a long input expression may be broken over multiple lines using
 207   the backslash convention.
 208 \end{funcdesc}
 209
 210 \begin{funcdesc}{int}{x}
 211   Convert a number to a plain integer.  The argument may be a plain or
 212   long integer or a floating point number.  Conversion of floating
 213   point numbers to integers is defined by the C semantics; normally
 214   the conversion truncates towards zero.\footnote{This is ugly --- the
 215   language definition should require truncation towards zero.}
 216 \end{funcdesc}
 217
 218 \begin{funcdesc}{len}{s}
 219   Return the length (the number of items) of an object.  The argument
 220   may be a sequence (string, tuple or list) or a mapping (dictionary).
 221 \end{funcdesc}
 222
 223 \begin{funcdesc}{locals}{}
 224 Return a dictionary representing the current local symbol table.
 225 Inside a function, modifying this dictionary does not always have the
 226 desired effect.
 227 \end{funcdesc}
 228
 229 \begin{funcdesc}{long}{x}
 230   Convert a number to a long integer.  The argument may be a plain or
 231   long integer or a floating point number.
 232 \end{funcdesc}
 233
 234 \begin{funcdesc}{map}{function\, list\, ...}
 235 Apply \var{function} to every item of \var{list} and return a list
 236 of the results.  If additional \var{list} arguments are passed,
 237 \var{function} must take that many arguments and is applied to
 238 the items of all lists in parallel; if a list is shorter than another
 239 it is assumed to be extended with \code{None} items.  If
 240 \var{function} is \code{None}, the identity function is assumed; if
 241 there are multiple list arguments, \code{map} returns a list
 242 consisting of tuples containing the corresponding items from all lists
 243 (i.e. a kind of transpose operation).  The \var{list} arguments may be
 244 any kind of sequence; the result is always a list.
 245 \end{funcdesc}
 246
 247 \begin{funcdesc}{max}{s}
 248   Return the largest item of a non-empty sequence (string, tuple or
 249   list).
 250 \end{funcdesc}
 251
 252 \begin{funcdesc}{min}{s}
 253   Return the smallest item of a non-empty sequence (string, tuple or
 254   list).
 255 \end{funcdesc}
 256
 257 \begin{funcdesc}{oct}{x}
 258   Convert an integer number (of any size) to an octal string.  The
 259   result is a valid Python expression.
 260 \end{funcdesc}
 261
 262 \begin{funcdesc}{open}{filename\optional{\, mode\optional{\, bufsize}}}
 263   Return a new file object (described earlier under Built-in Types).
 264   The first two arguments are the same as for \code{stdio}'s
 265   \code{fopen()}: \var{filename} is the file name to be opened,
 266   \var{mode} indicates how the file is to be opened: \code{'r'} for
 267   reading, \code{'w'} for writing (truncating an existing file), and
 268   \code{'a'} opens it for appending.  Modes \code{'r+'}, \code{'w+'} and
 269   \code{'a+'} open the file for updating, provided the underlying
 270   \code{stdio} library understands this.  On systems that differentiate
 271   between binary and text files, \code{'b'} appended to the mode opens
 272   the file in binary mode.  If the file cannot be opened, \code{IOError}
 273   is raised.
 274 If \var{mode} is omitted, it defaults to \code{'r'}.
 275 The optional \var{bufsize} argument specifies the file's desired
 276 buffer size: 0 means unbuffered, 1 means line buffered, any other
 277 positive value means use a buffer of (approximately) that size.  A
 278 negative \var{bufsize} means to use the system default, which is
 279 usually line buffered for for tty devices and fully buffered for other
 280 files.%
 281 \footnote{Specifying a buffer size currently has no effect on systems
 282 that don't have \code{setvbuf()}.  The interface to specify the buffer
 283 size is not done using a method that calls \code{setvbuf()}, because
 284 that may dump core when called after any I/O has been performed, and
 285 there's no reliable way to determine whether this is the case.}
 286 \end{funcdesc}
 287
 288 \begin{funcdesc}{ord}{c}
 289   Return the \ASCII{} value of a string of one character.  E.g.,
 290   \code{ord('a')} returns the integer \code{97}.  This is the inverse of
 291   \code{chr()}.
 292 \end{funcdesc}
 293
 294 \begin{funcdesc}{pow}{x\, y\optional{\, z}}
 295   Return \var{x} to the power \var{y}; if \var{z} is present, return
 296   \var{x} to the power \var{y}, modulo \var{z} (computed more
 297   efficiently than \code{pow(\var{x}, \var{y}) \% \var{z}}).
 298   The arguments must have
 299   numeric types.  With mixed operand types, the rules for binary
 300   arithmetic operators apply.  The effective operand type is also the
 301   type of the result; if the result is not expressible in this type, the
 302   function raises an exception; e.g., \code{pow(2, -1)} or \code{pow(2,
 303   35000)} is not allowed.
 304 \end{funcdesc}
 305
 306 \begin{funcdesc}{range}{\optional{start\,} end\optional{\, step}}
 307   This is a versatile function to create lists containing arithmetic
 308   progressions.  It is most often used in \code{for} loops.  The
 309   arguments must be plain integers.  If the \var{step} argument is
 310   omitted, it defaults to \code{1}.  If the \var{start} argument is
 311   omitted, it defaults to \code{0}.  The full form returns a list of
 312   plain integers \code{[\var{start}, \var{start} + \var{step},
 313   \var{start} + 2 * \var{step}, \ldots]}.  If \var{step} is positive,
 314   the last element is the largest \code{\var{start} + \var{i} *
 315   \var{step}} less than \var{end}; if \var{step} is negative, the last
 316   element is the largest \code{\var{start} + \var{i} * \var{step}}
 317   greater than \var{end}.  \var{step} must not be zero (or else an
 318   exception is raised).  Example:
 319
 320 \bcode\begin{verbatim}
 321 >>> range(10)
 322 [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
 323 >>> range(1, 11)
 324 [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
 325 >>> range(0, 30, 5)
 326 [0, 5, 10, 15, 20, 25]
 327 >>> range(0, 10, 3)
 328 [0, 3, 6, 9]
 329 >>> range(0, -10, -1)
 330 [0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
 331 >>> range(0)
 332 []
 333 >>> range(1, 0)
 334 []
 335 >>>
 336 \end{verbatim}\ecode
 337 \end{funcdesc}
 338
 339 \begin{funcdesc}{raw_input}{\optional{prompt}}
 340   If the \var{prompt} argument is present, it is written to standard output
 341   without a trailing newline.  The function then reads a line from input,
 342   converts it to a string (stripping a trailing newline), and returns that.
 343   When \EOF{} is read, \code{EOFError} is raised. Example:
 344
 345 \bcode\begin{verbatim}
 346 >>> s = raw_input('--> ')
 347 --> Monty Python's Flying Circus
 348 >>> s
 349 "Monty Python's Flying Circus"
 350 >>>
 351 \end{verbatim}\ecode
 352 \end{funcdesc}
 353
 354 \begin{funcdesc}{reduce}{function\, list\optional{\, initializer}}
 355 Apply the binary \var{function} to the items of \var{list} so as to
 356 reduce the list to a single value.  E.g.,
 357 \code{reduce(lambda x, y: x*y, \var{list}, 1)} returns the product of
 358 the elements of \var{list}.  The optional \var{initializer} can be
 359 thought of as being prepended to \var{list} so as to allow reduction
 360 of an empty \var{list}.  The \var{list} arguments may be any kind of
 361 sequence.
 362 \end{funcdesc}
 363
 364 \begin{funcdesc}{reload}{module}
 365 Re-parse and re-initialize an already imported \var{module}.  The
 366 argument must be a module object, so it must have been successfully
 367 imported before.  This is useful if you have edited the module source
 368 file using an external editor and want to try out the new version
 369 without leaving the Python interpreter.  The return value is the
 370 module object (i.e.\ the same as the \var{module} argument).
 371
 372 There are a number of caveats:
 373
 374 If a module is syntactically correct but its initialization fails, the
 375 first \code{import} statement for it does not bind its name locally,
 376 but does store a (partially initialized) module object in
 377 \code{sys.modules}.  To reload the module you must first
 378 \code{import} it again (this will bind the name to the partially
 379 initialized module object) before you can \code{reload()} it.
 380
 381 When a module is reloaded, its dictionary (containing the module's
 382 global variables) is retained.  Redefinitions of names will override
 383 the old definitions, so this is generally not a problem.  If the new
 384 version of a module does not define a name that was defined by the old
 385 version, the old definition remains.  This feature can be used to the
 386 module's advantage if it maintains a global table or cache of objects
 387 --- with a \code{try} statement it can test for the table's presence
 388 and skip its initialization if desired.
 389
 390 It is legal though generally not very useful to reload built-in or
 391 dynamically loaded modules, except for \code{sys}, \code{__main__} and
 392 \code{__builtin__}.  In certain cases, however, extension modules are
 393 not designed to be initialized more than once, and may fail in
 394 arbitrary ways when reloaded.
 395
 396 If a module imports objects from another module using \code{from}
 397 {\ldots} \code{import} {\ldots}, calling \code{reload()} for the other
 398 module does not redefine the objects imported from it --- one way
 399 around this is to re-execute the \code{from} statement, another is to
 400 use \code{import} and qualified names (\var{module}.\var{name})
 401 instead.
 402
 403 If a module instantiates instances of a class, reloading the module
 404 that defines the class does not affect the method definitions of the
 405 instances --- they continue to use the old class definition.  The same
 406 is true for derived classes.
 407 \end{funcdesc}
 408
 409 \begin{funcdesc}{repr}{object}
 410 Return a string containing a printable representation of an object.
 411 This is the same value yielded by conversions (reverse quotes).
 412 It is sometimes useful to be able to access this operation as an
 413 ordinary function.  For many types, this function makes an attempt
 414 to return a string that would yield an object with the same value
 415 when passed to \code{eval()}.
 416 \end{funcdesc}
 417
 418 \begin{funcdesc}{round}{x\, n}
 419   Return the floating point value \var{x} rounded to \var{n} digits
 420   after the decimal point.  If \var{n} is omitted, it defaults to zero.
 421   The result is a floating point number.  Values are rounded to the
 422   closest multiple of 10 to the power minus \var{n}; if two multiples
 423   are equally close, rounding is done away from 0 (so e.g.
 424   \code{round(0.5)} is \code{1.0} and \code{round(-0.5)} is \code{-1.0}).
 425 \end{funcdesc}
 426
 427 \begin{funcdesc}{setattr}{object\, name\, value}
 428   This is the counterpart of \code{getattr}.  The arguments are an
 429   object, a string and an arbitrary value.  The string must be the name
 430   of one of the object's attributes.  The function assigns the value to
 431   the attribute, provided the object allows it.  For example,
 432   \code{setattr(\var{x}, '\var{foobar}', 123)} is equivalent to
 433   \code{\var{x}.\var{foobar} = 123}.
 434 \end{funcdesc}
 435
 436 \begin{funcdesc}{str}{object}
 437 Return a string containing a nicely printable representation of an
 438 object.  For strings, this returns the string itself.  The difference
 439 with \code{repr(\var{object})} is that \code{str(\var{object})} does not
 440 always attempt to return a string that is acceptable to \code{eval()};
 441 its goal is to return a printable string.
 442 \end{funcdesc}
 443
 444 \begin{funcdesc}{tuple}{sequence}
 445 Return a tuple whose items are the same and in the same order as
 446 \var{sequence}'s items.  If \var{sequence} is alread a tuple, it
 447 is returned unchanged.  For instance, \code{tuple('abc')} returns
 448 returns \code{('a', 'b', 'c')} and \code{tuple([1, 2, 3])} returns
 449 \code{(1, 2, 3)}.
 450 \end{funcdesc}
 451
 452 \begin{funcdesc}{type}{object}
 453 Return the type of an \var{object}.  The return value is a type
 454 object.  The standard module \code{types} defines names for all
 455 built-in types.
 456 \stmodindex{types}
 457 \obindex{type}
 458 For instance:
 459
 460 \bcode\begin{verbatim}
 461 >>> import types
 462 >>> if type(x) == types.StringType: print "It's a string"
 463 \end{verbatim}\ecode
 464 \end{funcdesc}
 465
 466 \begin{funcdesc}{vars}{\optional{object}}
 467 Without arguments, return a dictionary corresponding to the current
 468 local symbol table.  With a module, class or class instance object as
 469 argument (or anything else that has a \code{__dict__} attribute),
 470 returns a dictionary corresponding to the object's symbol table.
 471 The returned dictionary should not be modified: the effects on the
 472 corresponding symbol table are undefined.%
 473 \footnote{In the current implementation, local variable bindings
 474 cannot normally be affected this way, but variables retrieved from
 475 other scopes (e.g. modules) can be.  This may change.}
 476 \end{funcdesc}
 477
 478 \begin{funcdesc}{xrange}{\optional{start\,} end\optional{\, step}}
 479 This function is very similar to \code{range()}, but returns an
 480 ``xrange object'' instead of a list.  This is an opaque sequence type
 481 which yields the same values as the corresponding list, without
 482 actually storing them all simultaneously.  The advantage of
 483 \code{xrange()} over \code{range()} is minimal (since \code{xrange()}
 484 still has to create the values when asked for them) except when a very
 485 large range is used on a memory-starved machine (e.g. MS-DOS) or when all
 486 of the range's elements are never used (e.g. when the loop is usually
 487 terminated with \code{break}).
 488 \end{funcdesc}