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