1 \section{Built-in Types
}
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
}
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.
16 \subsection{Truth Value Testing
}
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.
20 The following values are considered false:
23 \indexii{truth
}{value
}
24 \indexii{Boolean
}{operations
}
28 \renewcommand{\indexsubitem}{(Built-in object)
}
33 \item zero of any numeric type, e.g.,
\code{0},
\code{0L},
\code{0.0}.
35 \item any empty sequence, e.g.,
\code{''
},
\code{()
},
\code{[]}.
37 \item any empty mapping, e.g.,
\code{\
{\
}}.
39 \item instances of user-defined classes, if the class defines a
40 \code{__nonzero__()
} or
\code{__len__()
} method, when that
45 All other values are considered true --- so objects of many types are
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.)
54 \subsection{Boolean Operations
}
56 These are the Boolean operations, ordered by ascending priority:
57 \indexii{Boolean
}{operations
}
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)
}
62 \lineiii{\var{x
} and
\var{y
}}{if
\var{x
} is false, then
\var{x
}, else
\var{y
}}{(
1)
}
64 \lineiii{not
\var{x
}}{if
\var{x
} is false, then
\code{1}, else
\code{0}}{(
2)
}
76 These only evaluate their second argument if needed for their outcome.
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.
85 \subsection{Comparisons
}
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
}
95 This table summarizes the comparison operations:
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
}{}
108 \indexii{operator
}{comparison
}
109 \opindex{==
} % XXX *All* others have funny characters < ! >
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
}
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
}
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.)
139 Two more operations with the same syntactic priority,
\code{in
} and
140 \code{not in
}, are supported only by sequence types (below).
144 \subsection{Numeric Types
}
146 There are three numeric types:
\dfn{plain integers
},
\dfn{long integers
}, and
147 \dfn{floating point numbers
}. Plain integers (also just called
\dfn{integers
})
148 are implemented using
\code{long
} in
\C{}, which gives them at least
32
149 bits of precision. Long integers have unlimited precision. Floating
150 point numbers are implemented using
\code{double
} in
\C{}. All bets on
151 their precision are off unless you happen to know the machine you are
153 \indexii{numeric
}{types
}
154 \indexii{integer
}{types
}
155 \indexii{integer
}{type
}
156 \indexiii{long
}{integer
}{type
}
157 \indexii{floating point
}{type
}
158 \indexii{\C{}}{language
}
160 Numbers are created by numeric literals or as the result of built-in
161 functions and operators. Unadorned integer literals (including hex
162 and octal numbers) yield plain integers. Integer literals with an
\samp{L
}
163 or
\samp{l
} suffix yield long integers
164 (
\samp{L
} is preferred because
\code{1l} looks too much like eleven!).
165 Numeric literals containing a decimal point or an exponent sign yield
166 floating point numbers.
167 \indexii{numeric
}{literals
}
168 \indexii{integer
}{literals
}
169 \indexiii{long
}{integer
}{literals
}
170 \indexii{floating point
}{literals
}
171 \indexii{hexadecimal
}{literals
}
172 \indexii{octal
}{literals
}
174 Python fully supports mixed arithmetic: when a binary arithmetic
175 operator has operands of different numeric types, the operand with the
176 ``smaller'' type is converted to that of the other, where plain
177 integer is smaller than long integer is smaller than floating point.
178 Comparisons between numbers of mixed type use the same rule.
%
179 \footnote{As a consequence, the list
\code{[1,
2]} is considered equal
180 to
\code{[1.0,
2.0]}, and similar for tuples.
}
181 The functions
\code{int()
},
\code{long()
} and
\code{float()
} can be used
182 to coerce numbers to a specific type.
188 All numeric types support the following operations, sorted by
189 ascending priority (operations in the same box have the same
190 priority; all numeric operations have a higher priority than
191 comparison operations):
193 \begin{tableiii
}{|c|l|c|
}{code
}{Operation
}{Result
}{Notes
}
194 \lineiii{\var{x
} +
\var{y
}}{sum of
\var{x
} and
\var{y
}}{}
195 \lineiii{\var{x
} -
\var{y
}}{difference of
\var{x
} and
\var{y
}}{}
197 \lineiii{\var{x
} *
\var{y
}}{product of
\var{x
} and
\var{y
}}{}
198 \lineiii{\var{x
} /
\var{y
}}{quotient of
\var{x
} and
\var{y
}}{(
1)
}
199 \lineiii{\var{x
} \%
{} \var{y
}}{remainder of
\code{\var{x
} /
\var{y
}}}{}
201 \lineiii{-
\var{x
}}{\var{x
} negated
}{}
202 \lineiii{+
\var{x
}}{\var{x
} unchanged
}{}
204 \lineiii{abs(
\var{x
})
}{absolute value of
\var{x
}}{}
205 \lineiii{int(
\var{x
})
}{\var{x
} converted to integer
}{(
2)
}
206 \lineiii{long(
\var{x
})
}{\var{x
} converted to long integer
}{(
2)
}
207 \lineiii{float(
\var{x
})
}{\var{x
} converted to floating point
}{}
208 \lineiii{divmod(
\var{x
},
\var{y
})
}{the pair
\code{(
\var{x
} /
\var{y
},
\var{x
} \%
{} \var{y
})
}}{(
3)
}
209 \lineiii{pow(
\var{x
},
\var{y
})
}{\var{x
} to the power
\var{y
}}{}
211 \indexiii{operations on
}{numeric
}{types
}
218 For (plain or long) integer division, the result is an integer.
219 The result is always rounded towards minus infinity:
1/
2 is
0,
220 (-
1)/
2 is -
1,
1/(-
2) is -
1, and (-
1)/(-
2) is
0.
221 \indexii{integer
}{division
}
222 \indexiii{long
}{integer
}{division
}
225 Conversion from floating point to (long or plain) integer may round or
226 truncate as in
\C{}; see functions
\code{floor()
} and
\code{ceil()
} in
227 module
\code{math
} for well-defined conversions.
230 \indexii{numeric
}{conversions
}
232 \indexii{\C{}}{language
}
235 See the section on built-in functions for an exact definition.
238 % XXXJH exceptions: overflow (when? what operations?) zerodivision
240 \subsubsection{Bit-string Operations on Integer Types
}
241 \nodename{Bit-string Operations
}
243 Plain and long integer types support additional operations that make
244 sense only for bit-strings. Negative numbers are treated as their
2's
245 complement value (for long integers, this assumes a sufficiently large
246 number of bits that no overflow occurs during the operation).
248 The priorities of the binary bit-wise operations are all lower than
249 the numeric operations and higher than the comparisons; the unary
250 operation
\samp{~
} has the same priority as the other unary numeric
251 operations (
\samp{+
} and
\samp{-
}).
253 This table lists the bit-string operations sorted in ascending
254 priority (operations in the same box have the same priority):
256 \begin{tableiii
}{|c|l|c|
}{code
}{Operation
}{Result
}{Notes
}
257 \lineiii{\var{x
} |
\var{y
}}{bitwise
\dfn{or
} of
\var{x
} and
\var{y
}}{}
259 \lineiii{\var{x
} \^
{} \var{y
}}{bitwise
\dfn{exclusive or
} of
\var{x
} and
\var{y
}}{}
261 \lineiii{\var{x
} \&
{} \var{y
}}{bitwise
\dfn{and
} of
\var{x
} and
\var{y
}}{}
263 \lineiii{\var{x
} <<
\var{n
}}{\var{x
} shifted left by
\var{n
} bits
}{(
1), (
2)
}
264 \lineiii{\var{x
} >>
\var{n
}}{\var{x
} shifted right by
\var{n
} bits
}{(
1), (
3)
}
267 \lineiii{\~
\var{x
}}{the bits of
\var{x
} inverted
}{}
269 \indexiii{operations on
}{integer
}{types
}
270 \indexii{bit-string
}{operations
}
271 \indexii{shifting
}{operations
}
272 \indexii{masking
}{operations
}
277 \item[(
1)
] Negative shift counts are illegal.
278 \item[(
2)
] A left shift by
\var{n
} bits is equivalent to
279 multiplication by
\code{pow(
2,
\var{n
})
} without overflow check.
280 \item[(
3)
] A right shift by
\var{n
} bits is equivalent to
281 division by
\code{pow(
2,
\var{n
})
} without overflow check.
284 \subsection{Sequence Types
}
286 There are three sequence types: strings, lists and tuples.
288 Strings literals are written in single or double quotes:
289 \code{'xyzzy'
},
\code{"frobozz"
}. See Chapter
2 of the Python
290 Reference Manual for more about string literals. Lists are
291 constructed with square brackets, separating items with commas:
292 \code{[a, b, c
]}. Tuples are constructed by the comma operator (not
293 within square brackets), with or without enclosing parentheses, but an
294 empty tuple must have the enclosing parentheses, e.g.,
295 \code{a, b, c
} or
\code{()
}. A single item tuple must have a trailing
296 comma, e.g.,
\code{(d,)
}.
297 \indexii{sequence
}{types
}
298 \indexii{string
}{type
}
299 \indexii{tuple
}{type
}
302 Sequence types support the following operations. The
\samp{in
} and
303 \samp{not\,in
} operations have the same priorities as the comparison
304 operations. The
\samp{+
} and
\samp{*
} operations have the same
305 priority as the corresponding numeric operations.
\footnote{They must
306 have since the parser can't tell the type of the operands.
}
308 This table lists the sequence operations sorted in ascending priority
309 (operations in the same box have the same priority). In the table,
310 \var{s
} and
\var{t
} are sequences of the same type;
\var{n
},
\var{i
}
311 and
\var{j
} are integers:
313 \begin{tableiii
}{|c|l|c|
}{code
}{Operation
}{Result
}{Notes
}
314 \lineiii{\var{x
} in
\var{s
}}{\code{1} if an item of
\var{s
} is equal to
\var{x
}, else
\code{0}}{}
315 \lineiii{\var{x
} not in
\var{s
}}{\code{0} if an item of
\var{s
} is
316 equal to
\var{x
}, else
\code{1}}{}
318 \lineiii{\var{s
} +
\var{t
}}{the concatenation of
\var{s
} and
\var{t
}}{}
320 \lineiii{\var{s
} *
\var{n
}{\rm ,
} \var{n
} *
\var{s
}}{\var{n
} copies of
\var{s
} concatenated
}{}
322 \lineiii{\var{s
}[\var{i
}]}{\var{i
}'th item of
\var{s
}, origin
0}{(
1)
}
323 \lineiii{\var{s
}[\var{i
}:
\var{j
}]}{slice of
\var{s
} from
\var{i
} to
\var{j
}}{(
1), (
2)
}
325 \lineiii{len(
\var{s
})
}{length of
\var{s
}}{}
326 \lineiii{min(
\var{s
})
}{smallest item of
\var{s
}}{}
327 \lineiii{max(
\var{s
})
}{largest item of
\var{s
}}{}
329 \indexiii{operations on
}{sequence
}{types
}
333 \indexii{concatenation
}{operation
}
334 \indexii{repetition
}{operation
}
335 \indexii{subscript
}{operation
}
336 \indexii{slice
}{operation
}
345 \item[(
1)
] If
\var{i
} or
\var{j
} is negative, the index is relative to
346 the end of the string, i.e.,
\code{len(
\var{s
}) +
\var{i
}} or
347 \code{len(
\var{s
}) +
\var{j
}} is substituted. But note that
\code{-
0} is
350 \item[(
2)
] The slice of
\var{s
} from
\var{i
} to
\var{j
} is defined as
351 the sequence of items with index
\var{k
} such that
\code{\var{i
} <=
352 \var{k
} <
\var{j
}}. If
\var{i
} or
\var{j
} is greater than
353 \code{len(
\var{s
})
}, use
\code{len(
\var{s
})
}. If
\var{i
} is omitted,
354 use
\code{0}. If
\var{j
} is omitted, use
\code{len(
\var{s
})
}. If
355 \var{i
} is greater than or equal to
\var{j
}, the slice is empty.
359 \subsubsection{More String Operations
}
361 String objects have one unique built-in operation: the
\code{\%
}
362 operator (modulo) with a string left argument interprets this string
363 as a C sprintf format string to be applied to the right argument, and
364 returns the string resulting from this formatting operation.
366 The right argument should be a tuple with one item for each argument
367 required by the format string; if the string requires a single
368 argument, the right argument may also be a single non-tuple object.
%
369 \footnote{A tuple object in this case should be a singleton.
}
370 The following format characters are understood:
371 \%, c, s, i, d, u, o, x, X, e, E, f, g, G.
372 Width and precision may be a * to specify that an integer argument
373 specifies the actual width or precision. The flag characters -, +,
374 blank, \# and
0 are understood. The size specifiers h, l or L may be
375 present but are ignored. The
\code{\%s
} conversion takes any Python
376 object and converts it to a string using
\code{str()
} before
377 formatting it. The ANSI features
\code{\%p
} and
\code{\%n
}
378 are not supported. Since Python strings have an explicit length,
379 \code{\%s
} conversions don't assume that
\code{'
\e0'
} is the end of
382 For safety reasons, floating point precisions are clipped to
50;
383 \code{\%f
} conversions for numbers whose absolute value is over
1e25
384 are replaced by
\code{\%g
} conversions.
%
385 \footnote{These numbers are fairly arbitrary. They are intended to
386 avoid printing endless strings of meaningless digits without hampering
387 correct use and without having to know the exact precision of floating
388 point values on a particular machine.
}
389 All other errors raise exceptions.
391 If the right argument is a dictionary (or any kind of mapping), then
392 the formats in the string must have a parenthesized key into that
393 dictionary inserted immediately after the
\code{\%
} character, and
394 each format formats the corresponding entry from the mapping. E.g.
397 >>> language = 'Python'
398 >>> print '
%(language)s has %(count)03d quote types.' % vars()
399 Python has
002 quote types.
402 In this case no * specifiers may occur in a format (since they a
403 require sequential parameter list).
405 Additional string operations are defined in standard module
406 \code{string
} and in built-in module
\code{regex
}.
410 \subsubsection{Mutable Sequence Types
}
412 List objects support additional operations that allow in-place
413 modification of the object.
414 These operations would be supported by other mutable sequence types
415 (when added to the language) as well.
416 Strings and tuples are immutable sequence types and such objects cannot
417 be modified once created.
418 The following operations are defined on mutable sequence types (where
419 \var{x
} is an arbitrary object):
420 \indexiii{mutable
}{sequence
}{types
}
423 \begin{tableiii
}{|c|l|c|
}{code
}{Operation
}{Result
}{Notes
}
424 \lineiii{\var{s
}[\var{i
}] =
\var{x
}}
425 {item
\var{i
} of
\var{s
} is replaced by
\var{x
}}{}
426 \lineiii{\var{s
}[\var{i
}:
\var{j
}] =
\var{t
}}
427 {slice of
\var{s
} from
\var{i
} to
\var{j
} is replaced by
\var{t
}}{}
428 \lineiii{del
\var{s
}[\var{i
}:
\var{j
}]}
429 {same as
\code{\var{s
}[\var{i
}:
\var{j
}] =
[]}}{}
430 \lineiii{\var{s
}.append(
\var{x
})
}
431 {same as
\code{\var{s
}[len(
\var{s
}):len(
\var{s
})
] =
[\var{x
}]}}{}
432 \lineiii{\var{s
}.count(
\var{x
})
}
433 {return number of
\var{i
}'s for which
\code{\var{s
}[\var{i
}] ==
\var{x
}}}{}
434 \lineiii{\var{s
}.index(
\var{x
})
}
435 {return smallest
\var{i
} such that
\code{\var{s
}[\var{i
}] ==
\var{x
}}}{(
1)
}
436 \lineiii{\var{s
}.insert(
\var{i
},
\var{x
})
}
437 {same as
\code{\var{s
}[\var{i
}:
\var{i
}] =
[\var{x
}]}
438 if
\code{\var{i
} >=
0}}{}
439 \lineiii{\var{s
}.remove(
\var{x
})
}
440 {same as
\code{del
\var{s
}[\var{s
}.index(
\var{x
})
]}}{(
1)
}
441 \lineiii{\var{s
}.reverse()
}
442 {reverses the items of
\var{s
} in place
}{}
443 \lineiii{\var{s
}.sort()
}
444 {permutes the items of
\var{s
} to satisfy
445 \code{\var{s
}[\var{i
}] <=
\var{s
}[\var{j
}]},
446 for
\code{\var{i
} <
\var{j
}}}{(
2)
}
448 \indexiv{operations on
}{mutable
}{sequence
}{types
}
449 \indexiii{operations on
}{sequence
}{types
}
450 \indexiii{operations on
}{list
}{type
}
451 \indexii{subscript
}{assignment
}
452 \indexii{slice
}{assignment
}
454 \renewcommand{\indexsubitem}{(list method)
}
466 \item[(
1)
] Raises an exception when
\var{x
} is not found in
\var{s
}.
468 \item[(
2)
] The
\code{sort()
} method takes an optional argument
469 specifying a comparison function of two arguments (list items) which
470 should return
\code{-
1},
\code{0} or
\code{1} depending on whether the
471 first argument is considered smaller than, equal to, or larger than the
472 second argument. Note that this slows the sorting process down
473 considerably; e.g. to sort a list in reverse order it is much faster
474 to use calls to
\code{sort()
} and
\code{reverse()
} than to use
475 \code{sort()
} with a comparison function that reverses the ordering of
479 \subsection{Mapping Types
}
481 A
\dfn{mapping
} object maps values of one type (the key type) to
482 arbitrary objects. Mappings are mutable objects. There is currently
483 only one standard mapping type, the
\dfn{dictionary
}. A dictionary's keys are
484 almost arbitrary values. The only types of values not acceptable as
485 keys are values containing lists or dictionaries or other mutable
486 types that are compared by value rather than by object identity.
487 Numeric types used for keys obey the normal rules for numeric
488 comparison: if two numbers compare equal (e.g.
1 and
1.0) then they
489 can be used interchangeably to index the same dictionary entry.
491 \indexii{mapping
}{types
}
492 \indexii{dictionary
}{type
}
494 Dictionaries are created by placing a comma-separated list of
495 \code{\var{key
}:\,var
{value
}} pairs within braces, for example:
496 \code{\
{'jack':\,
4098, 'sjoerd':\,
4127\
}} or
497 \code{\
{4098:\,'jack',
4127:\,'sjoerd'\
}}.
499 The following operations are defined on mappings (where
\var{a
} is a
500 mapping,
\var{k
} is a key and
\var{x
} is an arbitrary object):
502 \begin{tableiii
}{|c|l|c|
}{code
}{Operation
}{Result
}{Notes
}
503 \lineiii{len(
\var{a
})
}{the number of items in
\var{a
}}{}
504 \lineiii{\var{a
}[\var{k
}]}{the item of
\var{a
} with key
\var{k
}}{(
1)
}
505 \lineiii{\var{a
}[\var{k
}] =
\var{x
}}{set
\code{\var{a
}[\var{k
}]} to
\var{x
}}{}
506 \lineiii{del
\var{a
}[\var{k
}]}{remove
\code{\var{a
}[\var{k
}]} from
\var{a
}}{(
1)
}
507 \lineiii{\var{a
}.items()
}{a copy of
\var{a
}'s list of (key, item) pairs
}{(
2)
}
508 \lineiii{\var{a
}.keys()
}{a copy of
\var{a
}'s list of keys
}{(
2)
}
509 \lineiii{\var{a
}.values()
}{a copy of
\var{a
}'s list of values
}{(
2)
}
510 \lineiii{\var{a
}.has_key(
\var{k
})
}{\code{1} if
\var{a
} has a key
\var{k
}, else
\code{0}}{}
512 \indexiii{operations on
}{mapping
}{types
}
513 \indexiii{operations on
}{dictionary
}{type
}
516 \renewcommand{\indexsubitem}{(dictionary method)
}
523 \item[(
1)
] Raises an exception if
\var{k
} is not in the map.
525 \item[(
2)
] Keys and values are listed in random order.
528 \subsection{Other Built-in Types
}
530 The interpreter supports several other kinds of objects.
531 Most of these support only one or two operations.
533 \subsubsection{Modules
}
535 The only special operation on a module is attribute access:
536 \code{\var{m
}.
\var{name
}}, where
\var{m
} is a module and
\var{name
} accesses
537 a name defined in
\var{m
}'s symbol table. Module attributes can be
538 assigned to. (Note that the
\code{import
} statement is not, strictly
539 spoken, an operation on a module object;
\code{import
\var{foo
}} does not
540 require a module object named
\var{foo
} to exist, rather it requires
541 an (external)
\emph{definition
} for a module named
\var{foo
}
544 A special member of every module is
\code{__dict__
}.
545 This is the dictionary containing the module's symbol table.
546 Modifying this dictionary will actually change the module's symbol
547 table, but direct assignment to the
\code{__dict__
} attribute is not
548 possible (i.e., you can write
\code{\var{m
}.__dict__
['a'
] =
1}, which
549 defines
\code{\var{m
}.a
} to be
\code{1}, but you can't write
\code{\var{m
}.__dict__ = \
{\
}}.
551 Modules are written like this:
\code{<module 'sys'>
}.
553 \subsubsection{Classes and Class Instances
}
554 \nodename{Classes and Instances
}
556 (See Chapters
3 and
7 of the Python Reference Manual for these.)
558 \subsubsection{Functions
}
560 Function objects are created by function definitions. The only
561 operation on a function object is to call it:
562 \code{\var{func
}(
\var{argument-list
})
}.
564 There are really two flavors of function objects: built-in functions
565 and user-defined functions. Both support the same operation (to call
566 the function), but the implementation is different, hence the
567 different object types.
569 The implementation adds two special read-only attributes:
570 \code{\var{f
}.func_code
} is a function's
\dfn{code object
} (see below) and
571 \code{\var{f
}.func_globals
} is the dictionary used as the function's
572 global name space (this is the same as
\code{\var{m
}.__dict__
} where
573 \var{m
} is the module in which the function
\var{f
} was defined).
575 \subsubsection{Methods
}
578 Methods are functions that are called using the attribute notation.
579 There are two flavors: built-in methods (such as
\code{append()
} on
580 lists) and class instance methods. Built-in methods are described
581 with the types that support them.
583 The implementation adds two special read-only attributes to class
584 instance methods:
\code{\var{m
}.im_self
} is the object whose method this
585 is, and
\code{\var{m
}.im_func
} is the function implementing the method.
586 Calling
\code{\var{m
}(
\var{arg-
1},
\var{arg-
2},
{\rm \ldots},
587 \var{arg-n
})
} is completely equivalent to calling
588 \code{\var{m
}.im_func(
\var{m
}.im_self,
\var{arg-
1},
\var{arg-
2},
{\rm
589 \ldots},
\var{arg-n
})
}.
591 (See the Python Reference Manual for more info.)
593 \subsubsection{Code Objects
}
596 Code objects are used by the implementation to represent
597 ``pseudo-compiled'' executable Python code such as a function body.
598 They differ from function objects because they don't contain a
599 reference to their global execution environment. Code objects are
600 returned by the built-in
\code{compile()
} function and can be
601 extracted from function objects through their
\code{func_code
}
603 \bifuncindex{compile
}
606 A code object can be executed or evaluated by passing it (instead of a
607 source string) to the
\code{exec
} statement or the built-in
608 \code{eval()
} function.
612 (See the Python Reference Manual for more info.)
614 \subsubsection{Type Objects
}
616 Type objects represent the various object types. An object's type is
617 accessed by the built-in function
\code{type()
}. There are no special
618 operations on types. The standard module
\code{types
} defines names
619 for all standard built-in types.
623 Types are written like this:
\code{<type 'int'>
}.
625 \subsubsection{The Null Object
}
627 This object is returned by functions that don't explicitly return a
628 value. It supports no special operations. There is exactly one null
629 object, named
\code{None
} (a built-in name).
631 It is written as
\code{None
}.
633 \subsubsection{File Objects
}
635 File objects are implemented using
\C{}'s
\code{stdio
} package and can be
636 created with the built-in function
\code{open()
} described under
637 Built-in Functions below. They are also returned by some other
638 built-in functions and methods, e.g.\
\code{posix.popen()
} and
639 \code{posix.fdopen()
} and the
\code{makefile()
} method of socket
644 \bifuncindex{makefile
}
646 When a file operation fails for an I/O-related reason, the exception
647 \code{IOError
} is raised. This includes situations where the
648 operation is not defined for some reason, like
\code{seek()
} on a tty
649 device or writing a file opened for reading.
651 Files have the following methods:
654 \renewcommand{\indexsubitem}{(file method)
}
656 \begin{funcdesc
}{close
}{}
657 Close the file. A closed file cannot be read or written anymore.
660 \begin{funcdesc
}{flush
}{}
661 Flush the internal buffer, like
\code{stdio
}'s
\code{fflush()
}.
664 \begin{funcdesc
}{isatty
}{}
665 Return
\code{1} if the file is connected to a tty(-like) device, else
669 \begin{funcdesc
}{read
}{\optional{size
}}
670 Read at most
\var{size
} bytes from the file (less if the read hits
671 \EOF{} or no more data is immediately available on a pipe, tty or
672 similar device). If the
\var{size
} argument is negative or omitted,
673 read all data until
\EOF{} is reached. The bytes are returned as a string
674 object. An empty string is returned when
\EOF{} is encountered
675 immediately. (For certain files, like ttys, it makes sense to
676 continue reading after an
\EOF{} is hit.)
679 \begin{funcdesc
}{readline
}optional
{size
}}
680 Read one entire line from the file. A trailing newline character is
682 \footnote{The advantage of leaving the newline on is that an empty string
683 can be returned to mean
\EOF{} without being ambiguous. Another
684 advantage is that (in cases where it might matter, e.g. if you
685 want to make an exact copy of a file while scanning its lines)
686 you can tell whether the last line of a file ended in a newline
687 or not (yes this happens!).
}
688 (but may be absent when a file ends with an
689 incomplete line). If thevar
{size
} argument is present and
690 non-negative, it is a maximum byte count (including the trailing
691 newline) and an incomplete line may be returned.
692 An empty string is returned when
\EOF{} is hit
693 immediately. Note: unlike
\code{stdio
}'s
\code{fgets()
}, the returned
694 string contains null characters (
\code{'
\e 0'
}) if they occurred in the
698 \begin{funcdesc
}{readlines
}{}
699 Read until
\EOF{} using
\code{readline()
} and return a list containing
703 \begin{funcdesc
}{seek
}{offset\, whence
}
704 Set the file's current position, like
\code{stdio
}'s
\code{fseek()
}.
705 The
\var{whence
} argument is optional and defaults to
\code{0}
706 (absolute file positioning); other values are
\code{1} (seek
707 relative to the current position) and
\code{2} (seek relative to the
708 file's end). There is no return value.
711 \begin{funcdesc
}{tell
}{}
712 Return the file's current position, like
\code{stdio
}'s
\code{ftell()
}.
715 \begin{funcdesc
}{write
}{str
}
716 Write a string to the file. There is no return value.
719 \begin{funcdesc
}{writelines
}{list
}
720 Write a list of strings to the file. There is no return value.
721 (The name is intended to match
\code{readlines
};
\code{writelines
}
722 does not add line separators.)
725 \subsubsection{Internal Objects
}
727 (See the Python Reference Manual for these.)
729 \subsection{Special Attributes
}
731 The implementation adds a few special read-only attributes to several
732 object types, where they are relevant:
737 \code{\var{x
}.__dict__
} is a dictionary of some sort used to store an
738 object's (writable) attributes;
741 \code{\var{x
}.__methods__
} lists the methods of many built-in object types,
742 e.g.,
\code{[].__methods__
} yields
743 \code{['append', 'count', 'index', 'insert', 'remove', 'reverse', 'sort'
]};
746 \code{\var{x
}.__members__
} lists data attributes;
749 \code{\var{x
}.__class__
} is the class to which a class instance belongs;
752 \code{\var{x
}.__bases__
} is the tuple of base classes of a class object.
