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{Iterator Types
\label{typeiter
}}
319 \index{iterator protocol
}
320 \index{protocol!iterator
}
321 \index{sequence!iteration
}
322 \index{container!iteration over
}
324 Python supports a concept of iteration over containers. This is
325 implemented using two distinct methods; these are used to allow
326 user-defined classes to support iteration. Sequences, described below
327 in more detail, always support the iteration methods.
329 One method needs to be defined for container objects to provide
332 \begin{methoddesc
}[container
]{__iter__
}{}
333 Return an iterator object. The object is required to support the
334 iterator protocol described below. If a container supports
335 different types of iteration, additional methods can be provided to
336 specifically request iterators for those iteration types. (An
337 example of an object supporting multiple forms of iteration would be
338 a tree structure which supports both breadth-first and depth-first
339 traversal.) This method corresponds to the
\member{tp_iter
} slot of
340 the type structure for Python objects in the Python/C API.
343 The iterator objects themselves are required to support the following
344 two methods, which together form the
\dfn{iterator protocol
}:
346 \begin{methoddesc
}[iterator
]{__iter__
}{}
347 Return the iterator object itself. This is required to allow both
348 containers and iterators to be used with the
\keyword{for
} and
349 \keyword{in
} statements. This method corresponds to the
350 \member{tp_iter
} slot of the type structure for Python objects in
354 \begin{methoddesc
}[iterator
]{next
}{}
355 Return the next item from the container. If there are no further
356 items, raise the
\exception{StopIteration
} exception. This method
357 corresponds to the
\member{tp_iternext
} slot of the type structure
358 for Python objects in the Python/C API.
361 Python defines several iterator objects to support iteration over
362 general and specific sequence types, dictionaries, and other more
363 specialized forms. The specific types are not important beyond their
364 implementation of the iterator protocol.
367 \subsection{Sequence Types
\label{typesseq
}}
369 There are six sequence types: strings, Unicode strings, lists,
370 tuples, buffers, and xrange objects.
372 Strings literals are written in single or double quotes:
373 \code{'xyzzy'
},
\code{"frobozz"
}. See chapter
2 of the
374 \citetitle[../ref/strings.html
]{Python Reference Manual
} for more about
375 string literals. Unicode strings are much like strings, but are
376 specified in the syntax using a preceeding
\character{u
} character:
377 \code{u'abc'
},
\code{u"def"
}. Lists are constructed with square brackets,
378 separating items with commas:
\code{[a, b, c
]}. Tuples are
379 constructed by the comma operator (not within square brackets), with
380 or without enclosing parentheses, but an empty tuple must have the
381 enclosing parentheses, e.g.,
\code{a, b, c
} or
\code{()
}. A single
382 item tuple must have a trailing comma, e.g.,
\code{(d,)
}.
389 Buffer objects are not directly supported by Python syntax, but can be
390 created by calling the builtin function
391 \function{buffer()
}.
\bifuncindex{buffer
}. They don't support
392 concatenation or repetition.
395 Xrange objects are similar to buffers in that there is no specific
396 syntax to create them, but they are created using the
\function{xrange()
}
397 function.
\bifuncindex{xrange
} They don't support slicing,
398 concatenation or repetition, and using
\code{in
},
\code{not in
},
399 \function{min()
} or
\function{max()
} on them is inefficient.
402 Most sequence types support the following operations. The
\samp{in
} and
403 \samp{not in
} operations have the same priorities as the comparison
404 operations. The
\samp{+
} and
\samp{*
} operations have the same
405 priority as the corresponding numeric operations.
\footnote{They must
406 have since the parser can't tell the type of the operands.
}
408 This table lists the sequence operations sorted in ascending priority
409 (operations in the same box have the same priority). In the table,
410 \var{s
} and
\var{t
} are sequences of the same type;
\var{n
},
\var{i
}
411 and
\var{j
} are integers:
413 \begin{tableiii
}{c|l|c
}{code
}{Operation
}{Result
}{Notes
}
414 \lineiii{\var{x
} in
\var{s
}}{\code{1} if an item of
\var{s
} is equal to
\var{x
}, else
\code{0}}{}
415 \lineiii{\var{x
} not in
\var{s
}}{\code{0} if an item of
\var{s
} is
416 equal to
\var{x
}, else
\code{1}}{}
418 \lineiii{\var{s
} +
\var{t
}}{the concatenation of
\var{s
} and
\var{t
}}{}
419 \lineiii{\var{s
} *
\var{n
}\textrm{,
} \var{n
} *
\var{s
}}{\var{n
} copies of
\var{s
} concatenated
}{(
1)
}
421 \lineiii{\var{s
}[\var{i
}]}{\var{i
}'th item of
\var{s
}, origin
0}{(
2)
}
422 \lineiii{\var{s
}[\var{i
}:
\var{j
}]}{slice of
\var{s
} from
\var{i
} to
\var{j
}}{(
2), (
3)
}
424 \lineiii{len(
\var{s
})
}{length of
\var{s
}}{}
425 \lineiii{min(
\var{s
})
}{smallest item of
\var{s
}}{}
426 \lineiii{max(
\var{s
})
}{largest item of
\var{s
}}{}
428 \indexiii{operations on
}{sequence
}{types
}
432 \indexii{concatenation
}{operation
}
433 \indexii{repetition
}{operation
}
434 \indexii{subscript
}{operation
}
435 \indexii{slice
}{operation
}
443 \item[(
1)
] Values of
\var{n
} less than
\code{0} are treated as
444 \code{0} (which yields an empty sequence of the same type as
447 \item[(
2)
] If
\var{i
} or
\var{j
} is negative, the index is relative to
448 the end of the string:
\code{len(
\var{s
}) +
\var{i
}} or
449 \code{len(
\var{s
}) +
\var{j
}} is substituted. But note that
\code{-
0} is
452 \item[(
3)
] The slice of
\var{s
} from
\var{i
} to
\var{j
} is defined as
453 the sequence of items with index
\var{k
} such that
\code{\var{i
} <=
454 \var{k
} <
\var{j
}}. If
\var{i
} or
\var{j
} is greater than
455 \code{len(
\var{s
})
}, use
\code{len(
\var{s
})
}. If
\var{i
} is omitted,
456 use
\code{0}. If
\var{j
} is omitted, use
\code{len(
\var{s
})
}. If
457 \var{i
} is greater than or equal to
\var{j
}, the slice is empty.
461 \subsubsection{String Methods
\label{string-methods
}}
463 These are the string methods which both
8-bit strings and Unicode
466 \begin{methoddesc
}[string
]{capitalize
}{}
467 Return a copy of the string with only its first character capitalized.
470 \begin{methoddesc
}[string
]{center
}{width
}
471 Return centered in a string of length
\var{width
}. Padding is done
475 \begin{methoddesc
}[string
]{count
}{sub
\optional{, start
\optional{, end
}}}
476 Return the number of occurrences of substring
\var{sub
} in string
477 S
\code{[\var{start
}:
\var{end
}]}. Optional arguments
\var{start
} and
478 \var{end
} are interpreted as in slice notation.
481 \begin{methoddesc
}[string
]{encode
}{\optional{encoding
\optional{,errors
}}}
482 Return an encoded version of the string. Default encoding is the current
483 default string encoding.
\var{errors
} may be given to set a different
484 error handling scheme. The default for
\var{errors
} is
485 \code{'strict'
}, meaning that encoding errors raise a
486 \exception{ValueError
}. Other possible values are
\code{'ignore'
} and
491 \begin{methoddesc
}[string
]{endswith
}{suffix
\optional{, start
\optional{, end
}}}
492 Return true if the string ends with the specified
\var{suffix
},
493 otherwise return false. With optional
\var{start
}, test beginning at
494 that position. With optional
\var{end
}, stop comparing at that position.
497 \begin{methoddesc
}[string
]{expandtabs
}{\optional{tabsize
}}
498 Return a copy of the string where all tab characters are expanded
499 using spaces. If
\var{tabsize
} is not given, a tab size of
\code{8}
500 characters is assumed.
503 \begin{methoddesc
}[string
]{find
}{sub
\optional{, start
\optional{, end
}}}
504 Return the lowest index in the string where substring
\var{sub
} is
505 found, such that
\var{sub
} is contained in the range
[\var{start
},
506 \var{end
}). Optional arguments
\var{start
} and
\var{end
} are
507 interpreted as in slice notation. Return
\code{-
1} if
\var{sub
} is
511 \begin{methoddesc
}[string
]{index
}{sub
\optional{, start
\optional{, end
}}}
512 Like
\method{find()
}, but raise
\exception{ValueError
} when the
513 substring is not found.
516 \begin{methoddesc
}[string
]{isalnum
}{}
517 Return true if all characters in the string are alphanumeric and there
518 is at least one character, false otherwise.
521 \begin{methoddesc
}[string
]{isalpha
}{}
522 Return true if all characters in the string are alphabetic and there
523 is at least one character, false otherwise.
526 \begin{methoddesc
}[string
]{isdigit
}{}
527 Return true if there are only digit characters, false otherwise.
530 \begin{methoddesc
}[string
]{islower
}{}
531 Return true if all cased characters in the string are lowercase and
532 there is at least one cased character, false otherwise.
535 \begin{methoddesc
}[string
]{isspace
}{}
536 Return true if there are only whitespace characters in the string and
537 the string is not empty, false otherwise.
540 \begin{methoddesc
}[string
]{istitle
}{}
541 Return true if the string is a titlecased string: uppercase
542 characters may only follow uncased characters and lowercase characters
543 only cased ones. Return false otherwise.
546 \begin{methoddesc
}[string
]{isupper
}{}
547 Return true if all cased characters in the string are uppercase and
548 there is at least one cased character, false otherwise.
551 \begin{methoddesc
}[string
]{join
}{seq
}
552 Return a string which is the concatenation of the strings in the
553 sequence
\var{seq
}. The separator between elements is the string
554 providing this method.
557 \begin{methoddesc
}[string
]{ljust
}{width
}
558 Return the string left justified in a string of length
\var{width
}.
559 Padding is done using spaces. The original string is returned if
560 \var{width
} is less than
\code{len(
\var{s
})
}.
563 \begin{methoddesc
}[string
]{lower
}{}
564 Return a copy of the string converted to lowercase.
567 \begin{methoddesc
}[string
]{lstrip
}{}
568 Return a copy of the string with leading whitespace removed.
571 \begin{methoddesc
}[string
]{replace
}{old, new
\optional{, maxsplit
}}
572 Return a copy of the string with all occurrences of substring
573 \var{old
} replaced by
\var{new
}. If the optional argument
574 \var{maxsplit
} is given, only the first
\var{maxsplit
} occurrences are
578 \begin{methoddesc
}[string
]{rfind
}{sub
\optional{,start
\optional{,end
}}}
579 Return the highest index in the string where substring
\var{sub
} is
580 found, such that
\var{sub
} is contained within s
[start,end
]. Optional
581 arguments
\var{start
} and
\var{end
} are interpreted as in slice
582 notation. Return
\code{-
1} on failure.
585 \begin{methoddesc
}[string
]{rindex
}{sub
\optional{, start
\optional{, end
}}}
586 Like
\method{rfind()
} but raises
\exception{ValueError
} when the
587 substring
\var{sub
} is not found.
590 \begin{methoddesc
}[string
]{rjust
}{width
}
591 Return the string right justified in a string of length
\var{width
}.
592 Padding is done using spaces. The original string is returned if
593 \var{width
} is less than
\code{len(
\var{s
})
}.
596 \begin{methoddesc
}[string
]{rstrip
}{}
597 Return a copy of the string with trailing whitespace removed.
600 \begin{methoddesc
}[string
]{split
}{\optional{sep
\optional{,maxsplit
}}}
601 Return a list of the words in the string, using
\var{sep
} as the
602 delimiter string. If
\var{maxsplit
} is given, at most
\var{maxsplit
}
603 splits are done. If
\var{sep
} is not specified or
\code{None
}, any
604 whitespace string is a separator.
607 \begin{methoddesc
}[string
]{splitlines
}{\optional{keepends
}}
608 Return a list of the lines in the string, breaking at line
609 boundaries. Line breaks are not included in the resulting list unless
610 \var{keepends
} is given and true.
613 \begin{methoddesc
}[string
]{startswith
}{prefix
\optional{, start
\optional{, end
}}}
614 Return true if string starts with the
\var{prefix
}, otherwise
615 return false. With optional
\var{start
}, test string beginning at
616 that position. With optional
\var{end
}, stop comparing string at that
620 \begin{methoddesc
}[string
]{strip
}{}
621 Return a copy of the string with leading and trailing whitespace
625 \begin{methoddesc
}[string
]{swapcase
}{}
626 Return a copy of the string with uppercase characters converted to
627 lowercase and vice versa.
630 \begin{methoddesc
}[string
]{title
}{}
631 Return a titlecased version of the string: words start with uppercase
632 characters, all remaining cased characters are lowercase.
635 \begin{methoddesc
}[string
]{translate
}{table
\optional{, deletechars
}}
636 Return a copy of the string where all characters occurring in the
637 optional argument
\var{deletechars
} are removed, and the remaining
638 characters have been mapped through the given translation table, which
639 must be a string of length
256.
642 \begin{methoddesc
}[string
]{upper
}{}
643 Return a copy of the string converted to uppercase.
647 \subsubsection{String Formatting Operations
\label{typesseq-strings
}}
649 \index{formatting, string
}
650 \index{string!formatting
}
651 \index{printf-style formatting
}
652 \index{sprintf-style formatting
}
654 String and Unicode objects have one unique built-in operation: the
655 \code{\%
} operator (modulo). Given
\code{\var{format
} \%
656 \var{values
}} (where
\var{format
} is a string or Unicode object),
657 \code{\%
} conversion specifications in
\var{format
} are replaced with
658 zero or more elements of
\var{values
}. The effect is similar to the
659 using
\cfunction{sprintf()
} in the C language. If
\var{format
} is a
660 Unicode object, or if any of the objects being converted using the
661 \code{\%s
} conversion are Unicode objects, the result will be a
662 Unicode object as well.
664 If
\var{format
} requires a single argument,
\var{values
} may be a
665 single non-tuple object.
\footnote{A tuple object in this case should
666 be a singleton.
} Otherwise,
\var{values
} must be a tuple with
667 exactly the number of items specified by the format string, or a
668 single mapping object (for example, a dictionary).
670 A conversion specifier contains two or more characters and has the
671 following components, which must occur in this order:
674 \item The
\character{\%
} character, which marks the start of the
676 \item Mapping key value (optional), consisting of an identifier in
677 parentheses (for example,
\code{(somename)
}).
678 \item Conversion flags (optional), which affect the result of some
680 \item Minimum field width (optional). If specified as an
681 \character{*
} (asterisk), the actual width is read from the
682 next element of the tuple in
\var{values
}, and the object to
683 convert comes after the minimum field width and optional
685 \item Precision (optional), given as a
\character{.
} (dot) followed
686 by the precision. If specified as
\character{*
} (an
687 asterisk), the actual width is read from the next element of
688 the tuple in
\var{values
}, and the value to convert comes after
690 \item Length modifier (optional).
691 \item Conversion type.
694 If the right argument is a dictionary (or any kind of mapping), then
695 the formats in the string
\emph{must
} have a parenthesized key into
696 that dictionary inserted immediately after the
\character{\%
}
697 character, and each format formats the corresponding entry from the
698 mapping. For example:
702 >>> language = 'Python'
703 >>> print '
%(language)s has %(count)03d quote types.' % vars()
704 Python has
002 quote types.
707 In this case no
\code{*
} specifiers may occur in a format (since they
708 require a sequential parameter list).
710 The conversion flag characters are:
712 \begin{tableii
}{c|l
}{character
}{Flag
}{Meaning
}
713 \lineii{\#
}{The value conversion will use the ``alternate form''
714 (where defined below).
}
715 \lineii{0}{The conversion will be zero padded.
}
716 \lineii{-
}{The converted value is left adjusted (overrides
718 \lineii{{~
}}{(a space) A blank should be left before a positive number
719 (or empty string) produced by a signed conversion.
}
720 \lineii{+
}{A sign character (
\character{+
} or
\character{-
}) will
721 precede the conversion (overrides a "space" flag).
}
724 The length modifier may be
\code{h
},
\code{l
}, and
\code{L
} may be
725 present, but are ignored as they are not necessary for Python.
727 The conversion types are:
729 \begin{tableii
}{c|l
}{character
}{Conversion
}{Meaning
}
730 \lineii{d
}{Signed integer decimal.
}
731 \lineii{i
}{Signed integer decimal.
}
732 \lineii{o
}{Unsigned octal.
}
733 \lineii{u
}{Unsigned decimal.
}
734 \lineii{x
}{Unsigned hexidecimal (lowercase).
}
735 \lineii{X
}{Unsigned hexidecimal (uppercase).
}
736 \lineii{e
}{Floating point exponential format (lowercase).
}
737 \lineii{E
}{Floating point exponential format (uppercase).
}
738 \lineii{f
}{Floating point decimal format.
}
739 \lineii{F
}{Floating point decimal format.
}
740 \lineii{g
}{Same as
\character{e
} if exponent is greater than -
4 or
741 less than precision,
\character{f
} otherwise.
}
742 \lineii{G
}{Same as
\character{E
} if exponent is greater than -
4 or
743 less than precision,
\character{F
} otherwise.
}
744 \lineii{c
}{Single character (accepts integer or single character
746 \lineii{r
}{String (converts any python object using
748 \lineii{s
}{String (converts any python object using
750 \lineii{\%
}{No argument is converted, results in a
\character{\%
}
751 character in the result. (The complete specification is
758 Since Python strings have an explicit length,
\code{\%s
} conversions
759 do not assume that
\code{'
\e0'
} is the end of the string.
761 For safety reasons, floating point precisions are clipped to
50;
762 \code{\%f
} conversions for numbers whose absolute value is over
1e25
763 are replaced by
\code{\%g
} conversions.
\footnote{
764 These numbers are fairly arbitrary. They are intended to
765 avoid printing endless strings of meaningless digits without hampering
766 correct use and without having to know the exact precision of floating
767 point values on a particular machine.
768 } All other errors raise exceptions.
770 Additional string operations are defined in standard module
771 \refmodule{string
} and in built-in module
\refmodule{re
}.
772 \refstmodindex{string
}
776 \subsubsection{XRange Type
\label{typesseq-xrange
}}
778 The xrange
\obindex{xrange
} type is an immutable sequence which is
779 commonly used for looping. The advantage of the xrange type is that an
780 xrange object will always take the same amount of memory, no matter the
781 size of the range it represents. There are no consistent performance
784 XRange objects have very little behavior: they only support indexing
785 and the
\function{len()
} function.
788 \subsubsection{Mutable Sequence Types
\label{typesseq-mutable
}}
790 List objects support additional operations that allow in-place
791 modification of the object.
792 These operations would be supported by other mutable sequence types
793 (when added to the language) as well.
794 Strings and tuples are immutable sequence types and such objects cannot
795 be modified once created.
796 The following operations are defined on mutable sequence types (where
797 \var{x
} is an arbitrary object):
798 \indexiii{mutable
}{sequence
}{types
}
801 \begin{tableiii
}{c|l|c
}{code
}{Operation
}{Result
}{Notes
}
802 \lineiii{\var{s
}[\var{i
}] =
\var{x
}}
803 {item
\var{i
} of
\var{s
} is replaced by
\var{x
}}{}
804 \lineiii{\var{s
}[\var{i
}:
\var{j
}] =
\var{t
}}
805 {slice of
\var{s
} from
\var{i
} to
\var{j
} is replaced by
\var{t
}}{}
806 \lineiii{del
\var{s
}[\var{i
}:
\var{j
}]}
807 {same as
\code{\var{s
}[\var{i
}:
\var{j
}] =
[]}}{}
808 \lineiii{\var{s
}.append(
\var{x
})
}
809 {same as
\code{\var{s
}[len(
\var{s
}):len(
\var{s
})
] =
[\var{x
}]}}{(
1)
}
810 \lineiii{\var{s
}.extend(
\var{x
})
}
811 {same as
\code{\var{s
}[len(
\var{s
}):len(
\var{s
})
] =
\var{x
}}}{(
2)
}
812 \lineiii{\var{s
}.count(
\var{x
})
}
813 {return number of
\var{i
}'s for which
\code{\var{s
}[\var{i
}] ==
\var{x
}}}{}
814 \lineiii{\var{s
}.index(
\var{x
})
}
815 {return smallest
\var{i
} such that
\code{\var{s
}[\var{i
}] ==
\var{x
}}}{(
3)
}
816 \lineiii{\var{s
}.insert(
\var{i
},
\var{x
})
}
817 {same as
\code{\var{s
}[\var{i
}:
\var{i
}] =
[\var{x
}]}
818 if
\code{\var{i
} >=
0}}{}
819 \lineiii{\var{s
}.pop(
\optional{\var{i
}})
}
820 {same as
\code{\var{x
} =
\var{s
}[\var{i
}]; del
\var{s
}[\var{i
}]; return
\var{x
}}}{(
4)
}
821 \lineiii{\var{s
}.remove(
\var{x
})
}
822 {same as
\code{del
\var{s
}[\var{s
}.index(
\var{x
})
]}}{(
3)
}
823 \lineiii{\var{s
}.reverse()
}
824 {reverses the items of
\var{s
} in place
}{(
5)
}
825 \lineiii{\var{s
}.sort(
\optional{\var{cmpfunc
}})
}
826 {sort the items of
\var{s
} in place
}{(
5), (
6)
}
828 \indexiv{operations on
}{mutable
}{sequence
}{types
}
829 \indexiii{operations on
}{sequence
}{types
}
830 \indexiii{operations on
}{list
}{type
}
831 \indexii{subscript
}{assignment
}
832 \indexii{slice
}{assignment
}
834 \withsubitem{(list method)
}{
835 \ttindex{append()
}\ttindex{extend()
}\ttindex{count()
}\ttindex{index()
}
836 \ttindex{insert()
}\ttindex{pop()
}\ttindex{remove()
}\ttindex{reverse()
}
841 \item[(
1)
] The C implementation of Python has historically accepted
842 multiple parameters and implicitly joined them into a tuple; this
843 no longer works in Python
2.0. Use of this misfeature has been
844 deprecated since Python
1.4.
846 \item[(
2)
] Raises an exception when
\var{x
} is not a list object. The
847 \method{extend()
} method is experimental and not supported by
848 mutable sequence types other than lists.
850 \item[(
3)
] Raises
\exception{ValueError
} when
\var{x
} is not found in
853 \item[(
4)
] The
\method{pop()
} method is only supported by the list and
854 array types. The optional argument
\var{i
} defaults to
\code{-
1},
855 so that by default the last item is removed and returned.
857 \item[(
5)
] The
\method{sort()
} and
\method{reverse()
} methods modify the
858 list in place for economy of space when sorting or reversing a large
859 list. To remind you that they operate by side effect, they don't return
860 the sorted or reversed list.
862 \item[(
6)
] The
\method{sort()
} method takes an optional argument
863 specifying a comparison function of two arguments (list items) which
864 should return
\code{-
1},
\code{0} or
\code{1} depending on whether
865 the first argument is considered smaller than, equal to, or larger
866 than the second argument. Note that this slows the sorting process
867 down considerably; e.g. to sort a list in reverse order it is much
868 faster to use calls to the methods
\method{sort()
} and
869 \method{reverse()
} than to use the built-in function
870 \function{sort()
} with a comparison function that reverses the
871 ordering of the elements.
875 \subsection{Mapping Types
\label{typesmapping
}}
879 A
\dfn{mapping
} object maps values of one type (the key type) to
880 arbitrary objects. Mappings are mutable objects. There is currently
881 only one standard mapping type, the
\dfn{dictionary
}. A dictionary's keys are
882 almost arbitrary values. The only types of values not acceptable as
883 keys are values containing lists or dictionaries or other mutable
884 types that are compared by value rather than by object identity.
885 Numeric types used for keys obey the normal rules for numeric
886 comparison: if two numbers compare equal (e.g.
\code{1} and
887 \code{1.0}) then they can be used interchangeably to index the same
890 Dictionaries are created by placing a comma-separated list of
891 \code{\var{key
}:
\var{value
}} pairs within braces, for example:
892 \code{\
{'jack':
4098, 'sjoerd':
4127\
}} or
893 \code{\
{4098: 'jack',
4127: 'sjoerd'\
}}.
895 The following operations are defined on mappings (where
\var{a
} and
896 \var{b
} are mappings,
\var{k
} is a key, and
\var{v
} and
\var{x
} are
898 \indexiii{operations on
}{mapping
}{types
}
899 \indexiii{operations on
}{dictionary
}{type
}
902 \withsubitem{(dictionary method)
}{
912 \begin{tableiii
}{c|l|c
}{code
}{Operation
}{Result
}{Notes
}
913 \lineiii{len(
\var{a
})
}{the number of items in
\var{a
}}{}
914 \lineiii{\var{a
}[\var{k
}]}{the item of
\var{a
} with key
\var{k
}}{(
1)
}
915 \lineiii{\var{a
}[\var{k
}] =
\var{v
}}
916 {set
\code{\var{a
}[\var{k
}]} to
\var{v
}}
918 \lineiii{del
\var{a
}[\var{k
}]}
919 {remove
\code{\var{a
}[\var{k
}]} from
\var{a
}}
921 \lineiii{\var{a
}.clear()
}{remove all items from
\code{a
}}{}
922 \lineiii{\var{a
}.copy()
}{a (shallow) copy of
\code{a
}}{}
923 \lineiii{\var{a
}.has_key(
\var{k
})
}
924 {\code{1} if
\var{a
} has a key
\var{k
}, else
\code{0}}
926 \lineiii{\var{k
} \code{in
} \var{a
}}
927 {Equivalent to
\var{a
}.has_key(
\var{k
})
}
929 \lineiii{\var{k
} not in
\var{a
}}
930 {Equivalent to
\code{not
} \var{a
}.has_key(
\var{k
})
}
932 \lineiii{\var{a
}.items()
}
933 {a copy of
\var{a
}'s list of (
\var{key
},
\var{value
}) pairs
}
935 \lineiii{\var{a
}.keys()
}{a copy of
\var{a
}'s list of keys
}{(
3)
}
936 \lineiii{\var{a
}.update(
\var{b
})
}
937 {\code{for k in
\var{b
}.keys():
\var{a
}[k
] =
\var{b
}[k
]}}
939 \lineiii{\var{a
}.values()
}{a copy of
\var{a
}'s list of values
}{(
3)
}
940 \lineiii{\var{a
}.get(
\var{k
}\optional{,
\var{x
}})
}
941 {\code{\var{a
}[\var{k
}]} if
\code{\var{k
} in
\var{a
}},
944 \lineiii{\var{a
}.setdefault(
\var{k
}\optional{,
\var{x
}})
}
945 {\code{\var{a
}[\var{k
}]} if
\code{\var{k
} in
\var{a
}},
946 else
\var{x
} (also setting it)
}
948 \lineiii{\var{a
}.popitem()
}
949 {remove and return an arbitrary (
\var{key
},
\var{value
}) pair
}
951 \lineiii{\var{a
}.iteritems()
}
952 {return an iterator over (
\var{key
},
\var{value
}) pairs
}
954 \lineiii{\var{a
}.iterkeys()
}
955 {return an iterator over the mapping's keys
}
957 \lineiii{\var{a
}.itervalues()
}
958 {return an iterator over the mapping's values
}
965 \item[(
1)
] Raises a
\exception{KeyError
} exception if
\var{k
} is not
968 \item[(
2)
] \versionadded{2.2}
970 \item[(
3)
] Keys and values are listed in random order. If
971 \method{keys()
} and
\method{values()
} are called with no intervening
972 modifications to the dictionary, the two lists will directly
973 correspond. This allows the creation of
\code{(
\var{value
},
974 \var{key
})
} pairs using
\function{zip()
}:
\samp{pairs =
975 zip(
\var{a
}.values(),
\var{a
}.keys())
}.
977 \item[(
4)
] Never raises an exception if
\var{k
} is not in the map,
978 instead it returns
\var{x
}.
\var{x
} is optional; when
\var{x
} is not
979 provided and
\var{k
} is not in the map,
\code{None
} is returned.
981 \item[(
5)
] \function{setdefault()
} is like
\function{get()
}, except
982 that if
\var{k
} is missing,
\var{x
} is both returned and inserted into
983 the dictionary as the value of
\var{k
}.
985 \item[(
6)
] \function{popitem()
} is useful to destructively iterate
986 over a dictionary, as often used in set algorithms.
990 \subsection{Other Built-in Types
\label{typesother
}}
992 The interpreter supports several other kinds of objects.
993 Most of these support only one or two operations.
996 \subsubsection{Modules
\label{typesmodules
}}
998 The only special operation on a module is attribute access:
999 \code{\var{m
}.
\var{name
}}, where
\var{m
} is a module and
\var{name
}
1000 accesses a name defined in
\var{m
}'s symbol table. Module attributes
1001 can be assigned to. (Note that the
\keyword{import
} statement is not,
1002 strictly speaking, an operation on a module object;
\code{import
1003 \var{foo
}} does not require a module object named
\var{foo
} to exist,
1004 rather it requires an (external)
\emph{definition
} for a module named
1005 \var{foo
} somewhere.)
1007 A special member of every module is
\member{__dict__
}.
1008 This is the dictionary containing the module's symbol table.
1009 Modifying this dictionary will actually change the module's symbol
1010 table, but direct assignment to the
\member{__dict__
} attribute is not
1011 possible (you can write
\code{\var{m
}.__dict__
['a'
] =
1}, which
1012 defines
\code{\var{m
}.a
} to be
\code{1}, but you can't write
1013 \code{\var{m
}.__dict__ = \
{\
}}.
1015 Modules built into the interpreter are written like this:
1016 \code{<module 'sys' (built-in)>
}. If loaded from a file, they are
1017 written as
\code{<module 'os' from
1018 '/usr/local/lib/python
\shortversion/os.pyc'>
}.
1021 \subsubsection{Classes and Class Instances
\label{typesobjects
}}
1022 \nodename{Classes and Instances
}
1024 See chapters
3 and
7 of the
\citetitle[../ref/ref.html
]{Python
1025 Reference Manual
} for these.
1028 \subsubsection{Functions
\label{typesfunctions
}}
1030 Function objects are created by function definitions. The only
1031 operation on a function object is to call it:
1032 \code{\var{func
}(
\var{argument-list
})
}.
1034 There are really two flavors of function objects: built-in functions
1035 and user-defined functions. Both support the same operation (to call
1036 the function), but the implementation is different, hence the
1037 different object types.
1039 The implementation adds two special read-only attributes:
1040 \code{\var{f
}.func_code
} is a function's
\dfn{code
1041 object
}\obindex{code
} (see below) and
\code{\var{f
}.func_globals
} is
1042 the dictionary used as the function's global namespace (this is the
1043 same as
\code{\var{m
}.__dict__
} where
\var{m
} is the module in which
1044 the function
\var{f
} was defined).
1046 Function objects also support getting and setting arbitrary
1047 attributes, which can be used to, e.g. attach metadata to functions.
1048 Regular attribute dot-notation is used to get and set such
1049 attributes.
\emph{Note that the current implementation only supports
1050 function attributes on functions written in Python. Function
1051 attributes on built-ins may be supported in the future.
}
1053 Functions have another special attribute
\code{\var{f
}.__dict__
}
1054 (a.k.a.
\code{\var{f
}.func_dict
}) which contains the namespace used to
1055 support function attributes.
\code{__dict__
} can be accessed
1056 directly, set to a dictionary object, or
\code{None
}. It can also be
1057 deleted (but the following two lines are equivalent):
1061 func.__dict__ = None
1064 \subsubsection{Methods
\label{typesmethods
}}
1067 Methods are functions that are called using the attribute notation.
1068 There are two flavors: built-in methods (such as
\method{append()
} on
1069 lists) and class instance methods. Built-in methods are described
1070 with the types that support them.
1072 The implementation adds two special read-only attributes to class
1073 instance methods:
\code{\var{m
}.im_self
} is the object on which the
1074 method operates, and
\code{\var{m
}.im_func
} is the function
1075 implementing the method. Calling
\code{\var{m
}(
\var{arg-
1},
1076 \var{arg-
2},
\textrm{\ldots},
\var{arg-n
})
} is completely equivalent to
1077 calling
\code{\var{m
}.im_func(
\var{m
}.im_self,
\var{arg-
1},
1078 \var{arg-
2},
\textrm{\ldots},
\var{arg-n
})
}.
1080 Class instance methods are either
\emph{bound
} or
\emph{unbound
},
1081 referring to whether the method was accessed through an instance or a
1082 class, respectively. When a method is unbound, its
\code{im_self
}
1083 attribute will be
\code{None
} and if called, an explicit
\code{self
}
1084 object must be passed as the first argument. In this case,
1085 \code{self
} must be an instance of the unbound method's class (or a
1086 subclass of that class), otherwise a
\code{TypeError
} is raised.
1088 Like function objects, methods objects support getting
1089 arbitrary attributes. However, since method attributes are actually
1090 stored on the underlying function object (
\code{meth.im_func
}),
1091 setting method attributes on either bound or unbound methods is
1092 disallowed. Attempting to set a method attribute results in a
1093 \code{TypeError
} being raised. In order to set a method attribute,
1094 you need to explicitly set it on the underlying function object:
1102 c.method.im_func.whoami = 'my name is c'
1105 See the
\citetitle[../ref/ref.html
]{Python Reference Manual
} for more
1109 \subsubsection{Code Objects
\label{bltin-code-objects
}}
1112 Code objects are used by the implementation to represent
1113 ``pseudo-compiled'' executable Python code such as a function body.
1114 They differ from function objects because they don't contain a
1115 reference to their global execution environment. Code objects are
1116 returned by the built-in
\function{compile()
} function and can be
1117 extracted from function objects through their
\member{func_code
}
1119 \bifuncindex{compile
}
1120 \withsubitem{(function object attribute)
}{\ttindex{func_code
}}
1122 A code object can be executed or evaluated by passing it (instead of a
1123 source string) to the
\keyword{exec
} statement or the built-in
1124 \function{eval()
} function.
1128 See the
\citetitle[../ref/ref.html
]{Python Reference Manual
} for more
1132 \subsubsection{Type Objects
\label{bltin-type-objects
}}
1134 Type objects represent the various object types. An object's type is
1135 accessed by the built-in function
\function{type()
}. There are no special
1136 operations on types. The standard module
\module{types
} defines names
1137 for all standard built-in types.
1139 \refstmodindex{types
}
1141 Types are written like this:
\code{<type 'int'>
}.
1144 \subsubsection{The Null Object
\label{bltin-null-object
}}
1146 This object is returned by functions that don't explicitly return a
1147 value. It supports no special operations. There is exactly one null
1148 object, named
\code{None
} (a built-in name).
1150 It is written as
\code{None
}.
1153 \subsubsection{The Ellipsis Object
\label{bltin-ellipsis-object
}}
1155 This object is used by extended slice notation (see the
1156 \citetitle[../ref/ref.html
]{Python Reference Manual
}). It supports no
1157 special operations. There is exactly one ellipsis object, named
1158 \constant{Ellipsis
} (a built-in name).
1160 It is written as
\code{Ellipsis
}.
1163 \subsubsection{File Objects
\obindex{file
}
1164 \label{bltin-file-objects
}}
1166 File objects are implemented using C's
\code{stdio
} package and can be
1167 created with the built-in function
1168 \function{open()
}\bifuncindex{open
} described in section
1169 \ref{built-in-funcs
}, ``Built-in Functions.'' They are also returned
1170 by some other built-in functions and methods, such as
1171 \function{os.popen()
} and
\function{os.fdopen()
} and the
1172 \method{makefile()
} method of socket objects.
1174 \refbimodindex{socket
}
1176 When a file operation fails for an I/O-related reason, the exception
1177 \exception{IOError
} is raised. This includes situations where the
1178 operation is not defined for some reason, like
\method{seek()
} on a tty
1179 device or writing a file opened for reading.
1181 Files have the following methods:
1184 \begin{methoddesc
}[file
]{close
}{}
1185 Close the file. A closed file cannot be read or written anymore.
1186 Any operation which requires that the file be open will raise a
1187 \exception{ValueError
} after the file has been closed. Calling
1188 \method{close()
} more than once is allowed.
1191 \begin{methoddesc
}[file
]{flush
}{}
1192 Flush the internal buffer, like
\code{stdio
}'s
1193 \cfunction{fflush()
}. This may be a no-op on some file-like
1197 \begin{methoddesc
}[file
]{isatty
}{}
1198 Return true if the file is connected to a tty(-like) device, else
1199 false.
\strong{Note:
} If a file-like object is not associated
1200 with a real file, this method should
\emph{not
} be implemented.
1203 \begin{methoddesc
}[file
]{fileno
}{}
1204 \index{file descriptor
}
1205 \index{descriptor, file
}
1206 Return the integer ``file descriptor'' that is used by the
1207 underlying implementation to request I/O operations from the
1208 operating system. This can be useful for other, lower level
1209 interfaces that use file descriptors, such as the
1210 \refmodule{fcntl
}\refbimodindex{fcntl
} module or
1211 \function{os.read()
} and friends.
\strong{Note:
} File-like objects
1212 which do not have a real file descriptor should
\emph{not
} provide
1216 \begin{methoddesc
}[file
]{read
}{\optional{size
}}
1217 Read at most
\var{size
} bytes from the file (less if the read hits
1218 \EOF{} before obtaining
\var{size
} bytes). If the
\var{size
}
1219 argument is negative or omitted, read all data until
\EOF{} is
1220 reached. The bytes are returned as a string object. An empty
1221 string is returned when
\EOF{} is encountered immediately. (For
1222 certain files, like ttys, it makes sense to continue reading after
1223 an
\EOF{} is hit.) Note that this method may call the underlying
1224 C function
\cfunction{fread()
} more than once in an effort to
1225 acquire as close to
\var{size
} bytes as possible.
1228 \begin{methoddesc
}[file
]{readline
}{\optional{size
}}
1229 Read one entire line from the file. A trailing newline character is
1230 kept in the string
\footnote{
1231 The advantage of leaving the newline on is that an empty string
1232 can be returned to mean
\EOF{} without being ambiguous. Another
1233 advantage is that (in cases where it might matter, for example. if you
1234 want to make an exact copy of a file while scanning its lines)
1235 you can tell whether the last line of a file ended in a newline
1236 or not (yes this happens!).
1237 } (but may be absent when a file ends with an
1238 incomplete line). If the
\var{size
} argument is present and
1239 non-negative, it is a maximum byte count (including the trailing
1240 newline) and an incomplete line may be returned.
1241 An empty string is returned when
\EOF{} is hit
1242 immediately. Note: Unlike
\code{stdio
}'s
\cfunction{fgets()
}, the
1243 returned string contains null characters (
\code{'
\e 0'
}) if they
1244 occurred in the input.
1247 \begin{methoddesc
}[file
]{readlines
}{\optional{sizehint
}}
1248 Read until
\EOF{} using
\method{readline()
} and return a list containing
1249 the lines thus read. If the optional
\var{sizehint
} argument is
1250 present, instead of reading up to
\EOF{}, whole lines totalling
1251 approximately
\var{sizehint
} bytes (possibly after rounding up to an
1252 internal buffer size) are read. Objects implementing a file-like
1253 interface may choose to ignore
\var{sizehint
} if it cannot be
1254 implemented, or cannot be implemented efficiently.
1257 \begin{methoddesc
}[file
]{xreadlines
}{}
1259 \function{xreadlines.xreadlines(
\var{file
})
}.
\refstmodindex{xreadlines
}
1260 (See the
\refmodule{xreadlines
} module for more information.)
1264 \begin{methoddesc
}[file
]{seek
}{offset
\optional{, whence
}}
1265 Set the file's current position, like
\code{stdio
}'s
\cfunction{fseek()
}.
1266 The
\var{whence
} argument is optional and defaults to
\code{0}
1267 (absolute file positioning); other values are
\code{1} (seek
1268 relative to the current position) and
\code{2} (seek relative to the
1269 file's end). There is no return value. Note that if the file is
1270 opened for appending (mode
\code{'a'
} or
\code{'a+'
}), any
1271 \method{seek()
} operations will be undone at the next write. If the
1272 file is only opened for writing in append mode (mode
\code{'a'
}),
1273 this method is essentially a no-op, but it remains useful for files
1274 opened in append mode with reading enabled (mode
\code{'a+'
}).
1277 \begin{methoddesc
}[file
]{tell
}{}
1278 Return the file's current position, like
\code{stdio
}'s
1279 \cfunction{ftell()
}.
1282 \begin{methoddesc
}[file
]{truncate
}{\optional{size
}}
1283 Truncate the file's size. If the optional
\var{size
} argument
1284 present, the file is truncated to (at most) that size. The size
1285 defaults to the current position. Availability of this function
1286 depends on the operating system version (for example, not all
1287 \UNIX{} versions support this operation).
1290 \begin{methoddesc
}[file
]{write
}{str
}
1291 Write a string to the file. There is no return value. Note: Due to
1292 buffering, the string may not actually show up in the file until
1293 the
\method{flush()
} or
\method{close()
} method is called.
1296 \begin{methoddesc
}[file
]{writelines
}{list
}
1297 Write a list of strings to the file. There is no return value.
1298 (The name is intended to match
\method{readlines()
};
1299 \method{writelines()
} does not add line separators.)
1303 File objects also offer a number of other interesting attributes.
1304 These are not required for file-like objects, but should be
1305 implemented if they make sense for the particular object.
1307 \begin{memberdesc
}[file
]{closed
}
1308 Boolean indicating the current state of the file object. This is a
1309 read-only attribute; the
\method{close()
} method changes the value.
1310 It may not be available on all file-like objects.
1313 \begin{memberdesc
}[file
]{mode
}
1314 The I/O mode for the file. If the file was created using the
1315 \function{open()
} built-in function, this will be the value of the
1316 \var{mode
} parameter. This is a read-only attribute and may not be
1317 present on all file-like objects.
1320 \begin{memberdesc
}[file
]{name
}
1321 If the file object was created using
\function{open()
}, the name of
1322 the file. Otherwise, some string that indicates the source of the
1323 file object, of the form
\samp{<
\mbox{\ldots}>
}. This is a read-only
1324 attribute and may not be present on all file-like objects.
1327 \begin{memberdesc
}[file
]{softspace
}
1328 Boolean that indicates whether a space character needs to be printed
1329 before another value when using the
\keyword{print
} statement.
1330 Classes that are trying to simulate a file object should also have a
1331 writable
\member{softspace
} attribute, which should be initialized to
1332 zero. This will be automatic for most classes implemented in Python
1333 (care may be needed for objects that override attribute access); types
1334 implemented in C will have to provide a writable
1335 \member{softspace
} attribute.
1336 \strong{Note:
} This attribute is not used to control the
1337 \keyword{print
} statement, but to allow the implementation of
1338 \keyword{print
} to keep track of its internal state.
1342 \subsubsection{Internal Objects
\label{typesinternal
}}
1344 See the
\citetitle[../ref/ref.html
]{Python Reference Manual
} for this
1345 information. It describes stack frame objects, traceback objects, and
1349 \subsection{Special Attributes
\label{specialattrs
}}
1351 The implementation adds a few special read-only attributes to several
1352 object types, where they are relevant:
1354 \begin{memberdesc
}[object
]{__dict__
}
1355 A dictionary or other mapping object used to store an
1356 object's (writable) attributes.
1359 \begin{memberdesc
}[object
]{__methods__
}
1360 List of the methods of many built-in object types. For example,
1361 \code{[].__methods__
} yields
\code{['append', 'count', 'index',
1362 'insert', 'pop', 'remove', 'reverse', 'sort'
]}. This usually does not
1363 need to be explicitly provided by the object.
1366 \begin{memberdesc
}[object
]{__members__
}
1367 Similar to
\member{__methods__
}, but lists data attributes. This
1368 usually does not need to be explicitly provided by the object, and
1369 need not include the names of the attributes defined in this section.
1372 \begin{memberdesc
}[instance
]{__class__
}
1373 The class to which a class instance belongs.
1376 \begin{memberdesc
}[class
]{__bases__
}
1377 The tuple of base classes of a class object. If there are no base
1378 classes, this will be an empty tuple.
