Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 1 | \section{Built-in Types} |
| 2 | |
| 3 | The following sections describe the standard types that are built into |
| 4 | the interpreter. These are the numeric types, sequence types, and |
| 5 | several others, including types themselves. There is no explicit |
| 6 | Boolean type; use integers instead. |
| 7 | \indexii{built-in}{types} |
| 8 | \indexii{Boolean}{type} |
| 9 | |
| 10 | Some operations are supported by several object types; in particular, |
| 11 | all objects can be compared, tested for truth value, and converted to |
| 12 | a string (with the \code{`{\rm \ldots}`} notation). The latter conversion is |
| 13 | implicitly used when an object is written by the \code{print} statement. |
| 14 | \stindex{print} |
| 15 | |
| 16 | \subsection{Truth Value Testing} |
| 17 | |
| 18 | Any object can be tested for truth value, for use in an \code{if} or |
| 19 | \code{while} condition or as operand of the Boolean operations below. |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 20 | The following values are considered false: |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 21 | \stindex{if} |
| 22 | \stindex{while} |
| 23 | \indexii{truth}{value} |
| 24 | \indexii{Boolean}{operations} |
| 25 | \index{false} |
| 26 | |
| 27 | \begin{itemize} |
| 28 | \renewcommand{\indexsubitem}{(Built-in object)} |
| 29 | |
| 30 | \item \code{None} |
| 31 | \ttindex{None} |
| 32 | |
| 33 | \item zero of any numeric type, e.g., \code{0}, \code{0L}, \code{0.0}. |
| 34 | |
| 35 | \item any empty sequence, e.g., \code{''}, \code{()}, \code{[]}. |
| 36 | |
| 37 | \item any empty mapping, e.g., \code{\{\}}. |
| 38 | |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 39 | \item instances of user-defined classes, if the class defines a |
| 40 | \code{__nonzero__()} or \code{__len__()} method, when that |
| 41 | method returns zero. |
| 42 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 43 | \end{itemize} |
| 44 | |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 45 | All other values are considered true --- so objects of many types are |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 46 | always true. |
| 47 | \index{true} |
| 48 | |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 49 | Operations and built-in functions that have a Boolean result always |
| 50 | return \code{0} for false and \code{1} for true, unless otherwise |
| 51 | stated. (Important exception: the Boolean operations \samp{or} and |
| 52 | \samp{and} always return one of their operands.) |
| 53 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 54 | \subsection{Boolean Operations} |
| 55 | |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 56 | These are the Boolean operations, ordered by ascending priority: |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 57 | \indexii{Boolean}{operations} |
| 58 | |
| 59 | \begin{tableiii}{|c|l|c|}{code}{Operation}{Result}{Notes} |
| 60 | \lineiii{\var{x} or \var{y}}{if \var{x} is false, then \var{y}, else \var{x}}{(1)} |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 61 | \hline |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 62 | \lineiii{\var{x} and \var{y}}{if \var{x} is false, then \var{x}, else \var{y}}{(1)} |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 63 | \hline |
| 64 | \lineiii{not \var{x}}{if \var{x} is false, then \code{1}, else \code{0}}{(2)} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 65 | \end{tableiii} |
| 66 | \opindex{and} |
| 67 | \opindex{or} |
| 68 | \opindex{not} |
| 69 | |
| 70 | \noindent |
| 71 | Notes: |
| 72 | |
| 73 | \begin{description} |
| 74 | |
| 75 | \item[(1)] |
| 76 | These only evaluate their second argument if needed for their outcome. |
| 77 | |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 78 | \item[(2)] |
| 79 | \samp{not} has a lower priority than non-Boolean operators, so e.g. |
| 80 | \code{not a == b} is interpreted as \code{not(a == b)}, and |
| 81 | \code{a == not b} is a syntax error. |
| 82 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 83 | \end{description} |
| 84 | |
| 85 | \subsection{Comparisons} |
| 86 | |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 87 | Comparison operations are supported by all objects. They all have the |
| 88 | same priority (which is higher than that of the Boolean operations). |
| 89 | Comparisons can be chained arbitrarily, e.g. \code{x < y <= z} is |
| 90 | equivalent to \code{x < y and y <= z}, except that \code{y} is |
| 91 | evaluated only once (but in both cases \code{z} is not evaluated at |
| 92 | all when \code{x < y} is found to be false). |
| 93 | \indexii{chaining}{comparisons} |
| 94 | |
| 95 | This table summarizes the comparison operations: |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 96 | |
| 97 | \begin{tableiii}{|c|l|c|}{code}{Operation}{Meaning}{Notes} |
| 98 | \lineiii{<}{strictly less than}{} |
| 99 | \lineiii{<=}{less than or equal}{} |
| 100 | \lineiii{>}{strictly greater than}{} |
| 101 | \lineiii{>=}{greater than or equal}{} |
| 102 | \lineiii{==}{equal}{} |
| 103 | \lineiii{<>}{not equal}{(1)} |
| 104 | \lineiii{!=}{not equal}{(1)} |
| 105 | \lineiii{is}{object identity}{} |
| 106 | \lineiii{is not}{negated object identity}{} |
| 107 | \end{tableiii} |
| 108 | \indexii{operator}{comparison} |
| 109 | \opindex{==} % XXX *All* others have funny characters < ! > |
| 110 | \opindex{is} |
| 111 | \opindex{is not} |
| 112 | |
| 113 | \noindent |
| 114 | Notes: |
| 115 | |
| 116 | \begin{description} |
| 117 | |
| 118 | \item[(1)] |
| 119 | \code{<>} and \code{!=} are alternate spellings for the same operator. |
| 120 | (I couldn't choose between \ABC{} and \C{}! :-) |
| 121 | \indexii{\ABC{}}{language} |
| 122 | \indexii{\C{}}{language} |
| 123 | |
| 124 | \end{description} |
| 125 | |
| 126 | Objects of different types, except different numeric types, never |
| 127 | compare equal; such objects are ordered consistently but arbitrarily |
| 128 | (so that sorting a heterogeneous array yields a consistent result). |
| 129 | Furthermore, some types (e.g., windows) support only a degenerate |
| 130 | notion of comparison where any two objects of that type are unequal. |
| 131 | Again, such objects are ordered arbitrarily but consistently. |
| 132 | \indexii{types}{numeric} |
| 133 | \indexii{objects}{comparing} |
| 134 | |
| 135 | (Implementation note: objects of different types except numbers are |
| 136 | ordered by their type names; objects of the same types that don't |
| 137 | support proper comparison are ordered by their address.) |
| 138 | |
| 139 | Two more operations with the same syntactic priority, \code{in} and |
| 140 | \code{not in}, are supported only by sequence types (below). |
| 141 | \opindex{in} |
| 142 | \opindex{not in} |
| 143 | |
| 144 | \subsection{Numeric Types} |
| 145 | |
Guido van Rossum | 3a0d850 | 1997-06-02 17:18:00 +0000 | [diff] [blame] | 146 | There are four numeric types: \dfn{plain integers}, \dfn{long integers}, |
| 147 | \dfn{floating point numbers}, and \dfn{complex numbers}. |
| 148 | Plain integers (also just called \dfn{integers}) |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 149 | are implemented using \code{long} in \C{}, which gives them at least 32 |
| 150 | bits of precision. Long integers have unlimited precision. Floating |
| 151 | point numbers are implemented using \code{double} in \C{}. All bets on |
| 152 | their precision are off unless you happen to know the machine you are |
| 153 | working with. |
| 154 | \indexii{numeric}{types} |
| 155 | \indexii{integer}{types} |
| 156 | \indexii{integer}{type} |
| 157 | \indexiii{long}{integer}{type} |
| 158 | \indexii{floating point}{type} |
Guido van Rossum | 3a0d850 | 1997-06-02 17:18:00 +0000 | [diff] [blame] | 159 | \indexii{complex number}{type} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 160 | \indexii{\C{}}{language} |
| 161 | |
Guido van Rossum | 3a0d850 | 1997-06-02 17:18:00 +0000 | [diff] [blame] | 162 | Complex numbers have a real and imaginary part, which are both |
| 163 | implemented using \code{double} in \C{}. To extract these parts from |
| 164 | a complex number \code{z}, use \code{z.real} and \code{z.imag}. |
| 165 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 166 | Numbers are created by numeric literals or as the result of built-in |
| 167 | functions and operators. Unadorned integer literals (including hex |
| 168 | and octal numbers) yield plain integers. Integer literals with an \samp{L} |
| 169 | or \samp{l} suffix yield long integers |
| 170 | (\samp{L} is preferred because \code{1l} looks too much like eleven!). |
| 171 | Numeric literals containing a decimal point or an exponent sign yield |
Guido van Rossum | 3a0d850 | 1997-06-02 17:18:00 +0000 | [diff] [blame] | 172 | floating point numbers. Appending \code{j} or \code{J} to a numeric |
| 173 | literal yields a complex number. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 174 | \indexii{numeric}{literals} |
| 175 | \indexii{integer}{literals} |
| 176 | \indexiii{long}{integer}{literals} |
| 177 | \indexii{floating point}{literals} |
Guido van Rossum | 3a0d850 | 1997-06-02 17:18:00 +0000 | [diff] [blame] | 178 | \indexii{complex number}{literals} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 179 | \indexii{hexadecimal}{literals} |
| 180 | \indexii{octal}{literals} |
| 181 | |
| 182 | Python fully supports mixed arithmetic: when a binary arithmetic |
| 183 | operator has operands of different numeric types, the operand with the |
| 184 | ``smaller'' type is converted to that of the other, where plain |
Guido van Rossum | 3a0d850 | 1997-06-02 17:18:00 +0000 | [diff] [blame] | 185 | integer is smaller than long integer is smaller than floating point is |
| 186 | smaller than complex. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 187 | Comparisons between numbers of mixed type use the same rule.% |
| 188 | \footnote{As a consequence, the list \code{[1, 2]} is considered equal |
| 189 | to \code{[1.0, 2.0]}, and similar for tuples.} |
Guido van Rossum | 3a0d850 | 1997-06-02 17:18:00 +0000 | [diff] [blame] | 190 | The functions \code{int()}, \code{long()}, \code{float()}, |
| 191 | and \code{complex()} can be used |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 192 | to coerce numbers to a specific type. |
| 193 | \index{arithmetic} |
| 194 | \bifuncindex{int} |
| 195 | \bifuncindex{long} |
| 196 | \bifuncindex{float} |
Guido van Rossum | 3a0d850 | 1997-06-02 17:18:00 +0000 | [diff] [blame] | 197 | \bifuncindex{complex} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 198 | |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 199 | All numeric types support the following operations, sorted by |
| 200 | ascending priority (operations in the same box have the same |
| 201 | priority; all numeric operations have a higher priority than |
| 202 | comparison operations): |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 203 | |
| 204 | \begin{tableiii}{|c|l|c|}{code}{Operation}{Result}{Notes} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 205 | \lineiii{\var{x} + \var{y}}{sum of \var{x} and \var{y}}{} |
| 206 | \lineiii{\var{x} - \var{y}}{difference of \var{x} and \var{y}}{} |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 207 | \hline |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 208 | \lineiii{\var{x} * \var{y}}{product of \var{x} and \var{y}}{} |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 209 | \lineiii{\var{x} / \var{y}}{quotient of \var{x} and \var{y}}{(1)} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 210 | \lineiii{\var{x} \%{} \var{y}}{remainder of \code{\var{x} / \var{y}}}{} |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 211 | \hline |
| 212 | \lineiii{-\var{x}}{\var{x} negated}{} |
| 213 | \lineiii{+\var{x}}{\var{x} unchanged}{} |
| 214 | \hline |
Guido van Rossum | 3a0d850 | 1997-06-02 17:18:00 +0000 | [diff] [blame] | 215 | \lineiii{abs(\var{x})}{absolute value or magnitude of \var{x}}{} |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 216 | \lineiii{int(\var{x})}{\var{x} converted to integer}{(2)} |
| 217 | \lineiii{long(\var{x})}{\var{x} converted to long integer}{(2)} |
| 218 | \lineiii{float(\var{x})}{\var{x} converted to floating point}{} |
Guido van Rossum | 3a0d850 | 1997-06-02 17:18:00 +0000 | [diff] [blame] | 219 | \lineiii{complex(\var{re},\var{im})}{a complex number with real part \var{re}, imaginary part \var{im}. \var{im} defaults to zero.}{} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 220 | \lineiii{divmod(\var{x}, \var{y})}{the pair \code{(\var{x} / \var{y}, \var{x} \%{} \var{y})}}{(3)} |
| 221 | \lineiii{pow(\var{x}, \var{y})}{\var{x} to the power \var{y}}{} |
Guido van Rossum | 3a0d850 | 1997-06-02 17:18:00 +0000 | [diff] [blame] | 222 | \lineiii{\var{x}**\var{y}}{\var{x} to the power \var{y}}{} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 223 | \end{tableiii} |
| 224 | \indexiii{operations on}{numeric}{types} |
| 225 | |
| 226 | \noindent |
| 227 | Notes: |
| 228 | \begin{description} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 229 | |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 230 | \item[(1)] |
Guido van Rossum | 0dbd1fd | 1995-08-10 14:22:39 +0000 | [diff] [blame] | 231 | For (plain or long) integer division, the result is an integer. |
| 232 | The result is always rounded towards minus infinity: 1/2 is 0, |
| 233 | (-1)/2 is -1, 1/(-2) is -1, and (-1)/(-2) is 0. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 234 | \indexii{integer}{division} |
| 235 | \indexiii{long}{integer}{division} |
| 236 | |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 237 | \item[(2)] |
| 238 | Conversion from floating point to (long or plain) integer may round or |
| 239 | truncate as in \C{}; see functions \code{floor()} and \code{ceil()} in |
| 240 | module \code{math} for well-defined conversions. |
| 241 | \bifuncindex{floor} |
| 242 | \bifuncindex{ceil} |
| 243 | \indexii{numeric}{conversions} |
Fred Drake | 8274f32 | 1997-12-15 22:19:46 +0000 | [diff] [blame] | 244 | \refbimodindex{math} |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 245 | \indexii{\C{}}{language} |
| 246 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 247 | \item[(3)] |
| 248 | See the section on built-in functions for an exact definition. |
| 249 | |
| 250 | \end{description} |
| 251 | % XXXJH exceptions: overflow (when? what operations?) zerodivision |
| 252 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 253 | \subsubsection{Bit-string Operations on Integer Types} |
Guido van Rossum | 86cb092 | 1995-03-20 12:59:56 +0000 | [diff] [blame] | 254 | \nodename{Bit-string Operations} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 255 | |
| 256 | Plain and long integer types support additional operations that make |
| 257 | sense only for bit-strings. Negative numbers are treated as their 2's |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 258 | complement value (for long integers, this assumes a sufficiently large |
| 259 | number of bits that no overflow occurs during the operation). |
| 260 | |
| 261 | The priorities of the binary bit-wise operations are all lower than |
| 262 | the numeric operations and higher than the comparisons; the unary |
Guido van Rossum | e903aab | 1997-12-18 16:28:56 +0000 | [diff] [blame] | 263 | operation \samp{\~} has the same priority as the other unary numeric |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 264 | operations (\samp{+} and \samp{-}). |
| 265 | |
| 266 | This table lists the bit-string operations sorted in ascending |
| 267 | priority (operations in the same box have the same priority): |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 268 | |
| 269 | \begin{tableiii}{|c|l|c|}{code}{Operation}{Result}{Notes} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 270 | \lineiii{\var{x} | \var{y}}{bitwise \dfn{or} of \var{x} and \var{y}}{} |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 271 | \hline |
| 272 | \lineiii{\var{x} \^{} \var{y}}{bitwise \dfn{exclusive or} of \var{x} and \var{y}}{} |
| 273 | \hline |
| 274 | \lineiii{\var{x} \&{} \var{y}}{bitwise \dfn{and} of \var{x} and \var{y}}{} |
| 275 | \hline |
| 276 | \lineiii{\var{x} << \var{n}}{\var{x} shifted left by \var{n} bits}{(1), (2)} |
| 277 | \lineiii{\var{x} >> \var{n}}{\var{x} shifted right by \var{n} bits}{(1), (3)} |
| 278 | \hline |
| 279 | \hline |
| 280 | \lineiii{\~\var{x}}{the bits of \var{x} inverted}{} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 281 | \end{tableiii} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 282 | \indexiii{operations on}{integer}{types} |
| 283 | \indexii{bit-string}{operations} |
| 284 | \indexii{shifting}{operations} |
| 285 | \indexii{masking}{operations} |
| 286 | |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 287 | \noindent |
| 288 | Notes: |
| 289 | \begin{description} |
| 290 | \item[(1)] Negative shift counts are illegal. |
| 291 | \item[(2)] A left shift by \var{n} bits is equivalent to |
| 292 | multiplication by \code{pow(2, \var{n})} without overflow check. |
| 293 | \item[(3)] A right shift by \var{n} bits is equivalent to |
| 294 | division by \code{pow(2, \var{n})} without overflow check. |
| 295 | \end{description} |
| 296 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 297 | \subsection{Sequence Types} |
| 298 | |
| 299 | There are three sequence types: strings, lists and tuples. |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 300 | |
| 301 | Strings literals are written in single or double quotes: |
| 302 | \code{'xyzzy'}, \code{"frobozz"}. See Chapter 2 of the Python |
| 303 | Reference Manual for more about string literals. Lists are |
| 304 | constructed with square brackets, separating items with commas: |
| 305 | \code{[a, b, c]}. Tuples are constructed by the comma operator (not |
| 306 | within square brackets), with or without enclosing parentheses, but an |
| 307 | empty tuple must have the enclosing parentheses, e.g., |
| 308 | \code{a, b, c} or \code{()}. A single item tuple must have a trailing |
| 309 | comma, e.g., \code{(d,)}. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 310 | \indexii{sequence}{types} |
| 311 | \indexii{string}{type} |
| 312 | \indexii{tuple}{type} |
| 313 | \indexii{list}{type} |
| 314 | |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 315 | Sequence types support the following operations. The \samp{in} and |
Fred Drake | 120ac20 | 1997-10-13 20:48:17 +0000 | [diff] [blame] | 316 | \samp{not in} operations have the same priorities as the comparison |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 317 | operations. The \samp{+} and \samp{*} operations have the same |
| 318 | priority as the corresponding numeric operations.\footnote{They must |
| 319 | have since the parser can't tell the type of the operands.} |
| 320 | |
Guido van Rossum | 96628a9 | 1995-04-10 11:34:00 +0000 | [diff] [blame] | 321 | This table lists the sequence operations sorted in ascending priority |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 322 | (operations in the same box have the same priority). In the table, |
| 323 | \var{s} and \var{t} are sequences of the same type; \var{n}, \var{i} |
| 324 | and \var{j} are integers: |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 325 | |
| 326 | \begin{tableiii}{|c|l|c|}{code}{Operation}{Result}{Notes} |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 327 | \lineiii{\var{x} in \var{s}}{\code{1} if an item of \var{s} is equal to \var{x}, else \code{0}}{} |
| 328 | \lineiii{\var{x} not in \var{s}}{\code{0} if an item of \var{s} is |
| 329 | equal to \var{x}, else \code{1}}{} |
| 330 | \hline |
| 331 | \lineiii{\var{s} + \var{t}}{the concatenation of \var{s} and \var{t}}{} |
| 332 | \hline |
Guido van Rossum | 7570669 | 1998-01-27 19:09:43 +0000 | [diff] [blame] | 333 | \lineiii{\var{s} * \var{n}{\rm ,} \var{n} * \var{s}}{\var{n} copies of \var{s} concatenated}{(3)} |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 334 | \hline |
| 335 | \lineiii{\var{s}[\var{i}]}{\var{i}'th item of \var{s}, origin 0}{(1)} |
| 336 | \lineiii{\var{s}[\var{i}:\var{j}]}{slice of \var{s} from \var{i} to \var{j}}{(1), (2)} |
| 337 | \hline |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 338 | \lineiii{len(\var{s})}{length of \var{s}}{} |
| 339 | \lineiii{min(\var{s})}{smallest item of \var{s}}{} |
| 340 | \lineiii{max(\var{s})}{largest item of \var{s}}{} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 341 | \end{tableiii} |
| 342 | \indexiii{operations on}{sequence}{types} |
| 343 | \bifuncindex{len} |
| 344 | \bifuncindex{min} |
| 345 | \bifuncindex{max} |
| 346 | \indexii{concatenation}{operation} |
| 347 | \indexii{repetition}{operation} |
| 348 | \indexii{subscript}{operation} |
| 349 | \indexii{slice}{operation} |
| 350 | \opindex{in} |
| 351 | \opindex{not in} |
| 352 | |
| 353 | \noindent |
| 354 | Notes: |
| 355 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 356 | \begin{description} |
| 357 | |
| 358 | \item[(1)] If \var{i} or \var{j} is negative, the index is relative to |
| 359 | the end of the string, i.e., \code{len(\var{s}) + \var{i}} or |
| 360 | \code{len(\var{s}) + \var{j}} is substituted. But note that \code{-0} is |
| 361 | still \code{0}. |
| 362 | |
| 363 | \item[(2)] The slice of \var{s} from \var{i} to \var{j} is defined as |
| 364 | the sequence of items with index \var{k} such that \code{\var{i} <= |
| 365 | \var{k} < \var{j}}. If \var{i} or \var{j} is greater than |
| 366 | \code{len(\var{s})}, use \code{len(\var{s})}. If \var{i} is omitted, |
| 367 | use \code{0}. If \var{j} is omitted, use \code{len(\var{s})}. If |
| 368 | \var{i} is greater than or equal to \var{j}, the slice is empty. |
| 369 | |
Guido van Rossum | 7570669 | 1998-01-27 19:09:43 +0000 | [diff] [blame] | 370 | \item[(3)] Values of \var{n} less than \code{0} are treated as |
| 371 | \code{0} (which yields an empty sequence of the same type as |
| 372 | \var{s}). |
| 373 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 374 | \end{description} |
| 375 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 376 | \subsubsection{More String Operations} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 377 | |
| 378 | String objects have one unique built-in operation: the \code{\%} |
| 379 | operator (modulo) with a string left argument interprets this string |
| 380 | as a C sprintf format string to be applied to the right argument, and |
| 381 | returns the string resulting from this formatting operation. |
| 382 | |
Guido van Rossum | 8b605eb | 1994-06-23 12:14:07 +0000 | [diff] [blame] | 383 | The right argument should be a tuple with one item for each argument |
| 384 | required by the format string; if the string requires a single |
| 385 | argument, the right argument may also be a single non-tuple object.% |
| 386 | \footnote{A tuple object in this case should be a singleton.} |
| 387 | The following format characters are understood: |
| 388 | \%, c, s, i, d, u, o, x, X, e, E, f, g, G. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 389 | Width and precision may be a * to specify that an integer argument |
| 390 | specifies the actual width or precision. The flag characters -, +, |
| 391 | blank, \# and 0 are understood. The size specifiers h, l or L may be |
Guido van Rossum | 1738311 | 1994-04-21 10:32:28 +0000 | [diff] [blame] | 392 | present but are ignored. The \code{\%s} conversion takes any Python |
| 393 | object and converts it to a string using \code{str()} before |
| 394 | formatting it. The ANSI features \code{\%p} and \code{\%n} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 395 | are not supported. Since Python strings have an explicit length, |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 396 | \code{\%s} conversions don't assume that \code{'\e0'} is the end of |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 397 | the string. |
| 398 | |
Guido van Rossum | e6ef032 | 1994-05-09 14:54:24 +0000 | [diff] [blame] | 399 | For safety reasons, floating point precisions are clipped to 50; |
| 400 | \code{\%f} conversions for numbers whose absolute value is over 1e25 |
| 401 | are replaced by \code{\%g} conversions.% |
| 402 | \footnote{These numbers are fairly arbitrary. They are intended to |
| 403 | avoid printing endless strings of meaningless digits without hampering |
| 404 | correct use and without having to know the exact precision of floating |
| 405 | point values on a particular machine.} |
| 406 | All other errors raise exceptions. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 407 | |
Guido van Rossum | 1738311 | 1994-04-21 10:32:28 +0000 | [diff] [blame] | 408 | If the right argument is a dictionary (or any kind of mapping), then |
| 409 | the formats in the string must have a parenthesized key into that |
| 410 | dictionary inserted immediately after the \code{\%} character, and |
| 411 | each format formats the corresponding entry from the mapping. E.g. |
Guido van Rossum | 6c9db41 | 1997-07-17 16:05:47 +0000 | [diff] [blame] | 412 | \bcode\begin{verbatim} |
| 413 | >>> count = 2 |
| 414 | >>> language = 'Python' |
| 415 | >>> print '%(language)s has %(count)03d quote types.' % vars() |
| 416 | Python has 002 quote types. |
| 417 | >>> |
| 418 | \end{verbatim}\ecode |
Fred Drake | 4bf1296 | 1996-10-11 16:33:48 +0000 | [diff] [blame] | 419 | In this case no * specifiers may occur in a format (since they |
| 420 | require a sequential parameter list). |
Guido van Rossum | 1738311 | 1994-04-21 10:32:28 +0000 | [diff] [blame] | 421 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 422 | Additional string operations are defined in standard module |
Fred Drake | 8274f32 | 1997-12-15 22:19:46 +0000 | [diff] [blame] | 423 | \code{string} and in built-in module \code{re}. |
| 424 | \refstmodindex{string} |
| 425 | \refbimodindex{re} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 426 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 427 | \subsubsection{Mutable Sequence Types} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 428 | |
| 429 | List objects support additional operations that allow in-place |
| 430 | modification of the object. |
| 431 | These operations would be supported by other mutable sequence types |
| 432 | (when added to the language) as well. |
| 433 | Strings and tuples are immutable sequence types and such objects cannot |
| 434 | be modified once created. |
| 435 | The following operations are defined on mutable sequence types (where |
| 436 | \var{x} is an arbitrary object): |
| 437 | \indexiii{mutable}{sequence}{types} |
| 438 | \indexii{list}{type} |
| 439 | |
| 440 | \begin{tableiii}{|c|l|c|}{code}{Operation}{Result}{Notes} |
| 441 | \lineiii{\var{s}[\var{i}] = \var{x}} |
| 442 | {item \var{i} of \var{s} is replaced by \var{x}}{} |
| 443 | \lineiii{\var{s}[\var{i}:\var{j}] = \var{t}} |
| 444 | {slice of \var{s} from \var{i} to \var{j} is replaced by \var{t}}{} |
| 445 | \lineiii{del \var{s}[\var{i}:\var{j}]} |
| 446 | {same as \code{\var{s}[\var{i}:\var{j}] = []}}{} |
| 447 | \lineiii{\var{s}.append(\var{x})} |
Guido van Rossum | e6ef032 | 1994-05-09 14:54:24 +0000 | [diff] [blame] | 448 | {same as \code{\var{s}[len(\var{s}):len(\var{s})] = [\var{x}]}}{} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 449 | \lineiii{\var{s}.count(\var{x})} |
| 450 | {return number of \var{i}'s for which \code{\var{s}[\var{i}] == \var{x}}}{} |
| 451 | \lineiii{\var{s}.index(\var{x})} |
| 452 | {return smallest \var{i} such that \code{\var{s}[\var{i}] == \var{x}}}{(1)} |
| 453 | \lineiii{\var{s}.insert(\var{i}, \var{x})} |
Guido van Rossum | 95a5b9c | 1995-07-07 23:03:07 +0000 | [diff] [blame] | 454 | {same as \code{\var{s}[\var{i}:\var{i}] = [\var{x}]} |
| 455 | if \code{\var{i} >= 0}}{} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 456 | \lineiii{\var{s}.remove(\var{x})} |
| 457 | {same as \code{del \var{s}[\var{s}.index(\var{x})]}}{(1)} |
| 458 | \lineiii{\var{s}.reverse()} |
Guido van Rossum | 3a0d850 | 1997-06-02 17:18:00 +0000 | [diff] [blame] | 459 | {reverses the items of \var{s} in place}{(3)} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 460 | \lineiii{\var{s}.sort()} |
Guido van Rossum | 3a0d850 | 1997-06-02 17:18:00 +0000 | [diff] [blame] | 461 | {sort the items of \var{s} in place}{(2), (3)} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 462 | \end{tableiii} |
| 463 | \indexiv{operations on}{mutable}{sequence}{types} |
| 464 | \indexiii{operations on}{sequence}{types} |
| 465 | \indexiii{operations on}{list}{type} |
| 466 | \indexii{subscript}{assignment} |
| 467 | \indexii{slice}{assignment} |
| 468 | \stindex{del} |
| 469 | \renewcommand{\indexsubitem}{(list method)} |
| 470 | \ttindex{append} |
| 471 | \ttindex{count} |
| 472 | \ttindex{index} |
| 473 | \ttindex{insert} |
| 474 | \ttindex{remove} |
| 475 | \ttindex{reverse} |
| 476 | \ttindex{sort} |
| 477 | |
| 478 | \noindent |
| 479 | Notes: |
| 480 | \begin{description} |
| 481 | \item[(1)] Raises an exception when \var{x} is not found in \var{s}. |
| 482 | |
| 483 | \item[(2)] The \code{sort()} method takes an optional argument |
| 484 | specifying a comparison function of two arguments (list items) which |
| 485 | should return \code{-1}, \code{0} or \code{1} depending on whether the |
| 486 | first argument is considered smaller than, equal to, or larger than the |
| 487 | second argument. Note that this slows the sorting process down |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 488 | considerably; e.g. to sort a list in reverse order it is much faster |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 489 | to use calls to \code{sort()} and \code{reverse()} than to use |
| 490 | \code{sort()} with a comparison function that reverses the ordering of |
| 491 | the elements. |
Guido van Rossum | 3a0d850 | 1997-06-02 17:18:00 +0000 | [diff] [blame] | 492 | |
| 493 | \item[(3)] The \code{sort()} and \code{reverse()} methods modify the |
| 494 | list in place for economy of space when sorting or reversing a large |
| 495 | list. They don't return the sorted or reversed list to remind you of |
| 496 | this side effect. |
| 497 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 498 | \end{description} |
| 499 | |
| 500 | \subsection{Mapping Types} |
| 501 | |
| 502 | A \dfn{mapping} object maps values of one type (the key type) to |
| 503 | arbitrary objects. Mappings are mutable objects. There is currently |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 504 | only one standard mapping type, the \dfn{dictionary}. A dictionary's keys are |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 505 | almost arbitrary values. The only types of values not acceptable as |
| 506 | keys are values containing lists or dictionaries or other mutable |
| 507 | types that are compared by value rather than by object identity. |
| 508 | Numeric types used for keys obey the normal rules for numeric |
| 509 | comparison: if two numbers compare equal (e.g. 1 and 1.0) then they |
| 510 | can be used interchangeably to index the same dictionary entry. |
| 511 | |
| 512 | \indexii{mapping}{types} |
| 513 | \indexii{dictionary}{type} |
| 514 | |
| 515 | Dictionaries are created by placing a comma-separated list of |
Guido van Rossum | 1dde7b7 | 1996-10-11 15:57:17 +0000 | [diff] [blame] | 516 | \code{\var{key}:\,\var{value}} pairs within braces, for example: |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 517 | \code{\{'jack':\,4098, 'sjoerd':\,4127\}} or |
| 518 | \code{\{4098:\,'jack', 4127:\,'sjoerd'\}}. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 519 | |
| 520 | The following operations are defined on mappings (where \var{a} is a |
| 521 | mapping, \var{k} is a key and \var{x} is an arbitrary object): |
| 522 | |
| 523 | \begin{tableiii}{|c|l|c|}{code}{Operation}{Result}{Notes} |
| 524 | \lineiii{len(\var{a})}{the number of items in \var{a}}{} |
| 525 | \lineiii{\var{a}[\var{k}]}{the item of \var{a} with key \var{k}}{(1)} |
| 526 | \lineiii{\var{a}[\var{k}] = \var{x}}{set \code{\var{a}[\var{k}]} to \var{x}}{} |
| 527 | \lineiii{del \var{a}[\var{k}]}{remove \code{\var{a}[\var{k}]} from \var{a}}{(1)} |
Guido van Rossum | 6102b51 | 1997-05-28 19:32:11 +0000 | [diff] [blame] | 528 | \lineiii{\var{a}.clear()}{remove all items from \code{a}}{} |
| 529 | \lineiii{\var{a}.copy()}{a (shallow) copy of \code{a}}{} |
| 530 | \lineiii{\var{a}.has_key(\var{k})}{\code{1} if \var{a} has a key \var{k}, else \code{0}}{} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 531 | \lineiii{\var{a}.items()}{a copy of \var{a}'s list of (key, item) pairs}{(2)} |
| 532 | \lineiii{\var{a}.keys()}{a copy of \var{a}'s list of keys}{(2)} |
Fred Drake | 6b3ed7f | 1998-01-09 20:36:44 +0000 | [diff] [blame] | 533 | \lineiii{\var{a}.update(\var{b})}{\code{for k, v in \var{b}.items(): \var{a}[k] = v}}{(3)} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 534 | \lineiii{\var{a}.values()}{a copy of \var{a}'s list of values}{(2)} |
Fred Drake | 6b3ed7f | 1998-01-09 20:36:44 +0000 | [diff] [blame] | 535 | \lineiii{\var{a}.get(\var{k}, \var{f})}{the item of \var{a} with key \var{k}}{(4)} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 536 | \end{tableiii} |
| 537 | \indexiii{operations on}{mapping}{types} |
| 538 | \indexiii{operations on}{dictionary}{type} |
| 539 | \stindex{del} |
| 540 | \bifuncindex{len} |
| 541 | \renewcommand{\indexsubitem}{(dictionary method)} |
| 542 | \ttindex{keys} |
| 543 | \ttindex{has_key} |
| 544 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 545 | \noindent |
| 546 | Notes: |
| 547 | \begin{description} |
| 548 | \item[(1)] Raises an exception if \var{k} is not in the map. |
| 549 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 550 | \item[(2)] Keys and values are listed in random order. |
Guido van Rossum | 6102b51 | 1997-05-28 19:32:11 +0000 | [diff] [blame] | 551 | |
Fred Drake | 73a973b | 1998-01-20 05:20:39 +0000 | [diff] [blame] | 552 | \item[(3)] \var{b} must be of the same type as \var{a}. |
Barry Warsaw | dc0f00a | 1997-10-06 17:50:48 +0000 | [diff] [blame] | 553 | |
| 554 | \item[(4)] Never raises an exception if \var{k} is not in the map, |
| 555 | instead it returns \var{f}. \var{f} is optional, when not provided |
| 556 | and \var{k} is not in the map, \code{None} is returned. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 557 | \end{description} |
| 558 | |
| 559 | \subsection{Other Built-in Types} |
| 560 | |
| 561 | The interpreter supports several other kinds of objects. |
| 562 | Most of these support only one or two operations. |
| 563 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 564 | \subsubsection{Modules} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 565 | |
| 566 | The only special operation on a module is attribute access: |
| 567 | \code{\var{m}.\var{name}}, where \var{m} is a module and \var{name} accesses |
| 568 | a name defined in \var{m}'s symbol table. Module attributes can be |
| 569 | assigned to. (Note that the \code{import} statement is not, strictly |
| 570 | spoken, an operation on a module object; \code{import \var{foo}} does not |
| 571 | require a module object named \var{foo} to exist, rather it requires |
| 572 | an (external) \emph{definition} for a module named \var{foo} |
| 573 | somewhere.) |
| 574 | |
| 575 | A special member of every module is \code{__dict__}. |
| 576 | This is the dictionary containing the module's symbol table. |
| 577 | Modifying this dictionary will actually change the module's symbol |
| 578 | table, but direct assignment to the \code{__dict__} attribute is not |
| 579 | possible (i.e., you can write \code{\var{m}.__dict__['a'] = 1}, which |
| 580 | defines \code{\var{m}.a} to be \code{1}, but you can't write \code{\var{m}.__dict__ = \{\}}. |
| 581 | |
| 582 | Modules are written like this: \code{<module 'sys'>}. |
| 583 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 584 | \subsubsection{Classes and Class Instances} |
Guido van Rossum | 86cb092 | 1995-03-20 12:59:56 +0000 | [diff] [blame] | 585 | \nodename{Classes and Instances} |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 586 | |
| 587 | (See Chapters 3 and 7 of the Python Reference Manual for these.) |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 588 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 589 | \subsubsection{Functions} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 590 | |
| 591 | Function objects are created by function definitions. The only |
| 592 | operation on a function object is to call it: |
| 593 | \code{\var{func}(\var{argument-list})}. |
| 594 | |
| 595 | There are really two flavors of function objects: built-in functions |
| 596 | and user-defined functions. Both support the same operation (to call |
| 597 | the function), but the implementation is different, hence the |
| 598 | different object types. |
| 599 | |
| 600 | The implementation adds two special read-only attributes: |
| 601 | \code{\var{f}.func_code} is a function's \dfn{code object} (see below) and |
| 602 | \code{\var{f}.func_globals} is the dictionary used as the function's |
| 603 | global name space (this is the same as \code{\var{m}.__dict__} where |
| 604 | \var{m} is the module in which the function \var{f} was defined). |
| 605 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 606 | \subsubsection{Methods} |
Guido van Rossum | ea6e19c | 1995-03-07 10:11:15 +0000 | [diff] [blame] | 607 | \obindex{method} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 608 | |
| 609 | Methods are functions that are called using the attribute notation. |
| 610 | There are two flavors: built-in methods (such as \code{append()} on |
| 611 | lists) and class instance methods. Built-in methods are described |
| 612 | with the types that support them. |
| 613 | |
| 614 | The implementation adds two special read-only attributes to class |
| 615 | instance methods: \code{\var{m}.im_self} is the object whose method this |
| 616 | is, and \code{\var{m}.im_func} is the function implementing the method. |
| 617 | Calling \code{\var{m}(\var{arg-1}, \var{arg-2}, {\rm \ldots}, |
| 618 | \var{arg-n})} is completely equivalent to calling |
| 619 | \code{\var{m}.im_func(\var{m}.im_self, \var{arg-1}, \var{arg-2}, {\rm |
| 620 | \ldots}, \var{arg-n})}. |
| 621 | |
| 622 | (See the Python Reference Manual for more info.) |
| 623 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 624 | \subsubsection{Code Objects} |
Guido van Rossum | ea6e19c | 1995-03-07 10:11:15 +0000 | [diff] [blame] | 625 | \obindex{code} |
| 626 | |
| 627 | Code objects are used by the implementation to represent |
| 628 | ``pseudo-compiled'' executable Python code such as a function body. |
| 629 | They differ from function objects because they don't contain a |
| 630 | reference to their global execution environment. Code objects are |
| 631 | returned by the built-in \code{compile()} function and can be |
| 632 | extracted from function objects through their \code{func_code} |
| 633 | attribute. |
| 634 | \bifuncindex{compile} |
| 635 | \ttindex{func_code} |
| 636 | |
| 637 | A code object can be executed or evaluated by passing it (instead of a |
| 638 | source string) to the \code{exec} statement or the built-in |
| 639 | \code{eval()} function. |
| 640 | \stindex{exec} |
| 641 | \bifuncindex{eval} |
| 642 | |
| 643 | (See the Python Reference Manual for more info.) |
| 644 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 645 | \subsubsection{Type Objects} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 646 | |
| 647 | Type objects represent the various object types. An object's type is |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 648 | accessed by the built-in function \code{type()}. There are no special |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 649 | operations on types. The standard module \code{types} defines names |
| 650 | for all standard built-in types. |
| 651 | \bifuncindex{type} |
Fred Drake | 8274f32 | 1997-12-15 22:19:46 +0000 | [diff] [blame] | 652 | \refstmodindex{types} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 653 | |
| 654 | Types are written like this: \code{<type 'int'>}. |
| 655 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 656 | \subsubsection{The Null Object} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 657 | |
| 658 | This object is returned by functions that don't explicitly return a |
| 659 | value. It supports no special operations. There is exactly one null |
| 660 | object, named \code{None} (a built-in name). |
| 661 | |
| 662 | It is written as \code{None}. |
| 663 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 664 | \subsubsection{File Objects} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 665 | |
| 666 | File objects are implemented using \C{}'s \code{stdio} package and can be |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 667 | created with the built-in function \code{open()} described under |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 668 | Built-in Functions below. They are also returned by some other |
| 669 | built-in functions and methods, e.g.\ \code{posix.popen()} and |
| 670 | \code{posix.fdopen()} and the \code{makefile()} method of socket |
| 671 | objects. |
| 672 | \bifuncindex{open} |
Fred Drake | 73a973b | 1998-01-20 05:20:39 +0000 | [diff] [blame] | 673 | \refbimodindex{posix} |
| 674 | \refbimodindex{socket} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 675 | |
| 676 | When a file operation fails for an I/O-related reason, the exception |
| 677 | \code{IOError} is raised. This includes situations where the |
| 678 | operation is not defined for some reason, like \code{seek()} on a tty |
| 679 | device or writing a file opened for reading. |
| 680 | |
| 681 | Files have the following methods: |
| 682 | |
| 683 | |
| 684 | \renewcommand{\indexsubitem}{(file method)} |
| 685 | |
| 686 | \begin{funcdesc}{close}{} |
| 687 | Close the file. A closed file cannot be read or written anymore. |
| 688 | \end{funcdesc} |
| 689 | |
| 690 | \begin{funcdesc}{flush}{} |
| 691 | Flush the internal buffer, like \code{stdio}'s \code{fflush()}. |
| 692 | \end{funcdesc} |
| 693 | |
| 694 | \begin{funcdesc}{isatty}{} |
| 695 | Return \code{1} if the file is connected to a tty(-like) device, else |
| 696 | \code{0}. |
| 697 | \end{funcdesc} |
| 698 | |
Guido van Rossum | 6c9db41 | 1997-07-17 16:05:47 +0000 | [diff] [blame] | 699 | \begin{funcdesc}{fileno}{} |
| 700 | Return the integer ``file descriptor'' that is used by the underlying |
| 701 | implementation to request I/O operations from the operating system. |
| 702 | This can be useful for other, lower level interfaces that use file |
Fred Drake | 8274f32 | 1997-12-15 22:19:46 +0000 | [diff] [blame] | 703 | descriptors, e.g. module \code{fcntl} or \code{os.read()} and friends. |
| 704 | \refbimodindex{fcntl} |
Guido van Rossum | 6c9db41 | 1997-07-17 16:05:47 +0000 | [diff] [blame] | 705 | \end{funcdesc} |
| 706 | |
Guido van Rossum | 0dbd1fd | 1995-08-10 14:22:39 +0000 | [diff] [blame] | 707 | \begin{funcdesc}{read}{\optional{size}} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 708 | Read at most \var{size} bytes from the file (less if the read hits |
| 709 | \EOF{} or no more data is immediately available on a pipe, tty or |
Guido van Rossum | 0dbd1fd | 1995-08-10 14:22:39 +0000 | [diff] [blame] | 710 | similar device). If the \var{size} argument is negative or omitted, |
| 711 | read all data until \EOF{} is reached. The bytes are returned as a string |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 712 | object. An empty string is returned when \EOF{} is encountered |
| 713 | immediately. (For certain files, like ttys, it makes sense to |
| 714 | continue reading after an \EOF{} is hit.) |
| 715 | \end{funcdesc} |
| 716 | |
Jack Jansen | 4518577 | 1995-08-14 13:38:36 +0000 | [diff] [blame] | 717 | \begin{funcdesc}{readline}{\optional{size}} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 718 | Read one entire line from the file. A trailing newline character is |
Guido van Rossum | 31cce97 | 1995-01-04 19:17:34 +0000 | [diff] [blame] | 719 | kept in the string% |
| 720 | \footnote{The advantage of leaving the newline on is that an empty string |
| 721 | can be returned to mean \EOF{} without being ambiguous. Another |
| 722 | advantage is that (in cases where it might matter, e.g. if you |
| 723 | want to make an exact copy of a file while scanning its lines) |
| 724 | you can tell whether the last line of a file ended in a newline |
| 725 | or not (yes this happens!).} |
| 726 | (but may be absent when a file ends with an |
Guido van Rossum | 1dde7b7 | 1996-10-11 15:57:17 +0000 | [diff] [blame] | 727 | incomplete line). If the \var{size} argument is present and |
Guido van Rossum | 0dbd1fd | 1995-08-10 14:22:39 +0000 | [diff] [blame] | 728 | non-negative, it is a maximum byte count (including the trailing |
| 729 | newline) and an incomplete line may be returned. |
| 730 | An empty string is returned when \EOF{} is hit |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 731 | immediately. Note: unlike \code{stdio}'s \code{fgets()}, the returned |
| 732 | string contains null characters (\code{'\e 0'}) if they occurred in the |
| 733 | input. |
| 734 | \end{funcdesc} |
| 735 | |
Guido van Rossum | 6c9db41 | 1997-07-17 16:05:47 +0000 | [diff] [blame] | 736 | \begin{funcdesc}{readlines}{\optional{sizehint}} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 737 | Read until \EOF{} using \code{readline()} and return a list containing |
Guido van Rossum | eb0f066 | 1997-12-30 20:38:16 +0000 | [diff] [blame] | 738 | the lines thus read. If the optional \var{sizehint} argument is |
Guido van Rossum | 6c9db41 | 1997-07-17 16:05:47 +0000 | [diff] [blame] | 739 | present, instead of reading up to \EOF{}, whole lines totalling |
| 740 | approximately \var{sizehint} bytes are read. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 741 | \end{funcdesc} |
| 742 | |
| 743 | \begin{funcdesc}{seek}{offset\, whence} |
| 744 | Set the file's current position, like \code{stdio}'s \code{fseek()}. |
| 745 | The \var{whence} argument is optional and defaults to \code{0} |
| 746 | (absolute file positioning); other values are \code{1} (seek |
| 747 | relative to the current position) and \code{2} (seek relative to the |
| 748 | file's end). There is no return value. |
| 749 | \end{funcdesc} |
| 750 | |
| 751 | \begin{funcdesc}{tell}{} |
| 752 | Return the file's current position, like \code{stdio}'s \code{ftell()}. |
| 753 | \end{funcdesc} |
| 754 | |
Guido van Rossum | 316a430 | 1996-05-02 15:28:53 +0000 | [diff] [blame] | 755 | \begin{funcdesc}{truncate}{\optional{size}} |
| 756 | Truncate the file's size. If the optional size argument present, the |
| 757 | file is truncated to (at most) that size. The size defaults to the |
| 758 | current position. Availability of this function depends on the |
Guido van Rossum | 1dde7b7 | 1996-10-11 15:57:17 +0000 | [diff] [blame] | 759 | operating system version (e.g., not all \UNIX{} versions support this |
Guido van Rossum | 316a430 | 1996-05-02 15:28:53 +0000 | [diff] [blame] | 760 | operation). |
| 761 | \end{funcdesc} |
| 762 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 763 | \begin{funcdesc}{write}{str} |
Guido van Rossum | 316a430 | 1996-05-02 15:28:53 +0000 | [diff] [blame] | 764 | Write a string to the file. There is no return value. Note: due to |
| 765 | buffering, the string may not actually show up in the file until |
| 766 | the \code{flush()} or \code{close()} method is called. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 767 | \end{funcdesc} |
| 768 | |
Guido van Rossum | 8b605eb | 1994-06-23 12:14:07 +0000 | [diff] [blame] | 769 | \begin{funcdesc}{writelines}{list} |
| 770 | Write a list of strings to the file. There is no return value. |
| 771 | (The name is intended to match \code{readlines}; \code{writelines} |
| 772 | does not add line separators.) |
| 773 | \end{funcdesc} |
| 774 | |
Guido van Rossum | 6c9db41 | 1997-07-17 16:05:47 +0000 | [diff] [blame] | 775 | Classes that are trying to simulate a file object should also have a |
| 776 | writable \code{softspace} attribute, which should be initialized to |
| 777 | zero. (\code{softspace} is used by the \code{print} statement.) This |
| 778 | will be automatic for classes implemented in Python; types implemented |
| 779 | in C will have to provide a writable \code{softspace} attribute. |
| 780 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 781 | \subsubsection{Internal Objects} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 782 | |
| 783 | (See the Python Reference Manual for these.) |
| 784 | |
| 785 | \subsection{Special Attributes} |
| 786 | |
| 787 | The implementation adds a few special read-only attributes to several |
| 788 | object types, where they are relevant: |
| 789 | |
| 790 | \begin{itemize} |
| 791 | |
| 792 | \item |
| 793 | \code{\var{x}.__dict__} is a dictionary of some sort used to store an |
| 794 | object's (writable) attributes; |
| 795 | |
| 796 | \item |
| 797 | \code{\var{x}.__methods__} lists the methods of many built-in object types, |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 798 | e.g., \code{[].__methods__} yields |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 799 | \code{['append', 'count', 'index', 'insert', 'remove', 'reverse', 'sort']}; |
| 800 | |
| 801 | \item |
| 802 | \code{\var{x}.__members__} lists data attributes; |
| 803 | |
| 804 | \item |
| 805 | \code{\var{x}.__class__} is the class to which a class instance belongs; |
| 806 | |
| 807 | \item |
| 808 | \code{\var{x}.__bases__} is the tuple of base classes of a class object. |
| 809 | |
| 810 | \end{itemize} |