Mercurial > cpython-lru_cache-weakref

annotate Doc/libfuncs.tex @ 5817:48b94de85bf3 legacy-trunk

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