home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / p / python / pyhtmldoc / b / built-in_f < prev    next >
Text File  |  1996-11-14  |  24KB  |  450 lines
  1. <TITLE>Built-in Functions -- Python library reference</TITLE>
  2. Prev: <A HREF="../e/exceptions" TYPE="Prev">Exceptions</A>  
  3. Up: <A HREF="../b/built-in_objects" TYPE="Up">Built-in Objects</A>  
  4. Top: <A HREF="../t/top" TYPE="Top">Top</A>  
  5. <H1>2.3. Built-in Functions</H1>
  6. The Python interpreter has a number of functions built into it that
  7. are always available.  They are listed here in alphabetical order.
  8. <P>
  9. <DL><DT><B>abs</B> (<VAR>x</VAR>) -- built-in function<DD>
  10. Return the absolute value of a number.  The argument may be a plain
  11. or long integer or a floating point number.
  12. </DL>
  13. <DL><DT><B>apply</B> (<VAR>function</VAR>, <VAR>args</VAR>[, <VAR>keywords</VAR>]) -- built-in function<DD>
  14. The <VAR>function</VAR> argument must be a callable object (a user-defined or
  15. built-in function or method, or a class object) and the <VAR>args</VAR>
  16. argument must be a tuple.  The <VAR>function</VAR> is called with
  17. <VAR>args</VAR> 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>(<VAR>args</VAR>)</CODE>, since in that case there is always
  20. exactly one argument.)
  21. If the optional <VAR>keywords</VAR> 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. </DL>
  25. <DL><DT><B>chr</B> (<VAR>i</VAR>) -- built-in function<DD>
  26. Return a string of one character whose ASCII code is the integer
  27. <VAR>i</VAR>, e.g., <CODE>chr(97)</CODE> returns the string <CODE>'a'</CODE>.  This is the
  28. inverse of <CODE>ord()</CODE>.  The argument must be in the range [0..255],
  29. inclusive.
  30. </DL>
  31. <DL><DT><B>cmp</B> (<VAR>x</VAR>, <VAR>y</VAR>) -- built-in function<DD>
  32. Compare the two objects <VAR>x</VAR> and <VAR>y</VAR> and return an integer
  33. according to the outcome.  The return value is negative if <CODE><VAR>x</VAR>
  34. < <VAR>y</VAR></CODE>, zero if <CODE><VAR>x</VAR> == <VAR>y</VAR></CODE> and strictly positive if
  35. <CODE><VAR>x</VAR> > <VAR>y</VAR></CODE>.
  36. </DL>
  37. <DL><DT><B>coerce</B> (<VAR>x</VAR>, <VAR>y</VAR>) -- built-in function<DD>
  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. </DL>
  42. <DL><DT><B>compile</B> (<VAR>string</VAR>, <VAR>filename</VAR>, <VAR>kind</VAR>) -- built-in function<DD>
  43. Compile the <VAR>string</VAR> into a code object.  Code objects can be
  44. executed by an <CODE>exec</CODE> statement or evaluated by a call to
  45. <CODE>eval()</CODE>.  The <VAR>filename</VAR> argument should
  46. give the file from which the code was read; pass e.g. <CODE>'<string>'</CODE>
  47. if it wasn't read from a file.  The <VAR>kind</VAR> argument specifies
  48. what kind of code must be compiled; it can be <CODE>'exec'</CODE> if
  49. <VAR>string</VAR> consists of a sequence of statements, <CODE>'eval'</CODE>
  50. if it consists of a single expression, or <CODE>'single'</CODE> if
  51. it consists of a single interactive statement (in the latter case,
  52. expression statements that evaluate to something else than
  53. <CODE>None</CODE> will printed).
  54. </DL>
  55. <DL><DT><B>delattr</B> (<VAR>object</VAR>, <VAR>name</VAR>) -- built-in function<DD>
  56. This is a relative of <CODE>setattr</CODE>.  The arguments are an
  57. object and a string.  The string must be the name
  58. of one of the object's attributes.  The function deletes
  59. the named attribute, provided the object allows it.  For example,
  60. <CODE>delattr(<VAR>x</VAR>, '<VAR>foobar</VAR>')</CODE> is equivalent to
  61. <CODE>del <VAR>x</VAR>.<VAR>foobar</VAR></CODE>.
  62. </DL>
  63. <DL><DT><B>dir</B> () -- built-in function<DD>
  64. Without arguments, return the list of names in the current local
  65. symbol table.  With a module, class or class instance object as
  66. argument (or anything else that has a <CODE>__dict__</CODE> attribute),
  67. returns the list of names in that object's attribute dictionary.
  68. The resulting list is sorted.  For example:
  69. <P>
  70. <UL COMPACT><CODE>>>> import sys<P>
  71. >>> dir()<P>
  72. ['sys']<P>
  73. >>> dir(sys)<P>
  74. ['argv', 'exit', 'modules', 'path', 'stderr', 'stdin', 'stdout']<P>
  75. >>> <P>
  76. </CODE></UL>
  77. </DL>
  78. <DL><DT><B>divmod</B> (<VAR>a</VAR>, <VAR>b</VAR>) -- built-in function<DD>
  79. Take two numbers as arguments and return a pair of integers
  80. consisting of their integer quotient and remainder.  With mixed
  81. operand types, the rules for binary arithmetic operators apply.  For
  82. plain and long integers, the result is the same as
  83. <CODE>(<VAR>a</VAR> / <VAR>b</VAR>, <VAR>a</VAR> % <VAR>b</VAR>)</CODE>.
  84. For floating point numbers the result is the same as
  85. <CODE>(math.floor(<VAR>a</VAR> / <VAR>b</VAR>), <VAR>a</VAR> % <VAR>b</VAR>)</CODE>.
  86. </DL>
  87. <DL><DT><B>eval</B> (<VAR>expression</VAR>[, <VAR>globals</VAR>[, <VAR>locals</VAR>]]) -- built-in function<DD>
  88. The arguments are a string and two optional dictionaries.  The
  89. <VAR>expression</VAR> argument is parsed and evaluated as a Python
  90. expression (technically speaking, a condition list) using the
  91. <VAR>globals</VAR> and <VAR>locals</VAR> dictionaries as global and local name
  92. space.  If the <VAR>locals</VAR> dictionary is omitted it defaults to
  93. the <VAR>globals</VAR> dictionary.  If both dictionaries are omitted, the
  94. expression is executed in the environment where <CODE>eval</CODE> is
  95. called.  The return value is the result of the evaluated expression.
  96. Syntax errors are reported as exceptions.  Example:
  97. <P>
  98. <UL COMPACT><CODE>>>> x = 1<P>
  99. >>> print eval('x+1')<P>
  100. 2<P>
  101. >>> <P>
  102. </CODE></UL>
  103. This function can also be used to execute arbitrary code objects
  104. (e.g. created by <CODE>compile()</CODE>).  In this case pass a code
  105. object instead of a string.  The code object must have been compiled
  106. passing <CODE>'eval'</CODE> to the <VAR>kind</VAR> argument.
  107. <P>
  108. Hints: dynamic execution of statements is supported by the
  109. <CODE>exec</CODE> statement.  Execution of statements from a file is
  110. supported by the <CODE>execfile()</CODE> function.  The <CODE>globals()</CODE>
  111. and <CODE>locals()</CODE> functions returns the current global and local
  112. dictionary, respectively, which may be useful
  113. to pass around for use by <CODE>eval()</CODE> or <CODE>execfile()</CODE>.
  114. <P>
  115. </DL>
  116. <DL><DT><B>execfile</B> (<VAR>file</VAR>[, <VAR>globals</VAR>[, <VAR>locals</VAR>]]) -- built-in function<DD>
  117. This function is similar to the
  118. <CODE>exec</CODE> statement, but parses a file instead of a string.  It is
  119. different from the <CODE>import</CODE> statement in that it does not use
  120. the module administration --- it reads the file unconditionally and
  121. does not create a new module.<A NAME="footnoteref1" HREF="#footnotetext1">(1)</A>
  122. <P>
  123. The arguments are a file name and two optional dictionaries.  The
  124. file is parsed and evaluated as a sequence of Python statements
  125. (similarly to a module) using the <VAR>globals</VAR> and <VAR>locals</VAR>
  126. dictionaries as global and local name space.  If the <VAR>locals</VAR>
  127. dictionary is omitted it defaults to the <VAR>globals</VAR> dictionary.
  128. If both dictionaries are omitted, the expression is executed in the
  129. environment where <CODE>execfile()</CODE> is called.  The return value is
  130. <CODE>None</CODE>.
  131. </DL>
  132. <DL><DT><B>filter</B> (<VAR>function</VAR>, <VAR>list</VAR>) -- built-in function<DD>
  133. Construct a list from those elements of <VAR>list</VAR> for which
  134. <VAR>function</VAR> returns true.  If <VAR>list</VAR> is a string or a tuple,
  135. the result also has that type; otherwise it is always a list.  If
  136. <VAR>function</VAR> is <CODE>None</CODE>, the identity function is assumed,
  137. i.e. all elements of <VAR>list</VAR> that are false (zero or empty) are
  138. removed.
  139. </DL>
  140. <DL><DT><B>float</B> (<VAR>x</VAR>) -- built-in function<DD>
  141. Convert a number to floating point.  The argument may be a plain or
  142. long integer or a floating point number.
  143. </DL>
  144. <DL><DT><B>getattr</B> (<VAR>object</VAR>, <VAR>name</VAR>) -- built-in function<DD>
  145. The arguments are an object and a string.  The string must be the
  146. name
  147. of one of the object's attributes.  The result is the value of that
  148. attribute.  For example, <CODE>getattr(<VAR>x</VAR>, '<VAR>foobar</VAR>')</CODE> is equivalent to
  149. <CODE><VAR>x</VAR>.<VAR>foobar</VAR></CODE>.
  150. </DL>
  151. <DL><DT><B>globals</B> () -- built-in function<DD>
  152. Return a dictionary represen