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