Mercurial > cpython-lru_cache-weakref
annotate Doc/ref/ref3.tex @ 21467:4e35fa5d5708 legacy-trunk
Add documentation for the help() built-in; contributed by Ka-Ping Yee.
This is part of SF patch #494622.
| author | Fred Drake <fdrake@acm.org> |
|---|---|
| date | Tue, 18 Dec 2001 16:31:08 +0000 |
| parents | 4cb223ef869b |
| children | 969c1d118c97 d24670384c39 |
| rev | line source |
|---|---|
|
8777
00524555ef17
Make sure all chapters, sections, and subsections have a \label to give them
Fred Drake <fdrake@acm.org>
parents:
8736
diff
changeset
|
1 \chapter{Data model\label{datamodel}} |
| 8231 | 2 |
|
18238
037c8be505e0
Fix a very minor (but annoying when looking for things!) markup nit.
Fred Drake <fdrake@acm.org>
parents:
17988
diff
changeset
|
3 |
|
8777
00524555ef17
Make sure all chapters, sections, and subsections have a \label to give them
Fred Drake <fdrake@acm.org>
parents:
8736
diff
changeset
|
4 \section{Objects, values and types\label{objects}} |
| 8231 | 5 |
| 6 \dfn{Objects} are Python's abstraction for data. All data in a Python | |
| 7 program is represented by objects or by relations between objects. | |
| 8 (In a sense, and in conformance to Von Neumann's model of a | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
9 ``stored program computer,'' code is also represented by objects.) |
| 8231 | 10 \index{object} |
| 11 \index{data} | |
| 12 | |
| 13 Every object has an identity, a type and a value. An object's | |
| 14 \emph{identity} never changes once it has been created; you may think | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
15 of it as the object's address in memory. The `\code{is}' operator |
|
9201
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
16 compares the identity of two objects; the |
|
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
17 \function{id()}\bifuncindex{id} function returns an integer |
|
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
18 representing its identity (currently implemented as its address). |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
19 An object's \dfn{type} is |
| 8231 | 20 also unchangeable. It determines the operations that an object |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
21 supports (e.g., ``does it have a length?'') and also defines the |
|
9201
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
22 possible values for objects of that type. The |
|
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
23 \function{type()}\bifuncindex{type} function returns an object's type |
|
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
24 (which is an object itself). The \emph{value} of some |
| 8231 | 25 objects can change. Objects whose value can change are said to be |
| 26 \emph{mutable}; objects whose value is unchangeable once they are | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
27 created are called \emph{immutable}. |
|
10280
cc9fd50630a6
1. Clarify that immutability isn't entirely the same as unchangeable
Guido van Rossum <guido@python.org>
parents:
10146
diff
changeset
|
28 (The value of an immutable container object that contains a reference |
|
cc9fd50630a6
1. Clarify that immutability isn't entirely the same as unchangeable
Guido van Rossum <guido@python.org>
parents:
10146
diff
changeset
|
29 to a mutable object can change when the latter's value is changed; |
|
cc9fd50630a6
1. Clarify that immutability isn't entirely the same as unchangeable
Guido van Rossum <guido@python.org>
parents:
10146
diff
changeset
|
30 however the container is still considered immutable, because the |
|
cc9fd50630a6
1. Clarify that immutability isn't entirely the same as unchangeable
Guido van Rossum <guido@python.org>
parents:
10146
diff
changeset
|
31 collection of objects it contains cannot be changed. So, immutability |
|
cc9fd50630a6
1. Clarify that immutability isn't entirely the same as unchangeable
Guido van Rossum <guido@python.org>
parents:
10146
diff
changeset
|
32 is not strictly the same as having an unchangeable value, it is more |
|
cc9fd50630a6
1. Clarify that immutability isn't entirely the same as unchangeable
Guido van Rossum <guido@python.org>
parents:
10146
diff
changeset
|
33 subtle.) |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
34 An object's mutability is determined by its type; for instance, |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
35 numbers, strings and tuples are immutable, while dictionaries and |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
36 lists are mutable. |
| 8231 | 37 \index{identity of an object} |
| 38 \index{value of an object} | |
| 39 \index{type of an object} | |
| 40 \index{mutable object} | |
| 41 \index{immutable object} | |
| 42 | |
| 43 Objects are never explicitly destroyed; however, when they become | |
| 44 unreachable they may be garbage-collected. An implementation is | |
|
8871
05c1104e084b
Minor refilling of a paragraph...
Barry Warsaw <barry@python.org>
parents:
8870
diff
changeset
|
45 allowed to postpone garbage collection or omit it altogether --- it is |
|
05c1104e084b
Minor refilling of a paragraph...
Barry Warsaw <barry@python.org>
parents:
8870
diff
changeset
|
46 a matter of implementation quality how garbage collection is |
| 8231 | 47 implemented, as long as no objects are collected that are still |
| 48 reachable. (Implementation note: the current implementation uses a | |
|
16116
60fac62f6c15
Updated note about collection of cyclic garbage, based on comments from
Fred Drake <fdrake@acm.org>
parents:
15987
diff
changeset
|
49 reference-counting scheme with (optional) delayed detection of |
|
60fac62f6c15
Updated note about collection of cyclic garbage, based on comments from
Fred Drake <fdrake@acm.org>
parents:
15987
diff
changeset
|
50 cyclicly linked garbage, which collects most objects as soon as they |
|
60fac62f6c15
Updated note about collection of cyclic garbage, based on comments from
Fred Drake <fdrake@acm.org>
parents:
15987
diff
changeset
|
51 become unreachable, but is not guaranteed to collect garbage |
|
60fac62f6c15
Updated note about collection of cyclic garbage, based on comments from
Fred Drake <fdrake@acm.org>
parents:
15987
diff
changeset
|
52 containing circular references. See the |
|
60fac62f6c15
Updated note about collection of cyclic garbage, based on comments from
Fred Drake <fdrake@acm.org>
parents:
15987
diff
changeset
|
53 \citetitle[../lib/module-gc.html]{Python Library Reference} for |
|
60fac62f6c15
Updated note about collection of cyclic garbage, based on comments from
Fred Drake <fdrake@acm.org>
parents:
15987
diff
changeset
|
54 information on controlling the collection of cyclic garbage.) |
| 8231 | 55 \index{garbage collection} |
| 56 \index{reference counting} | |
| 57 \index{unreachable object} | |
| 58 | |
| 59 Note that the use of the implementation's tracing or debugging | |
| 60 facilities may keep objects alive that would normally be collectable. | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
61 Also note that catching an exception with a |
|
9847
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
62 `\keyword{try}...\keyword{except}' statement may keep objects alive. |
| 8231 | 63 |
| 64 Some objects contain references to ``external'' resources such as open | |
| 65 files or windows. It is understood that these resources are freed | |
| 66 when the object is garbage-collected, but since garbage collection is | |
| 67 not guaranteed to happen, such objects also provide an explicit way to | |
| 68 release the external resource, usually a \method{close()} method. | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
69 Programs are strongly recommended to explicitly close such |
|
9847
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
70 objects. The `\keyword{try}...\keyword{finally}' statement provides |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
71 a convenient way to do this. |
| 8231 | 72 |
| 73 Some objects contain references to other objects; these are called | |
| 74 \emph{containers}. Examples of containers are tuples, lists and | |
| 75 dictionaries. The references are part of a container's value. In | |
| 76 most cases, when we talk about the value of a container, we imply the | |
| 77 values, not the identities of the contained objects; however, when we | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
78 talk about the mutability of a container, only the identities of |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
79 the immediately contained objects are implied. So, if an immutable |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
80 container (like a tuple) |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
81 contains a reference to a mutable object, its value changes |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
82 if that mutable object is changed. |
| 8231 | 83 \index{container} |
| 84 | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
85 Types affect almost all aspects of object behavior. Even the importance |
| 8231 | 86 of object identity is affected in some sense: for immutable types, |
| 87 operations that compute new values may actually return a reference to | |
| 88 any existing object with the same type and value, while for mutable | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
89 objects this is not allowed. E.g., after |
|
9201
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
90 \samp{a = 1; b = 1}, |
| 8231 | 91 \code{a} and \code{b} may or may not refer to the same object with the |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
92 value one, depending on the implementation, but after |
|
9201
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
93 \samp{c = []; d = []}, \code{c} and \code{d} |
| 8231 | 94 are guaranteed to refer to two different, unique, newly created empty |
| 95 lists. | |
|
9201
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
96 (Note that \samp{c = d = []} assigns the same object to both |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
97 \code{c} and \code{d}.) |
| 8231 | 98 |
|
18238
037c8be505e0
Fix a very minor (but annoying when looking for things!) markup nit.
Fred Drake <fdrake@acm.org>
parents:
17988
diff
changeset
|
99 |
|
8777
00524555ef17
Make sure all chapters, sections, and subsections have a \label to give them
Fred Drake <fdrake@acm.org>
parents:
8736
diff
changeset
|
100 \section{The standard type hierarchy\label{types}} |
| 8231 | 101 |
| 102 Below is a list of the types that are built into Python. Extension | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
103 modules written in \C{} can define additional types. Future versions of |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
104 Python may add types to the type hierarchy (e.g., rational |
| 8231 | 105 numbers, efficiently stored arrays of integers, etc.). |
| 106 \index{type} | |
| 107 \indexii{data}{type} | |
| 108 \indexii{type}{hierarchy} | |
| 109 \indexii{extension}{module} | |
| 110 \indexii{C}{language} | |
| 111 | |
| 112 Some of the type descriptions below contain a paragraph listing | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
113 `special attributes.' These are attributes that provide access to the |
| 8231 | 114 implementation and are not intended for general use. Their definition |
|
21159
6fa96b329e15
Remove most references to __members__ and __methods__, leaving only one pair
Fred Drake <fdrake@acm.org>
parents:
21062
diff
changeset
|
115 may change in the future. |
| 8231 | 116 \index{attribute} |
| 117 \indexii{special}{attribute} | |
| 118 \indexiii{generic}{special}{attribute} | |
| 119 | |
| 120 \begin{description} | |
| 121 | |
| 122 \item[None] | |
| 123 This type has a single value. There is a single object with this value. | |
| 124 This object is accessed through the built-in name \code{None}. | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
125 It is used to signify the absence of a value in many situations, e.g., |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
126 it is returned from functions that don't explicitly return anything. |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
127 Its truth value is false. |
| 8231 | 128 \ttindex{None} |
|
9530
83f83f002d2e
Remove two remaining {\tt ...} constructs.
Fred Drake <fdrake@acm.org>
parents:
9528
diff
changeset
|
129 \obindex{None@{\texttt{None}}} |
| 8231 | 130 |
|
15714
2a305129d566
Document the NotImplemented object.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
15622
diff
changeset
|
131 \item[NotImplemented] |
|
2a305129d566
Document the NotImplemented object.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
15622
diff
changeset
|
132 This type has a single value. There is a single object with this value. |
|
2a305129d566
Document the NotImplemented object.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
15622
diff
changeset
|
133 This object is accessed through the built-in name \code{NotImplemented}. |
|
15987
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
134 Numeric methods and rich comparison methods may return this value if |
|
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
135 they do not implement the operation for the operands provided. (The |
|
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
136 interpreter will then try the reflected operation, or some other |
|
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
137 fallback, depending on the operator.) Its truth value is true. |
|
15714
2a305129d566
Document the NotImplemented object.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
15622
diff
changeset
|
138 \ttindex{NotImplemented} |
|
2a305129d566
Document the NotImplemented object.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
15622
diff
changeset
|
139 \obindex{NotImplemented@{\texttt{NotImplemented}}} |
|
2a305129d566
Document the NotImplemented object.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
15622
diff
changeset
|
140 |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
141 \item[Ellipsis] |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
142 This type has a single value. There is a single object with this value. |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
143 This object is accessed through the built-in name \code{Ellipsis}. |
|
9201
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
144 It is used to indicate the presence of the \samp{...} syntax in a |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
145 slice. Its truth value is true. |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
146 \ttindex{Ellipsis} |
|
9530
83f83f002d2e
Remove two remaining {\tt ...} constructs.
Fred Drake <fdrake@acm.org>
parents:
9528
diff
changeset
|
147 \obindex{Ellipsis@{\texttt{Ellipsis}}} |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
148 |
| 8231 | 149 \item[Numbers] |
| 150 These are created by numeric literals and returned as results by | |
| 151 arithmetic operators and arithmetic built-in functions. Numeric | |
| 152 objects are immutable; once created their value never changes. Python | |
| 153 numbers are of course strongly related to mathematical numbers, but | |
| 154 subject to the limitations of numerical representation in computers. | |
| 155 \obindex{numeric} | |
| 156 | |
|
17825
0be16d0ecf64
Make sure we include all of Python's numeric types in the data model
Fred Drake <fdrake@acm.org>
parents:
17594
diff
changeset
|
157 Python distinguishes between integers, floating point numbers, and |
|
0be16d0ecf64
Make sure we include all of Python's numeric types in the data model
Fred Drake <fdrake@acm.org>
parents:
17594
diff
changeset
|
158 complex numbers: |
| 8231 | 159 |
| 160 \begin{description} | |
| 161 \item[Integers] | |
| 162 These represent elements from the mathematical set of whole numbers. | |
| 163 \obindex{integer} | |
| 164 | |
| 165 There are two types of integers: | |
| 166 | |
| 167 \begin{description} | |
| 168 | |
| 169 \item[Plain integers] | |
| 170 These represent numbers in the range -2147483648 through 2147483647. | |
| 171 (The range may be larger on machines with a larger natural word | |
| 172 size, but not smaller.) | |
|
12217
5ea773413531
Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
11462
diff
changeset
|
173 When the result of an operation would fall outside this range, the |
| 8231 | 174 exception \exception{OverflowError} is raised. |
| 175 For the purpose of shift and mask operations, integers are assumed to | |
| 176 have a binary, 2's complement notation using 32 or more bits, and | |
| 177 hiding no bits from the user (i.e., all 4294967296 different bit | |
| 178 patterns correspond to different values). | |
| 179 \obindex{plain integer} | |
| 180 \withsubitem{(built-in exception)}{\ttindex{OverflowError}} | |
| 181 | |
| 182 \item[Long integers] | |
| 183 These represent numbers in an unlimited range, subject to available | |
| 184 (virtual) memory only. For the purpose of shift and mask operations, | |
| 185 a binary representation is assumed, and negative numbers are | |
| 186 represented in a variant of 2's complement which gives the illusion of | |
| 187 an infinite string of sign bits extending to the left. | |
| 188 \obindex{long integer} | |
| 189 | |
| 190 \end{description} % Integers | |
| 191 | |
| 192 The rules for integer representation are intended to give the most | |
| 193 meaningful interpretation of shift and mask operations involving | |
| 194 negative integers and the least surprises when switching between the | |
| 195 plain and long integer domains. For any operation except left shift, | |
| 196 if it yields a result in the plain integer domain without causing | |
| 197 overflow, it will yield the same result in the long integer domain or | |
| 198 when using mixed operands. | |
| 199 \indexii{integer}{representation} | |
| 200 | |
| 201 \item[Floating point numbers] | |
| 202 These represent machine-level double precision floating point numbers. | |
| 203 You are at the mercy of the underlying machine architecture and | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
204 \C{} implementation for the accepted range and handling of overflow. |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
205 Python does not support single-precision floating point numbers; the |
|
18568
55511caa24ee
Minor change to match the style guide.
Fred Drake <fdrake@acm.org>
parents:
18238
diff
changeset
|
206 savings in processor and memory usage that are usually the reason for using |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
207 these is dwarfed by the overhead of using objects in Python, so there |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
208 is no reason to complicate the language with two kinds of floating |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
209 point numbers. |
| 8231 | 210 \obindex{floating point} |
| 211 \indexii{floating point}{number} | |
| 212 \indexii{C}{language} | |
| 213 | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
214 \item[Complex numbers] |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
215 These represent complex numbers as a pair of machine-level double |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
216 precision floating point numbers. The same caveats apply as for |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
217 floating point numbers. The real and imaginary value of a complex |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
218 number \code{z} can be retrieved through the attributes \code{z.real} |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
219 and \code{z.imag}. |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
220 \obindex{complex} |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
221 \indexii{complex}{number} |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
222 |
| 8231 | 223 \end{description} % Numbers |
| 224 | |
| 225 \item[Sequences] | |
|
16740
c10056100ea5
Sequence indexes are non-negative, not natural (0 is not a natural number).
Fred Drake <fdrake@acm.org>
parents:
16116
diff
changeset
|
226 These represent finite ordered sets indexed by non-negative numbers. |
| 8231 | 227 The built-in function \function{len()}\bifuncindex{len} returns the |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
228 number of items of a sequence. |
|
13626
f4da4355acde
More of Rob W. W. Hooft's spelling fixes. The only ones left now are the
Thomas Wouters <thomas@python.org>
parents:
13583
diff
changeset
|
229 When the length of a sequence is \var{n}, the |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
230 index set contains the numbers 0, 1, \ldots, \var{n}-1. Item |
| 8231 | 231 \var{i} of sequence \var{a} is selected by \code{\var{a}[\var{i}]}. |
|
12217
5ea773413531
Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
11462
diff
changeset
|
232 \obindex{sequence} |
| 8231 | 233 \index{index operation} |
| 234 \index{item selection} | |
| 235 \index{subscription} | |
| 236 | |
| 237 Sequences also support slicing: \code{\var{a}[\var{i}:\var{j}]} | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
238 selects all items with index \var{k} such that \var{i} \code{<=} |
| 8231 | 239 \var{k} \code{<} \var{j}. When used as an expression, a slice is a |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
240 sequence of the same type. This implies that the index set is |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
241 renumbered so that it starts at 0. |
| 8231 | 242 \index{slicing} |
| 243 | |
| 244 Sequences are distinguished according to their mutability: | |
| 245 | |
| 246 \begin{description} | |
|
9847
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
247 |
| 8231 | 248 \item[Immutable sequences] |
| 249 An object of an immutable sequence type cannot change once it is | |
| 250 created. (If the object contains references to other objects, | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
251 these other objects may be mutable and may be changed; however, |
| 8231 | 252 the collection of objects directly referenced by an immutable object |
| 253 cannot change.) | |
| 254 \obindex{immutable sequence} | |
| 255 \obindex{immutable} | |
| 256 | |
| 257 The following types are immutable sequences: | |
| 258 | |
| 259 \begin{description} | |
| 260 | |
| 261 \item[Strings] | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
262 The items of a string are characters. There is no separate |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
263 character type; a character is represented by a string of one item. |
| 8231 | 264 Characters represent (at least) 8-bit bytes. The built-in |
| 265 functions \function{chr()}\bifuncindex{chr} and | |
| 266 \function{ord()}\bifuncindex{ord} convert between characters and | |
| 267 nonnegative integers representing the byte values. Bytes with the | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
268 values 0-127 usually represent the corresponding \ASCII{} values, but |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
269 the interpretation of values is up to the program. The string |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
270 data type is also used to represent arrays of bytes, e.g., to hold data |
| 8231 | 271 read from a file. |
| 272 \obindex{string} | |
| 273 \index{character} | |
| 274 \index{byte} | |
|
21062
bc02c3b09626
Clean up some markup cruft. A number of the macros that take no
Fred Drake <fdrake@acm.org>
parents:
20580
diff
changeset
|
275 \index{ASCII@\ASCII} |
| 8231 | 276 |
|
21062
bc02c3b09626
Clean up some markup cruft. A number of the macros that take no
Fred Drake <fdrake@acm.org>
parents:
20580
diff
changeset
|
277 (On systems whose native character set is not \ASCII, strings may use |
| 8231 | 278 EBCDIC in their internal representation, provided the functions |
| 279 \function{chr()} and \function{ord()} implement a mapping between \ASCII{} and | |
| 280 EBCDIC, and string comparison preserves the \ASCII{} order. | |
| 281 Or perhaps someone can propose a better rule?) | |
|
21062
bc02c3b09626
Clean up some markup cruft. A number of the macros that take no
Fred Drake <fdrake@acm.org>
parents:
20580
diff
changeset
|
282 \index{ASCII@\ASCII} |
| 8231 | 283 \index{EBCDIC} |
| 284 \index{character set} | |
| 285 \indexii{string}{comparison} | |
| 286 \bifuncindex{chr} | |
| 287 \bifuncindex{ord} | |
| 288 | |
|
12256
0ba85709a671
Patch from Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12217
diff
changeset
|
289 \item[Unicode] |
|
0ba85709a671
Patch from Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12217
diff
changeset
|
290 The items of a Unicode object are Unicode characters. A Unicode |
|
0ba85709a671
Patch from Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12217
diff
changeset
|
291 character is represented by a Unicode object of one item and can hold |
|
0ba85709a671
Patch from Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12217
diff
changeset
|
292 a 16-bit value representing a Unicode ordinal. The built-in functions |
|
0ba85709a671
Patch from Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12217
diff
changeset
|
293 \function{unichr()}\bifuncindex{unichr} and |
|
0ba85709a671
Patch from Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12217
diff
changeset
|
294 \function{ord()}\bifuncindex{ord} convert between characters and |
|
0ba85709a671
Patch from Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12217
diff
changeset
|
295 nonnegative integers representing the Unicode ordinals as defined in |
|
0ba85709a671
Patch from Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12217
diff
changeset
|
296 the Unicode Standard 3.0. Conversion from and to other encodings are |
|
0ba85709a671
Patch from Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12217
diff
changeset
|
297 possible through the Unicode method \method{encode} and the built-in |
|
0ba85709a671
Patch from Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12217
diff
changeset
|
298 function \function{unicode()}\bifuncindex{unicode}. |
|
0ba85709a671
Patch from Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12217
diff
changeset
|
299 \obindex{unicode} |
|
0ba85709a671
Patch from Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12217
diff
changeset
|
300 \index{character} |
|
0ba85709a671
Patch from Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12217
diff
changeset
|
301 \index{integer} |
|
12257
23266352f138
But don't do the funny \UNICODE macro; we're trying to get away from
Fred Drake <fdrake@acm.org>
parents:
12256
diff
changeset
|
302 \index{Unicode} |
|
12256
0ba85709a671
Patch from Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12217
diff
changeset
|
303 |
| 8231 | 304 \item[Tuples] |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
305 The items of a tuple are arbitrary Python objects. |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
306 Tuples of two or more items are formed by comma-separated lists |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
307 of expressions. A tuple of one item (a `singleton') can be formed |
| 8231 | 308 by affixing a comma to an expression (an expression by itself does |
| 309 not create a tuple, since parentheses must be usable for grouping of | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
310 expressions). An empty tuple can be formed by an empty pair of |
| 8231 | 311 parentheses. |
| 312 \obindex{tuple} | |
| 313 \indexii{singleton}{tuple} | |
| 314 \indexii{empty}{tuple} | |
| 315 | |
| 316 \end{description} % Immutable sequences | |
| 317 | |
| 318 \item[Mutable sequences] | |
| 319 Mutable sequences can be changed after they are created. The | |
| 320 subscription and slicing notations can be used as the target of | |
| 321 assignment and \keyword{del} (delete) statements. | |
|
13626
f4da4355acde
More of Rob W. W. Hooft's spelling fixes. The only ones left now are the
Thomas Wouters <thomas@python.org>
parents:
13583
diff
changeset
|
322 \obindex{mutable sequence} |
| 8231 | 323 \obindex{mutable} |
| 324 \indexii{assignment}{statement} | |
| 325 \index{delete} | |
| 326 \stindex{del} | |
| 327 \index{subscription} | |
| 328 \index{slicing} | |
| 329 | |
| 330 There is currently a single mutable sequence type: | |
| 331 | |
| 332 \begin{description} | |
| 333 | |
| 334 \item[Lists] | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
335 The items of a list are arbitrary Python objects. Lists are formed |
| 8231 | 336 by placing a comma-separated list of expressions in square brackets. |
| 337 (Note that there are no special cases needed to form lists of length 0 | |
| 338 or 1.) | |
| 339 \obindex{list} | |
| 340 | |
| 341 \end{description} % Mutable sequences | |
| 342 | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
343 The extension module \module{array}\refstmodindex{array} provides an |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
344 additional example of a mutable sequence type. |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
345 |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
346 |
| 8231 | 347 \end{description} % Sequences |
| 348 | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
349 \item[Mappings] |
| 8231 | 350 These represent finite sets of objects indexed by arbitrary index sets. |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
351 The subscript notation \code{a[k]} selects the item indexed |
| 8231 | 352 by \code{k} from the mapping \code{a}; this can be used in |
| 353 expressions and as the target of assignments or \keyword{del} statements. | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
354 The built-in function \function{len()} returns the number of items |
| 8231 | 355 in a mapping. |
| 356 \bifuncindex{len} | |
| 357 \index{subscription} | |
| 358 \obindex{mapping} | |
| 359 | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
360 There is currently a single intrinsic mapping type: |
| 8231 | 361 |
| 362 \begin{description} | |
| 363 | |
| 364 \item[Dictionaries] | |
|
10287
3e3c09e14503
Dictionaries are created using the "{...}" notation, not the "..."
Fred Drake <fdrake@acm.org>
parents:
10280
diff
changeset
|
365 These\obindex{dictionary} represent finite sets of objects indexed by |
|
3e3c09e14503
Dictionaries are created using the "{...}" notation, not the "..."
Fred Drake <fdrake@acm.org>
parents:
10280
diff
changeset
|
366 nearly arbitrary values. The only types of values not acceptable as |
|
3e3c09e14503
Dictionaries are created using the "{...}" notation, not the "..."
Fred Drake <fdrake@acm.org>
parents:
10280
diff
changeset
|
367 keys are values containing lists or dictionaries or other mutable |
|
3e3c09e14503
Dictionaries are created using the "{...}" notation, not the "..."
Fred Drake <fdrake@acm.org>
parents:
10280
diff
changeset
|
368 types that are compared by value rather than by object identity, the |
|
3e3c09e14503
Dictionaries are created using the "{...}" notation, not the "..."
Fred Drake <fdrake@acm.org>
parents:
10280
diff
changeset
|
369 reason being that the efficient implementation of dictionaries |
|
3e3c09e14503
Dictionaries are created using the "{...}" notation, not the "..."
Fred Drake <fdrake@acm.org>
parents:
10280
diff
changeset
|
370 requires a key's hash value to remain constant. |
| 8231 | 371 Numeric types used for keys obey the normal rules for numeric |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
372 comparison: if two numbers compare equal (e.g., \code{1} and |
| 8231 | 373 \code{1.0}) then they can be used interchangeably to index the same |
| 374 dictionary entry. | |
| 375 | |
|
19829
bbaea53ac087
Work around a LaTeX2HTML bug that caused the "m" in "mutable" to be dropped
Fred Drake <fdrake@acm.org>
parents:
19254
diff
changeset
|
376 Dictionaries are mutable; they are created by the |
|
10287
3e3c09e14503
Dictionaries are created using the "{...}" notation, not the "..."
Fred Drake <fdrake@acm.org>
parents:
10280
diff
changeset
|
377 \code{\{...\}} notation (see section \ref{dict}, ``Dictionary |
|
3e3c09e14503
Dictionaries are created using the "{...}" notation, not the "..."
Fred Drake <fdrake@acm.org>
parents:
10280
diff
changeset
|
378 Displays''). |
| 8231 | 379 |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
380 The extension modules \module{dbm}\refstmodindex{dbm}, |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
381 \module{gdbm}\refstmodindex{gdbm}, \module{bsddb}\refstmodindex{bsddb} |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
382 provide additional examples of mapping types. |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
383 |
| 8231 | 384 \end{description} % Mapping types |
| 385 | |
| 386 \item[Callable types] | |
|
10287
3e3c09e14503
Dictionaries are created using the "{...}" notation, not the "..."
Fred Drake <fdrake@acm.org>
parents:
10280
diff
changeset
|
387 These\obindex{callable} are the types to which the function call |
|
3e3c09e14503
Dictionaries are created using the "{...}" notation, not the "..."
Fred Drake <fdrake@acm.org>
parents:
10280
diff
changeset
|
388 operation (see section \ref{calls}, ``Calls'') can be applied: |
| 8231 | 389 \indexii{function}{call} |
| 390 \index{invocation} | |
| 391 \indexii{function}{argument} | |
| 392 | |
| 393 \begin{description} | |
| 394 | |
| 395 \item[User-defined functions] | |
| 396 A user-defined function object is created by a function definition | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
397 (see section \ref{function}, ``Function definitions''). It should be |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
398 called with an argument |
| 8231 | 399 list containing the same number of items as the function's formal |
| 400 parameter list. | |
| 401 \indexii{user-defined}{function} | |
| 402 \obindex{function} | |
| 403 \obindex{user-defined function} | |
| 404 | |
|
10280
cc9fd50630a6
1. Clarify that immutability isn't entirely the same as unchangeable
Guido van Rossum <guido@python.org>
parents:
10146
diff
changeset
|
405 Special attributes: \member{func_doc} or \member{__doc__} is the |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
406 function's documentation string, or None if unavailable; |
|
9201
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
407 \member{func_name} or \member{__name__} is the function's name; |
|
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
408 \member{func_defaults} is a tuple containing default argument values for |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
409 those arguments that have defaults, or \code{None} if no arguments |
|
9201
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
410 have a default value; \member{func_code} is the code object representing |
|
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
411 the compiled function body; \member{func_globals} is (a reference to) |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
412 the dictionary that holds the function's global variables --- it |
|
8714
9731d8a6b4f3
'name space' -> 'namespace'
Guido van Rossum <guido@python.org>
parents:
8709
diff
changeset
|
413 defines the global namespace of the module in which the function was |
|
16779
eb29924a3370
Updates to describe function attributes.
Barry Warsaw <barry@python.org>
parents:
16740
diff
changeset
|
414 defined; \member{func_dict} or \member{__dict__} contains the |
|
17205
407d60b2fa41
Add nested scopes spec to appendix.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
16779
diff
changeset
|
415 namespace supporting arbitrary function attributes; |
|
407d60b2fa41
Add nested scopes spec to appendix.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
16779
diff
changeset
|
416 \member{func_closure} is \code{None} or a tuple of cells that contain |
|
407d60b2fa41
Add nested scopes spec to appendix.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
16779
diff
changeset
|
417 binding for the function's free variables. |
|
16779
eb29924a3370
Updates to describe function attributes.
Barry Warsaw <barry@python.org>
parents:
16740
diff
changeset
|
418 |
|
17205
407d60b2fa41
Add nested scopes spec to appendix.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
16779
diff
changeset
|
419 Of these, \member{func_code}, \member{func_defaults}, \member{func_closure}, |
|
16779
eb29924a3370
Updates to describe function attributes.
Barry Warsaw <barry@python.org>
parents:
16740
diff
changeset
|
420 \member{func_doc}/\member{__doc__}, and |
|
eb29924a3370
Updates to describe function attributes.
Barry Warsaw <barry@python.org>
parents:
16740
diff
changeset
|
421 \member{func_dict}/\member{__dict__} may be writable; the |
|
17205
407d60b2fa41
Add nested scopes spec to appendix.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
16779
diff
changeset
|
422 others can never be changed. Additional information about a |
|
407d60b2fa41
Add nested scopes spec to appendix.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
16779
diff
changeset
|
423 function's definition can be retrieved from its code object; see the |
|
407d60b2fa41
Add nested scopes spec to appendix.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
16779
diff
changeset
|
424 description of internal types below. |
|
407d60b2fa41
Add nested scopes spec to appendix.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
16779
diff
changeset
|
425 |
|
407d60b2fa41
Add nested scopes spec to appendix.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
16779
diff
changeset
|
426 In Python 2.1, the \member{func_closure} slot is always \code{None} |
|
407d60b2fa41
Add nested scopes spec to appendix.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
16779
diff
changeset
|
427 unless nested scopes are enabled. (See the appendix.) |
|
407d60b2fa41
Add nested scopes spec to appendix.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
16779
diff
changeset
|
428 |
|
9847
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
429 \withsubitem{(function attribute)}{ |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
430 \ttindex{func_doc} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
431 \ttindex{__doc__} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
432 \ttindex{__name__} |
|
16779
eb29924a3370
Updates to describe function attributes.
Barry Warsaw <barry@python.org>
parents:
16740
diff
changeset
|
433 \ttindex{__dict__} |
|
9847
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
434 \ttindex{func_defaults} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
435 \ttindex{func_code} |
|
16779
eb29924a3370
Updates to describe function attributes.
Barry Warsaw <barry@python.org>
parents:
16740
diff
changeset
|
436 \ttindex{func_globals} |
|
eb29924a3370
Updates to describe function attributes.
Barry Warsaw <barry@python.org>
parents:
16740
diff
changeset
|
437 \ttindex{func_dict}} |
|
8714
9731d8a6b4f3
'name space' -> 'namespace'
Guido van Rossum <guido@python.org>
parents:
8709
diff
changeset
|
438 \indexii{global}{namespace} |
| 8231 | 439 |
| 440 \item[User-defined methods] | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
441 A user-defined method object combines a class, a class instance (or |
|
18947
1346ecf318f2
User-defined methods *can* contain things other than user-defined functions
Fred Drake <fdrake@acm.org>
parents:
18942
diff
changeset
|
442 \code{None}) and any callable object (normally a user-defined |
|
1346ecf318f2
User-defined methods *can* contain things other than user-defined functions
Fred Drake <fdrake@acm.org>
parents:
18942
diff
changeset
|
443 function). |
| 8231 | 444 \obindex{method} |
| 445 \obindex{user-defined method} | |
| 446 \indexii{user-defined}{method} | |
| 447 | |
| 448 Special read-only attributes: \member{im_self} is the class instance | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
449 object, \member{im_func} is the function object; |
|
21304
d980ebcc696a
Correct the description of im_class. (Fred, this is changed in 2.2.
Guido van Rossum <guido@python.org>
parents:
21159
diff
changeset
|
450 \member{im_class} is the class of \member{im_self} for bound methods, |
|
d980ebcc696a
Correct the description of im_class. (Fred, this is changed in 2.2.
Guido van Rossum <guido@python.org>
parents:
21159
diff
changeset
|
451 or the class that asked for the method for unbound methods); |
|
9201
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
452 \member{__doc__} is the method's documentation (same as |
|
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
453 \code{im_func.__doc__}); \member{__name__} is the method name (same as |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
454 \code{im_func.__name__}). |
|
21305
d86d6e0d158c
Add change notes where im_class is discussed, since the exact meaning changes
Fred Drake <fdrake@acm.org>
parents:
21304
diff
changeset
|
455 \versionchanged[\member{im_self} used to refer to the class that |
|
d86d6e0d158c
Add change notes where im_class is discussed, since the exact meaning changes
Fred Drake <fdrake@acm.org>
parents:
21304
diff
changeset
|
456 defined the method]{2.2} |
|
9847
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
457 \withsubitem{(method attribute)}{ |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
458 \ttindex{im_func} |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
459 \ttindex{im_self}} |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
460 |
|
16779
eb29924a3370
Updates to describe function attributes.
Barry Warsaw <barry@python.org>
parents:
16740
diff
changeset
|
461 Methods also support accessing (but not setting) the arbitrary |
|
eb29924a3370
Updates to describe function attributes.
Barry Warsaw <barry@python.org>
parents:
16740
diff
changeset
|
462 function attributes on the underlying function object. |
|
eb29924a3370
Updates to describe function attributes.
Barry Warsaw <barry@python.org>
parents:
16740
diff
changeset
|
463 |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
464 User-defined method objects are created in two ways: when getting an |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
465 attribute of a class that is a user-defined function object, or when |
|
13071
c878dc63d7ae
Revise the description of when functions retrieved from class instances
Fred Drake <fdrake@acm.org>
parents:
12927
diff
changeset
|
466 getting an attribute of a class instance that is a user-defined |
|
c878dc63d7ae
Revise the description of when functions retrieved from class instances
Fred Drake <fdrake@acm.org>
parents:
12927
diff
changeset
|
467 function object defined by the class of the instance. In the former |
|
c878dc63d7ae
Revise the description of when functions retrieved from class instances
Fred Drake <fdrake@acm.org>
parents:
12927
diff
changeset
|
468 case (class attribute), the \member{im_self} attribute is \code{None}, |
|
c878dc63d7ae
Revise the description of when functions retrieved from class instances
Fred Drake <fdrake@acm.org>
parents:
12927
diff
changeset
|
469 and the method object is said to be unbound; in the latter case |
|
c878dc63d7ae
Revise the description of when functions retrieved from class instances
Fred Drake <fdrake@acm.org>
parents:
12927
diff
changeset
|
470 (instance attribute), \method{im_self} is the instance, and the method |
|
c878dc63d7ae
Revise the description of when functions retrieved from class instances
Fred Drake <fdrake@acm.org>
parents:
12927
diff
changeset
|
471 object is said to be bound. For |
|
21304
d980ebcc696a
Correct the description of im_class. (Fred, this is changed in 2.2.
Guido van Rossum <guido@python.org>
parents:
21159
diff
changeset
|
472 instance, when \class{C} is a class which has a method |
|
d980ebcc696a
Correct the description of im_class. (Fred, this is changed in 2.2.
Guido van Rossum <guido@python.org>
parents:
21159
diff
changeset
|
473 \method{f()}, \code{C.f} does not yield the function object |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
474 \code{f}; rather, it yields an unbound method object \code{m} where |
|
9201
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
475 \code{m.im_class} is \class{C}, \code{m.im_func} is \method{f()}, and |
|
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
476 \code{m.im_self} is \code{None}. When \code{x} is a \class{C} |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
477 instance, \code{x.f} yields a bound method object \code{m} where |
|
9201
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
478 \code{m.im_class} is \code{C}, \code{m.im_func} is \method{f()}, and |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
479 \code{m.im_self} is \code{x}. |
|
9847
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
480 \withsubitem{(method attribute)}{ |
|
13071
c878dc63d7ae
Revise the description of when functions retrieved from class instances
Fred Drake <fdrake@acm.org>
parents:
12927
diff
changeset
|
481 \ttindex{im_class}\ttindex{im_func}\ttindex{im_self}} |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
482 |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
483 When an unbound user-defined method object is called, the underlying |
|
9201
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
484 function (\member{im_func}) is called, with the restriction that the |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
485 first argument must be an instance of the proper class |
|
9201
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
486 (\member{im_class}) or of a derived class thereof. |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
487 |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
488 When a bound user-defined method object is called, the underlying |
|
9201
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
489 function (\member{im_func}) is called, inserting the class instance |
|
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
490 (\member{im_self}) in front of the argument list. For instance, when |
|
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
491 \class{C} is a class which contains a definition for a function |
|
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
492 \method{f()}, and \code{x} is an instance of \class{C}, calling |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
493 \code{x.f(1)} is equivalent to calling \code{C.f(x, 1)}. |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
494 |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
495 Note that the transformation from function object to (unbound or |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
496 bound) method object happens each time the attribute is retrieved from |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
497 the class or instance. In some cases, a fruitful optimization is to |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
498 assign the attribute to a local variable and call that local variable. |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
499 Also notice that this transformation only happens for user-defined |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
500 functions; other callable objects (and all non-callable objects) are |
|
13071
c878dc63d7ae
Revise the description of when functions retrieved from class instances
Fred Drake <fdrake@acm.org>
parents:
12927
diff
changeset
|
501 retrieved without transformation. It is also important to note that |
|
c878dc63d7ae
Revise the description of when functions retrieved from class instances
Fred Drake <fdrake@acm.org>
parents:
12927
diff
changeset
|
502 user-defined functions which are attributes of a class instance are |
|
c878dc63d7ae
Revise the description of when functions retrieved from class instances
Fred Drake <fdrake@acm.org>
parents:
12927
diff
changeset
|
503 not converted to bound methods; this \emph{only} happens when the |
|
c878dc63d7ae
Revise the description of when functions retrieved from class instances
Fred Drake <fdrake@acm.org>
parents:
12927
diff
changeset
|
504 function is an attribute of the class. |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
505 |
|
21357
de3c88b5f889
Document generators and the yield statement, avoiding implementation details.
Fred Drake <fdrake@acm.org>
parents:
21305
diff
changeset
|
506 \item[Generator functions\index{generator!function}\index{generator!iterator}] |
|
de3c88b5f889
Document generators and the yield statement, avoiding implementation details.
Fred Drake <fdrake@acm.org>
parents:
21305
diff
changeset
|
507 A function or method which uses the \keyword{yield} statement (see |
|
de3c88b5f889
Document generators and the yield statement, avoiding implementation details.
Fred Drake <fdrake@acm.org>
parents:
21305
diff
changeset
|
508 section~\ref{yield}, ``The \keyword{yield} statement'') is called a |
|
de3c88b5f889
Document generators and the yield statement, avoiding implementation details.
Fred Drake <fdrake@acm.org>
parents:
21305
diff
changeset
|
509 \dfn{generator function}. Such a function, when called, always |
|
de3c88b5f889
Document generators and the yield statement, avoiding implementation details.
Fred Drake <fdrake@acm.org>
parents:
21305
diff
changeset
|
510 returns an iterator object which can be used to execute the body of |
|
de3c88b5f889
Document generators and the yield statement, avoiding implementation details.
Fred Drake <fdrake@acm.org>
parents:
21305
diff
changeset
|
511 the function: calling the iterator's \method{next()} method will |
|
de3c88b5f889
Document generators and the yield statement, avoiding implementation details.
Fred Drake <fdrake@acm.org>
parents:
21305
diff
changeset
|
512 cause the function to execute until it provides a value using the |
|
de3c88b5f889
Document generators and the yield statement, avoiding implementation details.
Fred Drake <fdrake@acm.org>
parents:
21305
diff
changeset
|
513 \keyword{yield} statement. When the function executes a |
|
de3c88b5f889
Document generators and the yield statement, avoiding implementation details.
Fred Drake <fdrake@acm.org>
parents:
21305
diff
changeset
|
514 \keyword{return} statement or falls off the end, a |
|
de3c88b5f889
Document generators and the yield statement, avoiding implementation details.
Fred Drake <fdrake@acm.org>
parents:
21305
diff
changeset
|
515 \exception{StopIteration} exception is raised and the iterator will |
|
de3c88b5f889
Document generators and the yield statement, avoiding implementation details.
Fred Drake <fdrake@acm.org>
parents:
21305
diff
changeset
|
516 have reached the end of the set of values to be returned. |
|
de3c88b5f889
Document generators and the yield statement, avoiding implementation details.
Fred Drake <fdrake@acm.org>
parents:
21305
diff
changeset
|
517 |
| 8231 | 518 \item[Built-in functions] |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
519 A built-in function object is a wrapper around a \C{} function. Examples |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
520 of built-in functions are \function{len()} and \function{math.sin()} |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
521 (\module{math} is a standard built-in module). |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
522 The number and type of the arguments are |
| 8231 | 523 determined by the C function. |
|
9201
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
524 Special read-only attributes: \member{__doc__} is the function's |
|
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
525 documentation string, or \code{None} if unavailable; \member{__name__} |
|
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
526 is the function's name; \member{__self__} is set to \code{None} (but see |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
527 the next item). |
| 8231 | 528 \obindex{built-in function} |
| 529 \obindex{function} | |
| 530 \indexii{C}{language} | |
| 531 | |
| 532 \item[Built-in methods] | |
| 533 This is really a different disguise of a built-in function, this time | |
| 534 containing an object passed to the \C{} function as an implicit extra | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
535 argument. An example of a built-in method is |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
536 \code{\var{list}.append()}, assuming |
| 8231 | 537 \var{list} is a list object. |
|
9201
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
538 In this case, the special read-only attribute \member{__self__} is set |
|
21357
de3c88b5f889
Document generators and the yield statement, avoiding implementation details.
Fred Drake <fdrake@acm.org>
parents:
21305
diff
changeset
|
539 to the object denoted by \var{list}. |
| 8231 | 540 \obindex{built-in method} |
| 541 \obindex{method} | |
| 542 \indexii{built-in}{method} | |
| 543 | |
| 544 \item[Classes] | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
545 Class objects are described below. When a class object is called, |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
546 a new class instance (also described below) is created and |
| 8231 | 547 returned. This implies a call to the class's \method{__init__()} method |
| 548 if it has one. Any arguments are passed on to the \method{__init__()} | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
549 method. If there is no \method{__init__()} method, the class must be called |
| 8231 | 550 without arguments. |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
551 \withsubitem{(object method)}{\ttindex{__init__()}} |
| 8231 | 552 \obindex{class} |
| 553 \obindex{class instance} | |
| 554 \obindex{instance} | |
| 555 \indexii{class object}{call} | |
| 556 | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
557 \item[Class instances] |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
558 Class instances are described below. Class instances are callable |
|
9201
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
559 only when the class has a \method{__call__()} method; \code{x(arguments)} |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
560 is a shorthand for \code{x.__call__(arguments)}. |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
561 |
| 8231 | 562 \end{description} |
| 563 | |
| 564 \item[Modules] | |
| 565 Modules are imported by the \keyword{import} statement (see section | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
566 \ref{import}, ``The \keyword{import} statement''). |
|
8714
9731d8a6b4f3
'name space' -> 'namespace'
Guido van Rossum <guido@python.org>
parents:
8709
diff
changeset
|
567 A module object has a namespace implemented by a dictionary object |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
568 (this is the dictionary referenced by the func_globals attribute of |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
569 functions defined in the module). Attribute references are translated |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
570 to lookups in this dictionary, e.g., \code{m.x} is equivalent to |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
571 \code{m.__dict__["x"]}. |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
572 A module object does not contain the code object used to |
| 8231 | 573 initialize the module (since it isn't needed once the initialization |
| 574 is done). | |
| 575 \stindex{import} | |
| 576 \obindex{module} | |
| 577 | |
|
8714
9731d8a6b4f3
'name space' -> 'namespace'
Guido van Rossum <guido@python.org>
parents:
8709
diff
changeset
|
578 Attribute assignment updates the module's namespace dictionary, |
|
9201
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
579 e.g., \samp{m.x = 1} is equivalent to \samp{m.__dict__["x"] = 1}. |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
580 |
|
8714
9731d8a6b4f3
'name space' -> 'namespace'
Guido van Rossum <guido@python.org>
parents:
8709
diff
changeset
|
581 Special read-only attribute: \member{__dict__} is the module's |
|
9731d8a6b4f3
'name space' -> 'namespace'
Guido van Rossum <guido@python.org>
parents:
8709
diff
changeset
|
582 namespace as a dictionary object. |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
583 \withsubitem{(module attribute)}{\ttindex{__dict__}} |
| 8231 | 584 |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
585 Predefined (writable) attributes: \member{__name__} |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
586 is the module's name; \member{__doc__} is the |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
587 module's documentation string, or |
|
9201
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
588 \code{None} if unavailable; \member{__file__} is the pathname of the |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
589 file from which the module was loaded, if it was loaded from a file. |
|
9201
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
590 The \member{__file__} attribute is not present for C{} modules that are |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
591 statically linked into the interpreter; for extension modules loaded |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
592 dynamically from a shared library, it is the pathname of the shared |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
593 library file. |
|
9847
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
594 \withsubitem{(module attribute)}{ |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
595 \ttindex{__name__} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
596 \ttindex{__doc__} |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
597 \ttindex{__file__}} |
|
8714
9731d8a6b4f3
'name space' -> 'namespace'
Guido van Rossum <guido@python.org>
parents:
8709
diff
changeset
|
598 \indexii{module}{namespace} |
| 8231 | 599 |
| 600 \item[Classes] | |
| 601 Class objects are created by class definitions (see section | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
602 \ref{class}, ``Class definitions''). |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
603 A class has a namespace implemented by a dictionary object. |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
604 Class attribute references are translated to |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
605 lookups in this dictionary, |
|
9201
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
606 e.g., \samp{C.x} is translated to \samp{C.__dict__["x"]}. |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
607 When the attribute name is not found |
| 8231 | 608 there, the attribute search continues in the base classes. The search |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
609 is depth-first, left-to-right in the order of occurrence in the |
| 8231 | 610 base class list. |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
611 When a class attribute reference would yield a user-defined function |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
612 object, it is transformed into an unbound user-defined method object |
|
9201
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
613 (see above). The \member{im_class} attribute of this method object is the |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
614 class for which the attribute reference was initiated. |
| 8231 | 615 \obindex{class} |
| 616 \obindex{class instance} | |
| 617 \obindex{instance} | |
| 618 \indexii{class object}{call} | |
| 619 \index{container} | |
| 620 \obindex{dictionary} | |
| 621 \indexii{class}{attribute} | |
| 622 | |
| 623 Class attribute assignments update the class's dictionary, never the | |
| 624 dictionary of a base class. | |
| 625 \indexiii{class}{attribute}{assignment} | |
| 626 | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
627 A class object can be called (see above) to yield a class instance (see |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
628 below). |
| 8231 | 629 \indexii{class object}{call} |
| 630 | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
631 Special attributes: \member{__name__} is the class name; |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
632 \member{__module__} is the module name in which the class was defined; |
|
8714
9731d8a6b4f3
'name space' -> 'namespace'
Guido van Rossum <guido@python.org>
parents:
8709
diff
changeset
|
633 \member{__dict__} is the dictionary containing the class's namespace; |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
634 \member{__bases__} is a tuple (possibly empty or a singleton) |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
635 containing the base classes, in the order of their occurrence in the |
|
9201
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
636 base class list; \member{__doc__} is the class's documentation string, |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
637 or None if undefined. |
|
9847
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
638 \withsubitem{(class attribute)}{ |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
639 \ttindex{__name__} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
640 \ttindex{__module__} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
641 \ttindex{__dict__} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
642 \ttindex{__bases__} |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
643 \ttindex{__doc__}} |
| 8231 | 644 |
| 645 \item[Class instances] | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
646 A class instance is created by calling a class object (see above). |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
647 A class instance has a namespace implemented as a dictionary which |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
648 is the first place in which |
| 8231 | 649 attribute references are searched. When an attribute is not found |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
650 there, and the instance's class has an attribute by that name, |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
651 the search continues with the class attributes. If a class attribute |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
652 is found that is a user-defined function object (and in no other |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
653 case), it is transformed into an unbound user-defined method object |
|
9201
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
654 (see above). The \member{im_class} attribute of this method object is |
|
21304
d980ebcc696a
Correct the description of im_class. (Fred, this is changed in 2.2.
Guido van Rossum <guido@python.org>
parents:
21159
diff
changeset
|
655 the |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
656 class of the instance for which the attribute reference was initiated. |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
657 If no class attribute is found, and the object's class has a |
|
9201
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
658 \method{__getattr__()} method, that is called to satisfy the lookup. |
| 8231 | 659 \obindex{class instance} |
| 660 \obindex{instance} | |
| 661 \indexii{class}{instance} | |
| 662 \indexii{class instance}{attribute} | |
| 663 | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
664 Attribute assignments and deletions update the instance's dictionary, |
|
9201
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
665 never a class's dictionary. If the class has a \method{__setattr__()} or |
|
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
666 \method{__delattr__()} method, this is called instead of updating the |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
667 instance dictionary directly. |
| 8231 | 668 \indexiii{class instance}{attribute}{assignment} |
| 669 | |
| 670 Class instances can pretend to be numbers, sequences, or mappings if | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
671 they have methods with certain special names. See |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
672 section \ref{specialnames}, ``Special method names.'' |
|
12217
5ea773413531
Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
11462
diff
changeset
|
673 \obindex{numeric} |
| 8231 | 674 \obindex{sequence} |
| 675 \obindex{mapping} | |
| 676 | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
677 Special attributes: \member{__dict__} is the attribute |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
678 dictionary; \member{__class__} is the instance's class. |
|
9847
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
679 \withsubitem{(instance attribute)}{ |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
680 \ttindex{__dict__} |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
681 \ttindex{__class__}} |
| 8231 | 682 |
| 683 \item[Files] | |
|
11462
95a9833b000e
Use \citetitle as appropriate.
Fred Drake <fdrake@acm.org>
parents:
10840
diff
changeset
|
684 A file\obindex{file} object represents an open file. File objects are |
|
95a9833b000e
Use \citetitle as appropriate.
Fred Drake <fdrake@acm.org>
parents:
10840
diff
changeset
|
685 created by the \function{open()}\bifuncindex{open} built-in function, |
|
95a9833b000e
Use \citetitle as appropriate.
Fred Drake <fdrake@acm.org>
parents:
10840
diff
changeset
|
686 and also by |
|
95a9833b000e
Use \citetitle as appropriate.
Fred Drake <fdrake@acm.org>
parents:
10840
diff
changeset
|
687 \withsubitem{(in module os)}{\ttindex{popen()}}\function{os.popen()}, |
|
95a9833b000e
Use \citetitle as appropriate.
Fred Drake <fdrake@acm.org>
parents:
10840
diff
changeset
|
688 \function{os.fdopen()}, and the |
|
95a9833b000e
Use \citetitle as appropriate.
Fred Drake <fdrake@acm.org>
parents:
10840
diff
changeset
|
689 \method{makefile()}\withsubitem{(socket method)}{\ttindex{makefile()}} |
|
95a9833b000e
Use \citetitle as appropriate.
Fred Drake <fdrake@acm.org>
parents:
10840
diff
changeset
|
690 method of socket objects (and perhaps by other functions or methods |
|
95a9833b000e
Use \citetitle as appropriate.
Fred Drake <fdrake@acm.org>
parents:
10840
diff
changeset
|
691 provided by extension modules). The objects |
|
95a9833b000e
Use \citetitle as appropriate.
Fred Drake <fdrake@acm.org>
parents:
10840
diff
changeset
|
692 \ttindex{sys.stdin}\code{sys.stdin}, |
|
95a9833b000e
Use \citetitle as appropriate.
Fred Drake <fdrake@acm.org>
parents:
10840
diff
changeset
|
693 \ttindex{sys.stdout}\code{sys.stdout} and |
|
95a9833b000e
Use \citetitle as appropriate.
Fred Drake <fdrake@acm.org>
parents:
10840
diff
changeset
|
694 \ttindex{sys.stderr}\code{sys.stderr} are initialized to file objects |
|
95a9833b000e
Use \citetitle as appropriate.
Fred Drake <fdrake@acm.org>
parents:
10840
diff
changeset
|
695 corresponding to the interpreter's standard\index{stdio} input, output |
|
95a9833b000e
Use \citetitle as appropriate.
Fred Drake <fdrake@acm.org>
parents:
10840
diff
changeset
|
696 and error streams. See the \citetitle[../lib/lib.html]{Python Library |
|
95a9833b000e
Use \citetitle as appropriate.
Fred Drake <fdrake@acm.org>
parents:
10840
diff
changeset
|
697 Reference} for complete documentation of file objects. |
|
9847
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
698 \withsubitem{(in module sys)}{ |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
699 \ttindex{stdin} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
700 \ttindex{stdout} |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
701 \ttindex{stderr}} |
|
11462
95a9833b000e
Use \citetitle as appropriate.
Fred Drake <fdrake@acm.org>
parents:
10840
diff
changeset
|
702 |
| 8231 | 703 |
| 704 \item[Internal types] | |
| 705 A few types used internally by the interpreter are exposed to the user. | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
706 Their definitions may change with future versions of the interpreter, |
| 8231 | 707 but they are mentioned here for completeness. |
| 708 \index{internal type} | |
| 709 \index{types, internal} | |
| 710 | |
| 711 \begin{description} | |
| 712 | |
| 713 \item[Code objects] | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
714 Code objects represent \emph{byte-compiled} executable Python code, or |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
715 \emph{bytecode}. |
| 8231 | 716 The difference between a code |
| 717 object and a function object is that the function object contains an | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
718 explicit reference to the function's globals (the module in which it |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
719 was defined), while a code object contains no context; |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
720 also the default argument values are stored in the function object, |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
721 not in the code object (because they represent values calculated at |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
722 run-time). Unlike function objects, code objects are immutable and |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
723 contain no references (directly or indirectly) to mutable objects. |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
724 \index{bytecode} |
| 8231 | 725 \obindex{code} |
| 726 | |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
727 Special read-only attributes: \member{co_name} gives the function |
|
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
728 name; \member{co_argcount} is the number of positional arguments |
|
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
729 (including arguments with default values); \member{co_nlocals} is the |
|
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
730 number of local variables used by the function (including arguments); |
|
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
731 \member{co_varnames} is a tuple containing the names of the local |
|
17205
407d60b2fa41
Add nested scopes spec to appendix.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
16779
diff
changeset
|
732 variables (starting with the argument names); \member{co_cellvars} is |
|
407d60b2fa41
Add nested scopes spec to appendix.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
16779
diff
changeset
|
733 a tuple containing the names of local variables that are referenced by |
|
407d60b2fa41
Add nested scopes spec to appendix.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
16779
diff
changeset
|
734 nested functions; \member{co_freevars} is a tuple containing the names |
|
407d60b2fa41
Add nested scopes spec to appendix.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
16779
diff
changeset
|
735 of local variables that are neither local nor global; \member{co_code} |
|
407d60b2fa41
Add nested scopes spec to appendix.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
16779
diff
changeset
|
736 is a string representing the sequence of bytecode instructions; |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
737 \member{co_consts} is a tuple containing the literals used by the |
|
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
738 bytecode; \member{co_names} is a tuple containing the names used by |
|
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
739 the bytecode; \member{co_filename} is the filename from which the code |
|
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
740 was compiled; \member{co_firstlineno} is the first line number of the |
|
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
741 function; \member{co_lnotab} is a string encoding the mapping from |
|
13626
f4da4355acde
More of Rob W. W. Hooft's spelling fixes. The only ones left now are the
Thomas Wouters <thomas@python.org>
parents:
13583
diff
changeset
|
742 byte code offsets to line numbers (for details see the source code of |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
743 the interpreter); \member{co_stacksize} is the required stack size |
|
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
744 (including local variables); \member{co_flags} is an integer encoding |
|
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
745 a number of flags for the interpreter. |
|
17205
407d60b2fa41
Add nested scopes spec to appendix.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
16779
diff
changeset
|
746 |
|
407d60b2fa41
Add nested scopes spec to appendix.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
16779
diff
changeset
|
747 The \member{co_cellvars} and \member{co_freevars} are present in |
|
407d60b2fa41
Add nested scopes spec to appendix.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
16779
diff
changeset
|
748 Python 2.1 when nested scopes are not enabled, but the code itself |
|
407d60b2fa41
Add nested scopes spec to appendix.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
16779
diff
changeset
|
749 does not use or create cells. |
|
407d60b2fa41
Add nested scopes spec to appendix.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
16779
diff
changeset
|
750 |
|
9847
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
751 \withsubitem{(code object attribute)}{ |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
752 \ttindex{co_argcount} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
753 \ttindex{co_code} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
754 \ttindex{co_consts} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
755 \ttindex{co_filename} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
756 \ttindex{co_firstlineno} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
757 \ttindex{co_flags} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
758 \ttindex{co_lnotab} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
759 \ttindex{co_name} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
760 \ttindex{co_names} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
761 \ttindex{co_nlocals} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
762 \ttindex{co_stacksize} |
|
17205
407d60b2fa41
Add nested scopes spec to appendix.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
16779
diff
changeset
|
763 \ttindex{co_varnames} |
|
407d60b2fa41
Add nested scopes spec to appendix.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
16779
diff
changeset
|
764 \ttindex{co_cellvars} |
|
407d60b2fa41
Add nested scopes spec to appendix.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
16779
diff
changeset
|
765 \ttindex{co_freevars}} |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
766 |
|
12217
5ea773413531
Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
11462
diff
changeset
|
767 The following flag bits are defined for \member{co_flags}: bit |
|
5ea773413531
Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
11462
diff
changeset
|
768 \code{0x04} is set if the function uses the \samp{*arguments} syntax |
|
5ea773413531
Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
11462
diff
changeset
|
769 to accept an arbitrary number of positional arguments; bit |
|
5ea773413531
Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
11462
diff
changeset
|
770 \code{0x08} is set if the function uses the \samp{**keywords} syntax |
|
5ea773413531
Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
11462
diff
changeset
|
771 to accept arbitrary keyword arguments; other bits are used internally |
|
17205
407d60b2fa41
Add nested scopes spec to appendix.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
16779
diff
changeset
|
772 or reserved for future use; bit \code{0x10} is set if the function was |
|
407d60b2fa41
Add nested scopes spec to appendix.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
16779
diff
changeset
|
773 compiled with nested scopes enabled. If\index{documentation string} a |
|
407d60b2fa41
Add nested scopes spec to appendix.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
16779
diff
changeset
|
774 code object represents a function, the first item in |
|
407d60b2fa41
Add nested scopes spec to appendix.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
16779
diff
changeset
|
775 \member{co_consts} is the documentation string of the function, or |
|
407d60b2fa41
Add nested scopes spec to appendix.
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
16779
diff
changeset
|
776 \code{None} if undefined. |
| 8231 | 777 |
| 778 \item[Frame objects] | |
| 779 Frame objects represent execution frames. They may occur in traceback | |
| 780 objects (see below). | |
| 781 \obindex{frame} | |
| 782 | |
| 783 Special read-only attributes: \member{f_back} is to the previous | |
| 784 stack frame (towards the caller), or \code{None} if this is the bottom | |
| 785 stack frame; \member{f_code} is the code object being executed in this | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
786 frame; \member{f_locals} is the dictionary used to look up local |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
787 variables; \member{f_globals} is used for global variables; |
|
9201
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
788 \member{f_builtins} is used for built-in (intrinsic) names; |
|
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
789 \member{f_restricted} is a flag indicating whether the function is |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
790 executing in restricted execution mode; |
| 8231 | 791 \member{f_lineno} gives the line number and \member{f_lasti} gives the |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
792 precise instruction (this is an index into the bytecode string of |
| 8231 | 793 the code object). |
|
9847
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
794 \withsubitem{(frame attribute)}{ |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
795 \ttindex{f_back} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
796 \ttindex{f_code} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
797 \ttindex{f_globals} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
798 \ttindex{f_locals} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
799 \ttindex{f_lineno} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
800 \ttindex{f_lasti} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
801 \ttindex{f_builtins} |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
802 \ttindex{f_restricted}} |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
803 |
|
9201
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
804 Special writable attributes: \member{f_trace}, if not \code{None}, is a |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
805 function called at the start of each source code line (this is used by |
|
9201
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
806 the debugger); \member{f_exc_type}, \member{f_exc_value}, |
|
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
807 \member{f_exc_traceback} represent the most recent exception caught in |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
808 this frame. |
|
9847
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
809 \withsubitem{(frame attribute)}{ |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
810 \ttindex{f_trace} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
811 \ttindex{f_exc_type} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
812 \ttindex{f_exc_value} |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
813 \ttindex{f_exc_traceback}} |
| 8231 | 814 |
| 815 \item[Traceback objects] \label{traceback} | |
| 816 Traceback objects represent a stack trace of an exception. A | |
| 817 traceback object is created when an exception occurs. When the search | |
| 818 for an exception handler unwinds the execution stack, at each unwound | |
| 819 level a traceback object is inserted in front of the current | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
820 traceback. When an exception handler is entered, the stack trace is |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
821 made available to the program. |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
822 (See section \ref{try}, ``The \code{try} statement.'') |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
823 It is accessible as \code{sys.exc_traceback}, and also as the third |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
824 item of the tuple returned by \code{sys.exc_info()}. The latter is |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
825 the preferred interface, since it works correctly when the program is |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
826 using multiple threads. |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
827 When the program contains no suitable handler, the stack trace is written |
| 8231 | 828 (nicely formatted) to the standard error stream; if the interpreter is |
| 829 interactive, it is also made available to the user as | |
| 830 \code{sys.last_traceback}. | |
| 831 \obindex{traceback} | |
| 832 \indexii{stack}{trace} | |
| 833 \indexii{exception}{handler} | |
| 834 \indexii{execution}{stack} | |
|
9847
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
835 \withsubitem{(in module sys)}{ |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
836 \ttindex{exc_info} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
837 \ttindex{exc_traceback} |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
838 \ttindex{last_traceback}} |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
839 \ttindex{sys.exc_info} |
| 8231 | 840 \ttindex{sys.exc_traceback} |
| 841 \ttindex{sys.last_traceback} | |
| 842 | |
| 843 Special read-only attributes: \member{tb_next} is the next level in the | |
| 844 stack trace (towards the frame where the exception occurred), or | |
| 845 \code{None} if there is no next level; \member{tb_frame} points to the | |
| 846 execution frame of the current level; \member{tb_lineno} gives the line | |
| 847 number where the exception occurred; \member{tb_lasti} indicates the | |
| 848 precise instruction. The line number and last instruction in the | |
| 849 traceback may differ from the line number of its frame object if the | |
| 850 exception occurred in a \keyword{try} statement with no matching | |
| 851 except clause or with a finally clause. | |
|
9847
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
852 \withsubitem{(traceback attribute)}{ |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
853 \ttindex{tb_next} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
854 \ttindex{tb_frame} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
855 \ttindex{tb_lineno} |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
856 \ttindex{tb_lasti}} |
| 8231 | 857 \stindex{try} |
| 858 | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
859 \item[Slice objects] |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
860 Slice objects are used to represent slices when \emph{extended slice |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
861 syntax} is used. This is a slice using two colons, or multiple slices |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
862 or ellipses separated by commas, e.g., \code{a[i:j:step]}, \code{a[i:j, |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
863 k:l]}, or \code{a[..., i:j])}. They are also created by the built-in |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
864 \function{slice()}\bifuncindex{slice} function. |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
865 |
|
13626
f4da4355acde
More of Rob W. W. Hooft's spelling fixes. The only ones left now are the
Thomas Wouters <thomas@python.org>
parents:
13583
diff
changeset
|
866 Special read-only attributes: \member{start} is the lower bound; |
|
f4da4355acde
More of Rob W. W. Hooft's spelling fixes. The only ones left now are the
Thomas Wouters <thomas@python.org>
parents:
13583
diff
changeset
|
867 \member{stop} is the upper bound; \member{step} is the step value; each is |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
868 \code{None} if omitted. These attributes can have any type. |
|
9847
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
869 \withsubitem{(slice object attribute)}{ |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
870 \ttindex{start} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
871 \ttindex{stop} |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
872 \ttindex{step}} |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
873 |
| 8231 | 874 \end{description} % Internal types |
| 875 | |
| 876 \end{description} % Types | |
| 877 | |
| 878 | |
|
8777
00524555ef17
Make sure all chapters, sections, and subsections have a \label to give them
Fred Drake <fdrake@acm.org>
parents:
8736
diff
changeset
|
879 \section{Special method names\label{specialnames}} |
| 8231 | 880 |
| 881 A class can implement certain operations that are invoked by special | |
|
9057
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
882 syntax (such as arithmetic operations or subscripting and slicing) by |
|
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
883 defining methods with special names. For instance, if a class defines |
|
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
884 a method named \method{__getitem__()}, and \code{x} is an instance of |
|
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
885 this class, then \code{x[i]} is equivalent to |
|
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
886 \code{x.__getitem__(i)}. (The reverse is not true --- if \code{x} is |
|
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
887 a list object, \code{x.__getitem__(i)} is not equivalent to |
|
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
888 \code{x[i]}.) Except where mentioned, attempts to execute an |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
889 operation raise an exception when no appropriate method is defined. |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
890 \withsubitem{(mapping object method)}{\ttindex{__getitem__()}} |
| 8231 | 891 |
|
15494
8b596451f1c1
Added a note that objects which emulate built-in types should only
Fred Drake <fdrake@acm.org>
parents:
14742
diff
changeset
|
892 When implementing a class that emulates any built-in type, it is |
|
8b596451f1c1
Added a note that objects which emulate built-in types should only
Fred Drake <fdrake@acm.org>
parents:
14742
diff
changeset
|
893 important that the emulation only be implemented to the degree that it |
|
8b596451f1c1
Added a note that objects which emulate built-in types should only
Fred Drake <fdrake@acm.org>
parents:
14742
diff
changeset
|
894 makes sense for the object being modelled. For example, some |
|
8b596451f1c1
Added a note that objects which emulate built-in types should only
Fred Drake <fdrake@acm.org>
parents:
14742
diff
changeset
|
895 sequences may work well with retrieval of individual elements, but |
|
8b596451f1c1
Added a note that objects which emulate built-in types should only
Fred Drake <fdrake@acm.org>
parents:
14742
diff
changeset
|
896 extracting a slice may not make sense. (One example of this is the |
|
8b596451f1c1
Added a note that objects which emulate built-in types should only
Fred Drake <fdrake@acm.org>
parents:
14742
diff
changeset
|
897 \class{NodeList} interface in the W3C's Document Object Model.) |
|
8b596451f1c1
Added a note that objects which emulate built-in types should only
Fred Drake <fdrake@acm.org>
parents:
14742
diff
changeset
|
898 |
| 8231 | 899 |
|
8777
00524555ef17
Make sure all chapters, sections, and subsections have a \label to give them
Fred Drake <fdrake@acm.org>
parents:
8736
diff
changeset
|
900 \subsection{Basic customization\label{customization}} |
| 8231 | 901 |
|
18942
90d06cbce26a
Explain that __init__() methods do not get to return values.
Fred Drake <fdrake@acm.org>
parents:
18568
diff
changeset
|
902 \begin{methoddesc}[object]{__init__}{self\optional{, \moreargs}} |
|
90d06cbce26a
Explain that __init__() methods do not get to return values.
Fred Drake <fdrake@acm.org>
parents:
18568
diff
changeset
|
903 Called\indexii{class}{constructor} when the instance is created. The |
|
90d06cbce26a
Explain that __init__() methods do not get to return values.
Fred Drake <fdrake@acm.org>
parents:
18568
diff
changeset
|
904 arguments are those passed to the class constructor expression. If a |
|
90d06cbce26a
Explain that __init__() methods do not get to return values.
Fred Drake <fdrake@acm.org>
parents:
18568
diff
changeset
|
905 base class has an \method{__init__()} method the derived class's |
|
90d06cbce26a
Explain that __init__() methods do not get to return values.
Fred Drake <fdrake@acm.org>
parents:
18568
diff
changeset
|
906 \method{__init__()} method must explicitly call it to ensure proper |
|
90d06cbce26a
Explain that __init__() methods do not get to return values.
Fred Drake <fdrake@acm.org>
parents:
18568
diff
changeset
|
907 initialization of the base class part of the instance; for example: |
|
90d06cbce26a
Explain that __init__() methods do not get to return values.
Fred Drake <fdrake@acm.org>
parents:
18568
diff
changeset
|
908 \samp{BaseClass.__init__(\var{self}, [\var{args}...])}. As a special |
|
90d06cbce26a
Explain that __init__() methods do not get to return values.
Fred Drake <fdrake@acm.org>
parents:
18568
diff
changeset
|
909 contraint on constructors, no value may be returned; doing so will |
|
90d06cbce26a
Explain that __init__() methods do not get to return values.
Fred Drake <fdrake@acm.org>
parents:
18568
diff
changeset
|
910 cause a \exception{TypeError} to be raised at runtime. |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
911 \end{methoddesc} |
| 8231 | 912 |
| 913 | |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
914 \begin{methoddesc}[object]{__del__}{self} |
| 8736 | 915 Called when the instance is about to be destroyed. This is also |
| 916 called a destructor\index{destructor}. If a base class | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
917 has a \method{__del__()} method, the derived class's \method{__del__()} method |
| 8231 | 918 must explicitly call it to ensure proper deletion of the base class |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
919 part of the instance. Note that it is possible (though not recommended!) |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
920 for the \method{__del__()} |
| 8231 | 921 method to postpone destruction of the instance by creating a new |
| 922 reference to it. It may then be called at a later time when this new | |
| 923 reference is deleted. It is not guaranteed that | |
| 924 \method{__del__()} methods are called for objects that still exist when | |
| 925 the interpreter exits. | |
| 926 \stindex{del} | |
| 927 | |
|
21420
4cb223ef869b
Update information about __del__() & reference cycles for CPython.
Fred Drake <fdrake@acm.org>
parents:
21357
diff
changeset
|
928 \begin{notice} |
|
4cb223ef869b
Update information about __del__() & reference cycles for CPython.
Fred Drake <fdrake@acm.org>
parents:
21357
diff
changeset
|
929 \samp{del x} doesn't directly call |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
930 \code{x.__del__()} --- the former decrements the reference count for |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
931 \code{x} by one, and the latter is only called when its reference |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
932 count reaches zero. Some common situations that may prevent the |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
933 reference count of an object to go to zero include: circular |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
934 references between objects (e.g., a doubly-linked list or a tree data |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
935 structure with parent and child pointers); a reference to the object |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
936 on the stack frame of a function that caught an exception (the |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
937 traceback stored in \code{sys.exc_traceback} keeps the stack frame |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
938 alive); or a reference to the object on the stack frame that raised an |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
939 unhandled exception in interactive mode (the traceback stored in |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
940 \code{sys.last_traceback} keeps the stack frame alive). The first |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
941 situation can only be remedied by explicitly breaking the cycles; the |
|
21420
4cb223ef869b
Update information about __del__() & reference cycles for CPython.
Fred Drake <fdrake@acm.org>
parents:
21357
diff
changeset
|
942 latter two situations can be resolved by storing \code{None} in |
|
4cb223ef869b
Update information about __del__() & reference cycles for CPython.
Fred Drake <fdrake@acm.org>
parents:
21357
diff
changeset
|
943 \code{sys.exc_traceback} or \code{sys.last_traceback}. Circular |
|
4cb223ef869b
Update information about __del__() & reference cycles for CPython.
Fred Drake <fdrake@acm.org>
parents:
21357
diff
changeset
|
944 references which are garbage are detected when the option cycle |
|
4cb223ef869b
Update information about __del__() & reference cycles for CPython.
Fred Drake <fdrake@acm.org>
parents:
21357
diff
changeset
|
945 detector is enabled (it's on by default), but can only be cleaned up |
|
4cb223ef869b
Update information about __del__() & reference cycles for CPython.
Fred Drake <fdrake@acm.org>
parents:
21357
diff
changeset
|
946 if there are no Python-level \method{__del__()} methods involved. |
|
4cb223ef869b
Update information about __del__() & reference cycles for CPython.
Fred Drake <fdrake@acm.org>
parents:
21357
diff
changeset
|
947 Refer to the documentation for the \ulink{\module{gc} |
|
4cb223ef869b
Update information about __del__() & reference cycles for CPython.
Fred Drake <fdrake@acm.org>
parents:
21357
diff
changeset
|
948 module}{../lib/module-gc.html} for more information about how |
|
4cb223ef869b
Update information about __del__() & reference cycles for CPython.
Fred Drake <fdrake@acm.org>
parents:
21357
diff
changeset
|
949 \method{__del__()} methods are handled by the cycle detector, |
|
4cb223ef869b
Update information about __del__() & reference cycles for CPython.
Fred Drake <fdrake@acm.org>
parents:
21357
diff
changeset
|
950 particularly the description of the \code{garbage} value. |
|
4cb223ef869b
Update information about __del__() & reference cycles for CPython.
Fred Drake <fdrake@acm.org>
parents:
21357
diff
changeset
|
951 \end{notice} |
| 8231 | 952 |
|
21420
4cb223ef869b
Update information about __del__() & reference cycles for CPython.
Fred Drake <fdrake@acm.org>
parents:
21357
diff
changeset
|
953 \begin{notice}[warning] |
|
4cb223ef869b
Update information about __del__() & reference cycles for CPython.
Fred Drake <fdrake@acm.org>
parents:
21357
diff
changeset
|
954 Due to the precarious circumstances under which |
|
9057
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
955 \method{__del__()} methods are invoked, exceptions that occur during their |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
956 execution are ignored, and a warning is printed to \code{sys.stderr} |
|
21420
4cb223ef869b
Update information about __del__() & reference cycles for CPython.
Fred Drake <fdrake@acm.org>
parents:
21357
diff
changeset
|
957 instead. Also, when \method{__del__()} is invoked in response to a module |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
958 being deleted (e.g., when execution of the program is done), other |
|
9057
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
959 globals referenced by the \method{__del__()} method may already have been |
|
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
960 deleted. For this reason, \method{__del__()} methods should do the |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
961 absolute minimum needed to maintain external invariants. Python 1.5 |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
962 guarantees that globals whose name begins with a single underscore are |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
963 deleted from their module before other globals are deleted; if no |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
964 other references to such globals exist, this may help in assuring that |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
965 imported modules are still available at the time when the |
|
21420
4cb223ef869b
Update information about __del__() & reference cycles for CPython.
Fred Drake <fdrake@acm.org>
parents:
21357
diff
changeset
|
966 \method{__del__()} method is called. |
|
4cb223ef869b
Update information about __del__() & reference cycles for CPython.
Fred Drake <fdrake@acm.org>
parents:
21357
diff
changeset
|
967 \end{notice} |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
968 \end{methoddesc} |
| 8231 | 969 |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
970 \begin{methoddesc}[object]{__repr__}{self} |
|
9201
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
971 Called by the \function{repr()}\bifuncindex{repr} built-in function |
|
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
972 and by string conversions (reverse quotes) to compute the ``official'' |
| 15622 | 973 string representation of an object. If at all possible, this should |
|
15617
052e372ce151
Clarify __repr__ and __str__.
Guido van Rossum <guido@python.org>
parents:
15510
diff
changeset
|
974 look like a valid Python expression that could be used to recreate an |
|
052e372ce151
Clarify __repr__ and __str__.
Guido van Rossum <guido@python.org>
parents:
15510
diff
changeset
|
975 object with the same value (given an appropriate environment). If |
|
052e372ce151
Clarify __repr__ and __str__.
Guido van Rossum <guido@python.org>
parents:
15510
diff
changeset
|
976 this is not possible, a string of the form \samp{<\var{...some useful |
|
052e372ce151
Clarify __repr__ and __str__.
Guido van Rossum <guido@python.org>
parents:
15510
diff
changeset
|
977 description...}>} should be returned. The return value must be a |
|
052e372ce151
Clarify __repr__ and __str__.
Guido van Rossum <guido@python.org>
parents:
15510
diff
changeset
|
978 string object. |
|
052e372ce151
Clarify __repr__ and __str__.
Guido van Rossum <guido@python.org>
parents:
15510
diff
changeset
|
979 |
|
052e372ce151
Clarify __repr__ and __str__.
Guido van Rossum <guido@python.org>
parents:
15510
diff
changeset
|
980 This is typically used for debugging, so it is important that the |
|
052e372ce151
Clarify __repr__ and __str__.
Guido van Rossum <guido@python.org>
parents:
15510
diff
changeset
|
981 representation is information-rich and unambiguous. |
| 8231 | 982 \indexii{string}{conversion} |
| 983 \indexii{reverse}{quotes} | |
| 984 \indexii{backward}{quotes} | |
| 985 \index{back-quotes} | |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
986 \end{methoddesc} |
| 8231 | 987 |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
988 \begin{methoddesc}[object]{__str__}{self} |
|
9057
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
989 Called by the \function{str()}\bifuncindex{str} built-in function and |
|
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
990 by the \keyword{print}\stindex{print} statement to compute the |
|
9201
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
991 ``informal'' string representation of an object. This differs from |
|
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
992 \method{__repr__()} in that it does not have to be a valid Python |
|
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
993 expression: a more convenient or concise representation may be used |
|
15617
052e372ce151
Clarify __repr__ and __str__.
Guido van Rossum <guido@python.org>
parents:
15510
diff
changeset
|
994 instead. The return value must be a string object. |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
995 \end{methoddesc} |
| 8231 | 996 |
|
15987
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
997 \begin{methoddesc}[object]{__lt__}{self, other} |
|
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
998 \methodline[object]{__le__}{self, other} |
|
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
999 \methodline[object]{__eq__}{self, other} |
|
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
1000 \methodline[object]{__ne__}{self, other} |
|
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
1001 \methodline[object]{__gt__}{self, other} |
|
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
1002 \methodline[object]{__ge__}{self, other} |
|
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
1003 \versionadded{2.1} |
|
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
1004 These are the so-called ``rich comparison'' methods, and are called |
|
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
1005 for comparison operators in preference to \method{__cmp__()} below. |
|
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
1006 The correspondence between operator symbols and method names is as |
|
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
1007 follows: |
|
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
1008 \code{\var{x}<\var{y}} calls \code{\var{x}.__lt__(\var{y})}, |
|
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
1009 \code{\var{x}<=\var{y}} calls \code{\var{x}.__le__(\var{y})}, |
|
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
1010 \code{\var{x}==\var{y}} calls \code{\var{x}.__eq__(\var{y})}, |
|
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
1011 \code{\var{x}!=\var{y}} and \code{\var{x}<>\var{y}} call |
|
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
1012 \code{\var{x}.__ne__(\var{y})}, |
|
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
1013 \code{\var{x}>\var{y}} calls \code{\var{x}.__gt__(\var{y})}, and |
|
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
1014 \code{\var{x}>=\var{y}} calls \code{\var{x}.__ge__(\var{y})}. |
|
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
1015 These methods can return any value, but if the comparison operator is |
|
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
1016 used in a Boolean context, the return value should be interpretable as |
|
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
1017 a Boolean value, else a \exception{TypeError} will be raised. |
|
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
1018 By convention, \code{0} is used for false and \code{1} for true. |
|
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
1019 |
|
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
1020 There are no reflected (swapped-argument) versions of these methods |
|
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
1021 (to be used when the left argument does not support the operation but |
|
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
1022 the right argument does); rather, \method{__lt__()} and |
|
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
1023 \method{__gt__()} are each other's reflection, \method{__le__()} and |
|
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
1024 \method{__ge__()} are each other's reflection, and \method{__eq__()} |
|
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
1025 and \method{__ne__()} are their own reflection. |
|
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
1026 |
|
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
1027 Arguments to rich comparison methods are never coerced. A rich |
|
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
1028 comparison method may return \code{NotImplemented} if it does not |
|
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
1029 implement the operation for a given pair of arguments. |
|
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
1030 \end{methoddesc} |
|
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
1031 |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1032 \begin{methoddesc}[object]{__cmp__}{self, other} |
|
15987
5fb86507519c
Document rich comparisons.
Guido van Rossum <guido@python.org>
parents:
15736
diff
changeset
|
1033 Called by comparison operations if rich comparison (see above) is not |
|
17988
e819cc0a9ef6
Bring the notes on the relationship between __cmp__(), __eq__(), and
Fred Drake <fdrake@acm.org>
parents:
17825
diff
changeset
|
1034 defined. Should return a negative integer if \code{self < other}, |
|
e819cc0a9ef6
Bring the notes on the relationship between __cmp__(), __eq__(), and
Fred Drake <fdrake@acm.org>
parents:
17825
diff
changeset
|
1035 zero if \code{self == other}, a positive integer if \code{self > |
|
e819cc0a9ef6
Bring the notes on the relationship between __cmp__(), __eq__(), and
Fred Drake <fdrake@acm.org>
parents:
17825
diff
changeset
|
1036 other}. If no \method{__cmp__()}, \method{__eq__()} or |
|
e819cc0a9ef6
Bring the notes on the relationship between __cmp__(), __eq__(), and
Fred Drake <fdrake@acm.org>
parents:
17825
diff
changeset
|
1037 \method{__ne__()} operation is defined, class instances are compared |
|
e819cc0a9ef6
Bring the notes on the relationship between __cmp__(), __eq__(), and
Fred Drake <fdrake@acm.org>
parents:
17825
diff
changeset
|
1038 by object identity (``address''). See also the description of |
|
e819cc0a9ef6
Bring the notes on the relationship between __cmp__(), __eq__(), and
Fred Drake <fdrake@acm.org>
parents:
17825
diff
changeset
|
1039 \method{__hash__()} for some important notes on creating objects which |
|
e819cc0a9ef6
Bring the notes on the relationship between __cmp__(), __eq__(), and
Fred Drake <fdrake@acm.org>
parents:
17825
diff
changeset
|
1040 support custom comparison operations and are usable as dictionary |
|
e819cc0a9ef6
Bring the notes on the relationship between __cmp__(), __eq__(), and
Fred Drake <fdrake@acm.org>
parents:
17825
diff
changeset
|
1041 keys. |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1042 (Note: the restriction that exceptions are not propagated by |
|
9201
eb803e191887
Fix some confusion in the __repr__() and __str__() descriptions.
Fred Drake <fdrake@acm.org>
parents:
9057
diff
changeset
|
1043 \method{__cmp__()} has been removed in Python 1.5.) |
| 8231 | 1044 \bifuncindex{cmp} |
| 1045 \index{comparisons} | |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1046 \end{methoddesc} |
| 8231 | 1047 |
|
12927
15df3fa0fd4d
Fix markup error that hid a tilde character; reported long ago by
Fred Drake <fdrake@acm.org>
parents:
12257
diff
changeset
|
1048 \begin{methoddesc}[object]{__rcmp__}{self, other} |
|
15736
6124cedf8438
__rcmp__() description: Changed to indicate that this is no longer
Fred Drake <fdrake@acm.org>
parents:
15714
diff
changeset
|
1049 \versionchanged[No longer supported]{2.1} |
|
12927
15df3fa0fd4d
Fix markup error that hid a tilde character; reported long ago by
Fred Drake <fdrake@acm.org>
parents:
12257
diff
changeset
|
1050 \end{methoddesc} |
|
15df3fa0fd4d
Fix markup error that hid a tilde character; reported long ago by
Fred Drake <fdrake@acm.org>
parents:
12257
diff
changeset
|
1051 |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1052 \begin{methoddesc}[object]{__hash__}{self} |
|
9057
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1053 Called for the key object for dictionary\obindex{dictionary} |
|
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1054 operations, and by the built-in function |
| 8231 | 1055 \function{hash()}\bifuncindex{hash}. Should return a 32-bit integer |
| 1056 usable as a hash value | |
| 1057 for dictionary operations. The only required property is that objects | |
| 1058 which compare equal have the same hash value; it is advised to somehow | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1059 mix together (e.g., using exclusive or) the hash values for the |
| 8231 | 1060 components of the object that also play a part in comparison of |
| 1061 objects. If a class does not define a \method{__cmp__()} method it should | |
| 1062 not define a \method{__hash__()} operation either; if it defines | |
|
17988
e819cc0a9ef6
Bring the notes on the relationship between __cmp__(), __eq__(), and
Fred Drake <fdrake@acm.org>
parents:
17825
diff
changeset
|
1063 \method{__cmp__()} or \method{__eq__()} but not \method{__hash__()}, |
|
e819cc0a9ef6
Bring the notes on the relationship between __cmp__(), __eq__(), and
Fred Drake <fdrake@acm.org>
parents:
17825
diff
changeset
|
1064 its instances will not be usable as dictionary keys. If a class |
|
e819cc0a9ef6
Bring the notes on the relationship between __cmp__(), __eq__(), and
Fred Drake <fdrake@acm.org>
parents:
17825
diff
changeset
|
1065 defines mutable objects and implements a \method{__cmp__()} or |
|
e819cc0a9ef6
Bring the notes on the relationship between __cmp__(), __eq__(), and
Fred Drake <fdrake@acm.org>
parents:
17825
diff
changeset
|
1066 \method{__eq__()} method, it should not implement \method{__hash__()}, |
|
e819cc0a9ef6
Bring the notes on the relationship between __cmp__(), __eq__(), and
Fred Drake <fdrake@acm.org>
parents:
17825
diff
changeset
|
1067 since the dictionary implementation requires that a key's hash value |
|
e819cc0a9ef6
Bring the notes on the relationship between __cmp__(), __eq__(), and
Fred Drake <fdrake@acm.org>
parents:
17825
diff
changeset
|
1068 is immutable (if the object's hash value changes, it will be in the |
|
e819cc0a9ef6
Bring the notes on the relationship between __cmp__(), __eq__(), and
Fred Drake <fdrake@acm.org>
parents:
17825
diff
changeset
|
1069 wrong hash bucket). |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1070 \withsubitem{(object method)}{\ttindex{__cmp__()}} |
|
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1071 \end{methoddesc} |
| 8231 | 1072 |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1073 \begin{methoddesc}[object]{__nonzero__}{self} |
|
9057
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1074 Called to implement truth value testing; should return \code{0} or |
|
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1075 \code{1}. When this method is not defined, \method{__len__()} is |
|
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1076 called, if it is defined (see below). If a class defines neither |
|
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1077 \method{__len__()} nor \method{__nonzero__()}, all its instances are |
|
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1078 considered true. |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1079 \withsubitem{(mapping object method)}{\ttindex{__len__()}} |
|
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1080 \end{methoddesc} |
| 8231 | 1081 |
| 1082 | |
|
8777
00524555ef17
Make sure all chapters, sections, and subsections have a \label to give them
Fred Drake <fdrake@acm.org>
parents:
8736
diff
changeset
|
1083 \subsection{Customizing attribute access\label{attribute-access}} |
| 8231 | 1084 |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1085 The following methods can be defined to customize the meaning of |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1086 attribute access (use of, assignment to, or deletion of \code{x.name}) |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1087 for class instances. |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1088 For performance reasons, these methods are cached in the class object |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1089 at class definition time; therefore, they cannot be changed after the |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1090 class definition is executed. |
| 8231 | 1091 |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1092 \begin{methoddesc}[object]{__getattr__}{self, name} |
| 8231 | 1093 Called when an attribute lookup has not found the attribute in the |
| 1094 usual places (i.e. it is not an instance attribute nor is it found in | |
| 1095 the class tree for \code{self}). \code{name} is the attribute name. | |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1096 This method should return the (computed) attribute value or raise an |
|
9057
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1097 \exception{AttributeError} exception. |
| 8231 | 1098 |
| 1099 Note that if the attribute is found through the normal mechanism, | |
|
9057
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1100 \method{__getattr__()} is not called. (This is an intentional |
|
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1101 asymmetry between \method{__getattr__()} and \method{__setattr__()}.) |
| 8231 | 1102 This is done both for efficiency reasons and because otherwise |
|
9057
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1103 \method{__setattr__()} would have no way to access other attributes of |
|
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1104 the instance. |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1105 Note that at least for instance variables, you can fake |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1106 total control by not inserting any values in the instance |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1107 attribute dictionary (but instead inserting them in another object). |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1108 \withsubitem{(object method)}{\ttindex{__setattr__()}} |
|
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1109 \end{methoddesc} |
| 8231 | 1110 |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1111 \begin{methoddesc}[object]{__setattr__}{self, name, value} |
| 8231 | 1112 Called when an attribute assignment is attempted. This is called |
|
9057
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1113 instead of the normal mechanism (i.e.\ store the value in the instance |
|
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1114 dictionary). \var{name} is the attribute name, \var{value} is the |
| 8231 | 1115 value to be assigned to it. |
| 1116 | |
|
9057
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1117 If \method{__setattr__()} wants to assign to an instance attribute, it |
|
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1118 should not simply execute \samp{self.\var{name} = value} --- this |
|
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1119 would cause a recursive call to itself. Instead, it should insert the |
|
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1120 value in the dictionary of instance attributes, e.g., |
|
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1121 \samp{self.__dict__[\var{name}] = value}. |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1122 \withsubitem{(instance attribute)}{\ttindex{__dict__}} |
|
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1123 \end{methoddesc} |
| 8231 | 1124 |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1125 \begin{methoddesc}[object]{__delattr__}{self, name} |
|
9057
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1126 Like \method{__setattr__()} but for attribute deletion instead of |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1127 assignment. This should only be implemented if \samp{del |
|
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1128 obj.\var{name}} is meaningful for the object. |
|
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1129 \end{methoddesc} |
| 8231 | 1130 |
| 1131 | |
|
8777
00524555ef17
Make sure all chapters, sections, and subsections have a \label to give them
Fred Drake <fdrake@acm.org>
parents:
8736
diff
changeset
|
1132 \subsection{Emulating callable objects\label{callable-types}} |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1133 |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1134 \begin{methoddesc}[object]{__call__}{self\optional{, args...}} |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1135 Called when the instance is ``called'' as a function; if this method |
|
9057
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1136 is defined, \code{\var{x}(arg1, arg2, ...)} is a shorthand for |
|
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1137 \code{\var{x}.__call__(arg1, arg2, ...)}. |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1138 \indexii{call}{instance} |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1139 \end{methoddesc} |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1140 |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1141 |
|
20196
6de4ee477949
Refer to the objects which define __len__(), __*item__(), and __iter__()
Fred Drake <fdrake@acm.org>
parents:
19962
diff
changeset
|
1142 \subsection{Emulating container types\label{sequence-types}} |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1143 |
|
20196
6de4ee477949
Refer to the objects which define __len__(), __*item__(), and __iter__()
Fred Drake <fdrake@acm.org>
parents:
19962
diff
changeset
|
1144 The following methods can be defined to implement container |
|
6de4ee477949
Refer to the objects which define __len__(), __*item__(), and __iter__()
Fred Drake <fdrake@acm.org>
parents:
19962
diff
changeset
|
1145 objects. Containers usually are sequences (such as lists or tuples) |
|
6de4ee477949
Refer to the objects which define __len__(), __*item__(), and __iter__()
Fred Drake <fdrake@acm.org>
parents:
19962
diff
changeset
|
1146 or mappings (like dictionaries), but can represent other containers as |
|
6de4ee477949
Refer to the objects which define __len__(), __*item__(), and __iter__()
Fred Drake <fdrake@acm.org>
parents:
19962
diff
changeset
|
1147 well. The first set of methods is used either to emulate a |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1148 sequence or to emulate a mapping; the difference is that for a |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1149 sequence, the allowable keys should be the integers \var{k} for which |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1150 \code{0 <= \var{k} < \var{N}} where \var{N} is the length of the |
|
14037
91f847a783d2
Apply SF patch #101029: call __getitem__ with a proper slice object if there
Thomas Wouters <thomas@python.org>
parents:
13626
diff
changeset
|
1151 sequence, or slice objects, which define a range of items. (For backwards |
|
91f847a783d2
Apply SF patch #101029: call __getitem__ with a proper slice object if there
Thomas Wouters <thomas@python.org>
parents:
13626
diff
changeset
|
1152 compatibility, the method \method{__getslice__()} (see below) can also be |
|
91f847a783d2
Apply SF patch #101029: call __getitem__ with a proper slice object if there
Thomas Wouters <thomas@python.org>
parents:
13626
diff
changeset
|
1153 defined to handle simple, but not extended slices.) It is also recommended |
|
14043
023468117514
Adjust the way __getslice__() is marked as deprecated; this will also
Fred Drake <fdrake@acm.org>
parents:
14037
diff
changeset
|
1154 that mappings provide the methods \method{keys()}, \method{values()}, |
|
14037
91f847a783d2
Apply SF patch #101029: call __getitem__ with a proper slice object if there
Thomas Wouters <thomas@python.org>
parents:
13626
diff
changeset
|
1155 \method{items()}, \method{has_key()}, \method{get()}, \method{clear()}, |
|
91f847a783d2
Apply SF patch #101029: call __getitem__ with a proper slice object if there
Thomas Wouters <thomas@python.org>
parents:
13626
diff
changeset
|
1156 \method{copy()}, and \method{update()} behaving similar to those for |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1157 Python's standard dictionary objects; mutable sequences should provide |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1158 methods \method{append()}, \method{count()}, \method{index()}, |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1159 \method{insert()}, \method{pop()}, \method{remove()}, \method{reverse()} |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1160 and \method{sort()}, like Python standard list objects. Finally, |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1161 sequence types should implement addition (meaning concatenation) and |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1162 multiplication (meaning repetition) by defining the methods |
|
14160
5468b6e3b96a
Rough and incomplete documentation on augmented assignment, which follows
Thomas Wouters <thomas@python.org>
parents:
14043
diff
changeset
|
1163 \method{__add__()}, \method{__radd__()}, \method{__iadd__()}, |
|
5468b6e3b96a
Rough and incomplete documentation on augmented assignment, which follows
Thomas Wouters <thomas@python.org>
parents:
14043
diff
changeset
|
1164 \method{__mul__()}, \method{__rmul__()} and \method{__imul__()} described |
|
5468b6e3b96a
Rough and incomplete documentation on augmented assignment, which follows
Thomas Wouters <thomas@python.org>
parents:
14043
diff
changeset
|
1165 below; they should not define \method{__coerce__()} or other numerical |
|
17594
bf94af396b1e
Implement, test and document "key in dict" and "key not in dict".
Guido van Rossum <guido@python.org>
parents:
17492
diff
changeset
|
1166 operators. It is recommended that both mappings and sequences |
|
19962
cc52b05ac979
Fix minor usage and consistency nits.
Fred Drake <fdrake@acm.org>
parents:
19829
diff
changeset
|
1167 implement the \method{__contains__()} method to allow efficient use of |
|
cc52b05ac979
Fix minor usage and consistency nits.
Fred Drake <fdrake@acm.org>
parents:
19829
diff
changeset
|
1168 the \code{in} operator; for mappings, \code{in} should be equivalent |
|
cc52b05ac979
Fix minor usage and consistency nits.
Fred Drake <fdrake@acm.org>
parents:
19829
diff
changeset
|
1169 of \method{has_key()}; for sequences, it should search through the |
|
cc52b05ac979
Fix minor usage and consistency nits.
Fred Drake <fdrake@acm.org>
parents:
19829
diff
changeset
|
1170 values. |
|
9847
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
1171 \withsubitem{(mapping object method)}{ |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
1172 \ttindex{keys()} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
1173 \ttindex{values()} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
1174 \ttindex{items()} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
1175 \ttindex{has_key()} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
1176 \ttindex{get()} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
1177 \ttindex{clear()} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
1178 \ttindex{copy()} |
|
17594
bf94af396b1e
Implement, test and document "key in dict" and "key not in dict".
Guido van Rossum <guido@python.org>
parents:
17492
diff
changeset
|
1179 \ttindex{update()} |
|
bf94af396b1e
Implement, test and document "key in dict" and "key not in dict".
Guido van Rossum <guido@python.org>
parents:
17492
diff
changeset
|
1180 \ttindex{__contains__()}} |
|
9847
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
1181 \withsubitem{(sequence object method)}{ |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
1182 \ttindex{append()} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
1183 \ttindex{count()} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
1184 \ttindex{index()} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
1185 \ttindex{insert()} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
1186 \ttindex{pop()} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
1187 \ttindex{remove()} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
1188 \ttindex{reverse()} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
1189 \ttindex{sort()} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
1190 \ttindex{__add__()} |
|
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
1191 \ttindex{__radd__()} |
|
14160
5468b6e3b96a
Rough and incomplete documentation on augmented assignment, which follows
Thomas Wouters <thomas@python.org>
parents:
14043
diff
changeset
|
1192 \ttindex{__iadd__()} |
|
9847
5bac56ffcca8
Removed a lot of unnecessary comment markers which cause unexplained
Fred Drake <fdrake@acm.org>
parents:
9530
diff
changeset
|
1193 \ttindex{__mul__()} |
|
14160
5468b6e3b96a
Rough and incomplete documentation on augmented assignment, which follows
Thomas Wouters <thomas@python.org>
parents:
14043
diff
changeset
|
1194 \ttindex{__rmul__()} |
|
17594
bf94af396b1e
Implement, test and document "key in dict" and "key not in dict".
Guido van Rossum <guido@python.org>
parents:
17492
diff
changeset
|
1195 \ttindex{__imul__()} |
|
bf94af396b1e
Implement, test and document "key in dict" and "key not in dict".
Guido van Rossum <guido@python.org>
parents:
17492
diff
changeset
|
1196 \ttindex{__contains__()}} |
|
10002
4ab5e9f839d9
"numberic" --> "numeric", two places
Fred Drake <fdrake@acm.org>
parents:
9847
diff
changeset
|
1197 \withsubitem{(numeric object method)}{\ttindex{__coerce__()}} |
| 8231 | 1198 |
|
20196
6de4ee477949
Refer to the objects which define __len__(), __*item__(), and __iter__()
Fred Drake <fdrake@acm.org>
parents:
19962
diff
changeset
|
1199 \begin{methoddesc}[container object]{__len__}{self} |
|
9057
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1200 Called to implement the built-in function |
|
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1201 \function{len()}\bifuncindex{len}. Should return the length of the |
|
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1202 object, an integer \code{>=} 0. Also, an object that doesn't define a |
|
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1203 \method{__nonzero__()} method and whose \method{__len__()} method |
|
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1204 returns zero is considered to be false in a Boolean context. |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1205 \withsubitem{(object method)}{\ttindex{__nonzero__()}} |
|
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1206 \end{methoddesc} |
| 8231 | 1207 |
|
20196
6de4ee477949
Refer to the objects which define __len__(), __*item__(), and __iter__()
Fred Drake <fdrake@acm.org>
parents:
19962
diff
changeset
|
1208 \begin{methoddesc}[container object]{__getitem__}{self, key} |
|
9057
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1209 Called to implement evaluation of \code{\var{self}[\var{key}]}. |
|
14712
a6970449df42
Note that __getitem__() may receive a slice object as the index;
Fred Drake <fdrake@acm.org>
parents:
14690
diff
changeset
|
1210 For sequence types, the accepted keys should be integers and slice |
|
a6970449df42
Note that __getitem__() may receive a slice object as the index;
Fred Drake <fdrake@acm.org>
parents:
14690
diff
changeset
|
1211 objects.\obindex{slice} Note that |
|
a6970449df42
Note that __getitem__() may receive a slice object as the index;
Fred Drake <fdrake@acm.org>
parents:
14690
diff
changeset
|
1212 the special interpretation of negative indexes (if the class wishes to |
| 8231 | 1213 emulate a sequence type) is up to the \method{__getitem__()} method. |
|
13583
ad1c8271b6f8
Improve the descriptions of expected exceptions for __getitem__(),
Fred Drake <fdrake@acm.org>
parents:
13071
diff
changeset
|
1214 If \var{key} is of an inappropriate type, \exception{TypeError} may be |
|
ad1c8271b6f8
Improve the descriptions of expected exceptions for __getitem__(),
Fred Drake <fdrake@acm.org>
parents:
13071
diff
changeset
|
1215 raised; if of a value outside the set of indexes for the sequence |
|
ad1c8271b6f8
Improve the descriptions of expected exceptions for __getitem__(),
Fred Drake <fdrake@acm.org>
parents:
13071
diff
changeset
|
1216 (after any special interpretation of negative values), |
|
ad1c8271b6f8
Improve the descriptions of expected exceptions for __getitem__(),
Fred Drake <fdrake@acm.org>
parents:
13071
diff
changeset
|
1217 \exception{IndexError} should be raised. |
|
20580
376ee174ecd0
Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents:
20196
diff
changeset
|
1218 \note{\keyword{for} loops expect that an |
|
13583
ad1c8271b6f8
Improve the descriptions of expected exceptions for __getitem__(),
Fred Drake <fdrake@acm.org>
parents:
13071
diff
changeset
|
1219 \exception{IndexError} will be raised for illegal indexes to allow |
|
20580
376ee174ecd0
Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents:
20196
diff
changeset
|
1220 proper detection of the end of the sequence.} |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1221 \end{methoddesc} |
| 8231 | 1222 |
|
20196
6de4ee477949
Refer to the objects which define __len__(), __*item__(), and __iter__()
Fred Drake <fdrake@acm.org>
parents:
19962
diff
changeset
|
1223 \begin{methoddesc}[container object]{__setitem__}{self, key, value} |
|
9057
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1224 Called to implement assignment to \code{\var{self}[\var{key}]}. Same |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1225 note as for \method{__getitem__()}. This should only be implemented |
|
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1226 for mappings if the objects support changes to the values for keys, or |
|
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1227 if new keys can be added, or for sequences if elements can be |
|
13583
ad1c8271b6f8
Improve the descriptions of expected exceptions for __getitem__(),
Fred Drake <fdrake@acm.org>
parents:
13071
diff
changeset
|
1228 replaced. The same exceptions should be raised for improper |
|
ad1c8271b6f8
Improve the descriptions of expected exceptions for __getitem__(),
Fred Drake <fdrake@acm.org>
parents:
13071
diff
changeset
|
1229 \var{key} values as for the \method{__getitem__()} method. |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1230 \end{methoddesc} |
|
9057
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1231 |
|
20196
6de4ee477949
Refer to the objects which define __len__(), __*item__(), and __iter__()
Fred Drake <fdrake@acm.org>
parents:
19962
diff
changeset
|
1232 \begin{methoddesc}[container object]{__delitem__}{self, key} |
|
9057
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1233 Called to implement deletion of \code{\var{self}[\var{key}]}. Same |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1234 note as for \method{__getitem__()}. This should only be implemented |
|
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1235 for mappings if the objects support removal of keys, or for sequences |
|
13583
ad1c8271b6f8
Improve the descriptions of expected exceptions for __getitem__(),
Fred Drake <fdrake@acm.org>
parents:
13071
diff
changeset
|
1236 if elements can be removed from the sequence. The same exceptions |
|
ad1c8271b6f8
Improve the descriptions of expected exceptions for __getitem__(),
Fred Drake <fdrake@acm.org>
parents:
13071
diff
changeset
|
1237 should be raised for improper \var{key} values as for the |
|
ad1c8271b6f8
Improve the descriptions of expected exceptions for __getitem__(),
Fred Drake <fdrake@acm.org>
parents:
13071
diff
changeset
|
1238 \method{__getitem__()} method. |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1239 \end{methoddesc} |
| 8231 | 1240 |
|
20196
6de4ee477949
Refer to the objects which define __len__(), __*item__(), and __iter__()
Fred Drake <fdrake@acm.org>
parents:
19962
diff
changeset
|
1241 \begin{methoddesc}[container object]{__iter__}{self} |
|
6de4ee477949
Refer to the objects which define __len__(), __*item__(), and __iter__()
Fred Drake <fdrake@acm.org>
parents:
19962
diff
changeset
|
1242 This method is called when an iterator is required for a container. |
|
6de4ee477949
Refer to the objects which define __len__(), __*item__(), and __iter__()
Fred Drake <fdrake@acm.org>
parents:
19962
diff
changeset
|
1243 This method should return a new iterator object that can iterate over |
|
6de4ee477949
Refer to the objects which define __len__(), __*item__(), and __iter__()
Fred Drake <fdrake@acm.org>
parents:
19962
diff
changeset
|
1244 all the objects in the container. For mappings, it should iterate |
|
6de4ee477949
Refer to the objects which define __len__(), __*item__(), and __iter__()
Fred Drake <fdrake@acm.org>
parents:
19962
diff
changeset
|
1245 over the keys of the container, and should also be made available as |
|
6de4ee477949
Refer to the objects which define __len__(), __*item__(), and __iter__()
Fred Drake <fdrake@acm.org>
parents:
19962
diff
changeset
|
1246 the method \method{iterkeys()}. |
|
6de4ee477949
Refer to the objects which define __len__(), __*item__(), and __iter__()
Fred Drake <fdrake@acm.org>
parents:
19962
diff
changeset
|
1247 |
|
6de4ee477949
Refer to the objects which define __len__(), __*item__(), and __iter__()
Fred Drake <fdrake@acm.org>
parents:
19962
diff
changeset
|
1248 Iterator objects also need to implement this method; they are required |
|
6de4ee477949
Refer to the objects which define __len__(), __*item__(), and __iter__()
Fred Drake <fdrake@acm.org>
parents:
19962
diff
changeset
|
1249 to return themselves. For more information on iterator objects, see |
|
6de4ee477949
Refer to the objects which define __len__(), __*item__(), and __iter__()
Fred Drake <fdrake@acm.org>
parents:
19962
diff
changeset
|
1250 ``\ulink{Iterator Types}{../lib/typeiter.html}'' in the |
|
6de4ee477949
Refer to the objects which define __len__(), __*item__(), and __iter__()
Fred Drake <fdrake@acm.org>
parents:
19962
diff
changeset
|
1251 \citetitle[../lib/lib.html]{Python Library Reference}. |
|
6de4ee477949
Refer to the objects which define __len__(), __*item__(), and __iter__()
Fred Drake <fdrake@acm.org>
parents:
19962
diff
changeset
|
1252 \end{methoddesc} |
|
6de4ee477949
Refer to the objects which define __len__(), __*item__(), and __iter__()
Fred Drake <fdrake@acm.org>
parents:
19962
diff
changeset
|
1253 |
|
6de4ee477949
Refer to the objects which define __len__(), __*item__(), and __iter__()
Fred Drake <fdrake@acm.org>
parents:
19962
diff
changeset
|
1254 The membership test operators (\keyword{in} and \keyword{not in}) are |
|
6de4ee477949
Refer to the objects which define __len__(), __*item__(), and __iter__()
Fred Drake <fdrake@acm.org>
parents:
19962
diff
changeset
|
1255 normally implemented as an iteration through a sequence. However, |
|
6de4ee477949
Refer to the objects which define __len__(), __*item__(), and __iter__()
Fred Drake <fdrake@acm.org>
parents:
19962
diff
changeset
|
1256 container objects can supply the following special method with a more |
|
6de4ee477949
Refer to the objects which define __len__(), __*item__(), and __iter__()
Fred Drake <fdrake@acm.org>
parents:
19962
diff
changeset
|
1257 efficient implementation, which also does not require the object be a |
|
6de4ee477949
Refer to the objects which define __len__(), __*item__(), and __iter__()
Fred Drake <fdrake@acm.org>
parents:
19962
diff
changeset
|
1258 sequence. |
|
6de4ee477949
Refer to the objects which define __len__(), __*item__(), and __iter__()
Fred Drake <fdrake@acm.org>
parents:
19962
diff
changeset
|
1259 |
|
6de4ee477949
Refer to the objects which define __len__(), __*item__(), and __iter__()
Fred Drake <fdrake@acm.org>
parents:
19962
diff
changeset
|
1260 \begin{methoddesc}[container object]{__contains__}{self, item} |
|
6de4ee477949
Refer to the objects which define __len__(), __*item__(), and __iter__()
Fred Drake <fdrake@acm.org>
parents:
19962
diff
changeset
|
1261 Called to implement membership test operators. Should return true if |
|
6de4ee477949
Refer to the objects which define __len__(), __*item__(), and __iter__()
Fred Drake <fdrake@acm.org>
parents:
19962
diff
changeset
|
1262 \var{item} is in \var{self}, false otherwise. For mapping objects, |
|
6de4ee477949
Refer to the objects which define __len__(), __*item__(), and __iter__()
Fred Drake <fdrake@acm.org>
parents:
19962
diff
changeset
|
1263 this should consider the keys of the mapping rather than the values or |
|
6de4ee477949
Refer to the objects which define __len__(), __*item__(), and __iter__()
Fred Drake <fdrake@acm.org>
parents:
19962
diff
changeset
|
1264 the key-item pairs. |
|
6de4ee477949
Refer to the objects which define __len__(), __*item__(), and __iter__()
Fred Drake <fdrake@acm.org>
parents:
19962
diff
changeset
|
1265 \end{methoddesc} |
|
6de4ee477949
Refer to the objects which define __len__(), __*item__(), and __iter__()
Fred Drake <fdrake@acm.org>
parents:
19962
diff
changeset
|
1266 |
| 8231 | 1267 |
|
9415
7ba7fbeb88ec
Remove an unnecessary "%" character that seems to cause a minor glitch
Fred Drake <fdrake@acm.org>
parents:
9201
diff
changeset
|
1268 \subsection{Additional methods for emulation of sequence types |
|
8777
00524555ef17
Make sure all chapters, sections, and subsections have a \label to give them
Fred Drake <fdrake@acm.org>
parents:
8736
diff
changeset
|
1269 \label{sequence-methods}} |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1270 |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1271 The following methods can be defined to further emulate sequence |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1272 objects. Immutable sequences methods should only define |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1273 \method{__getslice__()}; mutable sequences, should define all three |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1274 three methods. |
| 8231 | 1275 |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1276 \begin{methoddesc}[sequence object]{__getslice__}{self, i, j} |
|
14043
023468117514
Adjust the way __getslice__() is marked as deprecated; this will also
Fred Drake <fdrake@acm.org>
parents:
14037
diff
changeset
|
1277 \deprecated{2.0}{Support slice objects as parameters to the |
|
023468117514
Adjust the way __getslice__() is marked as deprecated; this will also
Fred Drake <fdrake@acm.org>
parents:
14037
diff
changeset
|
1278 \method{__getitem__()} method.} |
|
9057
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1279 Called to implement evaluation of \code{\var{self}[\var{i}:\var{j}]}. |
|
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1280 The returned object should be of the same type as \var{self}. Note |
|
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1281 that missing \var{i} or \var{j} in the slice expression are replaced |
|
12217
5ea773413531
Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
11462
diff
changeset
|
1282 by zero or \code{sys.maxint}, respectively. If negative indexes are |
|
5ea773413531
Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
11462
diff
changeset
|
1283 used in the slice, the length of the sequence is added to that index. |
|
5ea773413531
Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
11462
diff
changeset
|
1284 If the instance does not implement the \method{__len__()} method, an |
|
5ea773413531
Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
11462
diff
changeset
|
1285 \exception{AttributeError} is raised. |
|
5ea773413531
Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
11462
diff
changeset
|
1286 No guarantee is made that indexes adjusted this way are not still |
|
5ea773413531
Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
11462
diff
changeset
|
1287 negative. Indexes which are greater than the length of the sequence |
|
5ea773413531
Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
11462
diff
changeset
|
1288 are not modified. |
|
14043
023468117514
Adjust the way __getslice__() is marked as deprecated; this will also
Fred Drake <fdrake@acm.org>
parents:
14037
diff
changeset
|
1289 If no \method{__getslice__()} is found, a slice |
|
14037
91f847a783d2
Apply SF patch #101029: call __getitem__ with a proper slice object if there
Thomas Wouters <thomas@python.org>
parents:
13626
diff
changeset
|
1290 object is created instead, and passed to \method{__getitem__()} instead. |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1291 \end{methoddesc} |
| 8231 | 1292 |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1293 \begin{methoddesc}[sequence object]{__setslice__}{self, i, j, sequence} |
|
9057
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1294 Called to implement assignment to \code{\var{self}[\var{i}:\var{j}]}. |
|
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1295 Same notes for \var{i} and \var{j} as for \method{__getslice__()}. |
|
14037
91f847a783d2
Apply SF patch #101029: call __getitem__ with a proper slice object if there
Thomas Wouters <thomas@python.org>
parents:
13626
diff
changeset
|
1296 |
|
17492
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1297 This method is deprecated. If no \method{__setslice__()} is found, a |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1298 slice object is created instead, and passed to \method{__setitem__()} |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1299 instead. |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1300 \end{methoddesc} |
| 8231 | 1301 |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1302 \begin{methoddesc}[sequence object]{__delslice__}{self, i, j} |
|
9057
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1303 Called to implement deletion of \code{\var{self}[\var{i}:\var{j}]}. |
|
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1304 Same notes for \var{i} and \var{j} as for \method{__getslice__()}. |
|
17492
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1305 This method is deprecated. If no \method{__delslice__()} is found, a |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1306 slice object is created instead, and passed to \method{__delitem__()} |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1307 instead. |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1308 \end{methoddesc} |
| 8231 | 1309 |
|
17492
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1310 Notice that these methods are only invoked when a single slice with a |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1311 single colon is used, and the slice method is available. For slice |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1312 operations involving extended slice notation, or in absence of the |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1313 slice methods, \method{__getitem__()}, \method{__setitem__()} or |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1314 \method{__delitem__()} is called with a slice object as argument. |
| 8231 | 1315 |
|
14742
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1316 The following example demonstrate how to make your program or module |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1317 compatible with earlier versions of Python (assuming that methods |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1318 \method{__getitem__()}, \method{__setitem__()} and \method{__delitem__()} |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1319 support slice objects as arguments): |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1320 |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1321 \begin{verbatim} |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1322 class MyClass: |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1323 ... |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1324 def __getitem__(self, index): |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1325 ... |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1326 def __setitem__(self, index, value): |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1327 ... |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1328 def __delitem__(self, index): |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1329 ... |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1330 |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1331 if sys.version_info < (2, 0): |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1332 # They won't be defined if version is at least 2.0 final |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1333 |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1334 def __getslice__(self, i, j): |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1335 return self[max(0, i):max(0, j):] |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1336 def __setslice__(self, i, j, seq): |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1337 self[max(0, i):max(0, j):] = seq |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1338 def __delslice__(self, i, j): |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1339 del self[max(0, i):max(0, j):] |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1340 ... |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1341 \end{verbatim} |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1342 |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1343 Note the calls to \function{max()}; these are actually necessary due |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1344 to the handling of negative indices before the |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1345 \method{__*slice__()} methods are called. When negative indexes are |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1346 used, the \method{__*item__()} methods receive them as provided, but |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1347 the \method{__*slice__()} methods get a ``cooked'' form of the index |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1348 values. For each negative index value, the length of the sequence is |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1349 added to the index before calling the method (which may still result |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1350 in a negative index); this is the customary handling of negative |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1351 indexes by the built-in sequence types, and the \method{__*item__()} |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1352 methods are expected to do this as well. However, since they should |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1353 already be doing that, negative indexes cannot be passed in; they must |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1354 be be constrained to the bounds of the sequence before being passed to |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1355 the \method{__*item__()} methods. |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1356 Calling \code{max(0, i)} conveniently returns the proper value. |
|
d732a3a1398e
Denis S. Otkidach <ods@users.sourceforge.net>:
Fred Drake <fdrake@acm.org>
parents:
14712
diff
changeset
|
1357 |
|
10146
bd49f91d59b2
Documented __complex__(), made sure all the discipline names hit the
Fred Drake <fdrake@acm.org>
parents:
10002
diff
changeset
|
1358 |
|
8777
00524555ef17
Make sure all chapters, sections, and subsections have a \label to give them
Fred Drake <fdrake@acm.org>
parents:
8736
diff
changeset
|
1359 \subsection{Emulating numeric types\label{numeric-types}} |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1360 |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1361 The following methods can be defined to emulate numeric objects. |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1362 Methods corresponding to operations that are not supported by the |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1363 particular kind of number implemented (e.g., bitwise operations for |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1364 non-integral numbers) should be left undefined. |
| 8231 | 1365 |
| 10840 | 1366 \begin{methoddesc}[numeric object]{__add__}{self, other} |
| 1367 \methodline[numeric object]{__sub__}{self, other} | |
| 1368 \methodline[numeric object]{__mul__}{self, other} | |
|
19254
6617030c51e3
Add information about __floordiv__() and __truediv__() methods for
Fred Drake <fdrake@acm.org>
parents:
18947
diff
changeset
|
1369 \methodline[numeric object]{__floordiv__}{self, other} |
| 10840 | 1370 \methodline[numeric object]{__mod__}{self, other} |
| 1371 \methodline[numeric object]{__divmod__}{self, other} | |
| 1372 \methodline[numeric object]{__pow__}{self, other\optional{, modulo}} | |
| 1373 \methodline[numeric object]{__lshift__}{self, other} | |
| 1374 \methodline[numeric object]{__rshift__}{self, other} | |
| 1375 \methodline[numeric object]{__and__}{self, other} | |
| 1376 \methodline[numeric object]{__xor__}{self, other} | |
| 1377 \methodline[numeric object]{__or__}{self, other} | |
|
19254
6617030c51e3
Add information about __floordiv__() and __truediv__() methods for
Fred Drake <fdrake@acm.org>
parents:
18947
diff
changeset
|
1378 These methods are |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1379 called to implement the binary arithmetic operations (\code{+}, |
|
19254
6617030c51e3
Add information about __floordiv__() and __truediv__() methods for
Fred Drake <fdrake@acm.org>
parents:
18947
diff
changeset
|
1380 \code{-}, \code{*}, \code{//}, \code{\%}, |
|
9057
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1381 \function{divmod()}\bifuncindex{divmod}, |
|
17492
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1382 \function{pow()}\bifuncindex{pow}, \code{**}, \code{<}\code{<}, |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1383 \code{>}\code{>}, \code{\&}, \code{\^}, \code{|}). For instance, to |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1384 evaluate the expression \var{x}\code{+}\var{y}, where \var{x} is an |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1385 instance of a class that has an \method{__add__()} method, |
|
19254
6617030c51e3
Add information about __floordiv__() and __truediv__() methods for
Fred Drake <fdrake@acm.org>
parents:
18947
diff
changeset
|
1386 \code{\var{x}.__add__(\var{y})} is called. The \method{__divmod__()} |
|
6617030c51e3
Add information about __floordiv__() and __truediv__() methods for
Fred Drake <fdrake@acm.org>
parents:
18947
diff
changeset
|
1387 method should be the equivalent to using \method{__floordiv__()} and |
|
6617030c51e3
Add information about __floordiv__() and __truediv__() methods for
Fred Drake <fdrake@acm.org>
parents:
18947
diff
changeset
|
1388 \method{__mod__()}; it should not be related to \method{__truediv__()} |
|
6617030c51e3
Add information about __floordiv__() and __truediv__() methods for
Fred Drake <fdrake@acm.org>
parents:
18947
diff
changeset
|
1389 (described below). Note that |
|
9057
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1390 \method{__pow__()} should be defined to accept an optional third |
|
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1391 argument if the ternary version of the built-in |
|
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1392 \function{pow()}\bifuncindex{pow} function is to be supported. |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1393 \end{methoddesc} |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1394 |
|
19254
6617030c51e3
Add information about __floordiv__() and __truediv__() methods for
Fred Drake <fdrake@acm.org>
parents:
18947
diff
changeset
|
1395 \begin{methoddesc}[numeric object]{__div__}{self, other} |
|
6617030c51e3
Add information about __floordiv__() and __truediv__() methods for
Fred Drake <fdrake@acm.org>
parents:
18947
diff
changeset
|
1396 \methodline[numeric object]{__truediv__}{self, other} |
|
6617030c51e3
Add information about __floordiv__() and __truediv__() methods for
Fred Drake <fdrake@acm.org>
parents:
18947
diff
changeset
|
1397 The division operator (\code{/}) is implemented by these methods. The |
|
6617030c51e3
Add information about __floordiv__() and __truediv__() methods for
Fred Drake <fdrake@acm.org>
parents:
18947
diff
changeset
|
1398 \method{__truediv__()} method is used when \code{__future__.division} |
|
6617030c51e3
Add information about __floordiv__() and __truediv__() methods for
Fred Drake <fdrake@acm.org>
parents:
18947
diff
changeset
|
1399 is in effect, otherwise \method{__div__()} is used. If only one of |
|
6617030c51e3
Add information about __floordiv__() and __truediv__() methods for
Fred Drake <fdrake@acm.org>
parents:
18947
diff
changeset
|
1400 these two methods is defined, the object will not support division in |
|
6617030c51e3
Add information about __floordiv__() and __truediv__() methods for
Fred Drake <fdrake@acm.org>
parents:
18947
diff
changeset
|
1401 the alternate context; \exception{TypeError} will be raised instead. |
|
6617030c51e3
Add information about __floordiv__() and __truediv__() methods for
Fred Drake <fdrake@acm.org>
parents:
18947
diff
changeset
|
1402 \end{methoddesc} |
|
6617030c51e3
Add information about __floordiv__() and __truediv__() methods for
Fred Drake <fdrake@acm.org>
parents:
18947
diff
changeset
|
1403 |
| 10840 | 1404 \begin{methoddesc}[numeric object]{__radd__}{self, other} |
| 1405 \methodline[numeric object]{__rsub__}{self, other} | |
| 1406 \methodline[numeric object]{__rmul__}{self, other} | |
| 1407 \methodline[numeric object]{__rdiv__}{self, other} | |
| 1408 \methodline[numeric object]{__rmod__}{self, other} | |
| 1409 \methodline[numeric object]{__rdivmod__}{self, other} | |
| 1410 \methodline[numeric object]{__rpow__}{self, other} | |
| 1411 \methodline[numeric object]{__rlshift__}{self, other} | |
| 1412 \methodline[numeric object]{__rrshift__}{self, other} | |
| 1413 \methodline[numeric object]{__rand__}{self, other} | |
| 1414 \methodline[numeric object]{__rxor__}{self, other} | |
| 1415 \methodline[numeric object]{__ror__}{self, other} | |
|
19254
6617030c51e3
Add information about __floordiv__() and __truediv__() methods for
Fred Drake <fdrake@acm.org>
parents:
18947
diff
changeset
|
1416 These methods are |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1417 called to implement the binary arithmetic operations (\code{+}, |
|
9057
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1418 \code{-}, \code{*}, \code{/}, \code{\%}, |
|
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1419 \function{divmod()}\bifuncindex{divmod}, |
|
17492
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1420 \function{pow()}\bifuncindex{pow}, \code{**}, \code{<}\code{<}, |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1421 \code{>}\code{>}, \code{\&}, \code{\^}, \code{|}) with reflected |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1422 (swapped) operands. These functions are only called if the left |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1423 operand does not support the corresponding operation. For instance, |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1424 to evaluate the expression \var{x}\code{-}\var{y}, where \var{y} is an |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1425 instance of a class that has an \method{__rsub__()} method, |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1426 \code{\var{y}.__rsub__(\var{x})} is called. Note that ternary |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1427 \function{pow()}\bifuncindex{pow} will not try calling |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1428 \method{__rpow__()} (the coercion rules would become too |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1429 complicated). |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1430 \end{methoddesc} |
| 8231 | 1431 |
|
15510
db7570225ef8
Additional docs for __iadd__ and family, closing SF bug #117178 and SF patch
Thomas Wouters <thomas@python.org>
parents:
15494
diff
changeset
|
1432 \begin{methoddesc}[numeric object]{__iadd__}{self, other} |
|
db7570225ef8
Additional docs for __iadd__ and family, closing SF bug #117178 and SF patch
Thomas Wouters <thomas@python.org>
parents:
15494
diff
changeset
|
1433 \methodline[numeric object]{__isub__}{self, other} |
|
db7570225ef8
Additional docs for __iadd__ and family, closing SF bug #117178 and SF patch
Thomas Wouters <thomas@python.org>
parents:
15494
diff
changeset
|
1434 \methodline[numeric object]{__imul__}{self, other} |
|
db7570225ef8
Additional docs for __iadd__ and family, closing SF bug #117178 and SF patch
Thomas Wouters <thomas@python.org>
parents:
15494
diff
changeset
|
1435 \methodline[numeric object]{__idiv__}{self, other} |
|
db7570225ef8
Additional docs for __iadd__ and family, closing SF bug #117178 and SF patch
Thomas Wouters <thomas@python.org>
parents:
15494
diff
changeset
|
1436 \methodline[numeric object]{__imod__}{self, other} |
|
db7570225ef8
Additional docs for __iadd__ and family, closing SF bug #117178 and SF patch
Thomas Wouters <thomas@python.org>
parents:
15494
diff
changeset
|
1437 \methodline[numeric object]{__ipow__}{self, other\optional{, modulo}} |
|
db7570225ef8
Additional docs for __iadd__ and family, closing SF bug #117178 and SF patch
Thomas Wouters <thomas@python.org>
parents:
15494
diff
changeset
|
1438 \methodline[numeric object]{__ilshift__}{self, other} |
|
db7570225ef8
Additional docs for __iadd__ and family, closing SF bug #117178 and SF patch
Thomas Wouters <thomas@python.org>
parents:
15494
diff
changeset
|
1439 \methodline[numeric object]{__irshift__}{self, other} |
|
db7570225ef8
Additional docs for __iadd__ and family, closing SF bug #117178 and SF patch
Thomas Wouters <thomas@python.org>
parents:
15494
diff
changeset
|
1440 \methodline[numeric object]{__iand__}{self, other} |
|
db7570225ef8
Additional docs for __iadd__ and family, closing SF bug #117178 and SF patch
Thomas Wouters <thomas@python.org>
parents:
15494
diff
changeset
|
1441 \methodline[numeric object]{__ixor__}{self, other} |
|
db7570225ef8
Additional docs for __iadd__ and family, closing SF bug #117178 and SF patch
Thomas Wouters <thomas@python.org>
parents:
15494
diff
changeset
|
1442 \methodline[numeric object]{__ior__}{self, other} |
|
17492
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1443 These methods are called to implement the augmented arithmetic |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1444 operations (\code{+=}, \code{-=}, \code{*=}, \code{/=}, \code{\%=}, |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1445 \code{**=}, \code{<}\code{<=}, \code{>}\code{>=}, \code{\&=}, |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1446 \code{\^=}, \code{|=}). These methods should attempt to do the |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1447 operation in-place (modifying \var{self}) and return the result (which |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1448 could be, but does not have to be, \var{self}). If a specific method |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1449 is not defined, the augmented operation falls back to the normal |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1450 methods. For instance, to evaluate the expression |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1451 \var{x}\code{+=}\var{y}, where \var{x} is an instance of a class that |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1452 has an \method{__iadd__()} method, \code{\var{x}.__iadd__(\var{y})} is |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1453 called. If \var{x} is an instance of a class that does not define a |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1454 \method{__iadd()} method, \code{\var{x}.__add__(\var{y})} and |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1455 \code{\var{y}.__radd__(\var{x})} are considered, as with the |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1456 evaluation of \var{x}\code{+}\var{y}. |
|
15510
db7570225ef8
Additional docs for __iadd__ and family, closing SF bug #117178 and SF patch
Thomas Wouters <thomas@python.org>
parents:
15494
diff
changeset
|
1457 \end{methoddesc} |
|
db7570225ef8
Additional docs for __iadd__ and family, closing SF bug #117178 and SF patch
Thomas Wouters <thomas@python.org>
parents:
15494
diff
changeset
|
1458 |
| 10840 | 1459 \begin{methoddesc}[numeric object]{__neg__}{self} |
| 1460 \methodline[numeric object]{__pos__}{self} | |
| 1461 \methodline[numeric object]{__abs__}{self} | |
| 1462 \methodline[numeric object]{__invert__}{self} | |
|
17492
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1463 Called to implement the unary arithmetic operations (\code{-}, |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1464 \code{+}, \function{abs()}\bifuncindex{abs} and \code{\~{}}). |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1465 \end{methoddesc} |
| 8231 | 1466 |
| 10840 | 1467 \begin{methoddesc}[numeric object]{__complex__}{self} |
| 1468 \methodline[numeric object]{__int__}{self} | |
| 1469 \methodline[numeric object]{__long__}{self} | |
| 1470 \methodline[numeric object]{__float__}{self} | |
|
9057
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1471 Called to implement the built-in functions |
|
10146
bd49f91d59b2
Documented __complex__(), made sure all the discipline names hit the
Fred Drake <fdrake@acm.org>
parents:
10002
diff
changeset
|
1472 \function{complex()}\bifuncindex{complex}, |
|
bd49f91d59b2
Documented __complex__(), made sure all the discipline names hit the
Fred Drake <fdrake@acm.org>
parents:
10002
diff
changeset
|
1473 \function{int()}\bifuncindex{int}, \function{long()}\bifuncindex{long}, |
|
9057
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1474 and \function{float()}\bifuncindex{float}. Should return a value of |
|
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1475 the appropriate type. |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1476 \end{methoddesc} |
| 8231 | 1477 |
| 10840 | 1478 \begin{methoddesc}[numeric object]{__oct__}{self} |
| 1479 \methodline[numeric object]{__hex__}{self} | |
|
9057
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1480 Called to implement the built-in functions |
|
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1481 \function{oct()}\bifuncindex{oct} and |
|
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1482 \function{hex()}\bifuncindex{hex}. Should return a string value. |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1483 \end{methoddesc} |
| 8231 | 1484 |
| 10840 | 1485 \begin{methoddesc}[numeric object]{__coerce__}{self, other} |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1486 Called to implement ``mixed-mode'' numeric arithmetic. Should either |
|
9057
026e1236243e
Markup changes in the section on disciplines to match method descriptions
Fred Drake <fdrake@acm.org>
parents:
8871
diff
changeset
|
1487 return a 2-tuple containing \var{self} and \var{other} converted to |
| 10840 | 1488 a common numeric type, or \code{None} if conversion is impossible. When |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1489 the common type would be the type of \code{other}, it is sufficient to |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1490 return \code{None}, since the interpreter will also ask the other |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1491 object to attempt a coercion (but sometimes, if the implementation of |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1492 the other type cannot be changed, it is useful to do the conversion to |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1493 the other type here). |
|
9528
e059049b1a76
Massive change to just about every construct that impacts the index.
Fred Drake <fdrake@acm.org>
parents:
9415
diff
changeset
|
1494 \end{methoddesc} |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1495 |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1496 \strong{Coercion rules}: to evaluate \var{x} \var{op} \var{y}, the |
|
17492
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1497 following steps are taken (where \method{__\var{op}__()} and |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1498 \method{__r\var{op}__()} are the method names corresponding to |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1499 \var{op}, e.g., if \var{op} is `\code{+}', \method{__add__()} and |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1500 \method{__radd__()} are used). If an exception occurs at any point, |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1501 the evaluation is abandoned and exception handling takes over. |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1502 |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1503 \begin{itemize} |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1504 |
|
17492
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1505 \item[0.] If \var{x} is a string object and \var{op} is the modulo |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1506 operator (\%), the string formatting operation is invoked and |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1507 the remaining steps are skipped. |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1508 |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1509 \item[1.] If \var{x} is a class instance: |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1510 |
|
16740
c10056100ea5
Sequence indexes are non-negative, not natural (0 is not a natural number).
Fred Drake <fdrake@acm.org>
parents:
16116
diff
changeset
|
1511 \begin{itemize} |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1512 |
|
16740
c10056100ea5
Sequence indexes are non-negative, not natural (0 is not a natural number).
Fred Drake <fdrake@acm.org>
parents:
16116
diff
changeset
|
1513 \item[1a.] If \var{x} has a \method{__coerce__()} method: |
|
c10056100ea5
Sequence indexes are non-negative, not natural (0 is not a natural number).
Fred Drake <fdrake@acm.org>
parents:
16116
diff
changeset
|
1514 replace \var{x} and \var{y} with the 2-tuple returned by |
|
c10056100ea5
Sequence indexes are non-negative, not natural (0 is not a natural number).
Fred Drake <fdrake@acm.org>
parents:
16116
diff
changeset
|
1515 \code{\var{x}.__coerce__(\var{y})}; skip to step 2 if the |
|
c10056100ea5
Sequence indexes are non-negative, not natural (0 is not a natural number).
Fred Drake <fdrake@acm.org>
parents:
16116
diff
changeset
|
1516 coercion returns \code{None}. |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1517 |
|
16740
c10056100ea5
Sequence indexes are non-negative, not natural (0 is not a natural number).
Fred Drake <fdrake@acm.org>
parents:
16116
diff
changeset
|
1518 \item[1b.] If neither \var{x} nor \var{y} is a class instance |
|
c10056100ea5
Sequence indexes are non-negative, not natural (0 is not a natural number).
Fred Drake <fdrake@acm.org>
parents:
16116
diff
changeset
|
1519 after coercion, go to step 3. |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1520 |
|
17492
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1521 \item[1c.] If \var{x} has a method \method{__\var{op}__()}, return |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1522 \code{\var{x}.__\var{op}__(\var{y})}; otherwise, restore \var{x} and |
|
16740
c10056100ea5
Sequence indexes are non-negative, not natural (0 is not a natural number).
Fred Drake <fdrake@acm.org>
parents:
16116
diff
changeset
|
1523 \var{y} to their value before step 1a. |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1524 |
|
16740
c10056100ea5
Sequence indexes are non-negative, not natural (0 is not a natural number).
Fred Drake <fdrake@acm.org>
parents:
16116
diff
changeset
|
1525 \end{itemize} |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1526 |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1527 \item[2.] If \var{y} is a class instance: |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1528 |
|
16740
c10056100ea5
Sequence indexes are non-negative, not natural (0 is not a natural number).
Fred Drake <fdrake@acm.org>
parents:
16116
diff
changeset
|
1529 \begin{itemize} |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1530 |
|
16740
c10056100ea5
Sequence indexes are non-negative, not natural (0 is not a natural number).
Fred Drake <fdrake@acm.org>
parents:
16116
diff
changeset
|
1531 \item[2a.] If \var{y} has a \method{__coerce__()} method: |
|
c10056100ea5
Sequence indexes are non-negative, not natural (0 is not a natural number).
Fred Drake <fdrake@acm.org>
parents:
16116
diff
changeset
|
1532 replace \var{y} and \var{x} with the 2-tuple returned by |
|
c10056100ea5
Sequence indexes are non-negative, not natural (0 is not a natural number).
Fred Drake <fdrake@acm.org>
parents:
16116
diff
changeset
|
1533 \code{\var{y}.__coerce__(\var{x})}; skip to step 3 if the |
|
c10056100ea5
Sequence indexes are non-negative, not natural (0 is not a natural number).
Fred Drake <fdrake@acm.org>
parents:
16116
diff
changeset
|
1534 coercion returns \code{None}. |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1535 |
|
16740
c10056100ea5
Sequence indexes are non-negative, not natural (0 is not a natural number).
Fred Drake <fdrake@acm.org>
parents:
16116
diff
changeset
|
1536 \item[2b.] If neither \var{x} nor \var{y} is a class instance |
|
c10056100ea5
Sequence indexes are non-negative, not natural (0 is not a natural number).
Fred Drake <fdrake@acm.org>
parents:
16116
diff
changeset
|
1537 after coercion, go to step 3. |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1538 |
|
17492
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1539 \item[2b.] If \var{y} has a method \method{__r\var{op}__()}, |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1540 return \code{\var{y}.__r\var{op}__(\var{x})}; otherwise, |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1541 restore \var{x} and \var{y} to their value before step 2a. |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1542 |
|
16740
c10056100ea5
Sequence indexes are non-negative, not natural (0 is not a natural number).
Fred Drake <fdrake@acm.org>
parents:
16116
diff
changeset
|
1543 \end{itemize} |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1544 |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1545 \item[3.] We only get here if neither \var{x} nor \var{y} is a class |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1546 instance. |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1547 |
|
16740
c10056100ea5
Sequence indexes are non-negative, not natural (0 is not a natural number).
Fred Drake <fdrake@acm.org>
parents:
16116
diff
changeset
|
1548 \begin{itemize} |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1549 |
|
17492
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1550 \item[3a.] If \var{op} is `\code{+}' and \var{x} is a |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1551 sequence, sequence concatenation is invoked. |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1552 |
|
17492
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1553 \item[3b.] If \var{op} is `\code{*}' and one operand is a |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1554 sequence and the other an integer, sequence repetition is |
|
b65d089e8841
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17205
diff
changeset
|
1555 invoked. |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1556 |
|
16740
c10056100ea5
Sequence indexes are non-negative, not natural (0 is not a natural number).
Fred Drake <fdrake@acm.org>
parents:
16116
diff
changeset
|
1557 \item[3c.] Otherwise, both operands must be numbers; they are |
|
c10056100ea5
Sequence indexes are non-negative, not natural (0 is not a natural number).
Fred Drake <fdrake@acm.org>
parents:
16116
diff
changeset
|
1558 coerced to a common type if possible, and the numeric |
|
c10056100ea5
Sequence indexes are non-negative, not natural (0 is not a natural number).
Fred Drake <fdrake@acm.org>
parents:
16116
diff
changeset
|
1559 operation is invoked for that type. |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1560 |
|
16740
c10056100ea5
Sequence indexes are non-negative, not natural (0 is not a natural number).
Fred Drake <fdrake@acm.org>
parents:
16116
diff
changeset
|
1561 \end{itemize} |
|
8709
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1562 |
|
0e2563c0eb0d
Lots of changes copied from the FrameMaker version. Also documented
Guido van Rossum <guido@python.org>
parents:
8337
diff
changeset
|
1563 \end{itemize} |