cpython-lru_cache-weakref: Doc/lib/libstdtypes.tex annotate

annotate Doc/lib/libstdtypes.tex @ 38199:aae2ff33e27c legacy-trunk

Remove misleading comment about type-class unification.

author	Georg Brandl <georg@python.org>
date	Wed, 17 May 2006 14:06:07 +0000
parents	e92a8b8eec73
children	81e385a641ef

rev	line source
9083 bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	1 \section{Built-in Types \label{types}}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	2
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	3 The following sections describe the standard types that are built into
38199 aae2ff33e27c Remove misleading comment about type-class unification. Georg Brandl <georg@python.org> parents: 38102 diff changeset	4 the interpreter.
aae2ff33e27c Remove misleading comment about type-class unification. Georg Brandl <georg@python.org> parents: 38102 diff changeset	5 \note{Historically (until release 2.2), Python's built-in types have
aae2ff33e27c Remove misleading comment about type-class unification. Georg Brandl <georg@python.org> parents: 38102 diff changeset	6 differed from user-defined types because it was not possible to use
aae2ff33e27c Remove misleading comment about type-class unification. Georg Brandl <georg@python.org> parents: 38102 diff changeset	7 the built-in types as the basis for object-oriented inheritance.
aae2ff33e27c Remove misleading comment about type-class unification. Georg Brandl <georg@python.org> parents: 38102 diff changeset	8 This limitation does not exist any longer.}
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	9
63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	10 The principal built-in types are numerics, sequences, mappings, files
63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	11 classes, instances and exceptions.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	12 \indexii{built-in}{types}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	13
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	14 Some operations are supported by several object types; in particular,
31298 ad3faf52e19e Correct misrepresentation of print (it uses str(), not `...` for Guido van Rossum <guido@python.org> parents: 31286 diff changeset	15 practically all objects can be compared, tested for truth value,
ad3faf52e19e Correct misrepresentation of print (it uses str(), not `...` for Guido van Rossum <guido@python.org> parents: 31286 diff changeset	16 and converted to a string (with the \code{`\textrm{\ldots}`} notation,
ad3faf52e19e Correct misrepresentation of print (it uses str(), not `...` for Guido van Rossum <guido@python.org> parents: 31286 diff changeset	17 the equivalent \function{repr()} function, or the slightly different
ad3faf52e19e Correct misrepresentation of print (it uses str(), not `...` for Guido van Rossum <guido@python.org> parents: 31286 diff changeset	18 \function{str()} function). The latter
ad3faf52e19e Correct misrepresentation of print (it uses str(), not `...` for Guido van Rossum <guido@python.org> parents: 31286 diff changeset	19 function is implicitly used when an object is written by the
9558 fa867d8ee7eb Remove some remaining {\rm ...} constructs. Fred Drake <fdrake@acm.org> parents: 9523 diff changeset	20 \keyword{print}\stindex{print} statement.
38000 94d9e0de4e49 add missing word Fred Drake <fdrake@acm.org> parents: 37971 diff changeset	21 (Information on the \ulink{\keyword{print} statement}{../ref/print.html}
28909 06abfc9c68e7 At the site of an indexed reference to print, point to the relevant Fred Drake <fdrake@acm.org> parents: 28606 diff changeset	22 and other language statements can be found in the
06abfc9c68e7 At the site of an indexed reference to print, point to the relevant Fred Drake <fdrake@acm.org> parents: 28606 diff changeset	23 \citetitle[../ref/ref.html]{Python Reference Manual} and the
06abfc9c68e7 At the site of an indexed reference to print, point to the relevant Fred Drake <fdrake@acm.org> parents: 28606 diff changeset	24 \citetitle[../tut/tut.html]{Python Tutorial}.)
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	25
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	26
28909 06abfc9c68e7 At the site of an indexed reference to print, point to the relevant Fred Drake <fdrake@acm.org> parents: 28606 diff changeset	27 \subsection{Truth Value Testing\label{truth}}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	28
9558 fa867d8ee7eb Remove some remaining {\rm ...} constructs. Fred Drake <fdrake@acm.org> parents: 9523 diff changeset	29 Any object can be tested for truth value, for use in an \keyword{if} or
fa867d8ee7eb Remove some remaining {\rm ...} constructs. Fred Drake <fdrake@acm.org> parents: 9523 diff changeset	30 \keyword{while} condition or as operand of the Boolean operations below.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	31 The following values are considered false:
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	32 \stindex{if}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	33 \stindex{while}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	34 \indexii{truth}{value}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	35 \indexii{Boolean}{operations}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	36 \index{false}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	37
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	38 \begin{itemize}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	39
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	40 \item \code{None}
24631 110c6edaf62f Clarify that the bool instances are acceptable return values from Fred Drake <fdrake@acm.org> parents: 24599 diff changeset	41 \withsubitem{(Built-in object)}{\ttindex{None}}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	42
22785 aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in Guido van Rossum <guido@python.org> parents: 22241 diff changeset	43 \item \code{False}
24631 110c6edaf62f Clarify that the bool instances are acceptable return values from Fred Drake <fdrake@acm.org> parents: 24599 diff changeset	44 \withsubitem{(Built-in object)}{\ttindex{False}}
22785 aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in Guido van Rossum <guido@python.org> parents: 22241 diff changeset	45
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	46 \item zero of any numeric type, for example, \code{0}, \code{0L},
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	47 \code{0.0}, \code{0j}.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	48
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	49 \item any empty sequence, for example, \code{''}, \code{()}, \code{[]}.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	50
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	51 \item any empty mapping, for example, \code{\{\}}.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	52
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	53 \item instances of user-defined classes, if the class defines a
24631 110c6edaf62f Clarify that the bool instances are acceptable return values from Fred Drake <fdrake@acm.org> parents: 24599 diff changeset	54 \method{__nonzero__()} or \method{__len__()} method, when that
110c6edaf62f Clarify that the bool instances are acceptable return values from Fred Drake <fdrake@acm.org> parents: 24599 diff changeset	55 method returns the integer zero or \class{bool} value
110c6edaf62f Clarify that the bool instances are acceptable return values from Fred Drake <fdrake@acm.org> parents: 24599 diff changeset	56 \code{False}.\footnote{Additional
24227 8a67f28a42a5 Clarify the return value of __nonzero__(): It must be an integer. Fred Drake <fdrake@acm.org> parents: 23860 diff changeset	57 information on these special methods may be found in the
8a67f28a42a5 Clarify the return value of __nonzero__(): It must be an integer. Fred Drake <fdrake@acm.org> parents: 23860 diff changeset	58 \citetitle[../ref/ref.html]{Python Reference Manual}.}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	59
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	60 \end{itemize}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	61
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	62 All other values are considered true --- so objects of many types are
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	63 always true.
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	64 \index{true}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	65
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	66 Operations and built-in functions that have a Boolean result always
22785 aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in Guido van Rossum <guido@python.org> parents: 22241 diff changeset	67 return \code{0} or \code{False} for false and \code{1} or \code{True}
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in Guido van Rossum <guido@python.org> parents: 22241 diff changeset	68 for true, unless otherwise stated. (Important exception: the Boolean
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in Guido van Rossum <guido@python.org> parents: 22241 diff changeset	69 operations \samp{or}\opindex{or} and \samp{and}\opindex{and} always
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in Guido van Rossum <guido@python.org> parents: 22241 diff changeset	70 return one of their operands.)
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in Guido van Rossum <guido@python.org> parents: 22241 diff changeset	71 \index{False}
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in Guido van Rossum <guido@python.org> parents: 22241 diff changeset	72 \index{True}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	73
35073 db1676fdb5b9 SF bug #1215887: String and list methods documentation deeply hidden Raymond Hettinger <python@rcn.com> parents: 34976 diff changeset	74 \subsection{Boolean Operations ---
db1676fdb5b9 SF bug #1215887: String and list methods documentation deeply hidden Raymond Hettinger <python@rcn.com> parents: 34976 diff changeset	75 \keyword{and}, \keyword{or}, \keyword{not}
db1676fdb5b9 SF bug #1215887: String and list methods documentation deeply hidden Raymond Hettinger <python@rcn.com> parents: 34976 diff changeset	76 \label{boolean}}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	77
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	78 These are the Boolean operations, ordered by ascending priority:
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	79 \indexii{Boolean}{operations}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	80
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	81 \begin{tableiii}{c\|l\|c}{code}{Operation}{Result}{Notes}
16285 15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	82 \lineiii{\var{x} or \var{y}}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	83 {if \var{x} is false, then \var{y}, else \var{x}}{(1)}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	84 \lineiii{\var{x} and \var{y}}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	85 {if \var{x} is false, then \var{x}, else \var{y}}{(1)}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	86 \hline
16285 15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	87 \lineiii{not \var{x}}
22785 aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in Guido van Rossum <guido@python.org> parents: 22241 diff changeset	88 {if \var{x} is false, then \code{True}, else \code{False}}{(2)}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	89 \end{tableiii}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	90 \opindex{and}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	91 \opindex{or}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	92 \opindex{not}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	93
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	94 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	95 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	96
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	97 \begin{description}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	98
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	99 \item[(1)]
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	100 These only evaluate their second argument if needed for their outcome.
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	101
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	102 \item[(2)]
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	103 \samp{not} has a lower priority than non-Boolean operators, so
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	104 \code{not \var{a} == \var{b}} is interpreted as \code{not (\var{a} ==
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	105 \var{b})}, and \code{\var{a} == not \var{b}} is a syntax error.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	106
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	107 \end{description}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	108
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	109
9083 bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	110 \subsection{Comparisons \label{comparisons}}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	111
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	112 Comparison operations are supported by all objects. They all have the
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	113 same priority (which is higher than that of the Boolean operations).
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	114 Comparisons can be chained arbitrarily; for example, \code{\var{x} <
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	115 \var{y} <= \var{z}} is equivalent to \code{\var{x} < \var{y} and
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	116 \var{y} <= \var{z}}, except that \var{y} is evaluated only once (but
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	117 in both cases \var{z} is not evaluated at all when \code{\var{x} <
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	118 \var{y}} is found to be false).
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	119 \indexii{chaining}{comparisons}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	120
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	121 This table summarizes the comparison operations:
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	122
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	123 \begin{tableiii}{c\|l\|c}{code}{Operation}{Meaning}{Notes}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	124 \lineiii{<}{strictly less than}{}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	125 \lineiii{<=}{less than or equal}{}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	126 \lineiii{>}{strictly greater than}{}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	127 \lineiii{>=}{greater than or equal}{}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	128 \lineiii{==}{equal}{}
14044 a905c5aa0691 As pointed out by Denis S. Otkidach <den@analyt.chem.msu.ru>, xrange() Fred Drake <fdrake@acm.org> parents: 13967 diff changeset	129 \lineiii{!=}{not equal}{(1)}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	130 \lineiii{<>}{not equal}{(1)}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	131 \lineiii{is}{object identity}{}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	132 \lineiii{is not}{negated object identity}{}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	133 \end{tableiii}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	134 \indexii{operator}{comparison}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	135 \opindex{==} % XXX All others have funny characters < ! >
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	136 \opindex{is}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	137 \opindex{is not}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	138
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	139 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	140 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	141
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	142 \begin{description}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	143
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	144 \item[(1)]
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	145 \code{<>} and \code{!=} are alternate spellings for the same operator.
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	146 \code{!=} is the preferred spelling; \code{<>} is obsolescent.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	147
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	148 \end{description}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	149
29343 e4f70e602598 Patch #744238: Explain that different string types also may compare equal. Martin v. Löwis <martin@v.loewis.de> parents: 29067 diff changeset	150 Objects of different types, except different numeric types and different string types, never
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	151 compare equal; such objects are ordered consistently but arbitrarily
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	152 (so that sorting a heterogeneous array yields a consistent result).
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	153 Furthermore, some types (for example, file objects) support only a
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	154 degenerate notion of comparison where any two objects of that type are
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	155 unequal. Again, such objects are ordered arbitrarily but
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	156 consistently. The \code{<}, \code{<=}, \code{>} and \code{>=}
63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	157 operators will raise a \exception{TypeError} exception when any operand
63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	158 is a complex number.
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	159 \indexii{object}{numeric}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	160 \indexii{objects}{comparing}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	161
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	162 Instances of a class normally compare as non-equal unless the class
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	163 \withsubitem{(instance method)}{\ttindex{__cmp__()}}
14485 ac0246586d52 Improve a couple of references to the language reference, making them Fred Drake <fdrake@acm.org> parents: 14044 diff changeset	164 defines the \method{__cmp__()} method. Refer to the
ac0246586d52 Improve a couple of references to the language reference, making them Fred Drake <fdrake@acm.org> parents: 14044 diff changeset	165 \citetitle[../ref/customization.html]{Python Reference Manual} for
ac0246586d52 Improve a couple of references to the language reference, making them Fred Drake <fdrake@acm.org> parents: 14044 diff changeset	166 information on the use of this method to effect object comparisons.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	167
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	168 \strong{Implementation note:} Objects of different types except
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	169 numbers are ordered by their type names; objects of the same types
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	170 that don't support proper comparison are ordered by their address.
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	171
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	172 Two more operations with the same syntactic priority,
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	173 \samp{in}\opindex{in} and \samp{not in}\opindex{not in}, are supported
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	174 only by sequence types (below).
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	175
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	176
35073 db1676fdb5b9 SF bug #1215887: String and list methods documentation deeply hidden Raymond Hettinger <python@rcn.com> parents: 34976 diff changeset	177 \subsection{Numeric Types ---
db1676fdb5b9 SF bug #1215887: String and list methods documentation deeply hidden Raymond Hettinger <python@rcn.com> parents: 34976 diff changeset	178 \class{int}, \class{float}, \class{long}, \class{complex}
db1676fdb5b9 SF bug #1215887: String and list methods documentation deeply hidden Raymond Hettinger <python@rcn.com> parents: 34976 diff changeset	179 \label{typesnumeric}}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	180
22785 aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in Guido van Rossum <guido@python.org> parents: 22241 diff changeset	181 There are four distinct numeric types: \dfn{plain integers},
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in Guido van Rossum <guido@python.org> parents: 22241 diff changeset	182 \dfn{long integers},
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	183 \dfn{floating point numbers}, and \dfn{complex numbers}.
22785 aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in Guido van Rossum <guido@python.org> parents: 22241 diff changeset	184 In addition, Booleans are a subtype of plain integers.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	185 Plain integers (also just called \dfn{integers})
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	186 are implemented using \ctype{long} in C, which gives them at least 32
37284 ef8059f87fd2 document sys.maxint in std objects Georg Brandl <georg@python.org> parents: 37259 diff changeset	187 bits of precision (\code{sys.maxint} is always set to the maximum
ef8059f87fd2 document sys.maxint in std objects Georg Brandl <georg@python.org> parents: 37259 diff changeset	188 plain integer value for the current platform, the minimum value is
ef8059f87fd2 document sys.maxint in std objects Georg Brandl <georg@python.org> parents: 37259 diff changeset	189 \code{-sys.maxint - 1}). Long integers have unlimited precision.
ef8059f87fd2 document sys.maxint in std objects Georg Brandl <georg@python.org> parents: 37259 diff changeset	190 Floating point numbers are implemented using \ctype{double} in C.
ef8059f87fd2 document sys.maxint in std objects Georg Brandl <georg@python.org> parents: 37259 diff changeset	191 All bets on their precision are off unless you happen to know the
ef8059f87fd2 document sys.maxint in std objects Georg Brandl <georg@python.org> parents: 37259 diff changeset	192 machine you are working with.
15005 0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	193 \obindex{numeric}
22785 aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in Guido van Rossum <guido@python.org> parents: 22241 diff changeset	194 \obindex{Boolean}
15005 0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	195 \obindex{integer}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	196 \obindex{long integer}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	197 \obindex{floating point}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	198 \obindex{complex number}
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	199 \indexii{C}{language}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	200
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	201 Complex numbers have a real and imaginary part, which are each
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	202 implemented using \ctype{double} in C. To extract these parts from
22241 7584b6f1afde Change Windows file.truncate() to (a) restore the original file position, Tim Peters <tim.peters@gmail.com> parents: 22214 diff changeset	203 a complex number \var{z}, use \code{\var{z}.real} and \code{\var{z}.imag}.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	204
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	205 Numbers are created by numeric literals or as the result of built-in
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	206 functions and operators. Unadorned integer literals (including hex
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	207 and octal numbers) yield plain integers unless the value they denote
63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	208 is too large to be represented as a plain integer, in which case
63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	209 they yield a long integer. Integer literals with an
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	210 \character{L} or \character{l} suffix yield long integers
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	211 (\character{L} is preferred because \samp{1l} looks too much like
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	212 eleven!). Numeric literals containing a decimal point or an exponent
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	213 sign yield floating point numbers. Appending \character{j} or
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	214 \character{J} to a numeric literal yields a complex number with a
63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	215 zero real part. A complex numeric literal is the sum of a real and
63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	216 an imaginary part.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	217 \indexii{numeric}{literals}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	218 \indexii{integer}{literals}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	219 \indexiii{long}{integer}{literals}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	220 \indexii{floating point}{literals}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	221 \indexii{complex number}{literals}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	222 \indexii{hexadecimal}{literals}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	223 \indexii{octal}{literals}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	224
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	225 Python fully supports mixed arithmetic: when a binary arithmetic
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	226 operator has operands of different numeric types, the operand with the
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	227 ``narrower'' type is widened to that of the other, where plain
63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	228 integer is narrower than long integer is narrower than floating point is
63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	229 narrower than complex.
10520 7ee1e3134147 Fixed latex2html weirdness with footnotes. Fred Drake <fdrake@acm.org> parents: 10241 diff changeset	230 Comparisons between numbers of mixed type use the same rule.\footnote{
7ee1e3134147 Fixed latex2html weirdness with footnotes. Fred Drake <fdrake@acm.org> parents: 10241 diff changeset	231 As a consequence, the list \code{[1, 2]} is considered equal
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	232 to \code{[1.0, 2.0]}, and similarly for tuples.
63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	233 } The constructors \function{int()}, \function{long()}, \function{float()},
9558 fa867d8ee7eb Remove some remaining {\rm ...} constructs. Fred Drake <fdrake@acm.org> parents: 9523 diff changeset	234 and \function{complex()} can be used
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	235 to produce numbers of a specific type.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	236 \index{arithmetic}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	237 \bifuncindex{int}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	238 \bifuncindex{long}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	239 \bifuncindex{float}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	240 \bifuncindex{complex}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	241
28171 24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	242 All numeric types (except complex) support the following operations,
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	243 sorted by ascending priority (operations in the same box have the same
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	244 priority; all numeric operations have a higher priority than
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	245 comparison operations):
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	246
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	247 \begin{tableiii}{c\|l\|c}{code}{Operation}{Result}{Notes}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	248 \lineiii{\var{x} + \var{y}}{sum of \var{x} and \var{y}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	249 \lineiii{\var{x} - \var{y}}{difference of \var{x} and \var{y}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	250 \hline
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	251 \lineiii{\var{x} * \var{y}}{product of \var{x} and \var{y}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	252 \lineiii{\var{x} / \var{y}}{quotient of \var{x} and \var{y}}{(1)}
37210 69c358bf6a34 SF bug # 1457358 and patch # 1458419, floor division not documented. Patch by Andy. Neal Norwitz <nnorwitz@gmail.com> parents: 37064 diff changeset	253 \lineiii{\var{x} // \var{y}}{(floored) quotient of \var{x} and \var{y}}{(5)}
28171 24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	254 \lineiii{\var{x} \%{} \var{y}}{remainder of \code{\var{x} / \var{y}}}{(4)}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	255 \hline
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	256 \lineiii{-\var{x}}{\var{x} negated}{}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	257 \lineiii{+\var{x}}{\var{x} unchanged}{}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	258 \hline
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	259 \lineiii{abs(\var{x})}{absolute value or magnitude of \var{x}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	260 \lineiii{int(\var{x})}{\var{x} converted to integer}{(2)}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	261 \lineiii{long(\var{x})}{\var{x} converted to long integer}{(2)}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	262 \lineiii{float(\var{x})}{\var{x} converted to floating point}{}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	263 \lineiii{complex(\var{re},\var{im})}{a complex number with real part \var{re}, imaginary part \var{im}. \var{im} defaults to zero.}{}
10147 3ac7f0066375 Document <complex #>.conjugate(). Fred Drake <fdrake@acm.org> parents: 9558 diff changeset	264 \lineiii{\var{c}.conjugate()}{conjugate of the complex number \var{c}}{}
34976 1873e8af5a8a SF bug #1209411: divmod documentation shd reference // not / Raymond Hettinger <python@rcn.com> parents: 34975 diff changeset	265 \lineiii{divmod(\var{x}, \var{y})}{the pair \code{(\var{x} // \var{y}, \var{x} \%{} \var{y})}}{(3)(4)}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	266 \lineiii{pow(\var{x}, \var{y})}{\var{x} to the power \var{y}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	267 \lineiii{\var{x} ** \var{y}}{\var{x} to the power \var{y}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	268 \end{tableiii}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	269 \indexiii{operations on}{numeric}{types}
10147 3ac7f0066375 Document <complex #>.conjugate(). Fred Drake <fdrake@acm.org> parents: 9558 diff changeset	270 \withsubitem{(complex number method)}{\ttindex{conjugate()}}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	271
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	272 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	273 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	274 \begin{description}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	275
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	276 \item[(1)]
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	277 For (plain or long) integer division, the result is an integer.
22241 7584b6f1afde Change Windows file.truncate() to (a) restore the original file position, Tim Peters <tim.peters@gmail.com> parents: 22214 diff changeset	278 The result is always rounded towards minus infinity: 1/2 is 0,
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	279 (-1)/2 is -1, 1/(-2) is -1, and (-1)/(-2) is 0. Note that the result
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	280 is a long integer if either operand is a long integer, regardless of
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	281 the numeric value.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	282 \indexii{integer}{division}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	283 \indexiii{long}{integer}{division}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	284
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	285 \item[(2)]
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	286 Conversion from floating point to (long or plain) integer may round or
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	287 truncate as in C; see functions \function{floor()} and
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	288 \function{ceil()} in the \refmodule{math}\refbimodindex{math} module
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	289 for well-defined conversions.
10156 0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	290 \withsubitem{(in module math)}{\ttindex{floor()}\ttindex{ceil()}}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	291 \indexii{numeric}{conversions}
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	292 \indexii{C}{language}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	293
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	294 \item[(3)]
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	295 See section \ref{built-in-funcs}, ``Built-in Functions,'' for a full
e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	296 description.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	297
28171 24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	298 \item[(4)]
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	299 Complex floor division operator, modulo operator, and \function{divmod()}.
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	300
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	301 \deprecated{2.3}{Instead convert to float using \function{abs()}
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	302 if appropriate.}
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	303
37210 69c358bf6a34 SF bug # 1457358 and patch # 1458419, floor division not documented. Patch by Andy. Neal Norwitz <nnorwitz@gmail.com> parents: 37064 diff changeset	304 \item[(5)]
69c358bf6a34 SF bug # 1457358 and patch # 1458419, floor division not documented. Patch by Andy. Neal Norwitz <nnorwitz@gmail.com> parents: 37064 diff changeset	305 Also referred to as integer division. The resultant value is a whole integer,
69c358bf6a34 SF bug # 1457358 and patch # 1458419, floor division not documented. Patch by Andy. Neal Norwitz <nnorwitz@gmail.com> parents: 37064 diff changeset	306 though the result's type is not necessarily int.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	307 \end{description}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	308 % XXXJH exceptions: overflow (when? what operations?) zerodivision
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	309
10241 f138ba72bf2d Update description of what modules "look like" when printed. Fred Drake <fdrake@acm.org> parents: 10156 diff changeset	310 \subsubsection{Bit-string Operations on Integer Types \label{bitstring-ops}}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	311 \nodename{Bit-string Operations}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	312
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	313 Plain and long integer types support additional operations that make
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	314 sense only for bit-strings. Negative numbers are treated as their 2's
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	315 complement value (for long integers, this assumes a sufficiently large
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	316 number of bits that no overflow occurs during the operation).
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	317
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	318 The priorities of the binary bit-wise operations are all lower than
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	319 the numeric operations and higher than the comparisons; the unary
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	320 operation \samp{\~} has the same priority as the other unary numeric
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	321 operations (\samp{+} and \samp{-}).
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	322
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	323 This table lists the bit-string operations sorted in ascending
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	324 priority (operations in the same box have the same priority):
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	325
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	326 \begin{tableiii}{c\|l\|c}{code}{Operation}{Result}{Notes}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	327 \lineiii{\var{x} \| \var{y}}{bitwise \dfn{or} of \var{x} and \var{y}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	328 \lineiii{\var{x} \^{} \var{y}}{bitwise \dfn{exclusive or} of \var{x} and \var{y}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	329 \lineiii{\var{x} \&{} \var{y}}{bitwise \dfn{and} of \var{x} and \var{y}}{}
33970 023801332395 Fix SF bug #1061770: Manual typesets bit-shift operators as guillemet Fred Drake <fdrake@acm.org> parents: 33899 diff changeset	330 % The empty groups below prevent conversion to guillemets.
023801332395 Fix SF bug #1061770: Manual typesets bit-shift operators as guillemet Fred Drake <fdrake@acm.org> parents: 33899 diff changeset	331 \lineiii{\var{x} <{}< \var{n}}{\var{x} shifted left by \var{n} bits}{(1), (2)}
023801332395 Fix SF bug #1061770: Manual typesets bit-shift operators as guillemet Fred Drake <fdrake@acm.org> parents: 33899 diff changeset	332 \lineiii{\var{x} >{}> \var{n}}{\var{x} shifted right by \var{n} bits}{(1), (3)}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	333 \hline
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	334 \lineiii{\~\var{x}}{the bits of \var{x} inverted}{}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	335 \end{tableiii}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	336 \indexiii{operations on}{integer}{types}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	337 \indexii{bit-string}{operations}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	338 \indexii{shifting}{operations}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	339 \indexii{masking}{operations}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	340
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	341 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	342 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	343 \begin{description}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	344 \item[(1)] Negative shift counts are illegal and cause a
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	345 \exception{ValueError} to be raised.
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	346 \item[(2)] A left shift by \var{n} bits is equivalent to
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	347 multiplication by \code{pow(2, \var{n})} without overflow check.
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	348 \item[(3)] A right shift by \var{n} bits is equivalent to
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	349 division by \code{pow(2, \var{n})} without overflow check.
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	350 \end{description}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	351
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	352
17658 d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	353 \subsection{Iterator Types \label{typeiter}}
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	354
17663 d76649bd38d0 The general iteration support is part of 2.2, not 2.1 -- fixed the version Fred Drake <fdrake@acm.org> parents: 17658 diff changeset	355 \versionadded{2.2}
17658 d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	356 \index{iterator protocol}
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	357 \index{protocol!iterator}
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	358 \index{sequence!iteration}
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	359 \index{container!iteration over}
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	360
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	361 Python supports a concept of iteration over containers. This is
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	362 implemented using two distinct methods; these are used to allow
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	363 user-defined classes to support iteration. Sequences, described below
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	364 in more detail, always support the iteration methods.
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	365
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	366 One method needs to be defined for container objects to provide
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	367 iteration support:
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	368
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	369 \begin{methoddesc}[container]{__iter__}{}
18839 ab8aa4302109 Typo fix. Greg Ward <gward@python.net> parents: 18829 diff changeset	370 Return an iterator object. The object is required to support the
17658 d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	371 iterator protocol described below. If a container supports
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	372 different types of iteration, additional methods can be provided to
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	373 specifically request iterators for those iteration types. (An
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	374 example of an object supporting multiple forms of iteration would be
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	375 a tree structure which supports both breadth-first and depth-first
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	376 traversal.) This method corresponds to the \member{tp_iter} slot of
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	377 the type structure for Python objects in the Python/C API.
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	378 \end{methoddesc}
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	379
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	380 The iterator objects themselves are required to support the following
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	381 two methods, which together form the \dfn{iterator protocol}:
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	382
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	383 \begin{methoddesc}[iterator]{__iter__}{}
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	384 Return the iterator object itself. This is required to allow both
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	385 containers and iterators to be used with the \keyword{for} and
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	386 \keyword{in} statements. This method corresponds to the
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	387 \member{tp_iter} slot of the type structure for Python objects in
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	388 the Python/C API.
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	389 \end{methoddesc}
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	390
17663 d76649bd38d0 The general iteration support is part of 2.2, not 2.1 -- fixed the version Fred Drake <fdrake@acm.org> parents: 17658 diff changeset	391 \begin{methoddesc}[iterator]{next}{}
17658 d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	392 Return the next item from the container. If there are no further
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	393 items, raise the \exception{StopIteration} exception. This method
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	394 corresponds to the \member{tp_iternext} slot of the type structure
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	395 for Python objects in the Python/C API.
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	396 \end{methoddesc}
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	397
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	398 Python defines several iterator objects to support iteration over
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	399 general and specific sequence types, dictionaries, and other more
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	400 specialized forms. The specific types are not important beyond their
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	401 implementation of the iterator protocol.
d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	402
24253 62f4b45b05fd Record the decision that StopIteration is a sink state (see recent Guido van Rossum <guido@python.org> parents: 24227 diff changeset	403 The intention of the protocol is that once an iterator's
62f4b45b05fd Record the decision that StopIteration is a sink state (see recent Guido van Rossum <guido@python.org> parents: 24227 diff changeset	404 \method{next()} method raises \exception{StopIteration}, it will
62f4b45b05fd Record the decision that StopIteration is a sink state (see recent Guido van Rossum <guido@python.org> parents: 24227 diff changeset	405 continue to do so on subsequent calls. Implementations that
62f4b45b05fd Record the decision that StopIteration is a sink state (see recent Guido van Rossum <guido@python.org> parents: 24227 diff changeset	406 do not obey this property are deemed broken. (This constraint
62f4b45b05fd Record the decision that StopIteration is a sink state (see recent Guido van Rossum <guido@python.org> parents: 24227 diff changeset	407 was added in Python 2.3; in Python 2.2, various iterators are
62f4b45b05fd Record the decision that StopIteration is a sink state (see recent Guido van Rossum <guido@python.org> parents: 24227 diff changeset	408 broken according to this rule.)
62f4b45b05fd Record the decision that StopIteration is a sink state (see recent Guido van Rossum <guido@python.org> parents: 24227 diff changeset	409
29590 8807e901c526 SF bug #696777: How to make a class iterable using a member generator. Raymond Hettinger <python@rcn.com> parents: 29516 diff changeset	410 Python's generators provide a convenient way to implement the
8807e901c526 SF bug #696777: How to make a class iterable using a member generator. Raymond Hettinger <python@rcn.com> parents: 29516 diff changeset	411 iterator protocol. If a container object's \method{__iter__()}
8807e901c526 SF bug #696777: How to make a class iterable using a member generator. Raymond Hettinger <python@rcn.com> parents: 29516 diff changeset	412 method is implemented as a generator, it will automatically
8807e901c526 SF bug #696777: How to make a class iterable using a member generator. Raymond Hettinger <python@rcn.com> parents: 29516 diff changeset	413 return an iterator object (technically, a generator object)
8807e901c526 SF bug #696777: How to make a class iterable using a member generator. Raymond Hettinger <python@rcn.com> parents: 29516 diff changeset	414 supplying the \method{__iter__()} and \method{next()} methods.
8807e901c526 SF bug #696777: How to make a class iterable using a member generator. Raymond Hettinger <python@rcn.com> parents: 29516 diff changeset	415
17658 d6498b1ef50d Added section describing the iterator protocol. Fred Drake <fdrake@acm.org> parents: 17616 diff changeset	416
35073 db1676fdb5b9 SF bug #1215887: String and list methods documentation deeply hidden Raymond Hettinger <python@rcn.com> parents: 34976 diff changeset	417 \subsection{Sequence Types ---
db1676fdb5b9 SF bug #1215887: String and list methods documentation deeply hidden Raymond Hettinger <python@rcn.com> parents: 34976 diff changeset	418 \class{str}, \class{unicode}, \class{list},
db1676fdb5b9 SF bug #1215887: String and list methods documentation deeply hidden Raymond Hettinger <python@rcn.com> parents: 34976 diff changeset	419 \class{tuple}, \class{buffer}, \class{xrange}
db1676fdb5b9 SF bug #1215887: String and list methods documentation deeply hidden Raymond Hettinger <python@rcn.com> parents: 34976 diff changeset	420 \label{typesseq}}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	421
13967 7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach Fred Drake <fdrake@acm.org> parents: 13933 diff changeset	422 There are six sequence types: strings, Unicode strings, lists,
14044 a905c5aa0691 As pointed out by Denis S. Otkidach <den@analyt.chem.msu.ru>, xrange() Fred Drake <fdrake@acm.org> parents: 13967 diff changeset	423 tuples, buffers, and xrange objects.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	424
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	425 String literals are written in single or double quotes:
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	426 \code{'xyzzy'}, \code{"frobozz"}. See chapter 2 of the
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	427 \citetitle[../ref/strings.html]{Python Reference Manual} for more about
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	428 string literals. Unicode strings are much like strings, but are
34296 67f2190e1f6d SF Patch #1093896: miscellaneous doc typos Raymond Hettinger <python@rcn.com> parents: 34076 diff changeset	429 specified in the syntax using a preceding \character{u} character:
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	430 \code{u'abc'}, \code{u"def"}. Lists are constructed with square brackets,
11463 17e12305973e Use \citetitle and \programopt as appropriate. Fred Drake <fdrake@acm.org> parents: 11183 diff changeset	431 separating items with commas: \code{[a, b, c]}. Tuples are
17e12305973e Use \citetitle and \programopt as appropriate. Fred Drake <fdrake@acm.org> parents: 11183 diff changeset	432 constructed by the comma operator (not within square brackets), with
17e12305973e Use \citetitle and \programopt as appropriate. Fred Drake <fdrake@acm.org> parents: 11183 diff changeset	433 or without enclosing parentheses, but an empty tuple must have the
30375 4aa84a8b1fe4 Fix spacing markup and other sundries. Raymond Hettinger <python@rcn.com> parents: 30250 diff changeset	434 enclosing parentheses, such as \code{a, b, c} or \code{()}. A single
4aa84a8b1fe4 Fix spacing markup and other sundries. Raymond Hettinger <python@rcn.com> parents: 30250 diff changeset	435 item tuple must have a trailing comma, such as \code{(d,)}.
15005 0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	436 \obindex{sequence}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	437 \obindex{string}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	438 \obindex{Unicode}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	439 \obindex{tuple}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	440 \obindex{list}
18395 1d0d3e6a3201 List constraints on xrange() objects. Guido van Rossum <guido@python.org> parents: 18391 diff changeset	441
1d0d3e6a3201 List constraints on xrange() objects. Guido van Rossum <guido@python.org> parents: 18391 diff changeset	442 Buffer objects are not directly supported by Python syntax, but can be
1d0d3e6a3201 List constraints on xrange() objects. Guido van Rossum <guido@python.org> parents: 18391 diff changeset	443 created by calling the builtin function
25393 f559e97a41be Remove spurious period. Fred Drake <fdrake@acm.org> parents: 24902 diff changeset	444 \function{buffer()}.\bifuncindex{buffer} They don't support
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	445 concatenation or repetition.
18395 1d0d3e6a3201 List constraints on xrange() objects. Guido van Rossum <guido@python.org> parents: 18391 diff changeset	446 \obindex{buffer}
1d0d3e6a3201 List constraints on xrange() objects. Guido van Rossum <guido@python.org> parents: 18391 diff changeset	447
1d0d3e6a3201 List constraints on xrange() objects. Guido van Rossum <guido@python.org> parents: 18391 diff changeset	448 Xrange objects are similar to buffers in that there is no specific
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	449 syntax to create them, but they are created using the \function{xrange()}
63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	450 function.\bifuncindex{xrange} They don't support slicing,
63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	451 concatenation or repetition, and using \code{in}, \code{not in},
63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	452 \function{min()} or \function{max()} on them is inefficient.
15005 0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	453 \obindex{xrange}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	454
18395 1d0d3e6a3201 List constraints on xrange() objects. Guido van Rossum <guido@python.org> parents: 18391 diff changeset	455 Most sequence types support the following operations. The \samp{in} and
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	456 \samp{not in} operations have the same priorities as the comparison
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	457 operations. The \samp{+} and \samp{*} operations have the same
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	458 priority as the corresponding numeric operations.\footnote{They must
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	459 have since the parser can't tell the type of the operands.}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	460
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	461 This table lists the sequence operations sorted in ascending priority
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	462 (operations in the same box have the same priority). In the table,
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	463 \var{s} and \var{t} are sequences of the same type; \var{n}, \var{i}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	464 and \var{j} are integers:
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	465
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	466 \begin{tableiii}{c\|l\|c}{code}{Operation}{Result}{Notes}
33688 af300403edb8 SF patch #1041364: True/False instead of 1/0 in libstdtypes.tex Raymond Hettinger <python@rcn.com> parents: 33448 diff changeset	467 \lineiii{\var{x} in \var{s}}{\code{True} if an item of \var{s} is equal to \var{x}, else \code{False}}{(1)}
af300403edb8 SF patch #1041364: True/False instead of 1/0 in libstdtypes.tex Raymond Hettinger <python@rcn.com> parents: 33448 diff changeset	468 \lineiii{\var{x} not in \var{s}}{\code{False} if an item of \var{s} is
af300403edb8 SF patch #1041364: True/False instead of 1/0 in libstdtypes.tex Raymond Hettinger <python@rcn.com> parents: 33448 diff changeset	469 equal to \var{x}, else \code{True}}{(1)}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	470 \hline
32974 fb6ffd290cfb SF patch #980695: efficient string concatenation Raymond Hettinger <python@rcn.com> parents: 32951 diff changeset	471 \lineiii{\var{s} + \var{t}}{the concatenation of \var{s} and \var{t}}{(6)}
24598 12e146171f3d Committing patch #591250 which provides "str1 in str2" when str1 is a Barry Warsaw <barry@python.org> parents: 24459 diff changeset	472 \lineiii{\var{s} * \var{n}\textrm{,} \var{n} * \var{s}}{\var{n} shallow copies of \var{s} concatenated}{(2)}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	473 \hline
24598 12e146171f3d Committing patch #591250 which provides "str1 in str2" when str1 is a Barry Warsaw <barry@python.org> parents: 24459 diff changeset	474 \lineiii{\var{s}[\var{i}]}{\var{i}'th item of \var{s}, origin 0}{(3)}
12e146171f3d Committing patch #591250 which provides "str1 in str2" when str1 is a Barry Warsaw <barry@python.org> parents: 24459 diff changeset	475 \lineiii{\var{s}[\var{i}:\var{j}]}{slice of \var{s} from \var{i} to \var{j}}{(3), (4)}
28171 24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	476 \lineiii{\var{s}[\var{i}:\var{j}:\var{k}]}{slice of \var{s} from \var{i} to \var{j} with step \var{k}}{(3), (5)}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	477 \hline
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	478 \lineiii{len(\var{s})}{length of \var{s}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	479 \lineiii{min(\var{s})}{smallest item of \var{s}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	480 \lineiii{max(\var{s})}{largest item of \var{s}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	481 \end{tableiii}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	482 \indexiii{operations on}{sequence}{types}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	483 \bifuncindex{len}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	484 \bifuncindex{min}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	485 \bifuncindex{max}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	486 \indexii{concatenation}{operation}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	487 \indexii{repetition}{operation}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	488 \indexii{subscript}{operation}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	489 \indexii{slice}{operation}
28171 24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	490 \indexii{extended slice}{operation}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	491 \opindex{in}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	492 \opindex{not in}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	493
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	494 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	495 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	496
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	497 \begin{description}
24598 12e146171f3d Committing patch #591250 which provides "str1 in str2" when str1 is a Barry Warsaw <barry@python.org> parents: 24459 diff changeset	498 \item[(1)] When \var{s} is a string or Unicode string object the
12e146171f3d Committing patch #591250 which provides "str1 in str2" when str1 is a Barry Warsaw <barry@python.org> parents: 24459 diff changeset	499 \code{in} and \code{not in} operations act like a substring test. In
12e146171f3d Committing patch #591250 which provides "str1 in str2" when str1 is a Barry Warsaw <barry@python.org> parents: 24459 diff changeset	500 Python versions before 2.3, \var{x} had to be a string of length 1.
12e146171f3d Committing patch #591250 which provides "str1 in str2" when str1 is a Barry Warsaw <barry@python.org> parents: 24459 diff changeset	501 In Python 2.3 and beyond, \var{x} may be a string of any length.
12e146171f3d Committing patch #591250 which provides "str1 in str2" when str1 is a Barry Warsaw <barry@python.org> parents: 24459 diff changeset	502
12e146171f3d Committing patch #591250 which provides "str1 in str2" when str1 is a Barry Warsaw <barry@python.org> parents: 24459 diff changeset	503 \item[(2)] Values of \var{n} less than \code{0} are treated as
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	504 \code{0} (which yields an empty sequence of the same type as
19529 dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	505 \var{s}). Note also that the copies are shallow; nested structures
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	506 are not copied. This often haunts new Python programmers; consider:
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	507
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	508 \begin{verbatim}
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	509 >>> lists = [[]] * 3
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	510 >>> lists
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	511 [[], [], []]
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	512 >>> lists[0].append(3)
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	513 >>> lists
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	514 [[3], [3], [3]]
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	515 \end{verbatim}
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	516
33899 eb979c3f14ba Mistakes in the "sequence types" page: Armin Rigo <arigo@tunes.org> parents: 33688 diff changeset	517 What has happened is that \code{[[]]} is a one-element list containing
eb979c3f14ba Mistakes in the "sequence types" page: Armin Rigo <arigo@tunes.org> parents: 33688 diff changeset	518 an empty list, so all three elements of \code{[[]] * 3} are (pointers to)
eb979c3f14ba Mistakes in the "sequence types" page: Armin Rigo <arigo@tunes.org> parents: 33688 diff changeset	519 this single empty list. Modifying any of the elements of \code{lists}
eb979c3f14ba Mistakes in the "sequence types" page: Armin Rigo <arigo@tunes.org> parents: 33688 diff changeset	520 modifies this single list. You can create a list of different lists this
eb979c3f14ba Mistakes in the "sequence types" page: Armin Rigo <arigo@tunes.org> parents: 33688 diff changeset	521 way:
19529 dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	522
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	523 \begin{verbatim}
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	524 >>> lists = [[] for i in range(3)]
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	525 >>> lists[0].append(3)
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	526 >>> lists[1].append(5)
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	527 >>> lists[2].append(7)
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	528 >>> lists
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	529 [[3], [5], [7]]
dd8d6153a8c6 Added explanation that [...] * n generates shallow copies of [...], so Fred Drake <fdrake@acm.org> parents: 19243 diff changeset	530 \end{verbatim}
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	531
24598 12e146171f3d Committing patch #591250 which provides "str1 in str2" when str1 is a Barry Warsaw <barry@python.org> parents: 24459 diff changeset	532 \item[(3)] If \var{i} or \var{j} is negative, the index is relative to
18416 33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18395 diff changeset	533 the end of the string: \code{len(\var{s}) + \var{i}} or
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	534 \code{len(\var{s}) + \var{j}} is substituted. But note that \code{-0} is
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	535 still \code{0}.
22241 7584b6f1afde Change Windows file.truncate() to (a) restore the original file position, Tim Peters <tim.peters@gmail.com> parents: 22214 diff changeset	536
24598 12e146171f3d Committing patch #591250 which provides "str1 in str2" when str1 is a Barry Warsaw <barry@python.org> parents: 24459 diff changeset	537 \item[(4)] The slice of \var{s} from \var{i} to \var{j} is defined as
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	538 the sequence of items with index \var{k} such that \code{\var{i} <=
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	539 \var{k} < \var{j}}. If \var{i} or \var{j} is greater than
36580 8e13236243dd Bug #801349: document that start/stop/step slice arguments can be None Georg Brandl <georg@python.org> parents: 36333 diff changeset	540 \code{len(\var{s})}, use \code{len(\var{s})}. If \var{i} is omitted
8e13236243dd Bug #801349: document that start/stop/step slice arguments can be None Georg Brandl <georg@python.org> parents: 36333 diff changeset	541 or \code{None}, use \code{0}. If \var{j} is omitted or \code{None},
8e13236243dd Bug #801349: document that start/stop/step slice arguments can be None Georg Brandl <georg@python.org> parents: 36333 diff changeset	542 use \code{len(\var{s})}. If \var{i} is greater than or equal to \var{j},
8e13236243dd Bug #801349: document that start/stop/step slice arguments can be None Georg Brandl <georg@python.org> parents: 36333 diff changeset	543 the slice is empty.
28171 24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	544
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	545 \item[(5)] The slice of \var{s} from \var{i} to \var{j} with step
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	546 \var{k} is defined as the sequence of items with index
33899 eb979c3f14ba Mistakes in the "sequence types" page: Armin Rigo <arigo@tunes.org> parents: 33688 diff changeset	547 \code{\var{x} = \var{i} + \var{n}*\var{k}} such that
eb979c3f14ba Mistakes in the "sequence types" page: Armin Rigo <arigo@tunes.org> parents: 33688 diff changeset	548 $0 \leq n < \frac{j-i}{k}$. In other words, the indices
eb979c3f14ba Mistakes in the "sequence types" page: Armin Rigo <arigo@tunes.org> parents: 33688 diff changeset	549 are \code{i}, \code{i+k}, \code{i+2k}, \code{i+3k} and so on, stopping when
eb979c3f14ba Mistakes in the "sequence types" page: Armin Rigo <arigo@tunes.org> parents: 33688 diff changeset	550 \var{j} is reached (but never including \var{j}). If \var{i} or \var{j}
28171 24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	551 is greater than \code{len(\var{s})}, use \code{len(\var{s})}. If
36580 8e13236243dd Bug #801349: document that start/stop/step slice arguments can be None Georg Brandl <georg@python.org> parents: 36333 diff changeset	552 \var{i} or \var{j} are omitted or \code{None}, they become ``end'' values
30250 830c0cd8fdb2 SF patch #797180: Bug 792656: slicing explained Raymond Hettinger <python@rcn.com> parents: 30095 diff changeset	553 (which end depends on the sign of \var{k}). Note, \var{k} cannot
36580 8e13236243dd Bug #801349: document that start/stop/step slice arguments can be None Georg Brandl <georg@python.org> parents: 36333 diff changeset	554 be zero. If \var{k} is \code{None}, it is treated like \code{1}.
28171 24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	555
32974 fb6ffd290cfb SF patch #980695: efficient string concatenation Raymond Hettinger <python@rcn.com> parents: 32951 diff changeset	556 \item[(6)] If \var{s} and \var{t} are both strings, some Python
32975 9b188158181f Typo fix; use 'in-place' instead of 'inplace' Andrew M. Kuchling <amk@amk.ca> parents: 32974 diff changeset	557 implementations such as CPython can usually perform an in-place optimization
32974 fb6ffd290cfb SF patch #980695: efficient string concatenation Raymond Hettinger <python@rcn.com> parents: 32951 diff changeset	558 for assignments of the form \code{\var{s}=\var{s}+\var{t}} or
fb6ffd290cfb SF patch #980695: efficient string concatenation Raymond Hettinger <python@rcn.com> parents: 32951 diff changeset	559 \code{\var{s}+=\var{t}}. When applicable, this optimization makes
fb6ffd290cfb SF patch #980695: efficient string concatenation Raymond Hettinger <python@rcn.com> parents: 32951 diff changeset	560 quadratic run-time much less likely. This optimization is both version
fb6ffd290cfb SF patch #980695: efficient string concatenation Raymond Hettinger <python@rcn.com> parents: 32951 diff changeset	561 and implementation dependent. For performance sensitive code, it is
34296 67f2190e1f6d SF Patch #1093896: miscellaneous doc typos Raymond Hettinger <python@rcn.com> parents: 34076 diff changeset	562 preferable to use the \method{str.join()} method which assures consistent
32974 fb6ffd290cfb SF patch #980695: efficient string concatenation Raymond Hettinger <python@rcn.com> parents: 32951 diff changeset	563 linear concatenation performance across versions and implementations.
32975 9b188158181f Typo fix; use 'in-place' instead of 'inplace' Andrew M. Kuchling <amk@amk.ca> parents: 32974 diff changeset	564 \versionchanged[Formerly, string concatenation never occurred in-place]{2.4}
32974 fb6ffd290cfb SF patch #980695: efficient string concatenation Raymond Hettinger <python@rcn.com> parents: 32951 diff changeset	565
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	566 \end{description}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	567
10156 0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	568
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	569 \subsubsection{String Methods \label{string-methods}}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	570
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	571 These are the string methods which both 8-bit strings and Unicode
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	572 objects support:
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	573
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	574 \begin{methoddesc}[string]{capitalize}{}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	575 Return a copy of the string with only its first character capitalized.
32214 6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749. Martin v. Löwis <martin@v.loewis.de> parents: 32197 diff changeset	576
6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749. Martin v. Löwis <martin@v.loewis.de> parents: 32197 diff changeset	577 For 8-bit strings, this method is locale-dependent.
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	578 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	579
31021 21a10c3600b5 Add optional fillchar argument to ljust(), rjust(), and center() string methods. Raymond Hettinger <python@rcn.com> parents: 31008 diff changeset	580 \begin{methoddesc}[string]{center}{width\optional{, fillchar}}
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	581 Return centered in a string of length \var{width}. Padding is done
31021 21a10c3600b5 Add optional fillchar argument to ljust(), rjust(), and center() string methods. Raymond Hettinger <python@rcn.com> parents: 31008 diff changeset	582 using the specified \var{fillchar} (default is a space).
31022 845f19b145a8 Add version changed doc for addition of fillchar to ljust/rjust/center Neal Norwitz <nnorwitz@gmail.com> parents: 31021 diff changeset	583 \versionchanged[Support for the \var{fillchar} argument]{2.4}
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	584 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	585
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	586 \begin{methoddesc}[string]{count}{sub\optional{, start\optional{, end}}}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	587 Return the number of occurrences of substring \var{sub} in string
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	588 S\code{[\var{start}:\var{end}]}. Optional arguments \var{start} and
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	589 \var{end} are interpreted as in slice notation.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	590 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	591
21332 fbbd8a4ca7a6 Added documentation for str.decode(). Fred Drake <fdrake@acm.org> parents: 21177 diff changeset	592 \begin{methoddesc}[string]{decode}{\optional{encoding\optional{, errors}}}
fbbd8a4ca7a6 Added documentation for str.decode(). Fred Drake <fdrake@acm.org> parents: 21177 diff changeset	593 Decodes the string using the codec registered for \var{encoding}.
fbbd8a4ca7a6 Added documentation for str.decode(). Fred Drake <fdrake@acm.org> parents: 21177 diff changeset	594 \var{encoding} defaults to the default string encoding. \var{errors}
fbbd8a4ca7a6 Added documentation for str.decode(). Fred Drake <fdrake@acm.org> parents: 21177 diff changeset	595 may be given to set a different error handling scheme. The default is
fbbd8a4ca7a6 Added documentation for str.decode(). Fred Drake <fdrake@acm.org> parents: 21177 diff changeset	596 \code{'strict'}, meaning that encoding errors raise
32459 6b1ea5c07ff7 Document that encode() and decode() raise UnicodeError Walter Dörwald <walter@livinglogic.de> parents: 32458 diff changeset	597 \exception{UnicodeError}. Other possible values are \code{'ignore'},
6b1ea5c07ff7 Document that encode() and decode() raise UnicodeError Walter Dörwald <walter@livinglogic.de> parents: 32458 diff changeset	598 \code{'replace'} and any other name registered via
35951 90797233208e SF patch #1364946: Add a reference link from the dcoumentation of the encode Walter Dörwald <walter@livinglogic.de> parents: 35686 diff changeset	599 \function{codecs.register_error}, see section~\ref{codec-base-classes}.
21332 fbbd8a4ca7a6 Added documentation for str.decode(). Fred Drake <fdrake@acm.org> parents: 21177 diff changeset	600 \versionadded{2.2}
32459 6b1ea5c07ff7 Document that encode() and decode() raise UnicodeError Walter Dörwald <walter@livinglogic.de> parents: 32458 diff changeset	601 \versionchanged[Support for other error handling schemes added]{2.3}
21332 fbbd8a4ca7a6 Added documentation for str.decode(). Fred Drake <fdrake@acm.org> parents: 21177 diff changeset	602 \end{methoddesc}
fbbd8a4ca7a6 Added documentation for str.decode(). Fred Drake <fdrake@acm.org> parents: 21177 diff changeset	603
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	604 \begin{methoddesc}[string]{encode}{\optional{encoding\optional{,errors}}}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	605 Return an encoded version of the string. Default encoding is the current
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	606 default string encoding. \var{errors} may be given to set a different
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	607 error handling scheme. The default for \var{errors} is
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	608 \code{'strict'}, meaning that encoding errors raise a
32459 6b1ea5c07ff7 Document that encode() and decode() raise UnicodeError Walter Dörwald <walter@livinglogic.de> parents: 32458 diff changeset	609 \exception{UnicodeError}. Other possible values are \code{'ignore'},
6b1ea5c07ff7 Document that encode() and decode() raise UnicodeError Walter Dörwald <walter@livinglogic.de> parents: 32458 diff changeset	610 \code{'replace'}, \code{'xmlcharrefreplace'}, \code{'backslashreplace'}
35951 90797233208e SF patch #1364946: Add a reference link from the dcoumentation of the encode Walter Dörwald <walter@livinglogic.de> parents: 35686 diff changeset	611 and any other name registered via \function{codecs.register_error},
90797233208e SF patch #1364946: Add a reference link from the dcoumentation of the encode Walter Dörwald <walter@livinglogic.de> parents: 35686 diff changeset	612 see section~\ref{codec-base-classes}.
32459 6b1ea5c07ff7 Document that encode() and decode() raise UnicodeError Walter Dörwald <walter@livinglogic.de> parents: 32458 diff changeset	613 For a list of possible encodings, see section~\ref{standard-encodings}.
15332 12aec3381c94 Marc-Andre Lemburg <mal@lemburg.com> noted that the encode() string method Fred Drake <fdrake@acm.org> parents: 15005 diff changeset	614 \versionadded{2.0}
32459 6b1ea5c07ff7 Document that encode() and decode() raise UnicodeError Walter Dörwald <walter@livinglogic.de> parents: 32458 diff changeset	615 \versionchanged[Support for \code{'xmlcharrefreplace'} and
6b1ea5c07ff7 Document that encode() and decode() raise UnicodeError Walter Dörwald <walter@livinglogic.de> parents: 32458 diff changeset	616 \code{'backslashreplace'} and other error handling schemes added]{2.3}
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	617 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	618
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	619 \begin{methoddesc}[string]{endswith}{suffix\optional{, start\optional{, end}}}
28171 24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	620 Return \code{True} if the string ends with the specified \var{suffix},
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	621 otherwise return \code{False}. With optional \var{start}, test beginning at
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	622 that position. With optional \var{end}, stop comparing at that position.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	623 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	624
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	625 \begin{methoddesc}[string]{expandtabs}{\optional{tabsize}}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	626 Return a copy of the string where all tab characters are expanded
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	627 using spaces. If \var{tabsize} is not given, a tab size of \code{8}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	628 characters is assumed.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	629 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	630
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	631 \begin{methoddesc}[string]{find}{sub\optional{, start\optional{, end}}}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	632 Return the lowest index in the string where substring \var{sub} is
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	633 found, such that \var{sub} is contained in the range [\var{start},
36333 ea6a46d8c51e Bug #1396471: Document that Windows' ftell() can return invalid Georg Brandl <georg@python.org> parents: 36166 diff changeset	634 \var{end}]. Optional arguments \var{start} and \var{end} are
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	635 interpreted as in slice notation. Return \code{-1} if \var{sub} is
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	636 not found.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	637 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	638
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	639 \begin{methoddesc}[string]{index}{sub\optional{, start\optional{, end}}}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	640 Like \method{find()}, but raise \exception{ValueError} when the
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	641 substring is not found.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	642 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	643
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	644 \begin{methoddesc}[string]{isalnum}{}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	645 Return true if all characters in the string are alphanumeric and there
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	646 is at least one character, false otherwise.
32214 6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749. Martin v. Löwis <martin@v.loewis.de> parents: 32197 diff changeset	647
6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749. Martin v. Löwis <martin@v.loewis.de> parents: 32197 diff changeset	648 For 8-bit strings, this method is locale-dependent.
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	649 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	650
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	651 \begin{methoddesc}[string]{isalpha}{}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	652 Return true if all characters in the string are alphabetic and there
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	653 is at least one character, false otherwise.
32214 6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749. Martin v. Löwis <martin@v.loewis.de> parents: 32197 diff changeset	654
6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749. Martin v. Löwis <martin@v.loewis.de> parents: 32197 diff changeset	655 For 8-bit strings, this method is locale-dependent.
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	656 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	657
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	658 \begin{methoddesc}[string]{isdigit}{}
30707 9e21e56bf5f3 Patch #825679: Clarify semantics of .isfoo on empty strings. Martin v. Löwis <martin@v.loewis.de> parents: 30705 diff changeset	659 Return true if all characters in the string are digits and there
9e21e56bf5f3 Patch #825679: Clarify semantics of .isfoo on empty strings. Martin v. Löwis <martin@v.loewis.de> parents: 30705 diff changeset	660 is at least one character, false otherwise.
32214 6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749. Martin v. Löwis <martin@v.loewis.de> parents: 32197 diff changeset	661
6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749. Martin v. Löwis <martin@v.loewis.de> parents: 32197 diff changeset	662 For 8-bit strings, this method is locale-dependent.
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	663 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	664
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	665 \begin{methoddesc}[string]{islower}{}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	666 Return true if all cased characters in the string are lowercase and
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	667 there is at least one cased character, false otherwise.
32214 6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749. Martin v. Löwis <martin@v.loewis.de> parents: 32197 diff changeset	668
6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749. Martin v. Löwis <martin@v.loewis.de> parents: 32197 diff changeset	669 For 8-bit strings, this method is locale-dependent.
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	670 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	671
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	672 \begin{methoddesc}[string]{isspace}{}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	673 Return true if there are only whitespace characters in the string and
30707 9e21e56bf5f3 Patch #825679: Clarify semantics of .isfoo on empty strings. Martin v. Löwis <martin@v.loewis.de> parents: 30705 diff changeset	674 there is at least one character, false otherwise.
32214 6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749. Martin v. Löwis <martin@v.loewis.de> parents: 32197 diff changeset	675
6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749. Martin v. Löwis <martin@v.loewis.de> parents: 32197 diff changeset	676 For 8-bit strings, this method is locale-dependent.
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	677 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	678
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	679 \begin{methoddesc}[string]{istitle}{}
30707 9e21e56bf5f3 Patch #825679: Clarify semantics of .isfoo on empty strings. Martin v. Löwis <martin@v.loewis.de> parents: 30705 diff changeset	680 Return true if the string is a titlecased string and there is at least one
30810 2cba0de70df6 Add list.sorted() classmethod. Raymond Hettinger <python@rcn.com> parents: 30750 diff changeset	681 character, for example uppercase characters may only follow uncased
30707 9e21e56bf5f3 Patch #825679: Clarify semantics of .isfoo on empty strings. Martin v. Löwis <martin@v.loewis.de> parents: 30705 diff changeset	682 characters and lowercase characters only cased ones. Return false
9e21e56bf5f3 Patch #825679: Clarify semantics of .isfoo on empty strings. Martin v. Löwis <martin@v.loewis.de> parents: 30705 diff changeset	683 otherwise.
32214 6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749. Martin v. Löwis <martin@v.loewis.de> parents: 32197 diff changeset	684
6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749. Martin v. Löwis <martin@v.loewis.de> parents: 32197 diff changeset	685 For 8-bit strings, this method is locale-dependent.
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	686 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	687
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	688 \begin{methoddesc}[string]{isupper}{}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	689 Return true if all cased characters in the string are uppercase and
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	690 there is at least one cased character, false otherwise.
32214 6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749. Martin v. Löwis <martin@v.loewis.de> parents: 32197 diff changeset	691
6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749. Martin v. Löwis <martin@v.loewis.de> parents: 32197 diff changeset	692 For 8-bit strings, this method is locale-dependent.
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	693 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	694
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	695 \begin{methoddesc}[string]{join}{seq}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	696 Return a string which is the concatenation of the strings in the
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	697 sequence \var{seq}. The separator between elements is the string
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	698 providing this method.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	699 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	700
31021 21a10c3600b5 Add optional fillchar argument to ljust(), rjust(), and center() string methods. Raymond Hettinger <python@rcn.com> parents: 31008 diff changeset	701 \begin{methoddesc}[string]{ljust}{width\optional{, fillchar}}
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	702 Return the string left justified in a string of length \var{width}.
31021 21a10c3600b5 Add optional fillchar argument to ljust(), rjust(), and center() string methods. Raymond Hettinger <python@rcn.com> parents: 31008 diff changeset	703 Padding is done using the specified \var{fillchar} (default is a
21a10c3600b5 Add optional fillchar argument to ljust(), rjust(), and center() string methods. Raymond Hettinger <python@rcn.com> parents: 31008 diff changeset	704 space). The original string is returned if
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	705 \var{width} is less than \code{len(\var{s})}.
31022 845f19b145a8 Add version changed doc for addition of fillchar to ljust/rjust/center Neal Norwitz <nnorwitz@gmail.com> parents: 31021 diff changeset	706 \versionchanged[Support for the \var{fillchar} argument]{2.4}
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	707 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	708
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	709 \begin{methoddesc}[string]{lower}{}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	710 Return a copy of the string converted to lowercase.
32214 6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749. Martin v. Löwis <martin@v.loewis.de> parents: 32197 diff changeset	711
6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749. Martin v. Löwis <martin@v.loewis.de> parents: 32197 diff changeset	712 For 8-bit strings, this method is locale-dependent.
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	713 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	714
23017 44637bd7f59b Document the optional argument to the .strip(), .rstrip(), .strip() string Fred Drake <fdrake@acm.org> parents: 22994 diff changeset	715 \begin{methoddesc}[string]{lstrip}{\optional{chars}}
34975 5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement Raymond Hettinger <python@rcn.com> parents: 34969 diff changeset	716 Return a copy of the string with leading characters removed. The
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement Raymond Hettinger <python@rcn.com> parents: 34969 diff changeset	717 \var{chars} argument is a string specifying the set of characters
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement Raymond Hettinger <python@rcn.com> parents: 34969 diff changeset	718 to be removed. If omitted or \code{None}, the \var{chars} argument
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement Raymond Hettinger <python@rcn.com> parents: 34969 diff changeset	719 defaults to removing whitespace. The \var{chars} argument is not
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement Raymond Hettinger <python@rcn.com> parents: 34969 diff changeset	720 a prefix; rather, all combinations of its values are stripped:
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement Raymond Hettinger <python@rcn.com> parents: 34969 diff changeset	721 \begin{verbatim}
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement Raymond Hettinger <python@rcn.com> parents: 34969 diff changeset	722 >>> ' spacious '.lstrip()
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement Raymond Hettinger <python@rcn.com> parents: 34969 diff changeset	723 'spacious '
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement Raymond Hettinger <python@rcn.com> parents: 34969 diff changeset	724 >>> 'www.example.com'.lstrip('cmowz.')
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement Raymond Hettinger <python@rcn.com> parents: 34969 diff changeset	725 'example.com'
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement Raymond Hettinger <python@rcn.com> parents: 34969 diff changeset	726 \end{verbatim}
26259 60d809a25bae Document that a minor feature was added in 2.2.2. ;-( Fred Drake <fdrake@acm.org> parents: 26161 diff changeset	727 \versionchanged[Support for the \var{chars} argument]{2.2.2}
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	728 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	729
30750 1d92ecdf2bb1 Avoid confusing name for the 3rd argument to str.replace(). Fred Drake <fdrake@acm.org> parents: 30737 diff changeset	730 \begin{methoddesc}[string]{replace}{old, new\optional{, count}}
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	731 Return a copy of the string with all occurrences of substring
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	732 \var{old} replaced by \var{new}. If the optional argument
30750 1d92ecdf2bb1 Avoid confusing name for the 3rd argument to str.replace(). Fred Drake <fdrake@acm.org> parents: 30737 diff changeset	733 \var{count} is given, only the first \var{count} occurrences are
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	734 replaced.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	735 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	736
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	737 \begin{methoddesc}[string]{rfind}{sub \optional{,start \optional{,end}}}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	738 Return the highest index in the string where substring \var{sub} is
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	739 found, such that \var{sub} is contained within s[start,end]. Optional
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	740 arguments \var{start} and \var{end} are interpreted as in slice
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	741 notation. Return \code{-1} on failure.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	742 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	743
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	744 \begin{methoddesc}[string]{rindex}{sub\optional{, start\optional{, end}}}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	745 Like \method{rfind()} but raises \exception{ValueError} when the
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	746 substring \var{sub} is not found.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	747 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	748
31021 21a10c3600b5 Add optional fillchar argument to ljust(), rjust(), and center() string methods. Raymond Hettinger <python@rcn.com> parents: 31008 diff changeset	749 \begin{methoddesc}[string]{rjust}{width\optional{, fillchar}}
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	750 Return the string right justified in a string of length \var{width}.
31021 21a10c3600b5 Add optional fillchar argument to ljust(), rjust(), and center() string methods. Raymond Hettinger <python@rcn.com> parents: 31008 diff changeset	751 Padding is done using the specified \var{fillchar} (default is a space).
21a10c3600b5 Add optional fillchar argument to ljust(), rjust(), and center() string methods. Raymond Hettinger <python@rcn.com> parents: 31008 diff changeset	752 The original string is returned if
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	753 \var{width} is less than \code{len(\var{s})}.
31022 845f19b145a8 Add version changed doc for addition of fillchar to ljust/rjust/center Neal Norwitz <nnorwitz@gmail.com> parents: 31021 diff changeset	754 \versionchanged[Support for the \var{fillchar} argument]{2.4}
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	755 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	756
31206 3771ff99d5f2 Update documentations for str.rsplit() with Alex Martelli's rewrite. Hye-Shik Chang <hyeshik@gmail.com> parents: 31199 diff changeset	757 \begin{methoddesc}[string]{rsplit}{\optional{sep \optional{,maxsplit}}}
3771ff99d5f2 Update documentations for str.rsplit() with Alex Martelli's rewrite. Hye-Shik Chang <hyeshik@gmail.com> parents: 31199 diff changeset	758 Return a list of the words in the string, using \var{sep} as the
3771ff99d5f2 Update documentations for str.rsplit() with Alex Martelli's rewrite. Hye-Shik Chang <hyeshik@gmail.com> parents: 31199 diff changeset	759 delimiter string. If \var{maxsplit} is given, at most \var{maxsplit}
31286 3894654b4848 fix a variety of markup bugs Fred Drake <fdrake@acm.org> parents: 31282 diff changeset	760 splits are done, the \emph{rightmost} ones. If \var{sep} is not specified
34491 68020bd1b9e2 SF bug #1105286: Undocumented implicit strip() in split(None) string method Raymond Hettinger <python@rcn.com> parents: 34296 diff changeset	761 or \code{None}, any whitespace string is a separator. Except for splitting
68020bd1b9e2 SF bug #1105286: Undocumented implicit strip() in split(None) string method Raymond Hettinger <python@rcn.com> parents: 34296 diff changeset	762 from the right, \method{rsplit()} behaves like \method{split()} which
68020bd1b9e2 SF bug #1105286: Undocumented implicit strip() in split(None) string method Raymond Hettinger <python@rcn.com> parents: 34296 diff changeset	763 is described in detail below.
31199 504943c89193 Add rsplit method for str and unicode builtin types. Hye-Shik Chang <hyeshik@gmail.com> parents: 31022 diff changeset	764 \versionadded{2.4}
504943c89193 Add rsplit method for str and unicode builtin types. Hye-Shik Chang <hyeshik@gmail.com> parents: 31022 diff changeset	765 \end{methoddesc}
504943c89193 Add rsplit method for str and unicode builtin types. Hye-Shik Chang <hyeshik@gmail.com> parents: 31022 diff changeset	766
23017 44637bd7f59b Document the optional argument to the .strip(), .rstrip(), .strip() string Fred Drake <fdrake@acm.org> parents: 22994 diff changeset	767 \begin{methoddesc}[string]{rstrip}{\optional{chars}}
34975 5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement Raymond Hettinger <python@rcn.com> parents: 34969 diff changeset	768 Return a copy of the string with trailing characters removed. The
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement Raymond Hettinger <python@rcn.com> parents: 34969 diff changeset	769 \var{chars} argument is a string specifying the set of characters
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement Raymond Hettinger <python@rcn.com> parents: 34969 diff changeset	770 to be removed. If omitted or \code{None}, the \var{chars} argument
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement Raymond Hettinger <python@rcn.com> parents: 34969 diff changeset	771 defaults to removing whitespace. The \var{chars} argument is not
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement Raymond Hettinger <python@rcn.com> parents: 34969 diff changeset	772 a suffix; rather, all combinations of its values are stripped:
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement Raymond Hettinger <python@rcn.com> parents: 34969 diff changeset	773 \begin{verbatim}
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement Raymond Hettinger <python@rcn.com> parents: 34969 diff changeset	774 >>> ' spacious '.rstrip()
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement Raymond Hettinger <python@rcn.com> parents: 34969 diff changeset	775 ' spacious'
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement Raymond Hettinger <python@rcn.com> parents: 34969 diff changeset	776 >>> 'mississippi'.rstrip('ipz')
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement Raymond Hettinger <python@rcn.com> parents: 34969 diff changeset	777 'mississ'
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement Raymond Hettinger <python@rcn.com> parents: 34969 diff changeset	778 \end{verbatim}
26259 60d809a25bae Document that a minor feature was added in 2.2.2. ;-( Fred Drake <fdrake@acm.org> parents: 26161 diff changeset	779 \versionchanged[Support for the \var{chars} argument]{2.2.2}
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	780 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	781
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	782 \begin{methoddesc}[string]{split}{\optional{sep \optional{,maxsplit}}}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	783 Return a list of the words in the string, using \var{sep} as the
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	784 delimiter string. If \var{maxsplit} is given, at most \var{maxsplit}
33411 136b388569a0 SF bug #901654: split method documentation can be improved Raymond Hettinger <python@rcn.com> parents: 33102 diff changeset	785 splits are done. (thus, the list will have at most \code{\var{maxsplit}+1}
34508 13176ed52e65 SF bug #1108303: fix .split() maxsplit doc Raymond Hettinger <python@rcn.com> parents: 34491 diff changeset	786 elements). If \var{maxsplit} is not specified, then there
33411 136b388569a0 SF bug #901654: split method documentation can be improved Raymond Hettinger <python@rcn.com> parents: 33102 diff changeset	787 is no limit on the number of splits (all possible splits are made).
136b388569a0 SF bug #901654: split method documentation can be improved Raymond Hettinger <python@rcn.com> parents: 33102 diff changeset	788 Consecutive delimiters are not grouped together and are
136b388569a0 SF bug #901654: split method documentation can be improved Raymond Hettinger <python@rcn.com> parents: 33102 diff changeset	789 deemed to delimit empty strings (for example, \samp{'1,,2'.split(',')}
33412 c09318b0090d Add missing close parenthesis. Raymond Hettinger <python@rcn.com> parents: 33411 diff changeset	790 returns \samp{['1', '', '2']}). The \var{sep} argument may consist of
33411 136b388569a0 SF bug #901654: split method documentation can be improved Raymond Hettinger <python@rcn.com> parents: 33102 diff changeset	791 multiple characters (for example, \samp{'1, 2, 3'.split(', ')} returns
33412 c09318b0090d Add missing close parenthesis. Raymond Hettinger <python@rcn.com> parents: 33411 diff changeset	792 \samp{['1', '2', '3']}). Splitting an empty string with a specified
34917 6bdc3426d411 Correct swapped descriptions of empty string splits. Raymond Hettinger <python@rcn.com> parents: 34898 diff changeset	793 separator returns \samp{['']}.
33411 136b388569a0 SF bug #901654: split method documentation can be improved Raymond Hettinger <python@rcn.com> parents: 33102 diff changeset	794
136b388569a0 SF bug #901654: split method documentation can be improved Raymond Hettinger <python@rcn.com> parents: 33102 diff changeset	795 If \var{sep} is not specified or is \code{None}, a different splitting
34491 68020bd1b9e2 SF bug #1105286: Undocumented implicit strip() in split(None) string method Raymond Hettinger <python@rcn.com> parents: 34296 diff changeset	796 algorithm is applied. First, whitespace characters (spaces, tabs,
68020bd1b9e2 SF bug #1105286: Undocumented implicit strip() in split(None) string method Raymond Hettinger <python@rcn.com> parents: 34296 diff changeset	797 newlines, returns, and formfeeds) are stripped from both ends. Then,
68020bd1b9e2 SF bug #1105286: Undocumented implicit strip() in split(None) string method Raymond Hettinger <python@rcn.com> parents: 34296 diff changeset	798 words are separated by arbitrary length strings of whitespace
68020bd1b9e2 SF bug #1105286: Undocumented implicit strip() in split(None) string method Raymond Hettinger <python@rcn.com> parents: 34296 diff changeset	799 characters. Consecutive whitespace delimiters are treated as a single
68020bd1b9e2 SF bug #1105286: Undocumented implicit strip() in split(None) string method Raymond Hettinger <python@rcn.com> parents: 34296 diff changeset	800 delimiter (\samp{'1 2 3'.split()} returns \samp{['1', '2', '3']}).
68020bd1b9e2 SF bug #1105286: Undocumented implicit strip() in split(None) string method Raymond Hettinger <python@rcn.com> parents: 34296 diff changeset	801 Splitting an empty string or a string consisting of just whitespace
34917 6bdc3426d411 Correct swapped descriptions of empty string splits. Raymond Hettinger <python@rcn.com> parents: 34898 diff changeset	802 returns an empty list.
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	803 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	804
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	805 \begin{methoddesc}[string]{splitlines}{\optional{keepends}}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	806 Return a list of the lines in the string, breaking at line
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	807 boundaries. Line breaks are not included in the resulting list unless
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	808 \var{keepends} is given and true.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	809 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	810
23017 44637bd7f59b Document the optional argument to the .strip(), .rstrip(), .strip() string Fred Drake <fdrake@acm.org> parents: 22994 diff changeset	811 \begin{methoddesc}[string]{startswith}{prefix\optional{,
44637bd7f59b Document the optional argument to the .strip(), .rstrip(), .strip() string Fred Drake <fdrake@acm.org> parents: 22994 diff changeset	812 start\optional{, end}}}
28171 24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	813 Return \code{True} if string starts with the \var{prefix}, otherwise
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	814 return \code{False}. With optional \var{start}, test string beginning at
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	815 that position. With optional \var{end}, stop comparing string at that
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	816 position.
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	817 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	818
23017 44637bd7f59b Document the optional argument to the .strip(), .rstrip(), .strip() string Fred Drake <fdrake@acm.org> parents: 22994 diff changeset	819 \begin{methoddesc}[string]{strip}{\optional{chars}}
34975 5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement Raymond Hettinger <python@rcn.com> parents: 34969 diff changeset	820 Return a copy of the string with the leading and trailing characters
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement Raymond Hettinger <python@rcn.com> parents: 34969 diff changeset	821 removed. The \var{chars} argument is a string specifying the set of
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement Raymond Hettinger <python@rcn.com> parents: 34969 diff changeset	822 characters to be removed. If omitted or \code{None}, the \var{chars}
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement Raymond Hettinger <python@rcn.com> parents: 34969 diff changeset	823 argument defaults to removing whitespace. The \var{chars} argument is not
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement Raymond Hettinger <python@rcn.com> parents: 34969 diff changeset	824 a prefix or suffix; rather, all combinations of its values are stripped:
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement Raymond Hettinger <python@rcn.com> parents: 34969 diff changeset	825 \begin{verbatim}
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement Raymond Hettinger <python@rcn.com> parents: 34969 diff changeset	826 >>> ' spacious '.strip()
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement Raymond Hettinger <python@rcn.com> parents: 34969 diff changeset	827 'spacious'
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement Raymond Hettinger <python@rcn.com> parents: 34969 diff changeset	828 >>> 'www.example.com'.strip('cmowz.')
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement Raymond Hettinger <python@rcn.com> parents: 34969 diff changeset	829 'example'
5e511ddef48b SF bug #1202395: Description of string.lstrip() needs improvement Raymond Hettinger <python@rcn.com> parents: 34969 diff changeset	830 \end{verbatim}
26259 60d809a25bae Document that a minor feature was added in 2.2.2. ;-( Fred Drake <fdrake@acm.org> parents: 26161 diff changeset	831 \versionchanged[Support for the \var{chars} argument]{2.2.2}
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	832 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	833
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	834 \begin{methoddesc}[string]{swapcase}{}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	835 Return a copy of the string with uppercase characters converted to
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	836 lowercase and vice versa.
32214 6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749. Martin v. Löwis <martin@v.loewis.de> parents: 32197 diff changeset	837
6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749. Martin v. Löwis <martin@v.loewis.de> parents: 32197 diff changeset	838 For 8-bit strings, this method is locale-dependent.
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	839 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	840
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	841 \begin{methoddesc}[string]{title}{}
18416 33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18395 diff changeset	842 Return a titlecased version of the string: words start with uppercase
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	843 characters, all remaining cased characters are lowercase.
32214 6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749. Martin v. Löwis <martin@v.loewis.de> parents: 32197 diff changeset	844
6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749. Martin v. Löwis <martin@v.loewis.de> parents: 32197 diff changeset	845 For 8-bit strings, this method is locale-dependent.
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	846 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	847
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	848 \begin{methoddesc}[string]{translate}{table\optional{, deletechars}}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	849 Return a copy of the string where all characters occurring in the
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	850 optional argument \var{deletechars} are removed, and the remaining
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	851 characters have been mapped through the given translation table, which
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	852 must be a string of length 256.
29893 e9dddfd2a62f Discussion of signatures for unicode.translate() and str.translate() Raymond Hettinger <python@rcn.com> parents: 29590 diff changeset	853
e9dddfd2a62f Discussion of signatures for unicode.translate() and str.translate() Raymond Hettinger <python@rcn.com> parents: 29590 diff changeset	854 For Unicode objects, the \method{translate()} method does not
e9dddfd2a62f Discussion of signatures for unicode.translate() and str.translate() Raymond Hettinger <python@rcn.com> parents: 29590 diff changeset	855 accept the optional \var{deletechars} argument. Instead, it
e9dddfd2a62f Discussion of signatures for unicode.translate() and str.translate() Raymond Hettinger <python@rcn.com> parents: 29590 diff changeset	856 returns a copy of the \var{s} where all characters have been mapped
e9dddfd2a62f Discussion of signatures for unicode.translate() and str.translate() Raymond Hettinger <python@rcn.com> parents: 29590 diff changeset	857 through the given translation table which must be a mapping of
e9dddfd2a62f Discussion of signatures for unicode.translate() and str.translate() Raymond Hettinger <python@rcn.com> parents: 29590 diff changeset	858 Unicode ordinals to Unicode ordinals, Unicode strings or \code{None}.
e9dddfd2a62f Discussion of signatures for unicode.translate() and str.translate() Raymond Hettinger <python@rcn.com> parents: 29590 diff changeset	859 Unmapped characters are left untouched. Characters mapped to \code{None}
e9dddfd2a62f Discussion of signatures for unicode.translate() and str.translate() Raymond Hettinger <python@rcn.com> parents: 29590 diff changeset	860 are deleted. Note, a more flexible approach is to create a custom
e9dddfd2a62f Discussion of signatures for unicode.translate() and str.translate() Raymond Hettinger <python@rcn.com> parents: 29590 diff changeset	861 character mapping codec using the \refmodule{codecs} module (see
e9dddfd2a62f Discussion of signatures for unicode.translate() and str.translate() Raymond Hettinger <python@rcn.com> parents: 29590 diff changeset	862 \module{encodings.cp1251} for an example).
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	863 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	864
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	865 \begin{methoddesc}[string]{upper}{}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	866 Return a copy of the string converted to uppercase.
32214 6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749. Martin v. Löwis <martin@v.loewis.de> parents: 32197 diff changeset	867
6478eb6ae3c0 Document string methods that are locale-dependent. Fixes #935749. Martin v. Löwis <martin@v.loewis.de> parents: 32197 diff changeset	868 For 8-bit strings, this method is locale-dependent.
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	869 \end{methoddesc}
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	870
23045 8b1268bc371a Apply the second version of SF patch http://www.python.org/sf/536241 Walter Dörwald <walter@livinglogic.de> parents: 23017 diff changeset	871 \begin{methoddesc}[string]{zfill}{width}
8b1268bc371a Apply the second version of SF patch http://www.python.org/sf/536241 Walter Dörwald <walter@livinglogic.de> parents: 23017 diff changeset	872 Return the numeric string left filled with zeros in a string
8b1268bc371a Apply the second version of SF patch http://www.python.org/sf/536241 Walter Dörwald <walter@livinglogic.de> parents: 23017 diff changeset	873 of length \var{width}. The original string is returned if
8b1268bc371a Apply the second version of SF patch http://www.python.org/sf/536241 Walter Dörwald <walter@livinglogic.de> parents: 23017 diff changeset	874 \var{width} is less than \code{len(\var{s})}.
26260 b327ffcfe9b7 Better note that str.zfill() was added in 2.2.2 as well. ;-( Fred Drake <fdrake@acm.org> parents: 26259 diff changeset	875 \versionadded{2.2.2}
23045 8b1268bc371a Apply the second version of SF patch http://www.python.org/sf/536241 Walter Dörwald <walter@livinglogic.de> parents: 23017 diff changeset	876 \end{methoddesc}
8b1268bc371a Apply the second version of SF patch http://www.python.org/sf/536241 Walter Dörwald <walter@livinglogic.de> parents: 23017 diff changeset	877
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	878
4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	879 \subsubsection{String Formatting Operations \label{typesseq-strings}}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	880
21177 7d1eac41ce3e Slightly improved indexing for the string-% operator, thanks to comments Fred Drake <fdrake@acm.org> parents: 21163 diff changeset	881 \index{formatting, string (\%{})}
21542 5d4135609efc Added index entries similar to some recommended by Skip, and used the word Fred Drake <fdrake@acm.org> parents: 21332 diff changeset	882 \index{interpolation, string (\%{})}
14552 a8d1c030b19f Add some index entries to make it easier to find information on Fred Drake <fdrake@acm.org> parents: 14520 diff changeset	883 \index{string!formatting}
21542 5d4135609efc Added index entries similar to some recommended by Skip, and used the word Fred Drake <fdrake@acm.org> parents: 21332 diff changeset	884 \index{string!interpolation}
14552 a8d1c030b19f Add some index entries to make it easier to find information on Fred Drake <fdrake@acm.org> parents: 14520 diff changeset	885 \index{printf-style formatting}
a8d1c030b19f Add some index entries to make it easier to find information on Fred Drake <fdrake@acm.org> parents: 14520 diff changeset	886 \index{sprintf-style formatting}
21177 7d1eac41ce3e Slightly improved indexing for the string-% operator, thanks to comments Fred Drake <fdrake@acm.org> parents: 21163 diff changeset	887 \index{\protect\%{} formatting}
21542 5d4135609efc Added index entries similar to some recommended by Skip, and used the word Fred Drake <fdrake@acm.org> parents: 21332 diff changeset	888 \index{\protect\%{} interpolation}
14552 a8d1c030b19f Add some index entries to make it easier to find information on Fred Drake <fdrake@acm.org> parents: 14520 diff changeset	889
16285 15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	890 String and Unicode objects have one unique built-in operation: the
21542 5d4135609efc Added index entries similar to some recommended by Skip, and used the word Fred Drake <fdrake@acm.org> parents: 21332 diff changeset	891 \code{\%} operator (modulo). This is also known as the string
5d4135609efc Added index entries similar to some recommended by Skip, and used the word Fred Drake <fdrake@acm.org> parents: 21332 diff changeset	892 \emph{formatting} or \emph{interpolation} operator. Given
5d4135609efc Added index entries similar to some recommended by Skip, and used the word Fred Drake <fdrake@acm.org> parents: 21332 diff changeset	893 \code{\var{format} \% \var{values}} (where \var{format} is a string or
5d4135609efc Added index entries similar to some recommended by Skip, and used the word Fred Drake <fdrake@acm.org> parents: 21332 diff changeset	894 Unicode object), \code{\%} conversion specifications in \var{format}
5d4135609efc Added index entries similar to some recommended by Skip, and used the word Fred Drake <fdrake@acm.org> parents: 21332 diff changeset	895 are replaced with zero or more elements of \var{values}. The effect
5d4135609efc Added index entries similar to some recommended by Skip, and used the word Fred Drake <fdrake@acm.org> parents: 21332 diff changeset	896 is similar to the using \cfunction{sprintf()} in the C language. If
5d4135609efc Added index entries similar to some recommended by Skip, and used the word Fred Drake <fdrake@acm.org> parents: 21332 diff changeset	897 \var{format} is a Unicode object, or if any of the objects being
5d4135609efc Added index entries similar to some recommended by Skip, and used the word Fred Drake <fdrake@acm.org> parents: 21332 diff changeset	898 converted using the \code{\%s} conversion are Unicode objects, the
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	899 result will also be a Unicode object.
16285 15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	900
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	901 If \var{format} requires a single argument, \var{values} may be a
31286 3894654b4848 fix a variety of markup bugs Fred Drake <fdrake@acm.org> parents: 31282 diff changeset	902 single non-tuple object.\footnote{To format only a tuple you
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	903 should therefore provide a singleton tuple whose only element
63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	904 is the tuple to be formatted.} Otherwise, \var{values} must be a tuple with
16285 15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	905 exactly the number of items specified by the format string, or a
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	906 single mapping object (for example, a dictionary).
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	907
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	908 A conversion specifier contains two or more characters and has the
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	909 following components, which must occur in this order:
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	910
16285 15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	911 \begin{enumerate}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	912 \item The \character{\%} character, which marks the start of the
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	913 specifier.
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	914 \item Mapping key (optional), consisting of a parenthesised sequence
63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	915 of characters (for example, \code{(somename)}).
16285 15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	916 \item Conversion flags (optional), which affect the result of some
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	917 conversion types.
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	918 \item Minimum field width (optional). If specified as an
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	919 \character{*} (asterisk), the actual width is read from the
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	920 next element of the tuple in \var{values}, and the object to
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	921 convert comes after the minimum field width and optional
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	922 precision.
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	923 \item Precision (optional), given as a \character{.} (dot) followed
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	924 by the precision. If specified as \character{*} (an
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	925 asterisk), the actual width is read from the next element of
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	926 the tuple in \var{values}, and the value to convert comes after
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	927 the precision.
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	928 \item Length modifier (optional).
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	929 \item Conversion type.
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	930 \end{enumerate}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	931
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	932 When the right argument is a dictionary (or other mapping type), then
63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	933 the formats in the string \emph{must} include a parenthesised mapping key into
16285 15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	934 that dictionary inserted immediately after the \character{\%}
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	935 character. The mapping key selects the value to be formatted from the
16285 15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	936 mapping. For example:
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	937
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	938 \begin{verbatim}
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	939 >>> print '%(language)s has %(#)03d quote types.' % \
63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	940 {'language': "Python", "#": 2}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	941 Python has 002 quote types.
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	942 \end{verbatim}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	943
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	944 In this case no \code{*} specifiers may occur in a format (since they
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	945 require a sequential parameter list).
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	946
16285 15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	947 The conversion flag characters are:
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	948
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	949 \begin{tableii}{c\|l}{character}{Flag}{Meaning}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	950 \lineii{\#}{The value conversion will use the ``alternate form''
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	951 (where defined below).}
27919 4b5c2e025c5e Fix SF bug #687655, String formatting conversions misleading Neal Norwitz <nnorwitz@gmail.com> parents: 27225 diff changeset	952 \lineii{0}{The conversion will be zero padded for numeric values.}
16285 15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	953 \lineii{-}{The converted value is left adjusted (overrides
25906 50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	954 the \character{0} conversion if both are given).}
16285 15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	955 \lineii{{~}}{(a space) A blank should be left before a positive number
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	956 (or empty string) produced by a signed conversion.}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	957 \lineii{+}{A sign character (\character{+} or \character{-}) will
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	958 precede the conversion (overrides a "space" flag).}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	959 \end{tableii}
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	960
36166 6f25029de9db Bug #1394868: doc typos Georg Brandl <georg@python.org> parents: 36135 diff changeset	961 A length modifier (\code{h}, \code{l}, or \code{L}) may be
6f25029de9db Bug #1394868: doc typos Georg Brandl <georg@python.org> parents: 36135 diff changeset	962 present, but is ignored as it is not necessary for Python.
16285 15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	963
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	964 The conversion types are:
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	965
25906 50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	966 \begin{tableiii}{c\|l\|c}{character}{Conversion}{Meaning}{Notes}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	967 \lineiii{d}{Signed integer decimal.}{}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	968 \lineiii{i}{Signed integer decimal.}{}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	969 \lineiii{o}{Unsigned octal.}{(1)}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	970 \lineiii{u}{Unsigned decimal.}{}
34296 67f2190e1f6d SF Patch #1093896: miscellaneous doc typos Raymond Hettinger <python@rcn.com> parents: 34076 diff changeset	971 \lineiii{x}{Unsigned hexadecimal (lowercase).}{(2)}
67f2190e1f6d SF Patch #1093896: miscellaneous doc typos Raymond Hettinger <python@rcn.com> parents: 34076 diff changeset	972 \lineiii{X}{Unsigned hexadecimal (uppercase).}{(2)}
25906 50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	973 \lineiii{e}{Floating point exponential format (lowercase).}{}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	974 \lineiii{E}{Floating point exponential format (uppercase).}{}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	975 \lineiii{f}{Floating point decimal format.}{}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	976 \lineiii{F}{Floating point decimal format.}{}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	977 \lineiii{g}{Same as \character{e} if exponent is greater than -4 or
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	978 less than precision, \character{f} otherwise.}{}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	979 \lineiii{G}{Same as \character{E} if exponent is greater than -4 or
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	980 less than precision, \character{F} otherwise.}{}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	981 \lineiii{c}{Single character (accepts integer or single character
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	982 string).}{}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	983 \lineiii{r}{String (converts any python object using
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	984 \function{repr()}).}{(3)}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	985 \lineiii{s}{String (converts any python object using
27225 5d42dba49fe5 SF patch 664183 and SF bug 664044: Note that both u'%s' % 'x' and Raymond Hettinger <python@rcn.com> parents: 27036 diff changeset	986 \function{str()}).}{(4)}
25906 50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	987 \lineiii{\%}{No argument is converted, results in a \character{\%}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	988 character in the result.}{}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	989 \end{tableiii}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	990
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	991 \noindent
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	992 Notes:
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	993 \begin{description}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	994 \item[(1)]
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	995 The alternate form causes a leading zero (\character{0}) to be
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	996 inserted between left-hand padding and the formatting of the
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	997 number if the leading character of the result is not already a
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	998 zero.
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	999 \item[(2)]
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	1000 The alternate form causes a leading \code{'0x'} or \code{'0X'}
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	1001 (depending on whether the \character{x} or \character{X} format
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	1002 was used) to be inserted between left-hand padding and the
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	1003 formatting of the number if the leading character of the result is
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	1004 not already a zero.
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	1005 \item[(3)]
50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	1006 The \code{\%r} conversion was added in Python 2.0.
27225 5d42dba49fe5 SF patch 664183 and SF bug 664044: Note that both u'%s' % 'x' and Raymond Hettinger <python@rcn.com> parents: 27036 diff changeset	1007 \item[(4)]
5d42dba49fe5 SF patch 664183 and SF bug 664044: Note that both u'%s' % 'x' and Raymond Hettinger <python@rcn.com> parents: 27036 diff changeset	1008 If the object or format provided is a \class{unicode} string,
5d42dba49fe5 SF patch 664183 and SF bug 664044: Note that both u'%s' % 'x' and Raymond Hettinger <python@rcn.com> parents: 27036 diff changeset	1009 the resulting string will also be \class{unicode}.
25906 50905db35da5 - The "-" format flag overrides the "0" flag, not the "-" flag. Fred Drake <fdrake@acm.org> parents: 25393 diff changeset	1010 \end{description}
16285 15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	1011
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	1012 % XXX Examples?
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	1013
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	1014 Since Python strings have an explicit length, \code{\%s} conversions
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	1015 do not assume that \code{'\e0'} is the end of the string.
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	1016
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	1017 For safety reasons, floating point precisions are clipped to 50;
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	1018 \code{\%f} conversions for numbers whose absolute value is over 1e25
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	1019 are replaced by \code{\%g} conversions.\footnote{
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	1020 These numbers are fairly arbitrary. They are intended to
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	1021 avoid printing endless strings of meaningless digits without hampering
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	1022 correct use and without having to know the exact precision of floating
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	1023 point values on a particular machine.
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	1024 } All other errors raise exceptions.
15e0c10092bb Massively improved documentation for string formatting operations, Fred Drake <fdrake@acm.org> parents: 15926 diff changeset	1025
21163 7b6879714b74 Make no assumption about how modules are built when referring to them; this Fred Drake <fdrake@acm.org> parents: 21159 diff changeset	1026 Additional string operations are defined in standard modules
31286 3894654b4848 fix a variety of markup bugs Fred Drake <fdrake@acm.org> parents: 31282 diff changeset	1027 \refmodule{string}\refstmodindex{string}\ and
22241 7584b6f1afde Change Windows file.truncate() to (a) restore the original file position, Tim Peters <tim.peters@gmail.com> parents: 22214 diff changeset	1028 \refmodule{re}.\refstmodindex{re}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1029
13967 7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach Fred Drake <fdrake@acm.org> parents: 13933 diff changeset	1030
14044 a905c5aa0691 As pointed out by Denis S. Otkidach <den@analyt.chem.msu.ru>, xrange() Fred Drake <fdrake@acm.org> parents: 13967 diff changeset	1031 \subsubsection{XRange Type \label{typesseq-xrange}}
13967 7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach Fred Drake <fdrake@acm.org> parents: 13933 diff changeset	1032
31286 3894654b4848 fix a variety of markup bugs Fred Drake <fdrake@acm.org> parents: 31282 diff changeset	1033 The \class{xrange}\obindex{xrange} type is an immutable sequence which
3894654b4848 fix a variety of markup bugs Fred Drake <fdrake@acm.org> parents: 31282 diff changeset	1034 is commonly used for looping. The advantage of the \class{xrange}
3894654b4848 fix a variety of markup bugs Fred Drake <fdrake@acm.org> parents: 31282 diff changeset	1035 type is that an \class{xrange} object will always take the same amount
3894654b4848 fix a variety of markup bugs Fred Drake <fdrake@acm.org> parents: 31282 diff changeset	1036 of memory, no matter the size of the range it represents. There are
3894654b4848 fix a variety of markup bugs Fred Drake <fdrake@acm.org> parents: 31282 diff changeset	1037 no consistent performance advantages.
13967 7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach Fred Drake <fdrake@acm.org> parents: 13933 diff changeset	1038
26592 0c646baeec58 Update comments about the performance of xrange(). Raymond Hettinger <python@rcn.com> parents: 26514 diff changeset	1039 XRange objects have very little behavior: they only support indexing,
0c646baeec58 Update comments about the performance of xrange(). Raymond Hettinger <python@rcn.com> parents: 26514 diff changeset	1040 iteration, and the \function{len()} function.
13967 7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach Fred Drake <fdrake@acm.org> parents: 13933 diff changeset	1041
7b7ee58901fb Document the range type, as suggested by Denis S. Otkidach Fred Drake <fdrake@acm.org> parents: 13933 diff changeset	1042
10156 0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	1043 \subsubsection{Mutable Sequence Types \label{typesseq-mutable}}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1044
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1045 List objects support additional operations that allow in-place
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1046 modification of the object.
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	1047 Other mutable sequence types (when added to the language) should
63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	1048 also support these operations.
63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	1049 Strings and tuples are immutable sequence types: such objects cannot
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1050 be modified once created.
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1051 The following operations are defined on mutable sequence types (where
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1052 \var{x} is an arbitrary object):
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1053 \indexiii{mutable}{sequence}{types}
15005 0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	1054 \obindex{list}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1055
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1056 \begin{tableiii}{c\|l\|c}{code}{Operation}{Result}{Notes}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1057 \lineiii{\var{s}[\var{i}] = \var{x}}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1058 {item \var{i} of \var{s} is replaced by \var{x}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1059 \lineiii{\var{s}[\var{i}:\var{j}] = \var{t}}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1060 {slice of \var{s} from \var{i} to \var{j} is replaced by \var{t}}{}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1061 \lineiii{del \var{s}[\var{i}:\var{j}]}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1062 {same as \code{\var{s}[\var{i}:\var{j}] = []}}{}
28171 24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1063 \lineiii{\var{s}[\var{i}:\var{j}:\var{k}] = \var{t}}
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1064 {the elements of \code{\var{s}[\var{i}:\var{j}:\var{k}]} are replaced by those of \var{t}}{(1)}
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1065 \lineiii{del \var{s}[\var{i}:\var{j}:\var{k}]}
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1066 {removes the elements of \code{\var{s}[\var{i}:\var{j}:\var{k}]} from the list}{}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1067 \lineiii{\var{s}.append(\var{x})}
28171 24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1068 {same as \code{\var{s}[len(\var{s}):len(\var{s})] = [\var{x}]}}{(2)}
9318 8a26e55e18b8 Document the new list.extend() method. Interesting enough, the Barry Warsaw <barry@python.org> parents: 9083 diff changeset	1069 \lineiii{\var{s}.extend(\var{x})}
28171 24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1070 {same as \code{\var{s}[len(\var{s}):len(\var{s})] = \var{x}}}{(3)}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1071 \lineiii{\var{s}.count(\var{x})}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1072 {return number of \var{i}'s for which \code{\var{s}[\var{i}] == \var{x}}}{}
29516 d761ff55b3be Updated documentation for the new slice arguments for list.index(). Walter Dörwald <walter@livinglogic.de> parents: 29343 diff changeset	1073 \lineiii{\var{s}.index(\var{x}\optional{, \var{i}\optional{, \var{j}}})}
d761ff55b3be Updated documentation for the new slice arguments for list.index(). Walter Dörwald <walter@livinglogic.de> parents: 29343 diff changeset	1074 {return smallest \var{k} such that \code{\var{s}[\var{k}] == \var{x}} and
d761ff55b3be Updated documentation for the new slice arguments for list.index(). Walter Dörwald <walter@livinglogic.de> parents: 29343 diff changeset	1075 \code{\var{i} <= \var{k} < \var{j}}}{(4)}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1076 \lineiii{\var{s}.insert(\var{i}, \var{x})}
28606 436d812f2b94 - list.insert(i, x) now interprets negative i as it would be Guido van Rossum <guido@python.org> parents: 28337 diff changeset	1077 {same as \code{\var{s}[\var{i}:\var{i}] = [\var{x}]}}{(5)}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1078 \lineiii{\var{s}.pop(\optional{\var{i}})}
28171 24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1079 {same as \code{\var{x} = \var{s}[\var{i}]; del \var{s}[\var{i}]; return \var{x}}}{(6)}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1080 \lineiii{\var{s}.remove(\var{x})}
28171 24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1081 {same as \code{del \var{s}[\var{s}.index(\var{x})]}}{(4)}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1082 \lineiii{\var{s}.reverse()}
28171 24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1083 {reverses the items of \var{s} in place}{(7)}
31286 3894654b4848 fix a variety of markup bugs Fred Drake <fdrake@acm.org> parents: 31282 diff changeset	1084 \lineiii{\var{s}.sort(\optional{\var{cmp}\optional{,
3894654b4848 fix a variety of markup bugs Fred Drake <fdrake@acm.org> parents: 31282 diff changeset	1085 \var{key}\optional{, \var{reverse}}}})}
28171 24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1086 {sort the items of \var{s} in place}{(7), (8), (9), (10)}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1087 \end{tableiii}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1088 \indexiv{operations on}{mutable}{sequence}{types}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1089 \indexiii{operations on}{sequence}{types}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1090 \indexiii{operations on}{list}{type}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1091 \indexii{subscript}{assignment}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1092 \indexii{slice}{assignment}
28171 24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1093 \indexii{extended slice}{assignment}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1094 \stindex{del}
10156 0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	1095 \withsubitem{(list method)}{
11183 1e0b1967be7f In note mentioning [].remove()'s exception, tell what exception is Fred Drake <fdrake@acm.org> parents: 11100 diff changeset	1096 \ttindex{append()}\ttindex{extend()}\ttindex{count()}\ttindex{index()}
1e0b1967be7f In note mentioning [].remove()'s exception, tell what exception is Fred Drake <fdrake@acm.org> parents: 11100 diff changeset	1097 \ttindex{insert()}\ttindex{pop()}\ttindex{remove()}\ttindex{reverse()}
9523 ed6cacddc6c6 Fix indexing of func_code attribute; this is on a function, not a code Fred Drake <fdrake@acm.org> parents: 9461 diff changeset	1098 \ttindex{sort()}}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1099 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1100 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1101 \begin{description}
28171 24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1102 \item[(1)] \var{t} must have the same length as the slice it is
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1103 replacing.
23778 245224d1b8c9 This is my nearly two year old patch Michael W. Hudson <mwh@python.net> parents: 23515 diff changeset	1104
28171 24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1105 \item[(2)] The C implementation of Python has historically accepted
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1106 multiple parameters and implicitly joined them into a tuple; this
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1107 no longer works in Python 2.0. Use of this misfeature has been
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1108 deprecated since Python 1.4.
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	1109
34573 19327db75d1c SF bug #1119700: list extend() accepts args besides lists Raymond Hettinger <python@rcn.com> parents: 34508 diff changeset	1110 \item[(3)] \var{x} can be any iterable object.
28171 24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1111
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1112 \item[(4)] Raises \exception{ValueError} when \var{x} is not found in
29516 d761ff55b3be Updated documentation for the new slice arguments for list.index(). Walter Dörwald <walter@livinglogic.de> parents: 29343 diff changeset	1113 \var{s}. When a negative index is passed as the second or third parameter
d761ff55b3be Updated documentation for the new slice arguments for list.index(). Walter Dörwald <walter@livinglogic.de> parents: 29343 diff changeset	1114 to the \method{index()} method, the list length is added, as for slice
d761ff55b3be Updated documentation for the new slice arguments for list.index(). Walter Dörwald <walter@livinglogic.de> parents: 29343 diff changeset	1115 indices. If it is still negative, it is truncated to zero, as for
d761ff55b3be Updated documentation for the new slice arguments for list.index(). Walter Dörwald <walter@livinglogic.de> parents: 29343 diff changeset	1116 slice indices. \versionchanged[Previously, \method{index()} didn't
d761ff55b3be Updated documentation for the new slice arguments for list.index(). Walter Dörwald <walter@livinglogic.de> parents: 29343 diff changeset	1117 have arguments for specifying start and stop positions]{2.3}
11183 1e0b1967be7f In note mentioning [].remove()'s exception, tell what exception is Fred Drake <fdrake@acm.org> parents: 11100 diff changeset	1118
28171 24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1119 \item[(5)] When a negative index is passed as the first parameter to
28606 436d812f2b94 - list.insert(i, x) now interprets negative i as it would be Guido van Rossum <guido@python.org> parents: 28337 diff changeset	1120 the \method{insert()} method, the list length is added, as for slice
436d812f2b94 - list.insert(i, x) now interprets negative i as it would be Guido van Rossum <guido@python.org> parents: 28337 diff changeset	1121 indices. If it is still negative, it is truncated to zero, as for
436d812f2b94 - list.insert(i, x) now interprets negative i as it would be Guido van Rossum <guido@python.org> parents: 28337 diff changeset	1122 slice indices. \versionchanged[Previously, all negative indices
436d812f2b94 - list.insert(i, x) now interprets negative i as it would be Guido van Rossum <guido@python.org> parents: 28337 diff changeset	1123 were truncated to zero]{2.3}
20701 5f6850d1f9e8 Explain what [].insert() does when the target index is negative. Fred Drake <fdrake@acm.org> parents: 20580 diff changeset	1124
28171 24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1125 \item[(6)] The \method{pop()} method is only supported by the list and
13777 b3903e05017f Stop lying about [].pop() being experimental! There is no backing it out Fred Drake <fdrake@acm.org> parents: 13772 diff changeset	1126 array types. The optional argument \var{i} defaults to \code{-1},
b3903e05017f Stop lying about [].pop() being experimental! There is no backing it out Fred Drake <fdrake@acm.org> parents: 13772 diff changeset	1127 so that by default the last item is removed and returned.
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	1128
28171 24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1129 \item[(7)] The \method{sort()} and \method{reverse()} methods modify the
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	1130 list in place for economy of space when sorting or reversing a large
18829 1bc1fdf1482b trivial rewording in footnote 5. Skip Montanaro <skip@pobox.com> parents: 18416 diff changeset	1131 list. To remind you that they operate by side effect, they don't return
1bc1fdf1482b trivial rewording in footnote 5. Skip Montanaro <skip@pobox.com> parents: 18416 diff changeset	1132 the sorted or reversed list.
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	1133
31210 c06b570adf12 Guido grants a Christmas wish: Raymond Hettinger <python@rcn.com> parents: 31206 diff changeset	1134 \item[(8)] The \method{sort()} method takes optional arguments for
33448 5570fae1f01c Typo fix: 'comparisions' is not a word Andrew M. Kuchling <amk@amk.ca> parents: 33412 diff changeset	1135 controlling the comparisons.
30697 1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse. Raymond Hettinger <python@rcn.com> parents: 30413 diff changeset	1136
1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse. Raymond Hettinger <python@rcn.com> parents: 30413 diff changeset	1137 \var{cmp} specifies a custom comparison function of two arguments
1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse. Raymond Hettinger <python@rcn.com> parents: 30413 diff changeset	1138 (list items) which should return a negative, zero or positive number
1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse. Raymond Hettinger <python@rcn.com> parents: 30413 diff changeset	1139 depending on whether the first argument is considered smaller than,
1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse. Raymond Hettinger <python@rcn.com> parents: 30413 diff changeset	1140 equal to, or larger than the second argument:
1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse. Raymond Hettinger <python@rcn.com> parents: 30413 diff changeset	1141 \samp{\var{cmp}=\keyword{lambda} \var{x},\var{y}:
1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse. Raymond Hettinger <python@rcn.com> parents: 30413 diff changeset	1142 \function{cmp}(x.lower(), y.lower())}
1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse. Raymond Hettinger <python@rcn.com> parents: 30413 diff changeset	1143
1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse. Raymond Hettinger <python@rcn.com> parents: 30413 diff changeset	1144 \var{key} specifies a function of one argument that is used to
1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse. Raymond Hettinger <python@rcn.com> parents: 30413 diff changeset	1145 extract a comparison key from each list element:
34076 43c00f0e6305 Fix typo. Raymond Hettinger <python@rcn.com> parents: 34029 diff changeset	1146 \samp{\var{key}=\function{str.lower}}
30697 1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse. Raymond Hettinger <python@rcn.com> parents: 30413 diff changeset	1147
1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse. Raymond Hettinger <python@rcn.com> parents: 30413 diff changeset	1148 \var{reverse} is a boolean value. If set to \code{True}, then the
1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse. Raymond Hettinger <python@rcn.com> parents: 30413 diff changeset	1149 list elements are sorted as if each comparison were reversed.
1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse. Raymond Hettinger <python@rcn.com> parents: 30413 diff changeset	1150
1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse. Raymond Hettinger <python@rcn.com> parents: 30413 diff changeset	1151 In general, the \var{key} and \var{reverse} conversion processes are
1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse. Raymond Hettinger <python@rcn.com> parents: 30413 diff changeset	1152 much faster than specifying an equivalent \var{cmp} function. This is
1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse. Raymond Hettinger <python@rcn.com> parents: 30413 diff changeset	1153 because \var{cmp} is called multiple times for each list element while
30737 38b0b7d41936 markup fixes; this would not format Fred Drake <fdrake@acm.org> parents: 30707 diff changeset	1154 \var{key} and \var{reverse} touch each element only once.
30697 1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse. Raymond Hettinger <python@rcn.com> parents: 30413 diff changeset	1155
28337 90f17c374f59 - added example of using a comparison function with list.sort(), and Fred Drake <fdrake@acm.org> parents: 28211 diff changeset	1156 \versionchanged[Support for \code{None} as an equivalent to omitting
31286 3894654b4848 fix a variety of markup bugs Fred Drake <fdrake@acm.org> parents: 31282 diff changeset	1157 \var{cmp} was added]{2.3}
28337 90f17c374f59 - added example of using a comparison function with list.sort(), and Fred Drake <fdrake@acm.org> parents: 28211 diff changeset	1158
30737 38b0b7d41936 markup fixes; this would not format Fred Drake <fdrake@acm.org> parents: 30707 diff changeset	1159 \versionchanged[Support for \var{key} and \var{reverse} was added]{2.4}
28337 90f17c374f59 - added example of using a comparison function with list.sort(), and Fred Drake <fdrake@acm.org> parents: 28211 diff changeset	1160
31286 3894654b4848 fix a variety of markup bugs Fred Drake <fdrake@acm.org> parents: 31282 diff changeset	1161 \item[(9)] Starting with Python 2.3, the \method{sort()} method is
31210 c06b570adf12 Guido grants a Christmas wish: Raymond Hettinger <python@rcn.com> parents: 31206 diff changeset	1162 guaranteed to be stable. A sort is stable if it guarantees not to
30697 1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse. Raymond Hettinger <python@rcn.com> parents: 30413 diff changeset	1163 change the relative order of elements that compare equal --- this is
1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse. Raymond Hettinger <python@rcn.com> parents: 30413 diff changeset	1164 helpful for sorting in multiple passes (for example, sort by
1345c23a0591 * list.sort() now supports three keyword arguments: cmp, key, and reverse. Raymond Hettinger <python@rcn.com> parents: 30413 diff changeset	1165 department, then by salary grade).
26161 dd10d97d329a SF patch 637176: list.sort crasher Tim Peters <tim.peters@gmail.com> parents: 25906 diff changeset	1166
28171 24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1167 \item[(10)] While a list is being sorted, the effect of attempting to
31286 3894654b4848 fix a variety of markup bugs Fred Drake <fdrake@acm.org> parents: 31282 diff changeset	1168 mutate, or even inspect, the list is undefined. The C
3894654b4848 fix a variety of markup bugs Fred Drake <fdrake@acm.org> parents: 31282 diff changeset	1169 implementation of Python 2.3 and newer makes the list appear empty
3894654b4848 fix a variety of markup bugs Fred Drake <fdrake@acm.org> parents: 31282 diff changeset	1170 for the duration, and raises \exception{ValueError} if it can detect
3894654b4848 fix a variety of markup bugs Fred Drake <fdrake@acm.org> parents: 31282 diff changeset	1171 that the list has been mutated during a sort.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1172 \end{description}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1173
35073 db1676fdb5b9 SF bug #1215887: String and list methods documentation deeply hidden Raymond Hettinger <python@rcn.com> parents: 34976 diff changeset	1174 \subsection{Set Types ---
db1676fdb5b9 SF bug #1215887: String and list methods documentation deeply hidden Raymond Hettinger <python@rcn.com> parents: 34976 diff changeset	1175 \class{set}, \class{frozenset}
db1676fdb5b9 SF bug #1215887: String and list methods documentation deeply hidden Raymond Hettinger <python@rcn.com> parents: 34976 diff changeset	1176 \label{types-set}}
31008 4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1177 \obindex{set}
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1178
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1179 A \dfn{set} object is an unordered collection of immutable values.
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1180 Common uses include membership testing, removing duplicates from a sequence,
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1181 and computing mathematical operations such as intersection, union, difference,
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1182 and symmetric difference.
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1183 \versionadded{2.4}
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1184
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1185 Like other collections, sets support \code{\var{x} in \var{set}},
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1186 \code{len(\var{set})}, and \code{for \var{x} in \var{set}}. Being an
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1187 unordered collection, sets do not record element position or order of
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1188 insertion. Accordingly, sets do not support indexing, slicing, or
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1189 other sequence-like behavior.
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1190
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1191 There are currently two builtin set types, \class{set} and \class{frozenset}.
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1192 The \class{set} type is mutable --- the contents can be changed using methods
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1193 like \method{add()} and \method{remove()}. Since it is mutable, it has no
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1194 hash value and cannot be used as either a dictionary key or as an element of
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1195 another set. The \class{frozenset} type is immutable and hashable --- its
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1196 contents cannot be altered after is created; however, it can be used as
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1197 a dictionary key or as an element of another set.
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1198
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1199 Instances of \class{set} and \class{frozenset} provide the following operations:
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1200
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1201 \begin{tableiii}{c\|c\|l}{code}{Operation}{Equivalent}{Result}
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1202 \lineiii{len(\var{s})}{}{cardinality of set \var{s}}
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1203
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1204 \hline
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1205 \lineiii{\var{x} in \var{s}}{}
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1206 {test \var{x} for membership in \var{s}}
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1207 \lineiii{\var{x} not in \var{s}}{}
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1208 {test \var{x} for non-membership in \var{s}}
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1209 \lineiii{\var{s}.issubset(\var{t})}{\code{\var{s} <= \var{t}}}
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1210 {test whether every element in \var{s} is in \var{t}}
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1211 \lineiii{\var{s}.issuperset(\var{t})}{\code{\var{s} >= \var{t}}}
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1212 {test whether every element in \var{t} is in \var{s}}
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1213
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1214 \hline
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1215 \lineiii{\var{s}.union(\var{t})}{\var{s} \| \var{t}}
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1216 {new set with elements from both \var{s} and \var{t}}
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1217 \lineiii{\var{s}.intersection(\var{t})}{\var{s} \&\ \var{t}}
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1218 {new set with elements common to \var{s} and \var{t}}
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1219 \lineiii{\var{s}.difference(\var{t})}{\var{s} - \var{t}}
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1220 {new set with elements in \var{s} but not in \var{t}}
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1221 \lineiii{\var{s}.symmetric_difference(\var{t})}{\var{s} \^\ \var{t}}
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1222 {new set with elements in either \var{s} or \var{t} but not both}
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1223 \lineiii{\var{s}.copy()}{}
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1224 {new set with a shallow copy of \var{s}}
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1225 \end{tableiii}
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1226
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1227 Note, the non-operator versions of \method{union()}, \method{intersection()},
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1228 \method{difference()}, and \method{symmetric_difference()},
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1229 \method{issubset()}, and \method{issuperset()} methods will accept any
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1230 iterable as an argument. In contrast, their operator based counterparts
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1231 require their arguments to be sets. This precludes error-prone constructions
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1232 like \code{set('abc') \&\ 'cbs'} in favor of the more readable
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1233 \code{set('abc').intersection('cbs')}.
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1234
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1235 Both \class{set} and \class{frozenset} support set to set comparisons.
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1236 Two sets are equal if and only if every element of each set is contained in
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1237 the other (each is a subset of the other).
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1238 A set is less than another set if and only if the first set is a proper
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1239 subset of the second set (is a subset, but is not equal).
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1240 A set is greater than another set if and only if the first set is a proper
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1241 superset of the second set (is a superset, but is not equal).
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1242
34296 67f2190e1f6d SF Patch #1093896: miscellaneous doc typos Raymond Hettinger <python@rcn.com> parents: 34076 diff changeset	1243 Instances of \class{set} are compared to instances of \class{frozenset} based
32795 46e0431c9701 SF bug #995983 and #995987: Documentation nits. Raymond Hettinger <python@rcn.com> parents: 32459 diff changeset	1244 on their members. For example, \samp{set('abc') == frozenset('abc')} returns
46e0431c9701 SF bug #995983 and #995987: Documentation nits. Raymond Hettinger <python@rcn.com> parents: 32459 diff changeset	1245 \code{True}.
46e0431c9701 SF bug #995983 and #995987: Documentation nits. Raymond Hettinger <python@rcn.com> parents: 32459 diff changeset	1246
31008 4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1247 The subset and equality comparisons do not generalize to a complete
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1248 ordering function. For example, any two disjoint sets are not equal and
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1249 are not subsets of each other, so \emph{all} of the following return
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1250 \code{False}: \code{\var{a}<\var{b}}, \code{\var{a}==\var{b}}, or
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1251 \code{\var{a}>\var{b}}.
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1252 Accordingly, sets do not implement the \method{__cmp__} method.
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1253
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1254 Since sets only define partial ordering (subset relationships), the output
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1255 of the \method{list.sort()} method is undefined for lists of sets.
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1256
34898 fbcb1da480dd SF bug #1179957: Missing def'n of equality for set element Raymond Hettinger <python@rcn.com> parents: 34573 diff changeset	1257 Set elements are like dictionary keys; they need to define both
fbcb1da480dd SF bug #1179957: Missing def'n of equality for set element Raymond Hettinger <python@rcn.com> parents: 34573 diff changeset	1258 \method{__hash__} and \method{__eq__} methods.
fbcb1da480dd SF bug #1179957: Missing def'n of equality for set element Raymond Hettinger <python@rcn.com> parents: 34573 diff changeset	1259
32795 46e0431c9701 SF bug #995983 and #995987: Documentation nits. Raymond Hettinger <python@rcn.com> parents: 32459 diff changeset	1260 Binary operations that mix \class{set} instances with \class{frozenset}
46e0431c9701 SF bug #995983 and #995987: Documentation nits. Raymond Hettinger <python@rcn.com> parents: 32459 diff changeset	1261 return the type of the first operand. For example:
46e0431c9701 SF bug #995983 and #995987: Documentation nits. Raymond Hettinger <python@rcn.com> parents: 32459 diff changeset	1262 \samp{frozenset('ab') \| set('bc')} returns an instance of \class{frozenset}.
31008 4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1263
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1264 The following table lists operations available for \class{set}
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1265 that do not apply to immutable instances of \class{frozenset}:
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1266
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1267 \begin{tableiii}{c\|c\|l}{code}{Operation}{Equivalent}{Result}
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1268 \lineiii{\var{s}.update(\var{t})}
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1269 {\var{s} \|= \var{t}}
36135 14f002cd0371 Bug #1389673: document correct return value of set methods Georg Brandl <georg@python.org> parents: 36037 diff changeset	1270 {update set \var{s}, adding elements from \var{t}}
31008 4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1271 \lineiii{\var{s}.intersection_update(\var{t})}
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1272 {\var{s} \&= \var{t}}
36135 14f002cd0371 Bug #1389673: document correct return value of set methods Georg Brandl <georg@python.org> parents: 36037 diff changeset	1273 {update set \var{s}, keeping only elements found in both \var{s} and \var{t}}
31008 4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1274 \lineiii{\var{s}.difference_update(\var{t})}
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1275 {\var{s} -= \var{t}}
36135 14f002cd0371 Bug #1389673: document correct return value of set methods Georg Brandl <georg@python.org> parents: 36037 diff changeset	1276 {update set \var{s}, removing elements found in \var{t}}
31008 4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1277 \lineiii{\var{s}.symmetric_difference_update(\var{t})}
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1278 {\var{s} \textasciicircum= \var{t}}
36135 14f002cd0371 Bug #1389673: document correct return value of set methods Georg Brandl <georg@python.org> parents: 36037 diff changeset	1279 {update set \var{s}, keeping only elements found in either \var{s} or \var{t}
14f002cd0371 Bug #1389673: document correct return value of set methods Georg Brandl <georg@python.org> parents: 36037 diff changeset	1280 but not in both}
31008 4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1281
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1282 \hline
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1283 \lineiii{\var{s}.add(\var{x})}{}
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1284 {add element \var{x} to set \var{s}}
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1285 \lineiii{\var{s}.remove(\var{x})}{}
37064 64c83e0f683e More \exception fixes. Georg Brandl <georg@python.org> parents: 36656 diff changeset	1286 {remove \var{x} from set \var{s}; raises \exception{KeyError}
64c83e0f683e More \exception fixes. Georg Brandl <georg@python.org> parents: 36656 diff changeset	1287 if not present}
31008 4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1288 \lineiii{\var{s}.discard(\var{x})}{}
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1289 {removes \var{x} from set \var{s} if present}
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1290 \lineiii{\var{s}.pop()}{}
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1291 {remove and return an arbitrary element from \var{s}; raises
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1292 \exception{KeyError} if empty}
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1293 \lineiii{\var{s}.clear()}{}
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1294 {remove all elements from set \var{s}}
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1295 \end{tableiii}
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1296
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1297 Note, the non-operator versions of the \method{update()},
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1298 \method{intersection_update()}, \method{difference_update()}, and
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1299 \method{symmetric_difference_update()} methods will accept any iterable
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1300 as an argument.
4224d807911c * Checkin remaining documentation Raymond Hettinger <python@rcn.com> parents: 30813 diff changeset	1301
35186 a2043affd543 Cross reference the set built-ins with the sets module. Raymond Hettinger <python@rcn.com> parents: 35073 diff changeset	1302 The design of the set types was based on lessons learned from the
a2043affd543 Cross reference the set built-ins with the sets module. Raymond Hettinger <python@rcn.com> parents: 35073 diff changeset	1303 \module{sets} module.
a2043affd543 Cross reference the set built-ins with the sets module. Raymond Hettinger <python@rcn.com> parents: 35073 diff changeset	1304
a2043affd543 Cross reference the set built-ins with the sets module. Raymond Hettinger <python@rcn.com> parents: 35073 diff changeset	1305 \begin{seealso}
35686 f98792378954 fix link to subsection (SF bug #1311674) Fred Drake <fdrake@acm.org> parents: 35356 diff changeset	1306 \seelink{comparison-to-builtin-set.html}
f98792378954 fix link to subsection (SF bug #1311674) Fred Drake <fdrake@acm.org> parents: 35356 diff changeset	1307 {Comparison to the built-in set types}
f98792378954 fix link to subsection (SF bug #1311674) Fred Drake <fdrake@acm.org> parents: 35356 diff changeset	1308 {Differences between the \module{sets} module and the
f98792378954 fix link to subsection (SF bug #1311674) Fred Drake <fdrake@acm.org> parents: 35356 diff changeset	1309 built-in set types.}
35186 a2043affd543 Cross reference the set built-ins with the sets module. Raymond Hettinger <python@rcn.com> parents: 35073 diff changeset	1310 \end{seealso}
a2043affd543 Cross reference the set built-ins with the sets module. Raymond Hettinger <python@rcn.com> parents: 35073 diff changeset	1311
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1312
35356 3a2fff690558 Fix markup. Raymond Hettinger <python@rcn.com> parents: 35201 diff changeset	1313 \subsection{Mapping Types --- \class{dict} \label{typesmapping}}
15005 0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	1314 \obindex{mapping}
0cf5111bf09c Use \obindex{...} instead of \indexii{...}{type} in many places; this is Fred Drake <fdrake@acm.org> parents: 14710 diff changeset	1315 \obindex{dictionary}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1316
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	1317 A \dfn{mapping} object maps immutable values to
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1318 arbitrary objects. Mappings are mutable objects. There is currently
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1319 only one standard mapping type, the \dfn{dictionary}. A dictionary's keys are
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	1320 almost arbitrary values. Only values containing lists, dictionaries
63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	1321 or other mutable types (that are compared by value rather than by
63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	1322 object identity) may not be used as keys.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1323 Numeric types used for keys obey the normal rules for numeric
30413 53f1c32ee69d SF bug #804280: fromkeys is not listed in index Raymond Hettinger <python@rcn.com> parents: 30375 diff changeset	1324 comparison: if two numbers compare equal (such as \code{1} and
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1325 \code{1.0}) then they can be used interchangeably to index the same
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1326 dictionary entry.
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1327
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1328 Dictionaries are created by placing a comma-separated list of
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1329 \code{\var{key}: \var{value}} pairs within braces, for example:
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1330 \code{\{'jack': 4098, 'sjoerd': 4127\}} or
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1331 \code{\{4098: 'jack', 4127: 'sjoerd'\}}.
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1332
10968 5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1333 The following operations are defined on mappings (where \var{a} and
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1334 \var{b} are mappings, \var{k} is a key, and \var{v} and \var{x} are
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1335 arbitrary objects):
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1336 \indexiii{operations on}{mapping}{types}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1337 \indexiii{operations on}{dictionary}{type}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1338 \stindex{del}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1339 \bifuncindex{len}
10156 0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	1340 \withsubitem{(dictionary method)}{
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	1341 \ttindex{clear()}
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	1342 \ttindex{copy()}
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	1343 \ttindex{has_key()}
30413 53f1c32ee69d SF bug #804280: fromkeys is not listed in index Raymond Hettinger <python@rcn.com> parents: 30375 diff changeset	1344 \ttindex{fromkeys()}
10156 0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	1345 \ttindex{items()}
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	1346 \ttindex{keys()}
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	1347 \ttindex{update()}
0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	1348 \ttindex{values()}
28171 24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1349 \ttindex{get()}
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1350 \ttindex{setdefault()}
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1351 \ttindex{pop()}
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1352 \ttindex{popitem()}
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1353 \ttindex{iteritems()}
29067 04065c4a1c6b Missing parenthesis found by texcheck.py Raymond Hettinger <python@rcn.com> parents: 29065 diff changeset	1354 \ttindex{iterkeys()}
28171 24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1355 \ttindex{itervalues()}}
10968 5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1356
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1357 \begin{tableiii}{c\|l\|c}{code}{Operation}{Result}{Notes}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1358 \lineiii{len(\var{a})}{the number of items in \var{a}}{}
36656 92ce8bb8b12a - Patch 1433928: Guido van Rossum <guido@python.org> parents: 36580 diff changeset	1359 \lineiii{\var{a}[\var{k}]}{the item of \var{a} with key \var{k}}{(1), (10)}
13764 fdbc8730d356 Two minor nits from Gerry Weiner (no working email address) about Fred Drake <fdrake@acm.org> parents: 13222 diff changeset	1360 \lineiii{\var{a}[\var{k}] = \var{v}}
fdbc8730d356 Two minor nits from Gerry Weiner (no working email address) about Fred Drake <fdrake@acm.org> parents: 13222 diff changeset	1361 {set \code{\var{a}[\var{k}]} to \var{v}}
10968 5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1362 {}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1363 \lineiii{del \var{a}[\var{k}]}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1364 {remove \code{\var{a}[\var{k}]} from \var{a}}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1365 {(1)}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1366 \lineiii{\var{a}.clear()}{remove all items from \code{a}}{}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1367 \lineiii{\var{a}.copy()}{a (shallow) copy of \code{a}}{}
17616 7acba78e1e09 At the suggestion of Peter Funk, document 'key in dict' and 'key not Guido van Rossum <guido@python.org> parents: 17612 diff changeset	1368 \lineiii{\var{a}.has_key(\var{k})}
30095 e3c9b48de60a SF bug #775836: change 0,1 to False,True in dict.has_key doc Raymond Hettinger <python@rcn.com> parents: 29893 diff changeset	1369 {\code{True} if \var{a} has a key \var{k}, else \code{False}}
17594 bf94af396b1e Implement, test and document "key in dict" and "key not in dict". Guido van Rossum <guido@python.org> parents: 16778 diff changeset	1370 {}
17616 7acba78e1e09 At the suggestion of Peter Funk, document 'key in dict' and 'key not Guido van Rossum <guido@python.org> parents: 17612 diff changeset	1371 \lineiii{\var{k} \code{in} \var{a}}
7acba78e1e09 At the suggestion of Peter Funk, document 'key in dict' and 'key not Guido van Rossum <guido@python.org> parents: 17612 diff changeset	1372 {Equivalent to \var{a}.has_key(\var{k})}
17966 178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues() Fred Drake <fdrake@acm.org> parents: 17663 diff changeset	1373 {(2)}
17594 bf94af396b1e Implement, test and document "key in dict" and "key not in dict". Guido van Rossum <guido@python.org> parents: 16778 diff changeset	1374 \lineiii{\var{k} not in \var{a}}
17616 7acba78e1e09 At the suggestion of Peter Funk, document 'key in dict' and 'key not Guido van Rossum <guido@python.org> parents: 17612 diff changeset	1375 {Equivalent to \code{not} \var{a}.has_key(\var{k})}
17966 178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues() Fred Drake <fdrake@acm.org> parents: 17663 diff changeset	1376 {(2)}
10968 5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1377 \lineiii{\var{a}.items()}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1378 {a copy of \var{a}'s list of (\var{key}, \var{value}) pairs}
17966 178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues() Fred Drake <fdrake@acm.org> parents: 17663 diff changeset	1379 {(3)}
18085 7e459fb3c332 Fixed reference to table notes for {}.keys() and {}.items() -- these Fred Drake <fdrake@acm.org> parents: 17966 diff changeset	1380 \lineiii{\var{a}.keys()}{a copy of \var{a}'s list of keys}{(3)}
31616 5b3898d9ba59 SF #904720: dict.update should take a 2-tuple sequence like dict.__init_ Raymond Hettinger <python@rcn.com> parents: 31357 diff changeset	1381 \lineiii{\var{a}.update(\optional{\var{b}})}
5b3898d9ba59 SF #904720: dict.update should take a 2-tuple sequence like dict.__init_ Raymond Hettinger <python@rcn.com> parents: 31357 diff changeset	1382 {updates (and overwrites) key/value pairs from \var{b}}
5b3898d9ba59 SF #904720: dict.update should take a 2-tuple sequence like dict.__init_ Raymond Hettinger <python@rcn.com> parents: 31357 diff changeset	1383 {(9)}
26437 57d03375aead SF Patch 643443. Added dict.fromkeys(iterable, value=None), a class Raymond Hettinger <python@rcn.com> parents: 26260 diff changeset	1384 \lineiii{\var{a}.fromkeys(\var{seq}\optional{, \var{value}})}
57d03375aead SF Patch 643443. Added dict.fromkeys(iterable, value=None), a class Raymond Hettinger <python@rcn.com> parents: 26260 diff changeset	1385 {Creates a new dictionary with keys from \var{seq} and values set to \var{value}}
57d03375aead SF Patch 643443. Added dict.fromkeys(iterable, value=None), a class Raymond Hettinger <python@rcn.com> parents: 26260 diff changeset	1386 {(7)}
18085 7e459fb3c332 Fixed reference to table notes for {}.keys() and {}.items() -- these Fred Drake <fdrake@acm.org> parents: 17966 diff changeset	1387 \lineiii{\var{a}.values()}{a copy of \var{a}'s list of values}{(3)}
10968 5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1388 \lineiii{\var{a}.get(\var{k}\optional{, \var{x}})}
17603 d638e419c304 Fix a number of minor markup errors. Fred Drake <fdrake@acm.org> parents: 17594 diff changeset	1389 {\code{\var{a}[\var{k}]} if \code{\var{k} in \var{a}},
10968 5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1390 else \var{x}}
18286 bc05a95242a3 Remove the restriction on a mapping's .update() method. Barry Warsaw <barry@python.org> parents: 18085 diff changeset	1391 {(4)}
13894 77b9e041b595 Barry's patch to document the new setdefault() method. Slightly Guido van Rossum <guido@python.org> parents: 13780 diff changeset	1392 \lineiii{\var{a}.setdefault(\var{k}\optional{, \var{x}})}
17603 d638e419c304 Fix a number of minor markup errors. Fred Drake <fdrake@acm.org> parents: 17594 diff changeset	1393 {\code{\var{a}[\var{k}]} if \code{\var{k} in \var{a}},
13894 77b9e041b595 Barry's patch to document the new setdefault() method. Slightly Guido van Rossum <guido@python.org> parents: 13780 diff changeset	1394 else \var{x} (also setting it)}
18286 bc05a95242a3 Remove the restriction on a mapping's .update() method. Barry Warsaw <barry@python.org> parents: 18085 diff changeset	1395 {(5)}
28211 92e3b611dc9f SF patch #693753: fix for bug 639806: default for dict.pop Raymond Hettinger <python@rcn.com> parents: 28171 diff changeset	1396 \lineiii{\var{a}.pop(\var{k}\optional{, \var{x}})}
92e3b611dc9f SF patch #693753: fix for bug 639806: default for dict.pop Raymond Hettinger <python@rcn.com> parents: 28171 diff changeset	1397 {\code{\var{a}[\var{k}]} if \code{\var{k} in \var{a}},
92e3b611dc9f SF patch #693753: fix for bug 639806: default for dict.pop Raymond Hettinger <python@rcn.com> parents: 28171 diff changeset	1398 else \var{x} (and remove k)}
92e3b611dc9f SF patch #693753: fix for bug 639806: default for dict.pop Raymond Hettinger <python@rcn.com> parents: 28171 diff changeset	1399 {(8)}
15522 aaa54752e4ba "Documentation" for {}.popitem(). Guido van Rossum <guido@python.org> parents: 15463 diff changeset	1400 \lineiii{\var{a}.popitem()}
aaa54752e4ba "Documentation" for {}.popitem(). Guido van Rossum <guido@python.org> parents: 15463 diff changeset	1401 {remove and return an arbitrary (\var{key}, \var{value}) pair}
18286 bc05a95242a3 Remove the restriction on a mapping's .update() method. Barry Warsaw <barry@python.org> parents: 18085 diff changeset	1402 {(6)}
17966 178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues() Fred Drake <fdrake@acm.org> parents: 17663 diff changeset	1403 \lineiii{\var{a}.iteritems()}
178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues() Fred Drake <fdrake@acm.org> parents: 17663 diff changeset	1404 {return an iterator over (\var{key}, \var{value}) pairs}
24902 f57d6db423f2 Extend some comments on the order of values in the returns from Fred Drake <fdrake@acm.org> parents: 24631 diff changeset	1405 {(2), (3)}
17966 178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues() Fred Drake <fdrake@acm.org> parents: 17663 diff changeset	1406 \lineiii{\var{a}.iterkeys()}
178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues() Fred Drake <fdrake@acm.org> parents: 17663 diff changeset	1407 {return an iterator over the mapping's keys}
24902 f57d6db423f2 Extend some comments on the order of values in the returns from Fred Drake <fdrake@acm.org> parents: 24631 diff changeset	1408 {(2), (3)}
17966 178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues() Fred Drake <fdrake@acm.org> parents: 17663 diff changeset	1409 \lineiii{\var{a}.itervalues()}
178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues() Fred Drake <fdrake@acm.org> parents: 17663 diff changeset	1410 {return an iterator over the mapping's values}
24902 f57d6db423f2 Extend some comments on the order of values in the returns from Fred Drake <fdrake@acm.org> parents: 24631 diff changeset	1411 {(2), (3)}
10968 5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1412 \end{tableiii}
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1413
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1414 \noindent
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1415 Notes:
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1416 \begin{description}
10968 5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1417 \item[(1)] Raises a \exception{KeyError} exception if \var{k} is not
5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1418 in the map.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1419
17966 178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues() Fred Drake <fdrake@acm.org> parents: 17663 diff changeset	1420 \item[(2)] \versionadded{2.2}
178bedf9536d Add descriptions of {}.iteritems(), {}.iterkeys(), and {}.itervalues() Fred Drake <fdrake@acm.org> parents: 17663 diff changeset	1421
34029 81a1f754d32c Clarify the ordering of dictionary keys. Raymond Hettinger <python@rcn.com> parents: 33970 diff changeset	1422 \item[(3)] Keys and values are listed in an arbitrary order which is
81a1f754d32c Clarify the ordering of dictionary keys. Raymond Hettinger <python@rcn.com> parents: 33970 diff changeset	1423 non-random, varies across Python implementations, and depends on the
81a1f754d32c Clarify the ordering of dictionary keys. Raymond Hettinger <python@rcn.com> parents: 33970 diff changeset	1424 dictionary's history of insertions and deletions.
81a1f754d32c Clarify the ordering of dictionary keys. Raymond Hettinger <python@rcn.com> parents: 33970 diff changeset	1425 If \method{items()}, \method{keys()}, \method{values()},
24902 f57d6db423f2 Extend some comments on the order of values in the returns from Fred Drake <fdrake@acm.org> parents: 24631 diff changeset	1426 \method{iteritems()}, \method{iterkeys()}, and \method{itervalues()}
f57d6db423f2 Extend some comments on the order of values in the returns from Fred Drake <fdrake@acm.org> parents: 24631 diff changeset	1427 are called with no intervening modifications to the dictionary, the
f57d6db423f2 Extend some comments on the order of values in the returns from Fred Drake <fdrake@acm.org> parents: 24631 diff changeset	1428 lists will directly correspond. This allows the creation of
f57d6db423f2 Extend some comments on the order of values in the returns from Fred Drake <fdrake@acm.org> parents: 24631 diff changeset	1429 \code{(\var{value}, \var{key})} pairs using \function{zip()}:
f57d6db423f2 Extend some comments on the order of values in the returns from Fred Drake <fdrake@acm.org> parents: 24631 diff changeset	1430 \samp{pairs = zip(\var{a}.values(), \var{a}.keys())}. The same
f57d6db423f2 Extend some comments on the order of values in the returns from Fred Drake <fdrake@acm.org> parents: 24631 diff changeset	1431 relationship holds for the \method{iterkeys()} and
f57d6db423f2 Extend some comments on the order of values in the returns from Fred Drake <fdrake@acm.org> parents: 24631 diff changeset	1432 \method{itervalues()} methods: \samp{pairs = zip(\var{a}.itervalues(),
f57d6db423f2 Extend some comments on the order of values in the returns from Fred Drake <fdrake@acm.org> parents: 24631 diff changeset	1433 \var{a}.iterkeys())} provides the same value for \code{pairs}.
f57d6db423f2 Extend some comments on the order of values in the returns from Fred Drake <fdrake@acm.org> parents: 24631 diff changeset	1434 Another way to create the same list is \samp{pairs = [(v, k) for (k,
f57d6db423f2 Extend some comments on the order of values in the returns from Fred Drake <fdrake@acm.org> parents: 24631 diff changeset	1435 v) in \var{a}.iteritems()]}.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1436
18286 bc05a95242a3 Remove the restriction on a mapping's .update() method. Barry Warsaw <barry@python.org> parents: 18085 diff changeset	1437 \item[(4)] Never raises an exception if \var{k} is not in the map,
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 11463 diff changeset	1438 instead it returns \var{x}. \var{x} is optional; when \var{x} is not
10968 5ba2e4ce58cb Some clarifications on operations for mapping types, based on comments Fred Drake <fdrake@acm.org> parents: 10785 diff changeset	1439 provided and \var{k} is not in the map, \code{None} is returned.
13894 77b9e041b595 Barry's patch to document the new setdefault() method. Slightly Guido van Rossum <guido@python.org> parents: 13780 diff changeset	1440
18286 bc05a95242a3 Remove the restriction on a mapping's .update() method. Barry Warsaw <barry@python.org> parents: 18085 diff changeset	1441 \item[(5)] \function{setdefault()} is like \function{get()}, except
13894 77b9e041b595 Barry's patch to document the new setdefault() method. Slightly Guido van Rossum <guido@python.org> parents: 13780 diff changeset	1442 that if \var{k} is missing, \var{x} is both returned and inserted into
33003 b5dcfe7a4159 Point out that the setdefault defaults the value to None. Inspired by Michael W. Hudson <mwh@python.net> parents: 32975 diff changeset	1443 the dictionary as the value of \var{k}. \var{x} defaults to \var{None}.
15522 aaa54752e4ba "Documentation" for {}.popitem(). Guido van Rossum <guido@python.org> parents: 15463 diff changeset	1444
18286 bc05a95242a3 Remove the restriction on a mapping's .update() method. Barry Warsaw <barry@python.org> parents: 18085 diff changeset	1445 \item[(6)] \function{popitem()} is useful to destructively iterate
34969 672e5f65172c SF bug #1209671: dict.popitem documentation should mention empty dict case Raymond Hettinger <python@rcn.com> parents: 34917 diff changeset	1446 over a dictionary, as often used in set algorithms. If the dictionary
672e5f65172c SF bug #1209671: dict.popitem documentation should mention empty dict case Raymond Hettinger <python@rcn.com> parents: 34917 diff changeset	1447 is empty, calling \function{popitem()} raises a \exception{KeyError}.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1448
26437 57d03375aead SF Patch 643443. Added dict.fromkeys(iterable, value=None), a class Raymond Hettinger <python@rcn.com> parents: 26260 diff changeset	1449 \item[(7)] \function{fromkeys()} is a class method that returns a
57d03375aead SF Patch 643443. Added dict.fromkeys(iterable, value=None), a class Raymond Hettinger <python@rcn.com> parents: 26260 diff changeset	1450 new dictionary. \var{value} defaults to \code{None}. \versionadded{2.3}
28211 92e3b611dc9f SF patch #693753: fix for bug 639806: default for dict.pop Raymond Hettinger <python@rcn.com> parents: 28171 diff changeset	1451
92e3b611dc9f SF patch #693753: fix for bug 639806: default for dict.pop Raymond Hettinger <python@rcn.com> parents: 28171 diff changeset	1452 \item[(8)] \function{pop()} raises a \exception{KeyError} when no default
92e3b611dc9f SF patch #693753: fix for bug 639806: default for dict.pop Raymond Hettinger <python@rcn.com> parents: 28171 diff changeset	1453 value is given and the key is not found. \versionadded{2.3}
26437 57d03375aead SF Patch 643443. Added dict.fromkeys(iterable, value=None), a class Raymond Hettinger <python@rcn.com> parents: 26260 diff changeset	1454
31616 5b3898d9ba59 SF #904720: dict.update should take a 2-tuple sequence like dict.__init_ Raymond Hettinger <python@rcn.com> parents: 31357 diff changeset	1455 \item[(9)] \function{update()} accepts either another mapping object
5b3898d9ba59 SF #904720: dict.update should take a 2-tuple sequence like dict.__init_ Raymond Hettinger <python@rcn.com> parents: 31357 diff changeset	1456 or an iterable of key/value pairs (as a tuple or other iterable of
5b3898d9ba59 SF #904720: dict.update should take a 2-tuple sequence like dict.__init_ Raymond Hettinger <python@rcn.com> parents: 31357 diff changeset	1457 length two). If keyword arguments are specified, the mapping is
5b3898d9ba59 SF #904720: dict.update should take a 2-tuple sequence like dict.__init_ Raymond Hettinger <python@rcn.com> parents: 31357 diff changeset	1458 then is updated with those key/value pairs:
5b3898d9ba59 SF #904720: dict.update should take a 2-tuple sequence like dict.__init_ Raymond Hettinger <python@rcn.com> parents: 31357 diff changeset	1459 \samp{d.update(red=1, blue=2)}.
5b3898d9ba59 SF #904720: dict.update should take a 2-tuple sequence like dict.__init_ Raymond Hettinger <python@rcn.com> parents: 31357 diff changeset	1460 \versionchanged[Allowed the argument to be an iterable of key/value
5b3898d9ba59 SF #904720: dict.update should take a 2-tuple sequence like dict.__init_ Raymond Hettinger <python@rcn.com> parents: 31357 diff changeset	1461 pairs and allowed keyword arguments]{2.4}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1462
36656 92ce8bb8b12a - Patch 1433928: Guido van Rossum <guido@python.org> parents: 36580 diff changeset	1463 \item[(10)] If a subclass of dict defines a method \method{__missing__},
92ce8bb8b12a - Patch 1433928: Guido van Rossum <guido@python.org> parents: 36580 diff changeset	1464 if the key \var{k} is not present, the \var{a}[\var{k}] operation calls
92ce8bb8b12a - Patch 1433928: Guido van Rossum <guido@python.org> parents: 36580 diff changeset	1465 that method with the key \var{k} as argument. The \var{a}[\var{k}]
92ce8bb8b12a - Patch 1433928: Guido van Rossum <guido@python.org> parents: 36580 diff changeset	1466 operation then returns or raises whatever is returned or raised by the
92ce8bb8b12a - Patch 1433928: Guido van Rossum <guido@python.org> parents: 36580 diff changeset	1467 \function{__missing__}(\var{k}) call if the key is not present.
92ce8bb8b12a - Patch 1433928: Guido van Rossum <guido@python.org> parents: 36580 diff changeset	1468 No other operations or methods invoke \method{__missing__}().
92ce8bb8b12a - Patch 1433928: Guido van Rossum <guido@python.org> parents: 36580 diff changeset	1469 If \method{__missing__} is not defined, \exception{KeyError} is raised.
92ce8bb8b12a - Patch 1433928: Guido van Rossum <guido@python.org> parents: 36580 diff changeset	1470 \method{__missing__} must be a method; it cannot be an instance variable.
92ce8bb8b12a - Patch 1433928: Guido van Rossum <guido@python.org> parents: 36580 diff changeset	1471 For an example, see \module{collections}.\class{defaultdict}.
92ce8bb8b12a - Patch 1433928: Guido van Rossum <guido@python.org> parents: 36580 diff changeset	1472 \versionadded{2.5}
92ce8bb8b12a - Patch 1433928: Guido van Rossum <guido@python.org> parents: 36580 diff changeset	1473
31631 228d264c5fbb SF Patch #912462: Relocate \end tag to the right place. Hye-Shik Chang <hyeshik@gmail.com> parents: 31616 diff changeset	1474 \end{description}
228d264c5fbb SF Patch #912462: Relocate \end tag to the right place. Hye-Shik Chang <hyeshik@gmail.com> parents: 31616 diff changeset	1475
20767 b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1476 \subsection{File Objects
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1477 \label{bltin-file-objects}}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1478
20767 b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1479 File objects\obindex{file} are implemented using C's \code{stdio}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1480 package and can be created with the built-in constructor
22241 7584b6f1afde Change Windows file.truncate() to (a) restore the original file position, Tim Peters <tim.peters@gmail.com> parents: 22214 diff changeset	1481 \function{file()}\bifuncindex{file} described in section
20764 37b8d92e12f5 Mention the new file() builtin in the section on file objects. Tim Peters <tim.peters@gmail.com> parents: 20701 diff changeset	1482 \ref{built-in-funcs}, ``Built-in Functions.''\footnote{\function{file()}
37b8d92e12f5 Mention the new file() builtin in the section on file objects. Tim Peters <tim.peters@gmail.com> parents: 20701 diff changeset	1483 is new in Python 2.2. The older built-in \function{open()} is an
31286 3894654b4848 fix a variety of markup bugs Fred Drake <fdrake@acm.org> parents: 31282 diff changeset	1484 alias for \function{file()}.} File objects are also returned
18416 33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18395 diff changeset	1485 by some other built-in functions and methods, such as
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	1486 \function{os.popen()} and \function{os.fdopen()} and the
9461 9ffd604807c2 Don't describe something as "below"; that won't make sense for the Fred Drake <fdrake@acm.org> parents: 9318 diff changeset	1487 \method{makefile()} method of socket objects.
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	1488 \refstmodindex{os}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1489 \refbimodindex{socket}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1490
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1491 When a file operation fails for an I/O-related reason, the exception
9558 fa867d8ee7eb Remove some remaining {\rm ...} constructs. Fred Drake <fdrake@acm.org> parents: 9523 diff changeset	1492 \exception{IOError} is raised. This includes situations where the
fa867d8ee7eb Remove some remaining {\rm ...} constructs. Fred Drake <fdrake@acm.org> parents: 9523 diff changeset	1493 operation is not defined for some reason, like \method{seek()} on a tty
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1494 device or writing a file opened for reading.
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1495
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1496 Files have the following methods:
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1497
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1498
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1499 \begin{methoddesc}[file]{close}{}
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	1500 Close the file. A closed file cannot be read or written any more.
15383 eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	1501 Any operation which requires that the file be open will raise a
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	1502 \exception{ValueError} after the file has been closed. Calling
14685 faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1503 \method{close()} more than once is allowed.
37259 af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 37210 diff changeset	1504
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 37210 diff changeset	1505 As of Python 2.5, you can avoid having to call this method explicitly
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 37210 diff changeset	1506 if you use the \keyword{with} statement. For example, the following
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 37210 diff changeset	1507 code will automatically close \code{f} when the \keyword{with} block
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 37210 diff changeset	1508 is exited:
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 37210 diff changeset	1509
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 37210 diff changeset	1510 \begin{verbatim}
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 37210 diff changeset	1511 from __future__ import with_statement
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 37210 diff changeset	1512
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 37210 diff changeset	1513 with open("hello.txt") as f:
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 37210 diff changeset	1514 for line in f:
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 37210 diff changeset	1515 print line
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 37210 diff changeset	1516 \end{verbatim}
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 37210 diff changeset	1517
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 37210 diff changeset	1518 In older versions of Python, you would have needed to do this to get
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 37210 diff changeset	1519 the same effect:
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 37210 diff changeset	1520
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 37210 diff changeset	1521 \begin{verbatim}
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 37210 diff changeset	1522 f = open("hello.txt")
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 37210 diff changeset	1523 try:
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 37210 diff changeset	1524 for line in f:
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 37210 diff changeset	1525 print line
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 37210 diff changeset	1526 finally:
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 37210 diff changeset	1527 f.close()
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 37210 diff changeset	1528 \end{verbatim}
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 37210 diff changeset	1529
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 37210 diff changeset	1530 \note{Not all ``file-like'' types in Python support use as a context
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 37210 diff changeset	1531 manager for the \keyword{with} statement. If your code is intended to
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 37210 diff changeset	1532 work with any file-like object, you can use the \function{closing()}
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 37210 diff changeset	1533 function in the \module{contextlib} module instead of using the object
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 37210 diff changeset	1534 directly. See section~\ref{context-closing} for details.}
af24eb3bbfce Document objects that can be used with the ``with`` statement. Phillip J. Eby <pje@telecommunity.com> parents: 37210 diff changeset	1535
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1536 \end{methoddesc}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1537
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1538 \begin{methoddesc}[file]{flush}{}
14685 faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1539 Flush the internal buffer, like \code{stdio}'s
faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1540 \cfunction{fflush()}. This may be a no-op on some file-like
faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1541 objects.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1542 \end{methoddesc}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1543
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1544 \begin{methoddesc}[file]{fileno}{}
14685 faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1545 \index{file descriptor}
faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1546 \index{descriptor, file}
faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1547 Return the integer ``file descriptor'' that is used by the
faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1548 underlying implementation to request I/O operations from the
faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1549 operating system. This can be useful for other, lower level
18416 33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18395 diff changeset	1550 interfaces that use file descriptors, such as the
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18395 diff changeset	1551 \refmodule{fcntl}\refbimodindex{fcntl} module or
20580 376ee174ecd0 Use the \note and \warning macros where appropriate. Fred Drake <fdrake@acm.org> parents: 20173 diff changeset	1552 \function{os.read()} and friends. \note{File-like objects
18416 33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18395 diff changeset	1553 which do not have a real file descriptor should \emph{not} provide
20580 376ee174ecd0 Use the \note and \warning macros where appropriate. Fred Drake <fdrake@acm.org> parents: 20173 diff changeset	1554 this method!}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1555 \end{methoddesc}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1556
24599 d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and Guido van Rossum <guido@python.org> parents: 24598 diff changeset	1557 \begin{methoddesc}[file]{isatty}{}
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and Guido van Rossum <guido@python.org> parents: 24598 diff changeset	1558 Return \code{True} if the file is connected to a tty(-like) device, else
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and Guido van Rossum <guido@python.org> parents: 24598 diff changeset	1559 \code{False}. \note{If a file-like object is not associated
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and Guido van Rossum <guido@python.org> parents: 24598 diff changeset	1560 with a real file, this method should \emph{not} be implemented.}
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and Guido van Rossum <guido@python.org> parents: 24598 diff changeset	1561 \end{methoddesc}
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and Guido van Rossum <guido@python.org> parents: 24598 diff changeset	1562
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and Guido van Rossum <guido@python.org> parents: 24598 diff changeset	1563 \begin{methoddesc}[file]{next}{}
30413 53f1c32ee69d SF bug #804280: fromkeys is not listed in index Raymond Hettinger <python@rcn.com> parents: 30375 diff changeset	1564 A file object is its own iterator, for example \code{iter(\var{f})} returns
24599 d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and Guido van Rossum <guido@python.org> parents: 24598 diff changeset	1565 \var{f} (unless \var{f} is closed). When a file is used as an
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and Guido van Rossum <guido@python.org> parents: 24598 diff changeset	1566 iterator, typically in a \keyword{for} loop (for example,
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and Guido van Rossum <guido@python.org> parents: 24598 diff changeset	1567 \code{for line in f: print line}), the \method{next()} method is
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and Guido van Rossum <guido@python.org> parents: 24598 diff changeset	1568 called repeatedly. This method returns the next input line, or raises
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and Guido van Rossum <guido@python.org> parents: 24598 diff changeset	1569 \exception{StopIteration} when \EOF{} is hit. In order to make a
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and Guido van Rossum <guido@python.org> parents: 24598 diff changeset	1570 \keyword{for} loop the most efficient way of looping over the lines of
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and Guido van Rossum <guido@python.org> parents: 24598 diff changeset	1571 a file (a very common operation), the \method{next()} method uses a
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and Guido van Rossum <guido@python.org> parents: 24598 diff changeset	1572 hidden read-ahead buffer. As a consequence of using a read-ahead
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and Guido van Rossum <guido@python.org> parents: 24598 diff changeset	1573 buffer, combining \method{next()} with other file methods (like
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and Guido van Rossum <guido@python.org> parents: 24598 diff changeset	1574 \method{readline()}) does not work right. However, using
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and Guido van Rossum <guido@python.org> parents: 24598 diff changeset	1575 \method{seek()} to reposition the file to an absolute position will
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and Guido van Rossum <guido@python.org> parents: 24598 diff changeset	1576 flush the read-ahead buffer.
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and Guido van Rossum <guido@python.org> parents: 24598 diff changeset	1577 \versionadded{2.3}
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and Guido van Rossum <guido@python.org> parents: 24598 diff changeset	1578 \end{methoddesc}
d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and Guido van Rossum <guido@python.org> parents: 24598 diff changeset	1579
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1580 \begin{methoddesc}[file]{read}{\optional{size}}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1581 Read at most \var{size} bytes from the file (less if the read hits
10606 fe5fcb7e73f7 Correct documentation for <file>.read(); Python makes a serious Fred Drake <fdrake@acm.org> parents: 10520 diff changeset	1582 \EOF{} before obtaining \var{size} bytes). If the \var{size}
fe5fcb7e73f7 Correct documentation for <file>.read(); Python makes a serious Fred Drake <fdrake@acm.org> parents: 10520 diff changeset	1583 argument is negative or omitted, read all data until \EOF{} is
fe5fcb7e73f7 Correct documentation for <file>.read(); Python makes a serious Fred Drake <fdrake@acm.org> parents: 10520 diff changeset	1584 reached. The bytes are returned as a string object. An empty
fe5fcb7e73f7 Correct documentation for <file>.read(); Python makes a serious Fred Drake <fdrake@acm.org> parents: 10520 diff changeset	1585 string is returned when \EOF{} is encountered immediately. (For
fe5fcb7e73f7 Correct documentation for <file>.read(); Python makes a serious Fred Drake <fdrake@acm.org> parents: 10520 diff changeset	1586 certain files, like ttys, it makes sense to continue reading after
fe5fcb7e73f7 Correct documentation for <file>.read(); Python makes a serious Fred Drake <fdrake@acm.org> parents: 10520 diff changeset	1587 an \EOF{} is hit.) Note that this method may call the underlying
fe5fcb7e73f7 Correct documentation for <file>.read(); Python makes a serious Fred Drake <fdrake@acm.org> parents: 10520 diff changeset	1588 C function \cfunction{fread()} more than once in an effort to
26672 8dd25a6f5913 Fixed bug Gustavo Niemeyer <gustavo@niemeyer.net> parents: 26592 diff changeset	1589 acquire as close to \var{size} bytes as possible. Also note that
8dd25a6f5913 Fixed bug Gustavo Niemeyer <gustavo@niemeyer.net> parents: 26592 diff changeset	1590 when in non-blocking mode, less data than what was requested may
8dd25a6f5913 Fixed bug Gustavo Niemeyer <gustavo@niemeyer.net> parents: 26592 diff changeset	1591 be returned, even if no \var{size} parameter was given.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1592 \end{methoddesc}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1593
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1594 \begin{methoddesc}[file]{readline}{\optional{size}}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1595 Read one entire line from the file. A trailing newline character is
31286 3894654b4848 fix a variety of markup bugs Fred Drake <fdrake@acm.org> parents: 31282 diff changeset	1596 kept in the string (but may be absent when a file ends with an
3894654b4848 fix a variety of markup bugs Fred Drake <fdrake@acm.org> parents: 31282 diff changeset	1597 incomplete line).\footnote{
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	1598 The advantage of leaving the newline on is that
63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	1599 returning an empty string is then an unambiguous \EOF{}
63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	1600 indication. It is also possible (in cases where it might
63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	1601 matter, for example, if you
22241 7584b6f1afde Change Windows file.truncate() to (a) restore the original file position, Tim Peters <tim.peters@gmail.com> parents: 22214 diff changeset	1602 want to make an exact copy of a file while scanning its lines)
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	1603 to tell whether the last line of a file ended in a newline
13933 4d14eef8ea07 Added Marc-Andre Lemburg's documentation for string methods, with some Fred Drake <fdrake@acm.org> parents: 13894 diff changeset	1604 or not (yes this happens!).
31286 3894654b4848 fix a variety of markup bugs Fred Drake <fdrake@acm.org> parents: 31282 diff changeset	1605 } If the \var{size} argument is present and
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1606 non-negative, it is a maximum byte count (including the trailing
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1607 newline) and an incomplete line may be returned.
23860 63ee31bb25f3 Make a start at describing the results of class/type unification Steve Holden <steve@holdenweb.com> parents: 23847 diff changeset	1608 An empty string is returned \emph{only} when \EOF{} is encountered
20580 376ee174ecd0 Use the \note and \warning macros where appropriate. Fred Drake <fdrake@acm.org> parents: 20173 diff changeset	1609 immediately. \note{Unlike \code{stdio}'s \cfunction{fgets()}, the
14685 faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1610 returned string contains null characters (\code{'\e 0'}) if they
20580 376ee174ecd0 Use the \note and \warning macros where appropriate. Fred Drake <fdrake@acm.org> parents: 20173 diff changeset	1611 occurred in the input.}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1612 \end{methoddesc}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1613
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1614 \begin{methoddesc}[file]{readlines}{\optional{sizehint}}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1615 Read until \EOF{} using \method{readline()} and return a list containing
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1616 the lines thus read. If the optional \var{sizehint} argument is
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 20767 diff changeset	1617 present, instead of reading up to \EOF, whole lines totalling
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1618 approximately \var{sizehint} bytes (possibly after rounding up to an
14685 faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1619 internal buffer size) are read. Objects implementing a file-like
faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1620 interface may choose to ignore \var{sizehint} if it cannot be
faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1621 implemented, or cannot be implemented efficiently.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1622 \end{methoddesc}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1623
15926 ac13cef423c8 Document xreadlines() method. (Forgot to check this in before!) Guido van Rossum <guido@python.org> parents: 15896 diff changeset	1624 \begin{methoddesc}[file]{xreadlines}{}
24599 d7ca0a2ce074 Document file.next(). Mark xreadlines obsolete (both method and Guido van Rossum <guido@python.org> parents: 24598 diff changeset	1625 This method returns the same thing as \code{iter(f)}.
17612 c19d6db6e99b Only document <file>.xreadlines() once; added version annotation. Fred Drake <fdrake@acm.org> parents: 17603 diff changeset	1626 \versionadded{2.1}
31286 3894654b4848 fix a variety of markup bugs Fred Drake <fdrake@acm.org> parents: 31282 diff changeset	1627 \deprecated{2.3}{Use \samp{for \var{line} in \var{file}} instead.}
15926 ac13cef423c8 Document xreadlines() method. (Forgot to check this in before!) Guido van Rossum <guido@python.org> parents: 15896 diff changeset	1628 \end{methoddesc}
ac13cef423c8 Document xreadlines() method. (Forgot to check this in before!) Guido van Rossum <guido@python.org> parents: 15896 diff changeset	1629
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1630 \begin{methoddesc}[file]{seek}{offset\optional{, whence}}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1631 Set the file's current position, like \code{stdio}'s \cfunction{fseek()}.
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1632 The \var{whence} argument is optional and defaults to \code{0}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1633 (absolute file positioning); other values are \code{1} (seek
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1634 relative to the current position) and \code{2} (seek relative to the
15731 a06415994cb5 Added information about the interaction of opening a file in append mode Fred Drake <fdrake@acm.org> parents: 15522 diff changeset	1635 file's end). There is no return value. Note that if the file is
a06415994cb5 Added information about the interaction of opening a file in append mode Fred Drake <fdrake@acm.org> parents: 15522 diff changeset	1636 opened for appending (mode \code{'a'} or \code{'a+'}), any
a06415994cb5 Added information about the interaction of opening a file in append mode Fred Drake <fdrake@acm.org> parents: 15522 diff changeset	1637 \method{seek()} operations will be undone at the next write. If the
a06415994cb5 Added information about the interaction of opening a file in append mode Fred Drake <fdrake@acm.org> parents: 15522 diff changeset	1638 file is only opened for writing in append mode (mode \code{'a'}),
a06415994cb5 Added information about the interaction of opening a file in append mode Fred Drake <fdrake@acm.org> parents: 15522 diff changeset	1639 this method is essentially a no-op, but it remains useful for files
30705 3ff03446f362 Patch #809535: Mention behaviour of seek on text files. Backported to 2.3. Martin v. Löwis <martin@v.loewis.de> parents: 30697 diff changeset	1640 opened in append mode with reading enabled (mode \code{'a+'}). If the
36037 de69a524f4ed Remove reference to the "t" open() mode as it is platform dependent. Georg Brandl <georg@python.org> parents: 35951 diff changeset	1641 file is opened in text mode (without \code{'b'}), only offsets returned
30705 3ff03446f362 Patch #809535: Mention behaviour of seek on text files. Backported to 2.3. Martin v. Löwis <martin@v.loewis.de> parents: 30697 diff changeset	1642 by \method{tell()} are legal. Use of other offsets causes undefined
3ff03446f362 Patch #809535: Mention behaviour of seek on text files. Backported to 2.3. Martin v. Löwis <martin@v.loewis.de> parents: 30697 diff changeset	1643 behavior.
3ff03446f362 Patch #809535: Mention behaviour of seek on text files. Backported to 2.3. Martin v. Löwis <martin@v.loewis.de> parents: 30697 diff changeset	1644
3ff03446f362 Patch #809535: Mention behaviour of seek on text files. Backported to 2.3. Martin v. Löwis <martin@v.loewis.de> parents: 30697 diff changeset	1645 Note that not all file objects are seekable.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1646 \end{methoddesc}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1647
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1648 \begin{methoddesc}[file]{tell}{}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1649 Return the file's current position, like \code{stdio}'s
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1650 \cfunction{ftell()}.
36333 ea6a46d8c51e Bug #1396471: Document that Windows' ftell() can return invalid Georg Brandl <georg@python.org> parents: 36166 diff changeset	1651
ea6a46d8c51e Bug #1396471: Document that Windows' ftell() can return invalid Georg Brandl <georg@python.org> parents: 36166 diff changeset	1652 \note{On Windows, \method{tell()} can return illegal values (after an
ea6a46d8c51e Bug #1396471: Document that Windows' ftell() can return invalid Georg Brandl <georg@python.org> parents: 36166 diff changeset	1653 \cfunction{fgets()}) when reading files with \UNIX{}-style line-endings.
ea6a46d8c51e Bug #1396471: Document that Windows' ftell() can return invalid Georg Brandl <georg@python.org> parents: 36166 diff changeset	1654 Use binary mode (\code{'rb'}) to circumvent this problem.}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1655 \end{methoddesc}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1656
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1657 \begin{methoddesc}[file]{truncate}{\optional{size}}
22241 7584b6f1afde Change Windows file.truncate() to (a) restore the original file position, Tim Peters <tim.peters@gmail.com> parents: 22214 diff changeset	1658 Truncate the file's size. If the optional \var{size} argument is
14685 faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1659 present, the file is truncated to (at most) that size. The size
22241 7584b6f1afde Change Windows file.truncate() to (a) restore the original file position, Tim Peters <tim.peters@gmail.com> parents: 22214 diff changeset	1660 defaults to the current position. The current file position is
7584b6f1afde Change Windows file.truncate() to (a) restore the original file position, Tim Peters <tim.peters@gmail.com> parents: 22214 diff changeset	1661 not changed. Note that if a specified size exceeds the file's
7584b6f1afde Change Windows file.truncate() to (a) restore the original file position, Tim Peters <tim.peters@gmail.com> parents: 22214 diff changeset	1662 current size, the result is platform-dependent: possibilities
36166 6f25029de9db Bug #1394868: doc typos Georg Brandl <georg@python.org> parents: 36135 diff changeset	1663 include that the file may remain unchanged, increase to the specified
22241 7584b6f1afde Change Windows file.truncate() to (a) restore the original file position, Tim Peters <tim.peters@gmail.com> parents: 22214 diff changeset	1664 size as if zero-filled, or increase to the specified size with
7584b6f1afde Change Windows file.truncate() to (a) restore the original file position, Tim Peters <tim.peters@gmail.com> parents: 22214 diff changeset	1665 undefined new content.
30375 4aa84a8b1fe4 Fix spacing markup and other sundries. Raymond Hettinger <python@rcn.com> parents: 30250 diff changeset	1666 Availability: Windows, many \UNIX{} variants.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1667 \end{methoddesc}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1668
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1669 \begin{methoddesc}[file]{write}{str}
20580 376ee174ecd0 Use the \note and \warning macros where appropriate. Fred Drake <fdrake@acm.org> parents: 20173 diff changeset	1670 Write a string to the file. There is no return value. Due to
15789 9e9556924b0a Added documentation for the xreadlines module & related changes. The Fred Drake <fdrake@acm.org> parents: 15731 diff changeset	1671 buffering, the string may not actually show up in the file until
9e9556924b0a Added documentation for the xreadlines module & related changes. The Fred Drake <fdrake@acm.org> parents: 15731 diff changeset	1672 the \method{flush()} or \method{close()} method is called.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1673 \end{methoddesc}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1674
20045 7b8c11739714 Generalize file.writelines() to allow iterable objects. Tim Peters <tim.peters@gmail.com> parents: 20031 diff changeset	1675 \begin{methoddesc}[file]{writelines}{sequence}
7b8c11739714 Generalize file.writelines() to allow iterable objects. Tim Peters <tim.peters@gmail.com> parents: 20031 diff changeset	1676 Write a sequence of strings to the file. The sequence can be any
7b8c11739714 Generalize file.writelines() to allow iterable objects. Tim Peters <tim.peters@gmail.com> parents: 20031 diff changeset	1677 iterable object producing strings, typically a list of strings.
7b8c11739714 Generalize file.writelines() to allow iterable objects. Tim Peters <tim.peters@gmail.com> parents: 20031 diff changeset	1678 There is no return value.
15789 9e9556924b0a Added documentation for the xreadlines module & related changes. The Fred Drake <fdrake@acm.org> parents: 15731 diff changeset	1679 (The name is intended to match \method{readlines()};
9e9556924b0a Added documentation for the xreadlines module & related changes. The Fred Drake <fdrake@acm.org> parents: 15731 diff changeset	1680 \method{writelines()} does not add line separators.)
9e9556924b0a Added documentation for the xreadlines module & related changes. The Fred Drake <fdrake@acm.org> parents: 15731 diff changeset	1681 \end{methoddesc}
9e9556924b0a Added documentation for the xreadlines module & related changes. The Fred Drake <fdrake@acm.org> parents: 15731 diff changeset	1682
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1683
20031 e5a3f9d7766b Note that files are iterable; describe what the iterator returns. Fred Drake <fdrake@acm.org> parents: 19529 diff changeset	1684 Files support the iterator protocol. Each iteration returns the same
e5a3f9d7766b Note that files are iterable; describe what the iterator returns. Fred Drake <fdrake@acm.org> parents: 19529 diff changeset	1685 result as \code{\var{file}.readline()}, and iteration ends when the
e5a3f9d7766b Note that files are iterable; describe what the iterator returns. Fred Drake <fdrake@acm.org> parents: 19529 diff changeset	1686 \method{readline()} method returns an empty string.
e5a3f9d7766b Note that files are iterable; describe what the iterator returns. Fred Drake <fdrake@acm.org> parents: 19529 diff changeset	1687
e5a3f9d7766b Note that files are iterable; describe what the iterator returns. Fred Drake <fdrake@acm.org> parents: 19529 diff changeset	1688
14685 faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1689 File objects also offer a number of other interesting attributes.
faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1690 These are not required for file-like objects, but should be
faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1691 implemented if they make sense for the particular object.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1692
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1693 \begin{memberdesc}[file]{closed}
22920 2392af05f052 Update docs for bool changes by Guido around April 6 Neal Norwitz <nnorwitz@gmail.com> parents: 22785 diff changeset	1694 bool indicating the current state of the file object. This is a
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1695 read-only attribute; the \method{close()} method changes the value.
14685 faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1696 It may not be available on all file-like objects.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1697 \end{memberdesc}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1698
29065 bf1634b023d5 Patch #612627: Add encoding attribute to file objects, and determine Martin v. Löwis <martin@v.loewis.de> parents: 28909 diff changeset	1699 \begin{memberdesc}[file]{encoding}
bf1634b023d5 Patch #612627: Add encoding attribute to file objects, and determine Martin v. Löwis <martin@v.loewis.de> parents: 28909 diff changeset	1700 The encoding that this file uses. When Unicode strings are written
bf1634b023d5 Patch #612627: Add encoding attribute to file objects, and determine Martin v. Löwis <martin@v.loewis.de> parents: 28909 diff changeset	1701 to a file, they will be converted to byte strings using this encoding.
bf1634b023d5 Patch #612627: Add encoding attribute to file objects, and determine Martin v. Löwis <martin@v.loewis.de> parents: 28909 diff changeset	1702 In addition, when the file is connected to a terminal, the attribute
bf1634b023d5 Patch #612627: Add encoding attribute to file objects, and determine Martin v. Löwis <martin@v.loewis.de> parents: 28909 diff changeset	1703 gives the encoding that the terminal is likely to use (that
bf1634b023d5 Patch #612627: Add encoding attribute to file objects, and determine Martin v. Löwis <martin@v.loewis.de> parents: 28909 diff changeset	1704 information might be incorrect if the user has misconfigured the
bf1634b023d5 Patch #612627: Add encoding attribute to file objects, and determine Martin v. Löwis <martin@v.loewis.de> parents: 28909 diff changeset	1705 terminal). The attribute is read-only and may not be present on
bf1634b023d5 Patch #612627: Add encoding attribute to file objects, and determine Martin v. Löwis <martin@v.loewis.de> parents: 28909 diff changeset	1706 all file-like objects. It may also be \code{None}, in which case
bf1634b023d5 Patch #612627: Add encoding attribute to file objects, and determine Martin v. Löwis <martin@v.loewis.de> parents: 28909 diff changeset	1707 the file uses the system default encoding for converting Unicode
bf1634b023d5 Patch #612627: Add encoding attribute to file objects, and determine Martin v. Löwis <martin@v.loewis.de> parents: 28909 diff changeset	1708 strings.
bf1634b023d5 Patch #612627: Add encoding attribute to file objects, and determine Martin v. Löwis <martin@v.loewis.de> parents: 28909 diff changeset	1709
bf1634b023d5 Patch #612627: Add encoding attribute to file objects, and determine Martin v. Löwis <martin@v.loewis.de> parents: 28909 diff changeset	1710 \versionadded{2.3}
bf1634b023d5 Patch #612627: Add encoding attribute to file objects, and determine Martin v. Löwis <martin@v.loewis.de> parents: 28909 diff changeset	1711 \end{memberdesc}
bf1634b023d5 Patch #612627: Add encoding attribute to file objects, and determine Martin v. Löwis <martin@v.loewis.de> parents: 28909 diff changeset	1712
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1713 \begin{memberdesc}[file]{mode}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1714 The I/O mode for the file. If the file was created using the
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1715 \function{open()} built-in function, this will be the value of the
14685 faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1716 \var{mode} parameter. This is a read-only attribute and may not be
faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1717 present on all file-like objects.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1718 \end{memberdesc}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1719
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1720 \begin{memberdesc}[file]{name}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1721 If the file object was created using \function{open()}, the name of
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1722 the file. Otherwise, some string that indicates the source of the
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1723 file object, of the form \samp{<\mbox{\ldots}>}. This is a read-only
14685 faf3e734254d Clarify a number of issues about the file-like object API based on Fred Drake <fdrake@acm.org> parents: 14557 diff changeset	1724 attribute and may not be present on all file-like objects.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1725 \end{memberdesc}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1726
28171 24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1727 \begin{memberdesc}[file]{newlines}
31282 8b62f4194a7e markup fix Fred Drake <fdrake@acm.org> parents: 31210 diff changeset	1728 If Python was built with the \longprogramopt{with-universal-newlines}
8b62f4194a7e markup fix Fred Drake <fdrake@acm.org> parents: 31210 diff changeset	1729 option to \program{configure} (the default) this read-only attribute
8b62f4194a7e markup fix Fred Drake <fdrake@acm.org> parents: 31210 diff changeset	1730 exists, and for files opened in
28171 24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1731 universal newline read mode it keeps track of the types of newlines
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1732 encountered while reading the file. The values it can take are
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1733 \code{'\e r'}, \code{'\e n'}, \code{'\e r\e n'}, \code{None} (unknown,
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1734 no newlines read yet) or a tuple containing all the newline
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1735 types seen, to indicate that multiple
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1736 newline conventions were encountered. For files not opened in universal
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1737 newline read mode the value of this attribute will be \code{None}.
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1738 \end{memberdesc}
24fe023901b0 Back in June in revision 1.98 Steve (accidentally, presumably) wiped Michael W. Hudson <mwh@python.net> parents: 27919 diff changeset	1739
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1740 \begin{memberdesc}[file]{softspace}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1741 Boolean that indicates whether a space character needs to be printed
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1742 before another value when using the \keyword{print} statement.
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1743 Classes that are trying to simulate a file object should also have a
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1744 writable \member{softspace} attribute, which should be initialized to
14485 ac0246586d52 Improve a couple of references to the language reference, making them Fred Drake <fdrake@acm.org> parents: 14044 diff changeset	1745 zero. This will be automatic for most classes implemented in Python
ac0246586d52 Improve a couple of references to the language reference, making them Fred Drake <fdrake@acm.org> parents: 14044 diff changeset	1746 (care may be needed for objects that override attribute access); types
ac0246586d52 Improve a couple of references to the language reference, making them Fred Drake <fdrake@acm.org> parents: 14044 diff changeset	1747 implemented in C will have to provide a writable
ac0246586d52 Improve a couple of references to the language reference, making them Fred Drake <fdrake@acm.org> parents: 14044 diff changeset	1748 \member{softspace} attribute.
20580 376ee174ecd0 Use the \note and \warning macros where appropriate. Fred Drake <fdrake@acm.org> parents: 20173 diff changeset	1749 \note{This attribute is not used to control the
14705 4712f5b8f279 Clarify that the softspace attribute is used by print for state management, Fred Drake <fdrake@acm.org> parents: 14685 diff changeset	1750 \keyword{print} statement, but to allow the implementation of
20580 376ee174ecd0 Use the \note and \warning macros where appropriate. Fred Drake <fdrake@acm.org> parents: 20173 diff changeset	1751 \keyword{print} to keep track of its internal state.}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1752 \end{memberdesc}
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	1753
15383 eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	1754
38101 6bc1e83a97a6 Finish bringing SVN into line with latest version of PEP 343 by getting rid of all remaining references to context objects that I could find. Without a __context__() method context objects no longer exist. Also get test_with working again, and adopt a suggestion from Neal for decimal.Context.get_manager() Nick Coghlan <ncoghlan@gmail.com> parents: 38000 diff changeset	1755 \subsection{Context Manager Types \label{typecontextmanager}}
37936 79959af0f9e0 Add a Context Types section to parallel the Iterator Types section (uses the same terminology as the 2.5a1 implementation) Nick Coghlan <ncoghlan@gmail.com> parents: 37284 diff changeset	1756
79959af0f9e0 Add a Context Types section to parallel the Iterator Types section (uses the same terminology as the 2.5a1 implementation) Nick Coghlan <ncoghlan@gmail.com> parents: 37284 diff changeset	1757 \versionadded{2.5}
38101 6bc1e83a97a6 Finish bringing SVN into line with latest version of PEP 343 by getting rid of all remaining references to context objects that I could find. Without a __context__() method context objects no longer exist. Also get test_with working again, and adopt a suggestion from Neal for decimal.Context.get_manager() Nick Coghlan <ncoghlan@gmail.com> parents: 38000 diff changeset	1758 \index{context manager}
37936 79959af0f9e0 Add a Context Types section to parallel the Iterator Types section (uses the same terminology as the 2.5a1 implementation) Nick Coghlan <ncoghlan@gmail.com> parents: 37284 diff changeset	1759 \index{context management protocol}
79959af0f9e0 Add a Context Types section to parallel the Iterator Types section (uses the same terminology as the 2.5a1 implementation) Nick Coghlan <ncoghlan@gmail.com> parents: 37284 diff changeset	1760 \index{protocol!context management}
79959af0f9e0 Add a Context Types section to parallel the Iterator Types section (uses the same terminology as the 2.5a1 implementation) Nick Coghlan <ncoghlan@gmail.com> parents: 37284 diff changeset	1761
79959af0f9e0 Add a Context Types section to parallel the Iterator Types section (uses the same terminology as the 2.5a1 implementation) Nick Coghlan <ncoghlan@gmail.com> parents: 37284 diff changeset	1762 Python's \keyword{with} statement supports the concept of a runtime
37971 af44db2a9523 Move the PEP 343 documentation and implementation closer to the Nick Coghlan <ncoghlan@gmail.com> parents: 37953 diff changeset	1763 context defined by a context manager. This is implemented using
38101 6bc1e83a97a6 Finish bringing SVN into line with latest version of PEP 343 by getting rid of all remaining references to context objects that I could find. Without a __context__() method context objects no longer exist. Also get test_with working again, and adopt a suggestion from Neal for decimal.Context.get_manager() Nick Coghlan <ncoghlan@gmail.com> parents: 38000 diff changeset	1764 two separate methods that allow user-defined classes to define
6bc1e83a97a6 Finish bringing SVN into line with latest version of PEP 343 by getting rid of all remaining references to context objects that I could find. Without a __context__() method context objects no longer exist. Also get test_with working again, and adopt a suggestion from Neal for decimal.Context.get_manager() Nick Coghlan <ncoghlan@gmail.com> parents: 38000 diff changeset	1765 a runtime context that is entered before the statement body is
6bc1e83a97a6 Finish bringing SVN into line with latest version of PEP 343 by getting rid of all remaining references to context objects that I could find. Without a __context__() method context objects no longer exist. Also get test_with working again, and adopt a suggestion from Neal for decimal.Context.get_manager() Nick Coghlan <ncoghlan@gmail.com> parents: 38000 diff changeset	1766 executed and exited when the statement ends.
37936 79959af0f9e0 Add a Context Types section to parallel the Iterator Types section (uses the same terminology as the 2.5a1 implementation) Nick Coghlan <ncoghlan@gmail.com> parents: 37284 diff changeset	1767
38101 6bc1e83a97a6 Finish bringing SVN into line with latest version of PEP 343 by getting rid of all remaining references to context objects that I could find. Without a __context__() method context objects no longer exist. Also get test_with working again, and adopt a suggestion from Neal for decimal.Context.get_manager() Nick Coghlan <ncoghlan@gmail.com> parents: 38000 diff changeset	1768 The \dfn{context management protocol} consists of a pair of
6bc1e83a97a6 Finish bringing SVN into line with latest version of PEP 343 by getting rid of all remaining references to context objects that I could find. Without a __context__() method context objects no longer exist. Also get test_with working again, and adopt a suggestion from Neal for decimal.Context.get_manager() Nick Coghlan <ncoghlan@gmail.com> parents: 38000 diff changeset	1769 methods that need to be provided for a context manager object to
37953 d60fbc54c0d4 Change PEP 343 related documentation to use the term context specifier instead of context object Nick Coghlan <ncoghlan@gmail.com> parents: 37936 diff changeset	1770 define a runtime context:
37936 79959af0f9e0 Add a Context Types section to parallel the Iterator Types section (uses the same terminology as the 2.5a1 implementation) Nick Coghlan <ncoghlan@gmail.com> parents: 37284 diff changeset	1771
38101 6bc1e83a97a6 Finish bringing SVN into line with latest version of PEP 343 by getting rid of all remaining references to context objects that I could find. Without a __context__() method context objects no longer exist. Also get test_with working again, and adopt a suggestion from Neal for decimal.Context.get_manager() Nick Coghlan <ncoghlan@gmail.com> parents: 38000 diff changeset	1772 \begin{methoddesc}[context manager]{__enter__}{}
6bc1e83a97a6 Finish bringing SVN into line with latest version of PEP 343 by getting rid of all remaining references to context objects that I could find. Without a __context__() method context objects no longer exist. Also get test_with working again, and adopt a suggestion from Neal for decimal.Context.get_manager() Nick Coghlan <ncoghlan@gmail.com> parents: 38000 diff changeset	1773 Enter the runtime context and return either this object or another
6bc1e83a97a6 Finish bringing SVN into line with latest version of PEP 343 by getting rid of all remaining references to context objects that I could find. Without a __context__() method context objects no longer exist. Also get test_with working again, and adopt a suggestion from Neal for decimal.Context.get_manager() Nick Coghlan <ncoghlan@gmail.com> parents: 38000 diff changeset	1774 object related to the runtime context. The value returned by this
6bc1e83a97a6 Finish bringing SVN into line with latest version of PEP 343 by getting rid of all remaining references to context objects that I could find. Without a __context__() method context objects no longer exist. Also get test_with working again, and adopt a suggestion from Neal for decimal.Context.get_manager() Nick Coghlan <ncoghlan@gmail.com> parents: 38000 diff changeset	1775 method is bound to the identifier in the \keyword{as} clause of
6bc1e83a97a6 Finish bringing SVN into line with latest version of PEP 343 by getting rid of all remaining references to context objects that I could find. Without a __context__() method context objects no longer exist. Also get test_with working again, and adopt a suggestion from Neal for decimal.Context.get_manager() Nick Coghlan <ncoghlan@gmail.com> parents: 38000 diff changeset	1776 \keyword{with} statements using this context manager.
6bc1e83a97a6 Finish bringing SVN into line with latest version of PEP 343 by getting rid of all remaining references to context objects that I could find. Without a __context__() method context objects no longer exist. Also get test_with working again, and adopt a suggestion from Neal for decimal.Context.get_manager() Nick Coghlan <ncoghlan@gmail.com> parents: 38000 diff changeset	1777
6bc1e83a97a6 Finish bringing SVN into line with latest version of PEP 343 by getting rid of all remaining references to context objects that I could find. Without a __context__() method context objects no longer exist. Also get test_with working again, and adopt a suggestion from Neal for decimal.Context.get_manager() Nick Coghlan <ncoghlan@gmail.com> parents: 38000 diff changeset	1778 An example of a context manager that returns itself is a file object.
6bc1e83a97a6 Finish bringing SVN into line with latest version of PEP 343 by getting rid of all remaining references to context objects that I could find. Without a __context__() method context objects no longer exist. Also get test_with working again, and adopt a suggestion from Neal for decimal.Context.get_manager() Nick Coghlan <ncoghlan@gmail.com> parents: 38000 diff changeset	1779 File objects return themselves from __enter__() to allow
38102 e92a8b8eec73 Get rid of a couple more context object references, fix some markup and clarify what happens when a generator context function swallows an exception. Nick Coghlan <ncoghlan@gmail.com> parents: 38101 diff changeset	1780 \function{open()} to be used as the context expression in a
e92a8b8eec73 Get rid of a couple more context object references, fix some markup and clarify what happens when a generator context function swallows an exception. Nick Coghlan <ncoghlan@gmail.com> parents: 38101 diff changeset	1781 \keyword{with} statement.
38101 6bc1e83a97a6 Finish bringing SVN into line with latest version of PEP 343 by getting rid of all remaining references to context objects that I could find. Without a __context__() method context objects no longer exist. Also get test_with working again, and adopt a suggestion from Neal for decimal.Context.get_manager() Nick Coghlan <ncoghlan@gmail.com> parents: 38000 diff changeset	1782
6bc1e83a97a6 Finish bringing SVN into line with latest version of PEP 343 by getting rid of all remaining references to context objects that I could find. Without a __context__() method context objects no longer exist. Also get test_with working again, and adopt a suggestion from Neal for decimal.Context.get_manager() Nick Coghlan <ncoghlan@gmail.com> parents: 38000 diff changeset	1783 An example of a context manager that returns a related
6bc1e83a97a6 Finish bringing SVN into line with latest version of PEP 343 by getting rid of all remaining references to context objects that I could find. Without a __context__() method context objects no longer exist. Also get test_with working again, and adopt a suggestion from Neal for decimal.Context.get_manager() Nick Coghlan <ncoghlan@gmail.com> parents: 38000 diff changeset	1784 object is the one returned by \code{decimal.Context.get_manager()}.
6bc1e83a97a6 Finish bringing SVN into line with latest version of PEP 343 by getting rid of all remaining references to context objects that I could find. Without a __context__() method context objects no longer exist. Also get test_with working again, and adopt a suggestion from Neal for decimal.Context.get_manager() Nick Coghlan <ncoghlan@gmail.com> parents: 38000 diff changeset	1785 These managers set the active decimal context to a copy of the
6bc1e83a97a6 Finish bringing SVN into line with latest version of PEP 343 by getting rid of all remaining references to context objects that I could find. Without a __context__() method context objects no longer exist. Also get test_with working again, and adopt a suggestion from Neal for decimal.Context.get_manager() Nick Coghlan <ncoghlan@gmail.com> parents: 38000 diff changeset	1786 original decimal context and then return the copy. This allows
6bc1e83a97a6 Finish bringing SVN into line with latest version of PEP 343 by getting rid of all remaining references to context objects that I could find. Without a __context__() method context objects no longer exist. Also get test_with working again, and adopt a suggestion from Neal for decimal.Context.get_manager() Nick Coghlan <ncoghlan@gmail.com> parents: 38000 diff changeset	1787 changes to be made to the current decimal context in the body of
6bc1e83a97a6 Finish bringing SVN into line with latest version of PEP 343 by getting rid of all remaining references to context objects that I could find. Without a __context__() method context objects no longer exist. Also get test_with working again, and adopt a suggestion from Neal for decimal.Context.get_manager() Nick Coghlan <ncoghlan@gmail.com> parents: 38000 diff changeset	1788 the \keyword{with} statement without affecting code outside
6bc1e83a97a6 Finish bringing SVN into line with latest version of PEP 343 by getting rid of all remaining references to context objects that I could find. Without a __context__() method context objects no longer exist. Also get test_with working again, and adopt a suggestion from Neal for decimal.Context.get_manager() Nick Coghlan <ncoghlan@gmail.com> parents: 38000 diff changeset	1789 the \keyword{with} statement.
37936 79959af0f9e0 Add a Context Types section to parallel the Iterator Types section (uses the same terminology as the 2.5a1 implementation) Nick Coghlan <ncoghlan@gmail.com> parents: 37284 diff changeset	1790 \end{methoddesc}
79959af0f9e0 Add a Context Types section to parallel the Iterator Types section (uses the same terminology as the 2.5a1 implementation) Nick Coghlan <ncoghlan@gmail.com> parents: 37284 diff changeset	1791
38101 6bc1e83a97a6 Finish bringing SVN into line with latest version of PEP 343 by getting rid of all remaining references to context objects that I could find. Without a __context__() method context objects no longer exist. Also get test_with working again, and adopt a suggestion from Neal for decimal.Context.get_manager() Nick Coghlan <ncoghlan@gmail.com> parents: 38000 diff changeset	1792 \begin{methoddesc}[context manager]{__exit__}{exc_type, exc_val, exc_tb}
37953 d60fbc54c0d4 Change PEP 343 related documentation to use the term context specifier instead of context object Nick Coghlan <ncoghlan@gmail.com> parents: 37936 diff changeset	1793 Exit the runtime context and return a Boolean flag indicating if any
d60fbc54c0d4 Change PEP 343 related documentation to use the term context specifier instead of context object Nick Coghlan <ncoghlan@gmail.com> parents: 37936 diff changeset	1794 expection that occurred should be suppressed. If an exception
37936 79959af0f9e0 Add a Context Types section to parallel the Iterator Types section (uses the same terminology as the 2.5a1 implementation) Nick Coghlan <ncoghlan@gmail.com> parents: 37284 diff changeset	1795 occurred while executing the body of the \keyword{with} statement, the
79959af0f9e0 Add a Context Types section to parallel the Iterator Types section (uses the same terminology as the 2.5a1 implementation) Nick Coghlan <ncoghlan@gmail.com> parents: 37284 diff changeset	1796 arguments contain the exception type, value and traceback information.
79959af0f9e0 Add a Context Types section to parallel the Iterator Types section (uses the same terminology as the 2.5a1 implementation) Nick Coghlan <ncoghlan@gmail.com> parents: 37284 diff changeset	1797 Otherwise, all three arguments are \var{None}.
38101 6bc1e83a97a6 Finish bringing SVN into line with latest version of PEP 343 by getting rid of all remaining references to context objects that I could find. Without a __context__() method context objects no longer exist. Also get test_with working again, and adopt a suggestion from Neal for decimal.Context.get_manager() Nick Coghlan <ncoghlan@gmail.com> parents: 38000 diff changeset	1798
37936 79959af0f9e0 Add a Context Types section to parallel the Iterator Types section (uses the same terminology as the 2.5a1 implementation) Nick Coghlan <ncoghlan@gmail.com> parents: 37284 diff changeset	1799 Returning a true value from this method will cause the \keyword{with}
79959af0f9e0 Add a Context Types section to parallel the Iterator Types section (uses the same terminology as the 2.5a1 implementation) Nick Coghlan <ncoghlan@gmail.com> parents: 37284 diff changeset	1800 statement to suppress the exception and continue execution with the
79959af0f9e0 Add a Context Types section to parallel the Iterator Types section (uses the same terminology as the 2.5a1 implementation) Nick Coghlan <ncoghlan@gmail.com> parents: 37284 diff changeset	1801 statement immediately following the \keyword{with} statement. Otherwise
79959af0f9e0 Add a Context Types section to parallel the Iterator Types section (uses the same terminology as the 2.5a1 implementation) Nick Coghlan <ncoghlan@gmail.com> parents: 37284 diff changeset	1802 the exception continues propagating after this method has finished
79959af0f9e0 Add a Context Types section to parallel the Iterator Types section (uses the same terminology as the 2.5a1 implementation) Nick Coghlan <ncoghlan@gmail.com> parents: 37284 diff changeset	1803 executing. Exceptions that occur during execution of this method will
79959af0f9e0 Add a Context Types section to parallel the Iterator Types section (uses the same terminology as the 2.5a1 implementation) Nick Coghlan <ncoghlan@gmail.com> parents: 37284 diff changeset	1804 replace any exception that occurred in the body of the \keyword{with}
79959af0f9e0 Add a Context Types section to parallel the Iterator Types section (uses the same terminology as the 2.5a1 implementation) Nick Coghlan <ncoghlan@gmail.com> parents: 37284 diff changeset	1805 statement.
38101 6bc1e83a97a6 Finish bringing SVN into line with latest version of PEP 343 by getting rid of all remaining references to context objects that I could find. Without a __context__() method context objects no longer exist. Also get test_with working again, and adopt a suggestion from Neal for decimal.Context.get_manager() Nick Coghlan <ncoghlan@gmail.com> parents: 38000 diff changeset	1806
37936 79959af0f9e0 Add a Context Types section to parallel the Iterator Types section (uses the same terminology as the 2.5a1 implementation) Nick Coghlan <ncoghlan@gmail.com> parents: 37284 diff changeset	1807 The exception passed in should never be reraised explicitly - instead,
79959af0f9e0 Add a Context Types section to parallel the Iterator Types section (uses the same terminology as the 2.5a1 implementation) Nick Coghlan <ncoghlan@gmail.com> parents: 37284 diff changeset	1808 this method should return a false value to indicate that the method
79959af0f9e0 Add a Context Types section to parallel the Iterator Types section (uses the same terminology as the 2.5a1 implementation) Nick Coghlan <ncoghlan@gmail.com> parents: 37284 diff changeset	1809 completed successfully and does not want to suppress the raised
79959af0f9e0 Add a Context Types section to parallel the Iterator Types section (uses the same terminology as the 2.5a1 implementation) Nick Coghlan <ncoghlan@gmail.com> parents: 37284 diff changeset	1810 exception. This allows context management code (such as
79959af0f9e0 Add a Context Types section to parallel the Iterator Types section (uses the same terminology as the 2.5a1 implementation) Nick Coghlan <ncoghlan@gmail.com> parents: 37284 diff changeset	1811 \code{contextlib.nested}) to easily detect whether or not an
79959af0f9e0 Add a Context Types section to parallel the Iterator Types section (uses the same terminology as the 2.5a1 implementation) Nick Coghlan <ncoghlan@gmail.com> parents: 37284 diff changeset	1812 \method{__exit__()} method has actually failed.
79959af0f9e0 Add a Context Types section to parallel the Iterator Types section (uses the same terminology as the 2.5a1 implementation) Nick Coghlan <ncoghlan@gmail.com> parents: 37284 diff changeset	1813 \end{methoddesc}
79959af0f9e0 Add a Context Types section to parallel the Iterator Types section (uses the same terminology as the 2.5a1 implementation) Nick Coghlan <ncoghlan@gmail.com> parents: 37284 diff changeset	1814
38101 6bc1e83a97a6 Finish bringing SVN into line with latest version of PEP 343 by getting rid of all remaining references to context objects that I could find. Without a __context__() method context objects no longer exist. Also get test_with working again, and adopt a suggestion from Neal for decimal.Context.get_manager() Nick Coghlan <ncoghlan@gmail.com> parents: 38000 diff changeset	1815 Python defines several context managers to support easy thread
6bc1e83a97a6 Finish bringing SVN into line with latest version of PEP 343 by getting rid of all remaining references to context objects that I could find. Without a __context__() method context objects no longer exist. Also get test_with working again, and adopt a suggestion from Neal for decimal.Context.get_manager() Nick Coghlan <ncoghlan@gmail.com> parents: 38000 diff changeset	1816 synchronisation, prompt closure of files or other objects, and
6bc1e83a97a6 Finish bringing SVN into line with latest version of PEP 343 by getting rid of all remaining references to context objects that I could find. Without a __context__() method context objects no longer exist. Also get test_with working again, and adopt a suggestion from Neal for decimal.Context.get_manager() Nick Coghlan <ncoghlan@gmail.com> parents: 38000 diff changeset	1817 simpler manipulation of the active decimal arithmetic
6bc1e83a97a6 Finish bringing SVN into line with latest version of PEP 343 by getting rid of all remaining references to context objects that I could find. Without a __context__() method context objects no longer exist. Also get test_with working again, and adopt a suggestion from Neal for decimal.Context.get_manager() Nick Coghlan <ncoghlan@gmail.com> parents: 38000 diff changeset	1818 context. The specific types are not treated specially beyond
6bc1e83a97a6 Finish bringing SVN into line with latest version of PEP 343 by getting rid of all remaining references to context objects that I could find. Without a __context__() method context objects no longer exist. Also get test_with working again, and adopt a suggestion from Neal for decimal.Context.get_manager() Nick Coghlan <ncoghlan@gmail.com> parents: 38000 diff changeset	1819 their implementation of the context management protocol.
37936 79959af0f9e0 Add a Context Types section to parallel the Iterator Types section (uses the same terminology as the 2.5a1 implementation) Nick Coghlan <ncoghlan@gmail.com> parents: 37284 diff changeset	1820
37971 af44db2a9523 Move the PEP 343 documentation and implementation closer to the Nick Coghlan <ncoghlan@gmail.com> parents: 37953 diff changeset	1821 Python's generators and the \code{contextlib.contextfactory} decorator
38101 6bc1e83a97a6 Finish bringing SVN into line with latest version of PEP 343 by getting rid of all remaining references to context objects that I could find. Without a __context__() method context objects no longer exist. Also get test_with working again, and adopt a suggestion from Neal for decimal.Context.get_manager() Nick Coghlan <ncoghlan@gmail.com> parents: 38000 diff changeset	1822 provide a convenient way to implement these protocols. If a generator
6bc1e83a97a6 Finish bringing SVN into line with latest version of PEP 343 by getting rid of all remaining references to context objects that I could find. Without a __context__() method context objects no longer exist. Also get test_with working again, and adopt a suggestion from Neal for decimal.Context.get_manager() Nick Coghlan <ncoghlan@gmail.com> parents: 38000 diff changeset	1823 function is decorated with the \code{contextlib.contextfactory}
6bc1e83a97a6 Finish bringing SVN into line with latest version of PEP 343 by getting rid of all remaining references to context objects that I could find. Without a __context__() method context objects no longer exist. Also get test_with working again, and adopt a suggestion from Neal for decimal.Context.get_manager() Nick Coghlan <ncoghlan@gmail.com> parents: 38000 diff changeset	1824 decorator, it will return a context manager implementing the necessary
6bc1e83a97a6 Finish bringing SVN into line with latest version of PEP 343 by getting rid of all remaining references to context objects that I could find. Without a __context__() method context objects no longer exist. Also get test_with working again, and adopt a suggestion from Neal for decimal.Context.get_manager() Nick Coghlan <ncoghlan@gmail.com> parents: 38000 diff changeset	1825 \method{__enter__()} and \method{__exit__()} methods, rather than the
6bc1e83a97a6 Finish bringing SVN into line with latest version of PEP 343 by getting rid of all remaining references to context objects that I could find. Without a __context__() method context objects no longer exist. Also get test_with working again, and adopt a suggestion from Neal for decimal.Context.get_manager() Nick Coghlan <ncoghlan@gmail.com> parents: 38000 diff changeset	1826 iterator produced by an undecorated generator function.
37936 79959af0f9e0 Add a Context Types section to parallel the Iterator Types section (uses the same terminology as the 2.5a1 implementation) Nick Coghlan <ncoghlan@gmail.com> parents: 37284 diff changeset	1827
79959af0f9e0 Add a Context Types section to parallel the Iterator Types section (uses the same terminology as the 2.5a1 implementation) Nick Coghlan <ncoghlan@gmail.com> parents: 37284 diff changeset	1828 Note that there is no specific slot for any of these methods in the
79959af0f9e0 Add a Context Types section to parallel the Iterator Types section (uses the same terminology as the 2.5a1 implementation) Nick Coghlan <ncoghlan@gmail.com> parents: 37284 diff changeset	1829 type structure for Python objects in the Python/C API. Extension
79959af0f9e0 Add a Context Types section to parallel the Iterator Types section (uses the same terminology as the 2.5a1 implementation) Nick Coghlan <ncoghlan@gmail.com> parents: 37284 diff changeset	1830 types wanting to define these methods must provide them as a normal
79959af0f9e0 Add a Context Types section to parallel the Iterator Types section (uses the same terminology as the 2.5a1 implementation) Nick Coghlan <ncoghlan@gmail.com> parents: 37284 diff changeset	1831 Python accessible method. Compared to the overhead of setting up the
79959af0f9e0 Add a Context Types section to parallel the Iterator Types section (uses the same terminology as the 2.5a1 implementation) Nick Coghlan <ncoghlan@gmail.com> parents: 37284 diff changeset	1832 runtime context, the overhead of a single class dictionary lookup
79959af0f9e0 Add a Context Types section to parallel the Iterator Types section (uses the same terminology as the 2.5a1 implementation) Nick Coghlan <ncoghlan@gmail.com> parents: 37284 diff changeset	1833 is negligible.
79959af0f9e0 Add a Context Types section to parallel the Iterator Types section (uses the same terminology as the 2.5a1 implementation) Nick Coghlan <ncoghlan@gmail.com> parents: 37284 diff changeset	1834
79959af0f9e0 Add a Context Types section to parallel the Iterator Types section (uses the same terminology as the 2.5a1 implementation) Nick Coghlan <ncoghlan@gmail.com> parents: 37284 diff changeset	1835
20767 b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1836 \subsection{Other Built-in Types \label{typesother}}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1837
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1838 The interpreter supports several other kinds of objects.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1839 Most of these support only one or two operations.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1840
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1841
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1842 \subsubsection{Modules \label{typesmodules}}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1843
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1844 The only special operation on a module is attribute access:
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1845 \code{\var{m}.\var{name}}, where \var{m} is a module and \var{name}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1846 accesses a name defined in \var{m}'s symbol table. Module attributes
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1847 can be assigned to. (Note that the \keyword{import} statement is not,
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1848 strictly speaking, an operation on a module object; \code{import
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1849 \var{foo}} does not require a module object named \var{foo} to exist,
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1850 rather it requires an (external) \emph{definition} for a module named
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1851 \var{foo} somewhere.)
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1852
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1853 A special member of every module is \member{__dict__}.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1854 This is the dictionary containing the module's symbol table.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1855 Modifying this dictionary will actually change the module's symbol
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1856 table, but direct assignment to the \member{__dict__} attribute is not
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1857 possible (you can write \code{\var{m}.__dict__['a'] = 1}, which
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1858 defines \code{\var{m}.a} to be \code{1}, but you can't write
31286 3894654b4848 fix a variety of markup bugs Fred Drake <fdrake@acm.org> parents: 31282 diff changeset	1859 \code{\var{m}.__dict__ = \{\}}). Modifying \member{__dict__} directly
3894654b4848 fix a variety of markup bugs Fred Drake <fdrake@acm.org> parents: 31282 diff changeset	1860 is not recommended.
20767 b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1861
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1862 Modules built into the interpreter are written like this:
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1863 \code{<module 'sys' (built-in)>}. If loaded from a file, they are
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1864 written as \code{<module 'os' from
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1865 '/usr/local/lib/python\shortversion/os.pyc'>}.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1866
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1867
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1868 \subsubsection{Classes and Class Instances \label{typesobjects}}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1869 \nodename{Classes and Instances}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1870
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1871 See chapters 3 and 7 of the \citetitle[../ref/ref.html]{Python
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1872 Reference Manual} for these.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1873
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1874
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1875 \subsubsection{Functions \label{typesfunctions}}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1876
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1877 Function objects are created by function definitions. The only
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1878 operation on a function object is to call it:
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1879 \code{\var{func}(\var{argument-list})}.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1880
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1881 There are really two flavors of function objects: built-in functions
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1882 and user-defined functions. Both support the same operation (to call
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1883 the function), but the implementation is different, hence the
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1884 different object types.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1885
33102 f27935b46985 This is my patch Michael W. Hudson <mwh@python.net> parents: 33003 diff changeset	1886 See the \citetitle[../ref/ref.html]{Python Reference Manual} for more
f27935b46985 This is my patch Michael W. Hudson <mwh@python.net> parents: 33003 diff changeset	1887 information.
20767 b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1888
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1889 \subsubsection{Methods \label{typesmethods}}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1890 \obindex{method}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1891
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1892 Methods are functions that are called using the attribute notation.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1893 There are two flavors: built-in methods (such as \method{append()} on
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1894 lists) and class instance methods. Built-in methods are described
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1895 with the types that support them.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1896
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1897 The implementation adds two special read-only attributes to class
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1898 instance methods: \code{\var{m}.im_self} is the object on which the
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1899 method operates, and \code{\var{m}.im_func} is the function
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1900 implementing the method. Calling \code{\var{m}(\var{arg-1},
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1901 \var{arg-2}, \textrm{\ldots}, \var{arg-n})} is completely equivalent to
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1902 calling \code{\var{m}.im_func(\var{m}.im_self, \var{arg-1},
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1903 \var{arg-2}, \textrm{\ldots}, \var{arg-n})}.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1904
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1905 Class instance methods are either \emph{bound} or \emph{unbound},
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1906 referring to whether the method was accessed through an instance or a
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1907 class, respectively. When a method is unbound, its \code{im_self}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1908 attribute will be \code{None} and if called, an explicit \code{self}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1909 object must be passed as the first argument. In this case,
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1910 \code{self} must be an instance of the unbound method's class (or a
37064 64c83e0f683e More \exception fixes. Georg Brandl <georg@python.org> parents: 36656 diff changeset	1911 subclass of that class), otherwise a \exception{TypeError} is raised.
20767 b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1912
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1913 Like function objects, methods objects support getting
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1914 arbitrary attributes. However, since method attributes are actually
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1915 stored on the underlying function object (\code{meth.im_func}),
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1916 setting method attributes on either bound or unbound methods is
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1917 disallowed. Attempting to set a method attribute results in a
37064 64c83e0f683e More \exception fixes. Georg Brandl <georg@python.org> parents: 36656 diff changeset	1918 \exception{TypeError} being raised. In order to set a method attribute,
20767 b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1919 you need to explicitly set it on the underlying function object:
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1920
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1921 \begin{verbatim}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1922 class C:
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1923 def method(self):
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1924 pass
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1925
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1926 c = C()
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1927 c.method.im_func.whoami = 'my name is c'
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1928 \end{verbatim}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1929
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1930 See the \citetitle[../ref/ref.html]{Python Reference Manual} for more
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1931 information.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1932
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1933
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1934 \subsubsection{Code Objects \label{bltin-code-objects}}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1935 \obindex{code}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1936
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1937 Code objects are used by the implementation to represent
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1938 ``pseudo-compiled'' executable Python code such as a function body.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1939 They differ from function objects because they don't contain a
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1940 reference to their global execution environment. Code objects are
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1941 returned by the built-in \function{compile()} function and can be
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1942 extracted from function objects through their \member{func_code}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1943 attribute.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1944 \bifuncindex{compile}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1945 \withsubitem{(function object attribute)}{\ttindex{func_code}}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1946
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1947 A code object can be executed or evaluated by passing it (instead of a
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1948 source string) to the \keyword{exec} statement or the built-in
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1949 \function{eval()} function.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1950 \stindex{exec}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1951 \bifuncindex{eval}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1952
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1953 See the \citetitle[../ref/ref.html]{Python Reference Manual} for more
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1954 information.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1955
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1956
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1957 \subsubsection{Type Objects \label{bltin-type-objects}}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1958
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1959 Type objects represent the various object types. An object's type is
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1960 accessed by the built-in function \function{type()}. There are no special
31286 3894654b4848 fix a variety of markup bugs Fred Drake <fdrake@acm.org> parents: 31282 diff changeset	1961 operations on types. The standard module \refmodule{types} defines names
20767 b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1962 for all standard built-in types.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1963 \bifuncindex{type}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1964 \refstmodindex{types}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1965
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1966 Types are written like this: \code{<type 'int'>}.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1967
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1968
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1969 \subsubsection{The Null Object \label{bltin-null-object}}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1970
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1971 This object is returned by functions that don't explicitly return a
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1972 value. It supports no special operations. There is exactly one null
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1973 object, named \code{None} (a built-in name).
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1974
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1975 It is written as \code{None}.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1976
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1977
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1978 \subsubsection{The Ellipsis Object \label{bltin-ellipsis-object}}
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1979
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1980 This object is used by extended slice notation (see the
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1981 \citetitle[../ref/ref.html]{Python Reference Manual}). It supports no
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1982 special operations. There is exactly one ellipsis object, named
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1983 \constant{Ellipsis} (a built-in name).
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1984
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1985 It is written as \code{Ellipsis}.
b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	1986
22785 aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in Guido van Rossum <guido@python.org> parents: 22241 diff changeset	1987 \subsubsection{Boolean Values}
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in Guido van Rossum <guido@python.org> parents: 22241 diff changeset	1988
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in Guido van Rossum <guido@python.org> parents: 22241 diff changeset	1989 Boolean values are the two constant objects \code{False} and
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in Guido van Rossum <guido@python.org> parents: 22241 diff changeset	1990 \code{True}. They are used to represent truth values (although other
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in Guido van Rossum <guido@python.org> parents: 22241 diff changeset	1991 values can also be considered false or true). In numeric contexts
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in Guido van Rossum <guido@python.org> parents: 22241 diff changeset	1992 (for example when used as the argument to an arithmetic operator),
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in Guido van Rossum <guido@python.org> parents: 22241 diff changeset	1993 they behave like the integers 0 and 1, respectively. The built-in
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in Guido van Rossum <guido@python.org> parents: 22241 diff changeset	1994 function \function{bool()} can be used to cast any value to a Boolean,
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in Guido van Rossum <guido@python.org> parents: 22241 diff changeset	1995 if the value can be interpreted as a truth value (see section Truth
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in Guido van Rossum <guido@python.org> parents: 22241 diff changeset	1996 Value Testing above).
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in Guido van Rossum <guido@python.org> parents: 22241 diff changeset	1997
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in Guido van Rossum <guido@python.org> parents: 22241 diff changeset	1998 They are written as \code{False} and \code{True}, respectively.
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in Guido van Rossum <guido@python.org> parents: 22241 diff changeset	1999 \index{False}
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in Guido van Rossum <guido@python.org> parents: 22241 diff changeset	2000 \index{True}
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in Guido van Rossum <guido@python.org> parents: 22241 diff changeset	2001 \indexii{Boolean}{values}
aa8d59823add Add the 'bool' type and its values 'False' and 'True', as described in Guido van Rossum <guido@python.org> parents: 22241 diff changeset	2002
20767 b3f48c5d6e16 Promote file objects out of the "Other Objects" category, so they become Fred Drake <fdrake@acm.org> parents: 20764 diff changeset	2003
10156 0f7d694bc334 Make sure all HTML pages generated from this section have reasonable Fred Drake <fdrake@acm.org> parents: 10147 diff changeset	2004 \subsubsection{Internal Objects \label{typesinternal}}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	2005
11463 17e12305973e Use \citetitle and \programopt as appropriate. Fred Drake <fdrake@acm.org> parents: 11183 diff changeset	2006 See the \citetitle[../ref/ref.html]{Python Reference Manual} for this
14044 a905c5aa0691 As pointed out by Denis S. Otkidach <den@analyt.chem.msu.ru>, xrange() Fred Drake <fdrake@acm.org> parents: 13967 diff changeset	2007 information. It describes stack frame objects, traceback objects, and
a905c5aa0691 As pointed out by Denis S. Otkidach <den@analyt.chem.msu.ru>, xrange() Fred Drake <fdrake@acm.org> parents: 13967 diff changeset	2008 slice objects.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	2009
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	2010
9083 bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	2011 \subsection{Special Attributes \label{specialattrs}}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	2012
8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	2013 The implementation adds a few special read-only attributes to several
32070 b319db3869d8 add note about the __name__ read-only attribute Fred Drake <fdrake@acm.org> parents: 31631 diff changeset	2014 object types, where they are relevant. Some of these are not reported
b319db3869d8 add note about the __name__ read-only attribute Fred Drake <fdrake@acm.org> parents: 31631 diff changeset	2015 by the \function{dir()} built-in function.
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	2016
15383 eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	2017 \begin{memberdesc}[object]{__dict__}
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	2018 A dictionary or other mapping object used to store an
9083 bc41e86c938c Markup nits. Fred Drake <fdrake@acm.org> parents: 9034 diff changeset	2019 object's (writable) attributes.
15383 eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	2020 \end{memberdesc}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	2021
15383 eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	2022 \begin{memberdesc}[object]{__methods__}
21159 6fa96b329e15 Remove most references to __members__ and __methods__, leaving only one pair Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	2023 \deprecated{2.2}{Use the built-in function \function{dir()} to get a
6fa96b329e15 Remove most references to __members__ and __methods__, leaving only one pair Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	2024 list of an object's attributes. This attribute is no longer available.}
15383 eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	2025 \end{memberdesc}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	2026
15383 eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	2027 \begin{memberdesc}[object]{__members__}
21159 6fa96b329e15 Remove most references to __members__ and __methods__, leaving only one pair Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	2028 \deprecated{2.2}{Use the built-in function \function{dir()} to get a
6fa96b329e15 Remove most references to __members__ and __methods__, leaving only one pair Fred Drake <fdrake@acm.org> parents: 21062 diff changeset	2029 list of an object's attributes. This attribute is no longer available.}
15383 eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	2030 \end{memberdesc}
8730 8a306dfd9f33 Move files around to get the names to match the module names except for Fred Drake <fdrake@acm.org> parents: diff changeset	2031
15383 eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	2032 \begin{memberdesc}[instance]{__class__}
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	2033 The class to which a class instance belongs.
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	2034 \end{memberdesc}
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	2035
eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	2036 \begin{memberdesc}[class]{__bases__}
18416 33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18395 diff changeset	2037 The tuple of base classes of a class object. If there are no base
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18395 diff changeset	2038 classes, this will be an empty tuple.
15383 eeb7c8a5b79f Document the proper exception to be raised by I/O operations on closed Fred Drake <fdrake@acm.org> parents: 15332 diff changeset	2039 \end{memberdesc}
32070 b319db3869d8 add note about the __name__ read-only attribute Fred Drake <fdrake@acm.org> parents: 31631 diff changeset	2040
b319db3869d8 add note about the __name__ read-only attribute Fred Drake <fdrake@acm.org> parents: 31631 diff changeset	2041 \begin{memberdesc}[class]{__name__}
b319db3869d8 add note about the __name__ read-only attribute Fred Drake <fdrake@acm.org> parents: 31631 diff changeset	2042 The name of the class or type.
b319db3869d8 add note about the __name__ read-only attribute Fred Drake <fdrake@acm.org> parents: 31631 diff changeset	2043 \end{memberdesc}

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libstdtypes.tex @ 38199:aae2ff33e27c legacy-trunk