1 \section{Built-in Types
\label{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{`
\textrm{\ldots}`
} notation). The latter
13 conversion is implicitly used when an object is written by the
14 \keyword{print
}\stindex{print
} statement.
17 \subsection{Truth Value Testing
\label{truth
}}
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.
21 The following values are considered false:
24 \indexii{truth
}{value
}
25 \indexii{Boolean
}{operations
}
31 \withsubitem{(Built-in object)
}{\ttindex{None
}}
33 \item zero of any numeric type, for example,
\code{0},
\code{0L},
34 \code{0.0},
\code{0j
}.
36 \item any empty sequence, for example,
\code{''
},
\code{()
},
\code{[]}.
38 \item any empty mapping, for example,
\code{\
{\
}}.
40 \item instances of user-defined classes, if the class defines a
41 \method{__nonzero__()
} or
\method{__len__()
} method, when that
42 method returns zero.
\footnote{Additional information on these
43 special methods may be found in the
\citetitle[../ref/ref.html
]{Python
48 All other values are considered true --- so objects of many types are
52 Operations and built-in functions that have a Boolean result always
53 return
\code{0} for false and
\code{1} for true, unless otherwise
54 stated. (Important exception: the Boolean operations
55 \samp{or
}\opindex{or
} and
\samp{and
}\opindex{and
} always return one of
59 \subsection{Boolean Operations
\label{boolean
}}
61 These are the Boolean operations, ordered by ascending priority:
62 \indexii{Boolean
}{operations
}
64 \begin{tableiii
}{c|l|c
}{code
}{Operation
}{Result
}{Notes
}
65 \lineiii{\var{x
} or
\var{y
}}
66 {if
\var{x
} is false, then
\var{y
}, else
\var{x
}}{(
1)
}
67 \lineiii{\var{x
} and
\var{y
}}
68 {if
\var{x
} is false, then
\var{x
}, else
\var{y
}}{(
1)
}
71 {if
\var{x
} is false, then
\code{1}, else
\code{0}}{(
2)
}
83 These only evaluate their second argument if needed for their outcome.
86 \samp{not
} has a lower priority than non-Boolean operators, so
87 \code{not
\var{a
} ==
\var{b
}} is interpreted as
\code{not (
\var{a
} ==
88 \var{b
})
}, and
\code{\var{a
} == not
\var{b
}} is a syntax error.
93 \subsection{Comparisons
\label{comparisons
}}
95 Comparison operations are supported by all objects. They all have the
96 same priority (which is higher than that of the Boolean operations).
97 Comparisons can be chained arbitrarily; for example,
\code{\var{x
} <
98 \var{y
} <=
\var{z
}} is equivalent to
\code{\var{x
} <
\var{y
} and
99 \var{y
} <=
\var{z
}}, except that
\var{y
} is evaluated only once (but
100 in both cases
\var{z
} is not evaluated at all when
\code{\var{x
} <
101 \var{y
}} is found to be false).
102 \indexii{chaining
}{comparisons
}
104 This table summarizes the comparison operations:
106 \begin{tableiii
}{c|l|c
}{code
}{Operation
}{Meaning
}{Notes
}
107 \lineiii{<
}{strictly less than
}{}
108 \lineiii{<=
}{less than or equal
}{}
109 \lineiii{>
}{strictly greater than
}{}
110 \lineiii{>=
}{greater than or equal
}{}
111 \lineiii{==
}{equal
}{}
112 \lineiii{!=
}{not equal
}{(
1)
}
113 \lineiii{<>
}{not equal
}{(
1)
}
114 \lineiii{is
}{object identity
}{}
115 \lineiii{is not
}{negated object identity
}{}
117 \indexii{operator
}{comparison
}
118 \opindex{==
} % XXX *All* others have funny characters < ! >
128 \code{<>
} and
\code{!=
} are alternate spellings for the same operator.
129 (I couldn't choose between
\ABC{} and C! :-)
130 \index{ABC language@
\ABC{} language
}
131 \index{language!ABC@
\ABC{}}
132 \indexii{C
}{language
}
133 \code{!=
} is the preferred spelling;
\code{<>
} is obsolescent.
137 Objects of different types, except different numeric types, never
138 compare equal; such objects are ordered consistently but arbitrarily
139 (so that sorting a heterogeneous array yields a consistent result).
140 Furthermore, some types (for example, file objects) support only a
141 degenerate notion of comparison where any two objects of that type are
142 unequal. Again, such objects are ordered arbitrarily but
144 \indexii{object
}{numeric
}
145 \indexii{objects
}{comparing
}
147 Instances of a class normally compare as non-equal unless the class
148 \withsubitem{(instance method)
}{\ttindex{__cmp__()
}}
149 defines the
\method{__cmp__()
} method. Refer to the
150 \citetitle[../ref/customization.html
]{Python Reference Manual
} for
151 information on the use of this method to effect object comparisons.
153 \strong{Implementation note:
} Objects of different types except
154 numbers are ordered by their type names; objects of the same types
155 that don't support proper comparison are ordered by their address.
157 Two more operations with the same syntactic priority,
158 \samp{in
}\opindex{in
} and
\samp{not in
}\opindex{not in
}, are supported
159 only by sequence types (below).
162 \subsection{Numeric Types
\label{typesnumeric
}}
164 There are four numeric types:
\dfn{plain integers
},
\dfn{long integers
},
165 \dfn{floating point numbers
}, and
\dfn{complex numbers
}.
166 Plain integers (also just called
\dfn{integers
})
167 are implemented using
\ctype{long
} in C, which gives them at least
32
168 bits of precision. Long integers have unlimited precision. Floating
169 point numbers are implemented using
\ctype{double
} in C. All bets on
170 their precision are off unless you happen to know the machine you are
174 \obindex{long integer
}
175 \obindex{floating point
}
176 \obindex{complex number
}
177 \indexii{C
}{language
}
179 Complex numbers have a real and imaginary part, which are both
180 implemented using
\ctype{double
} in C. To extract these parts from
181 a complex number
\var{z
}, use
\code{\var{z
}.real
} and
\code{\var{z
}.imag
}.
183 Numbers are created by numeric literals or as the result of built-in
184 functions and operators. Unadorned integer literals (including hex
185 and octal numbers) yield plain integers. Integer literals with an
186 \character{L
} or
\character{l
} suffix yield long integers
187 (
\character{L
} is preferred because
\samp{1l} looks too much like
188 eleven!). Numeric literals containing a decimal point or an exponent
189 sign yield floating point numbers. Appending
\character{j
} or
190 \character{J
} to a numeric literal yields a complex number.
191 \indexii{numeric
}{literals
}
192 \indexii{integer
}{literals
}
193 \indexiii{long
}{integer
}{literals
}
194 \indexii{floating point
}{literals
}
195 \indexii{complex number
}{literals
}
196 \indexii{hexadecimal
}{literals
}
197 \indexii{octal
}{literals
}
199 Python fully supports mixed arithmetic: when a binary arithmetic
200 operator has operands of different numeric types, the operand with the
201 ``smaller'' type is converted to that of the other, where plain
202 integer is smaller than long integer is smaller than floating point is
203 smaller than complex.
204 Comparisons between numbers of mixed type use the same rule.
\footnote{
205 As a consequence, the list
\code{[1,
2]} is considered equal
206 to
\code{[1.0,
2.0]}, and similar for tuples.
207 } The functions
\function{int()
},
\function{long()
},
\function{float()
},
208 and
\function{complex()
} can be used
209 to coerce numbers to a specific type.
214 \bifuncindex{complex
}
216 All numeric types support the following operations, sorted by
217 ascending priority (operations in the same box have the same
218 priority; all numeric operations have a higher priority than
219 comparison operations):
221 \begin{tableiii
}{c|l|c
}{code
}{Operation
}{Result
}{Notes
}
222 \lineiii{\var{x
} +
\var{y
}}{sum of
\var{x
} and
\var{y
}}{}
223 \lineiii{\var{x
} -
\var{y
}}{difference of
\var{x
} and
\var{y
}}{}
225 \lineiii{\var{x
} *
\var{y
}}{product of
\var{x
} and
\var{y
}}{}
226 \lineiii{\var{x
} /
\var{y
}}{quotient of
\var{x
} and
\var{y
}}{(
1)
}
227 \lineiii{\var{x
} \%
{} \var{y
}}{remainder of
\code{\var{x
} /
\var{y
}}}{}
229 \lineiii{-
\var{x
}}{\var{x
} negated
}{}
230 \lineiii{+
\var{x
}}{\var{x
} unchanged
}{}
232 \lineiii{abs(
\var{x
})
}{absolute value or magnitude of
\var{x
}}{}
233 \lineiii{int(
\var{x
})
}{\var{x
} converted to integer
}{(
2)
}
234 \lineiii{long(
\var{x
})
}{\var{x
} converted to long integer
}{(
2)
}
235 \lineiii{float(
\var{x
})
}{\var{x
} converted to floating point
}{}
236 \lineiii{complex(
\var{re
},
\var{im
})
}{a complex number with real part
\var{re
}, imaginary part
\var{im
}.
\var{im
} defaults to zero.
}{}
237 \lineiii{\var{c
}.conjugate()
}{conjugate of the complex number
\var{c
}}{}
238 \lineiii{divmod(
\var{x
},
\var{y
})
}{the pair
\code{(
\var{x
} /
\var{y
},
\var{x
} \%
{} \var{y
})
}}{(
3)
}
239 \lineiii{pow(
\var{x
},
\var{y
})
}{\var{x
} to the power
\var{y
}}{}
240 \lineiii{\var{x
} **
\var{y
}}{\var{x
} to the power
\var{y
}}{}
242 \indexiii{operations on
}{numeric
}{types
}
243 \withsubitem{(complex number method)
}{\ttindex{conjugate()
}}
250 For (plain or long) integer division, the result is an integer.
251 The result is always rounded towards minus infinity:
1/
2 is
0,
252 (-
1)/
2 is -
1,
1/(-
2) is -
1, and (-
1)/(-
2) is
0. Note that the result
253 is a long integer if either operand is a long integer, regardless of
255 \indexii{integer
}{division
}
256 \indexiii{long
}{integer
}{division
}
259 Conversion from floating point to (long or plain) integer may round or
260 truncate as in C; see functions
\function{floor()
} and
261 \function{ceil()
} in the
\refmodule{math
}\refbimodindex{math
} module
262 for well-defined conversions.
263 \withsubitem{(in module math)
}{\ttindex{floor()
}\ttindex{ceil()
}}
264 \indexii{numeric
}{conversions
}
265 \indexii{C
}{language
}
268 See section
\ref{built-in-funcs
}, ``Built-in Functions,'' for a full
272 % XXXJH exceptions: overflow (when? what operations?) zerodivision
274 \subsubsection{Bit-string Operations on Integer Types
\label{bitstring-ops
}}
275 \nodename{Bit-string Operations
}
277 Plain and long integer types support additional operations that make
278 sense only for bit-strings. Negative numbers are treated as their
2's
279 complement value (for long integers, this assumes a sufficiently large
280 number of bits that no overflow occurs during the operation).
282 The priorities of the binary bit-wise operations are all lower than
283 the numeric operations and higher than the comparisons; the unary
284 operation
\samp{\~
} has the same priority as the other unary numeric
285 operations (
\samp{+
} and
\samp{-
}).
287 This table lists the bit-string operations sorted in ascending
288 priority (operations in the same box have the same priority):
290 \begin{tableiii
}{c|l|c
}{code
}{Operation
}{Result
}{Notes
}
291 \lineiii{\var{x
} |
\var{y
}}{bitwise
\dfn{or
} of
\var{x
} and
\var{y
}}{}
292 \lineiii{\var{x
} \^
{} \var{y
}}{bitwise
\dfn{exclusive or
} of
\var{x
} and
\var{y
}}{}
293 \lineiii{\var{x
} \&
{} \var{y
}}{bitwise
\dfn{and
} of
\var{x
} and
\var{y
}}{}
294 \lineiii{\var{x
} <<
\var{n
}}{\var{x
} shifted left by
\var{n
} bits
}{(
1), (
2)
}
295 \lineiii{\var{x
} >>
\var{n
}}{\var{x
} shifted right by
\var{n
} bits
}{(
1), (
3)
}
297 \lineiii{\~
\var{x
}}{the bits of
\var{x
} inverted
}{}
299 \indexiii{operations on
}{integer
}{types
}
300 \indexii{bit-string
}{operations
}
301 \indexii{shifting
}{operations
}
302 \indexii{masking
}{operations
}
307 \item[(
1)
] Negative shift counts are illegal and cause a
308 \exception{ValueError
} to be raised.
309 \item[(
2)
] A left shift by
\var{n
} bits is equivalent to
310 multiplication by
\code{pow(
2,
\var{n
})
} without overflow check.
311 \item[(
3)
] A right shift by
\var{n
} bits is equivalent to
312 division by
\code{pow(
2,
\var{n
})
} without overflow check.
316 \subsection{Sequence Types
\label{typesseq
}}
318 There are six sequence types: strings, Unicode strings, lists,
319 tuples, buffers, and xrange objects.
321 Strings literals are written in single or double quotes:
322 \code{'xyzzy'
},
\code{"frobozz"
}. See chapter
2 of the
323 \citetitle[../ref/strings.html
]{Python Reference Manual
} for more about
324 string literals. Unicode strings are much like strings, but are
325 specified in the syntax using a preceeding
\character{u
} character:
326 \code{u'abc'
},
\code{u"def"
}. Lists are constructed with square brackets,
327 separating items with commas:
\code{[a, b, c
]}. Tuples are
328 constructed by the comma operator (not within square brackets), with
329 or without enclosing parentheses, but an empty tuple must have the
330 enclosing parentheses, e.g.,
\code{a, b, c
} or
\code{()
}. A single
331 item tuple must have a trailing comma, e.g.,
\code{(d,)
}. Buffers are
332 not directly supported by Python syntax, but can be created by calling the
333 builtin function
\function{buffer()
}.
\bifuncindex{buffer
} XRanges
334 objects are similar to buffers in that there is no specific syntax to
335 create them, but they are created using the
\function{xrange()
}
336 function.
\bifuncindex{xrange
}
345 Sequence types support the following operations. The
\samp{in
} and
346 \samp{not in
} operations have the same priorities as the comparison
347 operations. The
\samp{+
} and
\samp{*
} operations have the same
348 priority as the corresponding numeric operations.
\footnote{They must
349 have since the parser can't tell the type of the operands.
}
351 This table lists the sequence operations sorted in ascending priority
352 (operations in the same box have the same priority). In the table,
353 \var{s
} and
\var{t
} are sequences of the same type;
\var{n
},
\var{i
}
354 and
\var{j
} are integers:
356 \begin{tableiii
}{c|l|c
}{code
}{Operation
}{Result
}{Notes
}
357 \lineiii{\var{x
} in
\var{s
}}{\code{1} if an item of
\var{s
} is equal to
\var{x
}, else
\code{0}}{}
358 \lineiii{\var{x
} not in
\var{s
}}{\code{0} if an item of
\var{s
} is
359 equal to
\var{x
}, else
\code{1}}{}
361 \lineiii{\var{s
} +
\var{t
}}{the concatenation of
\var{s
} and
\var{t
}}{}
362 \lineiii{\var{s
} *
\var{n
}\textrm{,
} \var{n
} *
\var{s
}}{\var{n
} copies of
\var{s
} concatenated
}{(
1)
}
364 \lineiii{\var{s
}[\var{i
}]}{\var{i
}'th item of
\var{s
}, origin
0}{(
2)
}
365 \lineiii{\var{s
}[\var{i
}:
\var{j
}]}{slice of
\var{s
} from
\var{i
} to
\var{j
}}{(
2), (
3)
}
367 \lineiii{len(
\var{s
})
}{length of
\var{s
}}{}
368 \lineiii{min(
\var{s
})
}{smallest item of
\var{s
}}{}
369 \lineiii{max(
\var{s
})
}{largest item of
\var{s
}}{}
371 \indexiii{operations on
}{sequence
}{types
}
375 \indexii{concatenation
}{operation
}
376 \indexii{repetition
}{operation
}
377 \indexii{subscript
}{operation
}
378 \indexii{slice
}{operation
}
386 \item[(
1)
] Values of
\var{n
} less than
\code{0} are treated as
387 \code{0} (which yields an empty sequence of the same type as
390 \item[(
2)
] If
\var{i
} or
\var{j
} is negative, the index is relative to
391 the end of the string, i.e.,
\code{len(
\var{s
}) +
\var{i
}} or
392 \code{len(
\var{s
}) +
\var{j
}} is substituted. But note that
\code{-
0} is
395 \item[(
3)
] The slice of
\var{s
} from
\var{i
} to
\var{j
} is defined as
396 the sequence of items with index
\var{k
} such that
\code{\var{i
} <=
397 \var{k
} <
\var{j
}}. If
\var{i
} or
\var{j
} is greater than
398 \code{len(
\var{s
})
}, use
\code{len(
\var{s
})
}. If
\var{i
} is omitted,
399 use
\code{0}. If
\var{j
} is omitted, use
\code{len(
\var{s
})
}. If
400 \var{i
} is greater than or equal to
\var{j
}, the slice is empty.
404 \subsubsection{String Methods
\label{string-methods
}}
406 These are the string methods which both
8-bit strings and Unicode
409 \begin{methoddesc
}[string
]{capitalize
}{}
410 Return a copy of the string with only its first character capitalized.
413 \begin{methoddesc
}[string
]{center
}{width
}
414 Return centered in a string of length
\var{width
}. Padding is done
418 \begin{methoddesc
}[string
]{count
}{sub
\optional{, start
\optional{, end
}}}
419 Return the number of occurrences of substring
\var{sub
} in string
420 S
\code{[\var{start
}:
\var{end
}]}. Optional arguments
\var{start
} and
421 \var{end
} are interpreted as in slice notation.
424 \begin{methoddesc
}[string
]{encode
}{\optional{encoding
\optional{,errors
}}}
425 Return an encoded version of the string. Default encoding is the current
426 default string encoding.
\var{errors
} may be given to set a different
427 error handling scheme. The default for
\var{errors
} is
428 \code{'strict'
}, meaning that encoding errors raise a
429 \exception{ValueError
}. Other possible values are
\code{'ignore'
} and
434 \begin{methoddesc
}[string
]{endswith
}{suffix
\optional{, start
\optional{, end
}}}
435 Return true if the string ends with the specified
\var{suffix
},
436 otherwise return false. With optional
\var{start
}, test beginning at
437 that position. With optional
\var{end
}, stop comparing at that position.
440 \begin{methoddesc
}[string
]{expandtabs
}{\optional{tabsize
}}
441 Return a copy of the string where all tab characters are expanded
442 using spaces. If
\var{tabsize
} is not given, a tab size of
\code{8}
443 characters is assumed.
446 \begin{methoddesc
}[string
]{find
}{sub
\optional{, start
\optional{, end
}}}
447 Return the lowest index in the string where substring
\var{sub
} is
448 found, such that
\var{sub
} is contained in the range
[\var{start
},
449 \var{end
}). Optional arguments
\var{start
} and
\var{end
} are
450 interpreted as in slice notation. Return
\code{-
1} if
\var{sub
} is
454 \begin{methoddesc
}[string
]{index
}{sub
\optional{, start
\optional{, end
}}}
455 Like
\method{find()
}, but raise
\exception{ValueError
} when the
456 substring is not found.
459 \begin{methoddesc
}[string
]{isalnum
}{}
460 Return true if all characters in the string are alphanumeric and there
461 is at least one character, false otherwise.
464 \begin{methoddesc
}[string
]{isalpha
}{}
465 Return true if all characters in the string are alphabetic and there
466 is at least one character, false otherwise.
469 \begin{methoddesc
}[string
]{isdigit
}{}
470 Return true if there are only digit characters, false otherwise.
473 \begin{methoddesc
}[string
]{islower
}{}
474 Return true if all cased characters in the string are lowercase and
475 there is at least one cased character, false otherwise.
478 \begin{methoddesc
}[string
]{isspace
}{}
479 Return true if there are only whitespace characters in the string and
480 the string is not empty, false otherwise.
483 \begin{methoddesc
}[string
]{istitle
}{}
484 Return true if the string is a titlecased string, i.e.\ uppercase
485 characters may only follow uncased characters and lowercase characters
486 only cased ones. Return false otherwise.
489 \begin{methoddesc
}[string
]{isupper
}{}
490 Return true if all cased characters in the string are uppercase and
491 there is at least one cased character, false otherwise.
494 \begin{methoddesc
}[string
]{join
}{seq
}
495 Return a string which is the concatenation of the strings in the
496 sequence
\var{seq
}. The separator between elements is the string
497 providing this method.
500 \begin{methoddesc
}[string
]{ljust
}{width
}
501 Return the string left justified in a string of length
\var{width
}.
502 Padding is done using spaces. The original string is returned if
503 \var{width
} is less than
\code{len(
\var{s
})
}.
506 \begin{methoddesc
}[string
]{lower
}{}
507 Return a copy of the string converted to lowercase.
510 \begin{methoddesc
}[string
]{lstrip
}{}
511 Return a copy of the string with leading whitespace removed.
514 \begin{methoddesc
}[string
]{replace
}{old, new
\optional{, maxsplit
}}
515 Return a copy of the string with all occurrences of substring
516 \var{old
} replaced by
\var{new
}. If the optional argument
517 \var{maxsplit
} is given, only the first
\var{maxsplit
} occurrences are
521 \begin{methoddesc
}[string
]{rfind
}{sub
\optional{,start
\optional{,end
}}}
522 Return the highest index in the string where substring
\var{sub
} is
523 found, such that
\var{sub
} is contained within s
[start,end
]. Optional
524 arguments
\var{start
} and
\var{end
} are interpreted as in slice
525 notation. Return
\code{-
1} on failure.
528 \begin{methoddesc
}[string
]{rindex
}{sub
\optional{, start
\optional{, end
}}}
529 Like
\method{rfind()
} but raises
\exception{ValueError
} when the
530 substring
\var{sub
} is not found.
533 \begin{methoddesc
}[string
]{rjust
}{width
}
534 Return the string right justified in a string of length
\var{width
}.
535 Padding is done using spaces. The original string is returned if
536 \var{width
} is less than
\code{len(
\var{s
})
}.
539 \begin{methoddesc
}[string
]{rstrip
}{}
540 Return a copy of the string with trailing whitespace removed.
543 \begin{methoddesc
}[string
]{split
}{\optional{sep
\optional{,maxsplit
}}}
544 Return a list of the words in the string, using
\var{sep
} as the
545 delimiter string. If
\var{maxsplit
} is given, at most
\var{maxsplit
}
546 splits are done. If
\var{sep
} is not specified or
\code{None
}, any
547 whitespace string is a separator.
550 \begin{methoddesc
}[string
]{splitlines
}{\optional{keepends
}}
551 Return a list of the lines in the string, breaking at line
552 boundaries. Line breaks are not included in the resulting list unless
553 \var{keepends
} is given and true.
556 \begin{methoddesc
}[string
]{startswith
}{prefix
\optional{, start
\optional{, end
}}}
557 Return true if string starts with the
\var{prefix
}, otherwise
558 return false. With optional
\var{start
}, test string beginning at
559 that position. With optional
\var{end
}, stop comparing string at that
563 \begin{methoddesc
}[string
]{strip
}{}
564 Return a copy of the string with leading and trailing whitespace
568 \begin{methoddesc
}[string
]{swapcase
}{}
569 Return a copy of the string with uppercase characters converted to
570 lowercase and vice versa.
573 \begin{methoddesc
}[string
]{title
}{}
574 Return a titlecased version of, i.e.\ words start with uppercase
575 characters, all remaining cased characters are lowercase.
578 \begin{methoddesc
}[string
]{translate
}{table
\optional{, deletechars
}}
579 Return a copy of the string where all characters occurring in the
580 optional argument
\var{deletechars
} are removed, and the remaining
581 characters have been mapped through the given translation table, which
582 must be a string of length
256.
585 \begin{methoddesc
}[string
]{upper
}{}
586 Return a copy of the string converted to uppercase.
590 \subsubsection{String Formatting Operations
\label{typesseq-strings
}}
592 \index{formatting, string
}
593 \index{string!formatting
}
594 \index{printf-style formatting
}
595 \index{sprintf-style formatting
}
597 String and Unicode objects have one unique built-in operation: the
598 \code{\%
} operator (modulo). Given
\code{\var{format
} \%
599 \var{values
}} (where
\var{format
} is a string or Unicode object),
600 \code{\%
} conversion specifications in
\var{format
} are replaced with
601 zero or more elements of
\var{values
}. The effect is similar to the
602 using
\cfunction{sprintf()
} in the C language. If
\var{format
} is a
603 Unicode object, or if any of the objects being converted using the
604 \code{\%s
} conversion are Unicode objects, the result will be a
605 Unicode object as well.
607 If
\var{format
} requires a single argument,
\var{values
} may be a
608 single non-tuple object.
\footnote{A tuple object in this case should
609 be a singleton.
} Otherwise,
\var{values
} must be a tuple with
610 exactly the number of items specified by the format string, or a
611 single mapping object (for example, a dictionary).
613 A conversion specifier contains two or more characters and has the
614 following components, which must occur in this order:
617 \item The
\character{\%
} character, which marks the start of the
619 \item Mapping key value (optional), consisting of an identifier in
620 parentheses (for example,
\code{(somename)
}).
621 \item Conversion flags (optional), which affect the result of some
623 \item Minimum field width (optional). If specified as an
624 \character{*
} (asterisk), the actual width is read from the
625 next element of the tuple in
\var{values
}, and the object to
626 convert comes after the minimum field width and optional
628 \item Precision (optional), given as a
\character{.
} (dot) followed
629 by the precision. If specified as
\character{*
} (an
630 asterisk), the actual width is read from the next element of
631 the tuple in
\var{values
}, and the value to convert comes after
633 \item Length modifier (optional).
634 \item Conversion type.
637 If the right argument is a dictionary (or any kind of mapping), then
638 the formats in the string
\emph{must
} have a parenthesized key into
639 that dictionary inserted immediately after the
\character{\%
}
640 character, and each format formats the corresponding entry from the
641 mapping. For example:
645 >>> language = 'Python'
646 >>> print '
%(language)s has %(count)03d quote types.' % vars()
647 Python has
002 quote types.
650 In this case no
\code{*
} specifiers may occur in a format (since they
651 require a sequential parameter list).
653 The conversion flag characters are:
655 \begin{tableii
}{c|l
}{character
}{Flag
}{Meaning
}
656 \lineii{\#
}{The value conversion will use the ``alternate form''
657 (where defined below).
}
658 \lineii{0}{The conversion will be zero padded.
}
659 \lineii{-
}{The converted value is left adjusted (overrides
661 \lineii{{~
}}{(a space) A blank should be left before a positive number
662 (or empty string) produced by a signed conversion.
}
663 \lineii{+
}{A sign character (
\character{+
} or
\character{-
}) will
664 precede the conversion (overrides a "space" flag).
}
667 The length modifier may be
\code{h
},
\code{l
}, and
\code{L
} may be
668 present, but are ignored as they are not necessary for Python.
670 The conversion types are:
672 \begin{tableii
}{c|l
}{character
}{Conversion
}{Meaning
}
673 \lineii{d
}{Signed integer decimal.
}
674 \lineii{i
}{Signed integer decimal.
}
675 \lineii{o
}{Unsigned octal.
}
676 \lineii{u
}{Unsigned decimal.
}
677 \lineii{x
}{Unsigned hexidecimal (lowercase).
}
678 \lineii{X
}{Unsigned hexidecimal (uppercase).
}
679 \lineii{e
}{Floating point exponential format (lowercase).
}
680 \lineii{E
}{Floating point exponential format (uppercase).
}
681 \lineii{f
}{Floating point decimal format.
}
682 \lineii{F
}{Floating point decimal format.
}
683 \lineii{g
}{Same as
\character{e
} if exponent is greater than -
4 or
684 less than precision,
\character{f
} otherwise.
}
685 \lineii{G
}{Same as
\character{E
} if exponent is greater than -
4 or
686 less than precision,
\character{F
} otherwise.
}
687 \lineii{c
}{Single character (accepts integer or single character
689 \lineii{r
}{String (converts any python object using
691 \lineii{s
}{String (converts any python object using
693 \lineii{\%
}{No argument is converted, results in a
\character{\%
}
694 character in the result. (The complete specification is
701 Since Python strings have an explicit length,
\code{\%s
} conversions
702 do not assume that
\code{'
\e0'
} is the end of the string.
704 For safety reasons, floating point precisions are clipped to
50;
705 \code{\%f
} conversions for numbers whose absolute value is over
1e25
706 are replaced by
\code{\%g
} conversions.
\footnote{
707 These numbers are fairly arbitrary. They are intended to
708 avoid printing endless strings of meaningless digits without hampering
709 correct use and without having to know the exact precision of floating
710 point values on a particular machine.
711 } All other errors raise exceptions.
713 Additional string operations are defined in standard module
714 \refmodule{string
} and in built-in module
\refmodule{re
}.
715 \refstmodindex{string
}
719 \subsubsection{XRange Type
\label{typesseq-xrange
}}
721 The xrange
\obindex{xrange
} type is an immutable sequence which is
722 commonly used for looping. The advantage of the xrange type is that an
723 xrange object will always take the same amount of memory, no matter the
724 size of the range it represents. There are no consistent performance
727 XRange objects behave like tuples, and offer a single method:
729 \begin{methoddesc
}[xrange
]{tolist
}{}
730 Return a list object which represents the same values as the xrange
735 \subsubsection{Mutable Sequence Types
\label{typesseq-mutable
}}
737 List objects support additional operations that allow in-place
738 modification of the object.
739 These operations would be supported by other mutable sequence types
740 (when added to the language) as well.
741 Strings and tuples are immutable sequence types and such objects cannot
742 be modified once created.
743 The following operations are defined on mutable sequence types (where
744 \var{x
} is an arbitrary object):
745 \indexiii{mutable
}{sequence
}{types
}
748 \begin{tableiii
}{c|l|c
}{code
}{Operation
}{Result
}{Notes
}
749 \lineiii{\var{s
}[\var{i
}] =
\var{x
}}
750 {item
\var{i
} of
\var{s
} is replaced by
\var{x
}}{}
751 \lineiii{\var{s
}[\var{i
}:
\var{j
}] =
\var{t
}}
752 {slice of
\var{s
} from
\var{i
} to
\var{j
} is replaced by
\var{t
}}{}
753 \lineiii{del
\var{s
}[\var{i
}:
\var{j
}]}
754 {same as
\code{\var{s
}[\var{i
}:
\var{j
}] =
[]}}{}
755 \lineiii{\var{s
}.append(
\var{x
})
}
756 {same as
\code{\var{s
}[len(
\var{s
}):len(
\var{s
})
] =
[\var{x
}]}}{(
1)
}
757 \lineiii{\var{s
}.extend(
\var{x
})
}
758 {same as
\code{\var{s
}[len(
\var{s
}):len(
\var{s
})
] =
\var{x
}}}{(
2)
}
759 \lineiii{\var{s
}.count(
\var{x
})
}
760 {return number of
\var{i
}'s for which
\code{\var{s
}[\var{i
}] ==
\var{x
}}}{}
761 \lineiii{\var{s
}.index(
\var{x
})
}
762 {return smallest
\var{i
} such that
\code{\var{s
}[\var{i
}] ==
\var{x
}}}{(
3)
}
763 \lineiii{\var{s
}.insert(
\var{i
},
\var{x
})
}
764 {same as
\code{\var{s
}[\var{i
}:
\var{i
}] =
[\var{x
}]}
765 if
\code{\var{i
} >=
0}}{}
766 \lineiii{\var{s
}.pop(
\optional{\var{i
}})
}
767 {same as
\code{\var{x
} =
\var{s
}[\var{i
}]; del
\var{s
}[\var{i
}]; return
\var{x
}}}{(
4)
}
768 \lineiii{\var{s
}.remove(
\var{x
})
}
769 {same as
\code{del
\var{s
}[\var{s
}.index(
\var{x
})
]}}{(
3)
}
770 \lineiii{\var{s
}.reverse()
}
771 {reverses the items of
\var{s
} in place
}{(
5)
}
772 \lineiii{\var{s
}.sort(
\optional{\var{cmpfunc
}})
}
773 {sort the items of
\var{s
} in place
}{(
5), (
6)
}
775 \indexiv{operations on
}{mutable
}{sequence
}{types
}
776 \indexiii{operations on
}{sequence
}{types
}
777 \indexiii{operations on
}{list
}{type
}
778 \indexii{subscript
}{assignment
}
779 \indexii{slice
}{assignment
}
781 \withsubitem{(list method)
}{
782 \ttindex{append()
}\ttindex{extend()
}\ttindex{count()
}\ttindex{index()
}
783 \ttindex{insert()
}\ttindex{pop()
}\ttindex{remove()
}\ttindex{reverse()
}
788 \item[(
1)
] The C implementation of Python has historically accepted
789 multiple parameters and implicitly joined them into a tuple; this
790 no longer works in Python
2.0. Use of this misfeature has been
791 deprecated since Python
1.4.
793 \item[(
2)
] Raises an exception when
\var{x
} is not a list object. The
794 \method{extend()
} method is experimental and not supported by
795 mutable sequence types other than lists.
797 \item[(
3)
] Raises
\exception{ValueError
} when
\var{x
} is not found in
800 \item[(
4)
] The
\method{pop()
} method is only supported by the list and
801 array types. The optional argument
\var{i
} defaults to
\code{-
1},
802 so that by default the last item is removed and returned.
804 \item[(
5)
] The
\method{sort()
} and
\method{reverse()
} methods modify the
805 list in place for economy of space when sorting or reversing a large
806 list. They don't return the sorted or reversed list to remind you
809 \item[(
6)
] The
\method{sort()
} method takes an optional argument
810 specifying a comparison function of two arguments (list items) which
811 should return
\code{-
1},
\code{0} or
\code{1} depending on whether
812 the first argument is considered smaller than, equal to, or larger
813 than the second argument. Note that this slows the sorting process
814 down considerably; e.g. to sort a list in reverse order it is much
815 faster to use calls to the methods
\method{sort()
} and
816 \method{reverse()
} than to use the built-in function
817 \function{sort()
} with a comparison function that reverses the
818 ordering of the elements.
822 \subsection{Mapping Types
\label{typesmapping
}}
826 A
\dfn{mapping
} object maps values of one type (the key type) to
827 arbitrary objects. Mappings are mutable objects. There is currently
828 only one standard mapping type, the
\dfn{dictionary
}. A dictionary's keys are
829 almost arbitrary values. The only types of values not acceptable as
830 keys are values containing lists or dictionaries or other mutable
831 types that are compared by value rather than by object identity.
832 Numeric types used for keys obey the normal rules for numeric
833 comparison: if two numbers compare equal (e.g.
\code{1} and
834 \code{1.0}) then they can be used interchangeably to index the same
837 Dictionaries are created by placing a comma-separated list of
838 \code{\var{key
}:
\var{value
}} pairs within braces, for example:
839 \code{\
{'jack':
4098, 'sjoerd':
4127\
}} or
840 \code{\
{4098: 'jack',
4127: 'sjoerd'\
}}.
842 The following operations are defined on mappings (where
\var{a
} and
843 \var{b
} are mappings,
\var{k
} is a key, and
\var{v
} and
\var{x
} are
845 \indexiii{operations on
}{mapping
}{types
}
846 \indexiii{operations on
}{dictionary
}{type
}
849 \withsubitem{(dictionary method)
}{
859 \begin{tableiii
}{c|l|c
}{code
}{Operation
}{Result
}{Notes
}
860 \lineiii{len(
\var{a
})
}{the number of items in
\var{a
}}{}
861 \lineiii{\var{a
}[\var{k
}]}{the item of
\var{a
} with key
\var{k
}}{(
1)
}
862 \lineiii{\var{a
}[\var{k
}] =
\var{v
}}
863 {set
\code{\var{a
}[\var{k
}]} to
\var{v
}}
865 \lineiii{del
\var{a
}[\var{k
}]}
866 {remove
\code{\var{a
}[\var{k
}]} from
\var{a
}}
868 \lineiii{\var{a
}.clear()
}{remove all items from
\code{a
}}{}
869 \lineiii{\var{a
}.copy()
}{a (shallow) copy of
\code{a
}}{}
870 \lineiii{\var{a
}.has_key(
\var{k
})
}
871 {\code{1} if
\var{a
} has a key
\var{k
}, else
\code{0}}
873 \lineiii{\var{a
}.items()
}
874 {a copy of
\var{a
}'s list of (
\var{key
},
\var{value
}) pairs
}
876 \lineiii{\var{a
}.keys()
}{a copy of
\var{a
}'s list of keys
}{(
2)
}
877 \lineiii{\var{a
}.update(
\var{b
})
}
878 {\code{for k in
\var{b
}.keys():
\var{a
}[k
] =
\var{b
}[k
]}}
880 \lineiii{\var{a
}.values()
}{a copy of
\var{a
}'s list of values
}{(
2)
}
881 \lineiii{\var{a
}.get(
\var{k
}\optional{,
\var{x
}})
}
882 {\code{\var{a
}[\var{k
}]} if
\code{\var{a
}.has_key(
\var{k
})
},
885 \lineiii{\var{a
}.setdefault(
\var{k
}\optional{,
\var{x
}})
}
886 {\code{\var{a
}[\var{k
}]} if
\code{\var{a
}.has_key(
\var{k
})
},
887 else
\var{x
} (also setting it)
}
889 \lineiii{\var{a
}.popitem()
}
890 {remove and return an arbitrary (
\var{key
},
\var{value
}) pair
}
897 \item[(
1)
] Raises a
\exception{KeyError
} exception if
\var{k
} is not
900 \item[(
2)
] Keys and values are listed in random order. If
901 \method{keys()
} and
\method{values()
} are called with no intervening
902 modifications to the dictionary, the two lists will directly
903 correspond. This allows the creation of
\code{(
\var{value
},
904 \var{key
})
} pairs using
\function{map()
}:
\samp{pairs = map(None,
905 \var{a
}.values(),
\var{a
}.keys())
}.
907 \item[(
3)
] \var{b
} must be of the same type as
\var{a
}.
909 \item[(
4)
] Never raises an exception if
\var{k
} is not in the map,
910 instead it returns
\var{x
}.
\var{x
} is optional; when
\var{x
} is not
911 provided and
\var{k
} is not in the map,
\code{None
} is returned.
913 \item[(
5)
] \function{setdefault()
} is like
\function{get()
}, except
914 that if
\var{k
} is missing,
\var{x
} is both returned and inserted into
915 the dictionary as the value of
\var{k
}.
917 \item[(
6)
] \function{popitem()
} is useful to destructively iterate
918 over a dictionary, as often used in set algorithms.
922 \subsection{Other Built-in Types
\label{typesother
}}
924 The interpreter supports several other kinds of objects.
925 Most of these support only one or two operations.
928 \subsubsection{Modules
\label{typesmodules
}}
930 The only special operation on a module is attribute access:
931 \code{\var{m
}.
\var{name
}}, where
\var{m
} is a module and
\var{name
}
932 accesses a name defined in
\var{m
}'s symbol table. Module attributes
933 can be assigned to. (Note that the
\keyword{import
} statement is not,
934 strictly speaking, an operation on a module object;
\code{import
935 \var{foo
}} does not require a module object named
\var{foo
} to exist,
936 rather it requires an (external)
\emph{definition
} for a module named
937 \var{foo
} somewhere.)
939 A special member of every module is
\member{__dict__
}.
940 This is the dictionary containing the module's symbol table.
941 Modifying this dictionary will actually change the module's symbol
942 table, but direct assignment to the
\member{__dict__
} attribute is not
943 possible (i.e., you can write
\code{\var{m
}.__dict__
['a'
] =
1}, which
944 defines
\code{\var{m
}.a
} to be
\code{1}, but you can't write
945 \code{\var{m
}.__dict__ = \
{\
}}.
947 Modules built into the interpreter are written like this:
948 \code{<module 'sys' (built-in)>
}. If loaded from a file, they are
949 written as
\code{<module 'os' from
950 '/usr/local/lib/python
\shortversion/os.pyc'>
}.
953 \subsubsection{Classes and Class Instances
\label{typesobjects
}}
954 \nodename{Classes and Instances
}
956 See chapters
3 and
7 of the
\citetitle[../ref/ref.html
]{Python
957 Reference Manual
} for these.
960 \subsubsection{Functions
\label{typesfunctions
}}
962 Function objects are created by function definitions. The only
963 operation on a function object is to call it:
964 \code{\var{func
}(
\var{argument-list
})
}.
966 There are really two flavors of function objects: built-in functions
967 and user-defined functions. Both support the same operation (to call
968 the function), but the implementation is different, hence the
969 different object types.
971 The implementation adds two special read-only attributes:
972 \code{\var{f
}.func_code
} is a function's
\dfn{code
973 object
}\obindex{code
} (see below) and
\code{\var{f
}.func_globals
} is
974 the dictionary used as the function's global namespace (this is the
975 same as
\code{\var{m
}.__dict__
} where
\var{m
} is the module in which
976 the function
\var{f
} was defined).
978 Function objects also support getting and setting arbitrary
979 attributes, which can be used to, e.g. attach metadata to functions.
980 Regular attribute dot-notation is used to get and set such
981 attributes.
\emph{Note that the current implementation only supports
982 function attributes on functions written in Python. Function
983 attributes on built-ins may be supported in the future.
}
985 Functions have another special attribute
\code{\var{f
}.__dict__
}
986 (a.k.a.
\code{\var{f
}.func_dict
}) which contains the namespace used to
987 support function attributes.
\code{__dict__
} can be accessed
988 directly, set to a dictionary object, or
\code{None
}. It can also be
989 deleted (but the following two lines are equivalent):
996 \subsubsection{Methods
\label{typesmethods
}}
999 Methods are functions that are called using the attribute notation.
1000 There are two flavors: built-in methods (such as
\method{append()
} on
1001 lists) and class instance methods. Built-in methods are described
1002 with the types that support them.
1004 The implementation adds two special read-only attributes to class
1005 instance methods:
\code{\var{m
}.im_self
} is the object on which the
1006 method operates, and
\code{\var{m
}.im_func
} is the function
1007 implementing the method. Calling
\code{\var{m
}(
\var{arg-
1},
1008 \var{arg-
2},
\textrm{\ldots},
\var{arg-n
})
} is completely equivalent to
1009 calling
\code{\var{m
}.im_func(
\var{m
}.im_self,
\var{arg-
1},
1010 \var{arg-
2},
\textrm{\ldots},
\var{arg-n
})
}.
1012 Class instance methods are either
\emph{bound
} or
\emph{unbound
},
1013 referring to whether the method was accessed through an instance or a
1014 class, respectively. When a method is unbound, its
\code{im_self
}
1015 attribute will be
\code{None
} and if called, an explicit
\code{self
}
1016 object must be passed as the first argument. In this case,
1017 \code{self
} must be an instance of the unbound method's class (or a
1018 subclass of that class), otherwise a
\code{TypeError
} is raised.
1020 Like function objects, methods objects support getting
1021 arbitrary attributes. However, since method attributes are actually
1022 stored on the underlying function object (i.e.
\code{meth.im_func
}),
1023 setting method attributes on either bound or unbound methods is
1024 disallowed. Attempting to set a method attribute results in a
1025 \code{TypeError
} being raised. In order to set a method attribute,
1026 you need to explicitly set it on the underlying function object:
1034 c.method.im_func.whoami = 'my name is c'
1037 See the
\citetitle[../ref/ref.html
]{Python Reference Manual
} for more
1041 \subsubsection{Code Objects
\label{bltin-code-objects
}}
1044 Code objects are used by the implementation to represent
1045 ``pseudo-compiled'' executable Python code such as a function body.
1046 They differ from function objects because they don't contain a
1047 reference to their global execution environment. Code objects are
1048 returned by the built-in
\function{compile()
} function and can be
1049 extracted from function objects through their
\member{func_code
}
1051 \bifuncindex{compile
}
1052 \withsubitem{(function object attribute)
}{\ttindex{func_code
}}
1054 A code object can be executed or evaluated by passing it (instead of a
1055 source string) to the
\keyword{exec
} statement or the built-in
1056 \function{eval()
} function.
1060 See the
\citetitle[../ref/ref.html
]{Python Reference Manual
} for more
1064 \subsubsection{Type Objects
\label{bltin-type-objects
}}
1066 Type objects represent the various object types. An object's type is
1067 accessed by the built-in function
\function{type()
}. There are no special
1068 operations on types. The standard module
\module{types
} defines names
1069 for all standard built-in types.
1071 \refstmodindex{types
}
1073 Types are written like this:
\code{<type 'int'>
}.
1076 \subsubsection{The Null Object
\label{bltin-null-object
}}
1078 This object is returned by functions that don't explicitly return a
1079 value. It supports no special operations. There is exactly one null
1080 object, named
\code{None
} (a built-in name).
1082 It is written as
\code{None
}.
1085 \subsubsection{The Ellipsis Object
\label{bltin-ellipsis-object
}}
1087 This object is used by extended slice notation (see the
1088 \citetitle[../ref/ref.html
]{Python Reference Manual
}). It supports no
1089 special operations. There is exactly one ellipsis object, named
1090 \constant{Ellipsis
} (a built-in name).
1092 It is written as
\code{Ellipsis
}.
1095 \subsubsection{File Objects
\obindex{file
}
1096 \label{bltin-file-objects
}}
1098 File objects are implemented using C's
\code{stdio
} package and can be
1099 created with the built-in function
1100 \function{open()
}\bifuncindex{open
} described in section
1101 \ref{built-in-funcs
}, ``Built-in Functions.'' They are also returned
1102 by some other built-in functions and methods, e.g.,
1103 \function{os.popen()
} and
\function{os.fdopen()
} and the
1104 \method{makefile()
} method of socket objects.
1106 \refbimodindex{socket
}
1108 When a file operation fails for an I/O-related reason, the exception
1109 \exception{IOError
} is raised. This includes situations where the
1110 operation is not defined for some reason, like
\method{seek()
} on a tty
1111 device or writing a file opened for reading.
1113 Files have the following methods:
1116 \begin{methoddesc
}[file
]{close
}{}
1117 Close the file. A closed file cannot be read or written anymore.
1118 Any operation which requires that the file be open will raise a
1119 \exception{ValueError
} after the file has been closed. Calling
1120 \method{close()
} more than once is allowed.
1123 \begin{methoddesc
}[file
]{flush
}{}
1124 Flush the internal buffer, like
\code{stdio
}'s
1125 \cfunction{fflush()
}. This may be a no-op on some file-like
1129 \begin{methoddesc
}[file
]{isatty
}{}
1130 Return true if the file is connected to a tty(-like) device, else
1131 false.
\strong{Note:
} If a file-like object is not associated
1132 with a real file, this method should
\emph{not
} be implemented.
1135 \begin{methoddesc
}[file
]{fileno
}{}
1136 \index{file descriptor
}
1137 \index{descriptor, file
}
1138 Return the integer ``file descriptor'' that is used by the
1139 underlying implementation to request I/O operations from the
1140 operating system. This can be useful for other, lower level
1141 interfaces that use file descriptors, e.g.\ module
1142 \refmodule{fcntl
}\refbimodindex{fcntl
} or
\function{os.read()
} and
1143 friends.
\strong{Note:
} File-like objects which do not have a real
1144 file descriptor should
\emph{not
} provide this method!
1147 \begin{methoddesc
}[file
]{read
}{\optional{size
}}
1148 Read at most
\var{size
} bytes from the file (less if the read hits
1149 \EOF{} before obtaining
\var{size
} bytes). If the
\var{size
}
1150 argument is negative or omitted, read all data until
\EOF{} is
1151 reached. The bytes are returned as a string object. An empty
1152 string is returned when
\EOF{} is encountered immediately. (For
1153 certain files, like ttys, it makes sense to continue reading after
1154 an
\EOF{} is hit.) Note that this method may call the underlying
1155 C function
\cfunction{fread()
} more than once in an effort to
1156 acquire as close to
\var{size
} bytes as possible.
1159 \begin{methoddesc
}[file
]{readline
}{\optional{size
}}
1160 Read one entire line from the file. A trailing newline character is
1161 kept in the string
\footnote{
1162 The advantage of leaving the newline on is that an empty string
1163 can be returned to mean
\EOF{} without being ambiguous. Another
1164 advantage is that (in cases where it might matter, e.g. if you
1165 want to make an exact copy of a file while scanning its lines)
1166 you can tell whether the last line of a file ended in a newline
1167 or not (yes this happens!).
1168 } (but may be absent when a file ends with an
1169 incomplete line). If the
\var{size
} argument is present and
1170 non-negative, it is a maximum byte count (including the trailing
1171 newline) and an incomplete line may be returned.
1172 An empty string is returned when
\EOF{} is hit
1173 immediately. Note: Unlike
\code{stdio
}'s
\cfunction{fgets()
}, the
1174 returned string contains null characters (
\code{'
\e 0'
}) if they
1175 occurred in the input.
1178 \begin{methoddesc
}[file
]{readlines
}{\optional{sizehint
}}
1179 Read until
\EOF{} using
\method{readline()
} and return a list containing
1180 the lines thus read. If the optional
\var{sizehint
} argument is
1181 present, instead of reading up to
\EOF{}, whole lines totalling
1182 approximately
\var{sizehint
} bytes (possibly after rounding up to an
1183 internal buffer size) are read. Objects implementing a file-like
1184 interface may choose to ignore
\var{sizehint
} if it cannot be
1185 implemented, or cannot be implemented efficiently.
1188 \begin{methoddesc
}[file
]{xreadlines
}{}
1189 Equivalent to
\function{xreadlines.xreadlines(file)
}.
\refstmodindex{xreadlines
}
1192 \begin{methoddesc
}[file
]{seek
}{offset
\optional{, whence
}}
1193 Set the file's current position, like
\code{stdio
}'s
\cfunction{fseek()
}.
1194 The
\var{whence
} argument is optional and defaults to
\code{0}
1195 (absolute file positioning); other values are
\code{1} (seek
1196 relative to the current position) and
\code{2} (seek relative to the
1197 file's end). There is no return value. Note that if the file is
1198 opened for appending (mode
\code{'a'
} or
\code{'a+'
}), any
1199 \method{seek()
} operations will be undone at the next write. If the
1200 file is only opened for writing in append mode (mode
\code{'a'
}),
1201 this method is essentially a no-op, but it remains useful for files
1202 opened in append mode with reading enabled (mode
\code{'a+'
}).
1205 \begin{methoddesc
}[file
]{tell
}{}
1206 Return the file's current position, like
\code{stdio
}'s
1207 \cfunction{ftell()
}.
1210 \begin{methoddesc
}[file
]{truncate
}{\optional{size
}}
1211 Truncate the file's size. If the optional
\var{size
} argument
1212 present, the file is truncated to (at most) that size. The size
1213 defaults to the current position. Availability of this function
1214 depends on the operating system version (for example, not all
1215 \UNIX{} versions support this operation).
1218 \begin{methoddesc
}[file
]{write
}{str
}
1219 Write a string to the file. There is no return value. Note: Due to
1220 buffering, the string may not actually show up in the file until
1221 the
\method{flush()
} or
\method{close()
} method is called.
1224 \begin{methoddesc
}[file
]{writelines
}{list
}
1225 Write a list of strings to the file. There is no return value.
1226 (The name is intended to match
\method{readlines()
};
1227 \method{writelines()
} does not add line separators.)
1230 \begin{methoddesc
}[file
]{xreadlines
}{}
1232 \function{xreadlines.xreadlines(
\var{file
})
}.
\refstmodindex{xreadlines
}
1233 (See the
\refmodule{xreadlines
} module for more information.)
1237 File objects also offer a number of other interesting attributes.
1238 These are not required for file-like objects, but should be
1239 implemented if they make sense for the particular object.
1241 \begin{memberdesc
}[file
]{closed
}
1242 Boolean indicating the current state of the file object. This is a
1243 read-only attribute; the
\method{close()
} method changes the value.
1244 It may not be available on all file-like objects.
1247 \begin{memberdesc
}[file
]{mode
}
1248 The I/O mode for the file. If the file was created using the
1249 \function{open()
} built-in function, this will be the value of the
1250 \var{mode
} parameter. This is a read-only attribute and may not be
1251 present on all file-like objects.
1254 \begin{memberdesc
}[file
]{name
}
1255 If the file object was created using
\function{open()
}, the name of
1256 the file. Otherwise, some string that indicates the source of the
1257 file object, of the form
\samp{<
\mbox{\ldots}>
}. This is a read-only
1258 attribute and may not be present on all file-like objects.
1261 \begin{memberdesc
}[file
]{softspace
}
1262 Boolean that indicates whether a space character needs to be printed
1263 before another value when using the
\keyword{print
} statement.
1264 Classes that are trying to simulate a file object should also have a
1265 writable
\member{softspace
} attribute, which should be initialized to
1266 zero. This will be automatic for most classes implemented in Python
1267 (care may be needed for objects that override attribute access); types
1268 implemented in C will have to provide a writable
1269 \member{softspace
} attribute.
1270 \strong{Note:
} This attribute is not used to control the
1271 \keyword{print
} statement, but to allow the implementation of
1272 \keyword{print
} to keep track of its internal state.
1276 \subsubsection{Internal Objects
\label{typesinternal
}}
1278 See the
\citetitle[../ref/ref.html
]{Python Reference Manual
} for this
1279 information. It describes stack frame objects, traceback objects, and
1283 \subsection{Special Attributes
\label{specialattrs
}}
1285 The implementation adds a few special read-only attributes to several
1286 object types, where they are relevant:
1288 \begin{memberdesc
}[object
]{__dict__
}
1289 A dictionary or other mapping object used to store an
1290 object's (writable) attributes.
1293 \begin{memberdesc
}[object
]{__methods__
}
1294 List of the methods of many built-in object types,
1295 e.g.,
\code{[].__methods__
} yields
1296 \code{['append', 'count', 'index', 'insert', 'pop', 'remove',
1297 'reverse', 'sort'
]}. This usually does not need to be explicitly
1298 provided by the object.
1301 \begin{memberdesc
}[object
]{__members__
}
1302 Similar to
\member{__methods__
}, but lists data attributes. This
1303 usually does not need to be explicitly provided by the object.
1306 \begin{memberdesc
}[instance
]{__class__
}
1307 The class to which a class instance belongs.
1310 \begin{memberdesc
}[class
]{__bases__
}
1311 The tuple of base classes of a class object.
