|
jpayne@68
|
1 # -*- coding: utf-8 -*-
|
|
jpayne@68
|
2 # Autogenerated by Sphinx on Wed Dec 18 18:17:58 2019
|
|
jpayne@68
|
3 topics = {'assert': 'The "assert" statement\n'
|
|
jpayne@68
|
4 '**********************\n'
|
|
jpayne@68
|
5 '\n'
|
|
jpayne@68
|
6 'Assert statements are a convenient way to insert debugging '
|
|
jpayne@68
|
7 'assertions\n'
|
|
jpayne@68
|
8 'into a program:\n'
|
|
jpayne@68
|
9 '\n'
|
|
jpayne@68
|
10 ' assert_stmt ::= "assert" expression ["," expression]\n'
|
|
jpayne@68
|
11 '\n'
|
|
jpayne@68
|
12 'The simple form, "assert expression", is equivalent to\n'
|
|
jpayne@68
|
13 '\n'
|
|
jpayne@68
|
14 ' if __debug__:\n'
|
|
jpayne@68
|
15 ' if not expression: raise AssertionError\n'
|
|
jpayne@68
|
16 '\n'
|
|
jpayne@68
|
17 'The extended form, "assert expression1, expression2", is '
|
|
jpayne@68
|
18 'equivalent to\n'
|
|
jpayne@68
|
19 '\n'
|
|
jpayne@68
|
20 ' if __debug__:\n'
|
|
jpayne@68
|
21 ' if not expression1: raise AssertionError(expression2)\n'
|
|
jpayne@68
|
22 '\n'
|
|
jpayne@68
|
23 'These equivalences assume that "__debug__" and "AssertionError" '
|
|
jpayne@68
|
24 'refer\n'
|
|
jpayne@68
|
25 'to the built-in variables with those names. In the current\n'
|
|
jpayne@68
|
26 'implementation, the built-in variable "__debug__" is "True" under\n'
|
|
jpayne@68
|
27 'normal circumstances, "False" when optimization is requested '
|
|
jpayne@68
|
28 '(command\n'
|
|
jpayne@68
|
29 'line option "-O"). The current code generator emits no code for '
|
|
jpayne@68
|
30 'an\n'
|
|
jpayne@68
|
31 'assert statement when optimization is requested at compile time. '
|
|
jpayne@68
|
32 'Note\n'
|
|
jpayne@68
|
33 'that it is unnecessary to include the source code for the '
|
|
jpayne@68
|
34 'expression\n'
|
|
jpayne@68
|
35 'that failed in the error message; it will be displayed as part of '
|
|
jpayne@68
|
36 'the\n'
|
|
jpayne@68
|
37 'stack trace.\n'
|
|
jpayne@68
|
38 '\n'
|
|
jpayne@68
|
39 'Assignments to "__debug__" are illegal. The value for the '
|
|
jpayne@68
|
40 'built-in\n'
|
|
jpayne@68
|
41 'variable is determined when the interpreter starts.\n',
|
|
jpayne@68
|
42 'assignment': 'Assignment statements\n'
|
|
jpayne@68
|
43 '*********************\n'
|
|
jpayne@68
|
44 '\n'
|
|
jpayne@68
|
45 'Assignment statements are used to (re)bind names to values and '
|
|
jpayne@68
|
46 'to\n'
|
|
jpayne@68
|
47 'modify attributes or items of mutable objects:\n'
|
|
jpayne@68
|
48 '\n'
|
|
jpayne@68
|
49 ' assignment_stmt ::= (target_list "=")+ (starred_expression '
|
|
jpayne@68
|
50 '| yield_expression)\n'
|
|
jpayne@68
|
51 ' target_list ::= target ("," target)* [","]\n'
|
|
jpayne@68
|
52 ' target ::= identifier\n'
|
|
jpayne@68
|
53 ' | "(" [target_list] ")"\n'
|
|
jpayne@68
|
54 ' | "[" [target_list] "]"\n'
|
|
jpayne@68
|
55 ' | attributeref\n'
|
|
jpayne@68
|
56 ' | subscription\n'
|
|
jpayne@68
|
57 ' | slicing\n'
|
|
jpayne@68
|
58 ' | "*" target\n'
|
|
jpayne@68
|
59 '\n'
|
|
jpayne@68
|
60 '(See section Primaries for the syntax definitions for '
|
|
jpayne@68
|
61 '*attributeref*,\n'
|
|
jpayne@68
|
62 '*subscription*, and *slicing*.)\n'
|
|
jpayne@68
|
63 '\n'
|
|
jpayne@68
|
64 'An assignment statement evaluates the expression list '
|
|
jpayne@68
|
65 '(remember that\n'
|
|
jpayne@68
|
66 'this can be a single expression or a comma-separated list, the '
|
|
jpayne@68
|
67 'latter\n'
|
|
jpayne@68
|
68 'yielding a tuple) and assigns the single resulting object to '
|
|
jpayne@68
|
69 'each of\n'
|
|
jpayne@68
|
70 'the target lists, from left to right.\n'
|
|
jpayne@68
|
71 '\n'
|
|
jpayne@68
|
72 'Assignment is defined recursively depending on the form of the '
|
|
jpayne@68
|
73 'target\n'
|
|
jpayne@68
|
74 '(list). When a target is part of a mutable object (an '
|
|
jpayne@68
|
75 'attribute\n'
|
|
jpayne@68
|
76 'reference, subscription or slicing), the mutable object must\n'
|
|
jpayne@68
|
77 'ultimately perform the assignment and decide about its '
|
|
jpayne@68
|
78 'validity, and\n'
|
|
jpayne@68
|
79 'may raise an exception if the assignment is unacceptable. The '
|
|
jpayne@68
|
80 'rules\n'
|
|
jpayne@68
|
81 'observed by various types and the exceptions raised are given '
|
|
jpayne@68
|
82 'with the\n'
|
|
jpayne@68
|
83 'definition of the object types (see section The standard type\n'
|
|
jpayne@68
|
84 'hierarchy).\n'
|
|
jpayne@68
|
85 '\n'
|
|
jpayne@68
|
86 'Assignment of an object to a target list, optionally enclosed '
|
|
jpayne@68
|
87 'in\n'
|
|
jpayne@68
|
88 'parentheses or square brackets, is recursively defined as '
|
|
jpayne@68
|
89 'follows.\n'
|
|
jpayne@68
|
90 '\n'
|
|
jpayne@68
|
91 '* If the target list is a single target with no trailing '
|
|
jpayne@68
|
92 'comma,\n'
|
|
jpayne@68
|
93 ' optionally in parentheses, the object is assigned to that '
|
|
jpayne@68
|
94 'target.\n'
|
|
jpayne@68
|
95 '\n'
|
|
jpayne@68
|
96 '* Else: The object must be an iterable with the same number of '
|
|
jpayne@68
|
97 'items\n'
|
|
jpayne@68
|
98 ' as there are targets in the target list, and the items are '
|
|
jpayne@68
|
99 'assigned,\n'
|
|
jpayne@68
|
100 ' from left to right, to the corresponding targets.\n'
|
|
jpayne@68
|
101 '\n'
|
|
jpayne@68
|
102 ' * If the target list contains one target prefixed with an\n'
|
|
jpayne@68
|
103 ' asterisk, called a “starred” target: The object must be '
|
|
jpayne@68
|
104 'an\n'
|
|
jpayne@68
|
105 ' iterable with at least as many items as there are targets '
|
|
jpayne@68
|
106 'in the\n'
|
|
jpayne@68
|
107 ' target list, minus one. The first items of the iterable '
|
|
jpayne@68
|
108 'are\n'
|
|
jpayne@68
|
109 ' assigned, from left to right, to the targets before the '
|
|
jpayne@68
|
110 'starred\n'
|
|
jpayne@68
|
111 ' target. The final items of the iterable are assigned to '
|
|
jpayne@68
|
112 'the\n'
|
|
jpayne@68
|
113 ' targets after the starred target. A list of the remaining '
|
|
jpayne@68
|
114 'items\n'
|
|
jpayne@68
|
115 ' in the iterable is then assigned to the starred target '
|
|
jpayne@68
|
116 '(the list\n'
|
|
jpayne@68
|
117 ' can be empty).\n'
|
|
jpayne@68
|
118 '\n'
|
|
jpayne@68
|
119 ' * Else: The object must be an iterable with the same number '
|
|
jpayne@68
|
120 'of\n'
|
|
jpayne@68
|
121 ' items as there are targets in the target list, and the '
|
|
jpayne@68
|
122 'items are\n'
|
|
jpayne@68
|
123 ' assigned, from left to right, to the corresponding '
|
|
jpayne@68
|
124 'targets.\n'
|
|
jpayne@68
|
125 '\n'
|
|
jpayne@68
|
126 'Assignment of an object to a single target is recursively '
|
|
jpayne@68
|
127 'defined as\n'
|
|
jpayne@68
|
128 'follows.\n'
|
|
jpayne@68
|
129 '\n'
|
|
jpayne@68
|
130 '* If the target is an identifier (name):\n'
|
|
jpayne@68
|
131 '\n'
|
|
jpayne@68
|
132 ' * If the name does not occur in a "global" or "nonlocal" '
|
|
jpayne@68
|
133 'statement\n'
|
|
jpayne@68
|
134 ' in the current code block: the name is bound to the object '
|
|
jpayne@68
|
135 'in the\n'
|
|
jpayne@68
|
136 ' current local namespace.\n'
|
|
jpayne@68
|
137 '\n'
|
|
jpayne@68
|
138 ' * Otherwise: the name is bound to the object in the global\n'
|
|
jpayne@68
|
139 ' namespace or the outer namespace determined by '
|
|
jpayne@68
|
140 '"nonlocal",\n'
|
|
jpayne@68
|
141 ' respectively.\n'
|
|
jpayne@68
|
142 '\n'
|
|
jpayne@68
|
143 ' The name is rebound if it was already bound. This may cause '
|
|
jpayne@68
|
144 'the\n'
|
|
jpayne@68
|
145 ' reference count for the object previously bound to the name '
|
|
jpayne@68
|
146 'to reach\n'
|
|
jpayne@68
|
147 ' zero, causing the object to be deallocated and its '
|
|
jpayne@68
|
148 'destructor (if it\n'
|
|
jpayne@68
|
149 ' has one) to be called.\n'
|
|
jpayne@68
|
150 '\n'
|
|
jpayne@68
|
151 '* If the target is an attribute reference: The primary '
|
|
jpayne@68
|
152 'expression in\n'
|
|
jpayne@68
|
153 ' the reference is evaluated. It should yield an object with\n'
|
|
jpayne@68
|
154 ' assignable attributes; if this is not the case, "TypeError" '
|
|
jpayne@68
|
155 'is\n'
|
|
jpayne@68
|
156 ' raised. That object is then asked to assign the assigned '
|
|
jpayne@68
|
157 'object to\n'
|
|
jpayne@68
|
158 ' the given attribute; if it cannot perform the assignment, it '
|
|
jpayne@68
|
159 'raises\n'
|
|
jpayne@68
|
160 ' an exception (usually but not necessarily '
|
|
jpayne@68
|
161 '"AttributeError").\n'
|
|
jpayne@68
|
162 '\n'
|
|
jpayne@68
|
163 ' Note: If the object is a class instance and the attribute '
|
|
jpayne@68
|
164 'reference\n'
|
|
jpayne@68
|
165 ' occurs on both sides of the assignment operator, the '
|
|
jpayne@68
|
166 'right-hand side\n'
|
|
jpayne@68
|
167 ' expression, "a.x" can access either an instance attribute or '
|
|
jpayne@68
|
168 '(if no\n'
|
|
jpayne@68
|
169 ' instance attribute exists) a class attribute. The left-hand '
|
|
jpayne@68
|
170 'side\n'
|
|
jpayne@68
|
171 ' target "a.x" is always set as an instance attribute, '
|
|
jpayne@68
|
172 'creating it if\n'
|
|
jpayne@68
|
173 ' necessary. Thus, the two occurrences of "a.x" do not '
|
|
jpayne@68
|
174 'necessarily\n'
|
|
jpayne@68
|
175 ' refer to the same attribute: if the right-hand side '
|
|
jpayne@68
|
176 'expression\n'
|
|
jpayne@68
|
177 ' refers to a class attribute, the left-hand side creates a '
|
|
jpayne@68
|
178 'new\n'
|
|
jpayne@68
|
179 ' instance attribute as the target of the assignment:\n'
|
|
jpayne@68
|
180 '\n'
|
|
jpayne@68
|
181 ' class Cls:\n'
|
|
jpayne@68
|
182 ' x = 3 # class variable\n'
|
|
jpayne@68
|
183 ' inst = Cls()\n'
|
|
jpayne@68
|
184 ' inst.x = inst.x + 1 # writes inst.x as 4 leaving Cls.x '
|
|
jpayne@68
|
185 'as 3\n'
|
|
jpayne@68
|
186 '\n'
|
|
jpayne@68
|
187 ' This description does not necessarily apply to descriptor\n'
|
|
jpayne@68
|
188 ' attributes, such as properties created with "property()".\n'
|
|
jpayne@68
|
189 '\n'
|
|
jpayne@68
|
190 '* If the target is a subscription: The primary expression in '
|
|
jpayne@68
|
191 'the\n'
|
|
jpayne@68
|
192 ' reference is evaluated. It should yield either a mutable '
|
|
jpayne@68
|
193 'sequence\n'
|
|
jpayne@68
|
194 ' object (such as a list) or a mapping object (such as a '
|
|
jpayne@68
|
195 'dictionary).\n'
|
|
jpayne@68
|
196 ' Next, the subscript expression is evaluated.\n'
|
|
jpayne@68
|
197 '\n'
|
|
jpayne@68
|
198 ' If the primary is a mutable sequence object (such as a '
|
|
jpayne@68
|
199 'list), the\n'
|
|
jpayne@68
|
200 ' subscript must yield an integer. If it is negative, the '
|
|
jpayne@68
|
201 'sequence’s\n'
|
|
jpayne@68
|
202 ' length is added to it. The resulting value must be a '
|
|
jpayne@68
|
203 'nonnegative\n'
|
|
jpayne@68
|
204 ' integer less than the sequence’s length, and the sequence is '
|
|
jpayne@68
|
205 'asked\n'
|
|
jpayne@68
|
206 ' to assign the assigned object to its item with that index. '
|
|
jpayne@68
|
207 'If the\n'
|
|
jpayne@68
|
208 ' index is out of range, "IndexError" is raised (assignment to '
|
|
jpayne@68
|
209 'a\n'
|
|
jpayne@68
|
210 ' subscripted sequence cannot add new items to a list).\n'
|
|
jpayne@68
|
211 '\n'
|
|
jpayne@68
|
212 ' If the primary is a mapping object (such as a dictionary), '
|
|
jpayne@68
|
213 'the\n'
|
|
jpayne@68
|
214 ' subscript must have a type compatible with the mapping’s key '
|
|
jpayne@68
|
215 'type,\n'
|
|
jpayne@68
|
216 ' and the mapping is then asked to create a key/datum pair '
|
|
jpayne@68
|
217 'which maps\n'
|
|
jpayne@68
|
218 ' the subscript to the assigned object. This can either '
|
|
jpayne@68
|
219 'replace an\n'
|
|
jpayne@68
|
220 ' existing key/value pair with the same key value, or insert a '
|
|
jpayne@68
|
221 'new\n'
|
|
jpayne@68
|
222 ' key/value pair (if no key with the same value existed).\n'
|
|
jpayne@68
|
223 '\n'
|
|
jpayne@68
|
224 ' For user-defined objects, the "__setitem__()" method is '
|
|
jpayne@68
|
225 'called with\n'
|
|
jpayne@68
|
226 ' appropriate arguments.\n'
|
|
jpayne@68
|
227 '\n'
|
|
jpayne@68
|
228 '* If the target is a slicing: The primary expression in the\n'
|
|
jpayne@68
|
229 ' reference is evaluated. It should yield a mutable sequence '
|
|
jpayne@68
|
230 'object\n'
|
|
jpayne@68
|
231 ' (such as a list). The assigned object should be a sequence '
|
|
jpayne@68
|
232 'object\n'
|
|
jpayne@68
|
233 ' of the same type. Next, the lower and upper bound '
|
|
jpayne@68
|
234 'expressions are\n'
|
|
jpayne@68
|
235 ' evaluated, insofar they are present; defaults are zero and '
|
|
jpayne@68
|
236 'the\n'
|
|
jpayne@68
|
237 ' sequence’s length. The bounds should evaluate to integers. '
|
|
jpayne@68
|
238 'If\n'
|
|
jpayne@68
|
239 ' either bound is negative, the sequence’s length is added to '
|
|
jpayne@68
|
240 'it. The\n'
|
|
jpayne@68
|
241 ' resulting bounds are clipped to lie between zero and the '
|
|
jpayne@68
|
242 'sequence’s\n'
|
|
jpayne@68
|
243 ' length, inclusive. Finally, the sequence object is asked to '
|
|
jpayne@68
|
244 'replace\n'
|
|
jpayne@68
|
245 ' the slice with the items of the assigned sequence. The '
|
|
jpayne@68
|
246 'length of\n'
|
|
jpayne@68
|
247 ' the slice may be different from the length of the assigned '
|
|
jpayne@68
|
248 'sequence,\n'
|
|
jpayne@68
|
249 ' thus changing the length of the target sequence, if the '
|
|
jpayne@68
|
250 'target\n'
|
|
jpayne@68
|
251 ' sequence allows it.\n'
|
|
jpayne@68
|
252 '\n'
|
|
jpayne@68
|
253 '**CPython implementation detail:** In the current '
|
|
jpayne@68
|
254 'implementation, the\n'
|
|
jpayne@68
|
255 'syntax for targets is taken to be the same as for expressions, '
|
|
jpayne@68
|
256 'and\n'
|
|
jpayne@68
|
257 'invalid syntax is rejected during the code generation phase, '
|
|
jpayne@68
|
258 'causing\n'
|
|
jpayne@68
|
259 'less detailed error messages.\n'
|
|
jpayne@68
|
260 '\n'
|
|
jpayne@68
|
261 'Although the definition of assignment implies that overlaps '
|
|
jpayne@68
|
262 'between\n'
|
|
jpayne@68
|
263 'the left-hand side and the right-hand side are ‘simultaneous’ '
|
|
jpayne@68
|
264 '(for\n'
|
|
jpayne@68
|
265 'example "a, b = b, a" swaps two variables), overlaps *within* '
|
|
jpayne@68
|
266 'the\n'
|
|
jpayne@68
|
267 'collection of assigned-to variables occur left-to-right, '
|
|
jpayne@68
|
268 'sometimes\n'
|
|
jpayne@68
|
269 'resulting in confusion. For instance, the following program '
|
|
jpayne@68
|
270 'prints\n'
|
|
jpayne@68
|
271 '"[0, 2]":\n'
|
|
jpayne@68
|
272 '\n'
|
|
jpayne@68
|
273 ' x = [0, 1]\n'
|
|
jpayne@68
|
274 ' i = 0\n'
|
|
jpayne@68
|
275 ' i, x[i] = 1, 2 # i is updated, then x[i] is '
|
|
jpayne@68
|
276 'updated\n'
|
|
jpayne@68
|
277 ' print(x)\n'
|
|
jpayne@68
|
278 '\n'
|
|
jpayne@68
|
279 'See also:\n'
|
|
jpayne@68
|
280 '\n'
|
|
jpayne@68
|
281 ' **PEP 3132** - Extended Iterable Unpacking\n'
|
|
jpayne@68
|
282 ' The specification for the "*target" feature.\n'
|
|
jpayne@68
|
283 '\n'
|
|
jpayne@68
|
284 '\n'
|
|
jpayne@68
|
285 'Augmented assignment statements\n'
|
|
jpayne@68
|
286 '===============================\n'
|
|
jpayne@68
|
287 '\n'
|
|
jpayne@68
|
288 'Augmented assignment is the combination, in a single '
|
|
jpayne@68
|
289 'statement, of a\n'
|
|
jpayne@68
|
290 'binary operation and an assignment statement:\n'
|
|
jpayne@68
|
291 '\n'
|
|
jpayne@68
|
292 ' augmented_assignment_stmt ::= augtarget augop '
|
|
jpayne@68
|
293 '(expression_list | yield_expression)\n'
|
|
jpayne@68
|
294 ' augtarget ::= identifier | attributeref | '
|
|
jpayne@68
|
295 'subscription | slicing\n'
|
|
jpayne@68
|
296 ' augop ::= "+=" | "-=" | "*=" | "@=" | '
|
|
jpayne@68
|
297 '"/=" | "//=" | "%=" | "**="\n'
|
|
jpayne@68
|
298 ' | ">>=" | "<<=" | "&=" | "^=" | "|="\n'
|
|
jpayne@68
|
299 '\n'
|
|
jpayne@68
|
300 '(See section Primaries for the syntax definitions of the last '
|
|
jpayne@68
|
301 'three\n'
|
|
jpayne@68
|
302 'symbols.)\n'
|
|
jpayne@68
|
303 '\n'
|
|
jpayne@68
|
304 'An augmented assignment evaluates the target (which, unlike '
|
|
jpayne@68
|
305 'normal\n'
|
|
jpayne@68
|
306 'assignment statements, cannot be an unpacking) and the '
|
|
jpayne@68
|
307 'expression\n'
|
|
jpayne@68
|
308 'list, performs the binary operation specific to the type of '
|
|
jpayne@68
|
309 'assignment\n'
|
|
jpayne@68
|
310 'on the two operands, and assigns the result to the original '
|
|
jpayne@68
|
311 'target.\n'
|
|
jpayne@68
|
312 'The target is only evaluated once.\n'
|
|
jpayne@68
|
313 '\n'
|
|
jpayne@68
|
314 'An augmented assignment expression like "x += 1" can be '
|
|
jpayne@68
|
315 'rewritten as\n'
|
|
jpayne@68
|
316 '"x = x + 1" to achieve a similar, but not exactly equal '
|
|
jpayne@68
|
317 'effect. In the\n'
|
|
jpayne@68
|
318 'augmented version, "x" is only evaluated once. Also, when '
|
|
jpayne@68
|
319 'possible,\n'
|
|
jpayne@68
|
320 'the actual operation is performed *in-place*, meaning that '
|
|
jpayne@68
|
321 'rather than\n'
|
|
jpayne@68
|
322 'creating a new object and assigning that to the target, the '
|
|
jpayne@68
|
323 'old object\n'
|
|
jpayne@68
|
324 'is modified instead.\n'
|
|
jpayne@68
|
325 '\n'
|
|
jpayne@68
|
326 'Unlike normal assignments, augmented assignments evaluate the '
|
|
jpayne@68
|
327 'left-\n'
|
|
jpayne@68
|
328 'hand side *before* evaluating the right-hand side. For '
|
|
jpayne@68
|
329 'example, "a[i]\n'
|
|
jpayne@68
|
330 '+= f(x)" first looks-up "a[i]", then it evaluates "f(x)" and '
|
|
jpayne@68
|
331 'performs\n'
|
|
jpayne@68
|
332 'the addition, and lastly, it writes the result back to '
|
|
jpayne@68
|
333 '"a[i]".\n'
|
|
jpayne@68
|
334 '\n'
|
|
jpayne@68
|
335 'With the exception of assigning to tuples and multiple targets '
|
|
jpayne@68
|
336 'in a\n'
|
|
jpayne@68
|
337 'single statement, the assignment done by augmented assignment\n'
|
|
jpayne@68
|
338 'statements is handled the same way as normal assignments. '
|
|
jpayne@68
|
339 'Similarly,\n'
|
|
jpayne@68
|
340 'with the exception of the possible *in-place* behavior, the '
|
|
jpayne@68
|
341 'binary\n'
|
|
jpayne@68
|
342 'operation performed by augmented assignment is the same as the '
|
|
jpayne@68
|
343 'normal\n'
|
|
jpayne@68
|
344 'binary operations.\n'
|
|
jpayne@68
|
345 '\n'
|
|
jpayne@68
|
346 'For targets which are attribute references, the same caveat '
|
|
jpayne@68
|
347 'about\n'
|
|
jpayne@68
|
348 'class and instance attributes applies as for regular '
|
|
jpayne@68
|
349 'assignments.\n'
|
|
jpayne@68
|
350 '\n'
|
|
jpayne@68
|
351 '\n'
|
|
jpayne@68
|
352 'Annotated assignment statements\n'
|
|
jpayne@68
|
353 '===============================\n'
|
|
jpayne@68
|
354 '\n'
|
|
jpayne@68
|
355 '*Annotation* assignment is the combination, in a single '
|
|
jpayne@68
|
356 'statement, of\n'
|
|
jpayne@68
|
357 'a variable or attribute annotation and an optional assignment\n'
|
|
jpayne@68
|
358 'statement:\n'
|
|
jpayne@68
|
359 '\n'
|
|
jpayne@68
|
360 ' annotated_assignment_stmt ::= augtarget ":" expression\n'
|
|
jpayne@68
|
361 ' ["=" (starred_expression | '
|
|
jpayne@68
|
362 'yield_expression)]\n'
|
|
jpayne@68
|
363 '\n'
|
|
jpayne@68
|
364 'The difference from normal Assignment statements is that only '
|
|
jpayne@68
|
365 'single\n'
|
|
jpayne@68
|
366 'target is allowed.\n'
|
|
jpayne@68
|
367 '\n'
|
|
jpayne@68
|
368 'For simple names as assignment targets, if in class or module '
|
|
jpayne@68
|
369 'scope,\n'
|
|
jpayne@68
|
370 'the annotations are evaluated and stored in a special class or '
|
|
jpayne@68
|
371 'module\n'
|
|
jpayne@68
|
372 'attribute "__annotations__" that is a dictionary mapping from '
|
|
jpayne@68
|
373 'variable\n'
|
|
jpayne@68
|
374 'names (mangled if private) to evaluated annotations. This '
|
|
jpayne@68
|
375 'attribute is\n'
|
|
jpayne@68
|
376 'writable and is automatically created at the start of class or '
|
|
jpayne@68
|
377 'module\n'
|
|
jpayne@68
|
378 'body execution, if annotations are found statically.\n'
|
|
jpayne@68
|
379 '\n'
|
|
jpayne@68
|
380 'For expressions as assignment targets, the annotations are '
|
|
jpayne@68
|
381 'evaluated\n'
|
|
jpayne@68
|
382 'if in class or module scope, but not stored.\n'
|
|
jpayne@68
|
383 '\n'
|
|
jpayne@68
|
384 'If a name is annotated in a function scope, then this name is '
|
|
jpayne@68
|
385 'local\n'
|
|
jpayne@68
|
386 'for that scope. Annotations are never evaluated and stored in '
|
|
jpayne@68
|
387 'function\n'
|
|
jpayne@68
|
388 'scopes.\n'
|
|
jpayne@68
|
389 '\n'
|
|
jpayne@68
|
390 'If the right hand side is present, an annotated assignment '
|
|
jpayne@68
|
391 'performs\n'
|
|
jpayne@68
|
392 'the actual assignment before evaluating annotations (where\n'
|
|
jpayne@68
|
393 'applicable). If the right hand side is not present for an '
|
|
jpayne@68
|
394 'expression\n'
|
|
jpayne@68
|
395 'target, then the interpreter evaluates the target except for '
|
|
jpayne@68
|
396 'the last\n'
|
|
jpayne@68
|
397 '"__setitem__()" or "__setattr__()" call.\n'
|
|
jpayne@68
|
398 '\n'
|
|
jpayne@68
|
399 'See also:\n'
|
|
jpayne@68
|
400 '\n'
|
|
jpayne@68
|
401 ' **PEP 526** - Syntax for Variable Annotations\n'
|
|
jpayne@68
|
402 ' The proposal that added syntax for annotating the types '
|
|
jpayne@68
|
403 'of\n'
|
|
jpayne@68
|
404 ' variables (including class variables and instance '
|
|
jpayne@68
|
405 'variables),\n'
|
|
jpayne@68
|
406 ' instead of expressing them through comments.\n'
|
|
jpayne@68
|
407 '\n'
|
|
jpayne@68
|
408 ' **PEP 484** - Type hints\n'
|
|
jpayne@68
|
409 ' The proposal that added the "typing" module to provide a '
|
|
jpayne@68
|
410 'standard\n'
|
|
jpayne@68
|
411 ' syntax for type annotations that can be used in static '
|
|
jpayne@68
|
412 'analysis\n'
|
|
jpayne@68
|
413 ' tools and IDEs.\n'
|
|
jpayne@68
|
414 '\n'
|
|
jpayne@68
|
415 'Changed in version 3.8: Now annotated assignments allow same\n'
|
|
jpayne@68
|
416 'expressions in the right hand side as the regular '
|
|
jpayne@68
|
417 'assignments.\n'
|
|
jpayne@68
|
418 'Previously, some expressions (like un-parenthesized tuple '
|
|
jpayne@68
|
419 'expressions)\n'
|
|
jpayne@68
|
420 'caused a syntax error.\n',
|
|
jpayne@68
|
421 'async': 'Coroutines\n'
|
|
jpayne@68
|
422 '**********\n'
|
|
jpayne@68
|
423 '\n'
|
|
jpayne@68
|
424 'New in version 3.5.\n'
|
|
jpayne@68
|
425 '\n'
|
|
jpayne@68
|
426 '\n'
|
|
jpayne@68
|
427 'Coroutine function definition\n'
|
|
jpayne@68
|
428 '=============================\n'
|
|
jpayne@68
|
429 '\n'
|
|
jpayne@68
|
430 ' async_funcdef ::= [decorators] "async" "def" funcname "(" '
|
|
jpayne@68
|
431 '[parameter_list] ")"\n'
|
|
jpayne@68
|
432 ' ["->" expression] ":" suite\n'
|
|
jpayne@68
|
433 '\n'
|
|
jpayne@68
|
434 'Execution of Python coroutines can be suspended and resumed at '
|
|
jpayne@68
|
435 'many\n'
|
|
jpayne@68
|
436 'points (see *coroutine*). Inside the body of a coroutine '
|
|
jpayne@68
|
437 'function,\n'
|
|
jpayne@68
|
438 '"await" and "async" identifiers become reserved keywords; "await"\n'
|
|
jpayne@68
|
439 'expressions, "async for" and "async with" can only be used in\n'
|
|
jpayne@68
|
440 'coroutine function bodies.\n'
|
|
jpayne@68
|
441 '\n'
|
|
jpayne@68
|
442 'Functions defined with "async def" syntax are always coroutine\n'
|
|
jpayne@68
|
443 'functions, even if they do not contain "await" or "async" '
|
|
jpayne@68
|
444 'keywords.\n'
|
|
jpayne@68
|
445 '\n'
|
|
jpayne@68
|
446 'It is a "SyntaxError" to use a "yield from" expression inside the '
|
|
jpayne@68
|
447 'body\n'
|
|
jpayne@68
|
448 'of a coroutine function.\n'
|
|
jpayne@68
|
449 '\n'
|
|
jpayne@68
|
450 'An example of a coroutine function:\n'
|
|
jpayne@68
|
451 '\n'
|
|
jpayne@68
|
452 ' async def func(param1, param2):\n'
|
|
jpayne@68
|
453 ' do_stuff()\n'
|
|
jpayne@68
|
454 ' await some_coroutine()\n'
|
|
jpayne@68
|
455 '\n'
|
|
jpayne@68
|
456 '\n'
|
|
jpayne@68
|
457 'The "async for" statement\n'
|
|
jpayne@68
|
458 '=========================\n'
|
|
jpayne@68
|
459 '\n'
|
|
jpayne@68
|
460 ' async_for_stmt ::= "async" for_stmt\n'
|
|
jpayne@68
|
461 '\n'
|
|
jpayne@68
|
462 'An *asynchronous iterable* is able to call asynchronous code in '
|
|
jpayne@68
|
463 'its\n'
|
|
jpayne@68
|
464 '*iter* implementation, and *asynchronous iterator* can call\n'
|
|
jpayne@68
|
465 'asynchronous code in its *next* method.\n'
|
|
jpayne@68
|
466 '\n'
|
|
jpayne@68
|
467 'The "async for" statement allows convenient iteration over\n'
|
|
jpayne@68
|
468 'asynchronous iterators.\n'
|
|
jpayne@68
|
469 '\n'
|
|
jpayne@68
|
470 'The following code:\n'
|
|
jpayne@68
|
471 '\n'
|
|
jpayne@68
|
472 ' async for TARGET in ITER:\n'
|
|
jpayne@68
|
473 ' BLOCK\n'
|
|
jpayne@68
|
474 ' else:\n'
|
|
jpayne@68
|
475 ' BLOCK2\n'
|
|
jpayne@68
|
476 '\n'
|
|
jpayne@68
|
477 'Is semantically equivalent to:\n'
|
|
jpayne@68
|
478 '\n'
|
|
jpayne@68
|
479 ' iter = (ITER)\n'
|
|
jpayne@68
|
480 ' iter = type(iter).__aiter__(iter)\n'
|
|
jpayne@68
|
481 ' running = True\n'
|
|
jpayne@68
|
482 ' while running:\n'
|
|
jpayne@68
|
483 ' try:\n'
|
|
jpayne@68
|
484 ' TARGET = await type(iter).__anext__(iter)\n'
|
|
jpayne@68
|
485 ' except StopAsyncIteration:\n'
|
|
jpayne@68
|
486 ' running = False\n'
|
|
jpayne@68
|
487 ' else:\n'
|
|
jpayne@68
|
488 ' BLOCK\n'
|
|
jpayne@68
|
489 ' else:\n'
|
|
jpayne@68
|
490 ' BLOCK2\n'
|
|
jpayne@68
|
491 '\n'
|
|
jpayne@68
|
492 'See also "__aiter__()" and "__anext__()" for details.\n'
|
|
jpayne@68
|
493 '\n'
|
|
jpayne@68
|
494 'It is a "SyntaxError" to use an "async for" statement outside the '
|
|
jpayne@68
|
495 'body\n'
|
|
jpayne@68
|
496 'of a coroutine function.\n'
|
|
jpayne@68
|
497 '\n'
|
|
jpayne@68
|
498 '\n'
|
|
jpayne@68
|
499 'The "async with" statement\n'
|
|
jpayne@68
|
500 '==========================\n'
|
|
jpayne@68
|
501 '\n'
|
|
jpayne@68
|
502 ' async_with_stmt ::= "async" with_stmt\n'
|
|
jpayne@68
|
503 '\n'
|
|
jpayne@68
|
504 'An *asynchronous context manager* is a *context manager* that is '
|
|
jpayne@68
|
505 'able\n'
|
|
jpayne@68
|
506 'to suspend execution in its *enter* and *exit* methods.\n'
|
|
jpayne@68
|
507 '\n'
|
|
jpayne@68
|
508 'The following code:\n'
|
|
jpayne@68
|
509 '\n'
|
|
jpayne@68
|
510 ' async with EXPR as VAR:\n'
|
|
jpayne@68
|
511 ' BLOCK\n'
|
|
jpayne@68
|
512 '\n'
|
|
jpayne@68
|
513 'Is semantically equivalent to:\n'
|
|
jpayne@68
|
514 '\n'
|
|
jpayne@68
|
515 ' mgr = (EXPR)\n'
|
|
jpayne@68
|
516 ' aexit = type(mgr).__aexit__\n'
|
|
jpayne@68
|
517 ' aenter = type(mgr).__aenter__(mgr)\n'
|
|
jpayne@68
|
518 '\n'
|
|
jpayne@68
|
519 ' VAR = await aenter\n'
|
|
jpayne@68
|
520 ' try:\n'
|
|
jpayne@68
|
521 ' BLOCK\n'
|
|
jpayne@68
|
522 ' except:\n'
|
|
jpayne@68
|
523 ' if not await aexit(mgr, *sys.exc_info()):\n'
|
|
jpayne@68
|
524 ' raise\n'
|
|
jpayne@68
|
525 ' else:\n'
|
|
jpayne@68
|
526 ' await aexit(mgr, None, None, None)\n'
|
|
jpayne@68
|
527 '\n'
|
|
jpayne@68
|
528 'See also "__aenter__()" and "__aexit__()" for details.\n'
|
|
jpayne@68
|
529 '\n'
|
|
jpayne@68
|
530 'It is a "SyntaxError" to use an "async with" statement outside the\n'
|
|
jpayne@68
|
531 'body of a coroutine function.\n'
|
|
jpayne@68
|
532 '\n'
|
|
jpayne@68
|
533 'See also:\n'
|
|
jpayne@68
|
534 '\n'
|
|
jpayne@68
|
535 ' **PEP 492** - Coroutines with async and await syntax\n'
|
|
jpayne@68
|
536 ' The proposal that made coroutines a proper standalone concept '
|
|
jpayne@68
|
537 'in\n'
|
|
jpayne@68
|
538 ' Python, and added supporting syntax.\n'
|
|
jpayne@68
|
539 '\n'
|
|
jpayne@68
|
540 '-[ Footnotes ]-\n'
|
|
jpayne@68
|
541 '\n'
|
|
jpayne@68
|
542 '[1] The exception is propagated to the invocation stack unless\n'
|
|
jpayne@68
|
543 ' there is a "finally" clause which happens to raise another\n'
|
|
jpayne@68
|
544 ' exception. That new exception causes the old one to be lost.\n'
|
|
jpayne@68
|
545 '\n'
|
|
jpayne@68
|
546 '[2] A string literal appearing as the first statement in the\n'
|
|
jpayne@68
|
547 ' function body is transformed into the function’s "__doc__"\n'
|
|
jpayne@68
|
548 ' attribute and therefore the function’s *docstring*.\n'
|
|
jpayne@68
|
549 '\n'
|
|
jpayne@68
|
550 '[3] A string literal appearing as the first statement in the class\n'
|
|
jpayne@68
|
551 ' body is transformed into the namespace’s "__doc__" item and\n'
|
|
jpayne@68
|
552 ' therefore the class’s *docstring*.\n',
|
|
jpayne@68
|
553 'atom-identifiers': 'Identifiers (Names)\n'
|
|
jpayne@68
|
554 '*******************\n'
|
|
jpayne@68
|
555 '\n'
|
|
jpayne@68
|
556 'An identifier occurring as an atom is a name. See '
|
|
jpayne@68
|
557 'section Identifiers\n'
|
|
jpayne@68
|
558 'and keywords for lexical definition and section Naming '
|
|
jpayne@68
|
559 'and binding for\n'
|
|
jpayne@68
|
560 'documentation of naming and binding.\n'
|
|
jpayne@68
|
561 '\n'
|
|
jpayne@68
|
562 'When the name is bound to an object, evaluation of the '
|
|
jpayne@68
|
563 'atom yields\n'
|
|
jpayne@68
|
564 'that object. When a name is not bound, an attempt to '
|
|
jpayne@68
|
565 'evaluate it\n'
|
|
jpayne@68
|
566 'raises a "NameError" exception.\n'
|
|
jpayne@68
|
567 '\n'
|
|
jpayne@68
|
568 '**Private name mangling:** When an identifier that '
|
|
jpayne@68
|
569 'textually occurs in\n'
|
|
jpayne@68
|
570 'a class definition begins with two or more underscore '
|
|
jpayne@68
|
571 'characters and\n'
|
|
jpayne@68
|
572 'does not end in two or more underscores, it is '
|
|
jpayne@68
|
573 'considered a *private\n'
|
|
jpayne@68
|
574 'name* of that class. Private names are transformed to a '
|
|
jpayne@68
|
575 'longer form\n'
|
|
jpayne@68
|
576 'before code is generated for them. The transformation '
|
|
jpayne@68
|
577 'inserts the\n'
|
|
jpayne@68
|
578 'class name, with leading underscores removed and a '
|
|
jpayne@68
|
579 'single underscore\n'
|
|
jpayne@68
|
580 'inserted, in front of the name. For example, the '
|
|
jpayne@68
|
581 'identifier "__spam"\n'
|
|
jpayne@68
|
582 'occurring in a class named "Ham" will be transformed to '
|
|
jpayne@68
|
583 '"_Ham__spam".\n'
|
|
jpayne@68
|
584 'This transformation is independent of the syntactical '
|
|
jpayne@68
|
585 'context in which\n'
|
|
jpayne@68
|
586 'the identifier is used. If the transformed name is '
|
|
jpayne@68
|
587 'extremely long\n'
|
|
jpayne@68
|
588 '(longer than 255 characters), implementation defined '
|
|
jpayne@68
|
589 'truncation may\n'
|
|
jpayne@68
|
590 'happen. If the class name consists only of underscores, '
|
|
jpayne@68
|
591 'no\n'
|
|
jpayne@68
|
592 'transformation is done.\n',
|
|
jpayne@68
|
593 'atom-literals': 'Literals\n'
|
|
jpayne@68
|
594 '********\n'
|
|
jpayne@68
|
595 '\n'
|
|
jpayne@68
|
596 'Python supports string and bytes literals and various '
|
|
jpayne@68
|
597 'numeric\n'
|
|
jpayne@68
|
598 'literals:\n'
|
|
jpayne@68
|
599 '\n'
|
|
jpayne@68
|
600 ' literal ::= stringliteral | bytesliteral\n'
|
|
jpayne@68
|
601 ' | integer | floatnumber | imagnumber\n'
|
|
jpayne@68
|
602 '\n'
|
|
jpayne@68
|
603 'Evaluation of a literal yields an object of the given type '
|
|
jpayne@68
|
604 '(string,\n'
|
|
jpayne@68
|
605 'bytes, integer, floating point number, complex number) with '
|
|
jpayne@68
|
606 'the given\n'
|
|
jpayne@68
|
607 'value. The value may be approximated in the case of '
|
|
jpayne@68
|
608 'floating point\n'
|
|
jpayne@68
|
609 'and imaginary (complex) literals. See section Literals for '
|
|
jpayne@68
|
610 'details.\n'
|
|
jpayne@68
|
611 '\n'
|
|
jpayne@68
|
612 'All literals correspond to immutable data types, and hence '
|
|
jpayne@68
|
613 'the\n'
|
|
jpayne@68
|
614 'object’s identity is less important than its value. '
|
|
jpayne@68
|
615 'Multiple\n'
|
|
jpayne@68
|
616 'evaluations of literals with the same value (either the '
|
|
jpayne@68
|
617 'same\n'
|
|
jpayne@68
|
618 'occurrence in the program text or a different occurrence) '
|
|
jpayne@68
|
619 'may obtain\n'
|
|
jpayne@68
|
620 'the same object or a different object with the same '
|
|
jpayne@68
|
621 'value.\n',
|
|
jpayne@68
|
622 'attribute-access': 'Customizing attribute access\n'
|
|
jpayne@68
|
623 '****************************\n'
|
|
jpayne@68
|
624 '\n'
|
|
jpayne@68
|
625 'The following methods can be defined to customize the '
|
|
jpayne@68
|
626 'meaning of\n'
|
|
jpayne@68
|
627 'attribute access (use of, assignment to, or deletion of '
|
|
jpayne@68
|
628 '"x.name") for\n'
|
|
jpayne@68
|
629 'class instances.\n'
|
|
jpayne@68
|
630 '\n'
|
|
jpayne@68
|
631 'object.__getattr__(self, name)\n'
|
|
jpayne@68
|
632 '\n'
|
|
jpayne@68
|
633 ' Called when the default attribute access fails with '
|
|
jpayne@68
|
634 'an\n'
|
|
jpayne@68
|
635 ' "AttributeError" (either "__getattribute__()" raises '
|
|
jpayne@68
|
636 'an\n'
|
|
jpayne@68
|
637 ' "AttributeError" because *name* is not an instance '
|
|
jpayne@68
|
638 'attribute or an\n'
|
|
jpayne@68
|
639 ' attribute in the class tree for "self"; or '
|
|
jpayne@68
|
640 '"__get__()" of a *name*\n'
|
|
jpayne@68
|
641 ' property raises "AttributeError"). This method '
|
|
jpayne@68
|
642 'should either\n'
|
|
jpayne@68
|
643 ' return the (computed) attribute value or raise an '
|
|
jpayne@68
|
644 '"AttributeError"\n'
|
|
jpayne@68
|
645 ' exception.\n'
|
|
jpayne@68
|
646 '\n'
|
|
jpayne@68
|
647 ' Note that if the attribute is found through the '
|
|
jpayne@68
|
648 'normal mechanism,\n'
|
|
jpayne@68
|
649 ' "__getattr__()" is not called. (This is an '
|
|
jpayne@68
|
650 'intentional asymmetry\n'
|
|
jpayne@68
|
651 ' between "__getattr__()" and "__setattr__()".) This is '
|
|
jpayne@68
|
652 'done both for\n'
|
|
jpayne@68
|
653 ' efficiency reasons and because otherwise '
|
|
jpayne@68
|
654 '"__getattr__()" would have\n'
|
|
jpayne@68
|
655 ' no way to access other attributes of the instance. '
|
|
jpayne@68
|
656 'Note that at\n'
|
|
jpayne@68
|
657 ' least for instance variables, you can fake total '
|
|
jpayne@68
|
658 'control by not\n'
|
|
jpayne@68
|
659 ' inserting any values in the instance attribute '
|
|
jpayne@68
|
660 'dictionary (but\n'
|
|
jpayne@68
|
661 ' instead inserting them in another object). See the\n'
|
|
jpayne@68
|
662 ' "__getattribute__()" method below for a way to '
|
|
jpayne@68
|
663 'actually get total\n'
|
|
jpayne@68
|
664 ' control over attribute access.\n'
|
|
jpayne@68
|
665 '\n'
|
|
jpayne@68
|
666 'object.__getattribute__(self, name)\n'
|
|
jpayne@68
|
667 '\n'
|
|
jpayne@68
|
668 ' Called unconditionally to implement attribute '
|
|
jpayne@68
|
669 'accesses for\n'
|
|
jpayne@68
|
670 ' instances of the class. If the class also defines '
|
|
jpayne@68
|
671 '"__getattr__()",\n'
|
|
jpayne@68
|
672 ' the latter will not be called unless '
|
|
jpayne@68
|
673 '"__getattribute__()" either\n'
|
|
jpayne@68
|
674 ' calls it explicitly or raises an "AttributeError". '
|
|
jpayne@68
|
675 'This method\n'
|
|
jpayne@68
|
676 ' should return the (computed) attribute value or raise '
|
|
jpayne@68
|
677 'an\n'
|
|
jpayne@68
|
678 ' "AttributeError" exception. In order to avoid '
|
|
jpayne@68
|
679 'infinite recursion in\n'
|
|
jpayne@68
|
680 ' this method, its implementation should always call '
|
|
jpayne@68
|
681 'the base class\n'
|
|
jpayne@68
|
682 ' method with the same name to access any attributes it '
|
|
jpayne@68
|
683 'needs, for\n'
|
|
jpayne@68
|
684 ' example, "object.__getattribute__(self, name)".\n'
|
|
jpayne@68
|
685 '\n'
|
|
jpayne@68
|
686 ' Note: This method may still be bypassed when looking '
|
|
jpayne@68
|
687 'up special\n'
|
|
jpayne@68
|
688 ' methods as the result of implicit invocation via '
|
|
jpayne@68
|
689 'language syntax\n'
|
|
jpayne@68
|
690 ' or built-in functions. See Special method lookup.\n'
|
|
jpayne@68
|
691 '\n'
|
|
jpayne@68
|
692 'object.__setattr__(self, name, value)\n'
|
|
jpayne@68
|
693 '\n'
|
|
jpayne@68
|
694 ' Called when an attribute assignment is attempted. '
|
|
jpayne@68
|
695 'This is called\n'
|
|
jpayne@68
|
696 ' instead of the normal mechanism (i.e. store the value '
|
|
jpayne@68
|
697 'in the\n'
|
|
jpayne@68
|
698 ' instance dictionary). *name* is the attribute name, '
|
|
jpayne@68
|
699 '*value* is the\n'
|
|
jpayne@68
|
700 ' value to be assigned to it.\n'
|
|
jpayne@68
|
701 '\n'
|
|
jpayne@68
|
702 ' If "__setattr__()" wants to assign to an instance '
|
|
jpayne@68
|
703 'attribute, it\n'
|
|
jpayne@68
|
704 ' should call the base class method with the same name, '
|
|
jpayne@68
|
705 'for example,\n'
|
|
jpayne@68
|
706 ' "object.__setattr__(self, name, value)".\n'
|
|
jpayne@68
|
707 '\n'
|
|
jpayne@68
|
708 'object.__delattr__(self, name)\n'
|
|
jpayne@68
|
709 '\n'
|
|
jpayne@68
|
710 ' Like "__setattr__()" but for attribute deletion '
|
|
jpayne@68
|
711 'instead of\n'
|
|
jpayne@68
|
712 ' assignment. This should only be implemented if "del '
|
|
jpayne@68
|
713 'obj.name" is\n'
|
|
jpayne@68
|
714 ' meaningful for the object.\n'
|
|
jpayne@68
|
715 '\n'
|
|
jpayne@68
|
716 'object.__dir__(self)\n'
|
|
jpayne@68
|
717 '\n'
|
|
jpayne@68
|
718 ' Called when "dir()" is called on the object. A '
|
|
jpayne@68
|
719 'sequence must be\n'
|
|
jpayne@68
|
720 ' returned. "dir()" converts the returned sequence to a '
|
|
jpayne@68
|
721 'list and\n'
|
|
jpayne@68
|
722 ' sorts it.\n'
|
|
jpayne@68
|
723 '\n'
|
|
jpayne@68
|
724 '\n'
|
|
jpayne@68
|
725 'Customizing module attribute access\n'
|
|
jpayne@68
|
726 '===================================\n'
|
|
jpayne@68
|
727 '\n'
|
|
jpayne@68
|
728 'Special names "__getattr__" and "__dir__" can be also '
|
|
jpayne@68
|
729 'used to\n'
|
|
jpayne@68
|
730 'customize access to module attributes. The "__getattr__" '
|
|
jpayne@68
|
731 'function at\n'
|
|
jpayne@68
|
732 'the module level should accept one argument which is the '
|
|
jpayne@68
|
733 'name of an\n'
|
|
jpayne@68
|
734 'attribute and return the computed value or raise an '
|
|
jpayne@68
|
735 '"AttributeError".\n'
|
|
jpayne@68
|
736 'If an attribute is not found on a module object through '
|
|
jpayne@68
|
737 'the normal\n'
|
|
jpayne@68
|
738 'lookup, i.e. "object.__getattribute__()", then '
|
|
jpayne@68
|
739 '"__getattr__" is\n'
|
|
jpayne@68
|
740 'searched in the module "__dict__" before raising an '
|
|
jpayne@68
|
741 '"AttributeError".\n'
|
|
jpayne@68
|
742 'If found, it is called with the attribute name and the '
|
|
jpayne@68
|
743 'result is\n'
|
|
jpayne@68
|
744 'returned.\n'
|
|
jpayne@68
|
745 '\n'
|
|
jpayne@68
|
746 'The "__dir__" function should accept no arguments, and '
|
|
jpayne@68
|
747 'return a\n'
|
|
jpayne@68
|
748 'sequence of strings that represents the names accessible '
|
|
jpayne@68
|
749 'on module. If\n'
|
|
jpayne@68
|
750 'present, this function overrides the standard "dir()" '
|
|
jpayne@68
|
751 'search on a\n'
|
|
jpayne@68
|
752 'module.\n'
|
|
jpayne@68
|
753 '\n'
|
|
jpayne@68
|
754 'For a more fine grained customization of the module '
|
|
jpayne@68
|
755 'behavior (setting\n'
|
|
jpayne@68
|
756 'attributes, properties, etc.), one can set the '
|
|
jpayne@68
|
757 '"__class__" attribute\n'
|
|
jpayne@68
|
758 'of a module object to a subclass of "types.ModuleType". '
|
|
jpayne@68
|
759 'For example:\n'
|
|
jpayne@68
|
760 '\n'
|
|
jpayne@68
|
761 ' import sys\n'
|
|
jpayne@68
|
762 ' from types import ModuleType\n'
|
|
jpayne@68
|
763 '\n'
|
|
jpayne@68
|
764 ' class VerboseModule(ModuleType):\n'
|
|
jpayne@68
|
765 ' def __repr__(self):\n'
|
|
jpayne@68
|
766 " return f'Verbose {self.__name__}'\n"
|
|
jpayne@68
|
767 '\n'
|
|
jpayne@68
|
768 ' def __setattr__(self, attr, value):\n'
|
|
jpayne@68
|
769 " print(f'Setting {attr}...')\n"
|
|
jpayne@68
|
770 ' super().__setattr__(attr, value)\n'
|
|
jpayne@68
|
771 '\n'
|
|
jpayne@68
|
772 ' sys.modules[__name__].__class__ = VerboseModule\n'
|
|
jpayne@68
|
773 '\n'
|
|
jpayne@68
|
774 'Note: Defining module "__getattr__" and setting module '
|
|
jpayne@68
|
775 '"__class__"\n'
|
|
jpayne@68
|
776 ' only affect lookups made using the attribute access '
|
|
jpayne@68
|
777 'syntax –\n'
|
|
jpayne@68
|
778 ' directly accessing the module globals (whether by code '
|
|
jpayne@68
|
779 'within the\n'
|
|
jpayne@68
|
780 ' module, or via a reference to the module’s globals '
|
|
jpayne@68
|
781 'dictionary) is\n'
|
|
jpayne@68
|
782 ' unaffected.\n'
|
|
jpayne@68
|
783 '\n'
|
|
jpayne@68
|
784 'Changed in version 3.5: "__class__" module attribute is '
|
|
jpayne@68
|
785 'now writable.\n'
|
|
jpayne@68
|
786 '\n'
|
|
jpayne@68
|
787 'New in version 3.7: "__getattr__" and "__dir__" module '
|
|
jpayne@68
|
788 'attributes.\n'
|
|
jpayne@68
|
789 '\n'
|
|
jpayne@68
|
790 'See also:\n'
|
|
jpayne@68
|
791 '\n'
|
|
jpayne@68
|
792 ' **PEP 562** - Module __getattr__ and __dir__\n'
|
|
jpayne@68
|
793 ' Describes the "__getattr__" and "__dir__" functions '
|
|
jpayne@68
|
794 'on modules.\n'
|
|
jpayne@68
|
795 '\n'
|
|
jpayne@68
|
796 '\n'
|
|
jpayne@68
|
797 'Implementing Descriptors\n'
|
|
jpayne@68
|
798 '========================\n'
|
|
jpayne@68
|
799 '\n'
|
|
jpayne@68
|
800 'The following methods only apply when an instance of the '
|
|
jpayne@68
|
801 'class\n'
|
|
jpayne@68
|
802 'containing the method (a so-called *descriptor* class) '
|
|
jpayne@68
|
803 'appears in an\n'
|
|
jpayne@68
|
804 '*owner* class (the descriptor must be in either the '
|
|
jpayne@68
|
805 'owner’s class\n'
|
|
jpayne@68
|
806 'dictionary or in the class dictionary for one of its '
|
|
jpayne@68
|
807 'parents). In the\n'
|
|
jpayne@68
|
808 'examples below, “the attribute” refers to the attribute '
|
|
jpayne@68
|
809 'whose name is\n'
|
|
jpayne@68
|
810 'the key of the property in the owner class’ "__dict__".\n'
|
|
jpayne@68
|
811 '\n'
|
|
jpayne@68
|
812 'object.__get__(self, instance, owner=None)\n'
|
|
jpayne@68
|
813 '\n'
|
|
jpayne@68
|
814 ' Called to get the attribute of the owner class (class '
|
|
jpayne@68
|
815 'attribute\n'
|
|
jpayne@68
|
816 ' access) or of an instance of that class (instance '
|
|
jpayne@68
|
817 'attribute\n'
|
|
jpayne@68
|
818 ' access). The optional *owner* argument is the owner '
|
|
jpayne@68
|
819 'class, while\n'
|
|
jpayne@68
|
820 ' *instance* is the instance that the attribute was '
|
|
jpayne@68
|
821 'accessed through,\n'
|
|
jpayne@68
|
822 ' or "None" when the attribute is accessed through the '
|
|
jpayne@68
|
823 '*owner*.\n'
|
|
jpayne@68
|
824 '\n'
|
|
jpayne@68
|
825 ' This method should return the computed attribute '
|
|
jpayne@68
|
826 'value or raise an\n'
|
|
jpayne@68
|
827 ' "AttributeError" exception.\n'
|
|
jpayne@68
|
828 '\n'
|
|
jpayne@68
|
829 ' **PEP 252** specifies that "__get__()" is callable '
|
|
jpayne@68
|
830 'with one or two\n'
|
|
jpayne@68
|
831 ' arguments. Python’s own built-in descriptors support '
|
|
jpayne@68
|
832 'this\n'
|
|
jpayne@68
|
833 ' specification; however, it is likely that some '
|
|
jpayne@68
|
834 'third-party tools\n'
|
|
jpayne@68
|
835 ' have descriptors that require both arguments. '
|
|
jpayne@68
|
836 'Python’s own\n'
|
|
jpayne@68
|
837 ' "__getattribute__()" implementation always passes in '
|
|
jpayne@68
|
838 'both arguments\n'
|
|
jpayne@68
|
839 ' whether they are required or not.\n'
|
|
jpayne@68
|
840 '\n'
|
|
jpayne@68
|
841 'object.__set__(self, instance, value)\n'
|
|
jpayne@68
|
842 '\n'
|
|
jpayne@68
|
843 ' Called to set the attribute on an instance *instance* '
|
|
jpayne@68
|
844 'of the owner\n'
|
|
jpayne@68
|
845 ' class to a new value, *value*.\n'
|
|
jpayne@68
|
846 '\n'
|
|
jpayne@68
|
847 ' Note, adding "__set__()" or "__delete__()" changes '
|
|
jpayne@68
|
848 'the kind of\n'
|
|
jpayne@68
|
849 ' descriptor to a “data descriptor”. See Invoking '
|
|
jpayne@68
|
850 'Descriptors for\n'
|
|
jpayne@68
|
851 ' more details.\n'
|
|
jpayne@68
|
852 '\n'
|
|
jpayne@68
|
853 'object.__delete__(self, instance)\n'
|
|
jpayne@68
|
854 '\n'
|
|
jpayne@68
|
855 ' Called to delete the attribute on an instance '
|
|
jpayne@68
|
856 '*instance* of the\n'
|
|
jpayne@68
|
857 ' owner class.\n'
|
|
jpayne@68
|
858 '\n'
|
|
jpayne@68
|
859 'object.__set_name__(self, owner, name)\n'
|
|
jpayne@68
|
860 '\n'
|
|
jpayne@68
|
861 ' Called at the time the owning class *owner* is '
|
|
jpayne@68
|
862 'created. The\n'
|
|
jpayne@68
|
863 ' descriptor has been assigned to *name*.\n'
|
|
jpayne@68
|
864 '\n'
|
|
jpayne@68
|
865 ' Note: "__set_name__()" is only called implicitly as '
|
|
jpayne@68
|
866 'part of the\n'
|
|
jpayne@68
|
867 ' "type" constructor, so it will need to be called '
|
|
jpayne@68
|
868 'explicitly with\n'
|
|
jpayne@68
|
869 ' the appropriate parameters when a descriptor is '
|
|
jpayne@68
|
870 'added to a class\n'
|
|
jpayne@68
|
871 ' after initial creation:\n'
|
|
jpayne@68
|
872 '\n'
|
|
jpayne@68
|
873 ' class A:\n'
|
|
jpayne@68
|
874 ' pass\n'
|
|
jpayne@68
|
875 ' descr = custom_descriptor()\n'
|
|
jpayne@68
|
876 ' A.attr = descr\n'
|
|
jpayne@68
|
877 " descr.__set_name__(A, 'attr')\n"
|
|
jpayne@68
|
878 '\n'
|
|
jpayne@68
|
879 ' See Creating the class object for more details.\n'
|
|
jpayne@68
|
880 '\n'
|
|
jpayne@68
|
881 ' New in version 3.6.\n'
|
|
jpayne@68
|
882 '\n'
|
|
jpayne@68
|
883 'The attribute "__objclass__" is interpreted by the '
|
|
jpayne@68
|
884 '"inspect" module as\n'
|
|
jpayne@68
|
885 'specifying the class where this object was defined '
|
|
jpayne@68
|
886 '(setting this\n'
|
|
jpayne@68
|
887 'appropriately can assist in runtime introspection of '
|
|
jpayne@68
|
888 'dynamic class\n'
|
|
jpayne@68
|
889 'attributes). For callables, it may indicate that an '
|
|
jpayne@68
|
890 'instance of the\n'
|
|
jpayne@68
|
891 'given type (or a subclass) is expected or required as '
|
|
jpayne@68
|
892 'the first\n'
|
|
jpayne@68
|
893 'positional argument (for example, CPython sets this '
|
|
jpayne@68
|
894 'attribute for\n'
|
|
jpayne@68
|
895 'unbound methods that are implemented in C).\n'
|
|
jpayne@68
|
896 '\n'
|
|
jpayne@68
|
897 '\n'
|
|
jpayne@68
|
898 'Invoking Descriptors\n'
|
|
jpayne@68
|
899 '====================\n'
|
|
jpayne@68
|
900 '\n'
|
|
jpayne@68
|
901 'In general, a descriptor is an object attribute with '
|
|
jpayne@68
|
902 '“binding\n'
|
|
jpayne@68
|
903 'behavior”, one whose attribute access has been '
|
|
jpayne@68
|
904 'overridden by methods\n'
|
|
jpayne@68
|
905 'in the descriptor protocol: "__get__()", "__set__()", '
|
|
jpayne@68
|
906 'and\n'
|
|
jpayne@68
|
907 '"__delete__()". If any of those methods are defined for '
|
|
jpayne@68
|
908 'an object, it\n'
|
|
jpayne@68
|
909 'is said to be a descriptor.\n'
|
|
jpayne@68
|
910 '\n'
|
|
jpayne@68
|
911 'The default behavior for attribute access is to get, '
|
|
jpayne@68
|
912 'set, or delete\n'
|
|
jpayne@68
|
913 'the attribute from an object’s dictionary. For instance, '
|
|
jpayne@68
|
914 '"a.x" has a\n'
|
|
jpayne@68
|
915 'lookup chain starting with "a.__dict__[\'x\']", then\n'
|
|
jpayne@68
|
916 '"type(a).__dict__[\'x\']", and continuing through the '
|
|
jpayne@68
|
917 'base classes of\n'
|
|
jpayne@68
|
918 '"type(a)" excluding metaclasses.\n'
|
|
jpayne@68
|
919 '\n'
|
|
jpayne@68
|
920 'However, if the looked-up value is an object defining '
|
|
jpayne@68
|
921 'one of the\n'
|
|
jpayne@68
|
922 'descriptor methods, then Python may override the default '
|
|
jpayne@68
|
923 'behavior and\n'
|
|
jpayne@68
|
924 'invoke the descriptor method instead. Where this occurs '
|
|
jpayne@68
|
925 'in the\n'
|
|
jpayne@68
|
926 'precedence chain depends on which descriptor methods '
|
|
jpayne@68
|
927 'were defined and\n'
|
|
jpayne@68
|
928 'how they were called.\n'
|
|
jpayne@68
|
929 '\n'
|
|
jpayne@68
|
930 'The starting point for descriptor invocation is a '
|
|
jpayne@68
|
931 'binding, "a.x". How\n'
|
|
jpayne@68
|
932 'the arguments are assembled depends on "a":\n'
|
|
jpayne@68
|
933 '\n'
|
|
jpayne@68
|
934 'Direct Call\n'
|
|
jpayne@68
|
935 ' The simplest and least common call is when user code '
|
|
jpayne@68
|
936 'directly\n'
|
|
jpayne@68
|
937 ' invokes a descriptor method: "x.__get__(a)".\n'
|
|
jpayne@68
|
938 '\n'
|
|
jpayne@68
|
939 'Instance Binding\n'
|
|
jpayne@68
|
940 ' If binding to an object instance, "a.x" is '
|
|
jpayne@68
|
941 'transformed into the\n'
|
|
jpayne@68
|
942 ' call: "type(a).__dict__[\'x\'].__get__(a, type(a))".\n'
|
|
jpayne@68
|
943 '\n'
|
|
jpayne@68
|
944 'Class Binding\n'
|
|
jpayne@68
|
945 ' If binding to a class, "A.x" is transformed into the '
|
|
jpayne@68
|
946 'call:\n'
|
|
jpayne@68
|
947 ' "A.__dict__[\'x\'].__get__(None, A)".\n'
|
|
jpayne@68
|
948 '\n'
|
|
jpayne@68
|
949 'Super Binding\n'
|
|
jpayne@68
|
950 ' If "a" is an instance of "super", then the binding '
|
|
jpayne@68
|
951 '"super(B,\n'
|
|
jpayne@68
|
952 ' obj).m()" searches "obj.__class__.__mro__" for the '
|
|
jpayne@68
|
953 'base class "A"\n'
|
|
jpayne@68
|
954 ' immediately preceding "B" and then invokes the '
|
|
jpayne@68
|
955 'descriptor with the\n'
|
|
jpayne@68
|
956 ' call: "A.__dict__[\'m\'].__get__(obj, '
|
|
jpayne@68
|
957 'obj.__class__)".\n'
|
|
jpayne@68
|
958 '\n'
|
|
jpayne@68
|
959 'For instance bindings, the precedence of descriptor '
|
|
jpayne@68
|
960 'invocation depends\n'
|
|
jpayne@68
|
961 'on the which descriptor methods are defined. A '
|
|
jpayne@68
|
962 'descriptor can define\n'
|
|
jpayne@68
|
963 'any combination of "__get__()", "__set__()" and '
|
|
jpayne@68
|
964 '"__delete__()". If it\n'
|
|
jpayne@68
|
965 'does not define "__get__()", then accessing the '
|
|
jpayne@68
|
966 'attribute will return\n'
|
|
jpayne@68
|
967 'the descriptor object itself unless there is a value in '
|
|
jpayne@68
|
968 'the object’s\n'
|
|
jpayne@68
|
969 'instance dictionary. If the descriptor defines '
|
|
jpayne@68
|
970 '"__set__()" and/or\n'
|
|
jpayne@68
|
971 '"__delete__()", it is a data descriptor; if it defines '
|
|
jpayne@68
|
972 'neither, it is\n'
|
|
jpayne@68
|
973 'a non-data descriptor. Normally, data descriptors '
|
|
jpayne@68
|
974 'define both\n'
|
|
jpayne@68
|
975 '"__get__()" and "__set__()", while non-data descriptors '
|
|
jpayne@68
|
976 'have just the\n'
|
|
jpayne@68
|
977 '"__get__()" method. Data descriptors with "__set__()" '
|
|
jpayne@68
|
978 'and "__get__()"\n'
|
|
jpayne@68
|
979 'defined always override a redefinition in an instance '
|
|
jpayne@68
|
980 'dictionary. In\n'
|
|
jpayne@68
|
981 'contrast, non-data descriptors can be overridden by '
|
|
jpayne@68
|
982 'instances.\n'
|
|
jpayne@68
|
983 '\n'
|
|
jpayne@68
|
984 'Python methods (including "staticmethod()" and '
|
|
jpayne@68
|
985 '"classmethod()") are\n'
|
|
jpayne@68
|
986 'implemented as non-data descriptors. Accordingly, '
|
|
jpayne@68
|
987 'instances can\n'
|
|
jpayne@68
|
988 'redefine and override methods. This allows individual '
|
|
jpayne@68
|
989 'instances to\n'
|
|
jpayne@68
|
990 'acquire behaviors that differ from other instances of '
|
|
jpayne@68
|
991 'the same class.\n'
|
|
jpayne@68
|
992 '\n'
|
|
jpayne@68
|
993 'The "property()" function is implemented as a data '
|
|
jpayne@68
|
994 'descriptor.\n'
|
|
jpayne@68
|
995 'Accordingly, instances cannot override the behavior of a '
|
|
jpayne@68
|
996 'property.\n'
|
|
jpayne@68
|
997 '\n'
|
|
jpayne@68
|
998 '\n'
|
|
jpayne@68
|
999 '__slots__\n'
|
|
jpayne@68
|
1000 '=========\n'
|
|
jpayne@68
|
1001 '\n'
|
|
jpayne@68
|
1002 '*__slots__* allow us to explicitly declare data members '
|
|
jpayne@68
|
1003 '(like\n'
|
|
jpayne@68
|
1004 'properties) and deny the creation of *__dict__* and '
|
|
jpayne@68
|
1005 '*__weakref__*\n'
|
|
jpayne@68
|
1006 '(unless explicitly declared in *__slots__* or available '
|
|
jpayne@68
|
1007 'in a parent.)\n'
|
|
jpayne@68
|
1008 '\n'
|
|
jpayne@68
|
1009 'The space saved over using *__dict__* can be '
|
|
jpayne@68
|
1010 'significant. Attribute\n'
|
|
jpayne@68
|
1011 'lookup speed can be significantly improved as well.\n'
|
|
jpayne@68
|
1012 '\n'
|
|
jpayne@68
|
1013 'object.__slots__\n'
|
|
jpayne@68
|
1014 '\n'
|
|
jpayne@68
|
1015 ' This class variable can be assigned a string, '
|
|
jpayne@68
|
1016 'iterable, or sequence\n'
|
|
jpayne@68
|
1017 ' of strings with variable names used by instances. '
|
|
jpayne@68
|
1018 '*__slots__*\n'
|
|
jpayne@68
|
1019 ' reserves space for the declared variables and '
|
|
jpayne@68
|
1020 'prevents the\n'
|
|
jpayne@68
|
1021 ' automatic creation of *__dict__* and *__weakref__* '
|
|
jpayne@68
|
1022 'for each\n'
|
|
jpayne@68
|
1023 ' instance.\n'
|
|
jpayne@68
|
1024 '\n'
|
|
jpayne@68
|
1025 '\n'
|
|
jpayne@68
|
1026 'Notes on using *__slots__*\n'
|
|
jpayne@68
|
1027 '--------------------------\n'
|
|
jpayne@68
|
1028 '\n'
|
|
jpayne@68
|
1029 '* When inheriting from a class without *__slots__*, the '
|
|
jpayne@68
|
1030 '*__dict__*\n'
|
|
jpayne@68
|
1031 ' and *__weakref__* attribute of the instances will '
|
|
jpayne@68
|
1032 'always be\n'
|
|
jpayne@68
|
1033 ' accessible.\n'
|
|
jpayne@68
|
1034 '\n'
|
|
jpayne@68
|
1035 '* Without a *__dict__* variable, instances cannot be '
|
|
jpayne@68
|
1036 'assigned new\n'
|
|
jpayne@68
|
1037 ' variables not listed in the *__slots__* definition. '
|
|
jpayne@68
|
1038 'Attempts to\n'
|
|
jpayne@68
|
1039 ' assign to an unlisted variable name raises '
|
|
jpayne@68
|
1040 '"AttributeError". If\n'
|
|
jpayne@68
|
1041 ' dynamic assignment of new variables is desired, then '
|
|
jpayne@68
|
1042 'add\n'
|
|
jpayne@68
|
1043 ' "\'__dict__\'" to the sequence of strings in the '
|
|
jpayne@68
|
1044 '*__slots__*\n'
|
|
jpayne@68
|
1045 ' declaration.\n'
|
|
jpayne@68
|
1046 '\n'
|
|
jpayne@68
|
1047 '* Without a *__weakref__* variable for each instance, '
|
|
jpayne@68
|
1048 'classes\n'
|
|
jpayne@68
|
1049 ' defining *__slots__* do not support weak references to '
|
|
jpayne@68
|
1050 'its\n'
|
|
jpayne@68
|
1051 ' instances. If weak reference support is needed, then '
|
|
jpayne@68
|
1052 'add\n'
|
|
jpayne@68
|
1053 ' "\'__weakref__\'" to the sequence of strings in the '
|
|
jpayne@68
|
1054 '*__slots__*\n'
|
|
jpayne@68
|
1055 ' declaration.\n'
|
|
jpayne@68
|
1056 '\n'
|
|
jpayne@68
|
1057 '* *__slots__* are implemented at the class level by '
|
|
jpayne@68
|
1058 'creating\n'
|
|
jpayne@68
|
1059 ' descriptors (Implementing Descriptors) for each '
|
|
jpayne@68
|
1060 'variable name. As a\n'
|
|
jpayne@68
|
1061 ' result, class attributes cannot be used to set default '
|
|
jpayne@68
|
1062 'values for\n'
|
|
jpayne@68
|
1063 ' instance variables defined by *__slots__*; otherwise, '
|
|
jpayne@68
|
1064 'the class\n'
|
|
jpayne@68
|
1065 ' attribute would overwrite the descriptor assignment.\n'
|
|
jpayne@68
|
1066 '\n'
|
|
jpayne@68
|
1067 '* The action of a *__slots__* declaration is not limited '
|
|
jpayne@68
|
1068 'to the\n'
|
|
jpayne@68
|
1069 ' class where it is defined. *__slots__* declared in '
|
|
jpayne@68
|
1070 'parents are\n'
|
|
jpayne@68
|
1071 ' available in child classes. However, child subclasses '
|
|
jpayne@68
|
1072 'will get a\n'
|
|
jpayne@68
|
1073 ' *__dict__* and *__weakref__* unless they also define '
|
|
jpayne@68
|
1074 '*__slots__*\n'
|
|
jpayne@68
|
1075 ' (which should only contain names of any *additional* '
|
|
jpayne@68
|
1076 'slots).\n'
|
|
jpayne@68
|
1077 '\n'
|
|
jpayne@68
|
1078 '* If a class defines a slot also defined in a base '
|
|
jpayne@68
|
1079 'class, the\n'
|
|
jpayne@68
|
1080 ' instance variable defined by the base class slot is '
|
|
jpayne@68
|
1081 'inaccessible\n'
|
|
jpayne@68
|
1082 ' (except by retrieving its descriptor directly from the '
|
|
jpayne@68
|
1083 'base class).\n'
|
|
jpayne@68
|
1084 ' This renders the meaning of the program undefined. In '
|
|
jpayne@68
|
1085 'the future, a\n'
|
|
jpayne@68
|
1086 ' check may be added to prevent this.\n'
|
|
jpayne@68
|
1087 '\n'
|
|
jpayne@68
|
1088 '* Nonempty *__slots__* does not work for classes derived '
|
|
jpayne@68
|
1089 'from\n'
|
|
jpayne@68
|
1090 ' “variable-length” built-in types such as "int", '
|
|
jpayne@68
|
1091 '"bytes" and "tuple".\n'
|
|
jpayne@68
|
1092 '\n'
|
|
jpayne@68
|
1093 '* Any non-string iterable may be assigned to '
|
|
jpayne@68
|
1094 '*__slots__*. Mappings\n'
|
|
jpayne@68
|
1095 ' may also be used; however, in the future, special '
|
|
jpayne@68
|
1096 'meaning may be\n'
|
|
jpayne@68
|
1097 ' assigned to the values corresponding to each key.\n'
|
|
jpayne@68
|
1098 '\n'
|
|
jpayne@68
|
1099 '* *__class__* assignment works only if both classes have '
|
|
jpayne@68
|
1100 'the same\n'
|
|
jpayne@68
|
1101 ' *__slots__*.\n'
|
|
jpayne@68
|
1102 '\n'
|
|
jpayne@68
|
1103 '* Multiple inheritance with multiple slotted parent '
|
|
jpayne@68
|
1104 'classes can be\n'
|
|
jpayne@68
|
1105 ' used, but only one parent is allowed to have '
|
|
jpayne@68
|
1106 'attributes created by\n'
|
|
jpayne@68
|
1107 ' slots (the other bases must have empty slot layouts) - '
|
|
jpayne@68
|
1108 'violations\n'
|
|
jpayne@68
|
1109 ' raise "TypeError".\n'
|
|
jpayne@68
|
1110 '\n'
|
|
jpayne@68
|
1111 '* If an iterator is used for *__slots__* then a '
|
|
jpayne@68
|
1112 'descriptor is\n'
|
|
jpayne@68
|
1113 ' created for each of the iterator’s values. However, '
|
|
jpayne@68
|
1114 'the *__slots__*\n'
|
|
jpayne@68
|
1115 ' attribute will be an empty iterator.\n',
|
|
jpayne@68
|
1116 'attribute-references': 'Attribute references\n'
|
|
jpayne@68
|
1117 '********************\n'
|
|
jpayne@68
|
1118 '\n'
|
|
jpayne@68
|
1119 'An attribute reference is a primary followed by a '
|
|
jpayne@68
|
1120 'period and a name:\n'
|
|
jpayne@68
|
1121 '\n'
|
|
jpayne@68
|
1122 ' attributeref ::= primary "." identifier\n'
|
|
jpayne@68
|
1123 '\n'
|
|
jpayne@68
|
1124 'The primary must evaluate to an object of a type '
|
|
jpayne@68
|
1125 'that supports\n'
|
|
jpayne@68
|
1126 'attribute references, which most objects do. This '
|
|
jpayne@68
|
1127 'object is then\n'
|
|
jpayne@68
|
1128 'asked to produce the attribute whose name is the '
|
|
jpayne@68
|
1129 'identifier. This\n'
|
|
jpayne@68
|
1130 'production can be customized by overriding the '
|
|
jpayne@68
|
1131 '"__getattr__()" method.\n'
|
|
jpayne@68
|
1132 'If this attribute is not available, the exception '
|
|
jpayne@68
|
1133 '"AttributeError" is\n'
|
|
jpayne@68
|
1134 'raised. Otherwise, the type and value of the object '
|
|
jpayne@68
|
1135 'produced is\n'
|
|
jpayne@68
|
1136 'determined by the object. Multiple evaluations of '
|
|
jpayne@68
|
1137 'the same attribute\n'
|
|
jpayne@68
|
1138 'reference may yield different objects.\n',
|
|
jpayne@68
|
1139 'augassign': 'Augmented assignment statements\n'
|
|
jpayne@68
|
1140 '*******************************\n'
|
|
jpayne@68
|
1141 '\n'
|
|
jpayne@68
|
1142 'Augmented assignment is the combination, in a single statement, '
|
|
jpayne@68
|
1143 'of a\n'
|
|
jpayne@68
|
1144 'binary operation and an assignment statement:\n'
|
|
jpayne@68
|
1145 '\n'
|
|
jpayne@68
|
1146 ' augmented_assignment_stmt ::= augtarget augop '
|
|
jpayne@68
|
1147 '(expression_list | yield_expression)\n'
|
|
jpayne@68
|
1148 ' augtarget ::= identifier | attributeref | '
|
|
jpayne@68
|
1149 'subscription | slicing\n'
|
|
jpayne@68
|
1150 ' augop ::= "+=" | "-=" | "*=" | "@=" | '
|
|
jpayne@68
|
1151 '"/=" | "//=" | "%=" | "**="\n'
|
|
jpayne@68
|
1152 ' | ">>=" | "<<=" | "&=" | "^=" | "|="\n'
|
|
jpayne@68
|
1153 '\n'
|
|
jpayne@68
|
1154 '(See section Primaries for the syntax definitions of the last '
|
|
jpayne@68
|
1155 'three\n'
|
|
jpayne@68
|
1156 'symbols.)\n'
|
|
jpayne@68
|
1157 '\n'
|
|
jpayne@68
|
1158 'An augmented assignment evaluates the target (which, unlike '
|
|
jpayne@68
|
1159 'normal\n'
|
|
jpayne@68
|
1160 'assignment statements, cannot be an unpacking) and the '
|
|
jpayne@68
|
1161 'expression\n'
|
|
jpayne@68
|
1162 'list, performs the binary operation specific to the type of '
|
|
jpayne@68
|
1163 'assignment\n'
|
|
jpayne@68
|
1164 'on the two operands, and assigns the result to the original '
|
|
jpayne@68
|
1165 'target.\n'
|
|
jpayne@68
|
1166 'The target is only evaluated once.\n'
|
|
jpayne@68
|
1167 '\n'
|
|
jpayne@68
|
1168 'An augmented assignment expression like "x += 1" can be '
|
|
jpayne@68
|
1169 'rewritten as\n'
|
|
jpayne@68
|
1170 '"x = x + 1" to achieve a similar, but not exactly equal effect. '
|
|
jpayne@68
|
1171 'In the\n'
|
|
jpayne@68
|
1172 'augmented version, "x" is only evaluated once. Also, when '
|
|
jpayne@68
|
1173 'possible,\n'
|
|
jpayne@68
|
1174 'the actual operation is performed *in-place*, meaning that '
|
|
jpayne@68
|
1175 'rather than\n'
|
|
jpayne@68
|
1176 'creating a new object and assigning that to the target, the old '
|
|
jpayne@68
|
1177 'object\n'
|
|
jpayne@68
|
1178 'is modified instead.\n'
|
|
jpayne@68
|
1179 '\n'
|
|
jpayne@68
|
1180 'Unlike normal assignments, augmented assignments evaluate the '
|
|
jpayne@68
|
1181 'left-\n'
|
|
jpayne@68
|
1182 'hand side *before* evaluating the right-hand side. For '
|
|
jpayne@68
|
1183 'example, "a[i]\n'
|
|
jpayne@68
|
1184 '+= f(x)" first looks-up "a[i]", then it evaluates "f(x)" and '
|
|
jpayne@68
|
1185 'performs\n'
|
|
jpayne@68
|
1186 'the addition, and lastly, it writes the result back to "a[i]".\n'
|
|
jpayne@68
|
1187 '\n'
|
|
jpayne@68
|
1188 'With the exception of assigning to tuples and multiple targets '
|
|
jpayne@68
|
1189 'in a\n'
|
|
jpayne@68
|
1190 'single statement, the assignment done by augmented assignment\n'
|
|
jpayne@68
|
1191 'statements is handled the same way as normal assignments. '
|
|
jpayne@68
|
1192 'Similarly,\n'
|
|
jpayne@68
|
1193 'with the exception of the possible *in-place* behavior, the '
|
|
jpayne@68
|
1194 'binary\n'
|
|
jpayne@68
|
1195 'operation performed by augmented assignment is the same as the '
|
|
jpayne@68
|
1196 'normal\n'
|
|
jpayne@68
|
1197 'binary operations.\n'
|
|
jpayne@68
|
1198 '\n'
|
|
jpayne@68
|
1199 'For targets which are attribute references, the same caveat '
|
|
jpayne@68
|
1200 'about\n'
|
|
jpayne@68
|
1201 'class and instance attributes applies as for regular '
|
|
jpayne@68
|
1202 'assignments.\n',
|
|
jpayne@68
|
1203 'await': 'Await expression\n'
|
|
jpayne@68
|
1204 '****************\n'
|
|
jpayne@68
|
1205 '\n'
|
|
jpayne@68
|
1206 'Suspend the execution of *coroutine* on an *awaitable* object. Can\n'
|
|
jpayne@68
|
1207 'only be used inside a *coroutine function*.\n'
|
|
jpayne@68
|
1208 '\n'
|
|
jpayne@68
|
1209 ' await_expr ::= "await" primary\n'
|
|
jpayne@68
|
1210 '\n'
|
|
jpayne@68
|
1211 'New in version 3.5.\n',
|
|
jpayne@68
|
1212 'binary': 'Binary arithmetic operations\n'
|
|
jpayne@68
|
1213 '****************************\n'
|
|
jpayne@68
|
1214 '\n'
|
|
jpayne@68
|
1215 'The binary arithmetic operations have the conventional priority\n'
|
|
jpayne@68
|
1216 'levels. Note that some of these operations also apply to certain '
|
|
jpayne@68
|
1217 'non-\n'
|
|
jpayne@68
|
1218 'numeric types. Apart from the power operator, there are only two\n'
|
|
jpayne@68
|
1219 'levels, one for multiplicative operators and one for additive\n'
|
|
jpayne@68
|
1220 'operators:\n'
|
|
jpayne@68
|
1221 '\n'
|
|
jpayne@68
|
1222 ' m_expr ::= u_expr | m_expr "*" u_expr | m_expr "@" m_expr |\n'
|
|
jpayne@68
|
1223 ' m_expr "//" u_expr | m_expr "/" u_expr |\n'
|
|
jpayne@68
|
1224 ' m_expr "%" u_expr\n'
|
|
jpayne@68
|
1225 ' a_expr ::= m_expr | a_expr "+" m_expr | a_expr "-" m_expr\n'
|
|
jpayne@68
|
1226 '\n'
|
|
jpayne@68
|
1227 'The "*" (multiplication) operator yields the product of its '
|
|
jpayne@68
|
1228 'arguments.\n'
|
|
jpayne@68
|
1229 'The arguments must either both be numbers, or one argument must be '
|
|
jpayne@68
|
1230 'an\n'
|
|
jpayne@68
|
1231 'integer and the other must be a sequence. In the former case, the\n'
|
|
jpayne@68
|
1232 'numbers are converted to a common type and then multiplied '
|
|
jpayne@68
|
1233 'together.\n'
|
|
jpayne@68
|
1234 'In the latter case, sequence repetition is performed; a negative\n'
|
|
jpayne@68
|
1235 'repetition factor yields an empty sequence.\n'
|
|
jpayne@68
|
1236 '\n'
|
|
jpayne@68
|
1237 'The "@" (at) operator is intended to be used for matrix\n'
|
|
jpayne@68
|
1238 'multiplication. No builtin Python types implement this operator.\n'
|
|
jpayne@68
|
1239 '\n'
|
|
jpayne@68
|
1240 'New in version 3.5.\n'
|
|
jpayne@68
|
1241 '\n'
|
|
jpayne@68
|
1242 'The "/" (division) and "//" (floor division) operators yield the\n'
|
|
jpayne@68
|
1243 'quotient of their arguments. The numeric arguments are first\n'
|
|
jpayne@68
|
1244 'converted to a common type. Division of integers yields a float, '
|
|
jpayne@68
|
1245 'while\n'
|
|
jpayne@68
|
1246 'floor division of integers results in an integer; the result is '
|
|
jpayne@68
|
1247 'that\n'
|
|
jpayne@68
|
1248 'of mathematical division with the ‘floor’ function applied to the\n'
|
|
jpayne@68
|
1249 'result. Division by zero raises the "ZeroDivisionError" '
|
|
jpayne@68
|
1250 'exception.\n'
|
|
jpayne@68
|
1251 '\n'
|
|
jpayne@68
|
1252 'The "%" (modulo) operator yields the remainder from the division '
|
|
jpayne@68
|
1253 'of\n'
|
|
jpayne@68
|
1254 'the first argument by the second. The numeric arguments are '
|
|
jpayne@68
|
1255 'first\n'
|
|
jpayne@68
|
1256 'converted to a common type. A zero right argument raises the\n'
|
|
jpayne@68
|
1257 '"ZeroDivisionError" exception. The arguments may be floating '
|
|
jpayne@68
|
1258 'point\n'
|
|
jpayne@68
|
1259 'numbers, e.g., "3.14%0.7" equals "0.34" (since "3.14" equals '
|
|
jpayne@68
|
1260 '"4*0.7 +\n'
|
|
jpayne@68
|
1261 '0.34".) The modulo operator always yields a result with the same '
|
|
jpayne@68
|
1262 'sign\n'
|
|
jpayne@68
|
1263 'as its second operand (or zero); the absolute value of the result '
|
|
jpayne@68
|
1264 'is\n'
|
|
jpayne@68
|
1265 'strictly smaller than the absolute value of the second operand '
|
|
jpayne@68
|
1266 '[1].\n'
|
|
jpayne@68
|
1267 '\n'
|
|
jpayne@68
|
1268 'The floor division and modulo operators are connected by the '
|
|
jpayne@68
|
1269 'following\n'
|
|
jpayne@68
|
1270 'identity: "x == (x//y)*y + (x%y)". Floor division and modulo are '
|
|
jpayne@68
|
1271 'also\n'
|
|
jpayne@68
|
1272 'connected with the built-in function "divmod()": "divmod(x, y) ==\n'
|
|
jpayne@68
|
1273 '(x//y, x%y)". [2].\n'
|
|
jpayne@68
|
1274 '\n'
|
|
jpayne@68
|
1275 'In addition to performing the modulo operation on numbers, the '
|
|
jpayne@68
|
1276 '"%"\n'
|
|
jpayne@68
|
1277 'operator is also overloaded by string objects to perform '
|
|
jpayne@68
|
1278 'old-style\n'
|
|
jpayne@68
|
1279 'string formatting (also known as interpolation). The syntax for\n'
|
|
jpayne@68
|
1280 'string formatting is described in the Python Library Reference,\n'
|
|
jpayne@68
|
1281 'section printf-style String Formatting.\n'
|
|
jpayne@68
|
1282 '\n'
|
|
jpayne@68
|
1283 'The floor division operator, the modulo operator, and the '
|
|
jpayne@68
|
1284 '"divmod()"\n'
|
|
jpayne@68
|
1285 'function are not defined for complex numbers. Instead, convert to '
|
|
jpayne@68
|
1286 'a\n'
|
|
jpayne@68
|
1287 'floating point number using the "abs()" function if appropriate.\n'
|
|
jpayne@68
|
1288 '\n'
|
|
jpayne@68
|
1289 'The "+" (addition) operator yields the sum of its arguments. The\n'
|
|
jpayne@68
|
1290 'arguments must either both be numbers or both be sequences of the '
|
|
jpayne@68
|
1291 'same\n'
|
|
jpayne@68
|
1292 'type. In the former case, the numbers are converted to a common '
|
|
jpayne@68
|
1293 'type\n'
|
|
jpayne@68
|
1294 'and then added together. In the latter case, the sequences are\n'
|
|
jpayne@68
|
1295 'concatenated.\n'
|
|
jpayne@68
|
1296 '\n'
|
|
jpayne@68
|
1297 'The "-" (subtraction) operator yields the difference of its '
|
|
jpayne@68
|
1298 'arguments.\n'
|
|
jpayne@68
|
1299 'The numeric arguments are first converted to a common type.\n',
|
|
jpayne@68
|
1300 'bitwise': 'Binary bitwise operations\n'
|
|
jpayne@68
|
1301 '*************************\n'
|
|
jpayne@68
|
1302 '\n'
|
|
jpayne@68
|
1303 'Each of the three bitwise operations has a different priority '
|
|
jpayne@68
|
1304 'level:\n'
|
|
jpayne@68
|
1305 '\n'
|
|
jpayne@68
|
1306 ' and_expr ::= shift_expr | and_expr "&" shift_expr\n'
|
|
jpayne@68
|
1307 ' xor_expr ::= and_expr | xor_expr "^" and_expr\n'
|
|
jpayne@68
|
1308 ' or_expr ::= xor_expr | or_expr "|" xor_expr\n'
|
|
jpayne@68
|
1309 '\n'
|
|
jpayne@68
|
1310 'The "&" operator yields the bitwise AND of its arguments, which '
|
|
jpayne@68
|
1311 'must\n'
|
|
jpayne@68
|
1312 'be integers.\n'
|
|
jpayne@68
|
1313 '\n'
|
|
jpayne@68
|
1314 'The "^" operator yields the bitwise XOR (exclusive OR) of its\n'
|
|
jpayne@68
|
1315 'arguments, which must be integers.\n'
|
|
jpayne@68
|
1316 '\n'
|
|
jpayne@68
|
1317 'The "|" operator yields the bitwise (inclusive) OR of its '
|
|
jpayne@68
|
1318 'arguments,\n'
|
|
jpayne@68
|
1319 'which must be integers.\n',
|
|
jpayne@68
|
1320 'bltin-code-objects': 'Code Objects\n'
|
|
jpayne@68
|
1321 '************\n'
|
|
jpayne@68
|
1322 '\n'
|
|
jpayne@68
|
1323 'Code objects are used by the implementation to '
|
|
jpayne@68
|
1324 'represent “pseudo-\n'
|
|
jpayne@68
|
1325 'compiled” executable Python code such as a function '
|
|
jpayne@68
|
1326 'body. They differ\n'
|
|
jpayne@68
|
1327 'from function objects because they don’t contain a '
|
|
jpayne@68
|
1328 'reference to their\n'
|
|
jpayne@68
|
1329 'global execution environment. Code objects are '
|
|
jpayne@68
|
1330 'returned by the built-\n'
|
|
jpayne@68
|
1331 'in "compile()" function and can be extracted from '
|
|
jpayne@68
|
1332 'function objects\n'
|
|
jpayne@68
|
1333 'through their "__code__" attribute. See also the '
|
|
jpayne@68
|
1334 '"code" module.\n'
|
|
jpayne@68
|
1335 '\n'
|
|
jpayne@68
|
1336 'A code object can be executed or evaluated by passing '
|
|
jpayne@68
|
1337 'it (instead of a\n'
|
|
jpayne@68
|
1338 'source string) to the "exec()" or "eval()" built-in '
|
|
jpayne@68
|
1339 'functions.\n'
|
|
jpayne@68
|
1340 '\n'
|
|
jpayne@68
|
1341 'See The standard type hierarchy for more '
|
|
jpayne@68
|
1342 'information.\n',
|
|
jpayne@68
|
1343 'bltin-ellipsis-object': 'The Ellipsis Object\n'
|
|
jpayne@68
|
1344 '*******************\n'
|
|
jpayne@68
|
1345 '\n'
|
|
jpayne@68
|
1346 'This object is commonly used by slicing (see '
|
|
jpayne@68
|
1347 'Slicings). It supports\n'
|
|
jpayne@68
|
1348 'no special operations. There is exactly one '
|
|
jpayne@68
|
1349 'ellipsis object, named\n'
|
|
jpayne@68
|
1350 '"Ellipsis" (a built-in name). "type(Ellipsis)()" '
|
|
jpayne@68
|
1351 'produces the\n'
|
|
jpayne@68
|
1352 '"Ellipsis" singleton.\n'
|
|
jpayne@68
|
1353 '\n'
|
|
jpayne@68
|
1354 'It is written as "Ellipsis" or "...".\n',
|
|
jpayne@68
|
1355 'bltin-null-object': 'The Null Object\n'
|
|
jpayne@68
|
1356 '***************\n'
|
|
jpayne@68
|
1357 '\n'
|
|
jpayne@68
|
1358 'This object is returned by functions that don’t '
|
|
jpayne@68
|
1359 'explicitly return a\n'
|
|
jpayne@68
|
1360 'value. It supports no special operations. There is '
|
|
jpayne@68
|
1361 'exactly one null\n'
|
|
jpayne@68
|
1362 'object, named "None" (a built-in name). "type(None)()" '
|
|
jpayne@68
|
1363 'produces the\n'
|
|
jpayne@68
|
1364 'same singleton.\n'
|
|
jpayne@68
|
1365 '\n'
|
|
jpayne@68
|
1366 'It is written as "None".\n',
|
|
jpayne@68
|
1367 'bltin-type-objects': 'Type Objects\n'
|
|
jpayne@68
|
1368 '************\n'
|
|
jpayne@68
|
1369 '\n'
|
|
jpayne@68
|
1370 'Type objects represent the various object types. An '
|
|
jpayne@68
|
1371 'object’s type is\n'
|
|
jpayne@68
|
1372 'accessed by the built-in function "type()". There are '
|
|
jpayne@68
|
1373 'no special\n'
|
|
jpayne@68
|
1374 'operations on types. The standard module "types" '
|
|
jpayne@68
|
1375 'defines names for\n'
|
|
jpayne@68
|
1376 'all standard built-in types.\n'
|
|
jpayne@68
|
1377 '\n'
|
|
jpayne@68
|
1378 'Types are written like this: "<class \'int\'>".\n',
|
|
jpayne@68
|
1379 'booleans': 'Boolean operations\n'
|
|
jpayne@68
|
1380 '******************\n'
|
|
jpayne@68
|
1381 '\n'
|
|
jpayne@68
|
1382 ' or_test ::= and_test | or_test "or" and_test\n'
|
|
jpayne@68
|
1383 ' and_test ::= not_test | and_test "and" not_test\n'
|
|
jpayne@68
|
1384 ' not_test ::= comparison | "not" not_test\n'
|
|
jpayne@68
|
1385 '\n'
|
|
jpayne@68
|
1386 'In the context of Boolean operations, and also when expressions '
|
|
jpayne@68
|
1387 'are\n'
|
|
jpayne@68
|
1388 'used by control flow statements, the following values are '
|
|
jpayne@68
|
1389 'interpreted\n'
|
|
jpayne@68
|
1390 'as false: "False", "None", numeric zero of all types, and empty\n'
|
|
jpayne@68
|
1391 'strings and containers (including strings, tuples, lists,\n'
|
|
jpayne@68
|
1392 'dictionaries, sets and frozensets). All other values are '
|
|
jpayne@68
|
1393 'interpreted\n'
|
|
jpayne@68
|
1394 'as true. User-defined objects can customize their truth value '
|
|
jpayne@68
|
1395 'by\n'
|
|
jpayne@68
|
1396 'providing a "__bool__()" method.\n'
|
|
jpayne@68
|
1397 '\n'
|
|
jpayne@68
|
1398 'The operator "not" yields "True" if its argument is false, '
|
|
jpayne@68
|
1399 '"False"\n'
|
|
jpayne@68
|
1400 'otherwise.\n'
|
|
jpayne@68
|
1401 '\n'
|
|
jpayne@68
|
1402 'The expression "x and y" first evaluates *x*; if *x* is false, '
|
|
jpayne@68
|
1403 'its\n'
|
|
jpayne@68
|
1404 'value is returned; otherwise, *y* is evaluated and the resulting '
|
|
jpayne@68
|
1405 'value\n'
|
|
jpayne@68
|
1406 'is returned.\n'
|
|
jpayne@68
|
1407 '\n'
|
|
jpayne@68
|
1408 'The expression "x or y" first evaluates *x*; if *x* is true, its '
|
|
jpayne@68
|
1409 'value\n'
|
|
jpayne@68
|
1410 'is returned; otherwise, *y* is evaluated and the resulting value '
|
|
jpayne@68
|
1411 'is\n'
|
|
jpayne@68
|
1412 'returned.\n'
|
|
jpayne@68
|
1413 '\n'
|
|
jpayne@68
|
1414 'Note that neither "and" nor "or" restrict the value and type '
|
|
jpayne@68
|
1415 'they\n'
|
|
jpayne@68
|
1416 'return to "False" and "True", but rather return the last '
|
|
jpayne@68
|
1417 'evaluated\n'
|
|
jpayne@68
|
1418 'argument. This is sometimes useful, e.g., if "s" is a string '
|
|
jpayne@68
|
1419 'that\n'
|
|
jpayne@68
|
1420 'should be replaced by a default value if it is empty, the '
|
|
jpayne@68
|
1421 'expression\n'
|
|
jpayne@68
|
1422 '"s or \'foo\'" yields the desired value. Because "not" has to '
|
|
jpayne@68
|
1423 'create a\n'
|
|
jpayne@68
|
1424 'new value, it returns a boolean value regardless of the type of '
|
|
jpayne@68
|
1425 'its\n'
|
|
jpayne@68
|
1426 'argument (for example, "not \'foo\'" produces "False" rather '
|
|
jpayne@68
|
1427 'than "\'\'".)\n',
|
|
jpayne@68
|
1428 'break': 'The "break" statement\n'
|
|
jpayne@68
|
1429 '*********************\n'
|
|
jpayne@68
|
1430 '\n'
|
|
jpayne@68
|
1431 ' break_stmt ::= "break"\n'
|
|
jpayne@68
|
1432 '\n'
|
|
jpayne@68
|
1433 '"break" may only occur syntactically nested in a "for" or "while"\n'
|
|
jpayne@68
|
1434 'loop, but not nested in a function or class definition within that\n'
|
|
jpayne@68
|
1435 'loop.\n'
|
|
jpayne@68
|
1436 '\n'
|
|
jpayne@68
|
1437 'It terminates the nearest enclosing loop, skipping the optional '
|
|
jpayne@68
|
1438 '"else"\n'
|
|
jpayne@68
|
1439 'clause if the loop has one.\n'
|
|
jpayne@68
|
1440 '\n'
|
|
jpayne@68
|
1441 'If a "for" loop is terminated by "break", the loop control target\n'
|
|
jpayne@68
|
1442 'keeps its current value.\n'
|
|
jpayne@68
|
1443 '\n'
|
|
jpayne@68
|
1444 'When "break" passes control out of a "try" statement with a '
|
|
jpayne@68
|
1445 '"finally"\n'
|
|
jpayne@68
|
1446 'clause, that "finally" clause is executed before really leaving '
|
|
jpayne@68
|
1447 'the\n'
|
|
jpayne@68
|
1448 'loop.\n',
|
|
jpayne@68
|
1449 'callable-types': 'Emulating callable objects\n'
|
|
jpayne@68
|
1450 '**************************\n'
|
|
jpayne@68
|
1451 '\n'
|
|
jpayne@68
|
1452 'object.__call__(self[, args...])\n'
|
|
jpayne@68
|
1453 '\n'
|
|
jpayne@68
|
1454 ' Called when the instance is “called” as a function; if '
|
|
jpayne@68
|
1455 'this method\n'
|
|
jpayne@68
|
1456 ' is defined, "x(arg1, arg2, ...)" is a shorthand for\n'
|
|
jpayne@68
|
1457 ' "x.__call__(arg1, arg2, ...)".\n',
|
|
jpayne@68
|
1458 'calls': 'Calls\n'
|
|
jpayne@68
|
1459 '*****\n'
|
|
jpayne@68
|
1460 '\n'
|
|
jpayne@68
|
1461 'A call calls a callable object (e.g., a *function*) with a '
|
|
jpayne@68
|
1462 'possibly\n'
|
|
jpayne@68
|
1463 'empty series of *arguments*:\n'
|
|
jpayne@68
|
1464 '\n'
|
|
jpayne@68
|
1465 ' call ::= primary "(" [argument_list [","] | '
|
|
jpayne@68
|
1466 'comprehension] ")"\n'
|
|
jpayne@68
|
1467 ' argument_list ::= positional_arguments ["," '
|
|
jpayne@68
|
1468 'starred_and_keywords]\n'
|
|
jpayne@68
|
1469 ' ["," keywords_arguments]\n'
|
|
jpayne@68
|
1470 ' | starred_and_keywords ["," '
|
|
jpayne@68
|
1471 'keywords_arguments]\n'
|
|
jpayne@68
|
1472 ' | keywords_arguments\n'
|
|
jpayne@68
|
1473 ' positional_arguments ::= ["*"] expression ("," ["*"] '
|
|
jpayne@68
|
1474 'expression)*\n'
|
|
jpayne@68
|
1475 ' starred_and_keywords ::= ("*" expression | keyword_item)\n'
|
|
jpayne@68
|
1476 ' ("," "*" expression | "," '
|
|
jpayne@68
|
1477 'keyword_item)*\n'
|
|
jpayne@68
|
1478 ' keywords_arguments ::= (keyword_item | "**" expression)\n'
|
|
jpayne@68
|
1479 ' ("," keyword_item | "," "**" '
|
|
jpayne@68
|
1480 'expression)*\n'
|
|
jpayne@68
|
1481 ' keyword_item ::= identifier "=" expression\n'
|
|
jpayne@68
|
1482 '\n'
|
|
jpayne@68
|
1483 'An optional trailing comma may be present after the positional and\n'
|
|
jpayne@68
|
1484 'keyword arguments but does not affect the semantics.\n'
|
|
jpayne@68
|
1485 '\n'
|
|
jpayne@68
|
1486 'The primary must evaluate to a callable object (user-defined\n'
|
|
jpayne@68
|
1487 'functions, built-in functions, methods of built-in objects, class\n'
|
|
jpayne@68
|
1488 'objects, methods of class instances, and all objects having a\n'
|
|
jpayne@68
|
1489 '"__call__()" method are callable). All argument expressions are\n'
|
|
jpayne@68
|
1490 'evaluated before the call is attempted. Please refer to section\n'
|
|
jpayne@68
|
1491 'Function definitions for the syntax of formal *parameter* lists.\n'
|
|
jpayne@68
|
1492 '\n'
|
|
jpayne@68
|
1493 'If keyword arguments are present, they are first converted to\n'
|
|
jpayne@68
|
1494 'positional arguments, as follows. First, a list of unfilled slots '
|
|
jpayne@68
|
1495 'is\n'
|
|
jpayne@68
|
1496 'created for the formal parameters. If there are N positional\n'
|
|
jpayne@68
|
1497 'arguments, they are placed in the first N slots. Next, for each\n'
|
|
jpayne@68
|
1498 'keyword argument, the identifier is used to determine the\n'
|
|
jpayne@68
|
1499 'corresponding slot (if the identifier is the same as the first '
|
|
jpayne@68
|
1500 'formal\n'
|
|
jpayne@68
|
1501 'parameter name, the first slot is used, and so on). If the slot '
|
|
jpayne@68
|
1502 'is\n'
|
|
jpayne@68
|
1503 'already filled, a "TypeError" exception is raised. Otherwise, the\n'
|
|
jpayne@68
|
1504 'value of the argument is placed in the slot, filling it (even if '
|
|
jpayne@68
|
1505 'the\n'
|
|
jpayne@68
|
1506 'expression is "None", it fills the slot). When all arguments have\n'
|
|
jpayne@68
|
1507 'been processed, the slots that are still unfilled are filled with '
|
|
jpayne@68
|
1508 'the\n'
|
|
jpayne@68
|
1509 'corresponding default value from the function definition. '
|
|
jpayne@68
|
1510 '(Default\n'
|
|
jpayne@68
|
1511 'values are calculated, once, when the function is defined; thus, a\n'
|
|
jpayne@68
|
1512 'mutable object such as a list or dictionary used as default value '
|
|
jpayne@68
|
1513 'will\n'
|
|
jpayne@68
|
1514 'be shared by all calls that don’t specify an argument value for '
|
|
jpayne@68
|
1515 'the\n'
|
|
jpayne@68
|
1516 'corresponding slot; this should usually be avoided.) If there are '
|
|
jpayne@68
|
1517 'any\n'
|
|
jpayne@68
|
1518 'unfilled slots for which no default value is specified, a '
|
|
jpayne@68
|
1519 '"TypeError"\n'
|
|
jpayne@68
|
1520 'exception is raised. Otherwise, the list of filled slots is used '
|
|
jpayne@68
|
1521 'as\n'
|
|
jpayne@68
|
1522 'the argument list for the call.\n'
|
|
jpayne@68
|
1523 '\n'
|
|
jpayne@68
|
1524 '**CPython implementation detail:** An implementation may provide\n'
|
|
jpayne@68
|
1525 'built-in functions whose positional parameters do not have names, '
|
|
jpayne@68
|
1526 'even\n'
|
|
jpayne@68
|
1527 'if they are ‘named’ for the purpose of documentation, and which\n'
|
|
jpayne@68
|
1528 'therefore cannot be supplied by keyword. In CPython, this is the '
|
|
jpayne@68
|
1529 'case\n'
|
|
jpayne@68
|
1530 'for functions implemented in C that use "PyArg_ParseTuple()" to '
|
|
jpayne@68
|
1531 'parse\n'
|
|
jpayne@68
|
1532 'their arguments.\n'
|
|
jpayne@68
|
1533 '\n'
|
|
jpayne@68
|
1534 'If there are more positional arguments than there are formal '
|
|
jpayne@68
|
1535 'parameter\n'
|
|
jpayne@68
|
1536 'slots, a "TypeError" exception is raised, unless a formal '
|
|
jpayne@68
|
1537 'parameter\n'
|
|
jpayne@68
|
1538 'using the syntax "*identifier" is present; in this case, that '
|
|
jpayne@68
|
1539 'formal\n'
|
|
jpayne@68
|
1540 'parameter receives a tuple containing the excess positional '
|
|
jpayne@68
|
1541 'arguments\n'
|
|
jpayne@68
|
1542 '(or an empty tuple if there were no excess positional arguments).\n'
|
|
jpayne@68
|
1543 '\n'
|
|
jpayne@68
|
1544 'If any keyword argument does not correspond to a formal parameter\n'
|
|
jpayne@68
|
1545 'name, a "TypeError" exception is raised, unless a formal parameter\n'
|
|
jpayne@68
|
1546 'using the syntax "**identifier" is present; in this case, that '
|
|
jpayne@68
|
1547 'formal\n'
|
|
jpayne@68
|
1548 'parameter receives a dictionary containing the excess keyword\n'
|
|
jpayne@68
|
1549 'arguments (using the keywords as keys and the argument values as\n'
|
|
jpayne@68
|
1550 'corresponding values), or a (new) empty dictionary if there were '
|
|
jpayne@68
|
1551 'no\n'
|
|
jpayne@68
|
1552 'excess keyword arguments.\n'
|
|
jpayne@68
|
1553 '\n'
|
|
jpayne@68
|
1554 'If the syntax "*expression" appears in the function call, '
|
|
jpayne@68
|
1555 '"expression"\n'
|
|
jpayne@68
|
1556 'must evaluate to an *iterable*. Elements from these iterables are\n'
|
|
jpayne@68
|
1557 'treated as if they were additional positional arguments. For the '
|
|
jpayne@68
|
1558 'call\n'
|
|
jpayne@68
|
1559 '"f(x1, x2, *y, x3, x4)", if *y* evaluates to a sequence *y1*, …, '
|
|
jpayne@68
|
1560 '*yM*,\n'
|
|
jpayne@68
|
1561 'this is equivalent to a call with M+4 positional arguments *x1*, '
|
|
jpayne@68
|
1562 '*x2*,\n'
|
|
jpayne@68
|
1563 '*y1*, …, *yM*, *x3*, *x4*.\n'
|
|
jpayne@68
|
1564 '\n'
|
|
jpayne@68
|
1565 'A consequence of this is that although the "*expression" syntax '
|
|
jpayne@68
|
1566 'may\n'
|
|
jpayne@68
|
1567 'appear *after* explicit keyword arguments, it is processed '
|
|
jpayne@68
|
1568 '*before*\n'
|
|
jpayne@68
|
1569 'the keyword arguments (and any "**expression" arguments – see '
|
|
jpayne@68
|
1570 'below).\n'
|
|
jpayne@68
|
1571 'So:\n'
|
|
jpayne@68
|
1572 '\n'
|
|
jpayne@68
|
1573 ' >>> def f(a, b):\n'
|
|
jpayne@68
|
1574 ' ... print(a, b)\n'
|
|
jpayne@68
|
1575 ' ...\n'
|
|
jpayne@68
|
1576 ' >>> f(b=1, *(2,))\n'
|
|
jpayne@68
|
1577 ' 2 1\n'
|
|
jpayne@68
|
1578 ' >>> f(a=1, *(2,))\n'
|
|
jpayne@68
|
1579 ' Traceback (most recent call last):\n'
|
|
jpayne@68
|
1580 ' File "<stdin>", line 1, in <module>\n'
|
|
jpayne@68
|
1581 " TypeError: f() got multiple values for keyword argument 'a'\n"
|
|
jpayne@68
|
1582 ' >>> f(1, *(2,))\n'
|
|
jpayne@68
|
1583 ' 1 2\n'
|
|
jpayne@68
|
1584 '\n'
|
|
jpayne@68
|
1585 'It is unusual for both keyword arguments and the "*expression" '
|
|
jpayne@68
|
1586 'syntax\n'
|
|
jpayne@68
|
1587 'to be used in the same call, so in practice this confusion does '
|
|
jpayne@68
|
1588 'not\n'
|
|
jpayne@68
|
1589 'arise.\n'
|
|
jpayne@68
|
1590 '\n'
|
|
jpayne@68
|
1591 'If the syntax "**expression" appears in the function call,\n'
|
|
jpayne@68
|
1592 '"expression" must evaluate to a *mapping*, the contents of which '
|
|
jpayne@68
|
1593 'are\n'
|
|
jpayne@68
|
1594 'treated as additional keyword arguments. If a keyword is already\n'
|
|
jpayne@68
|
1595 'present (as an explicit keyword argument, or from another '
|
|
jpayne@68
|
1596 'unpacking),\n'
|
|
jpayne@68
|
1597 'a "TypeError" exception is raised.\n'
|
|
jpayne@68
|
1598 '\n'
|
|
jpayne@68
|
1599 'Formal parameters using the syntax "*identifier" or "**identifier"\n'
|
|
jpayne@68
|
1600 'cannot be used as positional argument slots or as keyword argument\n'
|
|
jpayne@68
|
1601 'names.\n'
|
|
jpayne@68
|
1602 '\n'
|
|
jpayne@68
|
1603 'Changed in version 3.5: Function calls accept any number of "*" '
|
|
jpayne@68
|
1604 'and\n'
|
|
jpayne@68
|
1605 '"**" unpackings, positional arguments may follow iterable '
|
|
jpayne@68
|
1606 'unpackings\n'
|
|
jpayne@68
|
1607 '("*"), and keyword arguments may follow dictionary unpackings '
|
|
jpayne@68
|
1608 '("**").\n'
|
|
jpayne@68
|
1609 'Originally proposed by **PEP 448**.\n'
|
|
jpayne@68
|
1610 '\n'
|
|
jpayne@68
|
1611 'A call always returns some value, possibly "None", unless it raises '
|
|
jpayne@68
|
1612 'an\n'
|
|
jpayne@68
|
1613 'exception. How this value is computed depends on the type of the\n'
|
|
jpayne@68
|
1614 'callable object.\n'
|
|
jpayne@68
|
1615 '\n'
|
|
jpayne@68
|
1616 'If it is—\n'
|
|
jpayne@68
|
1617 '\n'
|
|
jpayne@68
|
1618 'a user-defined function:\n'
|
|
jpayne@68
|
1619 ' The code block for the function is executed, passing it the\n'
|
|
jpayne@68
|
1620 ' argument list. The first thing the code block will do is bind '
|
|
jpayne@68
|
1621 'the\n'
|
|
jpayne@68
|
1622 ' formal parameters to the arguments; this is described in '
|
|
jpayne@68
|
1623 'section\n'
|
|
jpayne@68
|
1624 ' Function definitions. When the code block executes a "return"\n'
|
|
jpayne@68
|
1625 ' statement, this specifies the return value of the function '
|
|
jpayne@68
|
1626 'call.\n'
|
|
jpayne@68
|
1627 '\n'
|
|
jpayne@68
|
1628 'a built-in function or method:\n'
|
|
jpayne@68
|
1629 ' The result is up to the interpreter; see Built-in Functions for '
|
|
jpayne@68
|
1630 'the\n'
|
|
jpayne@68
|
1631 ' descriptions of built-in functions and methods.\n'
|
|
jpayne@68
|
1632 '\n'
|
|
jpayne@68
|
1633 'a class object:\n'
|
|
jpayne@68
|
1634 ' A new instance of that class is returned.\n'
|
|
jpayne@68
|
1635 '\n'
|
|
jpayne@68
|
1636 'a class instance method:\n'
|
|
jpayne@68
|
1637 ' The corresponding user-defined function is called, with an '
|
|
jpayne@68
|
1638 'argument\n'
|
|
jpayne@68
|
1639 ' list that is one longer than the argument list of the call: the\n'
|
|
jpayne@68
|
1640 ' instance becomes the first argument.\n'
|
|
jpayne@68
|
1641 '\n'
|
|
jpayne@68
|
1642 'a class instance:\n'
|
|
jpayne@68
|
1643 ' The class must define a "__call__()" method; the effect is then '
|
|
jpayne@68
|
1644 'the\n'
|
|
jpayne@68
|
1645 ' same as if that method was called.\n',
|
|
jpayne@68
|
1646 'class': 'Class definitions\n'
|
|
jpayne@68
|
1647 '*****************\n'
|
|
jpayne@68
|
1648 '\n'
|
|
jpayne@68
|
1649 'A class definition defines a class object (see section The '
|
|
jpayne@68
|
1650 'standard\n'
|
|
jpayne@68
|
1651 'type hierarchy):\n'
|
|
jpayne@68
|
1652 '\n'
|
|
jpayne@68
|
1653 ' classdef ::= [decorators] "class" classname [inheritance] ":" '
|
|
jpayne@68
|
1654 'suite\n'
|
|
jpayne@68
|
1655 ' inheritance ::= "(" [argument_list] ")"\n'
|
|
jpayne@68
|
1656 ' classname ::= identifier\n'
|
|
jpayne@68
|
1657 '\n'
|
|
jpayne@68
|
1658 'A class definition is an executable statement. The inheritance '
|
|
jpayne@68
|
1659 'list\n'
|
|
jpayne@68
|
1660 'usually gives a list of base classes (see Metaclasses for more\n'
|
|
jpayne@68
|
1661 'advanced uses), so each item in the list should evaluate to a '
|
|
jpayne@68
|
1662 'class\n'
|
|
jpayne@68
|
1663 'object which allows subclassing. Classes without an inheritance '
|
|
jpayne@68
|
1664 'list\n'
|
|
jpayne@68
|
1665 'inherit, by default, from the base class "object"; hence,\n'
|
|
jpayne@68
|
1666 '\n'
|
|
jpayne@68
|
1667 ' class Foo:\n'
|
|
jpayne@68
|
1668 ' pass\n'
|
|
jpayne@68
|
1669 '\n'
|
|
jpayne@68
|
1670 'is equivalent to\n'
|
|
jpayne@68
|
1671 '\n'
|
|
jpayne@68
|
1672 ' class Foo(object):\n'
|
|
jpayne@68
|
1673 ' pass\n'
|
|
jpayne@68
|
1674 '\n'
|
|
jpayne@68
|
1675 'The class’s suite is then executed in a new execution frame (see\n'
|
|
jpayne@68
|
1676 'Naming and binding), using a newly created local namespace and the\n'
|
|
jpayne@68
|
1677 'original global namespace. (Usually, the suite contains mostly\n'
|
|
jpayne@68
|
1678 'function definitions.) When the class’s suite finishes execution, '
|
|
jpayne@68
|
1679 'its\n'
|
|
jpayne@68
|
1680 'execution frame is discarded but its local namespace is saved. [3] '
|
|
jpayne@68
|
1681 'A\n'
|
|
jpayne@68
|
1682 'class object is then created using the inheritance list for the '
|
|
jpayne@68
|
1683 'base\n'
|
|
jpayne@68
|
1684 'classes and the saved local namespace for the attribute '
|
|
jpayne@68
|
1685 'dictionary.\n'
|
|
jpayne@68
|
1686 'The class name is bound to this class object in the original local\n'
|
|
jpayne@68
|
1687 'namespace.\n'
|
|
jpayne@68
|
1688 '\n'
|
|
jpayne@68
|
1689 'The order in which attributes are defined in the class body is\n'
|
|
jpayne@68
|
1690 'preserved in the new class’s "__dict__". Note that this is '
|
|
jpayne@68
|
1691 'reliable\n'
|
|
jpayne@68
|
1692 'only right after the class is created and only for classes that '
|
|
jpayne@68
|
1693 'were\n'
|
|
jpayne@68
|
1694 'defined using the definition syntax.\n'
|
|
jpayne@68
|
1695 '\n'
|
|
jpayne@68
|
1696 'Class creation can be customized heavily using metaclasses.\n'
|
|
jpayne@68
|
1697 '\n'
|
|
jpayne@68
|
1698 'Classes can also be decorated: just like when decorating '
|
|
jpayne@68
|
1699 'functions,\n'
|
|
jpayne@68
|
1700 '\n'
|
|
jpayne@68
|
1701 ' @f1(arg)\n'
|
|
jpayne@68
|
1702 ' @f2\n'
|
|
jpayne@68
|
1703 ' class Foo: pass\n'
|
|
jpayne@68
|
1704 '\n'
|
|
jpayne@68
|
1705 'is roughly equivalent to\n'
|
|
jpayne@68
|
1706 '\n'
|
|
jpayne@68
|
1707 ' class Foo: pass\n'
|
|
jpayne@68
|
1708 ' Foo = f1(arg)(f2(Foo))\n'
|
|
jpayne@68
|
1709 '\n'
|
|
jpayne@68
|
1710 'The evaluation rules for the decorator expressions are the same as '
|
|
jpayne@68
|
1711 'for\n'
|
|
jpayne@68
|
1712 'function decorators. The result is then bound to the class name.\n'
|
|
jpayne@68
|
1713 '\n'
|
|
jpayne@68
|
1714 '**Programmer’s note:** Variables defined in the class definition '
|
|
jpayne@68
|
1715 'are\n'
|
|
jpayne@68
|
1716 'class attributes; they are shared by instances. Instance '
|
|
jpayne@68
|
1717 'attributes\n'
|
|
jpayne@68
|
1718 'can be set in a method with "self.name = value". Both class and\n'
|
|
jpayne@68
|
1719 'instance attributes are accessible through the notation '
|
|
jpayne@68
|
1720 '“"self.name"”,\n'
|
|
jpayne@68
|
1721 'and an instance attribute hides a class attribute with the same '
|
|
jpayne@68
|
1722 'name\n'
|
|
jpayne@68
|
1723 'when accessed in this way. Class attributes can be used as '
|
|
jpayne@68
|
1724 'defaults\n'
|
|
jpayne@68
|
1725 'for instance attributes, but using mutable values there can lead '
|
|
jpayne@68
|
1726 'to\n'
|
|
jpayne@68
|
1727 'unexpected results. Descriptors can be used to create instance\n'
|
|
jpayne@68
|
1728 'variables with different implementation details.\n'
|
|
jpayne@68
|
1729 '\n'
|
|
jpayne@68
|
1730 'See also:\n'
|
|
jpayne@68
|
1731 '\n'
|
|
jpayne@68
|
1732 ' **PEP 3115** - Metaclasses in Python 3000\n'
|
|
jpayne@68
|
1733 ' The proposal that changed the declaration of metaclasses to '
|
|
jpayne@68
|
1734 'the\n'
|
|
jpayne@68
|
1735 ' current syntax, and the semantics for how classes with\n'
|
|
jpayne@68
|
1736 ' metaclasses are constructed.\n'
|
|
jpayne@68
|
1737 '\n'
|
|
jpayne@68
|
1738 ' **PEP 3129** - Class Decorators\n'
|
|
jpayne@68
|
1739 ' The proposal that added class decorators. Function and '
|
|
jpayne@68
|
1740 'method\n'
|
|
jpayne@68
|
1741 ' decorators were introduced in **PEP 318**.\n',
|
|
jpayne@68
|
1742 'comparisons': 'Comparisons\n'
|
|
jpayne@68
|
1743 '***********\n'
|
|
jpayne@68
|
1744 '\n'
|
|
jpayne@68
|
1745 'Unlike C, all comparison operations in Python have the same '
|
|
jpayne@68
|
1746 'priority,\n'
|
|
jpayne@68
|
1747 'which is lower than that of any arithmetic, shifting or '
|
|
jpayne@68
|
1748 'bitwise\n'
|
|
jpayne@68
|
1749 'operation. Also unlike C, expressions like "a < b < c" have '
|
|
jpayne@68
|
1750 'the\n'
|
|
jpayne@68
|
1751 'interpretation that is conventional in mathematics:\n'
|
|
jpayne@68
|
1752 '\n'
|
|
jpayne@68
|
1753 ' comparison ::= or_expr (comp_operator or_expr)*\n'
|
|
jpayne@68
|
1754 ' comp_operator ::= "<" | ">" | "==" | ">=" | "<=" | "!="\n'
|
|
jpayne@68
|
1755 ' | "is" ["not"] | ["not"] "in"\n'
|
|
jpayne@68
|
1756 '\n'
|
|
jpayne@68
|
1757 'Comparisons yield boolean values: "True" or "False".\n'
|
|
jpayne@68
|
1758 '\n'
|
|
jpayne@68
|
1759 'Comparisons can be chained arbitrarily, e.g., "x < y <= z" '
|
|
jpayne@68
|
1760 'is\n'
|
|
jpayne@68
|
1761 'equivalent to "x < y and y <= z", except that "y" is '
|
|
jpayne@68
|
1762 'evaluated only\n'
|
|
jpayne@68
|
1763 'once (but in both cases "z" is not evaluated at all when "x < '
|
|
jpayne@68
|
1764 'y" is\n'
|
|
jpayne@68
|
1765 'found to be false).\n'
|
|
jpayne@68
|
1766 '\n'
|
|
jpayne@68
|
1767 'Formally, if *a*, *b*, *c*, …, *y*, *z* are expressions and '
|
|
jpayne@68
|
1768 '*op1*,\n'
|
|
jpayne@68
|
1769 '*op2*, …, *opN* are comparison operators, then "a op1 b op2 c '
|
|
jpayne@68
|
1770 '... y\n'
|
|
jpayne@68
|
1771 'opN z" is equivalent to "a op1 b and b op2 c and ... y opN '
|
|
jpayne@68
|
1772 'z", except\n'
|
|
jpayne@68
|
1773 'that each expression is evaluated at most once.\n'
|
|
jpayne@68
|
1774 '\n'
|
|
jpayne@68
|
1775 'Note that "a op1 b op2 c" doesn’t imply any kind of '
|
|
jpayne@68
|
1776 'comparison between\n'
|
|
jpayne@68
|
1777 '*a* and *c*, so that, e.g., "x < y > z" is perfectly legal '
|
|
jpayne@68
|
1778 '(though\n'
|
|
jpayne@68
|
1779 'perhaps not pretty).\n'
|
|
jpayne@68
|
1780 '\n'
|
|
jpayne@68
|
1781 '\n'
|
|
jpayne@68
|
1782 'Value comparisons\n'
|
|
jpayne@68
|
1783 '=================\n'
|
|
jpayne@68
|
1784 '\n'
|
|
jpayne@68
|
1785 'The operators "<", ">", "==", ">=", "<=", and "!=" compare '
|
|
jpayne@68
|
1786 'the values\n'
|
|
jpayne@68
|
1787 'of two objects. The objects do not need to have the same '
|
|
jpayne@68
|
1788 'type.\n'
|
|
jpayne@68
|
1789 '\n'
|
|
jpayne@68
|
1790 'Chapter Objects, values and types states that objects have a '
|
|
jpayne@68
|
1791 'value (in\n'
|
|
jpayne@68
|
1792 'addition to type and identity). The value of an object is a '
|
|
jpayne@68
|
1793 'rather\n'
|
|
jpayne@68
|
1794 'abstract notion in Python: For example, there is no canonical '
|
|
jpayne@68
|
1795 'access\n'
|
|
jpayne@68
|
1796 'method for an object’s value. Also, there is no requirement '
|
|
jpayne@68
|
1797 'that the\n'
|
|
jpayne@68
|
1798 'value of an object should be constructed in a particular way, '
|
|
jpayne@68
|
1799 'e.g.\n'
|
|
jpayne@68
|
1800 'comprised of all its data attributes. Comparison operators '
|
|
jpayne@68
|
1801 'implement a\n'
|
|
jpayne@68
|
1802 'particular notion of what the value of an object is. One can '
|
|
jpayne@68
|
1803 'think of\n'
|
|
jpayne@68
|
1804 'them as defining the value of an object indirectly, by means '
|
|
jpayne@68
|
1805 'of their\n'
|
|
jpayne@68
|
1806 'comparison implementation.\n'
|
|
jpayne@68
|
1807 '\n'
|
|
jpayne@68
|
1808 'Because all types are (direct or indirect) subtypes of '
|
|
jpayne@68
|
1809 '"object", they\n'
|
|
jpayne@68
|
1810 'inherit the default comparison behavior from "object". Types '
|
|
jpayne@68
|
1811 'can\n'
|
|
jpayne@68
|
1812 'customize their comparison behavior by implementing *rich '
|
|
jpayne@68
|
1813 'comparison\n'
|
|
jpayne@68
|
1814 'methods* like "__lt__()", described in Basic customization.\n'
|
|
jpayne@68
|
1815 '\n'
|
|
jpayne@68
|
1816 'The default behavior for equality comparison ("==" and "!=") '
|
|
jpayne@68
|
1817 'is based\n'
|
|
jpayne@68
|
1818 'on the identity of the objects. Hence, equality comparison '
|
|
jpayne@68
|
1819 'of\n'
|
|
jpayne@68
|
1820 'instances with the same identity results in equality, and '
|
|
jpayne@68
|
1821 'equality\n'
|
|
jpayne@68
|
1822 'comparison of instances with different identities results in\n'
|
|
jpayne@68
|
1823 'inequality. A motivation for this default behavior is the '
|
|
jpayne@68
|
1824 'desire that\n'
|
|
jpayne@68
|
1825 'all objects should be reflexive (i.e. "x is y" implies "x == '
|
|
jpayne@68
|
1826 'y").\n'
|
|
jpayne@68
|
1827 '\n'
|
|
jpayne@68
|
1828 'A default order comparison ("<", ">", "<=", and ">=") is not '
|
|
jpayne@68
|
1829 'provided;\n'
|
|
jpayne@68
|
1830 'an attempt raises "TypeError". A motivation for this default '
|
|
jpayne@68
|
1831 'behavior\n'
|
|
jpayne@68
|
1832 'is the lack of a similar invariant as for equality.\n'
|
|
jpayne@68
|
1833 '\n'
|
|
jpayne@68
|
1834 'The behavior of the default equality comparison, that '
|
|
jpayne@68
|
1835 'instances with\n'
|
|
jpayne@68
|
1836 'different identities are always unequal, may be in contrast '
|
|
jpayne@68
|
1837 'to what\n'
|
|
jpayne@68
|
1838 'types will need that have a sensible definition of object '
|
|
jpayne@68
|
1839 'value and\n'
|
|
jpayne@68
|
1840 'value-based equality. Such types will need to customize '
|
|
jpayne@68
|
1841 'their\n'
|
|
jpayne@68
|
1842 'comparison behavior, and in fact, a number of built-in types '
|
|
jpayne@68
|
1843 'have done\n'
|
|
jpayne@68
|
1844 'that.\n'
|
|
jpayne@68
|
1845 '\n'
|
|
jpayne@68
|
1846 'The following list describes the comparison behavior of the '
|
|
jpayne@68
|
1847 'most\n'
|
|
jpayne@68
|
1848 'important built-in types.\n'
|
|
jpayne@68
|
1849 '\n'
|
|
jpayne@68
|
1850 '* Numbers of built-in numeric types (Numeric Types — int, '
|
|
jpayne@68
|
1851 'float,\n'
|
|
jpayne@68
|
1852 ' complex) and of the standard library types '
|
|
jpayne@68
|
1853 '"fractions.Fraction" and\n'
|
|
jpayne@68
|
1854 ' "decimal.Decimal" can be compared within and across their '
|
|
jpayne@68
|
1855 'types,\n'
|
|
jpayne@68
|
1856 ' with the restriction that complex numbers do not support '
|
|
jpayne@68
|
1857 'order\n'
|
|
jpayne@68
|
1858 ' comparison. Within the limits of the types involved, they '
|
|
jpayne@68
|
1859 'compare\n'
|
|
jpayne@68
|
1860 ' mathematically (algorithmically) correct without loss of '
|
|
jpayne@68
|
1861 'precision.\n'
|
|
jpayne@68
|
1862 '\n'
|
|
jpayne@68
|
1863 ' The not-a-number values "float(\'NaN\')" and '
|
|
jpayne@68
|
1864 '"decimal.Decimal(\'NaN\')"\n'
|
|
jpayne@68
|
1865 ' are special. Any ordered comparison of a number to a '
|
|
jpayne@68
|
1866 'not-a-number\n'
|
|
jpayne@68
|
1867 ' value is false. A counter-intuitive implication is that '
|
|
jpayne@68
|
1868 'not-a-number\n'
|
|
jpayne@68
|
1869 ' values are not equal to themselves. For example, if "x =\n'
|
|
jpayne@68
|
1870 ' float(\'NaN\')", "3 < x", "x < 3", "x == x", "x != x" are '
|
|
jpayne@68
|
1871 'all false.\n'
|
|
jpayne@68
|
1872 ' This behavior is compliant with IEEE 754.\n'
|
|
jpayne@68
|
1873 '\n'
|
|
jpayne@68
|
1874 '* "None" and "NotImplemented" are singletons. **PEP 8** '
|
|
jpayne@68
|
1875 'advises\n'
|
|
jpayne@68
|
1876 ' that comparisons for singletons should always be done with '
|
|
jpayne@68
|
1877 '"is" or\n'
|
|
jpayne@68
|
1878 ' "is not", never the equality operators.\n'
|
|
jpayne@68
|
1879 '\n'
|
|
jpayne@68
|
1880 '* Binary sequences (instances of "bytes" or "bytearray") can '
|
|
jpayne@68
|
1881 'be\n'
|
|
jpayne@68
|
1882 ' compared within and across their types. They compare\n'
|
|
jpayne@68
|
1883 ' lexicographically using the numeric values of their '
|
|
jpayne@68
|
1884 'elements.\n'
|
|
jpayne@68
|
1885 '\n'
|
|
jpayne@68
|
1886 '* Strings (instances of "str") compare lexicographically '
|
|
jpayne@68
|
1887 'using the\n'
|
|
jpayne@68
|
1888 ' numerical Unicode code points (the result of the built-in '
|
|
jpayne@68
|
1889 'function\n'
|
|
jpayne@68
|
1890 ' "ord()") of their characters. [3]\n'
|
|
jpayne@68
|
1891 '\n'
|
|
jpayne@68
|
1892 ' Strings and binary sequences cannot be directly compared.\n'
|
|
jpayne@68
|
1893 '\n'
|
|
jpayne@68
|
1894 '* Sequences (instances of "tuple", "list", or "range") can '
|
|
jpayne@68
|
1895 'be\n'
|
|
jpayne@68
|
1896 ' compared only within each of their types, with the '
|
|
jpayne@68
|
1897 'restriction that\n'
|
|
jpayne@68
|
1898 ' ranges do not support order comparison. Equality '
|
|
jpayne@68
|
1899 'comparison across\n'
|
|
jpayne@68
|
1900 ' these types results in inequality, and ordering comparison '
|
|
jpayne@68
|
1901 'across\n'
|
|
jpayne@68
|
1902 ' these types raises "TypeError".\n'
|
|
jpayne@68
|
1903 '\n'
|
|
jpayne@68
|
1904 ' Sequences compare lexicographically using comparison of\n'
|
|
jpayne@68
|
1905 ' corresponding elements. The built-in containers typically '
|
|
jpayne@68
|
1906 'assume\n'
|
|
jpayne@68
|
1907 ' identical objects are equal to themselves. That lets them '
|
|
jpayne@68
|
1908 'bypass\n'
|
|
jpayne@68
|
1909 ' equality tests for identical objects to improve performance '
|
|
jpayne@68
|
1910 'and to\n'
|
|
jpayne@68
|
1911 ' maintain their internal invariants.\n'
|
|
jpayne@68
|
1912 '\n'
|
|
jpayne@68
|
1913 ' Lexicographical comparison between built-in collections '
|
|
jpayne@68
|
1914 'works as\n'
|
|
jpayne@68
|
1915 ' follows:\n'
|
|
jpayne@68
|
1916 '\n'
|
|
jpayne@68
|
1917 ' * For two collections to compare equal, they must be of the '
|
|
jpayne@68
|
1918 'same\n'
|
|
jpayne@68
|
1919 ' type, have the same length, and each pair of '
|
|
jpayne@68
|
1920 'corresponding\n'
|
|
jpayne@68
|
1921 ' elements must compare equal (for example, "[1,2] == '
|
|
jpayne@68
|
1922 '(1,2)" is\n'
|
|
jpayne@68
|
1923 ' false because the type is not the same).\n'
|
|
jpayne@68
|
1924 '\n'
|
|
jpayne@68
|
1925 ' * Collections that support order comparison are ordered the '
|
|
jpayne@68
|
1926 'same\n'
|
|
jpayne@68
|
1927 ' as their first unequal elements (for example, "[1,2,x] <= '
|
|
jpayne@68
|
1928 '[1,2,y]"\n'
|
|
jpayne@68
|
1929 ' has the same value as "x <= y"). If a corresponding '
|
|
jpayne@68
|
1930 'element does\n'
|
|
jpayne@68
|
1931 ' not exist, the shorter collection is ordered first (for '
|
|
jpayne@68
|
1932 'example,\n'
|
|
jpayne@68
|
1933 ' "[1,2] < [1,2,3]" is true).\n'
|
|
jpayne@68
|
1934 '\n'
|
|
jpayne@68
|
1935 '* Mappings (instances of "dict") compare equal if and only if '
|
|
jpayne@68
|
1936 'they\n'
|
|
jpayne@68
|
1937 ' have equal *(key, value)* pairs. Equality comparison of the '
|
|
jpayne@68
|
1938 'keys and\n'
|
|
jpayne@68
|
1939 ' values enforces reflexivity.\n'
|
|
jpayne@68
|
1940 '\n'
|
|
jpayne@68
|
1941 ' Order comparisons ("<", ">", "<=", and ">=") raise '
|
|
jpayne@68
|
1942 '"TypeError".\n'
|
|
jpayne@68
|
1943 '\n'
|
|
jpayne@68
|
1944 '* Sets (instances of "set" or "frozenset") can be compared '
|
|
jpayne@68
|
1945 'within\n'
|
|
jpayne@68
|
1946 ' and across their types.\n'
|
|
jpayne@68
|
1947 '\n'
|
|
jpayne@68
|
1948 ' They define order comparison operators to mean subset and '
|
|
jpayne@68
|
1949 'superset\n'
|
|
jpayne@68
|
1950 ' tests. Those relations do not define total orderings (for '
|
|
jpayne@68
|
1951 'example,\n'
|
|
jpayne@68
|
1952 ' the two sets "{1,2}" and "{2,3}" are not equal, nor subsets '
|
|
jpayne@68
|
1953 'of one\n'
|
|
jpayne@68
|
1954 ' another, nor supersets of one another). Accordingly, sets '
|
|
jpayne@68
|
1955 'are not\n'
|
|
jpayne@68
|
1956 ' appropriate arguments for functions which depend on total '
|
|
jpayne@68
|
1957 'ordering\n'
|
|
jpayne@68
|
1958 ' (for example, "min()", "max()", and "sorted()" produce '
|
|
jpayne@68
|
1959 'undefined\n'
|
|
jpayne@68
|
1960 ' results given a list of sets as inputs).\n'
|
|
jpayne@68
|
1961 '\n'
|
|
jpayne@68
|
1962 ' Comparison of sets enforces reflexivity of its elements.\n'
|
|
jpayne@68
|
1963 '\n'
|
|
jpayne@68
|
1964 '* Most other built-in types have no comparison methods '
|
|
jpayne@68
|
1965 'implemented,\n'
|
|
jpayne@68
|
1966 ' so they inherit the default comparison behavior.\n'
|
|
jpayne@68
|
1967 '\n'
|
|
jpayne@68
|
1968 'User-defined classes that customize their comparison behavior '
|
|
jpayne@68
|
1969 'should\n'
|
|
jpayne@68
|
1970 'follow some consistency rules, if possible:\n'
|
|
jpayne@68
|
1971 '\n'
|
|
jpayne@68
|
1972 '* Equality comparison should be reflexive. In other words, '
|
|
jpayne@68
|
1973 'identical\n'
|
|
jpayne@68
|
1974 ' objects should compare equal:\n'
|
|
jpayne@68
|
1975 '\n'
|
|
jpayne@68
|
1976 ' "x is y" implies "x == y"\n'
|
|
jpayne@68
|
1977 '\n'
|
|
jpayne@68
|
1978 '* Comparison should be symmetric. In other words, the '
|
|
jpayne@68
|
1979 'following\n'
|
|
jpayne@68
|
1980 ' expressions should have the same result:\n'
|
|
jpayne@68
|
1981 '\n'
|
|
jpayne@68
|
1982 ' "x == y" and "y == x"\n'
|
|
jpayne@68
|
1983 '\n'
|
|
jpayne@68
|
1984 ' "x != y" and "y != x"\n'
|
|
jpayne@68
|
1985 '\n'
|
|
jpayne@68
|
1986 ' "x < y" and "y > x"\n'
|
|
jpayne@68
|
1987 '\n'
|
|
jpayne@68
|
1988 ' "x <= y" and "y >= x"\n'
|
|
jpayne@68
|
1989 '\n'
|
|
jpayne@68
|
1990 '* Comparison should be transitive. The following '
|
|
jpayne@68
|
1991 '(non-exhaustive)\n'
|
|
jpayne@68
|
1992 ' examples illustrate that:\n'
|
|
jpayne@68
|
1993 '\n'
|
|
jpayne@68
|
1994 ' "x > y and y > z" implies "x > z"\n'
|
|
jpayne@68
|
1995 '\n'
|
|
jpayne@68
|
1996 ' "x < y and y <= z" implies "x < z"\n'
|
|
jpayne@68
|
1997 '\n'
|
|
jpayne@68
|
1998 '* Inverse comparison should result in the boolean negation. '
|
|
jpayne@68
|
1999 'In other\n'
|
|
jpayne@68
|
2000 ' words, the following expressions should have the same '
|
|
jpayne@68
|
2001 'result:\n'
|
|
jpayne@68
|
2002 '\n'
|
|
jpayne@68
|
2003 ' "x == y" and "not x != y"\n'
|
|
jpayne@68
|
2004 '\n'
|
|
jpayne@68
|
2005 ' "x < y" and "not x >= y" (for total ordering)\n'
|
|
jpayne@68
|
2006 '\n'
|
|
jpayne@68
|
2007 ' "x > y" and "not x <= y" (for total ordering)\n'
|
|
jpayne@68
|
2008 '\n'
|
|
jpayne@68
|
2009 ' The last two expressions apply to totally ordered '
|
|
jpayne@68
|
2010 'collections (e.g.\n'
|
|
jpayne@68
|
2011 ' to sequences, but not to sets or mappings). See also the\n'
|
|
jpayne@68
|
2012 ' "total_ordering()" decorator.\n'
|
|
jpayne@68
|
2013 '\n'
|
|
jpayne@68
|
2014 '* The "hash()" result should be consistent with equality. '
|
|
jpayne@68
|
2015 'Objects\n'
|
|
jpayne@68
|
2016 ' that are equal should either have the same hash value, or '
|
|
jpayne@68
|
2017 'be marked\n'
|
|
jpayne@68
|
2018 ' as unhashable.\n'
|
|
jpayne@68
|
2019 '\n'
|
|
jpayne@68
|
2020 'Python does not enforce these consistency rules. In fact, '
|
|
jpayne@68
|
2021 'the\n'
|
|
jpayne@68
|
2022 'not-a-number values are an example for not following these '
|
|
jpayne@68
|
2023 'rules.\n'
|
|
jpayne@68
|
2024 '\n'
|
|
jpayne@68
|
2025 '\n'
|
|
jpayne@68
|
2026 'Membership test operations\n'
|
|
jpayne@68
|
2027 '==========================\n'
|
|
jpayne@68
|
2028 '\n'
|
|
jpayne@68
|
2029 'The operators "in" and "not in" test for membership. "x in '
|
|
jpayne@68
|
2030 's"\n'
|
|
jpayne@68
|
2031 'evaluates to "True" if *x* is a member of *s*, and "False" '
|
|
jpayne@68
|
2032 'otherwise.\n'
|
|
jpayne@68
|
2033 '"x not in s" returns the negation of "x in s". All built-in '
|
|
jpayne@68
|
2034 'sequences\n'
|
|
jpayne@68
|
2035 'and set types support this as well as dictionary, for which '
|
|
jpayne@68
|
2036 '"in" tests\n'
|
|
jpayne@68
|
2037 'whether the dictionary has a given key. For container types '
|
|
jpayne@68
|
2038 'such as\n'
|
|
jpayne@68
|
2039 'list, tuple, set, frozenset, dict, or collections.deque, the\n'
|
|
jpayne@68
|
2040 'expression "x in y" is equivalent to "any(x is e or x == e '
|
|
jpayne@68
|
2041 'for e in\n'
|
|
jpayne@68
|
2042 'y)".\n'
|
|
jpayne@68
|
2043 '\n'
|
|
jpayne@68
|
2044 'For the string and bytes types, "x in y" is "True" if and '
|
|
jpayne@68
|
2045 'only if *x*\n'
|
|
jpayne@68
|
2046 'is a substring of *y*. An equivalent test is "y.find(x) != '
|
|
jpayne@68
|
2047 '-1".\n'
|
|
jpayne@68
|
2048 'Empty strings are always considered to be a substring of any '
|
|
jpayne@68
|
2049 'other\n'
|
|
jpayne@68
|
2050 'string, so """ in "abc"" will return "True".\n'
|
|
jpayne@68
|
2051 '\n'
|
|
jpayne@68
|
2052 'For user-defined classes which define the "__contains__()" '
|
|
jpayne@68
|
2053 'method, "x\n'
|
|
jpayne@68
|
2054 'in y" returns "True" if "y.__contains__(x)" returns a true '
|
|
jpayne@68
|
2055 'value, and\n'
|
|
jpayne@68
|
2056 '"False" otherwise.\n'
|
|
jpayne@68
|
2057 '\n'
|
|
jpayne@68
|
2058 'For user-defined classes which do not define "__contains__()" '
|
|
jpayne@68
|
2059 'but do\n'
|
|
jpayne@68
|
2060 'define "__iter__()", "x in y" is "True" if some value "z", '
|
|
jpayne@68
|
2061 'for which\n'
|
|
jpayne@68
|
2062 'the expression "x is z or x == z" is true, is produced while '
|
|
jpayne@68
|
2063 'iterating\n'
|
|
jpayne@68
|
2064 'over "y". If an exception is raised during the iteration, it '
|
|
jpayne@68
|
2065 'is as if\n'
|
|
jpayne@68
|
2066 '"in" raised that exception.\n'
|
|
jpayne@68
|
2067 '\n'
|
|
jpayne@68
|
2068 'Lastly, the old-style iteration protocol is tried: if a class '
|
|
jpayne@68
|
2069 'defines\n'
|
|
jpayne@68
|
2070 '"__getitem__()", "x in y" is "True" if and only if there is a '
|
|
jpayne@68
|
2071 'non-\n'
|
|
jpayne@68
|
2072 'negative integer index *i* such that "x is y[i] or x == '
|
|
jpayne@68
|
2073 'y[i]", and no\n'
|
|
jpayne@68
|
2074 'lower integer index raises the "IndexError" exception. (If '
|
|
jpayne@68
|
2075 'any other\n'
|
|
jpayne@68
|
2076 'exception is raised, it is as if "in" raised that '
|
|
jpayne@68
|
2077 'exception).\n'
|
|
jpayne@68
|
2078 '\n'
|
|
jpayne@68
|
2079 'The operator "not in" is defined to have the inverse truth '
|
|
jpayne@68
|
2080 'value of\n'
|
|
jpayne@68
|
2081 '"in".\n'
|
|
jpayne@68
|
2082 '\n'
|
|
jpayne@68
|
2083 '\n'
|
|
jpayne@68
|
2084 'Identity comparisons\n'
|
|
jpayne@68
|
2085 '====================\n'
|
|
jpayne@68
|
2086 '\n'
|
|
jpayne@68
|
2087 'The operators "is" and "is not" test for an object’s '
|
|
jpayne@68
|
2088 'identity: "x is\n'
|
|
jpayne@68
|
2089 'y" is true if and only if *x* and *y* are the same object. '
|
|
jpayne@68
|
2090 'An\n'
|
|
jpayne@68
|
2091 'Object’s identity is determined using the "id()" function. '
|
|
jpayne@68
|
2092 '"x is not\n'
|
|
jpayne@68
|
2093 'y" yields the inverse truth value. [4]\n',
|
|
jpayne@68
|
2094 'compound': 'Compound statements\n'
|
|
jpayne@68
|
2095 '*******************\n'
|
|
jpayne@68
|
2096 '\n'
|
|
jpayne@68
|
2097 'Compound statements contain (groups of) other statements; they '
|
|
jpayne@68
|
2098 'affect\n'
|
|
jpayne@68
|
2099 'or control the execution of those other statements in some way. '
|
|
jpayne@68
|
2100 'In\n'
|
|
jpayne@68
|
2101 'general, compound statements span multiple lines, although in '
|
|
jpayne@68
|
2102 'simple\n'
|
|
jpayne@68
|
2103 'incarnations a whole compound statement may be contained in one '
|
|
jpayne@68
|
2104 'line.\n'
|
|
jpayne@68
|
2105 '\n'
|
|
jpayne@68
|
2106 'The "if", "while" and "for" statements implement traditional '
|
|
jpayne@68
|
2107 'control\n'
|
|
jpayne@68
|
2108 'flow constructs. "try" specifies exception handlers and/or '
|
|
jpayne@68
|
2109 'cleanup\n'
|
|
jpayne@68
|
2110 'code for a group of statements, while the "with" statement '
|
|
jpayne@68
|
2111 'allows the\n'
|
|
jpayne@68
|
2112 'execution of initialization and finalization code around a block '
|
|
jpayne@68
|
2113 'of\n'
|
|
jpayne@68
|
2114 'code. Function and class definitions are also syntactically '
|
|
jpayne@68
|
2115 'compound\n'
|
|
jpayne@68
|
2116 'statements.\n'
|
|
jpayne@68
|
2117 '\n'
|
|
jpayne@68
|
2118 'A compound statement consists of one or more ‘clauses.’ A '
|
|
jpayne@68
|
2119 'clause\n'
|
|
jpayne@68
|
2120 'consists of a header and a ‘suite.’ The clause headers of a\n'
|
|
jpayne@68
|
2121 'particular compound statement are all at the same indentation '
|
|
jpayne@68
|
2122 'level.\n'
|
|
jpayne@68
|
2123 'Each clause header begins with a uniquely identifying keyword '
|
|
jpayne@68
|
2124 'and ends\n'
|
|
jpayne@68
|
2125 'with a colon. A suite is a group of statements controlled by a\n'
|
|
jpayne@68
|
2126 'clause. A suite can be one or more semicolon-separated simple\n'
|
|
jpayne@68
|
2127 'statements on the same line as the header, following the '
|
|
jpayne@68
|
2128 'header’s\n'
|
|
jpayne@68
|
2129 'colon, or it can be one or more indented statements on '
|
|
jpayne@68
|
2130 'subsequent\n'
|
|
jpayne@68
|
2131 'lines. Only the latter form of a suite can contain nested '
|
|
jpayne@68
|
2132 'compound\n'
|
|
jpayne@68
|
2133 'statements; the following is illegal, mostly because it wouldn’t '
|
|
jpayne@68
|
2134 'be\n'
|
|
jpayne@68
|
2135 'clear to which "if" clause a following "else" clause would '
|
|
jpayne@68
|
2136 'belong:\n'
|
|
jpayne@68
|
2137 '\n'
|
|
jpayne@68
|
2138 ' if test1: if test2: print(x)\n'
|
|
jpayne@68
|
2139 '\n'
|
|
jpayne@68
|
2140 'Also note that the semicolon binds tighter than the colon in '
|
|
jpayne@68
|
2141 'this\n'
|
|
jpayne@68
|
2142 'context, so that in the following example, either all or none of '
|
|
jpayne@68
|
2143 'the\n'
|
|
jpayne@68
|
2144 '"print()" calls are executed:\n'
|
|
jpayne@68
|
2145 '\n'
|
|
jpayne@68
|
2146 ' if x < y < z: print(x); print(y); print(z)\n'
|
|
jpayne@68
|
2147 '\n'
|
|
jpayne@68
|
2148 'Summarizing:\n'
|
|
jpayne@68
|
2149 '\n'
|
|
jpayne@68
|
2150 ' compound_stmt ::= if_stmt\n'
|
|
jpayne@68
|
2151 ' | while_stmt\n'
|
|
jpayne@68
|
2152 ' | for_stmt\n'
|
|
jpayne@68
|
2153 ' | try_stmt\n'
|
|
jpayne@68
|
2154 ' | with_stmt\n'
|
|
jpayne@68
|
2155 ' | funcdef\n'
|
|
jpayne@68
|
2156 ' | classdef\n'
|
|
jpayne@68
|
2157 ' | async_with_stmt\n'
|
|
jpayne@68
|
2158 ' | async_for_stmt\n'
|
|
jpayne@68
|
2159 ' | async_funcdef\n'
|
|
jpayne@68
|
2160 ' suite ::= stmt_list NEWLINE | NEWLINE INDENT '
|
|
jpayne@68
|
2161 'statement+ DEDENT\n'
|
|
jpayne@68
|
2162 ' statement ::= stmt_list NEWLINE | compound_stmt\n'
|
|
jpayne@68
|
2163 ' stmt_list ::= simple_stmt (";" simple_stmt)* [";"]\n'
|
|
jpayne@68
|
2164 '\n'
|
|
jpayne@68
|
2165 'Note that statements always end in a "NEWLINE" possibly followed '
|
|
jpayne@68
|
2166 'by a\n'
|
|
jpayne@68
|
2167 '"DEDENT". Also note that optional continuation clauses always '
|
|
jpayne@68
|
2168 'begin\n'
|
|
jpayne@68
|
2169 'with a keyword that cannot start a statement, thus there are no\n'
|
|
jpayne@68
|
2170 'ambiguities (the ‘dangling "else"’ problem is solved in Python '
|
|
jpayne@68
|
2171 'by\n'
|
|
jpayne@68
|
2172 'requiring nested "if" statements to be indented).\n'
|
|
jpayne@68
|
2173 '\n'
|
|
jpayne@68
|
2174 'The formatting of the grammar rules in the following sections '
|
|
jpayne@68
|
2175 'places\n'
|
|
jpayne@68
|
2176 'each clause on a separate line for clarity.\n'
|
|
jpayne@68
|
2177 '\n'
|
|
jpayne@68
|
2178 '\n'
|
|
jpayne@68
|
2179 'The "if" statement\n'
|
|
jpayne@68
|
2180 '==================\n'
|
|
jpayne@68
|
2181 '\n'
|
|
jpayne@68
|
2182 'The "if" statement is used for conditional execution:\n'
|
|
jpayne@68
|
2183 '\n'
|
|
jpayne@68
|
2184 ' if_stmt ::= "if" expression ":" suite\n'
|
|
jpayne@68
|
2185 ' ("elif" expression ":" suite)*\n'
|
|
jpayne@68
|
2186 ' ["else" ":" suite]\n'
|
|
jpayne@68
|
2187 '\n'
|
|
jpayne@68
|
2188 'It selects exactly one of the suites by evaluating the '
|
|
jpayne@68
|
2189 'expressions one\n'
|
|
jpayne@68
|
2190 'by one until one is found to be true (see section Boolean '
|
|
jpayne@68
|
2191 'operations\n'
|
|
jpayne@68
|
2192 'for the definition of true and false); then that suite is '
|
|
jpayne@68
|
2193 'executed\n'
|
|
jpayne@68
|
2194 '(and no other part of the "if" statement is executed or '
|
|
jpayne@68
|
2195 'evaluated).\n'
|
|
jpayne@68
|
2196 'If all expressions are false, the suite of the "else" clause, '
|
|
jpayne@68
|
2197 'if\n'
|
|
jpayne@68
|
2198 'present, is executed.\n'
|
|
jpayne@68
|
2199 '\n'
|
|
jpayne@68
|
2200 '\n'
|
|
jpayne@68
|
2201 'The "while" statement\n'
|
|
jpayne@68
|
2202 '=====================\n'
|
|
jpayne@68
|
2203 '\n'
|
|
jpayne@68
|
2204 'The "while" statement is used for repeated execution as long as '
|
|
jpayne@68
|
2205 'an\n'
|
|
jpayne@68
|
2206 'expression is true:\n'
|
|
jpayne@68
|
2207 '\n'
|
|
jpayne@68
|
2208 ' while_stmt ::= "while" expression ":" suite\n'
|
|
jpayne@68
|
2209 ' ["else" ":" suite]\n'
|
|
jpayne@68
|
2210 '\n'
|
|
jpayne@68
|
2211 'This repeatedly tests the expression and, if it is true, '
|
|
jpayne@68
|
2212 'executes the\n'
|
|
jpayne@68
|
2213 'first suite; if the expression is false (which may be the first '
|
|
jpayne@68
|
2214 'time\n'
|
|
jpayne@68
|
2215 'it is tested) the suite of the "else" clause, if present, is '
|
|
jpayne@68
|
2216 'executed\n'
|
|
jpayne@68
|
2217 'and the loop terminates.\n'
|
|
jpayne@68
|
2218 '\n'
|
|
jpayne@68
|
2219 'A "break" statement executed in the first suite terminates the '
|
|
jpayne@68
|
2220 'loop\n'
|
|
jpayne@68
|
2221 'without executing the "else" clause’s suite. A "continue" '
|
|
jpayne@68
|
2222 'statement\n'
|
|
jpayne@68
|
2223 'executed in the first suite skips the rest of the suite and goes '
|
|
jpayne@68
|
2224 'back\n'
|
|
jpayne@68
|
2225 'to testing the expression.\n'
|
|
jpayne@68
|
2226 '\n'
|
|
jpayne@68
|
2227 '\n'
|
|
jpayne@68
|
2228 'The "for" statement\n'
|
|
jpayne@68
|
2229 '===================\n'
|
|
jpayne@68
|
2230 '\n'
|
|
jpayne@68
|
2231 'The "for" statement is used to iterate over the elements of a '
|
|
jpayne@68
|
2232 'sequence\n'
|
|
jpayne@68
|
2233 '(such as a string, tuple or list) or other iterable object:\n'
|
|
jpayne@68
|
2234 '\n'
|
|
jpayne@68
|
2235 ' for_stmt ::= "for" target_list "in" expression_list ":" '
|
|
jpayne@68
|
2236 'suite\n'
|
|
jpayne@68
|
2237 ' ["else" ":" suite]\n'
|
|
jpayne@68
|
2238 '\n'
|
|
jpayne@68
|
2239 'The expression list is evaluated once; it should yield an '
|
|
jpayne@68
|
2240 'iterable\n'
|
|
jpayne@68
|
2241 'object. An iterator is created for the result of the\n'
|
|
jpayne@68
|
2242 '"expression_list". The suite is then executed once for each '
|
|
jpayne@68
|
2243 'item\n'
|
|
jpayne@68
|
2244 'provided by the iterator, in the order returned by the '
|
|
jpayne@68
|
2245 'iterator. Each\n'
|
|
jpayne@68
|
2246 'item in turn is assigned to the target list using the standard '
|
|
jpayne@68
|
2247 'rules\n'
|
|
jpayne@68
|
2248 'for assignments (see Assignment statements), and then the suite '
|
|
jpayne@68
|
2249 'is\n'
|
|
jpayne@68
|
2250 'executed. When the items are exhausted (which is immediately '
|
|
jpayne@68
|
2251 'when the\n'
|
|
jpayne@68
|
2252 'sequence is empty or an iterator raises a "StopIteration" '
|
|
jpayne@68
|
2253 'exception),\n'
|
|
jpayne@68
|
2254 'the suite in the "else" clause, if present, is executed, and the '
|
|
jpayne@68
|
2255 'loop\n'
|
|
jpayne@68
|
2256 'terminates.\n'
|
|
jpayne@68
|
2257 '\n'
|
|
jpayne@68
|
2258 'A "break" statement executed in the first suite terminates the '
|
|
jpayne@68
|
2259 'loop\n'
|
|
jpayne@68
|
2260 'without executing the "else" clause’s suite. A "continue" '
|
|
jpayne@68
|
2261 'statement\n'
|
|
jpayne@68
|
2262 'executed in the first suite skips the rest of the suite and '
|
|
jpayne@68
|
2263 'continues\n'
|
|
jpayne@68
|
2264 'with the next item, or with the "else" clause if there is no '
|
|
jpayne@68
|
2265 'next\n'
|
|
jpayne@68
|
2266 'item.\n'
|
|
jpayne@68
|
2267 '\n'
|
|
jpayne@68
|
2268 'The for-loop makes assignments to the variables in the target '
|
|
jpayne@68
|
2269 'list.\n'
|
|
jpayne@68
|
2270 'This overwrites all previous assignments to those variables '
|
|
jpayne@68
|
2271 'including\n'
|
|
jpayne@68
|
2272 'those made in the suite of the for-loop:\n'
|
|
jpayne@68
|
2273 '\n'
|
|
jpayne@68
|
2274 ' for i in range(10):\n'
|
|
jpayne@68
|
2275 ' print(i)\n'
|
|
jpayne@68
|
2276 ' i = 5 # this will not affect the for-loop\n'
|
|
jpayne@68
|
2277 ' # because i will be overwritten with '
|
|
jpayne@68
|
2278 'the next\n'
|
|
jpayne@68
|
2279 ' # index in the range\n'
|
|
jpayne@68
|
2280 '\n'
|
|
jpayne@68
|
2281 'Names in the target list are not deleted when the loop is '
|
|
jpayne@68
|
2282 'finished,\n'
|
|
jpayne@68
|
2283 'but if the sequence is empty, they will not have been assigned '
|
|
jpayne@68
|
2284 'to at\n'
|
|
jpayne@68
|
2285 'all by the loop. Hint: the built-in function "range()" returns '
|
|
jpayne@68
|
2286 'an\n'
|
|
jpayne@68
|
2287 'iterator of integers suitable to emulate the effect of Pascal’s '
|
|
jpayne@68
|
2288 '"for i\n'
|
|
jpayne@68
|
2289 ':= a to b do"; e.g., "list(range(3))" returns the list "[0, 1, '
|
|
jpayne@68
|
2290 '2]".\n'
|
|
jpayne@68
|
2291 '\n'
|
|
jpayne@68
|
2292 'Note: There is a subtlety when the sequence is being modified by '
|
|
jpayne@68
|
2293 'the\n'
|
|
jpayne@68
|
2294 ' loop (this can only occur for mutable sequences, e.g. lists). '
|
|
jpayne@68
|
2295 'An\n'
|
|
jpayne@68
|
2296 ' internal counter is used to keep track of which item is used '
|
|
jpayne@68
|
2297 'next,\n'
|
|
jpayne@68
|
2298 ' and this is incremented on each iteration. When this counter '
|
|
jpayne@68
|
2299 'has\n'
|
|
jpayne@68
|
2300 ' reached the length of the sequence the loop terminates. This '
|
|
jpayne@68
|
2301 'means\n'
|
|
jpayne@68
|
2302 ' that if the suite deletes the current (or a previous) item '
|
|
jpayne@68
|
2303 'from the\n'
|
|
jpayne@68
|
2304 ' sequence, the next item will be skipped (since it gets the '
|
|
jpayne@68
|
2305 'index of\n'
|
|
jpayne@68
|
2306 ' the current item which has already been treated). Likewise, '
|
|
jpayne@68
|
2307 'if the\n'
|
|
jpayne@68
|
2308 ' suite inserts an item in the sequence before the current item, '
|
|
jpayne@68
|
2309 'the\n'
|
|
jpayne@68
|
2310 ' current item will be treated again the next time through the '
|
|
jpayne@68
|
2311 'loop.\n'
|
|
jpayne@68
|
2312 ' This can lead to nasty bugs that can be avoided by making a\n'
|
|
jpayne@68
|
2313 ' temporary copy using a slice of the whole sequence, e.g.,\n'
|
|
jpayne@68
|
2314 '\n'
|
|
jpayne@68
|
2315 ' for x in a[:]:\n'
|
|
jpayne@68
|
2316 ' if x < 0: a.remove(x)\n'
|
|
jpayne@68
|
2317 '\n'
|
|
jpayne@68
|
2318 '\n'
|
|
jpayne@68
|
2319 'The "try" statement\n'
|
|
jpayne@68
|
2320 '===================\n'
|
|
jpayne@68
|
2321 '\n'
|
|
jpayne@68
|
2322 'The "try" statement specifies exception handlers and/or cleanup '
|
|
jpayne@68
|
2323 'code\n'
|
|
jpayne@68
|
2324 'for a group of statements:\n'
|
|
jpayne@68
|
2325 '\n'
|
|
jpayne@68
|
2326 ' try_stmt ::= try1_stmt | try2_stmt\n'
|
|
jpayne@68
|
2327 ' try1_stmt ::= "try" ":" suite\n'
|
|
jpayne@68
|
2328 ' ("except" [expression ["as" identifier]] ":" '
|
|
jpayne@68
|
2329 'suite)+\n'
|
|
jpayne@68
|
2330 ' ["else" ":" suite]\n'
|
|
jpayne@68
|
2331 ' ["finally" ":" suite]\n'
|
|
jpayne@68
|
2332 ' try2_stmt ::= "try" ":" suite\n'
|
|
jpayne@68
|
2333 ' "finally" ":" suite\n'
|
|
jpayne@68
|
2334 '\n'
|
|
jpayne@68
|
2335 'The "except" clause(s) specify one or more exception handlers. '
|
|
jpayne@68
|
2336 'When no\n'
|
|
jpayne@68
|
2337 'exception occurs in the "try" clause, no exception handler is\n'
|
|
jpayne@68
|
2338 'executed. When an exception occurs in the "try" suite, a search '
|
|
jpayne@68
|
2339 'for an\n'
|
|
jpayne@68
|
2340 'exception handler is started. This search inspects the except '
|
|
jpayne@68
|
2341 'clauses\n'
|
|
jpayne@68
|
2342 'in turn until one is found that matches the exception. An '
|
|
jpayne@68
|
2343 'expression-\n'
|
|
jpayne@68
|
2344 'less except clause, if present, must be last; it matches any\n'
|
|
jpayne@68
|
2345 'exception. For an except clause with an expression, that '
|
|
jpayne@68
|
2346 'expression\n'
|
|
jpayne@68
|
2347 'is evaluated, and the clause matches the exception if the '
|
|
jpayne@68
|
2348 'resulting\n'
|
|
jpayne@68
|
2349 'object is “compatible” with the exception. An object is '
|
|
jpayne@68
|
2350 'compatible\n'
|
|
jpayne@68
|
2351 'with an exception if it is the class or a base class of the '
|
|
jpayne@68
|
2352 'exception\n'
|
|
jpayne@68
|
2353 'object or a tuple containing an item compatible with the '
|
|
jpayne@68
|
2354 'exception.\n'
|
|
jpayne@68
|
2355 '\n'
|
|
jpayne@68
|
2356 'If no except clause matches the exception, the search for an '
|
|
jpayne@68
|
2357 'exception\n'
|
|
jpayne@68
|
2358 'handler continues in the surrounding code and on the invocation '
|
|
jpayne@68
|
2359 'stack.\n'
|
|
jpayne@68
|
2360 '[1]\n'
|
|
jpayne@68
|
2361 '\n'
|
|
jpayne@68
|
2362 'If the evaluation of an expression in the header of an except '
|
|
jpayne@68
|
2363 'clause\n'
|
|
jpayne@68
|
2364 'raises an exception, the original search for a handler is '
|
|
jpayne@68
|
2365 'canceled and\n'
|
|
jpayne@68
|
2366 'a search starts for the new exception in the surrounding code '
|
|
jpayne@68
|
2367 'and on\n'
|
|
jpayne@68
|
2368 'the call stack (it is treated as if the entire "try" statement '
|
|
jpayne@68
|
2369 'raised\n'
|
|
jpayne@68
|
2370 'the exception).\n'
|
|
jpayne@68
|
2371 '\n'
|
|
jpayne@68
|
2372 'When a matching except clause is found, the exception is '
|
|
jpayne@68
|
2373 'assigned to\n'
|
|
jpayne@68
|
2374 'the target specified after the "as" keyword in that except '
|
|
jpayne@68
|
2375 'clause, if\n'
|
|
jpayne@68
|
2376 'present, and the except clause’s suite is executed. All except\n'
|
|
jpayne@68
|
2377 'clauses must have an executable block. When the end of this '
|
|
jpayne@68
|
2378 'block is\n'
|
|
jpayne@68
|
2379 'reached, execution continues normally after the entire try '
|
|
jpayne@68
|
2380 'statement.\n'
|
|
jpayne@68
|
2381 '(This means that if two nested handlers exist for the same '
|
|
jpayne@68
|
2382 'exception,\n'
|
|
jpayne@68
|
2383 'and the exception occurs in the try clause of the inner handler, '
|
|
jpayne@68
|
2384 'the\n'
|
|
jpayne@68
|
2385 'outer handler will not handle the exception.)\n'
|
|
jpayne@68
|
2386 '\n'
|
|
jpayne@68
|
2387 'When an exception has been assigned using "as target", it is '
|
|
jpayne@68
|
2388 'cleared\n'
|
|
jpayne@68
|
2389 'at the end of the except clause. This is as if\n'
|
|
jpayne@68
|
2390 '\n'
|
|
jpayne@68
|
2391 ' except E as N:\n'
|
|
jpayne@68
|
2392 ' foo\n'
|
|
jpayne@68
|
2393 '\n'
|
|
jpayne@68
|
2394 'was translated to\n'
|
|
jpayne@68
|
2395 '\n'
|
|
jpayne@68
|
2396 ' except E as N:\n'
|
|
jpayne@68
|
2397 ' try:\n'
|
|
jpayne@68
|
2398 ' foo\n'
|
|
jpayne@68
|
2399 ' finally:\n'
|
|
jpayne@68
|
2400 ' del N\n'
|
|
jpayne@68
|
2401 '\n'
|
|
jpayne@68
|
2402 'This means the exception must be assigned to a different name to '
|
|
jpayne@68
|
2403 'be\n'
|
|
jpayne@68
|
2404 'able to refer to it after the except clause. Exceptions are '
|
|
jpayne@68
|
2405 'cleared\n'
|
|
jpayne@68
|
2406 'because with the traceback attached to them, they form a '
|
|
jpayne@68
|
2407 'reference\n'
|
|
jpayne@68
|
2408 'cycle with the stack frame, keeping all locals in that frame '
|
|
jpayne@68
|
2409 'alive\n'
|
|
jpayne@68
|
2410 'until the next garbage collection occurs.\n'
|
|
jpayne@68
|
2411 '\n'
|
|
jpayne@68
|
2412 'Before an except clause’s suite is executed, details about the\n'
|
|
jpayne@68
|
2413 'exception are stored in the "sys" module and can be accessed '
|
|
jpayne@68
|
2414 'via\n'
|
|
jpayne@68
|
2415 '"sys.exc_info()". "sys.exc_info()" returns a 3-tuple consisting '
|
|
jpayne@68
|
2416 'of the\n'
|
|
jpayne@68
|
2417 'exception class, the exception instance and a traceback object '
|
|
jpayne@68
|
2418 '(see\n'
|
|
jpayne@68
|
2419 'section The standard type hierarchy) identifying the point in '
|
|
jpayne@68
|
2420 'the\n'
|
|
jpayne@68
|
2421 'program where the exception occurred. "sys.exc_info()" values '
|
|
jpayne@68
|
2422 'are\n'
|
|
jpayne@68
|
2423 'restored to their previous values (before the call) when '
|
|
jpayne@68
|
2424 'returning\n'
|
|
jpayne@68
|
2425 'from a function that handled an exception.\n'
|
|
jpayne@68
|
2426 '\n'
|
|
jpayne@68
|
2427 'The optional "else" clause is executed if the control flow '
|
|
jpayne@68
|
2428 'leaves the\n'
|
|
jpayne@68
|
2429 '"try" suite, no exception was raised, and no "return", '
|
|
jpayne@68
|
2430 '"continue", or\n'
|
|
jpayne@68
|
2431 '"break" statement was executed. Exceptions in the "else" clause '
|
|
jpayne@68
|
2432 'are\n'
|
|
jpayne@68
|
2433 'not handled by the preceding "except" clauses.\n'
|
|
jpayne@68
|
2434 '\n'
|
|
jpayne@68
|
2435 'If "finally" is present, it specifies a ‘cleanup’ handler. The '
|
|
jpayne@68
|
2436 '"try"\n'
|
|
jpayne@68
|
2437 'clause is executed, including any "except" and "else" clauses. '
|
|
jpayne@68
|
2438 'If an\n'
|
|
jpayne@68
|
2439 'exception occurs in any of the clauses and is not handled, the\n'
|
|
jpayne@68
|
2440 'exception is temporarily saved. The "finally" clause is '
|
|
jpayne@68
|
2441 'executed. If\n'
|
|
jpayne@68
|
2442 'there is a saved exception it is re-raised at the end of the '
|
|
jpayne@68
|
2443 '"finally"\n'
|
|
jpayne@68
|
2444 'clause. If the "finally" clause raises another exception, the '
|
|
jpayne@68
|
2445 'saved\n'
|
|
jpayne@68
|
2446 'exception is set as the context of the new exception. If the '
|
|
jpayne@68
|
2447 '"finally"\n'
|
|
jpayne@68
|
2448 'clause executes a "return", "break" or "continue" statement, the '
|
|
jpayne@68
|
2449 'saved\n'
|
|
jpayne@68
|
2450 'exception is discarded:\n'
|
|
jpayne@68
|
2451 '\n'
|
|
jpayne@68
|
2452 ' >>> def f():\n'
|
|
jpayne@68
|
2453 ' ... try:\n'
|
|
jpayne@68
|
2454 ' ... 1/0\n'
|
|
jpayne@68
|
2455 ' ... finally:\n'
|
|
jpayne@68
|
2456 ' ... return 42\n'
|
|
jpayne@68
|
2457 ' ...\n'
|
|
jpayne@68
|
2458 ' >>> f()\n'
|
|
jpayne@68
|
2459 ' 42\n'
|
|
jpayne@68
|
2460 '\n'
|
|
jpayne@68
|
2461 'The exception information is not available to the program '
|
|
jpayne@68
|
2462 'during\n'
|
|
jpayne@68
|
2463 'execution of the "finally" clause.\n'
|
|
jpayne@68
|
2464 '\n'
|
|
jpayne@68
|
2465 'When a "return", "break" or "continue" statement is executed in '
|
|
jpayne@68
|
2466 'the\n'
|
|
jpayne@68
|
2467 '"try" suite of a "try"…"finally" statement, the "finally" clause '
|
|
jpayne@68
|
2468 'is\n'
|
|
jpayne@68
|
2469 'also executed ‘on the way out.’\n'
|
|
jpayne@68
|
2470 '\n'
|
|
jpayne@68
|
2471 'The return value of a function is determined by the last '
|
|
jpayne@68
|
2472 '"return"\n'
|
|
jpayne@68
|
2473 'statement executed. Since the "finally" clause always executes, '
|
|
jpayne@68
|
2474 'a\n'
|
|
jpayne@68
|
2475 '"return" statement executed in the "finally" clause will always '
|
|
jpayne@68
|
2476 'be the\n'
|
|
jpayne@68
|
2477 'last one executed:\n'
|
|
jpayne@68
|
2478 '\n'
|
|
jpayne@68
|
2479 ' >>> def foo():\n'
|
|
jpayne@68
|
2480 ' ... try:\n'
|
|
jpayne@68
|
2481 " ... return 'try'\n"
|
|
jpayne@68
|
2482 ' ... finally:\n'
|
|
jpayne@68
|
2483 " ... return 'finally'\n"
|
|
jpayne@68
|
2484 ' ...\n'
|
|
jpayne@68
|
2485 ' >>> foo()\n'
|
|
jpayne@68
|
2486 " 'finally'\n"
|
|
jpayne@68
|
2487 '\n'
|
|
jpayne@68
|
2488 'Additional information on exceptions can be found in section\n'
|
|
jpayne@68
|
2489 'Exceptions, and information on using the "raise" statement to '
|
|
jpayne@68
|
2490 'generate\n'
|
|
jpayne@68
|
2491 'exceptions may be found in section The raise statement.\n'
|
|
jpayne@68
|
2492 '\n'
|
|
jpayne@68
|
2493 'Changed in version 3.8: Prior to Python 3.8, a "continue" '
|
|
jpayne@68
|
2494 'statement\n'
|
|
jpayne@68
|
2495 'was illegal in the "finally" clause due to a problem with the\n'
|
|
jpayne@68
|
2496 'implementation.\n'
|
|
jpayne@68
|
2497 '\n'
|
|
jpayne@68
|
2498 '\n'
|
|
jpayne@68
|
2499 'The "with" statement\n'
|
|
jpayne@68
|
2500 '====================\n'
|
|
jpayne@68
|
2501 '\n'
|
|
jpayne@68
|
2502 'The "with" statement is used to wrap the execution of a block '
|
|
jpayne@68
|
2503 'with\n'
|
|
jpayne@68
|
2504 'methods defined by a context manager (see section With '
|
|
jpayne@68
|
2505 'Statement\n'
|
|
jpayne@68
|
2506 'Context Managers). This allows common "try"…"except"…"finally" '
|
|
jpayne@68
|
2507 'usage\n'
|
|
jpayne@68
|
2508 'patterns to be encapsulated for convenient reuse.\n'
|
|
jpayne@68
|
2509 '\n'
|
|
jpayne@68
|
2510 ' with_stmt ::= "with" with_item ("," with_item)* ":" suite\n'
|
|
jpayne@68
|
2511 ' with_item ::= expression ["as" target]\n'
|
|
jpayne@68
|
2512 '\n'
|
|
jpayne@68
|
2513 'The execution of the "with" statement with one “item” proceeds '
|
|
jpayne@68
|
2514 'as\n'
|
|
jpayne@68
|
2515 'follows:\n'
|
|
jpayne@68
|
2516 '\n'
|
|
jpayne@68
|
2517 '1. The context expression (the expression given in the '
|
|
jpayne@68
|
2518 '"with_item")\n'
|
|
jpayne@68
|
2519 ' is evaluated to obtain a context manager.\n'
|
|
jpayne@68
|
2520 '\n'
|
|
jpayne@68
|
2521 '2. The context manager’s "__exit__()" is loaded for later use.\n'
|
|
jpayne@68
|
2522 '\n'
|
|
jpayne@68
|
2523 '3. The context manager’s "__enter__()" method is invoked.\n'
|
|
jpayne@68
|
2524 '\n'
|
|
jpayne@68
|
2525 '4. If a target was included in the "with" statement, the return\n'
|
|
jpayne@68
|
2526 ' value from "__enter__()" is assigned to it.\n'
|
|
jpayne@68
|
2527 '\n'
|
|
jpayne@68
|
2528 ' Note: The "with" statement guarantees that if the '
|
|
jpayne@68
|
2529 '"__enter__()"\n'
|
|
jpayne@68
|
2530 ' method returns without an error, then "__exit__()" will '
|
|
jpayne@68
|
2531 'always be\n'
|
|
jpayne@68
|
2532 ' called. Thus, if an error occurs during the assignment to '
|
|
jpayne@68
|
2533 'the\n'
|
|
jpayne@68
|
2534 ' target list, it will be treated the same as an error '
|
|
jpayne@68
|
2535 'occurring\n'
|
|
jpayne@68
|
2536 ' within the suite would be. See step 6 below.\n'
|
|
jpayne@68
|
2537 '\n'
|
|
jpayne@68
|
2538 '5. The suite is executed.\n'
|
|
jpayne@68
|
2539 '\n'
|
|
jpayne@68
|
2540 '6. The context manager’s "__exit__()" method is invoked. If an\n'
|
|
jpayne@68
|
2541 ' exception caused the suite to be exited, its type, value, '
|
|
jpayne@68
|
2542 'and\n'
|
|
jpayne@68
|
2543 ' traceback are passed as arguments to "__exit__()". Otherwise, '
|
|
jpayne@68
|
2544 'three\n'
|
|
jpayne@68
|
2545 ' "None" arguments are supplied.\n'
|
|
jpayne@68
|
2546 '\n'
|
|
jpayne@68
|
2547 ' If the suite was exited due to an exception, and the return '
|
|
jpayne@68
|
2548 'value\n'
|
|
jpayne@68
|
2549 ' from the "__exit__()" method was false, the exception is '
|
|
jpayne@68
|
2550 'reraised.\n'
|
|
jpayne@68
|
2551 ' If the return value was true, the exception is suppressed, '
|
|
jpayne@68
|
2552 'and\n'
|
|
jpayne@68
|
2553 ' execution continues with the statement following the "with"\n'
|
|
jpayne@68
|
2554 ' statement.\n'
|
|
jpayne@68
|
2555 '\n'
|
|
jpayne@68
|
2556 ' If the suite was exited for any reason other than an '
|
|
jpayne@68
|
2557 'exception, the\n'
|
|
jpayne@68
|
2558 ' return value from "__exit__()" is ignored, and execution '
|
|
jpayne@68
|
2559 'proceeds\n'
|
|
jpayne@68
|
2560 ' at the normal location for the kind of exit that was taken.\n'
|
|
jpayne@68
|
2561 '\n'
|
|
jpayne@68
|
2562 'With more than one item, the context managers are processed as '
|
|
jpayne@68
|
2563 'if\n'
|
|
jpayne@68
|
2564 'multiple "with" statements were nested:\n'
|
|
jpayne@68
|
2565 '\n'
|
|
jpayne@68
|
2566 ' with A() as a, B() as b:\n'
|
|
jpayne@68
|
2567 ' suite\n'
|
|
jpayne@68
|
2568 '\n'
|
|
jpayne@68
|
2569 'is equivalent to\n'
|
|
jpayne@68
|
2570 '\n'
|
|
jpayne@68
|
2571 ' with A() as a:\n'
|
|
jpayne@68
|
2572 ' with B() as b:\n'
|
|
jpayne@68
|
2573 ' suite\n'
|
|
jpayne@68
|
2574 '\n'
|
|
jpayne@68
|
2575 'Changed in version 3.1: Support for multiple context '
|
|
jpayne@68
|
2576 'expressions.\n'
|
|
jpayne@68
|
2577 '\n'
|
|
jpayne@68
|
2578 'See also:\n'
|
|
jpayne@68
|
2579 '\n'
|
|
jpayne@68
|
2580 ' **PEP 343** - The “with” statement\n'
|
|
jpayne@68
|
2581 ' The specification, background, and examples for the Python '
|
|
jpayne@68
|
2582 '"with"\n'
|
|
jpayne@68
|
2583 ' statement.\n'
|
|
jpayne@68
|
2584 '\n'
|
|
jpayne@68
|
2585 '\n'
|
|
jpayne@68
|
2586 'Function definitions\n'
|
|
jpayne@68
|
2587 '====================\n'
|
|
jpayne@68
|
2588 '\n'
|
|
jpayne@68
|
2589 'A function definition defines a user-defined function object '
|
|
jpayne@68
|
2590 '(see\n'
|
|
jpayne@68
|
2591 'section The standard type hierarchy):\n'
|
|
jpayne@68
|
2592 '\n'
|
|
jpayne@68
|
2593 ' funcdef ::= [decorators] "def" funcname "(" '
|
|
jpayne@68
|
2594 '[parameter_list] ")"\n'
|
|
jpayne@68
|
2595 ' ["->" expression] ":" suite\n'
|
|
jpayne@68
|
2596 ' decorators ::= decorator+\n'
|
|
jpayne@68
|
2597 ' decorator ::= "@" dotted_name ["(" '
|
|
jpayne@68
|
2598 '[argument_list [","]] ")"] NEWLINE\n'
|
|
jpayne@68
|
2599 ' dotted_name ::= identifier ("." identifier)*\n'
|
|
jpayne@68
|
2600 ' parameter_list ::= defparameter ("," '
|
|
jpayne@68
|
2601 'defparameter)* "," "/" ["," [parameter_list_no_posonly]]\n'
|
|
jpayne@68
|
2602 ' | parameter_list_no_posonly\n'
|
|
jpayne@68
|
2603 ' parameter_list_no_posonly ::= defparameter ("," '
|
|
jpayne@68
|
2604 'defparameter)* ["," [parameter_list_starargs]]\n'
|
|
jpayne@68
|
2605 ' | parameter_list_starargs\n'
|
|
jpayne@68
|
2606 ' parameter_list_starargs ::= "*" [parameter] ("," '
|
|
jpayne@68
|
2607 'defparameter)* ["," ["**" parameter [","]]]\n'
|
|
jpayne@68
|
2608 ' | "**" parameter [","]\n'
|
|
jpayne@68
|
2609 ' parameter ::= identifier [":" expression]\n'
|
|
jpayne@68
|
2610 ' defparameter ::= parameter ["=" expression]\n'
|
|
jpayne@68
|
2611 ' funcname ::= identifier\n'
|
|
jpayne@68
|
2612 '\n'
|
|
jpayne@68
|
2613 'A function definition is an executable statement. Its execution '
|
|
jpayne@68
|
2614 'binds\n'
|
|
jpayne@68
|
2615 'the function name in the current local namespace to a function '
|
|
jpayne@68
|
2616 'object\n'
|
|
jpayne@68
|
2617 '(a wrapper around the executable code for the function). This\n'
|
|
jpayne@68
|
2618 'function object contains a reference to the current global '
|
|
jpayne@68
|
2619 'namespace\n'
|
|
jpayne@68
|
2620 'as the global namespace to be used when the function is called.\n'
|
|
jpayne@68
|
2621 '\n'
|
|
jpayne@68
|
2622 'The function definition does not execute the function body; this '
|
|
jpayne@68
|
2623 'gets\n'
|
|
jpayne@68
|
2624 'executed only when the function is called. [2]\n'
|
|
jpayne@68
|
2625 '\n'
|
|
jpayne@68
|
2626 'A function definition may be wrapped by one or more *decorator*\n'
|
|
jpayne@68
|
2627 'expressions. Decorator expressions are evaluated when the '
|
|
jpayne@68
|
2628 'function is\n'
|
|
jpayne@68
|
2629 'defined, in the scope that contains the function definition. '
|
|
jpayne@68
|
2630 'The\n'
|
|
jpayne@68
|
2631 'result must be a callable, which is invoked with the function '
|
|
jpayne@68
|
2632 'object\n'
|
|
jpayne@68
|
2633 'as the only argument. The returned value is bound to the '
|
|
jpayne@68
|
2634 'function name\n'
|
|
jpayne@68
|
2635 'instead of the function object. Multiple decorators are applied '
|
|
jpayne@68
|
2636 'in\n'
|
|
jpayne@68
|
2637 'nested fashion. For example, the following code\n'
|
|
jpayne@68
|
2638 '\n'
|
|
jpayne@68
|
2639 ' @f1(arg)\n'
|
|
jpayne@68
|
2640 ' @f2\n'
|
|
jpayne@68
|
2641 ' def func(): pass\n'
|
|
jpayne@68
|
2642 '\n'
|
|
jpayne@68
|
2643 'is roughly equivalent to\n'
|
|
jpayne@68
|
2644 '\n'
|
|
jpayne@68
|
2645 ' def func(): pass\n'
|
|
jpayne@68
|
2646 ' func = f1(arg)(f2(func))\n'
|
|
jpayne@68
|
2647 '\n'
|
|
jpayne@68
|
2648 'except that the original function is not temporarily bound to '
|
|
jpayne@68
|
2649 'the name\n'
|
|
jpayne@68
|
2650 '"func".\n'
|
|
jpayne@68
|
2651 '\n'
|
|
jpayne@68
|
2652 'When one or more *parameters* have the form *parameter* "="\n'
|
|
jpayne@68
|
2653 '*expression*, the function is said to have “default parameter '
|
|
jpayne@68
|
2654 'values.”\n'
|
|
jpayne@68
|
2655 'For a parameter with a default value, the corresponding '
|
|
jpayne@68
|
2656 '*argument* may\n'
|
|
jpayne@68
|
2657 'be omitted from a call, in which case the parameter’s default '
|
|
jpayne@68
|
2658 'value is\n'
|
|
jpayne@68
|
2659 'substituted. If a parameter has a default value, all following\n'
|
|
jpayne@68
|
2660 'parameters up until the “"*"” must also have a default value — '
|
|
jpayne@68
|
2661 'this is\n'
|
|
jpayne@68
|
2662 'a syntactic restriction that is not expressed by the grammar.\n'
|
|
jpayne@68
|
2663 '\n'
|
|
jpayne@68
|
2664 '**Default parameter values are evaluated from left to right when '
|
|
jpayne@68
|
2665 'the\n'
|
|
jpayne@68
|
2666 'function definition is executed.** This means that the '
|
|
jpayne@68
|
2667 'expression is\n'
|
|
jpayne@68
|
2668 'evaluated once, when the function is defined, and that the same '
|
|
jpayne@68
|
2669 '“pre-\n'
|
|
jpayne@68
|
2670 'computed” value is used for each call. This is especially '
|
|
jpayne@68
|
2671 'important\n'
|
|
jpayne@68
|
2672 'to understand when a default parameter is a mutable object, such '
|
|
jpayne@68
|
2673 'as a\n'
|
|
jpayne@68
|
2674 'list or a dictionary: if the function modifies the object (e.g. '
|
|
jpayne@68
|
2675 'by\n'
|
|
jpayne@68
|
2676 'appending an item to a list), the default value is in effect '
|
|
jpayne@68
|
2677 'modified.\n'
|
|
jpayne@68
|
2678 'This is generally not what was intended. A way around this is '
|
|
jpayne@68
|
2679 'to use\n'
|
|
jpayne@68
|
2680 '"None" as the default, and explicitly test for it in the body of '
|
|
jpayne@68
|
2681 'the\n'
|
|
jpayne@68
|
2682 'function, e.g.:\n'
|
|
jpayne@68
|
2683 '\n'
|
|
jpayne@68
|
2684 ' def whats_on_the_telly(penguin=None):\n'
|
|
jpayne@68
|
2685 ' if penguin is None:\n'
|
|
jpayne@68
|
2686 ' penguin = []\n'
|
|
jpayne@68
|
2687 ' penguin.append("property of the zoo")\n'
|
|
jpayne@68
|
2688 ' return penguin\n'
|
|
jpayne@68
|
2689 '\n'
|
|
jpayne@68
|
2690 'Function call semantics are described in more detail in section '
|
|
jpayne@68
|
2691 'Calls.\n'
|
|
jpayne@68
|
2692 'A function call always assigns values to all parameters '
|
|
jpayne@68
|
2693 'mentioned in\n'
|
|
jpayne@68
|
2694 'the parameter list, either from position arguments, from '
|
|
jpayne@68
|
2695 'keyword\n'
|
|
jpayne@68
|
2696 'arguments, or from default values. If the form “"*identifier"” '
|
|
jpayne@68
|
2697 'is\n'
|
|
jpayne@68
|
2698 'present, it is initialized to a tuple receiving any excess '
|
|
jpayne@68
|
2699 'positional\n'
|
|
jpayne@68
|
2700 'parameters, defaulting to the empty tuple. If the form\n'
|
|
jpayne@68
|
2701 '“"**identifier"” is present, it is initialized to a new ordered\n'
|
|
jpayne@68
|
2702 'mapping receiving any excess keyword arguments, defaulting to a '
|
|
jpayne@68
|
2703 'new\n'
|
|
jpayne@68
|
2704 'empty mapping of the same type. Parameters after “"*"” or\n'
|
|
jpayne@68
|
2705 '“"*identifier"” are keyword-only parameters and may only be '
|
|
jpayne@68
|
2706 'passed\n'
|
|
jpayne@68
|
2707 'used keyword arguments.\n'
|
|
jpayne@68
|
2708 '\n'
|
|
jpayne@68
|
2709 'Parameters may have an *annotation* of the form “": '
|
|
jpayne@68
|
2710 'expression"”\n'
|
|
jpayne@68
|
2711 'following the parameter name. Any parameter may have an '
|
|
jpayne@68
|
2712 'annotation,\n'
|
|
jpayne@68
|
2713 'even those of the form "*identifier" or "**identifier". '
|
|
jpayne@68
|
2714 'Functions may\n'
|
|
jpayne@68
|
2715 'have “return” annotation of the form “"-> expression"” after '
|
|
jpayne@68
|
2716 'the\n'
|
|
jpayne@68
|
2717 'parameter list. These annotations can be any valid Python '
|
|
jpayne@68
|
2718 'expression.\n'
|
|
jpayne@68
|
2719 'The presence of annotations does not change the semantics of a\n'
|
|
jpayne@68
|
2720 'function. The annotation values are available as values of a\n'
|
|
jpayne@68
|
2721 'dictionary keyed by the parameters’ names in the '
|
|
jpayne@68
|
2722 '"__annotations__"\n'
|
|
jpayne@68
|
2723 'attribute of the function object. If the "annotations" import '
|
|
jpayne@68
|
2724 'from\n'
|
|
jpayne@68
|
2725 '"__future__" is used, annotations are preserved as strings at '
|
|
jpayne@68
|
2726 'runtime\n'
|
|
jpayne@68
|
2727 'which enables postponed evaluation. Otherwise, they are '
|
|
jpayne@68
|
2728 'evaluated\n'
|
|
jpayne@68
|
2729 'when the function definition is executed. In this case '
|
|
jpayne@68
|
2730 'annotations\n'
|
|
jpayne@68
|
2731 'may be evaluated in a different order than they appear in the '
|
|
jpayne@68
|
2732 'source\n'
|
|
jpayne@68
|
2733 'code.\n'
|
|
jpayne@68
|
2734 '\n'
|
|
jpayne@68
|
2735 'It is also possible to create anonymous functions (functions not '
|
|
jpayne@68
|
2736 'bound\n'
|
|
jpayne@68
|
2737 'to a name), for immediate use in expressions. This uses lambda\n'
|
|
jpayne@68
|
2738 'expressions, described in section Lambdas. Note that the '
|
|
jpayne@68
|
2739 'lambda\n'
|
|
jpayne@68
|
2740 'expression is merely a shorthand for a simplified function '
|
|
jpayne@68
|
2741 'definition;\n'
|
|
jpayne@68
|
2742 'a function defined in a “"def"” statement can be passed around '
|
|
jpayne@68
|
2743 'or\n'
|
|
jpayne@68
|
2744 'assigned to another name just like a function defined by a '
|
|
jpayne@68
|
2745 'lambda\n'
|
|
jpayne@68
|
2746 'expression. The “"def"” form is actually more powerful since '
|
|
jpayne@68
|
2747 'it\n'
|
|
jpayne@68
|
2748 'allows the execution of multiple statements and annotations.\n'
|
|
jpayne@68
|
2749 '\n'
|
|
jpayne@68
|
2750 '**Programmer’s note:** Functions are first-class objects. A '
|
|
jpayne@68
|
2751 '“"def"”\n'
|
|
jpayne@68
|
2752 'statement executed inside a function definition defines a local\n'
|
|
jpayne@68
|
2753 'function that can be returned or passed around. Free variables '
|
|
jpayne@68
|
2754 'used\n'
|
|
jpayne@68
|
2755 'in the nested function can access the local variables of the '
|
|
jpayne@68
|
2756 'function\n'
|
|
jpayne@68
|
2757 'containing the def. See section Naming and binding for '
|
|
jpayne@68
|
2758 'details.\n'
|
|
jpayne@68
|
2759 '\n'
|
|
jpayne@68
|
2760 'See also:\n'
|
|
jpayne@68
|
2761 '\n'
|
|
jpayne@68
|
2762 ' **PEP 3107** - Function Annotations\n'
|
|
jpayne@68
|
2763 ' The original specification for function annotations.\n'
|
|
jpayne@68
|
2764 '\n'
|
|
jpayne@68
|
2765 ' **PEP 484** - Type Hints\n'
|
|
jpayne@68
|
2766 ' Definition of a standard meaning for annotations: type '
|
|
jpayne@68
|
2767 'hints.\n'
|
|
jpayne@68
|
2768 '\n'
|
|
jpayne@68
|
2769 ' **PEP 526** - Syntax for Variable Annotations\n'
|
|
jpayne@68
|
2770 ' Ability to type hint variable declarations, including '
|
|
jpayne@68
|
2771 'class\n'
|
|
jpayne@68
|
2772 ' variables and instance variables\n'
|
|
jpayne@68
|
2773 '\n'
|
|
jpayne@68
|
2774 ' **PEP 563** - Postponed Evaluation of Annotations\n'
|
|
jpayne@68
|
2775 ' Support for forward references within annotations by '
|
|
jpayne@68
|
2776 'preserving\n'
|
|
jpayne@68
|
2777 ' annotations in a string form at runtime instead of eager\n'
|
|
jpayne@68
|
2778 ' evaluation.\n'
|
|
jpayne@68
|
2779 '\n'
|
|
jpayne@68
|
2780 '\n'
|
|
jpayne@68
|
2781 'Class definitions\n'
|
|
jpayne@68
|
2782 '=================\n'
|
|
jpayne@68
|
2783 '\n'
|
|
jpayne@68
|
2784 'A class definition defines a class object (see section The '
|
|
jpayne@68
|
2785 'standard\n'
|
|
jpayne@68
|
2786 'type hierarchy):\n'
|
|
jpayne@68
|
2787 '\n'
|
|
jpayne@68
|
2788 ' classdef ::= [decorators] "class" classname [inheritance] '
|
|
jpayne@68
|
2789 '":" suite\n'
|
|
jpayne@68
|
2790 ' inheritance ::= "(" [argument_list] ")"\n'
|
|
jpayne@68
|
2791 ' classname ::= identifier\n'
|
|
jpayne@68
|
2792 '\n'
|
|
jpayne@68
|
2793 'A class definition is an executable statement. The inheritance '
|
|
jpayne@68
|
2794 'list\n'
|
|
jpayne@68
|
2795 'usually gives a list of base classes (see Metaclasses for more\n'
|
|
jpayne@68
|
2796 'advanced uses), so each item in the list should evaluate to a '
|
|
jpayne@68
|
2797 'class\n'
|
|
jpayne@68
|
2798 'object which allows subclassing. Classes without an inheritance '
|
|
jpayne@68
|
2799 'list\n'
|
|
jpayne@68
|
2800 'inherit, by default, from the base class "object"; hence,\n'
|
|
jpayne@68
|
2801 '\n'
|
|
jpayne@68
|
2802 ' class Foo:\n'
|
|
jpayne@68
|
2803 ' pass\n'
|
|
jpayne@68
|
2804 '\n'
|
|
jpayne@68
|
2805 'is equivalent to\n'
|
|
jpayne@68
|
2806 '\n'
|
|
jpayne@68
|
2807 ' class Foo(object):\n'
|
|
jpayne@68
|
2808 ' pass\n'
|
|
jpayne@68
|
2809 '\n'
|
|
jpayne@68
|
2810 'The class’s suite is then executed in a new execution frame '
|
|
jpayne@68
|
2811 '(see\n'
|
|
jpayne@68
|
2812 'Naming and binding), using a newly created local namespace and '
|
|
jpayne@68
|
2813 'the\n'
|
|
jpayne@68
|
2814 'original global namespace. (Usually, the suite contains mostly\n'
|
|
jpayne@68
|
2815 'function definitions.) When the class’s suite finishes '
|
|
jpayne@68
|
2816 'execution, its\n'
|
|
jpayne@68
|
2817 'execution frame is discarded but its local namespace is saved. '
|
|
jpayne@68
|
2818 '[3] A\n'
|
|
jpayne@68
|
2819 'class object is then created using the inheritance list for the '
|
|
jpayne@68
|
2820 'base\n'
|
|
jpayne@68
|
2821 'classes and the saved local namespace for the attribute '
|
|
jpayne@68
|
2822 'dictionary.\n'
|
|
jpayne@68
|
2823 'The class name is bound to this class object in the original '
|
|
jpayne@68
|
2824 'local\n'
|
|
jpayne@68
|
2825 'namespace.\n'
|
|
jpayne@68
|
2826 '\n'
|
|
jpayne@68
|
2827 'The order in which attributes are defined in the class body is\n'
|
|
jpayne@68
|
2828 'preserved in the new class’s "__dict__". Note that this is '
|
|
jpayne@68
|
2829 'reliable\n'
|
|
jpayne@68
|
2830 'only right after the class is created and only for classes that '
|
|
jpayne@68
|
2831 'were\n'
|
|
jpayne@68
|
2832 'defined using the definition syntax.\n'
|
|
jpayne@68
|
2833 '\n'
|
|
jpayne@68
|
2834 'Class creation can be customized heavily using metaclasses.\n'
|
|
jpayne@68
|
2835 '\n'
|
|
jpayne@68
|
2836 'Classes can also be decorated: just like when decorating '
|
|
jpayne@68
|
2837 'functions,\n'
|
|
jpayne@68
|
2838 '\n'
|
|
jpayne@68
|
2839 ' @f1(arg)\n'
|
|
jpayne@68
|
2840 ' @f2\n'
|
|
jpayne@68
|
2841 ' class Foo: pass\n'
|
|
jpayne@68
|
2842 '\n'
|
|
jpayne@68
|
2843 'is roughly equivalent to\n'
|
|
jpayne@68
|
2844 '\n'
|
|
jpayne@68
|
2845 ' class Foo: pass\n'
|
|
jpayne@68
|
2846 ' Foo = f1(arg)(f2(Foo))\n'
|
|
jpayne@68
|
2847 '\n'
|
|
jpayne@68
|
2848 'The evaluation rules for the decorator expressions are the same '
|
|
jpayne@68
|
2849 'as for\n'
|
|
jpayne@68
|
2850 'function decorators. The result is then bound to the class '
|
|
jpayne@68
|
2851 'name.\n'
|
|
jpayne@68
|
2852 '\n'
|
|
jpayne@68
|
2853 '**Programmer’s note:** Variables defined in the class definition '
|
|
jpayne@68
|
2854 'are\n'
|
|
jpayne@68
|
2855 'class attributes; they are shared by instances. Instance '
|
|
jpayne@68
|
2856 'attributes\n'
|
|
jpayne@68
|
2857 'can be set in a method with "self.name = value". Both class '
|
|
jpayne@68
|
2858 'and\n'
|
|
jpayne@68
|
2859 'instance attributes are accessible through the notation '
|
|
jpayne@68
|
2860 '“"self.name"”,\n'
|
|
jpayne@68
|
2861 'and an instance attribute hides a class attribute with the same '
|
|
jpayne@68
|
2862 'name\n'
|
|
jpayne@68
|
2863 'when accessed in this way. Class attributes can be used as '
|
|
jpayne@68
|
2864 'defaults\n'
|
|
jpayne@68
|
2865 'for instance attributes, but using mutable values there can lead '
|
|
jpayne@68
|
2866 'to\n'
|
|
jpayne@68
|
2867 'unexpected results. Descriptors can be used to create instance\n'
|
|
jpayne@68
|
2868 'variables with different implementation details.\n'
|
|
jpayne@68
|
2869 '\n'
|
|
jpayne@68
|
2870 'See also:\n'
|
|
jpayne@68
|
2871 '\n'
|
|
jpayne@68
|
2872 ' **PEP 3115** - Metaclasses in Python 3000\n'
|
|
jpayne@68
|
2873 ' The proposal that changed the declaration of metaclasses to '
|
|
jpayne@68
|
2874 'the\n'
|
|
jpayne@68
|
2875 ' current syntax, and the semantics for how classes with\n'
|
|
jpayne@68
|
2876 ' metaclasses are constructed.\n'
|
|
jpayne@68
|
2877 '\n'
|
|
jpayne@68
|
2878 ' **PEP 3129** - Class Decorators\n'
|
|
jpayne@68
|
2879 ' The proposal that added class decorators. Function and '
|
|
jpayne@68
|
2880 'method\n'
|
|
jpayne@68
|
2881 ' decorators were introduced in **PEP 318**.\n'
|
|
jpayne@68
|
2882 '\n'
|
|
jpayne@68
|
2883 '\n'
|
|
jpayne@68
|
2884 'Coroutines\n'
|
|
jpayne@68
|
2885 '==========\n'
|
|
jpayne@68
|
2886 '\n'
|
|
jpayne@68
|
2887 'New in version 3.5.\n'
|
|
jpayne@68
|
2888 '\n'
|
|
jpayne@68
|
2889 '\n'
|
|
jpayne@68
|
2890 'Coroutine function definition\n'
|
|
jpayne@68
|
2891 '-----------------------------\n'
|
|
jpayne@68
|
2892 '\n'
|
|
jpayne@68
|
2893 ' async_funcdef ::= [decorators] "async" "def" funcname "(" '
|
|
jpayne@68
|
2894 '[parameter_list] ")"\n'
|
|
jpayne@68
|
2895 ' ["->" expression] ":" suite\n'
|
|
jpayne@68
|
2896 '\n'
|
|
jpayne@68
|
2897 'Execution of Python coroutines can be suspended and resumed at '
|
|
jpayne@68
|
2898 'many\n'
|
|
jpayne@68
|
2899 'points (see *coroutine*). Inside the body of a coroutine '
|
|
jpayne@68
|
2900 'function,\n'
|
|
jpayne@68
|
2901 '"await" and "async" identifiers become reserved keywords; '
|
|
jpayne@68
|
2902 '"await"\n'
|
|
jpayne@68
|
2903 'expressions, "async for" and "async with" can only be used in\n'
|
|
jpayne@68
|
2904 'coroutine function bodies.\n'
|
|
jpayne@68
|
2905 '\n'
|
|
jpayne@68
|
2906 'Functions defined with "async def" syntax are always coroutine\n'
|
|
jpayne@68
|
2907 'functions, even if they do not contain "await" or "async" '
|
|
jpayne@68
|
2908 'keywords.\n'
|
|
jpayne@68
|
2909 '\n'
|
|
jpayne@68
|
2910 'It is a "SyntaxError" to use a "yield from" expression inside '
|
|
jpayne@68
|
2911 'the body\n'
|
|
jpayne@68
|
2912 'of a coroutine function.\n'
|
|
jpayne@68
|
2913 '\n'
|
|
jpayne@68
|
2914 'An example of a coroutine function:\n'
|
|
jpayne@68
|
2915 '\n'
|
|
jpayne@68
|
2916 ' async def func(param1, param2):\n'
|
|
jpayne@68
|
2917 ' do_stuff()\n'
|
|
jpayne@68
|
2918 ' await some_coroutine()\n'
|
|
jpayne@68
|
2919 '\n'
|
|
jpayne@68
|
2920 '\n'
|
|
jpayne@68
|
2921 'The "async for" statement\n'
|
|
jpayne@68
|
2922 '-------------------------\n'
|
|
jpayne@68
|
2923 '\n'
|
|
jpayne@68
|
2924 ' async_for_stmt ::= "async" for_stmt\n'
|
|
jpayne@68
|
2925 '\n'
|
|
jpayne@68
|
2926 'An *asynchronous iterable* is able to call asynchronous code in '
|
|
jpayne@68
|
2927 'its\n'
|
|
jpayne@68
|
2928 '*iter* implementation, and *asynchronous iterator* can call\n'
|
|
jpayne@68
|
2929 'asynchronous code in its *next* method.\n'
|
|
jpayne@68
|
2930 '\n'
|
|
jpayne@68
|
2931 'The "async for" statement allows convenient iteration over\n'
|
|
jpayne@68
|
2932 'asynchronous iterators.\n'
|
|
jpayne@68
|
2933 '\n'
|
|
jpayne@68
|
2934 'The following code:\n'
|
|
jpayne@68
|
2935 '\n'
|
|
jpayne@68
|
2936 ' async for TARGET in ITER:\n'
|
|
jpayne@68
|
2937 ' BLOCK\n'
|
|
jpayne@68
|
2938 ' else:\n'
|
|
jpayne@68
|
2939 ' BLOCK2\n'
|
|
jpayne@68
|
2940 '\n'
|
|
jpayne@68
|
2941 'Is semantically equivalent to:\n'
|
|
jpayne@68
|
2942 '\n'
|
|
jpayne@68
|
2943 ' iter = (ITER)\n'
|
|
jpayne@68
|
2944 ' iter = type(iter).__aiter__(iter)\n'
|
|
jpayne@68
|
2945 ' running = True\n'
|
|
jpayne@68
|
2946 ' while running:\n'
|
|
jpayne@68
|
2947 ' try:\n'
|
|
jpayne@68
|
2948 ' TARGET = await type(iter).__anext__(iter)\n'
|
|
jpayne@68
|
2949 ' except StopAsyncIteration:\n'
|
|
jpayne@68
|
2950 ' running = False\n'
|
|
jpayne@68
|
2951 ' else:\n'
|
|
jpayne@68
|
2952 ' BLOCK\n'
|
|
jpayne@68
|
2953 ' else:\n'
|
|
jpayne@68
|
2954 ' BLOCK2\n'
|
|
jpayne@68
|
2955 '\n'
|
|
jpayne@68
|
2956 'See also "__aiter__()" and "__anext__()" for details.\n'
|
|
jpayne@68
|
2957 '\n'
|
|
jpayne@68
|
2958 'It is a "SyntaxError" to use an "async for" statement outside '
|
|
jpayne@68
|
2959 'the body\n'
|
|
jpayne@68
|
2960 'of a coroutine function.\n'
|
|
jpayne@68
|
2961 '\n'
|
|
jpayne@68
|
2962 '\n'
|
|
jpayne@68
|
2963 'The "async with" statement\n'
|
|
jpayne@68
|
2964 '--------------------------\n'
|
|
jpayne@68
|
2965 '\n'
|
|
jpayne@68
|
2966 ' async_with_stmt ::= "async" with_stmt\n'
|
|
jpayne@68
|
2967 '\n'
|
|
jpayne@68
|
2968 'An *asynchronous context manager* is a *context manager* that is '
|
|
jpayne@68
|
2969 'able\n'
|
|
jpayne@68
|
2970 'to suspend execution in its *enter* and *exit* methods.\n'
|
|
jpayne@68
|
2971 '\n'
|
|
jpayne@68
|
2972 'The following code:\n'
|
|
jpayne@68
|
2973 '\n'
|
|
jpayne@68
|
2974 ' async with EXPR as VAR:\n'
|
|
jpayne@68
|
2975 ' BLOCK\n'
|
|
jpayne@68
|
2976 '\n'
|
|
jpayne@68
|
2977 'Is semantically equivalent to:\n'
|
|
jpayne@68
|
2978 '\n'
|
|
jpayne@68
|
2979 ' mgr = (EXPR)\n'
|
|
jpayne@68
|
2980 ' aexit = type(mgr).__aexit__\n'
|
|
jpayne@68
|
2981 ' aenter = type(mgr).__aenter__(mgr)\n'
|
|
jpayne@68
|
2982 '\n'
|
|
jpayne@68
|
2983 ' VAR = await aenter\n'
|
|
jpayne@68
|
2984 ' try:\n'
|
|
jpayne@68
|
2985 ' BLOCK\n'
|
|
jpayne@68
|
2986 ' except:\n'
|
|
jpayne@68
|
2987 ' if not await aexit(mgr, *sys.exc_info()):\n'
|
|
jpayne@68
|
2988 ' raise\n'
|
|
jpayne@68
|
2989 ' else:\n'
|
|
jpayne@68
|
2990 ' await aexit(mgr, None, None, None)\n'
|
|
jpayne@68
|
2991 '\n'
|
|
jpayne@68
|
2992 'See also "__aenter__()" and "__aexit__()" for details.\n'
|
|
jpayne@68
|
2993 '\n'
|
|
jpayne@68
|
2994 'It is a "SyntaxError" to use an "async with" statement outside '
|
|
jpayne@68
|
2995 'the\n'
|
|
jpayne@68
|
2996 'body of a coroutine function.\n'
|
|
jpayne@68
|
2997 '\n'
|
|
jpayne@68
|
2998 'See also:\n'
|
|
jpayne@68
|
2999 '\n'
|
|
jpayne@68
|
3000 ' **PEP 492** - Coroutines with async and await syntax\n'
|
|
jpayne@68
|
3001 ' The proposal that made coroutines a proper standalone '
|
|
jpayne@68
|
3002 'concept in\n'
|
|
jpayne@68
|
3003 ' Python, and added supporting syntax.\n'
|
|
jpayne@68
|
3004 '\n'
|
|
jpayne@68
|
3005 '-[ Footnotes ]-\n'
|
|
jpayne@68
|
3006 '\n'
|
|
jpayne@68
|
3007 '[1] The exception is propagated to the invocation stack unless\n'
|
|
jpayne@68
|
3008 ' there is a "finally" clause which happens to raise another\n'
|
|
jpayne@68
|
3009 ' exception. That new exception causes the old one to be '
|
|
jpayne@68
|
3010 'lost.\n'
|
|
jpayne@68
|
3011 '\n'
|
|
jpayne@68
|
3012 '[2] A string literal appearing as the first statement in the\n'
|
|
jpayne@68
|
3013 ' function body is transformed into the function’s "__doc__"\n'
|
|
jpayne@68
|
3014 ' attribute and therefore the function’s *docstring*.\n'
|
|
jpayne@68
|
3015 '\n'
|
|
jpayne@68
|
3016 '[3] A string literal appearing as the first statement in the '
|
|
jpayne@68
|
3017 'class\n'
|
|
jpayne@68
|
3018 ' body is transformed into the namespace’s "__doc__" item and\n'
|
|
jpayne@68
|
3019 ' therefore the class’s *docstring*.\n',
|
|
jpayne@68
|
3020 'context-managers': 'With Statement Context Managers\n'
|
|
jpayne@68
|
3021 '*******************************\n'
|
|
jpayne@68
|
3022 '\n'
|
|
jpayne@68
|
3023 'A *context manager* is an object that defines the '
|
|
jpayne@68
|
3024 'runtime context to\n'
|
|
jpayne@68
|
3025 'be established when executing a "with" statement. The '
|
|
jpayne@68
|
3026 'context manager\n'
|
|
jpayne@68
|
3027 'handles the entry into, and the exit from, the desired '
|
|
jpayne@68
|
3028 'runtime context\n'
|
|
jpayne@68
|
3029 'for the execution of the block of code. Context '
|
|
jpayne@68
|
3030 'managers are normally\n'
|
|
jpayne@68
|
3031 'invoked using the "with" statement (described in section '
|
|
jpayne@68
|
3032 'The with\n'
|
|
jpayne@68
|
3033 'statement), but can also be used by directly invoking '
|
|
jpayne@68
|
3034 'their methods.\n'
|
|
jpayne@68
|
3035 '\n'
|
|
jpayne@68
|
3036 'Typical uses of context managers include saving and '
|
|
jpayne@68
|
3037 'restoring various\n'
|
|
jpayne@68
|
3038 'kinds of global state, locking and unlocking resources, '
|
|
jpayne@68
|
3039 'closing opened\n'
|
|
jpayne@68
|
3040 'files, etc.\n'
|
|
jpayne@68
|
3041 '\n'
|
|
jpayne@68
|
3042 'For more information on context managers, see Context '
|
|
jpayne@68
|
3043 'Manager Types.\n'
|
|
jpayne@68
|
3044 '\n'
|
|
jpayne@68
|
3045 'object.__enter__(self)\n'
|
|
jpayne@68
|
3046 '\n'
|
|
jpayne@68
|
3047 ' Enter the runtime context related to this object. The '
|
|
jpayne@68
|
3048 '"with"\n'
|
|
jpayne@68
|
3049 ' statement will bind this method’s return value to the '
|
|
jpayne@68
|
3050 'target(s)\n'
|
|
jpayne@68
|
3051 ' specified in the "as" clause of the statement, if '
|
|
jpayne@68
|
3052 'any.\n'
|
|
jpayne@68
|
3053 '\n'
|
|
jpayne@68
|
3054 'object.__exit__(self, exc_type, exc_value, traceback)\n'
|
|
jpayne@68
|
3055 '\n'
|
|
jpayne@68
|
3056 ' Exit the runtime context related to this object. The '
|
|
jpayne@68
|
3057 'parameters\n'
|
|
jpayne@68
|
3058 ' describe the exception that caused the context to be '
|
|
jpayne@68
|
3059 'exited. If the\n'
|
|
jpayne@68
|
3060 ' context was exited without an exception, all three '
|
|
jpayne@68
|
3061 'arguments will\n'
|
|
jpayne@68
|
3062 ' be "None".\n'
|
|
jpayne@68
|
3063 '\n'
|
|
jpayne@68
|
3064 ' If an exception is supplied, and the method wishes to '
|
|
jpayne@68
|
3065 'suppress the\n'
|
|
jpayne@68
|
3066 ' exception (i.e., prevent it from being propagated), '
|
|
jpayne@68
|
3067 'it should\n'
|
|
jpayne@68
|
3068 ' return a true value. Otherwise, the exception will be '
|
|
jpayne@68
|
3069 'processed\n'
|
|
jpayne@68
|
3070 ' normally upon exit from this method.\n'
|
|
jpayne@68
|
3071 '\n'
|
|
jpayne@68
|
3072 ' Note that "__exit__()" methods should not reraise the '
|
|
jpayne@68
|
3073 'passed-in\n'
|
|
jpayne@68
|
3074 ' exception; this is the caller’s responsibility.\n'
|
|
jpayne@68
|
3075 '\n'
|
|
jpayne@68
|
3076 'See also:\n'
|
|
jpayne@68
|
3077 '\n'
|
|
jpayne@68
|
3078 ' **PEP 343** - The “with” statement\n'
|
|
jpayne@68
|
3079 ' The specification, background, and examples for the '
|
|
jpayne@68
|
3080 'Python "with"\n'
|
|
jpayne@68
|
3081 ' statement.\n',
|
|
jpayne@68
|
3082 'continue': 'The "continue" statement\n'
|
|
jpayne@68
|
3083 '************************\n'
|
|
jpayne@68
|
3084 '\n'
|
|
jpayne@68
|
3085 ' continue_stmt ::= "continue"\n'
|
|
jpayne@68
|
3086 '\n'
|
|
jpayne@68
|
3087 '"continue" may only occur syntactically nested in a "for" or '
|
|
jpayne@68
|
3088 '"while"\n'
|
|
jpayne@68
|
3089 'loop, but not nested in a function or class definition within '
|
|
jpayne@68
|
3090 'that\n'
|
|
jpayne@68
|
3091 'loop. It continues with the next cycle of the nearest enclosing '
|
|
jpayne@68
|
3092 'loop.\n'
|
|
jpayne@68
|
3093 '\n'
|
|
jpayne@68
|
3094 'When "continue" passes control out of a "try" statement with a\n'
|
|
jpayne@68
|
3095 '"finally" clause, that "finally" clause is executed before '
|
|
jpayne@68
|
3096 'really\n'
|
|
jpayne@68
|
3097 'starting the next loop cycle.\n',
|
|
jpayne@68
|
3098 'conversions': 'Arithmetic conversions\n'
|
|
jpayne@68
|
3099 '**********************\n'
|
|
jpayne@68
|
3100 '\n'
|
|
jpayne@68
|
3101 'When a description of an arithmetic operator below uses the '
|
|
jpayne@68
|
3102 'phrase\n'
|
|
jpayne@68
|
3103 '“the numeric arguments are converted to a common type,” this '
|
|
jpayne@68
|
3104 'means\n'
|
|
jpayne@68
|
3105 'that the operator implementation for built-in types works as '
|
|
jpayne@68
|
3106 'follows:\n'
|
|
jpayne@68
|
3107 '\n'
|
|
jpayne@68
|
3108 '* If either argument is a complex number, the other is '
|
|
jpayne@68
|
3109 'converted to\n'
|
|
jpayne@68
|
3110 ' complex;\n'
|
|
jpayne@68
|
3111 '\n'
|
|
jpayne@68
|
3112 '* otherwise, if either argument is a floating point number, '
|
|
jpayne@68
|
3113 'the\n'
|
|
jpayne@68
|
3114 ' other is converted to floating point;\n'
|
|
jpayne@68
|
3115 '\n'
|
|
jpayne@68
|
3116 '* otherwise, both must be integers and no conversion is '
|
|
jpayne@68
|
3117 'necessary.\n'
|
|
jpayne@68
|
3118 '\n'
|
|
jpayne@68
|
3119 'Some additional rules apply for certain operators (e.g., a '
|
|
jpayne@68
|
3120 'string as a\n'
|
|
jpayne@68
|
3121 'left argument to the ‘%’ operator). Extensions must define '
|
|
jpayne@68
|
3122 'their own\n'
|
|
jpayne@68
|
3123 'conversion behavior.\n',
|
|
jpayne@68
|
3124 'customization': 'Basic customization\n'
|
|
jpayne@68
|
3125 '*******************\n'
|
|
jpayne@68
|
3126 '\n'
|
|
jpayne@68
|
3127 'object.__new__(cls[, ...])\n'
|
|
jpayne@68
|
3128 '\n'
|
|
jpayne@68
|
3129 ' Called to create a new instance of class *cls*. '
|
|
jpayne@68
|
3130 '"__new__()" is a\n'
|
|
jpayne@68
|
3131 ' static method (special-cased so you need not declare it '
|
|
jpayne@68
|
3132 'as such)\n'
|
|
jpayne@68
|
3133 ' that takes the class of which an instance was requested '
|
|
jpayne@68
|
3134 'as its\n'
|
|
jpayne@68
|
3135 ' first argument. The remaining arguments are those '
|
|
jpayne@68
|
3136 'passed to the\n'
|
|
jpayne@68
|
3137 ' object constructor expression (the call to the class). '
|
|
jpayne@68
|
3138 'The return\n'
|
|
jpayne@68
|
3139 ' value of "__new__()" should be the new object instance '
|
|
jpayne@68
|
3140 '(usually an\n'
|
|
jpayne@68
|
3141 ' instance of *cls*).\n'
|
|
jpayne@68
|
3142 '\n'
|
|
jpayne@68
|
3143 ' Typical implementations create a new instance of the '
|
|
jpayne@68
|
3144 'class by\n'
|
|
jpayne@68
|
3145 ' invoking the superclass’s "__new__()" method using\n'
|
|
jpayne@68
|
3146 ' "super().__new__(cls[, ...])" with appropriate arguments '
|
|
jpayne@68
|
3147 'and then\n'
|
|
jpayne@68
|
3148 ' modifying the newly-created instance as necessary before '
|
|
jpayne@68
|
3149 'returning\n'
|
|
jpayne@68
|
3150 ' it.\n'
|
|
jpayne@68
|
3151 '\n'
|
|
jpayne@68
|
3152 ' If "__new__()" is invoked during object construction and '
|
|
jpayne@68
|
3153 'it returns\n'
|
|
jpayne@68
|
3154 ' an instance or subclass of *cls*, then the new '
|
|
jpayne@68
|
3155 'instance’s\n'
|
|
jpayne@68
|
3156 ' "__init__()" method will be invoked like '
|
|
jpayne@68
|
3157 '"__init__(self[, ...])",\n'
|
|
jpayne@68
|
3158 ' where *self* is the new instance and the remaining '
|
|
jpayne@68
|
3159 'arguments are\n'
|
|
jpayne@68
|
3160 ' the same as were passed to the object constructor.\n'
|
|
jpayne@68
|
3161 '\n'
|
|
jpayne@68
|
3162 ' If "__new__()" does not return an instance of *cls*, '
|
|
jpayne@68
|
3163 'then the new\n'
|
|
jpayne@68
|
3164 ' instance’s "__init__()" method will not be invoked.\n'
|
|
jpayne@68
|
3165 '\n'
|
|
jpayne@68
|
3166 ' "__new__()" is intended mainly to allow subclasses of '
|
|
jpayne@68
|
3167 'immutable\n'
|
|
jpayne@68
|
3168 ' types (like int, str, or tuple) to customize instance '
|
|
jpayne@68
|
3169 'creation. It\n'
|
|
jpayne@68
|
3170 ' is also commonly overridden in custom metaclasses in '
|
|
jpayne@68
|
3171 'order to\n'
|
|
jpayne@68
|
3172 ' customize class creation.\n'
|
|
jpayne@68
|
3173 '\n'
|
|
jpayne@68
|
3174 'object.__init__(self[, ...])\n'
|
|
jpayne@68
|
3175 '\n'
|
|
jpayne@68
|
3176 ' Called after the instance has been created (by '
|
|
jpayne@68
|
3177 '"__new__()"), but\n'
|
|
jpayne@68
|
3178 ' before it is returned to the caller. The arguments are '
|
|
jpayne@68
|
3179 'those\n'
|
|
jpayne@68
|
3180 ' passed to the class constructor expression. If a base '
|
|
jpayne@68
|
3181 'class has an\n'
|
|
jpayne@68
|
3182 ' "__init__()" method, the derived class’s "__init__()" '
|
|
jpayne@68
|
3183 'method, if\n'
|
|
jpayne@68
|
3184 ' any, must explicitly call it to ensure proper '
|
|
jpayne@68
|
3185 'initialization of the\n'
|
|
jpayne@68
|
3186 ' base class part of the instance; for example:\n'
|
|
jpayne@68
|
3187 ' "super().__init__([args...])".\n'
|
|
jpayne@68
|
3188 '\n'
|
|
jpayne@68
|
3189 ' Because "__new__()" and "__init__()" work together in '
|
|
jpayne@68
|
3190 'constructing\n'
|
|
jpayne@68
|
3191 ' objects ("__new__()" to create it, and "__init__()" to '
|
|
jpayne@68
|
3192 'customize\n'
|
|
jpayne@68
|
3193 ' it), no non-"None" value may be returned by '
|
|
jpayne@68
|
3194 '"__init__()"; doing so\n'
|
|
jpayne@68
|
3195 ' will cause a "TypeError" to be raised at runtime.\n'
|
|
jpayne@68
|
3196 '\n'
|
|
jpayne@68
|
3197 'object.__del__(self)\n'
|
|
jpayne@68
|
3198 '\n'
|
|
jpayne@68
|
3199 ' Called when the instance is about to be destroyed. This '
|
|
jpayne@68
|
3200 'is also\n'
|
|
jpayne@68
|
3201 ' called a finalizer or (improperly) a destructor. If a '
|
|
jpayne@68
|
3202 'base class\n'
|
|
jpayne@68
|
3203 ' has a "__del__()" method, the derived class’s '
|
|
jpayne@68
|
3204 '"__del__()" method,\n'
|
|
jpayne@68
|
3205 ' if any, must explicitly call it to ensure proper '
|
|
jpayne@68
|
3206 'deletion of the\n'
|
|
jpayne@68
|
3207 ' base class part of the instance.\n'
|
|
jpayne@68
|
3208 '\n'
|
|
jpayne@68
|
3209 ' It is possible (though not recommended!) for the '
|
|
jpayne@68
|
3210 '"__del__()" method\n'
|
|
jpayne@68
|
3211 ' to postpone destruction of the instance by creating a '
|
|
jpayne@68
|
3212 'new reference\n'
|
|
jpayne@68
|
3213 ' to it. This is called object *resurrection*. It is\n'
|
|
jpayne@68
|
3214 ' implementation-dependent whether "__del__()" is called a '
|
|
jpayne@68
|
3215 'second\n'
|
|
jpayne@68
|
3216 ' time when a resurrected object is about to be destroyed; '
|
|
jpayne@68
|
3217 'the\n'
|
|
jpayne@68
|
3218 ' current *CPython* implementation only calls it once.\n'
|
|
jpayne@68
|
3219 '\n'
|
|
jpayne@68
|
3220 ' It is not guaranteed that "__del__()" methods are called '
|
|
jpayne@68
|
3221 'for\n'
|
|
jpayne@68
|
3222 ' objects that still exist when the interpreter exits.\n'
|
|
jpayne@68
|
3223 '\n'
|
|
jpayne@68
|
3224 ' Note: "del x" doesn’t directly call "x.__del__()" — the '
|
|
jpayne@68
|
3225 'former\n'
|
|
jpayne@68
|
3226 ' decrements the reference count for "x" by one, and the '
|
|
jpayne@68
|
3227 'latter is\n'
|
|
jpayne@68
|
3228 ' only called when "x"’s reference count reaches zero.\n'
|
|
jpayne@68
|
3229 '\n'
|
|
jpayne@68
|
3230 ' **CPython implementation detail:** It is possible for a '
|
|
jpayne@68
|
3231 'reference\n'
|
|
jpayne@68
|
3232 ' cycle to prevent the reference count of an object from '
|
|
jpayne@68
|
3233 'going to\n'
|
|
jpayne@68
|
3234 ' zero. In this case, the cycle will be later detected '
|
|
jpayne@68
|
3235 'and deleted\n'
|
|
jpayne@68
|
3236 ' by the *cyclic garbage collector*. A common cause of '
|
|
jpayne@68
|
3237 'reference\n'
|
|
jpayne@68
|
3238 ' cycles is when an exception has been caught in a local '
|
|
jpayne@68
|
3239 'variable.\n'
|
|
jpayne@68
|
3240 ' The frame’s locals then reference the exception, which '
|
|
jpayne@68
|
3241 'references\n'
|
|
jpayne@68
|
3242 ' its own traceback, which references the locals of all '
|
|
jpayne@68
|
3243 'frames caught\n'
|
|
jpayne@68
|
3244 ' in the traceback.\n'
|
|
jpayne@68
|
3245 '\n'
|
|
jpayne@68
|
3246 ' See also: Documentation for the "gc" module.\n'
|
|
jpayne@68
|
3247 '\n'
|
|
jpayne@68
|
3248 ' Warning: Due to the precarious circumstances under '
|
|
jpayne@68
|
3249 'which\n'
|
|
jpayne@68
|
3250 ' "__del__()" methods are invoked, exceptions that occur '
|
|
jpayne@68
|
3251 'during\n'
|
|
jpayne@68
|
3252 ' their execution are ignored, and a warning is printed '
|
|
jpayne@68
|
3253 'to\n'
|
|
jpayne@68
|
3254 ' "sys.stderr" instead. In particular:\n'
|
|
jpayne@68
|
3255 '\n'
|
|
jpayne@68
|
3256 ' * "__del__()" can be invoked when arbitrary code is '
|
|
jpayne@68
|
3257 'being\n'
|
|
jpayne@68
|
3258 ' executed, including from any arbitrary thread. If '
|
|
jpayne@68
|
3259 '"__del__()"\n'
|
|
jpayne@68
|
3260 ' needs to take a lock or invoke any other blocking '
|
|
jpayne@68
|
3261 'resource, it\n'
|
|
jpayne@68
|
3262 ' may deadlock as the resource may already be taken by '
|
|
jpayne@68
|
3263 'the code\n'
|
|
jpayne@68
|
3264 ' that gets interrupted to execute "__del__()".\n'
|
|
jpayne@68
|
3265 '\n'
|
|
jpayne@68
|
3266 ' * "__del__()" can be executed during interpreter '
|
|
jpayne@68
|
3267 'shutdown. As\n'
|
|
jpayne@68
|
3268 ' a consequence, the global variables it needs to '
|
|
jpayne@68
|
3269 'access\n'
|
|
jpayne@68
|
3270 ' (including other modules) may already have been '
|
|
jpayne@68
|
3271 'deleted or set\n'
|
|
jpayne@68
|
3272 ' to "None". Python guarantees that globals whose name '
|
|
jpayne@68
|
3273 'begins\n'
|
|
jpayne@68
|
3274 ' with a single underscore are deleted from their '
|
|
jpayne@68
|
3275 'module before\n'
|
|
jpayne@68
|
3276 ' other globals are deleted; if no other references to '
|
|
jpayne@68
|
3277 'such\n'
|
|
jpayne@68
|
3278 ' globals exist, this may help in assuring that '
|
|
jpayne@68
|
3279 'imported modules\n'
|
|
jpayne@68
|
3280 ' are still available at the time when the "__del__()" '
|
|
jpayne@68
|
3281 'method is\n'
|
|
jpayne@68
|
3282 ' called.\n'
|
|
jpayne@68
|
3283 '\n'
|
|
jpayne@68
|
3284 'object.__repr__(self)\n'
|
|
jpayne@68
|
3285 '\n'
|
|
jpayne@68
|
3286 ' Called by the "repr()" built-in function to compute the '
|
|
jpayne@68
|
3287 '“official”\n'
|
|
jpayne@68
|
3288 ' string representation of an object. If at all possible, '
|
|
jpayne@68
|
3289 'this\n'
|
|
jpayne@68
|
3290 ' should look like a valid Python expression that could be '
|
|
jpayne@68
|
3291 'used to\n'
|
|
jpayne@68
|
3292 ' recreate an object with the same value (given an '
|
|
jpayne@68
|
3293 'appropriate\n'
|
|
jpayne@68
|
3294 ' environment). If this is not possible, a string of the '
|
|
jpayne@68
|
3295 'form\n'
|
|
jpayne@68
|
3296 ' "<...some useful description...>" should be returned. '
|
|
jpayne@68
|
3297 'The return\n'
|
|
jpayne@68
|
3298 ' value must be a string object. If a class defines '
|
|
jpayne@68
|
3299 '"__repr__()" but\n'
|
|
jpayne@68
|
3300 ' not "__str__()", then "__repr__()" is also used when an '
|
|
jpayne@68
|
3301 '“informal”\n'
|
|
jpayne@68
|
3302 ' string representation of instances of that class is '
|
|
jpayne@68
|
3303 'required.\n'
|
|
jpayne@68
|
3304 '\n'
|
|
jpayne@68
|
3305 ' This is typically used for debugging, so it is important '
|
|
jpayne@68
|
3306 'that the\n'
|
|
jpayne@68
|
3307 ' representation is information-rich and unambiguous.\n'
|
|
jpayne@68
|
3308 '\n'
|
|
jpayne@68
|
3309 'object.__str__(self)\n'
|
|
jpayne@68
|
3310 '\n'
|
|
jpayne@68
|
3311 ' Called by "str(object)" and the built-in functions '
|
|
jpayne@68
|
3312 '"format()" and\n'
|
|
jpayne@68
|
3313 ' "print()" to compute the “informal” or nicely printable '
|
|
jpayne@68
|
3314 'string\n'
|
|
jpayne@68
|
3315 ' representation of an object. The return value must be a '
|
|
jpayne@68
|
3316 'string\n'
|
|
jpayne@68
|
3317 ' object.\n'
|
|
jpayne@68
|
3318 '\n'
|
|
jpayne@68
|
3319 ' This method differs from "object.__repr__()" in that '
|
|
jpayne@68
|
3320 'there is no\n'
|
|
jpayne@68
|
3321 ' expectation that "__str__()" return a valid Python '
|
|
jpayne@68
|
3322 'expression: a\n'
|
|
jpayne@68
|
3323 ' more convenient or concise representation can be used.\n'
|
|
jpayne@68
|
3324 '\n'
|
|
jpayne@68
|
3325 ' The default implementation defined by the built-in type '
|
|
jpayne@68
|
3326 '"object"\n'
|
|
jpayne@68
|
3327 ' calls "object.__repr__()".\n'
|
|
jpayne@68
|
3328 '\n'
|
|
jpayne@68
|
3329 'object.__bytes__(self)\n'
|
|
jpayne@68
|
3330 '\n'
|
|
jpayne@68
|
3331 ' Called by bytes to compute a byte-string representation '
|
|
jpayne@68
|
3332 'of an\n'
|
|
jpayne@68
|
3333 ' object. This should return a "bytes" object.\n'
|
|
jpayne@68
|
3334 '\n'
|
|
jpayne@68
|
3335 'object.__format__(self, format_spec)\n'
|
|
jpayne@68
|
3336 '\n'
|
|
jpayne@68
|
3337 ' Called by the "format()" built-in function, and by '
|
|
jpayne@68
|
3338 'extension,\n'
|
|
jpayne@68
|
3339 ' evaluation of formatted string literals and the '
|
|
jpayne@68
|
3340 '"str.format()"\n'
|
|
jpayne@68
|
3341 ' method, to produce a “formatted” string representation '
|
|
jpayne@68
|
3342 'of an\n'
|
|
jpayne@68
|
3343 ' object. The *format_spec* argument is a string that '
|
|
jpayne@68
|
3344 'contains a\n'
|
|
jpayne@68
|
3345 ' description of the formatting options desired. The '
|
|
jpayne@68
|
3346 'interpretation\n'
|
|
jpayne@68
|
3347 ' of the *format_spec* argument is up to the type '
|
|
jpayne@68
|
3348 'implementing\n'
|
|
jpayne@68
|
3349 ' "__format__()", however most classes will either '
|
|
jpayne@68
|
3350 'delegate\n'
|
|
jpayne@68
|
3351 ' formatting to one of the built-in types, or use a '
|
|
jpayne@68
|
3352 'similar\n'
|
|
jpayne@68
|
3353 ' formatting option syntax.\n'
|
|
jpayne@68
|
3354 '\n'
|
|
jpayne@68
|
3355 ' See Format Specification Mini-Language for a description '
|
|
jpayne@68
|
3356 'of the\n'
|
|
jpayne@68
|
3357 ' standard formatting syntax.\n'
|
|
jpayne@68
|
3358 '\n'
|
|
jpayne@68
|
3359 ' The return value must be a string object.\n'
|
|
jpayne@68
|
3360 '\n'
|
|
jpayne@68
|
3361 ' Changed in version 3.4: The __format__ method of '
|
|
jpayne@68
|
3362 '"object" itself\n'
|
|
jpayne@68
|
3363 ' raises a "TypeError" if passed any non-empty string.\n'
|
|
jpayne@68
|
3364 '\n'
|
|
jpayne@68
|
3365 ' Changed in version 3.7: "object.__format__(x, \'\')" is '
|
|
jpayne@68
|
3366 'now\n'
|
|
jpayne@68
|
3367 ' equivalent to "str(x)" rather than "format(str(self), '
|
|
jpayne@68
|
3368 '\'\')".\n'
|
|
jpayne@68
|
3369 '\n'
|
|
jpayne@68
|
3370 'object.__lt__(self, other)\n'
|
|
jpayne@68
|
3371 'object.__le__(self, other)\n'
|
|
jpayne@68
|
3372 'object.__eq__(self, other)\n'
|
|
jpayne@68
|
3373 'object.__ne__(self, other)\n'
|
|
jpayne@68
|
3374 'object.__gt__(self, other)\n'
|
|
jpayne@68
|
3375 'object.__ge__(self, other)\n'
|
|
jpayne@68
|
3376 '\n'
|
|
jpayne@68
|
3377 ' These are the so-called “rich comparison” methods. The\n'
|
|
jpayne@68
|
3378 ' correspondence between operator symbols and method names '
|
|
jpayne@68
|
3379 'is as\n'
|
|
jpayne@68
|
3380 ' follows: "x<y" calls "x.__lt__(y)", "x<=y" calls '
|
|
jpayne@68
|
3381 '"x.__le__(y)",\n'
|
|
jpayne@68
|
3382 ' "x==y" calls "x.__eq__(y)", "x!=y" calls "x.__ne__(y)", '
|
|
jpayne@68
|
3383 '"x>y" calls\n'
|
|
jpayne@68
|
3384 ' "x.__gt__(y)", and "x>=y" calls "x.__ge__(y)".\n'
|
|
jpayne@68
|
3385 '\n'
|
|
jpayne@68
|
3386 ' A rich comparison method may return the singleton '
|
|
jpayne@68
|
3387 '"NotImplemented"\n'
|
|
jpayne@68
|
3388 ' if it does not implement the operation for a given pair '
|
|
jpayne@68
|
3389 'of\n'
|
|
jpayne@68
|
3390 ' arguments. By convention, "False" and "True" are '
|
|
jpayne@68
|
3391 'returned for a\n'
|
|
jpayne@68
|
3392 ' successful comparison. However, these methods can return '
|
|
jpayne@68
|
3393 'any value,\n'
|
|
jpayne@68
|
3394 ' so if the comparison operator is used in a Boolean '
|
|
jpayne@68
|
3395 'context (e.g.,\n'
|
|
jpayne@68
|
3396 ' in the condition of an "if" statement), Python will call '
|
|
jpayne@68
|
3397 '"bool()"\n'
|
|
jpayne@68
|
3398 ' on the value to determine if the result is true or '
|
|
jpayne@68
|
3399 'false.\n'
|
|
jpayne@68
|
3400 '\n'
|
|
jpayne@68
|
3401 ' By default, "__ne__()" delegates to "__eq__()" and '
|
|
jpayne@68
|
3402 'inverts the\n'
|
|
jpayne@68
|
3403 ' result unless it is "NotImplemented". There are no '
|
|
jpayne@68
|
3404 'other implied\n'
|
|
jpayne@68
|
3405 ' relationships among the comparison operators, for '
|
|
jpayne@68
|
3406 'example, the\n'
|
|
jpayne@68
|
3407 ' truth of "(x<y or x==y)" does not imply "x<=y". To '
|
|
jpayne@68
|
3408 'automatically\n'
|
|
jpayne@68
|
3409 ' generate ordering operations from a single root '
|
|
jpayne@68
|
3410 'operation, see\n'
|
|
jpayne@68
|
3411 ' "functools.total_ordering()".\n'
|
|
jpayne@68
|
3412 '\n'
|
|
jpayne@68
|
3413 ' See the paragraph on "__hash__()" for some important '
|
|
jpayne@68
|
3414 'notes on\n'
|
|
jpayne@68
|
3415 ' creating *hashable* objects which support custom '
|
|
jpayne@68
|
3416 'comparison\n'
|
|
jpayne@68
|
3417 ' operations and are usable as dictionary keys.\n'
|
|
jpayne@68
|
3418 '\n'
|
|
jpayne@68
|
3419 ' There are no swapped-argument versions of these methods '
|
|
jpayne@68
|
3420 '(to be used\n'
|
|
jpayne@68
|
3421 ' when the left argument does not support the operation '
|
|
jpayne@68
|
3422 'but the right\n'
|
|
jpayne@68
|
3423 ' argument does); rather, "__lt__()" and "__gt__()" are '
|
|
jpayne@68
|
3424 'each other’s\n'
|
|
jpayne@68
|
3425 ' reflection, "__le__()" and "__ge__()" are each other’s '
|
|
jpayne@68
|
3426 'reflection,\n'
|
|
jpayne@68
|
3427 ' and "__eq__()" and "__ne__()" are their own reflection. '
|
|
jpayne@68
|
3428 'If the\n'
|
|
jpayne@68
|
3429 ' operands are of different types, and right operand’s '
|
|
jpayne@68
|
3430 'type is a\n'
|
|
jpayne@68
|
3431 ' direct or indirect subclass of the left operand’s type, '
|
|
jpayne@68
|
3432 'the\n'
|
|
jpayne@68
|
3433 ' reflected method of the right operand has priority, '
|
|
jpayne@68
|
3434 'otherwise the\n'
|
|
jpayne@68
|
3435 ' left operand’s method has priority. Virtual subclassing '
|
|
jpayne@68
|
3436 'is not\n'
|
|
jpayne@68
|
3437 ' considered.\n'
|
|
jpayne@68
|
3438 '\n'
|
|
jpayne@68
|
3439 'object.__hash__(self)\n'
|
|
jpayne@68
|
3440 '\n'
|
|
jpayne@68
|
3441 ' Called by built-in function "hash()" and for operations '
|
|
jpayne@68
|
3442 'on members\n'
|
|
jpayne@68
|
3443 ' of hashed collections including "set", "frozenset", and '
|
|
jpayne@68
|
3444 '"dict".\n'
|
|
jpayne@68
|
3445 ' "__hash__()" should return an integer. The only required '
|
|
jpayne@68
|
3446 'property\n'
|
|
jpayne@68
|
3447 ' is that objects which compare equal have the same hash '
|
|
jpayne@68
|
3448 'value; it is\n'
|
|
jpayne@68
|
3449 ' advised to mix together the hash values of the '
|
|
jpayne@68
|
3450 'components of the\n'
|
|
jpayne@68
|
3451 ' object that also play a part in comparison of objects by '
|
|
jpayne@68
|
3452 'packing\n'
|
|
jpayne@68
|
3453 ' them into a tuple and hashing the tuple. Example:\n'
|
|
jpayne@68
|
3454 '\n'
|
|
jpayne@68
|
3455 ' def __hash__(self):\n'
|
|
jpayne@68
|
3456 ' return hash((self.name, self.nick, self.color))\n'
|
|
jpayne@68
|
3457 '\n'
|
|
jpayne@68
|
3458 ' Note: "hash()" truncates the value returned from an '
|
|
jpayne@68
|
3459 'object’s\n'
|
|
jpayne@68
|
3460 ' custom "__hash__()" method to the size of a '
|
|
jpayne@68
|
3461 '"Py_ssize_t". This\n'
|
|
jpayne@68
|
3462 ' is typically 8 bytes on 64-bit builds and 4 bytes on '
|
|
jpayne@68
|
3463 '32-bit\n'
|
|
jpayne@68
|
3464 ' builds. If an object’s "__hash__()" must '
|
|
jpayne@68
|
3465 'interoperate on builds\n'
|
|
jpayne@68
|
3466 ' of different bit sizes, be sure to check the width on '
|
|
jpayne@68
|
3467 'all\n'
|
|
jpayne@68
|
3468 ' supported builds. An easy way to do this is with '
|
|
jpayne@68
|
3469 '"python -c\n'
|
|
jpayne@68
|
3470 ' "import sys; print(sys.hash_info.width)"".\n'
|
|
jpayne@68
|
3471 '\n'
|
|
jpayne@68
|
3472 ' If a class does not define an "__eq__()" method it '
|
|
jpayne@68
|
3473 'should not\n'
|
|
jpayne@68
|
3474 ' define a "__hash__()" operation either; if it defines '
|
|
jpayne@68
|
3475 '"__eq__()"\n'
|
|
jpayne@68
|
3476 ' but not "__hash__()", its instances will not be usable '
|
|
jpayne@68
|
3477 'as items in\n'
|
|
jpayne@68
|
3478 ' hashable collections. If a class defines mutable '
|
|
jpayne@68
|
3479 'objects and\n'
|
|
jpayne@68
|
3480 ' implements an "__eq__()" method, it should not '
|
|
jpayne@68
|
3481 'implement\n'
|
|
jpayne@68
|
3482 ' "__hash__()", since the implementation of hashable '
|
|
jpayne@68
|
3483 'collections\n'
|
|
jpayne@68
|
3484 ' requires that a key’s hash value is immutable (if the '
|
|
jpayne@68
|
3485 'object’s hash\n'
|
|
jpayne@68
|
3486 ' value changes, it will be in the wrong hash bucket).\n'
|
|
jpayne@68
|
3487 '\n'
|
|
jpayne@68
|
3488 ' User-defined classes have "__eq__()" and "__hash__()" '
|
|
jpayne@68
|
3489 'methods by\n'
|
|
jpayne@68
|
3490 ' default; with them, all objects compare unequal (except '
|
|
jpayne@68
|
3491 'with\n'
|
|
jpayne@68
|
3492 ' themselves) and "x.__hash__()" returns an appropriate '
|
|
jpayne@68
|
3493 'value such\n'
|
|
jpayne@68
|
3494 ' that "x == y" implies both that "x is y" and "hash(x) == '
|
|
jpayne@68
|
3495 'hash(y)".\n'
|
|
jpayne@68
|
3496 '\n'
|
|
jpayne@68
|
3497 ' A class that overrides "__eq__()" and does not define '
|
|
jpayne@68
|
3498 '"__hash__()"\n'
|
|
jpayne@68
|
3499 ' will have its "__hash__()" implicitly set to "None". '
|
|
jpayne@68
|
3500 'When the\n'
|
|
jpayne@68
|
3501 ' "__hash__()" method of a class is "None", instances of '
|
|
jpayne@68
|
3502 'the class\n'
|
|
jpayne@68
|
3503 ' will raise an appropriate "TypeError" when a program '
|
|
jpayne@68
|
3504 'attempts to\n'
|
|
jpayne@68
|
3505 ' retrieve their hash value, and will also be correctly '
|
|
jpayne@68
|
3506 'identified as\n'
|
|
jpayne@68
|
3507 ' unhashable when checking "isinstance(obj,\n'
|
|
jpayne@68
|
3508 ' collections.abc.Hashable)".\n'
|
|
jpayne@68
|
3509 '\n'
|
|
jpayne@68
|
3510 ' If a class that overrides "__eq__()" needs to retain '
|
|
jpayne@68
|
3511 'the\n'
|
|
jpayne@68
|
3512 ' implementation of "__hash__()" from a parent class, the '
|
|
jpayne@68
|
3513 'interpreter\n'
|
|
jpayne@68
|
3514 ' must be told this explicitly by setting "__hash__ =\n'
|
|
jpayne@68
|
3515 ' <ParentClass>.__hash__".\n'
|
|
jpayne@68
|
3516 '\n'
|
|
jpayne@68
|
3517 ' If a class that does not override "__eq__()" wishes to '
|
|
jpayne@68
|
3518 'suppress\n'
|
|
jpayne@68
|
3519 ' hash support, it should include "__hash__ = None" in the '
|
|
jpayne@68
|
3520 'class\n'
|
|
jpayne@68
|
3521 ' definition. A class which defines its own "__hash__()" '
|
|
jpayne@68
|
3522 'that\n'
|
|
jpayne@68
|
3523 ' explicitly raises a "TypeError" would be incorrectly '
|
|
jpayne@68
|
3524 'identified as\n'
|
|
jpayne@68
|
3525 ' hashable by an "isinstance(obj, '
|
|
jpayne@68
|
3526 'collections.abc.Hashable)" call.\n'
|
|
jpayne@68
|
3527 '\n'
|
|
jpayne@68
|
3528 ' Note: By default, the "__hash__()" values of str and '
|
|
jpayne@68
|
3529 'bytes\n'
|
|
jpayne@68
|
3530 ' objects are “salted” with an unpredictable random '
|
|
jpayne@68
|
3531 'value.\n'
|
|
jpayne@68
|
3532 ' Although they remain constant within an individual '
|
|
jpayne@68
|
3533 'Python\n'
|
|
jpayne@68
|
3534 ' process, they are not predictable between repeated '
|
|
jpayne@68
|
3535 'invocations of\n'
|
|
jpayne@68
|
3536 ' Python.This is intended to provide protection against '
|
|
jpayne@68
|
3537 'a denial-\n'
|
|
jpayne@68
|
3538 ' of-service caused by carefully-chosen inputs that '
|
|
jpayne@68
|
3539 'exploit the\n'
|
|
jpayne@68
|
3540 ' worst case performance of a dict insertion, O(n^2) '
|
|
jpayne@68
|
3541 'complexity.\n'
|
|
jpayne@68
|
3542 ' See '
|
|
jpayne@68
|
3543 'http://www.ocert.org/advisories/ocert-2011-003.html for\n'
|
|
jpayne@68
|
3544 ' details.Changing hash values affects the iteration '
|
|
jpayne@68
|
3545 'order of sets.\n'
|
|
jpayne@68
|
3546 ' Python has never made guarantees about this ordering '
|
|
jpayne@68
|
3547 '(and it\n'
|
|
jpayne@68
|
3548 ' typically varies between 32-bit and 64-bit builds).See '
|
|
jpayne@68
|
3549 'also\n'
|
|
jpayne@68
|
3550 ' "PYTHONHASHSEED".\n'
|
|
jpayne@68
|
3551 '\n'
|
|
jpayne@68
|
3552 ' Changed in version 3.3: Hash randomization is enabled by '
|
|
jpayne@68
|
3553 'default.\n'
|
|
jpayne@68
|
3554 '\n'
|
|
jpayne@68
|
3555 'object.__bool__(self)\n'
|
|
jpayne@68
|
3556 '\n'
|
|
jpayne@68
|
3557 ' Called to implement truth value testing and the built-in '
|
|
jpayne@68
|
3558 'operation\n'
|
|
jpayne@68
|
3559 ' "bool()"; should return "False" or "True". When this '
|
|
jpayne@68
|
3560 'method is not\n'
|
|
jpayne@68
|
3561 ' defined, "__len__()" is called, if it is defined, and '
|
|
jpayne@68
|
3562 'the object is\n'
|
|
jpayne@68
|
3563 ' considered true if its result is nonzero. If a class '
|
|
jpayne@68
|
3564 'defines\n'
|
|
jpayne@68
|
3565 ' neither "__len__()" nor "__bool__()", all its instances '
|
|
jpayne@68
|
3566 'are\n'
|
|
jpayne@68
|
3567 ' considered true.\n',
|
|
jpayne@68
|
3568 'debugger': '"pdb" — The Python Debugger\n'
|
|
jpayne@68
|
3569 '***************************\n'
|
|
jpayne@68
|
3570 '\n'
|
|
jpayne@68
|
3571 '**Source code:** Lib/pdb.py\n'
|
|
jpayne@68
|
3572 '\n'
|
|
jpayne@68
|
3573 '======================================================================\n'
|
|
jpayne@68
|
3574 '\n'
|
|
jpayne@68
|
3575 'The module "pdb" defines an interactive source code debugger '
|
|
jpayne@68
|
3576 'for\n'
|
|
jpayne@68
|
3577 'Python programs. It supports setting (conditional) breakpoints '
|
|
jpayne@68
|
3578 'and\n'
|
|
jpayne@68
|
3579 'single stepping at the source line level, inspection of stack '
|
|
jpayne@68
|
3580 'frames,\n'
|
|
jpayne@68
|
3581 'source code listing, and evaluation of arbitrary Python code in '
|
|
jpayne@68
|
3582 'the\n'
|
|
jpayne@68
|
3583 'context of any stack frame. It also supports post-mortem '
|
|
jpayne@68
|
3584 'debugging\n'
|
|
jpayne@68
|
3585 'and can be called under program control.\n'
|
|
jpayne@68
|
3586 '\n'
|
|
jpayne@68
|
3587 'The debugger is extensible – it is actually defined as the '
|
|
jpayne@68
|
3588 'class\n'
|
|
jpayne@68
|
3589 '"Pdb". This is currently undocumented but easily understood by '
|
|
jpayne@68
|
3590 'reading\n'
|
|
jpayne@68
|
3591 'the source. The extension interface uses the modules "bdb" and '
|
|
jpayne@68
|
3592 '"cmd".\n'
|
|
jpayne@68
|
3593 '\n'
|
|
jpayne@68
|
3594 'The debugger’s prompt is "(Pdb)". Typical usage to run a program '
|
|
jpayne@68
|
3595 'under\n'
|
|
jpayne@68
|
3596 'control of the debugger is:\n'
|
|
jpayne@68
|
3597 '\n'
|
|
jpayne@68
|
3598 ' >>> import pdb\n'
|
|
jpayne@68
|
3599 ' >>> import mymodule\n'
|
|
jpayne@68
|
3600 " >>> pdb.run('mymodule.test()')\n"
|
|
jpayne@68
|
3601 ' > <string>(0)?()\n'
|
|
jpayne@68
|
3602 ' (Pdb) continue\n'
|
|
jpayne@68
|
3603 ' > <string>(1)?()\n'
|
|
jpayne@68
|
3604 ' (Pdb) continue\n'
|
|
jpayne@68
|
3605 " NameError: 'spam'\n"
|
|
jpayne@68
|
3606 ' > <string>(1)?()\n'
|
|
jpayne@68
|
3607 ' (Pdb)\n'
|
|
jpayne@68
|
3608 '\n'
|
|
jpayne@68
|
3609 'Changed in version 3.3: Tab-completion via the "readline" module '
|
|
jpayne@68
|
3610 'is\n'
|
|
jpayne@68
|
3611 'available for commands and command arguments, e.g. the current '
|
|
jpayne@68
|
3612 'global\n'
|
|
jpayne@68
|
3613 'and local names are offered as arguments of the "p" command.\n'
|
|
jpayne@68
|
3614 '\n'
|
|
jpayne@68
|
3615 '"pdb.py" can also be invoked as a script to debug other '
|
|
jpayne@68
|
3616 'scripts. For\n'
|
|
jpayne@68
|
3617 'example:\n'
|
|
jpayne@68
|
3618 '\n'
|
|
jpayne@68
|
3619 ' python3 -m pdb myscript.py\n'
|
|
jpayne@68
|
3620 '\n'
|
|
jpayne@68
|
3621 'When invoked as a script, pdb will automatically enter '
|
|
jpayne@68
|
3622 'post-mortem\n'
|
|
jpayne@68
|
3623 'debugging if the program being debugged exits abnormally. After '
|
|
jpayne@68
|
3624 'post-\n'
|
|
jpayne@68
|
3625 'mortem debugging (or after normal exit of the program), pdb '
|
|
jpayne@68
|
3626 'will\n'
|
|
jpayne@68
|
3627 'restart the program. Automatic restarting preserves pdb’s state '
|
|
jpayne@68
|
3628 '(such\n'
|
|
jpayne@68
|
3629 'as breakpoints) and in most cases is more useful than quitting '
|
|
jpayne@68
|
3630 'the\n'
|
|
jpayne@68
|
3631 'debugger upon program’s exit.\n'
|
|
jpayne@68
|
3632 '\n'
|
|
jpayne@68
|
3633 'New in version 3.2: "pdb.py" now accepts a "-c" option that '
|
|
jpayne@68
|
3634 'executes\n'
|
|
jpayne@68
|
3635 'commands as if given in a ".pdbrc" file, see Debugger Commands.\n'
|
|
jpayne@68
|
3636 '\n'
|
|
jpayne@68
|
3637 'New in version 3.7: "pdb.py" now accepts a "-m" option that '
|
|
jpayne@68
|
3638 'execute\n'
|
|
jpayne@68
|
3639 'modules similar to the way "python3 -m" does. As with a script, '
|
|
jpayne@68
|
3640 'the\n'
|
|
jpayne@68
|
3641 'debugger will pause execution just before the first line of the\n'
|
|
jpayne@68
|
3642 'module.\n'
|
|
jpayne@68
|
3643 '\n'
|
|
jpayne@68
|
3644 'The typical usage to break into the debugger from a running '
|
|
jpayne@68
|
3645 'program is\n'
|
|
jpayne@68
|
3646 'to insert\n'
|
|
jpayne@68
|
3647 '\n'
|
|
jpayne@68
|
3648 ' import pdb; pdb.set_trace()\n'
|
|
jpayne@68
|
3649 '\n'
|
|
jpayne@68
|
3650 'at the location you want to break into the debugger. You can '
|
|
jpayne@68
|
3651 'then\n'
|
|
jpayne@68
|
3652 'step through the code following this statement, and continue '
|
|
jpayne@68
|
3653 'running\n'
|
|
jpayne@68
|
3654 'without the debugger using the "continue" command.\n'
|
|
jpayne@68
|
3655 '\n'
|
|
jpayne@68
|
3656 'New in version 3.7: The built-in "breakpoint()", when called '
|
|
jpayne@68
|
3657 'with\n'
|
|
jpayne@68
|
3658 'defaults, can be used instead of "import pdb; pdb.set_trace()".\n'
|
|
jpayne@68
|
3659 '\n'
|
|
jpayne@68
|
3660 'The typical usage to inspect a crashed program is:\n'
|
|
jpayne@68
|
3661 '\n'
|
|
jpayne@68
|
3662 ' >>> import pdb\n'
|
|
jpayne@68
|
3663 ' >>> import mymodule\n'
|
|
jpayne@68
|
3664 ' >>> mymodule.test()\n'
|
|
jpayne@68
|
3665 ' Traceback (most recent call last):\n'
|
|
jpayne@68
|
3666 ' File "<stdin>", line 1, in <module>\n'
|
|
jpayne@68
|
3667 ' File "./mymodule.py", line 4, in test\n'
|
|
jpayne@68
|
3668 ' test2()\n'
|
|
jpayne@68
|
3669 ' File "./mymodule.py", line 3, in test2\n'
|
|
jpayne@68
|
3670 ' print(spam)\n'
|
|
jpayne@68
|
3671 ' NameError: spam\n'
|
|
jpayne@68
|
3672 ' >>> pdb.pm()\n'
|
|
jpayne@68
|
3673 ' > ./mymodule.py(3)test2()\n'
|
|
jpayne@68
|
3674 ' -> print(spam)\n'
|
|
jpayne@68
|
3675 ' (Pdb)\n'
|
|
jpayne@68
|
3676 '\n'
|
|
jpayne@68
|
3677 'The module defines the following functions; each enters the '
|
|
jpayne@68
|
3678 'debugger\n'
|
|
jpayne@68
|
3679 'in a slightly different way:\n'
|
|
jpayne@68
|
3680 '\n'
|
|
jpayne@68
|
3681 'pdb.run(statement, globals=None, locals=None)\n'
|
|
jpayne@68
|
3682 '\n'
|
|
jpayne@68
|
3683 ' Execute the *statement* (given as a string or a code object) '
|
|
jpayne@68
|
3684 'under\n'
|
|
jpayne@68
|
3685 ' debugger control. The debugger prompt appears before any '
|
|
jpayne@68
|
3686 'code is\n'
|
|
jpayne@68
|
3687 ' executed; you can set breakpoints and type "continue", or you '
|
|
jpayne@68
|
3688 'can\n'
|
|
jpayne@68
|
3689 ' step through the statement using "step" or "next" (all these\n'
|
|
jpayne@68
|
3690 ' commands are explained below). The optional *globals* and '
|
|
jpayne@68
|
3691 '*locals*\n'
|
|
jpayne@68
|
3692 ' arguments specify the environment in which the code is '
|
|
jpayne@68
|
3693 'executed; by\n'
|
|
jpayne@68
|
3694 ' default the dictionary of the module "__main__" is used. '
|
|
jpayne@68
|
3695 '(See the\n'
|
|
jpayne@68
|
3696 ' explanation of the built-in "exec()" or "eval()" functions.)\n'
|
|
jpayne@68
|
3697 '\n'
|
|
jpayne@68
|
3698 'pdb.runeval(expression, globals=None, locals=None)\n'
|
|
jpayne@68
|
3699 '\n'
|
|
jpayne@68
|
3700 ' Evaluate the *expression* (given as a string or a code '
|
|
jpayne@68
|
3701 'object)\n'
|
|
jpayne@68
|
3702 ' under debugger control. When "runeval()" returns, it returns '
|
|
jpayne@68
|
3703 'the\n'
|
|
jpayne@68
|
3704 ' value of the expression. Otherwise this function is similar '
|
|
jpayne@68
|
3705 'to\n'
|
|
jpayne@68
|
3706 ' "run()".\n'
|
|
jpayne@68
|
3707 '\n'
|
|
jpayne@68
|
3708 'pdb.runcall(function, *args, **kwds)\n'
|
|
jpayne@68
|
3709 '\n'
|
|
jpayne@68
|
3710 ' Call the *function* (a function or method object, not a '
|
|
jpayne@68
|
3711 'string)\n'
|
|
jpayne@68
|
3712 ' with the given arguments. When "runcall()" returns, it '
|
|
jpayne@68
|
3713 'returns\n'
|
|
jpayne@68
|
3714 ' whatever the function call returned. The debugger prompt '
|
|
jpayne@68
|
3715 'appears\n'
|
|
jpayne@68
|
3716 ' as soon as the function is entered.\n'
|
|
jpayne@68
|
3717 '\n'
|
|
jpayne@68
|
3718 'pdb.set_trace(*, header=None)\n'
|
|
jpayne@68
|
3719 '\n'
|
|
jpayne@68
|
3720 ' Enter the debugger at the calling stack frame. This is '
|
|
jpayne@68
|
3721 'useful to\n'
|
|
jpayne@68
|
3722 ' hard-code a breakpoint at a given point in a program, even if '
|
|
jpayne@68
|
3723 'the\n'
|
|
jpayne@68
|
3724 ' code is not otherwise being debugged (e.g. when an assertion\n'
|
|
jpayne@68
|
3725 ' fails). If given, *header* is printed to the console just '
|
|
jpayne@68
|
3726 'before\n'
|
|
jpayne@68
|
3727 ' debugging begins.\n'
|
|
jpayne@68
|
3728 '\n'
|
|
jpayne@68
|
3729 ' Changed in version 3.7: The keyword-only argument *header*.\n'
|
|
jpayne@68
|
3730 '\n'
|
|
jpayne@68
|
3731 'pdb.post_mortem(traceback=None)\n'
|
|
jpayne@68
|
3732 '\n'
|
|
jpayne@68
|
3733 ' Enter post-mortem debugging of the given *traceback* object. '
|
|
jpayne@68
|
3734 'If no\n'
|
|
jpayne@68
|
3735 ' *traceback* is given, it uses the one of the exception that '
|
|
jpayne@68
|
3736 'is\n'
|
|
jpayne@68
|
3737 ' currently being handled (an exception must be being handled '
|
|
jpayne@68
|
3738 'if the\n'
|
|
jpayne@68
|
3739 ' default is to be used).\n'
|
|
jpayne@68
|
3740 '\n'
|
|
jpayne@68
|
3741 'pdb.pm()\n'
|
|
jpayne@68
|
3742 '\n'
|
|
jpayne@68
|
3743 ' Enter post-mortem debugging of the traceback found in\n'
|
|
jpayne@68
|
3744 ' "sys.last_traceback".\n'
|
|
jpayne@68
|
3745 '\n'
|
|
jpayne@68
|
3746 'The "run*" functions and "set_trace()" are aliases for '
|
|
jpayne@68
|
3747 'instantiating\n'
|
|
jpayne@68
|
3748 'the "Pdb" class and calling the method of the same name. If you '
|
|
jpayne@68
|
3749 'want\n'
|
|
jpayne@68
|
3750 'to access further features, you have to do this yourself:\n'
|
|
jpayne@68
|
3751 '\n'
|
|
jpayne@68
|
3752 "class pdb.Pdb(completekey='tab', stdin=None, stdout=None, "
|
|
jpayne@68
|
3753 'skip=None, nosigint=False, readrc=True)\n'
|
|
jpayne@68
|
3754 '\n'
|
|
jpayne@68
|
3755 ' "Pdb" is the debugger class.\n'
|
|
jpayne@68
|
3756 '\n'
|
|
jpayne@68
|
3757 ' The *completekey*, *stdin* and *stdout* arguments are passed '
|
|
jpayne@68
|
3758 'to the\n'
|
|
jpayne@68
|
3759 ' underlying "cmd.Cmd" class; see the description there.\n'
|
|
jpayne@68
|
3760 '\n'
|
|
jpayne@68
|
3761 ' The *skip* argument, if given, must be an iterable of '
|
|
jpayne@68
|
3762 'glob-style\n'
|
|
jpayne@68
|
3763 ' module name patterns. The debugger will not step into frames '
|
|
jpayne@68
|
3764 'that\n'
|
|
jpayne@68
|
3765 ' originate in a module that matches one of these patterns. '
|
|
jpayne@68
|
3766 '[1]\n'
|
|
jpayne@68
|
3767 '\n'
|
|
jpayne@68
|
3768 ' By default, Pdb sets a handler for the SIGINT signal (which '
|
|
jpayne@68
|
3769 'is sent\n'
|
|
jpayne@68
|
3770 ' when the user presses "Ctrl-C" on the console) when you give '
|
|
jpayne@68
|
3771 'a\n'
|
|
jpayne@68
|
3772 ' "continue" command. This allows you to break into the '
|
|
jpayne@68
|
3773 'debugger\n'
|
|
jpayne@68
|
3774 ' again by pressing "Ctrl-C". If you want Pdb not to touch '
|
|
jpayne@68
|
3775 'the\n'
|
|
jpayne@68
|
3776 ' SIGINT handler, set *nosigint* to true.\n'
|
|
jpayne@68
|
3777 '\n'
|
|
jpayne@68
|
3778 ' The *readrc* argument defaults to true and controls whether '
|
|
jpayne@68
|
3779 'Pdb\n'
|
|
jpayne@68
|
3780 ' will load .pdbrc files from the filesystem.\n'
|
|
jpayne@68
|
3781 '\n'
|
|
jpayne@68
|
3782 ' Example call to enable tracing with *skip*:\n'
|
|
jpayne@68
|
3783 '\n'
|
|
jpayne@68
|
3784 " import pdb; pdb.Pdb(skip=['django.*']).set_trace()\n"
|
|
jpayne@68
|
3785 '\n'
|
|
jpayne@68
|
3786 ' Raises an auditing event "pdb.Pdb" with no arguments.\n'
|
|
jpayne@68
|
3787 '\n'
|
|
jpayne@68
|
3788 ' New in version 3.1: The *skip* argument.\n'
|
|
jpayne@68
|
3789 '\n'
|
|
jpayne@68
|
3790 ' New in version 3.2: The *nosigint* argument. Previously, a '
|
|
jpayne@68
|
3791 'SIGINT\n'
|
|
jpayne@68
|
3792 ' handler was never set by Pdb.\n'
|
|
jpayne@68
|
3793 '\n'
|
|
jpayne@68
|
3794 ' Changed in version 3.6: The *readrc* argument.\n'
|
|
jpayne@68
|
3795 '\n'
|
|
jpayne@68
|
3796 ' run(statement, globals=None, locals=None)\n'
|
|
jpayne@68
|
3797 ' runeval(expression, globals=None, locals=None)\n'
|
|
jpayne@68
|
3798 ' runcall(function, *args, **kwds)\n'
|
|
jpayne@68
|
3799 ' set_trace()\n'
|
|
jpayne@68
|
3800 '\n'
|
|
jpayne@68
|
3801 ' See the documentation for the functions explained above.\n'
|
|
jpayne@68
|
3802 '\n'
|
|
jpayne@68
|
3803 '\n'
|
|
jpayne@68
|
3804 'Debugger Commands\n'
|
|
jpayne@68
|
3805 '=================\n'
|
|
jpayne@68
|
3806 '\n'
|
|
jpayne@68
|
3807 'The commands recognized by the debugger are listed below. Most\n'
|
|
jpayne@68
|
3808 'commands can be abbreviated to one or two letters as indicated; '
|
|
jpayne@68
|
3809 'e.g.\n'
|
|
jpayne@68
|
3810 '"h(elp)" means that either "h" or "help" can be used to enter '
|
|
jpayne@68
|
3811 'the help\n'
|
|
jpayne@68
|
3812 'command (but not "he" or "hel", nor "H" or "Help" or "HELP").\n'
|
|
jpayne@68
|
3813 'Arguments to commands must be separated by whitespace (spaces '
|
|
jpayne@68
|
3814 'or\n'
|
|
jpayne@68
|
3815 'tabs). Optional arguments are enclosed in square brackets '
|
|
jpayne@68
|
3816 '("[]") in\n'
|
|
jpayne@68
|
3817 'the command syntax; the square brackets must not be typed.\n'
|
|
jpayne@68
|
3818 'Alternatives in the command syntax are separated by a vertical '
|
|
jpayne@68
|
3819 'bar\n'
|
|
jpayne@68
|
3820 '("|").\n'
|
|
jpayne@68
|
3821 '\n'
|
|
jpayne@68
|
3822 'Entering a blank line repeats the last command entered. '
|
|
jpayne@68
|
3823 'Exception: if\n'
|
|
jpayne@68
|
3824 'the last command was a "list" command, the next 11 lines are '
|
|
jpayne@68
|
3825 'listed.\n'
|
|
jpayne@68
|
3826 '\n'
|
|
jpayne@68
|
3827 'Commands that the debugger doesn’t recognize are assumed to be '
|
|
jpayne@68
|
3828 'Python\n'
|
|
jpayne@68
|
3829 'statements and are executed in the context of the program being\n'
|
|
jpayne@68
|
3830 'debugged. Python statements can also be prefixed with an '
|
|
jpayne@68
|
3831 'exclamation\n'
|
|
jpayne@68
|
3832 'point ("!"). This is a powerful way to inspect the program '
|
|
jpayne@68
|
3833 'being\n'
|
|
jpayne@68
|
3834 'debugged; it is even possible to change a variable or call a '
|
|
jpayne@68
|
3835 'function.\n'
|
|
jpayne@68
|
3836 'When an exception occurs in such a statement, the exception name '
|
|
jpayne@68
|
3837 'is\n'
|
|
jpayne@68
|
3838 'printed but the debugger’s state is not changed.\n'
|
|
jpayne@68
|
3839 '\n'
|
|
jpayne@68
|
3840 'The debugger supports aliases. Aliases can have parameters '
|
|
jpayne@68
|
3841 'which\n'
|
|
jpayne@68
|
3842 'allows one a certain level of adaptability to the context under\n'
|
|
jpayne@68
|
3843 'examination.\n'
|
|
jpayne@68
|
3844 '\n'
|
|
jpayne@68
|
3845 'Multiple commands may be entered on a single line, separated by '
|
|
jpayne@68
|
3846 '";;".\n'
|
|
jpayne@68
|
3847 '(A single ";" is not used as it is the separator for multiple '
|
|
jpayne@68
|
3848 'commands\n'
|
|
jpayne@68
|
3849 'in a line that is passed to the Python parser.) No intelligence '
|
|
jpayne@68
|
3850 'is\n'
|
|
jpayne@68
|
3851 'applied to separating the commands; the input is split at the '
|
|
jpayne@68
|
3852 'first\n'
|
|
jpayne@68
|
3853 '";;" pair, even if it is in the middle of a quoted string.\n'
|
|
jpayne@68
|
3854 '\n'
|
|
jpayne@68
|
3855 'If a file ".pdbrc" exists in the user’s home directory or in '
|
|
jpayne@68
|
3856 'the\n'
|
|
jpayne@68
|
3857 'current directory, it is read in and executed as if it had been '
|
|
jpayne@68
|
3858 'typed\n'
|
|
jpayne@68
|
3859 'at the debugger prompt. This is particularly useful for '
|
|
jpayne@68
|
3860 'aliases. If\n'
|
|
jpayne@68
|
3861 'both files exist, the one in the home directory is read first '
|
|
jpayne@68
|
3862 'and\n'
|
|
jpayne@68
|
3863 'aliases defined there can be overridden by the local file.\n'
|
|
jpayne@68
|
3864 '\n'
|
|
jpayne@68
|
3865 'Changed in version 3.2: ".pdbrc" can now contain commands that\n'
|
|
jpayne@68
|
3866 'continue debugging, such as "continue" or "next". Previously, '
|
|
jpayne@68
|
3867 'these\n'
|
|
jpayne@68
|
3868 'commands had no effect.\n'
|
|
jpayne@68
|
3869 '\n'
|
|
jpayne@68
|
3870 'h(elp) [command]\n'
|
|
jpayne@68
|
3871 '\n'
|
|
jpayne@68
|
3872 ' Without argument, print the list of available commands. With '
|
|
jpayne@68
|
3873 'a\n'
|
|
jpayne@68
|
3874 ' *command* as argument, print help about that command. "help '
|
|
jpayne@68
|
3875 'pdb"\n'
|
|
jpayne@68
|
3876 ' displays the full documentation (the docstring of the "pdb"\n'
|
|
jpayne@68
|
3877 ' module). Since the *command* argument must be an identifier, '
|
|
jpayne@68
|
3878 '"help\n'
|
|
jpayne@68
|
3879 ' exec" must be entered to get help on the "!" command.\n'
|
|
jpayne@68
|
3880 '\n'
|
|
jpayne@68
|
3881 'w(here)\n'
|
|
jpayne@68
|
3882 '\n'
|
|
jpayne@68
|
3883 ' Print a stack trace, with the most recent frame at the '
|
|
jpayne@68
|
3884 'bottom. An\n'
|
|
jpayne@68
|
3885 ' arrow indicates the current frame, which determines the '
|
|
jpayne@68
|
3886 'context of\n'
|
|
jpayne@68
|
3887 ' most commands.\n'
|
|
jpayne@68
|
3888 '\n'
|
|
jpayne@68
|
3889 'd(own) [count]\n'
|
|
jpayne@68
|
3890 '\n'
|
|
jpayne@68
|
3891 ' Move the current frame *count* (default one) levels down in '
|
|
jpayne@68
|
3892 'the\n'
|
|
jpayne@68
|
3893 ' stack trace (to a newer frame).\n'
|
|
jpayne@68
|
3894 '\n'
|
|
jpayne@68
|
3895 'u(p) [count]\n'
|
|
jpayne@68
|
3896 '\n'
|
|
jpayne@68
|
3897 ' Move the current frame *count* (default one) levels up in the '
|
|
jpayne@68
|
3898 'stack\n'
|
|
jpayne@68
|
3899 ' trace (to an older frame).\n'
|
|
jpayne@68
|
3900 '\n'
|
|
jpayne@68
|
3901 'b(reak) [([filename:]lineno | function) [, condition]]\n'
|
|
jpayne@68
|
3902 '\n'
|
|
jpayne@68
|
3903 ' With a *lineno* argument, set a break there in the current '
|
|
jpayne@68
|
3904 'file.\n'
|
|
jpayne@68
|
3905 ' With a *function* argument, set a break at the first '
|
|
jpayne@68
|
3906 'executable\n'
|
|
jpayne@68
|
3907 ' statement within that function. The line number may be '
|
|
jpayne@68
|
3908 'prefixed\n'
|
|
jpayne@68
|
3909 ' with a filename and a colon, to specify a breakpoint in '
|
|
jpayne@68
|
3910 'another\n'
|
|
jpayne@68
|
3911 ' file (probably one that hasn’t been loaded yet). The file '
|
|
jpayne@68
|
3912 'is\n'
|
|
jpayne@68
|
3913 ' searched on "sys.path". Note that each breakpoint is '
|
|
jpayne@68
|
3914 'assigned a\n'
|
|
jpayne@68
|
3915 ' number to which all the other breakpoint commands refer.\n'
|
|
jpayne@68
|
3916 '\n'
|
|
jpayne@68
|
3917 ' If a second argument is present, it is an expression which '
|
|
jpayne@68
|
3918 'must\n'
|
|
jpayne@68
|
3919 ' evaluate to true before the breakpoint is honored.\n'
|
|
jpayne@68
|
3920 '\n'
|
|
jpayne@68
|
3921 ' Without argument, list all breaks, including for each '
|
|
jpayne@68
|
3922 'breakpoint,\n'
|
|
jpayne@68
|
3923 ' the number of times that breakpoint has been hit, the '
|
|
jpayne@68
|
3924 'current\n'
|
|
jpayne@68
|
3925 ' ignore count, and the associated condition if any.\n'
|
|
jpayne@68
|
3926 '\n'
|
|
jpayne@68
|
3927 'tbreak [([filename:]lineno | function) [, condition]]\n'
|
|
jpayne@68
|
3928 '\n'
|
|
jpayne@68
|
3929 ' Temporary breakpoint, which is removed automatically when it '
|
|
jpayne@68
|
3930 'is\n'
|
|
jpayne@68
|
3931 ' first hit. The arguments are the same as for "break".\n'
|
|
jpayne@68
|
3932 '\n'
|
|
jpayne@68
|
3933 'cl(ear) [filename:lineno | bpnumber [bpnumber ...]]\n'
|
|
jpayne@68
|
3934 '\n'
|
|
jpayne@68
|
3935 ' With a *filename:lineno* argument, clear all the breakpoints '
|
|
jpayne@68
|
3936 'at\n'
|
|
jpayne@68
|
3937 ' this line. With a space separated list of breakpoint numbers, '
|
|
jpayne@68
|
3938 'clear\n'
|
|
jpayne@68
|
3939 ' those breakpoints. Without argument, clear all breaks (but '
|
|
jpayne@68
|
3940 'first\n'
|
|
jpayne@68
|
3941 ' ask confirmation).\n'
|
|
jpayne@68
|
3942 '\n'
|
|
jpayne@68
|
3943 'disable [bpnumber [bpnumber ...]]\n'
|
|
jpayne@68
|
3944 '\n'
|
|
jpayne@68
|
3945 ' Disable the breakpoints given as a space separated list of\n'
|
|
jpayne@68
|
3946 ' breakpoint numbers. Disabling a breakpoint means it cannot '
|
|
jpayne@68
|
3947 'cause\n'
|
|
jpayne@68
|
3948 ' the program to stop execution, but unlike clearing a '
|
|
jpayne@68
|
3949 'breakpoint, it\n'
|
|
jpayne@68
|
3950 ' remains in the list of breakpoints and can be (re-)enabled.\n'
|
|
jpayne@68
|
3951 '\n'
|
|
jpayne@68
|
3952 'enable [bpnumber [bpnumber ...]]\n'
|
|
jpayne@68
|
3953 '\n'
|
|
jpayne@68
|
3954 ' Enable the breakpoints specified.\n'
|
|
jpayne@68
|
3955 '\n'
|
|
jpayne@68
|
3956 'ignore bpnumber [count]\n'
|
|
jpayne@68
|
3957 '\n'
|
|
jpayne@68
|
3958 ' Set the ignore count for the given breakpoint number. If '
|
|
jpayne@68
|
3959 'count is\n'
|
|
jpayne@68
|
3960 ' omitted, the ignore count is set to 0. A breakpoint becomes '
|
|
jpayne@68
|
3961 'active\n'
|
|
jpayne@68
|
3962 ' when the ignore count is zero. When non-zero, the count is\n'
|
|
jpayne@68
|
3963 ' decremented each time the breakpoint is reached and the '
|
|
jpayne@68
|
3964 'breakpoint\n'
|
|
jpayne@68
|
3965 ' is not disabled and any associated condition evaluates to '
|
|
jpayne@68
|
3966 'true.\n'
|
|
jpayne@68
|
3967 '\n'
|
|
jpayne@68
|
3968 'condition bpnumber [condition]\n'
|
|
jpayne@68
|
3969 '\n'
|
|
jpayne@68
|
3970 ' Set a new *condition* for the breakpoint, an expression which '
|
|
jpayne@68
|
3971 'must\n'
|
|
jpayne@68
|
3972 ' evaluate to true before the breakpoint is honored. If '
|
|
jpayne@68
|
3973 '*condition*\n'
|
|
jpayne@68
|
3974 ' is absent, any existing condition is removed; i.e., the '
|
|
jpayne@68
|
3975 'breakpoint\n'
|
|
jpayne@68
|
3976 ' is made unconditional.\n'
|
|
jpayne@68
|
3977 '\n'
|
|
jpayne@68
|
3978 'commands [bpnumber]\n'
|
|
jpayne@68
|
3979 '\n'
|
|
jpayne@68
|
3980 ' Specify a list of commands for breakpoint number *bpnumber*. '
|
|
jpayne@68
|
3981 'The\n'
|
|
jpayne@68
|
3982 ' commands themselves appear on the following lines. Type a '
|
|
jpayne@68
|
3983 'line\n'
|
|
jpayne@68
|
3984 ' containing just "end" to terminate the commands. An example:\n'
|
|
jpayne@68
|
3985 '\n'
|
|
jpayne@68
|
3986 ' (Pdb) commands 1\n'
|
|
jpayne@68
|
3987 ' (com) p some_variable\n'
|
|
jpayne@68
|
3988 ' (com) end\n'
|
|
jpayne@68
|
3989 ' (Pdb)\n'
|
|
jpayne@68
|
3990 '\n'
|
|
jpayne@68
|
3991 ' To remove all commands from a breakpoint, type "commands" '
|
|
jpayne@68
|
3992 'and\n'
|
|
jpayne@68
|
3993 ' follow it immediately with "end"; that is, give no commands.\n'
|
|
jpayne@68
|
3994 '\n'
|
|
jpayne@68
|
3995 ' With no *bpnumber* argument, "commands" refers to the last\n'
|
|
jpayne@68
|
3996 ' breakpoint set.\n'
|
|
jpayne@68
|
3997 '\n'
|
|
jpayne@68
|
3998 ' You can use breakpoint commands to start your program up '
|
|
jpayne@68
|
3999 'again.\n'
|
|
jpayne@68
|
4000 ' Simply use the "continue" command, or "step", or any other '
|
|
jpayne@68
|
4001 'command\n'
|
|
jpayne@68
|
4002 ' that resumes execution.\n'
|
|
jpayne@68
|
4003 '\n'
|
|
jpayne@68
|
4004 ' Specifying any command resuming execution (currently '
|
|
jpayne@68
|
4005 '"continue",\n'
|
|
jpayne@68
|
4006 ' "step", "next", "return", "jump", "quit" and their '
|
|
jpayne@68
|
4007 'abbreviations)\n'
|
|
jpayne@68
|
4008 ' terminates the command list (as if that command was '
|
|
jpayne@68
|
4009 'immediately\n'
|
|
jpayne@68
|
4010 ' followed by end). This is because any time you resume '
|
|
jpayne@68
|
4011 'execution\n'
|
|
jpayne@68
|
4012 ' (even with a simple next or step), you may encounter another\n'
|
|
jpayne@68
|
4013 ' breakpoint—which could have its own command list, leading to\n'
|
|
jpayne@68
|
4014 ' ambiguities about which list to execute.\n'
|
|
jpayne@68
|
4015 '\n'
|
|
jpayne@68
|
4016 ' If you use the ‘silent’ command in the command list, the '
|
|
jpayne@68
|
4017 'usual\n'
|
|
jpayne@68
|
4018 ' message about stopping at a breakpoint is not printed. This '
|
|
jpayne@68
|
4019 'may be\n'
|
|
jpayne@68
|
4020 ' desirable for breakpoints that are to print a specific '
|
|
jpayne@68
|
4021 'message and\n'
|
|
jpayne@68
|
4022 ' then continue. If none of the other commands print anything, '
|
|
jpayne@68
|
4023 'you\n'
|
|
jpayne@68
|
4024 ' see no sign that the breakpoint was reached.\n'
|
|
jpayne@68
|
4025 '\n'
|
|
jpayne@68
|
4026 's(tep)\n'
|
|
jpayne@68
|
4027 '\n'
|
|
jpayne@68
|
4028 ' Execute the current line, stop at the first possible '
|
|
jpayne@68
|
4029 'occasion\n'
|
|
jpayne@68
|
4030 ' (either in a function that is called or on the next line in '
|
|
jpayne@68
|
4031 'the\n'
|
|
jpayne@68
|
4032 ' current function).\n'
|
|
jpayne@68
|
4033 '\n'
|
|
jpayne@68
|
4034 'n(ext)\n'
|
|
jpayne@68
|
4035 '\n'
|
|
jpayne@68
|
4036 ' Continue execution until the next line in the current '
|
|
jpayne@68
|
4037 'function is\n'
|
|
jpayne@68
|
4038 ' reached or it returns. (The difference between "next" and '
|
|
jpayne@68
|
4039 '"step"\n'
|
|
jpayne@68
|
4040 ' is that "step" stops inside a called function, while "next"\n'
|
|
jpayne@68
|
4041 ' executes called functions at (nearly) full speed, only '
|
|
jpayne@68
|
4042 'stopping at\n'
|
|
jpayne@68
|
4043 ' the next line in the current function.)\n'
|
|
jpayne@68
|
4044 '\n'
|
|
jpayne@68
|
4045 'unt(il) [lineno]\n'
|
|
jpayne@68
|
4046 '\n'
|
|
jpayne@68
|
4047 ' Without argument, continue execution until the line with a '
|
|
jpayne@68
|
4048 'number\n'
|
|
jpayne@68
|
4049 ' greater than the current one is reached.\n'
|
|
jpayne@68
|
4050 '\n'
|
|
jpayne@68
|
4051 ' With a line number, continue execution until a line with a '
|
|
jpayne@68
|
4052 'number\n'
|
|
jpayne@68
|
4053 ' greater or equal to that is reached. In both cases, also '
|
|
jpayne@68
|
4054 'stop when\n'
|
|
jpayne@68
|
4055 ' the current frame returns.\n'
|
|
jpayne@68
|
4056 '\n'
|
|
jpayne@68
|
4057 ' Changed in version 3.2: Allow giving an explicit line '
|
|
jpayne@68
|
4058 'number.\n'
|
|
jpayne@68
|
4059 '\n'
|
|
jpayne@68
|
4060 'r(eturn)\n'
|
|
jpayne@68
|
4061 '\n'
|
|
jpayne@68
|
4062 ' Continue execution until the current function returns.\n'
|
|
jpayne@68
|
4063 '\n'
|
|
jpayne@68
|
4064 'c(ont(inue))\n'
|
|
jpayne@68
|
4065 '\n'
|
|
jpayne@68
|
4066 ' Continue execution, only stop when a breakpoint is '
|
|
jpayne@68
|
4067 'encountered.\n'
|
|
jpayne@68
|
4068 '\n'
|
|
jpayne@68
|
4069 'j(ump) lineno\n'
|
|
jpayne@68
|
4070 '\n'
|
|
jpayne@68
|
4071 ' Set the next line that will be executed. Only available in '
|
|
jpayne@68
|
4072 'the\n'
|
|
jpayne@68
|
4073 ' bottom-most frame. This lets you jump back and execute code '
|
|
jpayne@68
|
4074 'again,\n'
|
|
jpayne@68
|
4075 ' or jump forward to skip code that you don’t want to run.\n'
|
|
jpayne@68
|
4076 '\n'
|
|
jpayne@68
|
4077 ' It should be noted that not all jumps are allowed – for '
|
|
jpayne@68
|
4078 'instance it\n'
|
|
jpayne@68
|
4079 ' is not possible to jump into the middle of a "for" loop or '
|
|
jpayne@68
|
4080 'out of a\n'
|
|
jpayne@68
|
4081 ' "finally" clause.\n'
|
|
jpayne@68
|
4082 '\n'
|
|
jpayne@68
|
4083 'l(ist) [first[, last]]\n'
|
|
jpayne@68
|
4084 '\n'
|
|
jpayne@68
|
4085 ' List source code for the current file. Without arguments, '
|
|
jpayne@68
|
4086 'list 11\n'
|
|
jpayne@68
|
4087 ' lines around the current line or continue the previous '
|
|
jpayne@68
|
4088 'listing.\n'
|
|
jpayne@68
|
4089 ' With "." as argument, list 11 lines around the current line. '
|
|
jpayne@68
|
4090 'With\n'
|
|
jpayne@68
|
4091 ' one argument, list 11 lines around at that line. With two\n'
|
|
jpayne@68
|
4092 ' arguments, list the given range; if the second argument is '
|
|
jpayne@68
|
4093 'less\n'
|
|
jpayne@68
|
4094 ' than the first, it is interpreted as a count.\n'
|
|
jpayne@68
|
4095 '\n'
|
|
jpayne@68
|
4096 ' The current line in the current frame is indicated by "->". '
|
|
jpayne@68
|
4097 'If an\n'
|
|
jpayne@68
|
4098 ' exception is being debugged, the line where the exception '
|
|
jpayne@68
|
4099 'was\n'
|
|
jpayne@68
|
4100 ' originally raised or propagated is indicated by ">>", if it '
|
|
jpayne@68
|
4101 'differs\n'
|
|
jpayne@68
|
4102 ' from the current line.\n'
|
|
jpayne@68
|
4103 '\n'
|
|
jpayne@68
|
4104 ' New in version 3.2: The ">>" marker.\n'
|
|
jpayne@68
|
4105 '\n'
|
|
jpayne@68
|
4106 'll | longlist\n'
|
|
jpayne@68
|
4107 '\n'
|
|
jpayne@68
|
4108 ' List all source code for the current function or frame.\n'
|
|
jpayne@68
|
4109 ' Interesting lines are marked as for "list".\n'
|
|
jpayne@68
|
4110 '\n'
|
|
jpayne@68
|
4111 ' New in version 3.2.\n'
|
|
jpayne@68
|
4112 '\n'
|
|
jpayne@68
|
4113 'a(rgs)\n'
|
|
jpayne@68
|
4114 '\n'
|
|
jpayne@68
|
4115 ' Print the argument list of the current function.\n'
|
|
jpayne@68
|
4116 '\n'
|
|
jpayne@68
|
4117 'p expression\n'
|
|
jpayne@68
|
4118 '\n'
|
|
jpayne@68
|
4119 ' Evaluate the *expression* in the current context and print '
|
|
jpayne@68
|
4120 'its\n'
|
|
jpayne@68
|
4121 ' value.\n'
|
|
jpayne@68
|
4122 '\n'
|
|
jpayne@68
|
4123 ' Note: "print()" can also be used, but is not a debugger '
|
|
jpayne@68
|
4124 'command —\n'
|
|
jpayne@68
|
4125 ' this executes the Python "print()" function.\n'
|
|
jpayne@68
|
4126 '\n'
|
|
jpayne@68
|
4127 'pp expression\n'
|
|
jpayne@68
|
4128 '\n'
|
|
jpayne@68
|
4129 ' Like the "p" command, except the value of the expression is '
|
|
jpayne@68
|
4130 'pretty-\n'
|
|
jpayne@68
|
4131 ' printed using the "pprint" module.\n'
|
|
jpayne@68
|
4132 '\n'
|
|
jpayne@68
|
4133 'whatis expression\n'
|
|
jpayne@68
|
4134 '\n'
|
|
jpayne@68
|
4135 ' Print the type of the *expression*.\n'
|
|
jpayne@68
|
4136 '\n'
|
|
jpayne@68
|
4137 'source expression\n'
|
|
jpayne@68
|
4138 '\n'
|
|
jpayne@68
|
4139 ' Try to get source code for the given object and display it.\n'
|
|
jpayne@68
|
4140 '\n'
|
|
jpayne@68
|
4141 ' New in version 3.2.\n'
|
|
jpayne@68
|
4142 '\n'
|
|
jpayne@68
|
4143 'display [expression]\n'
|
|
jpayne@68
|
4144 '\n'
|
|
jpayne@68
|
4145 ' Display the value of the expression if it changed, each time\n'
|
|
jpayne@68
|
4146 ' execution stops in the current frame.\n'
|
|
jpayne@68
|
4147 '\n'
|
|
jpayne@68
|
4148 ' Without expression, list all display expressions for the '
|
|
jpayne@68
|
4149 'current\n'
|
|
jpayne@68
|
4150 ' frame.\n'
|
|
jpayne@68
|
4151 '\n'
|
|
jpayne@68
|
4152 ' New in version 3.2.\n'
|
|
jpayne@68
|
4153 '\n'
|
|
jpayne@68
|
4154 'undisplay [expression]\n'
|
|
jpayne@68
|
4155 '\n'
|
|
jpayne@68
|
4156 ' Do not display the expression any more in the current frame.\n'
|
|
jpayne@68
|
4157 ' Without expression, clear all display expressions for the '
|
|
jpayne@68
|
4158 'current\n'
|
|
jpayne@68
|
4159 ' frame.\n'
|
|
jpayne@68
|
4160 '\n'
|
|
jpayne@68
|
4161 ' New in version 3.2.\n'
|
|
jpayne@68
|
4162 '\n'
|
|
jpayne@68
|
4163 'interact\n'
|
|
jpayne@68
|
4164 '\n'
|
|
jpayne@68
|
4165 ' Start an interactive interpreter (using the "code" module) '
|
|
jpayne@68
|
4166 'whose\n'
|
|
jpayne@68
|
4167 ' global namespace contains all the (global and local) names '
|
|
jpayne@68
|
4168 'found in\n'
|
|
jpayne@68
|
4169 ' the current scope.\n'
|
|
jpayne@68
|
4170 '\n'
|
|
jpayne@68
|
4171 ' New in version 3.2.\n'
|
|
jpayne@68
|
4172 '\n'
|
|
jpayne@68
|
4173 'alias [name [command]]\n'
|
|
jpayne@68
|
4174 '\n'
|
|
jpayne@68
|
4175 ' Create an alias called *name* that executes *command*. The '
|
|
jpayne@68
|
4176 'command\n'
|
|
jpayne@68
|
4177 ' must *not* be enclosed in quotes. Replaceable parameters can '
|
|
jpayne@68
|
4178 'be\n'
|
|
jpayne@68
|
4179 ' indicated by "%1", "%2", and so on, while "%*" is replaced by '
|
|
jpayne@68
|
4180 'all\n'
|
|
jpayne@68
|
4181 ' the parameters. If no command is given, the current alias '
|
|
jpayne@68
|
4182 'for\n'
|
|
jpayne@68
|
4183 ' *name* is shown. If no arguments are given, all aliases are '
|
|
jpayne@68
|
4184 'listed.\n'
|
|
jpayne@68
|
4185 '\n'
|
|
jpayne@68
|
4186 ' Aliases may be nested and can contain anything that can be '
|
|
jpayne@68
|
4187 'legally\n'
|
|
jpayne@68
|
4188 ' typed at the pdb prompt. Note that internal pdb commands '
|
|
jpayne@68
|
4189 '*can* be\n'
|
|
jpayne@68
|
4190 ' overridden by aliases. Such a command is then hidden until '
|
|
jpayne@68
|
4191 'the\n'
|
|
jpayne@68
|
4192 ' alias is removed. Aliasing is recursively applied to the '
|
|
jpayne@68
|
4193 'first\n'
|
|
jpayne@68
|
4194 ' word of the command line; all other words in the line are '
|
|
jpayne@68
|
4195 'left\n'
|
|
jpayne@68
|
4196 ' alone.\n'
|
|
jpayne@68
|
4197 '\n'
|
|
jpayne@68
|
4198 ' As an example, here are two useful aliases (especially when '
|
|
jpayne@68
|
4199 'placed\n'
|
|
jpayne@68
|
4200 ' in the ".pdbrc" file):\n'
|
|
jpayne@68
|
4201 '\n'
|
|
jpayne@68
|
4202 ' # Print instance variables (usage "pi classInst")\n'
|
|
jpayne@68
|
4203 ' alias pi for k in %1.__dict__.keys(): '
|
|
jpayne@68
|
4204 'print("%1.",k,"=",%1.__dict__[k])\n'
|
|
jpayne@68
|
4205 ' # Print instance variables in self\n'
|
|
jpayne@68
|
4206 ' alias ps pi self\n'
|
|
jpayne@68
|
4207 '\n'
|
|
jpayne@68
|
4208 'unalias name\n'
|
|
jpayne@68
|
4209 '\n'
|
|
jpayne@68
|
4210 ' Delete the specified alias.\n'
|
|
jpayne@68
|
4211 '\n'
|
|
jpayne@68
|
4212 '! statement\n'
|
|
jpayne@68
|
4213 '\n'
|
|
jpayne@68
|
4214 ' Execute the (one-line) *statement* in the context of the '
|
|
jpayne@68
|
4215 'current\n'
|
|
jpayne@68
|
4216 ' stack frame. The exclamation point can be omitted unless the '
|
|
jpayne@68
|
4217 'first\n'
|
|
jpayne@68
|
4218 ' word of the statement resembles a debugger command. To set '
|
|
jpayne@68
|
4219 'a\n'
|
|
jpayne@68
|
4220 ' global variable, you can prefix the assignment command with '
|
|
jpayne@68
|
4221 'a\n'
|
|
jpayne@68
|
4222 ' "global" statement on the same line, e.g.:\n'
|
|
jpayne@68
|
4223 '\n'
|
|
jpayne@68
|
4224 " (Pdb) global list_options; list_options = ['-l']\n"
|
|
jpayne@68
|
4225 ' (Pdb)\n'
|
|
jpayne@68
|
4226 '\n'
|
|
jpayne@68
|
4227 'run [args ...]\n'
|
|
jpayne@68
|
4228 'restart [args ...]\n'
|
|
jpayne@68
|
4229 '\n'
|
|
jpayne@68
|
4230 ' Restart the debugged Python program. If an argument is '
|
|
jpayne@68
|
4231 'supplied,\n'
|
|
jpayne@68
|
4232 ' it is split with "shlex" and the result is used as the new\n'
|
|
jpayne@68
|
4233 ' "sys.argv". History, breakpoints, actions and debugger '
|
|
jpayne@68
|
4234 'options are\n'
|
|
jpayne@68
|
4235 ' preserved. "restart" is an alias for "run".\n'
|
|
jpayne@68
|
4236 '\n'
|
|
jpayne@68
|
4237 'q(uit)\n'
|
|
jpayne@68
|
4238 '\n'
|
|
jpayne@68
|
4239 ' Quit from the debugger. The program being executed is '
|
|
jpayne@68
|
4240 'aborted.\n'
|
|
jpayne@68
|
4241 '\n'
|
|
jpayne@68
|
4242 'debug code\n'
|
|
jpayne@68
|
4243 '\n'
|
|
jpayne@68
|
4244 ' Enter a recursive debugger that steps through the code '
|
|
jpayne@68
|
4245 'argument\n'
|
|
jpayne@68
|
4246 ' (which is an arbitrary expression or statement to be executed '
|
|
jpayne@68
|
4247 'in\n'
|
|
jpayne@68
|
4248 ' the current environment).\n'
|
|
jpayne@68
|
4249 '\n'
|
|
jpayne@68
|
4250 'retval\n'
|
|
jpayne@68
|
4251 'Print the return value for the last return of a function.\n'
|
|
jpayne@68
|
4252 '\n'
|
|
jpayne@68
|
4253 '-[ Footnotes ]-\n'
|
|
jpayne@68
|
4254 '\n'
|
|
jpayne@68
|
4255 '[1] Whether a frame is considered to originate in a certain '
|
|
jpayne@68
|
4256 'module\n'
|
|
jpayne@68
|
4257 ' is determined by the "__name__" in the frame globals.\n',
|
|
jpayne@68
|
4258 'del': 'The "del" statement\n'
|
|
jpayne@68
|
4259 '*******************\n'
|
|
jpayne@68
|
4260 '\n'
|
|
jpayne@68
|
4261 ' del_stmt ::= "del" target_list\n'
|
|
jpayne@68
|
4262 '\n'
|
|
jpayne@68
|
4263 'Deletion is recursively defined very similar to the way assignment '
|
|
jpayne@68
|
4264 'is\n'
|
|
jpayne@68
|
4265 'defined. Rather than spelling it out in full details, here are some\n'
|
|
jpayne@68
|
4266 'hints.\n'
|
|
jpayne@68
|
4267 '\n'
|
|
jpayne@68
|
4268 'Deletion of a target list recursively deletes each target, from left\n'
|
|
jpayne@68
|
4269 'to right.\n'
|
|
jpayne@68
|
4270 '\n'
|
|
jpayne@68
|
4271 'Deletion of a name removes the binding of that name from the local '
|
|
jpayne@68
|
4272 'or\n'
|
|
jpayne@68
|
4273 'global namespace, depending on whether the name occurs in a "global"\n'
|
|
jpayne@68
|
4274 'statement in the same code block. If the name is unbound, a\n'
|
|
jpayne@68
|
4275 '"NameError" exception will be raised.\n'
|
|
jpayne@68
|
4276 '\n'
|
|
jpayne@68
|
4277 'Deletion of attribute references, subscriptions and slicings is '
|
|
jpayne@68
|
4278 'passed\n'
|
|
jpayne@68
|
4279 'to the primary object involved; deletion of a slicing is in general\n'
|
|
jpayne@68
|
4280 'equivalent to assignment of an empty slice of the right type (but '
|
|
jpayne@68
|
4281 'even\n'
|
|
jpayne@68
|
4282 'this is determined by the sliced object).\n'
|
|
jpayne@68
|
4283 '\n'
|
|
jpayne@68
|
4284 'Changed in version 3.2: Previously it was illegal to delete a name\n'
|
|
jpayne@68
|
4285 'from the local namespace if it occurs as a free variable in a nested\n'
|
|
jpayne@68
|
4286 'block.\n',
|
|
jpayne@68
|
4287 'dict': 'Dictionary displays\n'
|
|
jpayne@68
|
4288 '*******************\n'
|
|
jpayne@68
|
4289 '\n'
|
|
jpayne@68
|
4290 'A dictionary display is a possibly empty series of key/datum pairs\n'
|
|
jpayne@68
|
4291 'enclosed in curly braces:\n'
|
|
jpayne@68
|
4292 '\n'
|
|
jpayne@68
|
4293 ' dict_display ::= "{" [key_datum_list | dict_comprehension] '
|
|
jpayne@68
|
4294 '"}"\n'
|
|
jpayne@68
|
4295 ' key_datum_list ::= key_datum ("," key_datum)* [","]\n'
|
|
jpayne@68
|
4296 ' key_datum ::= expression ":" expression | "**" or_expr\n'
|
|
jpayne@68
|
4297 ' dict_comprehension ::= expression ":" expression comp_for\n'
|
|
jpayne@68
|
4298 '\n'
|
|
jpayne@68
|
4299 'A dictionary display yields a new dictionary object.\n'
|
|
jpayne@68
|
4300 '\n'
|
|
jpayne@68
|
4301 'If a comma-separated sequence of key/datum pairs is given, they are\n'
|
|
jpayne@68
|
4302 'evaluated from left to right to define the entries of the '
|
|
jpayne@68
|
4303 'dictionary:\n'
|
|
jpayne@68
|
4304 'each key object is used as a key into the dictionary to store the\n'
|
|
jpayne@68
|
4305 'corresponding datum. This means that you can specify the same key\n'
|
|
jpayne@68
|
4306 'multiple times in the key/datum list, and the final dictionary’s '
|
|
jpayne@68
|
4307 'value\n'
|
|
jpayne@68
|
4308 'for that key will be the last one given.\n'
|
|
jpayne@68
|
4309 '\n'
|
|
jpayne@68
|
4310 'A double asterisk "**" denotes *dictionary unpacking*. Its operand\n'
|
|
jpayne@68
|
4311 'must be a *mapping*. Each mapping item is added to the new\n'
|
|
jpayne@68
|
4312 'dictionary. Later values replace values already set by earlier\n'
|
|
jpayne@68
|
4313 'key/datum pairs and earlier dictionary unpackings.\n'
|
|
jpayne@68
|
4314 '\n'
|
|
jpayne@68
|
4315 'New in version 3.5: Unpacking into dictionary displays, originally\n'
|
|
jpayne@68
|
4316 'proposed by **PEP 448**.\n'
|
|
jpayne@68
|
4317 '\n'
|
|
jpayne@68
|
4318 'A dict comprehension, in contrast to list and set comprehensions,\n'
|
|
jpayne@68
|
4319 'needs two expressions separated with a colon followed by the usual\n'
|
|
jpayne@68
|
4320 '“for” and “if” clauses. When the comprehension is run, the '
|
|
jpayne@68
|
4321 'resulting\n'
|
|
jpayne@68
|
4322 'key and value elements are inserted in the new dictionary in the '
|
|
jpayne@68
|
4323 'order\n'
|
|
jpayne@68
|
4324 'they are produced.\n'
|
|
jpayne@68
|
4325 '\n'
|
|
jpayne@68
|
4326 'Restrictions on the types of the key values are listed earlier in\n'
|
|
jpayne@68
|
4327 'section The standard type hierarchy. (To summarize, the key type\n'
|
|
jpayne@68
|
4328 'should be *hashable*, which excludes all mutable objects.) Clashes\n'
|
|
jpayne@68
|
4329 'between duplicate keys are not detected; the last datum (textually\n'
|
|
jpayne@68
|
4330 'rightmost in the display) stored for a given key value prevails.\n'
|
|
jpayne@68
|
4331 '\n'
|
|
jpayne@68
|
4332 'Changed in version 3.8: Prior to Python 3.8, in dict '
|
|
jpayne@68
|
4333 'comprehensions,\n'
|
|
jpayne@68
|
4334 'the evaluation order of key and value was not well-defined. In\n'
|
|
jpayne@68
|
4335 'CPython, the value was evaluated before the key. Starting with '
|
|
jpayne@68
|
4336 '3.8,\n'
|
|
jpayne@68
|
4337 'the key is evaluated before the value, as proposed by **PEP 572**.\n',
|
|
jpayne@68
|
4338 'dynamic-features': 'Interaction with dynamic features\n'
|
|
jpayne@68
|
4339 '*********************************\n'
|
|
jpayne@68
|
4340 '\n'
|
|
jpayne@68
|
4341 'Name resolution of free variables occurs at runtime, not '
|
|
jpayne@68
|
4342 'at compile\n'
|
|
jpayne@68
|
4343 'time. This means that the following code will print 42:\n'
|
|
jpayne@68
|
4344 '\n'
|
|
jpayne@68
|
4345 ' i = 10\n'
|
|
jpayne@68
|
4346 ' def f():\n'
|
|
jpayne@68
|
4347 ' print(i)\n'
|
|
jpayne@68
|
4348 ' i = 42\n'
|
|
jpayne@68
|
4349 ' f()\n'
|
|
jpayne@68
|
4350 '\n'
|
|
jpayne@68
|
4351 'The "eval()" and "exec()" functions do not have access '
|
|
jpayne@68
|
4352 'to the full\n'
|
|
jpayne@68
|
4353 'environment for resolving names. Names may be resolved '
|
|
jpayne@68
|
4354 'in the local\n'
|
|
jpayne@68
|
4355 'and global namespaces of the caller. Free variables are '
|
|
jpayne@68
|
4356 'not resolved\n'
|
|
jpayne@68
|
4357 'in the nearest enclosing namespace, but in the global '
|
|
jpayne@68
|
4358 'namespace. [1]\n'
|
|
jpayne@68
|
4359 'The "exec()" and "eval()" functions have optional '
|
|
jpayne@68
|
4360 'arguments to\n'
|
|
jpayne@68
|
4361 'override the global and local namespace. If only one '
|
|
jpayne@68
|
4362 'namespace is\n'
|
|
jpayne@68
|
4363 'specified, it is used for both.\n',
|
|
jpayne@68
|
4364 'else': 'The "if" statement\n'
|
|
jpayne@68
|
4365 '******************\n'
|
|
jpayne@68
|
4366 '\n'
|
|
jpayne@68
|
4367 'The "if" statement is used for conditional execution:\n'
|
|
jpayne@68
|
4368 '\n'
|
|
jpayne@68
|
4369 ' if_stmt ::= "if" expression ":" suite\n'
|
|
jpayne@68
|
4370 ' ("elif" expression ":" suite)*\n'
|
|
jpayne@68
|
4371 ' ["else" ":" suite]\n'
|
|
jpayne@68
|
4372 '\n'
|
|
jpayne@68
|
4373 'It selects exactly one of the suites by evaluating the expressions '
|
|
jpayne@68
|
4374 'one\n'
|
|
jpayne@68
|
4375 'by one until one is found to be true (see section Boolean '
|
|
jpayne@68
|
4376 'operations\n'
|
|
jpayne@68
|
4377 'for the definition of true and false); then that suite is executed\n'
|
|
jpayne@68
|
4378 '(and no other part of the "if" statement is executed or evaluated).\n'
|
|
jpayne@68
|
4379 'If all expressions are false, the suite of the "else" clause, if\n'
|
|
jpayne@68
|
4380 'present, is executed.\n',
|
|
jpayne@68
|
4381 'exceptions': 'Exceptions\n'
|
|
jpayne@68
|
4382 '**********\n'
|
|
jpayne@68
|
4383 '\n'
|
|
jpayne@68
|
4384 'Exceptions are a means of breaking out of the normal flow of '
|
|
jpayne@68
|
4385 'control\n'
|
|
jpayne@68
|
4386 'of a code block in order to handle errors or other '
|
|
jpayne@68
|
4387 'exceptional\n'
|
|
jpayne@68
|
4388 'conditions. An exception is *raised* at the point where the '
|
|
jpayne@68
|
4389 'error is\n'
|
|
jpayne@68
|
4390 'detected; it may be *handled* by the surrounding code block or '
|
|
jpayne@68
|
4391 'by any\n'
|
|
jpayne@68
|
4392 'code block that directly or indirectly invoked the code block '
|
|
jpayne@68
|
4393 'where\n'
|
|
jpayne@68
|
4394 'the error occurred.\n'
|
|
jpayne@68
|
4395 '\n'
|
|
jpayne@68
|
4396 'The Python interpreter raises an exception when it detects a '
|
|
jpayne@68
|
4397 'run-time\n'
|
|
jpayne@68
|
4398 'error (such as division by zero). A Python program can also\n'
|
|
jpayne@68
|
4399 'explicitly raise an exception with the "raise" statement. '
|
|
jpayne@68
|
4400 'Exception\n'
|
|
jpayne@68
|
4401 'handlers are specified with the "try" … "except" statement. '
|
|
jpayne@68
|
4402 'The\n'
|
|
jpayne@68
|
4403 '"finally" clause of such a statement can be used to specify '
|
|
jpayne@68
|
4404 'cleanup\n'
|
|
jpayne@68
|
4405 'code which does not handle the exception, but is executed '
|
|
jpayne@68
|
4406 'whether an\n'
|
|
jpayne@68
|
4407 'exception occurred or not in the preceding code.\n'
|
|
jpayne@68
|
4408 '\n'
|
|
jpayne@68
|
4409 'Python uses the “termination” model of error handling: an '
|
|
jpayne@68
|
4410 'exception\n'
|
|
jpayne@68
|
4411 'handler can find out what happened and continue execution at '
|
|
jpayne@68
|
4412 'an outer\n'
|
|
jpayne@68
|
4413 'level, but it cannot repair the cause of the error and retry '
|
|
jpayne@68
|
4414 'the\n'
|
|
jpayne@68
|
4415 'failing operation (except by re-entering the offending piece '
|
|
jpayne@68
|
4416 'of code\n'
|
|
jpayne@68
|
4417 'from the top).\n'
|
|
jpayne@68
|
4418 '\n'
|
|
jpayne@68
|
4419 'When an exception is not handled at all, the interpreter '
|
|
jpayne@68
|
4420 'terminates\n'
|
|
jpayne@68
|
4421 'execution of the program, or returns to its interactive main '
|
|
jpayne@68
|
4422 'loop. In\n'
|
|
jpayne@68
|
4423 'either case, it prints a stack traceback, except when the '
|
|
jpayne@68
|
4424 'exception is\n'
|
|
jpayne@68
|
4425 '"SystemExit".\n'
|
|
jpayne@68
|
4426 '\n'
|
|
jpayne@68
|
4427 'Exceptions are identified by class instances. The "except" '
|
|
jpayne@68
|
4428 'clause is\n'
|
|
jpayne@68
|
4429 'selected depending on the class of the instance: it must '
|
|
jpayne@68
|
4430 'reference the\n'
|
|
jpayne@68
|
4431 'class of the instance or a base class thereof. The instance '
|
|
jpayne@68
|
4432 'can be\n'
|
|
jpayne@68
|
4433 'received by the handler and can carry additional information '
|
|
jpayne@68
|
4434 'about the\n'
|
|
jpayne@68
|
4435 'exceptional condition.\n'
|
|
jpayne@68
|
4436 '\n'
|
|
jpayne@68
|
4437 'Note: Exception messages are not part of the Python API. '
|
|
jpayne@68
|
4438 'Their\n'
|
|
jpayne@68
|
4439 ' contents may change from one version of Python to the next '
|
|
jpayne@68
|
4440 'without\n'
|
|
jpayne@68
|
4441 ' warning and should not be relied on by code which will run '
|
|
jpayne@68
|
4442 'under\n'
|
|
jpayne@68
|
4443 ' multiple versions of the interpreter.\n'
|
|
jpayne@68
|
4444 '\n'
|
|
jpayne@68
|
4445 'See also the description of the "try" statement in section The '
|
|
jpayne@68
|
4446 'try\n'
|
|
jpayne@68
|
4447 'statement and "raise" statement in section The raise '
|
|
jpayne@68
|
4448 'statement.\n'
|
|
jpayne@68
|
4449 '\n'
|
|
jpayne@68
|
4450 '-[ Footnotes ]-\n'
|
|
jpayne@68
|
4451 '\n'
|
|
jpayne@68
|
4452 '[1] This limitation occurs because the code that is executed '
|
|
jpayne@68
|
4453 'by\n'
|
|
jpayne@68
|
4454 ' these operations is not available at the time the module '
|
|
jpayne@68
|
4455 'is\n'
|
|
jpayne@68
|
4456 ' compiled.\n',
|
|
jpayne@68
|
4457 'execmodel': 'Execution model\n'
|
|
jpayne@68
|
4458 '***************\n'
|
|
jpayne@68
|
4459 '\n'
|
|
jpayne@68
|
4460 '\n'
|
|
jpayne@68
|
4461 'Structure of a program\n'
|
|
jpayne@68
|
4462 '======================\n'
|
|
jpayne@68
|
4463 '\n'
|
|
jpayne@68
|
4464 'A Python program is constructed from code blocks. A *block* is '
|
|
jpayne@68
|
4465 'a piece\n'
|
|
jpayne@68
|
4466 'of Python program text that is executed as a unit. The '
|
|
jpayne@68
|
4467 'following are\n'
|
|
jpayne@68
|
4468 'blocks: a module, a function body, and a class definition. '
|
|
jpayne@68
|
4469 'Each\n'
|
|
jpayne@68
|
4470 'command typed interactively is a block. A script file (a file '
|
|
jpayne@68
|
4471 'given\n'
|
|
jpayne@68
|
4472 'as standard input to the interpreter or specified as a command '
|
|
jpayne@68
|
4473 'line\n'
|
|
jpayne@68
|
4474 'argument to the interpreter) is a code block. A script command '
|
|
jpayne@68
|
4475 '(a\n'
|
|
jpayne@68
|
4476 'command specified on the interpreter command line with the '
|
|
jpayne@68
|
4477 '"-c"\n'
|
|
jpayne@68
|
4478 'option) is a code block. The string argument passed to the '
|
|
jpayne@68
|
4479 'built-in\n'
|
|
jpayne@68
|
4480 'functions "eval()" and "exec()" is a code block.\n'
|
|
jpayne@68
|
4481 '\n'
|
|
jpayne@68
|
4482 'A code block is executed in an *execution frame*. A frame '
|
|
jpayne@68
|
4483 'contains\n'
|
|
jpayne@68
|
4484 'some administrative information (used for debugging) and '
|
|
jpayne@68
|
4485 'determines\n'
|
|
jpayne@68
|
4486 'where and how execution continues after the code block’s '
|
|
jpayne@68
|
4487 'execution has\n'
|
|
jpayne@68
|
4488 'completed.\n'
|
|
jpayne@68
|
4489 '\n'
|
|
jpayne@68
|
4490 '\n'
|
|
jpayne@68
|
4491 'Naming and binding\n'
|
|
jpayne@68
|
4492 '==================\n'
|
|
jpayne@68
|
4493 '\n'
|
|
jpayne@68
|
4494 '\n'
|
|
jpayne@68
|
4495 'Binding of names\n'
|
|
jpayne@68
|
4496 '----------------\n'
|
|
jpayne@68
|
4497 '\n'
|
|
jpayne@68
|
4498 '*Names* refer to objects. Names are introduced by name '
|
|
jpayne@68
|
4499 'binding\n'
|
|
jpayne@68
|
4500 'operations.\n'
|
|
jpayne@68
|
4501 '\n'
|
|
jpayne@68
|
4502 'The following constructs bind names: formal parameters to '
|
|
jpayne@68
|
4503 'functions,\n'
|
|
jpayne@68
|
4504 '"import" statements, class and function definitions (these bind '
|
|
jpayne@68
|
4505 'the\n'
|
|
jpayne@68
|
4506 'class or function name in the defining block), and targets that '
|
|
jpayne@68
|
4507 'are\n'
|
|
jpayne@68
|
4508 'identifiers if occurring in an assignment, "for" loop header, '
|
|
jpayne@68
|
4509 'or after\n'
|
|
jpayne@68
|
4510 '"as" in a "with" statement or "except" clause. The "import" '
|
|
jpayne@68
|
4511 'statement\n'
|
|
jpayne@68
|
4512 'of the form "from ... import *" binds all names defined in the\n'
|
|
jpayne@68
|
4513 'imported module, except those beginning with an underscore. '
|
|
jpayne@68
|
4514 'This form\n'
|
|
jpayne@68
|
4515 'may only be used at the module level.\n'
|
|
jpayne@68
|
4516 '\n'
|
|
jpayne@68
|
4517 'A target occurring in a "del" statement is also considered '
|
|
jpayne@68
|
4518 'bound for\n'
|
|
jpayne@68
|
4519 'this purpose (though the actual semantics are to unbind the '
|
|
jpayne@68
|
4520 'name).\n'
|
|
jpayne@68
|
4521 '\n'
|
|
jpayne@68
|
4522 'Each assignment or import statement occurs within a block '
|
|
jpayne@68
|
4523 'defined by a\n'
|
|
jpayne@68
|
4524 'class or function definition or at the module level (the '
|
|
jpayne@68
|
4525 'top-level\n'
|
|
jpayne@68
|
4526 'code block).\n'
|
|
jpayne@68
|
4527 '\n'
|
|
jpayne@68
|
4528 'If a name is bound in a block, it is a local variable of that '
|
|
jpayne@68
|
4529 'block,\n'
|
|
jpayne@68
|
4530 'unless declared as "nonlocal" or "global". If a name is bound '
|
|
jpayne@68
|
4531 'at the\n'
|
|
jpayne@68
|
4532 'module level, it is a global variable. (The variables of the '
|
|
jpayne@68
|
4533 'module\n'
|
|
jpayne@68
|
4534 'code block are local and global.) If a variable is used in a '
|
|
jpayne@68
|
4535 'code\n'
|
|
jpayne@68
|
4536 'block but not defined there, it is a *free variable*.\n'
|
|
jpayne@68
|
4537 '\n'
|
|
jpayne@68
|
4538 'Each occurrence of a name in the program text refers to the '
|
|
jpayne@68
|
4539 '*binding*\n'
|
|
jpayne@68
|
4540 'of that name established by the following name resolution '
|
|
jpayne@68
|
4541 'rules.\n'
|
|
jpayne@68
|
4542 '\n'
|
|
jpayne@68
|
4543 '\n'
|
|
jpayne@68
|
4544 'Resolution of names\n'
|
|
jpayne@68
|
4545 '-------------------\n'
|
|
jpayne@68
|
4546 '\n'
|
|
jpayne@68
|
4547 'A *scope* defines the visibility of a name within a block. If '
|
|
jpayne@68
|
4548 'a local\n'
|
|
jpayne@68
|
4549 'variable is defined in a block, its scope includes that block. '
|
|
jpayne@68
|
4550 'If the\n'
|
|
jpayne@68
|
4551 'definition occurs in a function block, the scope extends to any '
|
|
jpayne@68
|
4552 'blocks\n'
|
|
jpayne@68
|
4553 'contained within the defining one, unless a contained block '
|
|
jpayne@68
|
4554 'introduces\n'
|
|
jpayne@68
|
4555 'a different binding for the name.\n'
|
|
jpayne@68
|
4556 '\n'
|
|
jpayne@68
|
4557 'When a name is used in a code block, it is resolved using the '
|
|
jpayne@68
|
4558 'nearest\n'
|
|
jpayne@68
|
4559 'enclosing scope. The set of all such scopes visible to a code '
|
|
jpayne@68
|
4560 'block\n'
|
|
jpayne@68
|
4561 'is called the block’s *environment*.\n'
|
|
jpayne@68
|
4562 '\n'
|
|
jpayne@68
|
4563 'When a name is not found at all, a "NameError" exception is '
|
|
jpayne@68
|
4564 'raised. If\n'
|
|
jpayne@68
|
4565 'the current scope is a function scope, and the name refers to a '
|
|
jpayne@68
|
4566 'local\n'
|
|
jpayne@68
|
4567 'variable that has not yet been bound to a value at the point '
|
|
jpayne@68
|
4568 'where the\n'
|
|
jpayne@68
|
4569 'name is used, an "UnboundLocalError" exception is raised.\n'
|
|
jpayne@68
|
4570 '"UnboundLocalError" is a subclass of "NameError".\n'
|
|
jpayne@68
|
4571 '\n'
|
|
jpayne@68
|
4572 'If a name binding operation occurs anywhere within a code '
|
|
jpayne@68
|
4573 'block, all\n'
|
|
jpayne@68
|
4574 'uses of the name within the block are treated as references to '
|
|
jpayne@68
|
4575 'the\n'
|
|
jpayne@68
|
4576 'current block. This can lead to errors when a name is used '
|
|
jpayne@68
|
4577 'within a\n'
|
|
jpayne@68
|
4578 'block before it is bound. This rule is subtle. Python lacks\n'
|
|
jpayne@68
|
4579 'declarations and allows name binding operations to occur '
|
|
jpayne@68
|
4580 'anywhere\n'
|
|
jpayne@68
|
4581 'within a code block. The local variables of a code block can '
|
|
jpayne@68
|
4582 'be\n'
|
|
jpayne@68
|
4583 'determined by scanning the entire text of the block for name '
|
|
jpayne@68
|
4584 'binding\n'
|
|
jpayne@68
|
4585 'operations.\n'
|
|
jpayne@68
|
4586 '\n'
|
|
jpayne@68
|
4587 'If the "global" statement occurs within a block, all uses of '
|
|
jpayne@68
|
4588 'the name\n'
|
|
jpayne@68
|
4589 'specified in the statement refer to the binding of that name in '
|
|
jpayne@68
|
4590 'the\n'
|
|
jpayne@68
|
4591 'top-level namespace. Names are resolved in the top-level '
|
|
jpayne@68
|
4592 'namespace by\n'
|
|
jpayne@68
|
4593 'searching the global namespace, i.e. the namespace of the '
|
|
jpayne@68
|
4594 'module\n'
|
|
jpayne@68
|
4595 'containing the code block, and the builtins namespace, the '
|
|
jpayne@68
|
4596 'namespace\n'
|
|
jpayne@68
|
4597 'of the module "builtins". The global namespace is searched '
|
|
jpayne@68
|
4598 'first. If\n'
|
|
jpayne@68
|
4599 'the name is not found there, the builtins namespace is '
|
|
jpayne@68
|
4600 'searched. The\n'
|
|
jpayne@68
|
4601 '"global" statement must precede all uses of the name.\n'
|
|
jpayne@68
|
4602 '\n'
|
|
jpayne@68
|
4603 'The "global" statement has the same scope as a name binding '
|
|
jpayne@68
|
4604 'operation\n'
|
|
jpayne@68
|
4605 'in the same block. If the nearest enclosing scope for a free '
|
|
jpayne@68
|
4606 'variable\n'
|
|
jpayne@68
|
4607 'contains a global statement, the free variable is treated as a '
|
|
jpayne@68
|
4608 'global.\n'
|
|
jpayne@68
|
4609 '\n'
|
|
jpayne@68
|
4610 'The "nonlocal" statement causes corresponding names to refer '
|
|
jpayne@68
|
4611 'to\n'
|
|
jpayne@68
|
4612 'previously bound variables in the nearest enclosing function '
|
|
jpayne@68
|
4613 'scope.\n'
|
|
jpayne@68
|
4614 '"SyntaxError" is raised at compile time if the given name does '
|
|
jpayne@68
|
4615 'not\n'
|
|
jpayne@68
|
4616 'exist in any enclosing function scope.\n'
|
|
jpayne@68
|
4617 '\n'
|
|
jpayne@68
|
4618 'The namespace for a module is automatically created the first '
|
|
jpayne@68
|
4619 'time a\n'
|
|
jpayne@68
|
4620 'module is imported. The main module for a script is always '
|
|
jpayne@68
|
4621 'called\n'
|
|
jpayne@68
|
4622 '"__main__".\n'
|
|
jpayne@68
|
4623 '\n'
|
|
jpayne@68
|
4624 'Class definition blocks and arguments to "exec()" and "eval()" '
|
|
jpayne@68
|
4625 'are\n'
|
|
jpayne@68
|
4626 'special in the context of name resolution. A class definition '
|
|
jpayne@68
|
4627 'is an\n'
|
|
jpayne@68
|
4628 'executable statement that may use and define names. These '
|
|
jpayne@68
|
4629 'references\n'
|
|
jpayne@68
|
4630 'follow the normal rules for name resolution with an exception '
|
|
jpayne@68
|
4631 'that\n'
|
|
jpayne@68
|
4632 'unbound local variables are looked up in the global namespace. '
|
|
jpayne@68
|
4633 'The\n'
|
|
jpayne@68
|
4634 'namespace of the class definition becomes the attribute '
|
|
jpayne@68
|
4635 'dictionary of\n'
|
|
jpayne@68
|
4636 'the class. The scope of names defined in a class block is '
|
|
jpayne@68
|
4637 'limited to\n'
|
|
jpayne@68
|
4638 'the class block; it does not extend to the code blocks of '
|
|
jpayne@68
|
4639 'methods –\n'
|
|
jpayne@68
|
4640 'this includes comprehensions and generator expressions since '
|
|
jpayne@68
|
4641 'they are\n'
|
|
jpayne@68
|
4642 'implemented using a function scope. This means that the '
|
|
jpayne@68
|
4643 'following\n'
|
|
jpayne@68
|
4644 'will fail:\n'
|
|
jpayne@68
|
4645 '\n'
|
|
jpayne@68
|
4646 ' class A:\n'
|
|
jpayne@68
|
4647 ' a = 42\n'
|
|
jpayne@68
|
4648 ' b = list(a + i for i in range(10))\n'
|
|
jpayne@68
|
4649 '\n'
|
|
jpayne@68
|
4650 '\n'
|
|
jpayne@68
|
4651 'Builtins and restricted execution\n'
|
|
jpayne@68
|
4652 '---------------------------------\n'
|
|
jpayne@68
|
4653 '\n'
|
|
jpayne@68
|
4654 '**CPython implementation detail:** Users should not touch\n'
|
|
jpayne@68
|
4655 '"__builtins__"; it is strictly an implementation detail. '
|
|
jpayne@68
|
4656 'Users\n'
|
|
jpayne@68
|
4657 'wanting to override values in the builtins namespace should '
|
|
jpayne@68
|
4658 '"import"\n'
|
|
jpayne@68
|
4659 'the "builtins" module and modify its attributes appropriately.\n'
|
|
jpayne@68
|
4660 '\n'
|
|
jpayne@68
|
4661 'The builtins namespace associated with the execution of a code '
|
|
jpayne@68
|
4662 'block\n'
|
|
jpayne@68
|
4663 'is actually found by looking up the name "__builtins__" in its '
|
|
jpayne@68
|
4664 'global\n'
|
|
jpayne@68
|
4665 'namespace; this should be a dictionary or a module (in the '
|
|
jpayne@68
|
4666 'latter case\n'
|
|
jpayne@68
|
4667 'the module’s dictionary is used). By default, when in the '
|
|
jpayne@68
|
4668 '"__main__"\n'
|
|
jpayne@68
|
4669 'module, "__builtins__" is the built-in module "builtins"; when '
|
|
jpayne@68
|
4670 'in any\n'
|
|
jpayne@68
|
4671 'other module, "__builtins__" is an alias for the dictionary of '
|
|
jpayne@68
|
4672 'the\n'
|
|
jpayne@68
|
4673 '"builtins" module itself.\n'
|
|
jpayne@68
|
4674 '\n'
|
|
jpayne@68
|
4675 '\n'
|
|
jpayne@68
|
4676 'Interaction with dynamic features\n'
|
|
jpayne@68
|
4677 '---------------------------------\n'
|
|
jpayne@68
|
4678 '\n'
|
|
jpayne@68
|
4679 'Name resolution of free variables occurs at runtime, not at '
|
|
jpayne@68
|
4680 'compile\n'
|
|
jpayne@68
|
4681 'time. This means that the following code will print 42:\n'
|
|
jpayne@68
|
4682 '\n'
|
|
jpayne@68
|
4683 ' i = 10\n'
|
|
jpayne@68
|
4684 ' def f():\n'
|
|
jpayne@68
|
4685 ' print(i)\n'
|
|
jpayne@68
|
4686 ' i = 42\n'
|
|
jpayne@68
|
4687 ' f()\n'
|
|
jpayne@68
|
4688 '\n'
|
|
jpayne@68
|
4689 'The "eval()" and "exec()" functions do not have access to the '
|
|
jpayne@68
|
4690 'full\n'
|
|
jpayne@68
|
4691 'environment for resolving names. Names may be resolved in the '
|
|
jpayne@68
|
4692 'local\n'
|
|
jpayne@68
|
4693 'and global namespaces of the caller. Free variables are not '
|
|
jpayne@68
|
4694 'resolved\n'
|
|
jpayne@68
|
4695 'in the nearest enclosing namespace, but in the global '
|
|
jpayne@68
|
4696 'namespace. [1]\n'
|
|
jpayne@68
|
4697 'The "exec()" and "eval()" functions have optional arguments to\n'
|
|
jpayne@68
|
4698 'override the global and local namespace. If only one namespace '
|
|
jpayne@68
|
4699 'is\n'
|
|
jpayne@68
|
4700 'specified, it is used for both.\n'
|
|
jpayne@68
|
4701 '\n'
|
|
jpayne@68
|
4702 '\n'
|
|
jpayne@68
|
4703 'Exceptions\n'
|
|
jpayne@68
|
4704 '==========\n'
|
|
jpayne@68
|
4705 '\n'
|
|
jpayne@68
|
4706 'Exceptions are a means of breaking out of the normal flow of '
|
|
jpayne@68
|
4707 'control\n'
|
|
jpayne@68
|
4708 'of a code block in order to handle errors or other exceptional\n'
|
|
jpayne@68
|
4709 'conditions. An exception is *raised* at the point where the '
|
|
jpayne@68
|
4710 'error is\n'
|
|
jpayne@68
|
4711 'detected; it may be *handled* by the surrounding code block or '
|
|
jpayne@68
|
4712 'by any\n'
|
|
jpayne@68
|
4713 'code block that directly or indirectly invoked the code block '
|
|
jpayne@68
|
4714 'where\n'
|
|
jpayne@68
|
4715 'the error occurred.\n'
|
|
jpayne@68
|
4716 '\n'
|
|
jpayne@68
|
4717 'The Python interpreter raises an exception when it detects a '
|
|
jpayne@68
|
4718 'run-time\n'
|
|
jpayne@68
|
4719 'error (such as division by zero). A Python program can also\n'
|
|
jpayne@68
|
4720 'explicitly raise an exception with the "raise" statement. '
|
|
jpayne@68
|
4721 'Exception\n'
|
|
jpayne@68
|
4722 'handlers are specified with the "try" … "except" statement. '
|
|
jpayne@68
|
4723 'The\n'
|
|
jpayne@68
|
4724 '"finally" clause of such a statement can be used to specify '
|
|
jpayne@68
|
4725 'cleanup\n'
|
|
jpayne@68
|
4726 'code which does not handle the exception, but is executed '
|
|
jpayne@68
|
4727 'whether an\n'
|
|
jpayne@68
|
4728 'exception occurred or not in the preceding code.\n'
|
|
jpayne@68
|
4729 '\n'
|
|
jpayne@68
|
4730 'Python uses the “termination” model of error handling: an '
|
|
jpayne@68
|
4731 'exception\n'
|
|
jpayne@68
|
4732 'handler can find out what happened and continue execution at an '
|
|
jpayne@68
|
4733 'outer\n'
|
|
jpayne@68
|
4734 'level, but it cannot repair the cause of the error and retry '
|
|
jpayne@68
|
4735 'the\n'
|
|
jpayne@68
|
4736 'failing operation (except by re-entering the offending piece of '
|
|
jpayne@68
|
4737 'code\n'
|
|
jpayne@68
|
4738 'from the top).\n'
|
|
jpayne@68
|
4739 '\n'
|
|
jpayne@68
|
4740 'When an exception is not handled at all, the interpreter '
|
|
jpayne@68
|
4741 'terminates\n'
|
|
jpayne@68
|
4742 'execution of the program, or returns to its interactive main '
|
|
jpayne@68
|
4743 'loop. In\n'
|
|
jpayne@68
|
4744 'either case, it prints a stack traceback, except when the '
|
|
jpayne@68
|
4745 'exception is\n'
|
|
jpayne@68
|
4746 '"SystemExit".\n'
|
|
jpayne@68
|
4747 '\n'
|
|
jpayne@68
|
4748 'Exceptions are identified by class instances. The "except" '
|
|
jpayne@68
|
4749 'clause is\n'
|
|
jpayne@68
|
4750 'selected depending on the class of the instance: it must '
|
|
jpayne@68
|
4751 'reference the\n'
|
|
jpayne@68
|
4752 'class of the instance or a base class thereof. The instance '
|
|
jpayne@68
|
4753 'can be\n'
|
|
jpayne@68
|
4754 'received by the handler and can carry additional information '
|
|
jpayne@68
|
4755 'about the\n'
|
|
jpayne@68
|
4756 'exceptional condition.\n'
|
|
jpayne@68
|
4757 '\n'
|
|
jpayne@68
|
4758 'Note: Exception messages are not part of the Python API. '
|
|
jpayne@68
|
4759 'Their\n'
|
|
jpayne@68
|
4760 ' contents may change from one version of Python to the next '
|
|
jpayne@68
|
4761 'without\n'
|
|
jpayne@68
|
4762 ' warning and should not be relied on by code which will run '
|
|
jpayne@68
|
4763 'under\n'
|
|
jpayne@68
|
4764 ' multiple versions of the interpreter.\n'
|
|
jpayne@68
|
4765 '\n'
|
|
jpayne@68
|
4766 'See also the description of the "try" statement in section The '
|
|
jpayne@68
|
4767 'try\n'
|
|
jpayne@68
|
4768 'statement and "raise" statement in section The raise '
|
|
jpayne@68
|
4769 'statement.\n'
|
|
jpayne@68
|
4770 '\n'
|
|
jpayne@68
|
4771 '-[ Footnotes ]-\n'
|
|
jpayne@68
|
4772 '\n'
|
|
jpayne@68
|
4773 '[1] This limitation occurs because the code that is executed '
|
|
jpayne@68
|
4774 'by\n'
|
|
jpayne@68
|
4775 ' these operations is not available at the time the module '
|
|
jpayne@68
|
4776 'is\n'
|
|
jpayne@68
|
4777 ' compiled.\n',
|
|
jpayne@68
|
4778 'exprlists': 'Expression lists\n'
|
|
jpayne@68
|
4779 '****************\n'
|
|
jpayne@68
|
4780 '\n'
|
|
jpayne@68
|
4781 ' expression_list ::= expression ("," expression)* [","]\n'
|
|
jpayne@68
|
4782 ' starred_list ::= starred_item ("," starred_item)* '
|
|
jpayne@68
|
4783 '[","]\n'
|
|
jpayne@68
|
4784 ' starred_expression ::= expression | (starred_item ",")* '
|
|
jpayne@68
|
4785 '[starred_item]\n'
|
|
jpayne@68
|
4786 ' starred_item ::= expression | "*" or_expr\n'
|
|
jpayne@68
|
4787 '\n'
|
|
jpayne@68
|
4788 'Except when part of a list or set display, an expression list\n'
|
|
jpayne@68
|
4789 'containing at least one comma yields a tuple. The length of '
|
|
jpayne@68
|
4790 'the tuple\n'
|
|
jpayne@68
|
4791 'is the number of expressions in the list. The expressions are\n'
|
|
jpayne@68
|
4792 'evaluated from left to right.\n'
|
|
jpayne@68
|
4793 '\n'
|
|
jpayne@68
|
4794 'An asterisk "*" denotes *iterable unpacking*. Its operand must '
|
|
jpayne@68
|
4795 'be an\n'
|
|
jpayne@68
|
4796 '*iterable*. The iterable is expanded into a sequence of items, '
|
|
jpayne@68
|
4797 'which\n'
|
|
jpayne@68
|
4798 'are included in the new tuple, list, or set, at the site of '
|
|
jpayne@68
|
4799 'the\n'
|
|
jpayne@68
|
4800 'unpacking.\n'
|
|
jpayne@68
|
4801 '\n'
|
|
jpayne@68
|
4802 'New in version 3.5: Iterable unpacking in expression lists, '
|
|
jpayne@68
|
4803 'originally\n'
|
|
jpayne@68
|
4804 'proposed by **PEP 448**.\n'
|
|
jpayne@68
|
4805 '\n'
|
|
jpayne@68
|
4806 'The trailing comma is required only to create a single tuple '
|
|
jpayne@68
|
4807 '(a.k.a. a\n'
|
|
jpayne@68
|
4808 '*singleton*); it is optional in all other cases. A single '
|
|
jpayne@68
|
4809 'expression\n'
|
|
jpayne@68
|
4810 'without a trailing comma doesn’t create a tuple, but rather '
|
|
jpayne@68
|
4811 'yields the\n'
|
|
jpayne@68
|
4812 'value of that expression. (To create an empty tuple, use an '
|
|
jpayne@68
|
4813 'empty pair\n'
|
|
jpayne@68
|
4814 'of parentheses: "()".)\n',
|
|
jpayne@68
|
4815 'floating': 'Floating point literals\n'
|
|
jpayne@68
|
4816 '***********************\n'
|
|
jpayne@68
|
4817 '\n'
|
|
jpayne@68
|
4818 'Floating point literals are described by the following lexical\n'
|
|
jpayne@68
|
4819 'definitions:\n'
|
|
jpayne@68
|
4820 '\n'
|
|
jpayne@68
|
4821 ' floatnumber ::= pointfloat | exponentfloat\n'
|
|
jpayne@68
|
4822 ' pointfloat ::= [digitpart] fraction | digitpart "."\n'
|
|
jpayne@68
|
4823 ' exponentfloat ::= (digitpart | pointfloat) exponent\n'
|
|
jpayne@68
|
4824 ' digitpart ::= digit (["_"] digit)*\n'
|
|
jpayne@68
|
4825 ' fraction ::= "." digitpart\n'
|
|
jpayne@68
|
4826 ' exponent ::= ("e" | "E") ["+" | "-"] digitpart\n'
|
|
jpayne@68
|
4827 '\n'
|
|
jpayne@68
|
4828 'Note that the integer and exponent parts are always interpreted '
|
|
jpayne@68
|
4829 'using\n'
|
|
jpayne@68
|
4830 'radix 10. For example, "077e010" is legal, and denotes the same '
|
|
jpayne@68
|
4831 'number\n'
|
|
jpayne@68
|
4832 'as "77e10". The allowed range of floating point literals is\n'
|
|
jpayne@68
|
4833 'implementation-dependent. As in integer literals, underscores '
|
|
jpayne@68
|
4834 'are\n'
|
|
jpayne@68
|
4835 'supported for digit grouping.\n'
|
|
jpayne@68
|
4836 '\n'
|
|
jpayne@68
|
4837 'Some examples of floating point literals:\n'
|
|
jpayne@68
|
4838 '\n'
|
|
jpayne@68
|
4839 ' 3.14 10. .001 1e100 3.14e-10 0e0 '
|
|
jpayne@68
|
4840 '3.14_15_93\n'
|
|
jpayne@68
|
4841 '\n'
|
|
jpayne@68
|
4842 'Changed in version 3.6: Underscores are now allowed for '
|
|
jpayne@68
|
4843 'grouping\n'
|
|
jpayne@68
|
4844 'purposes in literals.\n',
|
|
jpayne@68
|
4845 'for': 'The "for" statement\n'
|
|
jpayne@68
|
4846 '*******************\n'
|
|
jpayne@68
|
4847 '\n'
|
|
jpayne@68
|
4848 'The "for" statement is used to iterate over the elements of a '
|
|
jpayne@68
|
4849 'sequence\n'
|
|
jpayne@68
|
4850 '(such as a string, tuple or list) or other iterable object:\n'
|
|
jpayne@68
|
4851 '\n'
|
|
jpayne@68
|
4852 ' for_stmt ::= "for" target_list "in" expression_list ":" suite\n'
|
|
jpayne@68
|
4853 ' ["else" ":" suite]\n'
|
|
jpayne@68
|
4854 '\n'
|
|
jpayne@68
|
4855 'The expression list is evaluated once; it should yield an iterable\n'
|
|
jpayne@68
|
4856 'object. An iterator is created for the result of the\n'
|
|
jpayne@68
|
4857 '"expression_list". The suite is then executed once for each item\n'
|
|
jpayne@68
|
4858 'provided by the iterator, in the order returned by the iterator. '
|
|
jpayne@68
|
4859 'Each\n'
|
|
jpayne@68
|
4860 'item in turn is assigned to the target list using the standard rules\n'
|
|
jpayne@68
|
4861 'for assignments (see Assignment statements), and then the suite is\n'
|
|
jpayne@68
|
4862 'executed. When the items are exhausted (which is immediately when '
|
|
jpayne@68
|
4863 'the\n'
|
|
jpayne@68
|
4864 'sequence is empty or an iterator raises a "StopIteration" '
|
|
jpayne@68
|
4865 'exception),\n'
|
|
jpayne@68
|
4866 'the suite in the "else" clause, if present, is executed, and the '
|
|
jpayne@68
|
4867 'loop\n'
|
|
jpayne@68
|
4868 'terminates.\n'
|
|
jpayne@68
|
4869 '\n'
|
|
jpayne@68
|
4870 'A "break" statement executed in the first suite terminates the loop\n'
|
|
jpayne@68
|
4871 'without executing the "else" clause’s suite. A "continue" statement\n'
|
|
jpayne@68
|
4872 'executed in the first suite skips the rest of the suite and '
|
|
jpayne@68
|
4873 'continues\n'
|
|
jpayne@68
|
4874 'with the next item, or with the "else" clause if there is no next\n'
|
|
jpayne@68
|
4875 'item.\n'
|
|
jpayne@68
|
4876 '\n'
|
|
jpayne@68
|
4877 'The for-loop makes assignments to the variables in the target list.\n'
|
|
jpayne@68
|
4878 'This overwrites all previous assignments to those variables '
|
|
jpayne@68
|
4879 'including\n'
|
|
jpayne@68
|
4880 'those made in the suite of the for-loop:\n'
|
|
jpayne@68
|
4881 '\n'
|
|
jpayne@68
|
4882 ' for i in range(10):\n'
|
|
jpayne@68
|
4883 ' print(i)\n'
|
|
jpayne@68
|
4884 ' i = 5 # this will not affect the for-loop\n'
|
|
jpayne@68
|
4885 ' # because i will be overwritten with the '
|
|
jpayne@68
|
4886 'next\n'
|
|
jpayne@68
|
4887 ' # index in the range\n'
|
|
jpayne@68
|
4888 '\n'
|
|
jpayne@68
|
4889 'Names in the target list are not deleted when the loop is finished,\n'
|
|
jpayne@68
|
4890 'but if the sequence is empty, they will not have been assigned to at\n'
|
|
jpayne@68
|
4891 'all by the loop. Hint: the built-in function "range()" returns an\n'
|
|
jpayne@68
|
4892 'iterator of integers suitable to emulate the effect of Pascal’s "for '
|
|
jpayne@68
|
4893 'i\n'
|
|
jpayne@68
|
4894 ':= a to b do"; e.g., "list(range(3))" returns the list "[0, 1, 2]".\n'
|
|
jpayne@68
|
4895 '\n'
|
|
jpayne@68
|
4896 'Note: There is a subtlety when the sequence is being modified by the\n'
|
|
jpayne@68
|
4897 ' loop (this can only occur for mutable sequences, e.g. lists). An\n'
|
|
jpayne@68
|
4898 ' internal counter is used to keep track of which item is used next,\n'
|
|
jpayne@68
|
4899 ' and this is incremented on each iteration. When this counter has\n'
|
|
jpayne@68
|
4900 ' reached the length of the sequence the loop terminates. This '
|
|
jpayne@68
|
4901 'means\n'
|
|
jpayne@68
|
4902 ' that if the suite deletes the current (or a previous) item from '
|
|
jpayne@68
|
4903 'the\n'
|
|
jpayne@68
|
4904 ' sequence, the next item will be skipped (since it gets the index '
|
|
jpayne@68
|
4905 'of\n'
|
|
jpayne@68
|
4906 ' the current item which has already been treated). Likewise, if '
|
|
jpayne@68
|
4907 'the\n'
|
|
jpayne@68
|
4908 ' suite inserts an item in the sequence before the current item, the\n'
|
|
jpayne@68
|
4909 ' current item will be treated again the next time through the loop.\n'
|
|
jpayne@68
|
4910 ' This can lead to nasty bugs that can be avoided by making a\n'
|
|
jpayne@68
|
4911 ' temporary copy using a slice of the whole sequence, e.g.,\n'
|
|
jpayne@68
|
4912 '\n'
|
|
jpayne@68
|
4913 ' for x in a[:]:\n'
|
|
jpayne@68
|
4914 ' if x < 0: a.remove(x)\n',
|
|
jpayne@68
|
4915 'formatstrings': 'Format String Syntax\n'
|
|
jpayne@68
|
4916 '********************\n'
|
|
jpayne@68
|
4917 '\n'
|
|
jpayne@68
|
4918 'The "str.format()" method and the "Formatter" class share '
|
|
jpayne@68
|
4919 'the same\n'
|
|
jpayne@68
|
4920 'syntax for format strings (although in the case of '
|
|
jpayne@68
|
4921 '"Formatter",\n'
|
|
jpayne@68
|
4922 'subclasses can define their own format string syntax). The '
|
|
jpayne@68
|
4923 'syntax is\n'
|
|
jpayne@68
|
4924 'related to that of formatted string literals, but there '
|
|
jpayne@68
|
4925 'are\n'
|
|
jpayne@68
|
4926 'differences.\n'
|
|
jpayne@68
|
4927 '\n'
|
|
jpayne@68
|
4928 'Format strings contain “replacement fields” surrounded by '
|
|
jpayne@68
|
4929 'curly braces\n'
|
|
jpayne@68
|
4930 '"{}". Anything that is not contained in braces is '
|
|
jpayne@68
|
4931 'considered literal\n'
|
|
jpayne@68
|
4932 'text, which is copied unchanged to the output. If you need '
|
|
jpayne@68
|
4933 'to include\n'
|
|
jpayne@68
|
4934 'a brace character in the literal text, it can be escaped by '
|
|
jpayne@68
|
4935 'doubling:\n'
|
|
jpayne@68
|
4936 '"{{" and "}}".\n'
|
|
jpayne@68
|
4937 '\n'
|
|
jpayne@68
|
4938 'The grammar for a replacement field is as follows:\n'
|
|
jpayne@68
|
4939 '\n'
|
|
jpayne@68
|
4940 ' replacement_field ::= "{" [field_name] ["!" '
|
|
jpayne@68
|
4941 'conversion] [":" format_spec] "}"\n'
|
|
jpayne@68
|
4942 ' field_name ::= arg_name ("." attribute_name | '
|
|
jpayne@68
|
4943 '"[" element_index "]")*\n'
|
|
jpayne@68
|
4944 ' arg_name ::= [identifier | digit+]\n'
|
|
jpayne@68
|
4945 ' attribute_name ::= identifier\n'
|
|
jpayne@68
|
4946 ' element_index ::= digit+ | index_string\n'
|
|
jpayne@68
|
4947 ' index_string ::= <any source character except '
|
|
jpayne@68
|
4948 '"]"> +\n'
|
|
jpayne@68
|
4949 ' conversion ::= "r" | "s" | "a"\n'
|
|
jpayne@68
|
4950 ' format_spec ::= <described in the next '
|
|
jpayne@68
|
4951 'section>\n'
|
|
jpayne@68
|
4952 '\n'
|
|
jpayne@68
|
4953 'In less formal terms, the replacement field can start with '
|
|
jpayne@68
|
4954 'a\n'
|
|
jpayne@68
|
4955 '*field_name* that specifies the object whose value is to be '
|
|
jpayne@68
|
4956 'formatted\n'
|
|
jpayne@68
|
4957 'and inserted into the output instead of the replacement '
|
|
jpayne@68
|
4958 'field. The\n'
|
|
jpayne@68
|
4959 '*field_name* is optionally followed by a *conversion* '
|
|
jpayne@68
|
4960 'field, which is\n'
|
|
jpayne@68
|
4961 'preceded by an exclamation point "\'!\'", and a '
|
|
jpayne@68
|
4962 '*format_spec*, which is\n'
|
|
jpayne@68
|
4963 'preceded by a colon "\':\'". These specify a non-default '
|
|
jpayne@68
|
4964 'format for the\n'
|
|
jpayne@68
|
4965 'replacement value.\n'
|
|
jpayne@68
|
4966 '\n'
|
|
jpayne@68
|
4967 'See also the Format Specification Mini-Language section.\n'
|
|
jpayne@68
|
4968 '\n'
|
|
jpayne@68
|
4969 'The *field_name* itself begins with an *arg_name* that is '
|
|
jpayne@68
|
4970 'either a\n'
|
|
jpayne@68
|
4971 'number or a keyword. If it’s a number, it refers to a '
|
|
jpayne@68
|
4972 'positional\n'
|
|
jpayne@68
|
4973 'argument, and if it’s a keyword, it refers to a named '
|
|
jpayne@68
|
4974 'keyword\n'
|
|
jpayne@68
|
4975 'argument. If the numerical arg_names in a format string '
|
|
jpayne@68
|
4976 'are 0, 1, 2,\n'
|
|
jpayne@68
|
4977 '… in sequence, they can all be omitted (not just some) and '
|
|
jpayne@68
|
4978 'the numbers\n'
|
|
jpayne@68
|
4979 '0, 1, 2, … will be automatically inserted in that order. '
|
|
jpayne@68
|
4980 'Because\n'
|
|
jpayne@68
|
4981 '*arg_name* is not quote-delimited, it is not possible to '
|
|
jpayne@68
|
4982 'specify\n'
|
|
jpayne@68
|
4983 'arbitrary dictionary keys (e.g., the strings "\'10\'" or '
|
|
jpayne@68
|
4984 '"\':-]\'") within\n'
|
|
jpayne@68
|
4985 'a format string. The *arg_name* can be followed by any '
|
|
jpayne@68
|
4986 'number of index\n'
|
|
jpayne@68
|
4987 'or attribute expressions. An expression of the form '
|
|
jpayne@68
|
4988 '"\'.name\'" selects\n'
|
|
jpayne@68
|
4989 'the named attribute using "getattr()", while an expression '
|
|
jpayne@68
|
4990 'of the form\n'
|
|
jpayne@68
|
4991 '"\'[index]\'" does an index lookup using "__getitem__()".\n'
|
|
jpayne@68
|
4992 '\n'
|
|
jpayne@68
|
4993 'Changed in version 3.1: The positional argument specifiers '
|
|
jpayne@68
|
4994 'can be\n'
|
|
jpayne@68
|
4995 'omitted for "str.format()", so "\'{} {}\'.format(a, b)" is '
|
|
jpayne@68
|
4996 'equivalent to\n'
|
|
jpayne@68
|
4997 '"\'{0} {1}\'.format(a, b)".\n'
|
|
jpayne@68
|
4998 '\n'
|
|
jpayne@68
|
4999 'Changed in version 3.4: The positional argument specifiers '
|
|
jpayne@68
|
5000 'can be\n'
|
|
jpayne@68
|
5001 'omitted for "Formatter".\n'
|
|
jpayne@68
|
5002 '\n'
|
|
jpayne@68
|
5003 'Some simple format string examples:\n'
|
|
jpayne@68
|
5004 '\n'
|
|
jpayne@68
|
5005 ' "First, thou shalt count to {0}" # References first '
|
|
jpayne@68
|
5006 'positional argument\n'
|
|
jpayne@68
|
5007 ' "Bring me a {}" # Implicitly '
|
|
jpayne@68
|
5008 'references the first positional argument\n'
|
|
jpayne@68
|
5009 ' "From {} to {}" # Same as "From {0} to '
|
|
jpayne@68
|
5010 '{1}"\n'
|
|
jpayne@68
|
5011 ' "My quest is {name}" # References keyword '
|
|
jpayne@68
|
5012 "argument 'name'\n"
|
|
jpayne@68
|
5013 ' "Weight in tons {0.weight}" # \'weight\' attribute '
|
|
jpayne@68
|
5014 'of first positional arg\n'
|
|
jpayne@68
|
5015 ' "Units destroyed: {players[0]}" # First element of '
|
|
jpayne@68
|
5016 "keyword argument 'players'.\n"
|
|
jpayne@68
|
5017 '\n'
|
|
jpayne@68
|
5018 'The *conversion* field causes a type coercion before '
|
|
jpayne@68
|
5019 'formatting.\n'
|
|
jpayne@68
|
5020 'Normally, the job of formatting a value is done by the '
|
|
jpayne@68
|
5021 '"__format__()"\n'
|
|
jpayne@68
|
5022 'method of the value itself. However, in some cases it is '
|
|
jpayne@68
|
5023 'desirable to\n'
|
|
jpayne@68
|
5024 'force a type to be formatted as a string, overriding its '
|
|
jpayne@68
|
5025 'own\n'
|
|
jpayne@68
|
5026 'definition of formatting. By converting the value to a '
|
|
jpayne@68
|
5027 'string before\n'
|
|
jpayne@68
|
5028 'calling "__format__()", the normal formatting logic is '
|
|
jpayne@68
|
5029 'bypassed.\n'
|
|
jpayne@68
|
5030 '\n'
|
|
jpayne@68
|
5031 'Three conversion flags are currently supported: "\'!s\'" '
|
|
jpayne@68
|
5032 'which calls\n'
|
|
jpayne@68
|
5033 '"str()" on the value, "\'!r\'" which calls "repr()" and '
|
|
jpayne@68
|
5034 '"\'!a\'" which\n'
|
|
jpayne@68
|
5035 'calls "ascii()".\n'
|
|
jpayne@68
|
5036 '\n'
|
|
jpayne@68
|
5037 'Some examples:\n'
|
|
jpayne@68
|
5038 '\n'
|
|
jpayne@68
|
5039 ' "Harold\'s a clever {0!s}" # Calls str() on the '
|
|
jpayne@68
|
5040 'argument first\n'
|
|
jpayne@68
|
5041 ' "Bring out the holy {name!r}" # Calls repr() on the '
|
|
jpayne@68
|
5042 'argument first\n'
|
|
jpayne@68
|
5043 ' "More {!a}" # Calls ascii() on the '
|
|
jpayne@68
|
5044 'argument first\n'
|
|
jpayne@68
|
5045 '\n'
|
|
jpayne@68
|
5046 'The *format_spec* field contains a specification of how the '
|
|
jpayne@68
|
5047 'value\n'
|
|
jpayne@68
|
5048 'should be presented, including such details as field width, '
|
|
jpayne@68
|
5049 'alignment,\n'
|
|
jpayne@68
|
5050 'padding, decimal precision and so on. Each value type can '
|
|
jpayne@68
|
5051 'define its\n'
|
|
jpayne@68
|
5052 'own “formatting mini-language” or interpretation of the '
|
|
jpayne@68
|
5053 '*format_spec*.\n'
|
|
jpayne@68
|
5054 '\n'
|
|
jpayne@68
|
5055 'Most built-in types support a common formatting '
|
|
jpayne@68
|
5056 'mini-language, which\n'
|
|
jpayne@68
|
5057 'is described in the next section.\n'
|
|
jpayne@68
|
5058 '\n'
|
|
jpayne@68
|
5059 'A *format_spec* field can also include nested replacement '
|
|
jpayne@68
|
5060 'fields\n'
|
|
jpayne@68
|
5061 'within it. These nested replacement fields may contain a '
|
|
jpayne@68
|
5062 'field name,\n'
|
|
jpayne@68
|
5063 'conversion flag and format specification, but deeper '
|
|
jpayne@68
|
5064 'nesting is not\n'
|
|
jpayne@68
|
5065 'allowed. The replacement fields within the format_spec '
|
|
jpayne@68
|
5066 'are\n'
|
|
jpayne@68
|
5067 'substituted before the *format_spec* string is interpreted. '
|
|
jpayne@68
|
5068 'This\n'
|
|
jpayne@68
|
5069 'allows the formatting of a value to be dynamically '
|
|
jpayne@68
|
5070 'specified.\n'
|
|
jpayne@68
|
5071 '\n'
|
|
jpayne@68
|
5072 'See the Format examples section for some examples.\n'
|
|
jpayne@68
|
5073 '\n'
|
|
jpayne@68
|
5074 '\n'
|
|
jpayne@68
|
5075 'Format Specification Mini-Language\n'
|
|
jpayne@68
|
5076 '==================================\n'
|
|
jpayne@68
|
5077 '\n'
|
|
jpayne@68
|
5078 '“Format specifications” are used within replacement fields '
|
|
jpayne@68
|
5079 'contained\n'
|
|
jpayne@68
|
5080 'within a format string to define how individual values are '
|
|
jpayne@68
|
5081 'presented\n'
|
|
jpayne@68
|
5082 '(see Format String Syntax and Formatted string literals). '
|
|
jpayne@68
|
5083 'They can\n'
|
|
jpayne@68
|
5084 'also be passed directly to the built-in "format()" '
|
|
jpayne@68
|
5085 'function. Each\n'
|
|
jpayne@68
|
5086 'formattable type may define how the format specification is '
|
|
jpayne@68
|
5087 'to be\n'
|
|
jpayne@68
|
5088 'interpreted.\n'
|
|
jpayne@68
|
5089 '\n'
|
|
jpayne@68
|
5090 'Most built-in types implement the following options for '
|
|
jpayne@68
|
5091 'format\n'
|
|
jpayne@68
|
5092 'specifications, although some of the formatting options are '
|
|
jpayne@68
|
5093 'only\n'
|
|
jpayne@68
|
5094 'supported by the numeric types.\n'
|
|
jpayne@68
|
5095 '\n'
|
|
jpayne@68
|
5096 'A general convention is that an empty format string ("""") '
|
|
jpayne@68
|
5097 'produces\n'
|
|
jpayne@68
|
5098 'the same result as if you had called "str()" on the value. '
|
|
jpayne@68
|
5099 'A non-empty\n'
|
|
jpayne@68
|
5100 'format string typically modifies the result.\n'
|
|
jpayne@68
|
5101 '\n'
|
|
jpayne@68
|
5102 'The general form of a *standard format specifier* is:\n'
|
|
jpayne@68
|
5103 '\n'
|
|
jpayne@68
|
5104 ' format_spec ::= '
|
|
jpayne@68
|
5105 '[[fill]align][sign][#][0][width][grouping_option][.precision][type]\n'
|
|
jpayne@68
|
5106 ' fill ::= <any character>\n'
|
|
jpayne@68
|
5107 ' align ::= "<" | ">" | "=" | "^"\n'
|
|
jpayne@68
|
5108 ' sign ::= "+" | "-" | " "\n'
|
|
jpayne@68
|
5109 ' width ::= digit+\n'
|
|
jpayne@68
|
5110 ' grouping_option ::= "_" | ","\n'
|
|
jpayne@68
|
5111 ' precision ::= digit+\n'
|
|
jpayne@68
|
5112 ' type ::= "b" | "c" | "d" | "e" | "E" | "f" | '
|
|
jpayne@68
|
5113 '"F" | "g" | "G" | "n" | "o" | "s" | "x" | "X" | "%"\n'
|
|
jpayne@68
|
5114 '\n'
|
|
jpayne@68
|
5115 'If a valid *align* value is specified, it can be preceded '
|
|
jpayne@68
|
5116 'by a *fill*\n'
|
|
jpayne@68
|
5117 'character that can be any character and defaults to a space '
|
|
jpayne@68
|
5118 'if\n'
|
|
jpayne@68
|
5119 'omitted. It is not possible to use a literal curly brace '
|
|
jpayne@68
|
5120 '(“"{"” or\n'
|
|
jpayne@68
|
5121 '“"}"”) as the *fill* character in a formatted string '
|
|
jpayne@68
|
5122 'literal or when\n'
|
|
jpayne@68
|
5123 'using the "str.format()" method. However, it is possible '
|
|
jpayne@68
|
5124 'to insert a\n'
|
|
jpayne@68
|
5125 'curly brace with a nested replacement field. This '
|
|
jpayne@68
|
5126 'limitation doesn’t\n'
|
|
jpayne@68
|
5127 'affect the "format()" function.\n'
|
|
jpayne@68
|
5128 '\n'
|
|
jpayne@68
|
5129 'The meaning of the various alignment options is as '
|
|
jpayne@68
|
5130 'follows:\n'
|
|
jpayne@68
|
5131 '\n'
|
|
jpayne@68
|
5132 ' '
|
|
jpayne@68
|
5133 '+-----------+------------------------------------------------------------+\n'
|
|
jpayne@68
|
5134 ' | Option | '
|
|
jpayne@68
|
5135 'Meaning '
|
|
jpayne@68
|
5136 '|\n'
|
|
jpayne@68
|
5137 ' '
|
|
jpayne@68
|
5138 '|===========|============================================================|\n'
|
|
jpayne@68
|
5139 ' | "\'<\'" | Forces the field to be left-aligned '
|
|
jpayne@68
|
5140 'within the available |\n'
|
|
jpayne@68
|
5141 ' | | space (this is the default for most '
|
|
jpayne@68
|
5142 'objects). |\n'
|
|
jpayne@68
|
5143 ' '
|
|
jpayne@68
|
5144 '+-----------+------------------------------------------------------------+\n'
|
|
jpayne@68
|
5145 ' | "\'>\'" | Forces the field to be right-aligned '
|
|
jpayne@68
|
5146 'within the available |\n'
|
|
jpayne@68
|
5147 ' | | space (this is the default for '
|
|
jpayne@68
|
5148 'numbers). |\n'
|
|
jpayne@68
|
5149 ' '
|
|
jpayne@68
|
5150 '+-----------+------------------------------------------------------------+\n'
|
|
jpayne@68
|
5151 ' | "\'=\'" | Forces the padding to be placed after '
|
|
jpayne@68
|
5152 'the sign (if any) |\n'
|
|
jpayne@68
|
5153 ' | | but before the digits. This is used for '
|
|
jpayne@68
|
5154 'printing fields |\n'
|
|
jpayne@68
|
5155 ' | | in the form ‘+000000120’. This alignment '
|
|
jpayne@68
|
5156 'option is only |\n'
|
|
jpayne@68
|
5157 ' | | valid for numeric types. It becomes the '
|
|
jpayne@68
|
5158 'default when ‘0’ |\n'
|
|
jpayne@68
|
5159 ' | | immediately precedes the field '
|
|
jpayne@68
|
5160 'width. |\n'
|
|
jpayne@68
|
5161 ' '
|
|
jpayne@68
|
5162 '+-----------+------------------------------------------------------------+\n'
|
|
jpayne@68
|
5163 ' | "\'^\'" | Forces the field to be centered within '
|
|
jpayne@68
|
5164 'the available |\n'
|
|
jpayne@68
|
5165 ' | | '
|
|
jpayne@68
|
5166 'space. '
|
|
jpayne@68
|
5167 '|\n'
|
|
jpayne@68
|
5168 ' '
|
|
jpayne@68
|
5169 '+-----------+------------------------------------------------------------+\n'
|
|
jpayne@68
|
5170 '\n'
|
|
jpayne@68
|
5171 'Note that unless a minimum field width is defined, the '
|
|
jpayne@68
|
5172 'field width\n'
|
|
jpayne@68
|
5173 'will always be the same size as the data to fill it, so '
|
|
jpayne@68
|
5174 'that the\n'
|
|
jpayne@68
|
5175 'alignment option has no meaning in this case.\n'
|
|
jpayne@68
|
5176 '\n'
|
|
jpayne@68
|
5177 'The *sign* option is only valid for number types, and can '
|
|
jpayne@68
|
5178 'be one of\n'
|
|
jpayne@68
|
5179 'the following:\n'
|
|
jpayne@68
|
5180 '\n'
|
|
jpayne@68
|
5181 ' '
|
|
jpayne@68
|
5182 '+-----------+------------------------------------------------------------+\n'
|
|
jpayne@68
|
5183 ' | Option | '
|
|
jpayne@68
|
5184 'Meaning '
|
|
jpayne@68
|
5185 '|\n'
|
|
jpayne@68
|
5186 ' '
|
|
jpayne@68
|
5187 '|===========|============================================================|\n'
|
|
jpayne@68
|
5188 ' | "\'+\'" | indicates that a sign should be used for '
|
|
jpayne@68
|
5189 'both positive as |\n'
|
|
jpayne@68
|
5190 ' | | well as negative '
|
|
jpayne@68
|
5191 'numbers. |\n'
|
|
jpayne@68
|
5192 ' '
|
|
jpayne@68
|
5193 '+-----------+------------------------------------------------------------+\n'
|
|
jpayne@68
|
5194 ' | "\'-\'" | indicates that a sign should be used '
|
|
jpayne@68
|
5195 'only for negative |\n'
|
|
jpayne@68
|
5196 ' | | numbers (this is the default '
|
|
jpayne@68
|
5197 'behavior). |\n'
|
|
jpayne@68
|
5198 ' '
|
|
jpayne@68
|
5199 '+-----------+------------------------------------------------------------+\n'
|
|
jpayne@68
|
5200 ' | space | indicates that a leading space should be '
|
|
jpayne@68
|
5201 'used on positive |\n'
|
|
jpayne@68
|
5202 ' | | numbers, and a minus sign on negative '
|
|
jpayne@68
|
5203 'numbers. |\n'
|
|
jpayne@68
|
5204 ' '
|
|
jpayne@68
|
5205 '+-----------+------------------------------------------------------------+\n'
|
|
jpayne@68
|
5206 '\n'
|
|
jpayne@68
|
5207 'The "\'#\'" option causes the “alternate form” to be used '
|
|
jpayne@68
|
5208 'for the\n'
|
|
jpayne@68
|
5209 'conversion. The alternate form is defined differently for '
|
|
jpayne@68
|
5210 'different\n'
|
|
jpayne@68
|
5211 'types. This option is only valid for integer, float, '
|
|
jpayne@68
|
5212 'complex and\n'
|
|
jpayne@68
|
5213 'Decimal types. For integers, when binary, octal, or '
|
|
jpayne@68
|
5214 'hexadecimal output\n'
|
|
jpayne@68
|
5215 'is used, this option adds the prefix respective "\'0b\'", '
|
|
jpayne@68
|
5216 '"\'0o\'", or\n'
|
|
jpayne@68
|
5217 '"\'0x\'" to the output value. For floats, complex and '
|
|
jpayne@68
|
5218 'Decimal the\n'
|
|
jpayne@68
|
5219 'alternate form causes the result of the conversion to '
|
|
jpayne@68
|
5220 'always contain a\n'
|
|
jpayne@68
|
5221 'decimal-point character, even if no digits follow it. '
|
|
jpayne@68
|
5222 'Normally, a\n'
|
|
jpayne@68
|
5223 'decimal-point character appears in the result of these '
|
|
jpayne@68
|
5224 'conversions\n'
|
|
jpayne@68
|
5225 'only if a digit follows it. In addition, for "\'g\'" and '
|
|
jpayne@68
|
5226 '"\'G\'"\n'
|
|
jpayne@68
|
5227 'conversions, trailing zeros are not removed from the '
|
|
jpayne@68
|
5228 'result.\n'
|
|
jpayne@68
|
5229 '\n'
|
|
jpayne@68
|
5230 'The "\',\'" option signals the use of a comma for a '
|
|
jpayne@68
|
5231 'thousands separator.\n'
|
|
jpayne@68
|
5232 'For a locale aware separator, use the "\'n\'" integer '
|
|
jpayne@68
|
5233 'presentation type\n'
|
|
jpayne@68
|
5234 'instead.\n'
|
|
jpayne@68
|
5235 '\n'
|
|
jpayne@68
|
5236 'Changed in version 3.1: Added the "\',\'" option (see also '
|
|
jpayne@68
|
5237 '**PEP 378**).\n'
|
|
jpayne@68
|
5238 '\n'
|
|
jpayne@68
|
5239 'The "\'_\'" option signals the use of an underscore for a '
|
|
jpayne@68
|
5240 'thousands\n'
|
|
jpayne@68
|
5241 'separator for floating point presentation types and for '
|
|
jpayne@68
|
5242 'integer\n'
|
|
jpayne@68
|
5243 'presentation type "\'d\'". For integer presentation types '
|
|
jpayne@68
|
5244 '"\'b\'", "\'o\'",\n'
|
|
jpayne@68
|
5245 '"\'x\'", and "\'X\'", underscores will be inserted every 4 '
|
|
jpayne@68
|
5246 'digits. For\n'
|
|
jpayne@68
|
5247 'other presentation types, specifying this option is an '
|
|
jpayne@68
|
5248 'error.\n'
|
|
jpayne@68
|
5249 '\n'
|
|
jpayne@68
|
5250 'Changed in version 3.6: Added the "\'_\'" option (see also '
|
|
jpayne@68
|
5251 '**PEP 515**).\n'
|
|
jpayne@68
|
5252 '\n'
|
|
jpayne@68
|
5253 '*width* is a decimal integer defining the minimum field '
|
|
jpayne@68
|
5254 'width. If not\n'
|
|
jpayne@68
|
5255 'specified, then the field width will be determined by the '
|
|
jpayne@68
|
5256 'content.\n'
|
|
jpayne@68
|
5257 '\n'
|
|
jpayne@68
|
5258 'When no explicit alignment is given, preceding the *width* '
|
|
jpayne@68
|
5259 'field by a\n'
|
|
jpayne@68
|
5260 'zero ("\'0\'") character enables sign-aware zero-padding '
|
|
jpayne@68
|
5261 'for numeric\n'
|
|
jpayne@68
|
5262 'types. This is equivalent to a *fill* character of "\'0\'" '
|
|
jpayne@68
|
5263 'with an\n'
|
|
jpayne@68
|
5264 '*alignment* type of "\'=\'".\n'
|
|
jpayne@68
|
5265 '\n'
|
|
jpayne@68
|
5266 'The *precision* is a decimal number indicating how many '
|
|
jpayne@68
|
5267 'digits should\n'
|
|
jpayne@68
|
5268 'be displayed after the decimal point for a floating point '
|
|
jpayne@68
|
5269 'value\n'
|
|
jpayne@68
|
5270 'formatted with "\'f\'" and "\'F\'", or before and after the '
|
|
jpayne@68
|
5271 'decimal point\n'
|
|
jpayne@68
|
5272 'for a floating point value formatted with "\'g\'" or '
|
|
jpayne@68
|
5273 '"\'G\'". For non-\n'
|
|
jpayne@68
|
5274 'number types the field indicates the maximum field size - '
|
|
jpayne@68
|
5275 'in other\n'
|
|
jpayne@68
|
5276 'words, how many characters will be used from the field '
|
|
jpayne@68
|
5277 'content. The\n'
|
|
jpayne@68
|
5278 '*precision* is not allowed for integer values.\n'
|
|
jpayne@68
|
5279 '\n'
|
|
jpayne@68
|
5280 'Finally, the *type* determines how the data should be '
|
|
jpayne@68
|
5281 'presented.\n'
|
|
jpayne@68
|
5282 '\n'
|
|
jpayne@68
|
5283 'The available string presentation types are:\n'
|
|
jpayne@68
|
5284 '\n'
|
|
jpayne@68
|
5285 ' '
|
|
jpayne@68
|
5286 '+-----------+------------------------------------------------------------+\n'
|
|
jpayne@68
|
5287 ' | Type | '
|
|
jpayne@68
|
5288 'Meaning '
|
|
jpayne@68
|
5289 '|\n'
|
|
jpayne@68
|
5290 ' '
|
|
jpayne@68
|
5291 '|===========|============================================================|\n'
|
|
jpayne@68
|
5292 ' | "\'s\'" | String format. This is the default type '
|
|
jpayne@68
|
5293 'for strings and |\n'
|
|
jpayne@68
|
5294 ' | | may be '
|
|
jpayne@68
|
5295 'omitted. |\n'
|
|
jpayne@68
|
5296 ' '
|
|
jpayne@68
|
5297 '+-----------+------------------------------------------------------------+\n'
|
|
jpayne@68
|
5298 ' | None | The same as '
|
|
jpayne@68
|
5299 '"\'s\'". |\n'
|
|
jpayne@68
|
5300 ' '
|
|
jpayne@68
|
5301 '+-----------+------------------------------------------------------------+\n'
|
|
jpayne@68
|
5302 '\n'
|
|
jpayne@68
|
5303 'The available integer presentation types are:\n'
|
|
jpayne@68
|
5304 '\n'
|
|
jpayne@68
|
5305 ' '
|
|
jpayne@68
|
5306 '+-----------+------------------------------------------------------------+\n'
|
|
jpayne@68
|
5307 ' | Type | '
|
|
jpayne@68
|
5308 'Meaning '
|
|
jpayne@68
|
5309 '|\n'
|
|
jpayne@68
|
5310 ' '
|
|
jpayne@68
|
5311 '|===========|============================================================|\n'
|
|
jpayne@68
|
5312 ' | "\'b\'" | Binary format. Outputs the number in '
|
|
jpayne@68
|
5313 'base 2. |\n'
|
|
jpayne@68
|
5314 ' '
|
|
jpayne@68
|
5315 '+-----------+------------------------------------------------------------+\n'
|
|
jpayne@68
|
5316 ' | "\'c\'" | Character. Converts the integer to the '
|
|
jpayne@68
|
5317 'corresponding |\n'
|
|
jpayne@68
|
5318 ' | | unicode character before '
|
|
jpayne@68
|
5319 'printing. |\n'
|
|
jpayne@68
|
5320 ' '
|
|
jpayne@68
|
5321 '+-----------+------------------------------------------------------------+\n'
|
|
jpayne@68
|
5322 ' | "\'d\'" | Decimal Integer. Outputs the number in '
|
|
jpayne@68
|
5323 'base 10. |\n'
|
|
jpayne@68
|
5324 ' '
|
|
jpayne@68
|
5325 '+-----------+------------------------------------------------------------+\n'
|
|
jpayne@68
|
5326 ' | "\'o\'" | Octal format. Outputs the number in base '
|
|
jpayne@68
|
5327 '8. |\n'
|
|
jpayne@68
|
5328 ' '
|
|
jpayne@68
|
5329 '+-----------+------------------------------------------------------------+\n'
|
|
jpayne@68
|
5330 ' | "\'x\'" | Hex format. Outputs the number in base '
|
|
jpayne@68
|
5331 '16, using lower- |\n'
|
|
jpayne@68
|
5332 ' | | case letters for the digits above '
|
|
jpayne@68
|
5333 '9. |\n'
|
|
jpayne@68
|
5334 ' '
|
|
jpayne@68
|
5335 '+-----------+------------------------------------------------------------+\n'
|
|
jpayne@68
|
5336 ' | "\'X\'" | Hex format. Outputs the number in base '
|
|
jpayne@68
|
5337 '16, using upper- |\n'
|
|
jpayne@68
|
5338 ' | | case letters for the digits above '
|
|
jpayne@68
|
5339 '9. |\n'
|
|
jpayne@68
|
5340 ' '
|
|
jpayne@68
|
5341 '+-----------+------------------------------------------------------------+\n'
|
|
jpayne@68
|
5342 ' | "\'n\'" | Number. This is the same as "\'d\'", '
|
|
jpayne@68
|
5343 'except that it uses the |\n'
|
|
jpayne@68
|
5344 ' | | current locale setting to insert the '
|
|
jpayne@68
|
5345 'appropriate number |\n'
|
|
jpayne@68
|
5346 ' | | separator '
|
|
jpayne@68
|
5347 'characters. |\n'
|
|
jpayne@68
|
5348 ' '
|
|
jpayne@68
|
5349 '+-----------+------------------------------------------------------------+\n'
|
|
jpayne@68
|
5350 ' | None | The same as '
|
|
jpayne@68
|
5351 '"\'d\'". |\n'
|
|
jpayne@68
|
5352 ' '
|
|
jpayne@68
|
5353 '+-----------+------------------------------------------------------------+\n'
|
|
jpayne@68
|
5354 '\n'
|
|
jpayne@68
|
5355 'In addition to the above presentation types, integers can '
|
|
jpayne@68
|
5356 'be formatted\n'
|
|
jpayne@68
|
5357 'with the floating point presentation types listed below '
|
|
jpayne@68
|
5358 '(except "\'n\'"\n'
|
|
jpayne@68
|
5359 'and "None"). When doing so, "float()" is used to convert '
|
|
jpayne@68
|
5360 'the integer\n'
|
|
jpayne@68
|
5361 'to a floating point number before formatting.\n'
|
|
jpayne@68
|
5362 '\n'
|
|
jpayne@68
|
5363 'The available presentation types for floating point and '
|
|
jpayne@68
|
5364 'decimal values\n'
|
|
jpayne@68
|
5365 'are:\n'
|
|
jpayne@68
|
5366 '\n'
|
|
jpayne@68
|
5367 ' '
|
|
jpayne@68
|
5368 '+-----------+------------------------------------------------------------+\n'
|
|
jpayne@68
|
5369 ' | Type | '
|
|
jpayne@68
|
5370 'Meaning '
|
|
jpayne@68
|
5371 '|\n'
|
|
jpayne@68
|
5372 ' '
|
|
jpayne@68
|
5373 '|===========|============================================================|\n'
|
|
jpayne@68
|
5374 ' | "\'e\'" | Exponent notation. Prints the number in '
|
|
jpayne@68
|
5375 'scientific |\n'
|
|
jpayne@68
|
5376 ' | | notation using the letter ‘e’ to indicate '
|
|
jpayne@68
|
5377 'the exponent. |\n'
|
|
jpayne@68
|
5378 ' | | The default precision is '
|
|
jpayne@68
|
5379 '"6". |\n'
|
|
jpayne@68
|
5380 ' '
|
|
jpayne@68
|
5381 '+-----------+------------------------------------------------------------+\n'
|
|
jpayne@68
|
5382 ' | "\'E\'" | Exponent notation. Same as "\'e\'" '
|
|
jpayne@68
|
5383 'except it uses an upper |\n'
|
|
jpayne@68
|
5384 ' | | case ‘E’ as the separator '
|
|
jpayne@68
|
5385 'character. |\n'
|
|
jpayne@68
|
5386 ' '
|
|
jpayne@68
|
5387 '+-----------+------------------------------------------------------------+\n'
|
|
jpayne@68
|
5388 ' | "\'f\'" | Fixed-point notation. Displays the '
|
|
jpayne@68
|
5389 'number as a fixed-point |\n'
|
|
jpayne@68
|
5390 ' | | number. The default precision is '
|
|
jpayne@68
|
5391 '"6". |\n'
|
|
jpayne@68
|
5392 ' '
|
|
jpayne@68
|
5393 '+-----------+------------------------------------------------------------+\n'
|
|
jpayne@68
|
5394 ' | "\'F\'" | Fixed-point notation. Same as "\'f\'", '
|
|
jpayne@68
|
5395 'but converts "nan" to |\n'
|
|
jpayne@68
|
5396 ' | | "NAN" and "inf" to '
|
|
jpayne@68
|
5397 '"INF". |\n'
|
|
jpayne@68
|
5398 ' '
|
|
jpayne@68
|
5399 '+-----------+------------------------------------------------------------+\n'
|
|
jpayne@68
|
5400 ' | "\'g\'" | General format. For a given precision '
|
|
jpayne@68
|
5401 '"p >= 1", this |\n'
|
|
jpayne@68
|
5402 ' | | rounds the number to "p" significant '
|
|
jpayne@68
|
5403 'digits and then |\n'
|
|
jpayne@68
|
5404 ' | | formats the result in either fixed-point '
|
|
jpayne@68
|
5405 'format or in |\n'
|
|
jpayne@68
|
5406 ' | | scientific notation, depending on its '
|
|
jpayne@68
|
5407 'magnitude. The |\n'
|
|
jpayne@68
|
5408 ' | | precise rules are as follows: suppose that '
|
|
jpayne@68
|
5409 'the result |\n'
|
|
jpayne@68
|
5410 ' | | formatted with presentation type "\'e\'" '
|
|
jpayne@68
|
5411 'and precision "p-1" |\n'
|
|
jpayne@68
|
5412 ' | | would have exponent "exp". Then, if "m <= '
|
|
jpayne@68
|
5413 'exp < p", where |\n'
|
|
jpayne@68
|
5414 ' | | "m" is -4 for floats and -6 for '
|
|
jpayne@68
|
5415 '"Decimals", the number is |\n'
|
|
jpayne@68
|
5416 ' | | formatted with presentation type "\'f\'" '
|
|
jpayne@68
|
5417 'and precision |\n'
|
|
jpayne@68
|
5418 ' | | "p-1-exp". Otherwise, the number is '
|
|
jpayne@68
|
5419 'formatted with |\n'
|
|
jpayne@68
|
5420 ' | | presentation type "\'e\'" and precision '
|
|
jpayne@68
|
5421 '"p-1". In both cases |\n'
|
|
jpayne@68
|
5422 ' | | insignificant trailing zeros are removed '
|
|
jpayne@68
|
5423 'from the |\n'
|
|
jpayne@68
|
5424 ' | | significand, and the decimal point is also '
|
|
jpayne@68
|
5425 'removed if |\n'
|
|
jpayne@68
|
5426 ' | | there are no remaining digits following '
|
|
jpayne@68
|
5427 'it, unless the |\n'
|
|
jpayne@68
|
5428 ' | | "\'#\'" option is used. Positive and '
|
|
jpayne@68
|
5429 'negative infinity, |\n'
|
|
jpayne@68
|
5430 ' | | positive and negative zero, and nans, are '
|
|
jpayne@68
|
5431 'formatted as |\n'
|
|
jpayne@68
|
5432 ' | | "inf", "-inf", "0", "-0" and "nan" '
|
|
jpayne@68
|
5433 'respectively, |\n'
|
|
jpayne@68
|
5434 ' | | regardless of the precision. A precision '
|
|
jpayne@68
|
5435 'of "0" is |\n'
|
|
jpayne@68
|
5436 ' | | treated as equivalent to a precision of '
|
|
jpayne@68
|
5437 '"1". The default |\n'
|
|
jpayne@68
|
5438 ' | | precision is '
|
|
jpayne@68
|
5439 '"6". |\n'
|
|
jpayne@68
|
5440 ' '
|
|
jpayne@68
|
5441 '+-----------+------------------------------------------------------------+\n'
|
|
jpayne@68
|
5442 ' | "\'G\'" | General format. Same as "\'g\'" except '
|
|
jpayne@68
|
5443 'switches to "\'E\'" if |\n'
|
|
jpayne@68
|
5444 ' | | the number gets too large. The '
|
|
jpayne@68
|
5445 'representations of infinity |\n'
|
|
jpayne@68
|
5446 ' | | and NaN are uppercased, '
|
|
jpayne@68
|
5447 'too. |\n'
|
|
jpayne@68
|
5448 ' '
|
|
jpayne@68
|
5449 '+-----------+------------------------------------------------------------+\n'
|
|
jpayne@68
|
5450 ' | "\'n\'" | Number. This is the same as "\'g\'", '
|
|
jpayne@68
|
5451 'except that it uses the |\n'
|
|
jpayne@68
|
5452 ' | | current locale setting to insert the '
|
|
jpayne@68
|
5453 'appropriate number |\n'
|
|
jpayne@68
|
5454 ' | | separator '
|
|
jpayne@68
|
5455 'characters. |\n'
|
|
jpayne@68
|
5456 ' '
|
|
jpayne@68
|
5457 '+-----------+------------------------------------------------------------+\n'
|
|
jpayne@68
|
5458 ' | "\'%\'" | Percentage. Multiplies the number by 100 '
|
|
jpayne@68
|
5459 'and displays in |\n'
|
|
jpayne@68
|
5460 ' | | fixed ("\'f\'") format, followed by a '
|
|
jpayne@68
|
5461 'percent sign. |\n'
|
|
jpayne@68
|
5462 ' '
|
|
jpayne@68
|
5463 '+-----------+------------------------------------------------------------+\n'
|
|
jpayne@68
|
5464 ' | None | Similar to "\'g\'", except that '
|
|
jpayne@68
|
5465 'fixed-point notation, when |\n'
|
|
jpayne@68
|
5466 ' | | used, has at least one digit past the '
|
|
jpayne@68
|
5467 'decimal point. The |\n'
|
|
jpayne@68
|
5468 ' | | default precision is as high as needed to '
|
|
jpayne@68
|
5469 'represent the |\n'
|
|
jpayne@68
|
5470 ' | | particular value. The overall effect is to '
|
|
jpayne@68
|
5471 'match the |\n'
|
|
jpayne@68
|
5472 ' | | output of "str()" as altered by the other '
|
|
jpayne@68
|
5473 'format |\n'
|
|
jpayne@68
|
5474 ' | | '
|
|
jpayne@68
|
5475 'modifiers. '
|
|
jpayne@68
|
5476 '|\n'
|
|
jpayne@68
|
5477 ' '
|
|
jpayne@68
|
5478 '+-----------+------------------------------------------------------------+\n'
|
|
jpayne@68
|
5479 '\n'
|
|
jpayne@68
|
5480 '\n'
|
|
jpayne@68
|
5481 'Format examples\n'
|
|
jpayne@68
|
5482 '===============\n'
|
|
jpayne@68
|
5483 '\n'
|
|
jpayne@68
|
5484 'This section contains examples of the "str.format()" syntax '
|
|
jpayne@68
|
5485 'and\n'
|
|
jpayne@68
|
5486 'comparison with the old "%"-formatting.\n'
|
|
jpayne@68
|
5487 '\n'
|
|
jpayne@68
|
5488 'In most of the cases the syntax is similar to the old '
|
|
jpayne@68
|
5489 '"%"-formatting,\n'
|
|
jpayne@68
|
5490 'with the addition of the "{}" and with ":" used instead of '
|
|
jpayne@68
|
5491 '"%". For\n'
|
|
jpayne@68
|
5492 'example, "\'%03.2f\'" can be translated to "\'{:03.2f}\'".\n'
|
|
jpayne@68
|
5493 '\n'
|
|
jpayne@68
|
5494 'The new format syntax also supports new and different '
|
|
jpayne@68
|
5495 'options, shown\n'
|
|
jpayne@68
|
5496 'in the following examples.\n'
|
|
jpayne@68
|
5497 '\n'
|
|
jpayne@68
|
5498 'Accessing arguments by position:\n'
|
|
jpayne@68
|
5499 '\n'
|
|
jpayne@68
|
5500 " >>> '{0}, {1}, {2}'.format('a', 'b', 'c')\n"
|
|
jpayne@68
|
5501 " 'a, b, c'\n"
|
|
jpayne@68
|
5502 " >>> '{}, {}, {}'.format('a', 'b', 'c') # 3.1+ only\n"
|
|
jpayne@68
|
5503 " 'a, b, c'\n"
|
|
jpayne@68
|
5504 " >>> '{2}, {1}, {0}'.format('a', 'b', 'c')\n"
|
|
jpayne@68
|
5505 " 'c, b, a'\n"
|
|
jpayne@68
|
5506 " >>> '{2}, {1}, {0}'.format(*'abc') # unpacking "
|
|
jpayne@68
|
5507 'argument sequence\n'
|
|
jpayne@68
|
5508 " 'c, b, a'\n"
|
|
jpayne@68
|
5509 " >>> '{0}{1}{0}'.format('abra', 'cad') # arguments' "
|
|
jpayne@68
|
5510 'indices can be repeated\n'
|
|
jpayne@68
|
5511 " 'abracadabra'\n"
|
|
jpayne@68
|
5512 '\n'
|
|
jpayne@68
|
5513 'Accessing arguments by name:\n'
|
|
jpayne@68
|
5514 '\n'
|
|
jpayne@68
|
5515 " >>> 'Coordinates: {latitude}, "
|
|
jpayne@68
|
5516 "{longitude}'.format(latitude='37.24N', "
|
|
jpayne@68
|
5517 "longitude='-115.81W')\n"
|
|
jpayne@68
|
5518 " 'Coordinates: 37.24N, -115.81W'\n"
|
|
jpayne@68
|
5519 " >>> coord = {'latitude': '37.24N', 'longitude': "
|
|
jpayne@68
|
5520 "'-115.81W'}\n"
|
|
jpayne@68
|
5521 " >>> 'Coordinates: {latitude}, "
|
|
jpayne@68
|
5522 "{longitude}'.format(**coord)\n"
|
|
jpayne@68
|
5523 " 'Coordinates: 37.24N, -115.81W'\n"
|
|
jpayne@68
|
5524 '\n'
|
|
jpayne@68
|
5525 'Accessing arguments’ attributes:\n'
|
|
jpayne@68
|
5526 '\n'
|
|
jpayne@68
|
5527 ' >>> c = 3-5j\n'
|
|
jpayne@68
|
5528 " >>> ('The complex number {0} is formed from the real "
|
|
jpayne@68
|
5529 "part {0.real} '\n"
|
|
jpayne@68
|
5530 " ... 'and the imaginary part {0.imag}.').format(c)\n"
|
|
jpayne@68
|
5531 " 'The complex number (3-5j) is formed from the real part "
|
|
jpayne@68
|
5532 "3.0 and the imaginary part -5.0.'\n"
|
|
jpayne@68
|
5533 ' >>> class Point:\n'
|
|
jpayne@68
|
5534 ' ... def __init__(self, x, y):\n'
|
|
jpayne@68
|
5535 ' ... self.x, self.y = x, y\n'
|
|
jpayne@68
|
5536 ' ... def __str__(self):\n'
|
|
jpayne@68
|
5537 " ... return 'Point({self.x}, "
|
|
jpayne@68
|
5538 "{self.y})'.format(self=self)\n"
|
|
jpayne@68
|
5539 ' ...\n'
|
|
jpayne@68
|
5540 ' >>> str(Point(4, 2))\n'
|
|
jpayne@68
|
5541 " 'Point(4, 2)'\n"
|
|
jpayne@68
|
5542 '\n'
|
|
jpayne@68
|
5543 'Accessing arguments’ items:\n'
|
|
jpayne@68
|
5544 '\n'
|
|
jpayne@68
|
5545 ' >>> coord = (3, 5)\n'
|
|
jpayne@68
|
5546 " >>> 'X: {0[0]}; Y: {0[1]}'.format(coord)\n"
|
|
jpayne@68
|
5547 " 'X: 3; Y: 5'\n"
|
|
jpayne@68
|
5548 '\n'
|
|
jpayne@68
|
5549 'Replacing "%s" and "%r":\n'
|
|
jpayne@68
|
5550 '\n'
|
|
jpayne@68
|
5551 ' >>> "repr() shows quotes: {!r}; str() doesn\'t: '
|
|
jpayne@68
|
5552 '{!s}".format(\'test1\', \'test2\')\n'
|
|
jpayne@68
|
5553 ' "repr() shows quotes: \'test1\'; str() doesn\'t: test2"\n'
|
|
jpayne@68
|
5554 '\n'
|
|
jpayne@68
|
5555 'Aligning the text and specifying a width:\n'
|
|
jpayne@68
|
5556 '\n'
|
|
jpayne@68
|
5557 " >>> '{:<30}'.format('left aligned')\n"
|
|
jpayne@68
|
5558 " 'left aligned '\n"
|
|
jpayne@68
|
5559 " >>> '{:>30}'.format('right aligned')\n"
|
|
jpayne@68
|
5560 " ' right aligned'\n"
|
|
jpayne@68
|
5561 " >>> '{:^30}'.format('centered')\n"
|
|
jpayne@68
|
5562 " ' centered '\n"
|
|
jpayne@68
|
5563 " >>> '{:*^30}'.format('centered') # use '*' as a fill "
|
|
jpayne@68
|
5564 'char\n'
|
|
jpayne@68
|
5565 " '***********centered***********'\n"
|
|
jpayne@68
|
5566 '\n'
|
|
jpayne@68
|
5567 'Replacing "%+f", "%-f", and "% f" and specifying a sign:\n'
|
|
jpayne@68
|
5568 '\n'
|
|
jpayne@68
|
5569 " >>> '{:+f}; {:+f}'.format(3.14, -3.14) # show it "
|
|
jpayne@68
|
5570 'always\n'
|
|
jpayne@68
|
5571 " '+3.140000; -3.140000'\n"
|
|
jpayne@68
|
5572 " >>> '{: f}; {: f}'.format(3.14, -3.14) # show a space "
|
|
jpayne@68
|
5573 'for positive numbers\n'
|
|
jpayne@68
|
5574 " ' 3.140000; -3.140000'\n"
|
|
jpayne@68
|
5575 " >>> '{:-f}; {:-f}'.format(3.14, -3.14) # show only the "
|
|
jpayne@68
|
5576 "minus -- same as '{:f}; {:f}'\n"
|
|
jpayne@68
|
5577 " '3.140000; -3.140000'\n"
|
|
jpayne@68
|
5578 '\n'
|
|
jpayne@68
|
5579 'Replacing "%x" and "%o" and converting the value to '
|
|
jpayne@68
|
5580 'different bases:\n'
|
|
jpayne@68
|
5581 '\n'
|
|
jpayne@68
|
5582 ' >>> # format also supports binary numbers\n'
|
|
jpayne@68
|
5583 ' >>> "int: {0:d}; hex: {0:x}; oct: {0:o}; bin: '
|
|
jpayne@68
|
5584 '{0:b}".format(42)\n'
|
|
jpayne@68
|
5585 " 'int: 42; hex: 2a; oct: 52; bin: 101010'\n"
|
|
jpayne@68
|
5586 ' >>> # with 0x, 0o, or 0b as prefix:\n'
|
|
jpayne@68
|
5587 ' >>> "int: {0:d}; hex: {0:#x}; oct: {0:#o}; bin: '
|
|
jpayne@68
|
5588 '{0:#b}".format(42)\n'
|
|
jpayne@68
|
5589 " 'int: 42; hex: 0x2a; oct: 0o52; bin: 0b101010'\n"
|
|
jpayne@68
|
5590 '\n'
|
|
jpayne@68
|
5591 'Using the comma as a thousands separator:\n'
|
|
jpayne@68
|
5592 '\n'
|
|
jpayne@68
|
5593 " >>> '{:,}'.format(1234567890)\n"
|
|
jpayne@68
|
5594 " '1,234,567,890'\n"
|
|
jpayne@68
|
5595 '\n'
|
|
jpayne@68
|
5596 'Expressing a percentage:\n'
|
|
jpayne@68
|
5597 '\n'
|
|
jpayne@68
|
5598 ' >>> points = 19\n'
|
|
jpayne@68
|
5599 ' >>> total = 22\n'
|
|
jpayne@68
|
5600 " >>> 'Correct answers: {:.2%}'.format(points/total)\n"
|
|
jpayne@68
|
5601 " 'Correct answers: 86.36%'\n"
|
|
jpayne@68
|
5602 '\n'
|
|
jpayne@68
|
5603 'Using type-specific formatting:\n'
|
|
jpayne@68
|
5604 '\n'
|
|
jpayne@68
|
5605 ' >>> import datetime\n'
|
|
jpayne@68
|
5606 ' >>> d = datetime.datetime(2010, 7, 4, 12, 15, 58)\n'
|
|
jpayne@68
|
5607 " >>> '{:%Y-%m-%d %H:%M:%S}'.format(d)\n"
|
|
jpayne@68
|
5608 " '2010-07-04 12:15:58'\n"
|
|
jpayne@68
|
5609 '\n'
|
|
jpayne@68
|
5610 'Nesting arguments and more complex examples:\n'
|
|
jpayne@68
|
5611 '\n'
|
|
jpayne@68
|
5612 " >>> for align, text in zip('<^>', ['left', 'center', "
|
|
jpayne@68
|
5613 "'right']):\n"
|
|
jpayne@68
|
5614 " ... '{0:{fill}{align}16}'.format(text, fill=align, "
|
|
jpayne@68
|
5615 'align=align)\n'
|
|
jpayne@68
|
5616 ' ...\n'
|
|
jpayne@68
|
5617 " 'left<<<<<<<<<<<<'\n"
|
|
jpayne@68
|
5618 " '^^^^^center^^^^^'\n"
|
|
jpayne@68
|
5619 " '>>>>>>>>>>>right'\n"
|
|
jpayne@68
|
5620 ' >>>\n'
|
|
jpayne@68
|
5621 ' >>> octets = [192, 168, 0, 1]\n'
|
|
jpayne@68
|
5622 " >>> '{:02X}{:02X}{:02X}{:02X}'.format(*octets)\n"
|
|
jpayne@68
|
5623 " 'C0A80001'\n"
|
|
jpayne@68
|
5624 ' >>> int(_, 16)\n'
|
|
jpayne@68
|
5625 ' 3232235521\n'
|
|
jpayne@68
|
5626 ' >>>\n'
|
|
jpayne@68
|
5627 ' >>> width = 5\n'
|
|
jpayne@68
|
5628 ' >>> for num in range(5,12): \n'
|
|
jpayne@68
|
5629 " ... for base in 'dXob':\n"
|
|
jpayne@68
|
5630 " ... print('{0:{width}{base}}'.format(num, "
|
|
jpayne@68
|
5631 "base=base, width=width), end=' ')\n"
|
|
jpayne@68
|
5632 ' ... print()\n'
|
|
jpayne@68
|
5633 ' ...\n'
|
|
jpayne@68
|
5634 ' 5 5 5 101\n'
|
|
jpayne@68
|
5635 ' 6 6 6 110\n'
|
|
jpayne@68
|
5636 ' 7 7 7 111\n'
|
|
jpayne@68
|
5637 ' 8 8 10 1000\n'
|
|
jpayne@68
|
5638 ' 9 9 11 1001\n'
|
|
jpayne@68
|
5639 ' 10 A 12 1010\n'
|
|
jpayne@68
|
5640 ' 11 B 13 1011\n',
|
|
jpayne@68
|
5641 'function': 'Function definitions\n'
|
|
jpayne@68
|
5642 '********************\n'
|
|
jpayne@68
|
5643 '\n'
|
|
jpayne@68
|
5644 'A function definition defines a user-defined function object '
|
|
jpayne@68
|
5645 '(see\n'
|
|
jpayne@68
|
5646 'section The standard type hierarchy):\n'
|
|
jpayne@68
|
5647 '\n'
|
|
jpayne@68
|
5648 ' funcdef ::= [decorators] "def" funcname "(" '
|
|
jpayne@68
|
5649 '[parameter_list] ")"\n'
|
|
jpayne@68
|
5650 ' ["->" expression] ":" suite\n'
|
|
jpayne@68
|
5651 ' decorators ::= decorator+\n'
|
|
jpayne@68
|
5652 ' decorator ::= "@" dotted_name ["(" '
|
|
jpayne@68
|
5653 '[argument_list [","]] ")"] NEWLINE\n'
|
|
jpayne@68
|
5654 ' dotted_name ::= identifier ("." identifier)*\n'
|
|
jpayne@68
|
5655 ' parameter_list ::= defparameter ("," '
|
|
jpayne@68
|
5656 'defparameter)* "," "/" ["," [parameter_list_no_posonly]]\n'
|
|
jpayne@68
|
5657 ' | parameter_list_no_posonly\n'
|
|
jpayne@68
|
5658 ' parameter_list_no_posonly ::= defparameter ("," '
|
|
jpayne@68
|
5659 'defparameter)* ["," [parameter_list_starargs]]\n'
|
|
jpayne@68
|
5660 ' | parameter_list_starargs\n'
|
|
jpayne@68
|
5661 ' parameter_list_starargs ::= "*" [parameter] ("," '
|
|
jpayne@68
|
5662 'defparameter)* ["," ["**" parameter [","]]]\n'
|
|
jpayne@68
|
5663 ' | "**" parameter [","]\n'
|
|
jpayne@68
|
5664 ' parameter ::= identifier [":" expression]\n'
|
|
jpayne@68
|
5665 ' defparameter ::= parameter ["=" expression]\n'
|
|
jpayne@68
|
5666 ' funcname ::= identifier\n'
|
|
jpayne@68
|
5667 '\n'
|
|
jpayne@68
|
5668 'A function definition is an executable statement. Its execution '
|
|
jpayne@68
|
5669 'binds\n'
|
|
jpayne@68
|
5670 'the function name in the current local namespace to a function '
|
|
jpayne@68
|
5671 'object\n'
|
|
jpayne@68
|
5672 '(a wrapper around the executable code for the function). This\n'
|
|
jpayne@68
|
5673 'function object contains a reference to the current global '
|
|
jpayne@68
|
5674 'namespace\n'
|
|
jpayne@68
|
5675 'as the global namespace to be used when the function is called.\n'
|
|
jpayne@68
|
5676 '\n'
|
|
jpayne@68
|
5677 'The function definition does not execute the function body; this '
|
|
jpayne@68
|
5678 'gets\n'
|
|
jpayne@68
|
5679 'executed only when the function is called. [2]\n'
|
|
jpayne@68
|
5680 '\n'
|
|
jpayne@68
|
5681 'A function definition may be wrapped by one or more *decorator*\n'
|
|
jpayne@68
|
5682 'expressions. Decorator expressions are evaluated when the '
|
|
jpayne@68
|
5683 'function is\n'
|
|
jpayne@68
|
5684 'defined, in the scope that contains the function definition. '
|
|
jpayne@68
|
5685 'The\n'
|
|
jpayne@68
|
5686 'result must be a callable, which is invoked with the function '
|
|
jpayne@68
|
5687 'object\n'
|
|
jpayne@68
|
5688 'as the only argument. The returned value is bound to the '
|
|
jpayne@68
|
5689 'function name\n'
|
|
jpayne@68
|
5690 'instead of the function object. Multiple decorators are applied '
|
|
jpayne@68
|
5691 'in\n'
|
|
jpayne@68
|
5692 'nested fashion. For example, the following code\n'
|
|
jpayne@68
|
5693 '\n'
|
|
jpayne@68
|
5694 ' @f1(arg)\n'
|
|
jpayne@68
|
5695 ' @f2\n'
|
|
jpayne@68
|
5696 ' def func(): pass\n'
|
|
jpayne@68
|
5697 '\n'
|
|
jpayne@68
|
5698 'is roughly equivalent to\n'
|
|
jpayne@68
|
5699 '\n'
|
|
jpayne@68
|
5700 ' def func(): pass\n'
|
|
jpayne@68
|
5701 ' func = f1(arg)(f2(func))\n'
|
|
jpayne@68
|
5702 '\n'
|
|
jpayne@68
|
5703 'except that the original function is not temporarily bound to '
|
|
jpayne@68
|
5704 'the name\n'
|
|
jpayne@68
|
5705 '"func".\n'
|
|
jpayne@68
|
5706 '\n'
|
|
jpayne@68
|
5707 'When one or more *parameters* have the form *parameter* "="\n'
|
|
jpayne@68
|
5708 '*expression*, the function is said to have “default parameter '
|
|
jpayne@68
|
5709 'values.”\n'
|
|
jpayne@68
|
5710 'For a parameter with a default value, the corresponding '
|
|
jpayne@68
|
5711 '*argument* may\n'
|
|
jpayne@68
|
5712 'be omitted from a call, in which case the parameter’s default '
|
|
jpayne@68
|
5713 'value is\n'
|
|
jpayne@68
|
5714 'substituted. If a parameter has a default value, all following\n'
|
|
jpayne@68
|
5715 'parameters up until the “"*"” must also have a default value — '
|
|
jpayne@68
|
5716 'this is\n'
|
|
jpayne@68
|
5717 'a syntactic restriction that is not expressed by the grammar.\n'
|
|
jpayne@68
|
5718 '\n'
|
|
jpayne@68
|
5719 '**Default parameter values are evaluated from left to right when '
|
|
jpayne@68
|
5720 'the\n'
|
|
jpayne@68
|
5721 'function definition is executed.** This means that the '
|
|
jpayne@68
|
5722 'expression is\n'
|
|
jpayne@68
|
5723 'evaluated once, when the function is defined, and that the same '
|
|
jpayne@68
|
5724 '“pre-\n'
|
|
jpayne@68
|
5725 'computed” value is used for each call. This is especially '
|
|
jpayne@68
|
5726 'important\n'
|
|
jpayne@68
|
5727 'to understand when a default parameter is a mutable object, such '
|
|
jpayne@68
|
5728 'as a\n'
|
|
jpayne@68
|
5729 'list or a dictionary: if the function modifies the object (e.g. '
|
|
jpayne@68
|
5730 'by\n'
|
|
jpayne@68
|
5731 'appending an item to a list), the default value is in effect '
|
|
jpayne@68
|
5732 'modified.\n'
|
|
jpayne@68
|
5733 'This is generally not what was intended. A way around this is '
|
|
jpayne@68
|
5734 'to use\n'
|
|
jpayne@68
|
5735 '"None" as the default, and explicitly test for it in the body of '
|
|
jpayne@68
|
5736 'the\n'
|
|
jpayne@68
|
5737 'function, e.g.:\n'
|
|
jpayne@68
|
5738 '\n'
|
|
jpayne@68
|
5739 ' def whats_on_the_telly(penguin=None):\n'
|
|
jpayne@68
|
5740 ' if penguin is None:\n'
|
|
jpayne@68
|
5741 ' penguin = []\n'
|
|
jpayne@68
|
5742 ' penguin.append("property of the zoo")\n'
|
|
jpayne@68
|
5743 ' return penguin\n'
|
|
jpayne@68
|
5744 '\n'
|
|
jpayne@68
|
5745 'Function call semantics are described in more detail in section '
|
|
jpayne@68
|
5746 'Calls.\n'
|
|
jpayne@68
|
5747 'A function call always assigns values to all parameters '
|
|
jpayne@68
|
5748 'mentioned in\n'
|
|
jpayne@68
|
5749 'the parameter list, either from position arguments, from '
|
|
jpayne@68
|
5750 'keyword\n'
|
|
jpayne@68
|
5751 'arguments, or from default values. If the form “"*identifier"” '
|
|
jpayne@68
|
5752 'is\n'
|
|
jpayne@68
|
5753 'present, it is initialized to a tuple receiving any excess '
|
|
jpayne@68
|
5754 'positional\n'
|
|
jpayne@68
|
5755 'parameters, defaulting to the empty tuple. If the form\n'
|
|
jpayne@68
|
5756 '“"**identifier"” is present, it is initialized to a new ordered\n'
|
|
jpayne@68
|
5757 'mapping receiving any excess keyword arguments, defaulting to a '
|
|
jpayne@68
|
5758 'new\n'
|
|
jpayne@68
|
5759 'empty mapping of the same type. Parameters after “"*"” or\n'
|
|
jpayne@68
|
5760 '“"*identifier"” are keyword-only parameters and may only be '
|
|
jpayne@68
|
5761 'passed\n'
|
|
jpayne@68
|
5762 'used keyword arguments.\n'
|
|
jpayne@68
|
5763 '\n'
|
|
jpayne@68
|
5764 'Parameters may have an *annotation* of the form “": '
|
|
jpayne@68
|
5765 'expression"”\n'
|
|
jpayne@68
|
5766 'following the parameter name. Any parameter may have an '
|
|
jpayne@68
|
5767 'annotation,\n'
|
|
jpayne@68
|
5768 'even those of the form "*identifier" or "**identifier". '
|
|
jpayne@68
|
5769 'Functions may\n'
|
|
jpayne@68
|
5770 'have “return” annotation of the form “"-> expression"” after '
|
|
jpayne@68
|
5771 'the\n'
|
|
jpayne@68
|
5772 'parameter list. These annotations can be any valid Python '
|
|
jpayne@68
|
5773 'expression.\n'
|
|
jpayne@68
|
5774 'The presence of annotations does not change the semantics of a\n'
|
|
jpayne@68
|
5775 'function. The annotation values are available as values of a\n'
|
|
jpayne@68
|
5776 'dictionary keyed by the parameters’ names in the '
|
|
jpayne@68
|
5777 '"__annotations__"\n'
|
|
jpayne@68
|
5778 'attribute of the function object. If the "annotations" import '
|
|
jpayne@68
|
5779 'from\n'
|
|
jpayne@68
|
5780 '"__future__" is used, annotations are preserved as strings at '
|
|
jpayne@68
|
5781 'runtime\n'
|
|
jpayne@68
|
5782 'which enables postponed evaluation. Otherwise, they are '
|
|
jpayne@68
|
5783 'evaluated\n'
|
|
jpayne@68
|
5784 'when the function definition is executed. In this case '
|
|
jpayne@68
|
5785 'annotations\n'
|
|
jpayne@68
|
5786 'may be evaluated in a different order than they appear in the '
|
|
jpayne@68
|
5787 'source\n'
|
|
jpayne@68
|
5788 'code.\n'
|
|
jpayne@68
|
5789 '\n'
|
|
jpayne@68
|
5790 'It is also possible to create anonymous functions (functions not '
|
|
jpayne@68
|
5791 'bound\n'
|
|
jpayne@68
|
5792 'to a name), for immediate use in expressions. This uses lambda\n'
|
|
jpayne@68
|
5793 'expressions, described in section Lambdas. Note that the '
|
|
jpayne@68
|
5794 'lambda\n'
|
|
jpayne@68
|
5795 'expression is merely a shorthand for a simplified function '
|
|
jpayne@68
|
5796 'definition;\n'
|
|
jpayne@68
|
5797 'a function defined in a “"def"” statement can be passed around '
|
|
jpayne@68
|
5798 'or\n'
|
|
jpayne@68
|
5799 'assigned to another name just like a function defined by a '
|
|
jpayne@68
|
5800 'lambda\n'
|
|
jpayne@68
|
5801 'expression. The “"def"” form is actually more powerful since '
|
|
jpayne@68
|
5802 'it\n'
|
|
jpayne@68
|
5803 'allows the execution of multiple statements and annotations.\n'
|
|
jpayne@68
|
5804 '\n'
|
|
jpayne@68
|
5805 '**Programmer’s note:** Functions are first-class objects. A '
|
|
jpayne@68
|
5806 '“"def"”\n'
|
|
jpayne@68
|
5807 'statement executed inside a function definition defines a local\n'
|
|
jpayne@68
|
5808 'function that can be returned or passed around. Free variables '
|
|
jpayne@68
|
5809 'used\n'
|
|
jpayne@68
|
5810 'in the nested function can access the local variables of the '
|
|
jpayne@68
|
5811 'function\n'
|
|
jpayne@68
|
5812 'containing the def. See section Naming and binding for '
|
|
jpayne@68
|
5813 'details.\n'
|
|
jpayne@68
|
5814 '\n'
|
|
jpayne@68
|
5815 'See also:\n'
|
|
jpayne@68
|
5816 '\n'
|
|
jpayne@68
|
5817 ' **PEP 3107** - Function Annotations\n'
|
|
jpayne@68
|
5818 ' The original specification for function annotations.\n'
|
|
jpayne@68
|
5819 '\n'
|
|
jpayne@68
|
5820 ' **PEP 484** - Type Hints\n'
|
|
jpayne@68
|
5821 ' Definition of a standard meaning for annotations: type '
|
|
jpayne@68
|
5822 'hints.\n'
|
|
jpayne@68
|
5823 '\n'
|
|
jpayne@68
|
5824 ' **PEP 526** - Syntax for Variable Annotations\n'
|
|
jpayne@68
|
5825 ' Ability to type hint variable declarations, including '
|
|
jpayne@68
|
5826 'class\n'
|
|
jpayne@68
|
5827 ' variables and instance variables\n'
|
|
jpayne@68
|
5828 '\n'
|
|
jpayne@68
|
5829 ' **PEP 563** - Postponed Evaluation of Annotations\n'
|
|
jpayne@68
|
5830 ' Support for forward references within annotations by '
|
|
jpayne@68
|
5831 'preserving\n'
|
|
jpayne@68
|
5832 ' annotations in a string form at runtime instead of eager\n'
|
|
jpayne@68
|
5833 ' evaluation.\n',
|
|
jpayne@68
|
5834 'global': 'The "global" statement\n'
|
|
jpayne@68
|
5835 '**********************\n'
|
|
jpayne@68
|
5836 '\n'
|
|
jpayne@68
|
5837 ' global_stmt ::= "global" identifier ("," identifier)*\n'
|
|
jpayne@68
|
5838 '\n'
|
|
jpayne@68
|
5839 'The "global" statement is a declaration which holds for the '
|
|
jpayne@68
|
5840 'entire\n'
|
|
jpayne@68
|
5841 'current code block. It means that the listed identifiers are to '
|
|
jpayne@68
|
5842 'be\n'
|
|
jpayne@68
|
5843 'interpreted as globals. It would be impossible to assign to a '
|
|
jpayne@68
|
5844 'global\n'
|
|
jpayne@68
|
5845 'variable without "global", although free variables may refer to\n'
|
|
jpayne@68
|
5846 'globals without being declared global.\n'
|
|
jpayne@68
|
5847 '\n'
|
|
jpayne@68
|
5848 'Names listed in a "global" statement must not be used in the same '
|
|
jpayne@68
|
5849 'code\n'
|
|
jpayne@68
|
5850 'block textually preceding that "global" statement.\n'
|
|
jpayne@68
|
5851 '\n'
|
|
jpayne@68
|
5852 'Names listed in a "global" statement must not be defined as '
|
|
jpayne@68
|
5853 'formal\n'
|
|
jpayne@68
|
5854 'parameters or in a "for" loop control target, "class" definition,\n'
|
|
jpayne@68
|
5855 'function definition, "import" statement, or variable annotation.\n'
|
|
jpayne@68
|
5856 '\n'
|
|
jpayne@68
|
5857 '**CPython implementation detail:** The current implementation does '
|
|
jpayne@68
|
5858 'not\n'
|
|
jpayne@68
|
5859 'enforce some of these restrictions, but programs should not abuse '
|
|
jpayne@68
|
5860 'this\n'
|
|
jpayne@68
|
5861 'freedom, as future implementations may enforce them or silently '
|
|
jpayne@68
|
5862 'change\n'
|
|
jpayne@68
|
5863 'the meaning of the program.\n'
|
|
jpayne@68
|
5864 '\n'
|
|
jpayne@68
|
5865 '**Programmer’s note:** "global" is a directive to the parser. It\n'
|
|
jpayne@68
|
5866 'applies only to code parsed at the same time as the "global"\n'
|
|
jpayne@68
|
5867 'statement. In particular, a "global" statement contained in a '
|
|
jpayne@68
|
5868 'string\n'
|
|
jpayne@68
|
5869 'or code object supplied to the built-in "exec()" function does '
|
|
jpayne@68
|
5870 'not\n'
|
|
jpayne@68
|
5871 'affect the code block *containing* the function call, and code\n'
|
|
jpayne@68
|
5872 'contained in such a string is unaffected by "global" statements in '
|
|
jpayne@68
|
5873 'the\n'
|
|
jpayne@68
|
5874 'code containing the function call. The same applies to the '
|
|
jpayne@68
|
5875 '"eval()"\n'
|
|
jpayne@68
|
5876 'and "compile()" functions.\n',
|
|
jpayne@68
|
5877 'id-classes': 'Reserved classes of identifiers\n'
|
|
jpayne@68
|
5878 '*******************************\n'
|
|
jpayne@68
|
5879 '\n'
|
|
jpayne@68
|
5880 'Certain classes of identifiers (besides keywords) have '
|
|
jpayne@68
|
5881 'special\n'
|
|
jpayne@68
|
5882 'meanings. These classes are identified by the patterns of '
|
|
jpayne@68
|
5883 'leading and\n'
|
|
jpayne@68
|
5884 'trailing underscore characters:\n'
|
|
jpayne@68
|
5885 '\n'
|
|
jpayne@68
|
5886 '"_*"\n'
|
|
jpayne@68
|
5887 ' Not imported by "from module import *". The special '
|
|
jpayne@68
|
5888 'identifier "_"\n'
|
|
jpayne@68
|
5889 ' is used in the interactive interpreter to store the result '
|
|
jpayne@68
|
5890 'of the\n'
|
|
jpayne@68
|
5891 ' last evaluation; it is stored in the "builtins" module. '
|
|
jpayne@68
|
5892 'When not\n'
|
|
jpayne@68
|
5893 ' in interactive mode, "_" has no special meaning and is not '
|
|
jpayne@68
|
5894 'defined.\n'
|
|
jpayne@68
|
5895 ' See section The import statement.\n'
|
|
jpayne@68
|
5896 '\n'
|
|
jpayne@68
|
5897 ' Note: The name "_" is often used in conjunction with\n'
|
|
jpayne@68
|
5898 ' internationalization; refer to the documentation for the\n'
|
|
jpayne@68
|
5899 ' "gettext" module for more information on this '
|
|
jpayne@68
|
5900 'convention.\n'
|
|
jpayne@68
|
5901 '\n'
|
|
jpayne@68
|
5902 '"__*__"\n'
|
|
jpayne@68
|
5903 ' System-defined names. These names are defined by the '
|
|
jpayne@68
|
5904 'interpreter\n'
|
|
jpayne@68
|
5905 ' and its implementation (including the standard library). '
|
|
jpayne@68
|
5906 'Current\n'
|
|
jpayne@68
|
5907 ' system names are discussed in the Special method names '
|
|
jpayne@68
|
5908 'section and\n'
|
|
jpayne@68
|
5909 ' elsewhere. More will likely be defined in future versions '
|
|
jpayne@68
|
5910 'of\n'
|
|
jpayne@68
|
5911 ' Python. *Any* use of "__*__" names, in any context, that '
|
|
jpayne@68
|
5912 'does not\n'
|
|
jpayne@68
|
5913 ' follow explicitly documented use, is subject to breakage '
|
|
jpayne@68
|
5914 'without\n'
|
|
jpayne@68
|
5915 ' warning.\n'
|
|
jpayne@68
|
5916 '\n'
|
|
jpayne@68
|
5917 '"__*"\n'
|
|
jpayne@68
|
5918 ' Class-private names. Names in this category, when used '
|
|
jpayne@68
|
5919 'within the\n'
|
|
jpayne@68
|
5920 ' context of a class definition, are re-written to use a '
|
|
jpayne@68
|
5921 'mangled form\n'
|
|
jpayne@68
|
5922 ' to help avoid name clashes between “private” attributes of '
|
|
jpayne@68
|
5923 'base and\n'
|
|
jpayne@68
|
5924 ' derived classes. See section Identifiers (Names).\n',
|
|
jpayne@68
|
5925 'identifiers': 'Identifiers and keywords\n'
|
|
jpayne@68
|
5926 '************************\n'
|
|
jpayne@68
|
5927 '\n'
|
|
jpayne@68
|
5928 'Identifiers (also referred to as *names*) are described by '
|
|
jpayne@68
|
5929 'the\n'
|
|
jpayne@68
|
5930 'following lexical definitions.\n'
|
|
jpayne@68
|
5931 '\n'
|
|
jpayne@68
|
5932 'The syntax of identifiers in Python is based on the Unicode '
|
|
jpayne@68
|
5933 'standard\n'
|
|
jpayne@68
|
5934 'annex UAX-31, with elaboration and changes as defined below; '
|
|
jpayne@68
|
5935 'see also\n'
|
|
jpayne@68
|
5936 '**PEP 3131** for further details.\n'
|
|
jpayne@68
|
5937 '\n'
|
|
jpayne@68
|
5938 'Within the ASCII range (U+0001..U+007F), the valid characters '
|
|
jpayne@68
|
5939 'for\n'
|
|
jpayne@68
|
5940 'identifiers are the same as in Python 2.x: the uppercase and '
|
|
jpayne@68
|
5941 'lowercase\n'
|
|
jpayne@68
|
5942 'letters "A" through "Z", the underscore "_" and, except for '
|
|
jpayne@68
|
5943 'the first\n'
|
|
jpayne@68
|
5944 'character, the digits "0" through "9".\n'
|
|
jpayne@68
|
5945 '\n'
|
|
jpayne@68
|
5946 'Python 3.0 introduces additional characters from outside the '
|
|
jpayne@68
|
5947 'ASCII\n'
|
|
jpayne@68
|
5948 'range (see **PEP 3131**). For these characters, the '
|
|
jpayne@68
|
5949 'classification\n'
|
|
jpayne@68
|
5950 'uses the version of the Unicode Character Database as '
|
|
jpayne@68
|
5951 'included in the\n'
|
|
jpayne@68
|
5952 '"unicodedata" module.\n'
|
|
jpayne@68
|
5953 '\n'
|
|
jpayne@68
|
5954 'Identifiers are unlimited in length. Case is significant.\n'
|
|
jpayne@68
|
5955 '\n'
|
|
jpayne@68
|
5956 ' identifier ::= xid_start xid_continue*\n'
|
|
jpayne@68
|
5957 ' id_start ::= <all characters in general categories Lu, '
|
|
jpayne@68
|
5958 'Ll, Lt, Lm, Lo, Nl, the underscore, and characters with the '
|
|
jpayne@68
|
5959 'Other_ID_Start property>\n'
|
|
jpayne@68
|
5960 ' id_continue ::= <all characters in id_start, plus '
|
|
jpayne@68
|
5961 'characters in the categories Mn, Mc, Nd, Pc and others with '
|
|
jpayne@68
|
5962 'the Other_ID_Continue property>\n'
|
|
jpayne@68
|
5963 ' xid_start ::= <all characters in id_start whose NFKC '
|
|
jpayne@68
|
5964 'normalization is in "id_start xid_continue*">\n'
|
|
jpayne@68
|
5965 ' xid_continue ::= <all characters in id_continue whose NFKC '
|
|
jpayne@68
|
5966 'normalization is in "id_continue*">\n'
|
|
jpayne@68
|
5967 '\n'
|
|
jpayne@68
|
5968 'The Unicode category codes mentioned above stand for:\n'
|
|
jpayne@68
|
5969 '\n'
|
|
jpayne@68
|
5970 '* *Lu* - uppercase letters\n'
|
|
jpayne@68
|
5971 '\n'
|
|
jpayne@68
|
5972 '* *Ll* - lowercase letters\n'
|
|
jpayne@68
|
5973 '\n'
|
|
jpayne@68
|
5974 '* *Lt* - titlecase letters\n'
|
|
jpayne@68
|
5975 '\n'
|
|
jpayne@68
|
5976 '* *Lm* - modifier letters\n'
|
|
jpayne@68
|
5977 '\n'
|
|
jpayne@68
|
5978 '* *Lo* - other letters\n'
|
|
jpayne@68
|
5979 '\n'
|
|
jpayne@68
|
5980 '* *Nl* - letter numbers\n'
|
|
jpayne@68
|
5981 '\n'
|
|
jpayne@68
|
5982 '* *Mn* - nonspacing marks\n'
|
|
jpayne@68
|
5983 '\n'
|
|
jpayne@68
|
5984 '* *Mc* - spacing combining marks\n'
|
|
jpayne@68
|
5985 '\n'
|
|
jpayne@68
|
5986 '* *Nd* - decimal numbers\n'
|
|
jpayne@68
|
5987 '\n'
|
|
jpayne@68
|
5988 '* *Pc* - connector punctuations\n'
|
|
jpayne@68
|
5989 '\n'
|
|
jpayne@68
|
5990 '* *Other_ID_Start* - explicit list of characters in '
|
|
jpayne@68
|
5991 'PropList.txt to\n'
|
|
jpayne@68
|
5992 ' support backwards compatibility\n'
|
|
jpayne@68
|
5993 '\n'
|
|
jpayne@68
|
5994 '* *Other_ID_Continue* - likewise\n'
|
|
jpayne@68
|
5995 '\n'
|
|
jpayne@68
|
5996 'All identifiers are converted into the normal form NFKC while '
|
|
jpayne@68
|
5997 'parsing;\n'
|
|
jpayne@68
|
5998 'comparison of identifiers is based on NFKC.\n'
|
|
jpayne@68
|
5999 '\n'
|
|
jpayne@68
|
6000 'A non-normative HTML file listing all valid identifier '
|
|
jpayne@68
|
6001 'characters for\n'
|
|
jpayne@68
|
6002 'Unicode 4.1 can be found at https://www.dcl.hpi.uni-\n'
|
|
jpayne@68
|
6003 'potsdam.de/home/loewis/table-3131.html.\n'
|
|
jpayne@68
|
6004 '\n'
|
|
jpayne@68
|
6005 '\n'
|
|
jpayne@68
|
6006 'Keywords\n'
|
|
jpayne@68
|
6007 '========\n'
|
|
jpayne@68
|
6008 '\n'
|
|
jpayne@68
|
6009 'The following identifiers are used as reserved words, or '
|
|
jpayne@68
|
6010 '*keywords* of\n'
|
|
jpayne@68
|
6011 'the language, and cannot be used as ordinary identifiers. '
|
|
jpayne@68
|
6012 'They must\n'
|
|
jpayne@68
|
6013 'be spelled exactly as written here:\n'
|
|
jpayne@68
|
6014 '\n'
|
|
jpayne@68
|
6015 ' False await else import pass\n'
|
|
jpayne@68
|
6016 ' None break except in raise\n'
|
|
jpayne@68
|
6017 ' True class finally is return\n'
|
|
jpayne@68
|
6018 ' and continue for lambda try\n'
|
|
jpayne@68
|
6019 ' as def from nonlocal while\n'
|
|
jpayne@68
|
6020 ' assert del global not with\n'
|
|
jpayne@68
|
6021 ' async elif if or yield\n'
|
|
jpayne@68
|
6022 '\n'
|
|
jpayne@68
|
6023 '\n'
|
|
jpayne@68
|
6024 'Reserved classes of identifiers\n'
|
|
jpayne@68
|
6025 '===============================\n'
|
|
jpayne@68
|
6026 '\n'
|
|
jpayne@68
|
6027 'Certain classes of identifiers (besides keywords) have '
|
|
jpayne@68
|
6028 'special\n'
|
|
jpayne@68
|
6029 'meanings. These classes are identified by the patterns of '
|
|
jpayne@68
|
6030 'leading and\n'
|
|
jpayne@68
|
6031 'trailing underscore characters:\n'
|
|
jpayne@68
|
6032 '\n'
|
|
jpayne@68
|
6033 '"_*"\n'
|
|
jpayne@68
|
6034 ' Not imported by "from module import *". The special '
|
|
jpayne@68
|
6035 'identifier "_"\n'
|
|
jpayne@68
|
6036 ' is used in the interactive interpreter to store the result '
|
|
jpayne@68
|
6037 'of the\n'
|
|
jpayne@68
|
6038 ' last evaluation; it is stored in the "builtins" module. '
|
|
jpayne@68
|
6039 'When not\n'
|
|
jpayne@68
|
6040 ' in interactive mode, "_" has no special meaning and is not '
|
|
jpayne@68
|
6041 'defined.\n'
|
|
jpayne@68
|
6042 ' See section The import statement.\n'
|
|
jpayne@68
|
6043 '\n'
|
|
jpayne@68
|
6044 ' Note: The name "_" is often used in conjunction with\n'
|
|
jpayne@68
|
6045 ' internationalization; refer to the documentation for '
|
|
jpayne@68
|
6046 'the\n'
|
|
jpayne@68
|
6047 ' "gettext" module for more information on this '
|
|
jpayne@68
|
6048 'convention.\n'
|
|
jpayne@68
|
6049 '\n'
|
|
jpayne@68
|
6050 '"__*__"\n'
|
|
jpayne@68
|
6051 ' System-defined names. These names are defined by the '
|
|
jpayne@68
|
6052 'interpreter\n'
|
|
jpayne@68
|
6053 ' and its implementation (including the standard library). '
|
|
jpayne@68
|
6054 'Current\n'
|
|
jpayne@68
|
6055 ' system names are discussed in the Special method names '
|
|
jpayne@68
|
6056 'section and\n'
|
|
jpayne@68
|
6057 ' elsewhere. More will likely be defined in future versions '
|
|
jpayne@68
|
6058 'of\n'
|
|
jpayne@68
|
6059 ' Python. *Any* use of "__*__" names, in any context, that '
|
|
jpayne@68
|
6060 'does not\n'
|
|
jpayne@68
|
6061 ' follow explicitly documented use, is subject to breakage '
|
|
jpayne@68
|
6062 'without\n'
|
|
jpayne@68
|
6063 ' warning.\n'
|
|
jpayne@68
|
6064 '\n'
|
|
jpayne@68
|
6065 '"__*"\n'
|
|
jpayne@68
|
6066 ' Class-private names. Names in this category, when used '
|
|
jpayne@68
|
6067 'within the\n'
|
|
jpayne@68
|
6068 ' context of a class definition, are re-written to use a '
|
|
jpayne@68
|
6069 'mangled form\n'
|
|
jpayne@68
|
6070 ' to help avoid name clashes between “private” attributes of '
|
|
jpayne@68
|
6071 'base and\n'
|
|
jpayne@68
|
6072 ' derived classes. See section Identifiers (Names).\n',
|
|
jpayne@68
|
6073 'if': 'The "if" statement\n'
|
|
jpayne@68
|
6074 '******************\n'
|
|
jpayne@68
|
6075 '\n'
|
|
jpayne@68
|
6076 'The "if" statement is used for conditional execution:\n'
|
|
jpayne@68
|
6077 '\n'
|
|
jpayne@68
|
6078 ' if_stmt ::= "if" expression ":" suite\n'
|
|
jpayne@68
|
6079 ' ("elif" expression ":" suite)*\n'
|
|
jpayne@68
|
6080 ' ["else" ":" suite]\n'
|
|
jpayne@68
|
6081 '\n'
|
|
jpayne@68
|
6082 'It selects exactly one of the suites by evaluating the expressions '
|
|
jpayne@68
|
6083 'one\n'
|
|
jpayne@68
|
6084 'by one until one is found to be true (see section Boolean operations\n'
|
|
jpayne@68
|
6085 'for the definition of true and false); then that suite is executed\n'
|
|
jpayne@68
|
6086 '(and no other part of the "if" statement is executed or evaluated).\n'
|
|
jpayne@68
|
6087 'If all expressions are false, the suite of the "else" clause, if\n'
|
|
jpayne@68
|
6088 'present, is executed.\n',
|
|
jpayne@68
|
6089 'imaginary': 'Imaginary literals\n'
|
|
jpayne@68
|
6090 '******************\n'
|
|
jpayne@68
|
6091 '\n'
|
|
jpayne@68
|
6092 'Imaginary literals are described by the following lexical '
|
|
jpayne@68
|
6093 'definitions:\n'
|
|
jpayne@68
|
6094 '\n'
|
|
jpayne@68
|
6095 ' imagnumber ::= (floatnumber | digitpart) ("j" | "J")\n'
|
|
jpayne@68
|
6096 '\n'
|
|
jpayne@68
|
6097 'An imaginary literal yields a complex number with a real part '
|
|
jpayne@68
|
6098 'of 0.0.\n'
|
|
jpayne@68
|
6099 'Complex numbers are represented as a pair of floating point '
|
|
jpayne@68
|
6100 'numbers\n'
|
|
jpayne@68
|
6101 'and have the same restrictions on their range. To create a '
|
|
jpayne@68
|
6102 'complex\n'
|
|
jpayne@68
|
6103 'number with a nonzero real part, add a floating point number to '
|
|
jpayne@68
|
6104 'it,\n'
|
|
jpayne@68
|
6105 'e.g., "(3+4j)". Some examples of imaginary literals:\n'
|
|
jpayne@68
|
6106 '\n'
|
|
jpayne@68
|
6107 ' 3.14j 10.j 10j .001j 1e100j 3.14e-10j '
|
|
jpayne@68
|
6108 '3.14_15_93j\n',
|
|
jpayne@68
|
6109 'import': 'The "import" statement\n'
|
|
jpayne@68
|
6110 '**********************\n'
|
|
jpayne@68
|
6111 '\n'
|
|
jpayne@68
|
6112 ' import_stmt ::= "import" module ["as" identifier] ("," '
|
|
jpayne@68
|
6113 'module ["as" identifier])*\n'
|
|
jpayne@68
|
6114 ' | "from" relative_module "import" identifier '
|
|
jpayne@68
|
6115 '["as" identifier]\n'
|
|
jpayne@68
|
6116 ' ("," identifier ["as" identifier])*\n'
|
|
jpayne@68
|
6117 ' | "from" relative_module "import" "(" '
|
|
jpayne@68
|
6118 'identifier ["as" identifier]\n'
|
|
jpayne@68
|
6119 ' ("," identifier ["as" identifier])* [","] ")"\n'
|
|
jpayne@68
|
6120 ' | "from" module "import" "*"\n'
|
|
jpayne@68
|
6121 ' module ::= (identifier ".")* identifier\n'
|
|
jpayne@68
|
6122 ' relative_module ::= "."* module | "."+\n'
|
|
jpayne@68
|
6123 '\n'
|
|
jpayne@68
|
6124 'The basic import statement (no "from" clause) is executed in two\n'
|
|
jpayne@68
|
6125 'steps:\n'
|
|
jpayne@68
|
6126 '\n'
|
|
jpayne@68
|
6127 '1. find a module, loading and initializing it if necessary\n'
|
|
jpayne@68
|
6128 '\n'
|
|
jpayne@68
|
6129 '2. define a name or names in the local namespace for the scope\n'
|
|
jpayne@68
|
6130 ' where the "import" statement occurs.\n'
|
|
jpayne@68
|
6131 '\n'
|
|
jpayne@68
|
6132 'When the statement contains multiple clauses (separated by commas) '
|
|
jpayne@68
|
6133 'the\n'
|
|
jpayne@68
|
6134 'two steps are carried out separately for each clause, just as '
|
|
jpayne@68
|
6135 'though\n'
|
|
jpayne@68
|
6136 'the clauses had been separated out into individual import '
|
|
jpayne@68
|
6137 'statements.\n'
|
|
jpayne@68
|
6138 '\n'
|
|
jpayne@68
|
6139 'The details of the first step, finding and loading modules are\n'
|
|
jpayne@68
|
6140 'described in greater detail in the section on the import system, '
|
|
jpayne@68
|
6141 'which\n'
|
|
jpayne@68
|
6142 'also describes the various types of packages and modules that can '
|
|
jpayne@68
|
6143 'be\n'
|
|
jpayne@68
|
6144 'imported, as well as all the hooks that can be used to customize '
|
|
jpayne@68
|
6145 'the\n'
|
|
jpayne@68
|
6146 'import system. Note that failures in this step may indicate '
|
|
jpayne@68
|
6147 'either\n'
|
|
jpayne@68
|
6148 'that the module could not be located, *or* that an error occurred\n'
|
|
jpayne@68
|
6149 'while initializing the module, which includes execution of the\n'
|
|
jpayne@68
|
6150 'module’s code.\n'
|
|
jpayne@68
|
6151 '\n'
|
|
jpayne@68
|
6152 'If the requested module is retrieved successfully, it will be '
|
|
jpayne@68
|
6153 'made\n'
|
|
jpayne@68
|
6154 'available in the local namespace in one of three ways:\n'
|
|
jpayne@68
|
6155 '\n'
|
|
jpayne@68
|
6156 '* If the module name is followed by "as", then the name following\n'
|
|
jpayne@68
|
6157 ' "as" is bound directly to the imported module.\n'
|
|
jpayne@68
|
6158 '\n'
|
|
jpayne@68
|
6159 '* If no other name is specified, and the module being imported is '
|
|
jpayne@68
|
6160 'a\n'
|
|
jpayne@68
|
6161 ' top level module, the module’s name is bound in the local '
|
|
jpayne@68
|
6162 'namespace\n'
|
|
jpayne@68
|
6163 ' as a reference to the imported module\n'
|
|
jpayne@68
|
6164 '\n'
|
|
jpayne@68
|
6165 '* If the module being imported is *not* a top level module, then '
|
|
jpayne@68
|
6166 'the\n'
|
|
jpayne@68
|
6167 ' name of the top level package that contains the module is bound '
|
|
jpayne@68
|
6168 'in\n'
|
|
jpayne@68
|
6169 ' the local namespace as a reference to the top level package. '
|
|
jpayne@68
|
6170 'The\n'
|
|
jpayne@68
|
6171 ' imported module must be accessed using its full qualified name\n'
|
|
jpayne@68
|
6172 ' rather than directly\n'
|
|
jpayne@68
|
6173 '\n'
|
|
jpayne@68
|
6174 'The "from" form uses a slightly more complex process:\n'
|
|
jpayne@68
|
6175 '\n'
|
|
jpayne@68
|
6176 '1. find the module specified in the "from" clause, loading and\n'
|
|
jpayne@68
|
6177 ' initializing it if necessary;\n'
|
|
jpayne@68
|
6178 '\n'
|
|
jpayne@68
|
6179 '2. for each of the identifiers specified in the "import" clauses:\n'
|
|
jpayne@68
|
6180 '\n'
|
|
jpayne@68
|
6181 ' 1. check if the imported module has an attribute by that name\n'
|
|
jpayne@68
|
6182 '\n'
|
|
jpayne@68
|
6183 ' 2. if not, attempt to import a submodule with that name and '
|
|
jpayne@68
|
6184 'then\n'
|
|
jpayne@68
|
6185 ' check the imported module again for that attribute\n'
|
|
jpayne@68
|
6186 '\n'
|
|
jpayne@68
|
6187 ' 3. if the attribute is not found, "ImportError" is raised.\n'
|
|
jpayne@68
|
6188 '\n'
|
|
jpayne@68
|
6189 ' 4. otherwise, a reference to that value is stored in the local\n'
|
|
jpayne@68
|
6190 ' namespace, using the name in the "as" clause if it is '
|
|
jpayne@68
|
6191 'present,\n'
|
|
jpayne@68
|
6192 ' otherwise using the attribute name\n'
|
|
jpayne@68
|
6193 '\n'
|
|
jpayne@68
|
6194 'Examples:\n'
|
|
jpayne@68
|
6195 '\n'
|
|
jpayne@68
|
6196 ' import foo # foo imported and bound locally\n'
|
|
jpayne@68
|
6197 ' import foo.bar.baz # foo.bar.baz imported, foo bound '
|
|
jpayne@68
|
6198 'locally\n'
|
|
jpayne@68
|
6199 ' import foo.bar.baz as fbb # foo.bar.baz imported and bound as '
|
|
jpayne@68
|
6200 'fbb\n'
|
|
jpayne@68
|
6201 ' from foo.bar import baz # foo.bar.baz imported and bound as '
|
|
jpayne@68
|
6202 'baz\n'
|
|
jpayne@68
|
6203 ' from foo import attr # foo imported and foo.attr bound as '
|
|
jpayne@68
|
6204 'attr\n'
|
|
jpayne@68
|
6205 '\n'
|
|
jpayne@68
|
6206 'If the list of identifiers is replaced by a star ("\'*\'"), all '
|
|
jpayne@68
|
6207 'public\n'
|
|
jpayne@68
|
6208 'names defined in the module are bound in the local namespace for '
|
|
jpayne@68
|
6209 'the\n'
|
|
jpayne@68
|
6210 'scope where the "import" statement occurs.\n'
|
|
jpayne@68
|
6211 '\n'
|
|
jpayne@68
|
6212 'The *public names* defined by a module are determined by checking '
|
|
jpayne@68
|
6213 'the\n'
|
|
jpayne@68
|
6214 'module’s namespace for a variable named "__all__"; if defined, it '
|
|
jpayne@68
|
6215 'must\n'
|
|
jpayne@68
|
6216 'be a sequence of strings which are names defined or imported by '
|
|
jpayne@68
|
6217 'that\n'
|
|
jpayne@68
|
6218 'module. The names given in "__all__" are all considered public '
|
|
jpayne@68
|
6219 'and\n'
|
|
jpayne@68
|
6220 'are required to exist. If "__all__" is not defined, the set of '
|
|
jpayne@68
|
6221 'public\n'
|
|
jpayne@68
|
6222 'names includes all names found in the module’s namespace which do '
|
|
jpayne@68
|
6223 'not\n'
|
|
jpayne@68
|
6224 'begin with an underscore character ("\'_\'"). "__all__" should '
|
|
jpayne@68
|
6225 'contain\n'
|
|
jpayne@68
|
6226 'the entire public API. It is intended to avoid accidentally '
|
|
jpayne@68
|
6227 'exporting\n'
|
|
jpayne@68
|
6228 'items that are not part of the API (such as library modules which '
|
|
jpayne@68
|
6229 'were\n'
|
|
jpayne@68
|
6230 'imported and used within the module).\n'
|
|
jpayne@68
|
6231 '\n'
|
|
jpayne@68
|
6232 'The wild card form of import — "from module import *" — is only\n'
|
|
jpayne@68
|
6233 'allowed at the module level. Attempting to use it in class or\n'
|
|
jpayne@68
|
6234 'function definitions will raise a "SyntaxError".\n'
|
|
jpayne@68
|
6235 '\n'
|
|
jpayne@68
|
6236 'When specifying what module to import you do not have to specify '
|
|
jpayne@68
|
6237 'the\n'
|
|
jpayne@68
|
6238 'absolute name of the module. When a module or package is '
|
|
jpayne@68
|
6239 'contained\n'
|
|
jpayne@68
|
6240 'within another package it is possible to make a relative import '
|
|
jpayne@68
|
6241 'within\n'
|
|
jpayne@68
|
6242 'the same top package without having to mention the package name. '
|
|
jpayne@68
|
6243 'By\n'
|
|
jpayne@68
|
6244 'using leading dots in the specified module or package after "from" '
|
|
jpayne@68
|
6245 'you\n'
|
|
jpayne@68
|
6246 'can specify how high to traverse up the current package hierarchy\n'
|
|
jpayne@68
|
6247 'without specifying exact names. One leading dot means the current\n'
|
|
jpayne@68
|
6248 'package where the module making the import exists. Two dots means '
|
|
jpayne@68
|
6249 'up\n'
|
|
jpayne@68
|
6250 'one package level. Three dots is up two levels, etc. So if you '
|
|
jpayne@68
|
6251 'execute\n'
|
|
jpayne@68
|
6252 '"from . import mod" from a module in the "pkg" package then you '
|
|
jpayne@68
|
6253 'will\n'
|
|
jpayne@68
|
6254 'end up importing "pkg.mod". If you execute "from ..subpkg2 import '
|
|
jpayne@68
|
6255 'mod"\n'
|
|
jpayne@68
|
6256 'from within "pkg.subpkg1" you will import "pkg.subpkg2.mod". The\n'
|
|
jpayne@68
|
6257 'specification for relative imports is contained in the Package\n'
|
|
jpayne@68
|
6258 'Relative Imports section.\n'
|
|
jpayne@68
|
6259 '\n'
|
|
jpayne@68
|
6260 '"importlib.import_module()" is provided to support applications '
|
|
jpayne@68
|
6261 'that\n'
|
|
jpayne@68
|
6262 'determine dynamically the modules to be loaded.\n'
|
|
jpayne@68
|
6263 '\n'
|
|
jpayne@68
|
6264 'Raises an auditing event "import" with arguments "module", '
|
|
jpayne@68
|
6265 '"filename",\n'
|
|
jpayne@68
|
6266 '"sys.path", "sys.meta_path", "sys.path_hooks".\n'
|
|
jpayne@68
|
6267 '\n'
|
|
jpayne@68
|
6268 '\n'
|
|
jpayne@68
|
6269 'Future statements\n'
|
|
jpayne@68
|
6270 '=================\n'
|
|
jpayne@68
|
6271 '\n'
|
|
jpayne@68
|
6272 'A *future statement* is a directive to the compiler that a '
|
|
jpayne@68
|
6273 'particular\n'
|
|
jpayne@68
|
6274 'module should be compiled using syntax or semantics that will be\n'
|
|
jpayne@68
|
6275 'available in a specified future release of Python where the '
|
|
jpayne@68
|
6276 'feature\n'
|
|
jpayne@68
|
6277 'becomes standard.\n'
|
|
jpayne@68
|
6278 '\n'
|
|
jpayne@68
|
6279 'The future statement is intended to ease migration to future '
|
|
jpayne@68
|
6280 'versions\n'
|
|
jpayne@68
|
6281 'of Python that introduce incompatible changes to the language. '
|
|
jpayne@68
|
6282 'It\n'
|
|
jpayne@68
|
6283 'allows use of the new features on a per-module basis before the\n'
|
|
jpayne@68
|
6284 'release in which the feature becomes standard.\n'
|
|
jpayne@68
|
6285 '\n'
|
|
jpayne@68
|
6286 ' future_stmt ::= "from" "__future__" "import" feature ["as" '
|
|
jpayne@68
|
6287 'identifier]\n'
|
|
jpayne@68
|
6288 ' ("," feature ["as" identifier])*\n'
|
|
jpayne@68
|
6289 ' | "from" "__future__" "import" "(" feature '
|
|
jpayne@68
|
6290 '["as" identifier]\n'
|
|
jpayne@68
|
6291 ' ("," feature ["as" identifier])* [","] ")"\n'
|
|
jpayne@68
|
6292 ' feature ::= identifier\n'
|
|
jpayne@68
|
6293 '\n'
|
|
jpayne@68
|
6294 'A future statement must appear near the top of the module. The '
|
|
jpayne@68
|
6295 'only\n'
|
|
jpayne@68
|
6296 'lines that can appear before a future statement are:\n'
|
|
jpayne@68
|
6297 '\n'
|
|
jpayne@68
|
6298 '* the module docstring (if any),\n'
|
|
jpayne@68
|
6299 '\n'
|
|
jpayne@68
|
6300 '* comments,\n'
|
|
jpayne@68
|
6301 '\n'
|
|
jpayne@68
|
6302 '* blank lines, and\n'
|
|
jpayne@68
|
6303 '\n'
|
|
jpayne@68
|
6304 '* other future statements.\n'
|
|
jpayne@68
|
6305 '\n'
|
|
jpayne@68
|
6306 'The only feature in Python 3.7 that requires using the future\n'
|
|
jpayne@68
|
6307 'statement is "annotations".\n'
|
|
jpayne@68
|
6308 '\n'
|
|
jpayne@68
|
6309 'All historical features enabled by the future statement are still\n'
|
|
jpayne@68
|
6310 'recognized by Python 3. The list includes "absolute_import",\n'
|
|
jpayne@68
|
6311 '"division", "generators", "generator_stop", "unicode_literals",\n'
|
|
jpayne@68
|
6312 '"print_function", "nested_scopes" and "with_statement". They are '
|
|
jpayne@68
|
6313 'all\n'
|
|
jpayne@68
|
6314 'redundant because they are always enabled, and only kept for '
|
|
jpayne@68
|
6315 'backwards\n'
|
|
jpayne@68
|
6316 'compatibility.\n'
|
|
jpayne@68
|
6317 '\n'
|
|
jpayne@68
|
6318 'A future statement is recognized and treated specially at compile\n'
|
|
jpayne@68
|
6319 'time: Changes to the semantics of core constructs are often\n'
|
|
jpayne@68
|
6320 'implemented by generating different code. It may even be the '
|
|
jpayne@68
|
6321 'case\n'
|
|
jpayne@68
|
6322 'that a new feature introduces new incompatible syntax (such as a '
|
|
jpayne@68
|
6323 'new\n'
|
|
jpayne@68
|
6324 'reserved word), in which case the compiler may need to parse the\n'
|
|
jpayne@68
|
6325 'module differently. Such decisions cannot be pushed off until\n'
|
|
jpayne@68
|
6326 'runtime.\n'
|
|
jpayne@68
|
6327 '\n'
|
|
jpayne@68
|
6328 'For any given release, the compiler knows which feature names '
|
|
jpayne@68
|
6329 'have\n'
|
|
jpayne@68
|
6330 'been defined, and raises a compile-time error if a future '
|
|
jpayne@68
|
6331 'statement\n'
|
|
jpayne@68
|
6332 'contains a feature not known to it.\n'
|
|
jpayne@68
|
6333 '\n'
|
|
jpayne@68
|
6334 'The direct runtime semantics are the same as for any import '
|
|
jpayne@68
|
6335 'statement:\n'
|
|
jpayne@68
|
6336 'there is a standard module "__future__", described later, and it '
|
|
jpayne@68
|
6337 'will\n'
|
|
jpayne@68
|
6338 'be imported in the usual way at the time the future statement is\n'
|
|
jpayne@68
|
6339 'executed.\n'
|
|
jpayne@68
|
6340 '\n'
|
|
jpayne@68
|
6341 'The interesting runtime semantics depend on the specific feature\n'
|
|
jpayne@68
|
6342 'enabled by the future statement.\n'
|
|
jpayne@68
|
6343 '\n'
|
|
jpayne@68
|
6344 'Note that there is nothing special about the statement:\n'
|
|
jpayne@68
|
6345 '\n'
|
|
jpayne@68
|
6346 ' import __future__ [as name]\n'
|
|
jpayne@68
|
6347 '\n'
|
|
jpayne@68
|
6348 'That is not a future statement; it’s an ordinary import statement '
|
|
jpayne@68
|
6349 'with\n'
|
|
jpayne@68
|
6350 'no special semantics or syntax restrictions.\n'
|
|
jpayne@68
|
6351 '\n'
|
|
jpayne@68
|
6352 'Code compiled by calls to the built-in functions "exec()" and\n'
|
|
jpayne@68
|
6353 '"compile()" that occur in a module "M" containing a future '
|
|
jpayne@68
|
6354 'statement\n'
|
|
jpayne@68
|
6355 'will, by default, use the new syntax or semantics associated with '
|
|
jpayne@68
|
6356 'the\n'
|
|
jpayne@68
|
6357 'future statement. This can be controlled by optional arguments '
|
|
jpayne@68
|
6358 'to\n'
|
|
jpayne@68
|
6359 '"compile()" — see the documentation of that function for details.\n'
|
|
jpayne@68
|
6360 '\n'
|
|
jpayne@68
|
6361 'A future statement typed at an interactive interpreter prompt '
|
|
jpayne@68
|
6362 'will\n'
|
|
jpayne@68
|
6363 'take effect for the rest of the interpreter session. If an\n'
|
|
jpayne@68
|
6364 'interpreter is started with the "-i" option, is passed a script '
|
|
jpayne@68
|
6365 'name\n'
|
|
jpayne@68
|
6366 'to execute, and the script includes a future statement, it will be '
|
|
jpayne@68
|
6367 'in\n'
|
|
jpayne@68
|
6368 'effect in the interactive session started after the script is\n'
|
|
jpayne@68
|
6369 'executed.\n'
|
|
jpayne@68
|
6370 '\n'
|
|
jpayne@68
|
6371 'See also:\n'
|
|
jpayne@68
|
6372 '\n'
|
|
jpayne@68
|
6373 ' **PEP 236** - Back to the __future__\n'
|
|
jpayne@68
|
6374 ' The original proposal for the __future__ mechanism.\n',
|
|
jpayne@68
|
6375 'in': 'Membership test operations\n'
|
|
jpayne@68
|
6376 '**************************\n'
|
|
jpayne@68
|
6377 '\n'
|
|
jpayne@68
|
6378 'The operators "in" and "not in" test for membership. "x in s"\n'
|
|
jpayne@68
|
6379 'evaluates to "True" if *x* is a member of *s*, and "False" otherwise.\n'
|
|
jpayne@68
|
6380 '"x not in s" returns the negation of "x in s". All built-in '
|
|
jpayne@68
|
6381 'sequences\n'
|
|
jpayne@68
|
6382 'and set types support this as well as dictionary, for which "in" '
|
|
jpayne@68
|
6383 'tests\n'
|
|
jpayne@68
|
6384 'whether the dictionary has a given key. For container types such as\n'
|
|
jpayne@68
|
6385 'list, tuple, set, frozenset, dict, or collections.deque, the\n'
|
|
jpayne@68
|
6386 'expression "x in y" is equivalent to "any(x is e or x == e for e in\n'
|
|
jpayne@68
|
6387 'y)".\n'
|
|
jpayne@68
|
6388 '\n'
|
|
jpayne@68
|
6389 'For the string and bytes types, "x in y" is "True" if and only if *x*\n'
|
|
jpayne@68
|
6390 'is a substring of *y*. An equivalent test is "y.find(x) != -1".\n'
|
|
jpayne@68
|
6391 'Empty strings are always considered to be a substring of any other\n'
|
|
jpayne@68
|
6392 'string, so """ in "abc"" will return "True".\n'
|
|
jpayne@68
|
6393 '\n'
|
|
jpayne@68
|
6394 'For user-defined classes which define the "__contains__()" method, "x\n'
|
|
jpayne@68
|
6395 'in y" returns "True" if "y.__contains__(x)" returns a true value, and\n'
|
|
jpayne@68
|
6396 '"False" otherwise.\n'
|
|
jpayne@68
|
6397 '\n'
|
|
jpayne@68
|
6398 'For user-defined classes which do not define "__contains__()" but do\n'
|
|
jpayne@68
|
6399 'define "__iter__()", "x in y" is "True" if some value "z", for which\n'
|
|
jpayne@68
|
6400 'the expression "x is z or x == z" is true, is produced while '
|
|
jpayne@68
|
6401 'iterating\n'
|
|
jpayne@68
|
6402 'over "y". If an exception is raised during the iteration, it is as if\n'
|
|
jpayne@68
|
6403 '"in" raised that exception.\n'
|
|
jpayne@68
|
6404 '\n'
|
|
jpayne@68
|
6405 'Lastly, the old-style iteration protocol is tried: if a class defines\n'
|
|
jpayne@68
|
6406 '"__getitem__()", "x in y" is "True" if and only if there is a non-\n'
|
|
jpayne@68
|
6407 'negative integer index *i* such that "x is y[i] or x == y[i]", and no\n'
|
|
jpayne@68
|
6408 'lower integer index raises the "IndexError" exception. (If any other\n'
|
|
jpayne@68
|
6409 'exception is raised, it is as if "in" raised that exception).\n'
|
|
jpayne@68
|
6410 '\n'
|
|
jpayne@68
|
6411 'The operator "not in" is defined to have the inverse truth value of\n'
|
|
jpayne@68
|
6412 '"in".\n',
|
|
jpayne@68
|
6413 'integers': 'Integer literals\n'
|
|
jpayne@68
|
6414 '****************\n'
|
|
jpayne@68
|
6415 '\n'
|
|
jpayne@68
|
6416 'Integer literals are described by the following lexical '
|
|
jpayne@68
|
6417 'definitions:\n'
|
|
jpayne@68
|
6418 '\n'
|
|
jpayne@68
|
6419 ' integer ::= decinteger | bininteger | octinteger | '
|
|
jpayne@68
|
6420 'hexinteger\n'
|
|
jpayne@68
|
6421 ' decinteger ::= nonzerodigit (["_"] digit)* | "0"+ (["_"] '
|
|
jpayne@68
|
6422 '"0")*\n'
|
|
jpayne@68
|
6423 ' bininteger ::= "0" ("b" | "B") (["_"] bindigit)+\n'
|
|
jpayne@68
|
6424 ' octinteger ::= "0" ("o" | "O") (["_"] octdigit)+\n'
|
|
jpayne@68
|
6425 ' hexinteger ::= "0" ("x" | "X") (["_"] hexdigit)+\n'
|
|
jpayne@68
|
6426 ' nonzerodigit ::= "1"..."9"\n'
|
|
jpayne@68
|
6427 ' digit ::= "0"..."9"\n'
|
|
jpayne@68
|
6428 ' bindigit ::= "0" | "1"\n'
|
|
jpayne@68
|
6429 ' octdigit ::= "0"..."7"\n'
|
|
jpayne@68
|
6430 ' hexdigit ::= digit | "a"..."f" | "A"..."F"\n'
|
|
jpayne@68
|
6431 '\n'
|
|
jpayne@68
|
6432 'There is no limit for the length of integer literals apart from '
|
|
jpayne@68
|
6433 'what\n'
|
|
jpayne@68
|
6434 'can be stored in available memory.\n'
|
|
jpayne@68
|
6435 '\n'
|
|
jpayne@68
|
6436 'Underscores are ignored for determining the numeric value of '
|
|
jpayne@68
|
6437 'the\n'
|
|
jpayne@68
|
6438 'literal. They can be used to group digits for enhanced '
|
|
jpayne@68
|
6439 'readability.\n'
|
|
jpayne@68
|
6440 'One underscore can occur between digits, and after base '
|
|
jpayne@68
|
6441 'specifiers\n'
|
|
jpayne@68
|
6442 'like "0x".\n'
|
|
jpayne@68
|
6443 '\n'
|
|
jpayne@68
|
6444 'Note that leading zeros in a non-zero decimal number are not '
|
|
jpayne@68
|
6445 'allowed.\n'
|
|
jpayne@68
|
6446 'This is for disambiguation with C-style octal literals, which '
|
|
jpayne@68
|
6447 'Python\n'
|
|
jpayne@68
|
6448 'used before version 3.0.\n'
|
|
jpayne@68
|
6449 '\n'
|
|
jpayne@68
|
6450 'Some examples of integer literals:\n'
|
|
jpayne@68
|
6451 '\n'
|
|
jpayne@68
|
6452 ' 7 2147483647 0o177 0b100110111\n'
|
|
jpayne@68
|
6453 ' 3 79228162514264337593543950336 0o377 0xdeadbeef\n'
|
|
jpayne@68
|
6454 ' 100_000_000_000 0b_1110_0101\n'
|
|
jpayne@68
|
6455 '\n'
|
|
jpayne@68
|
6456 'Changed in version 3.6: Underscores are now allowed for '
|
|
jpayne@68
|
6457 'grouping\n'
|
|
jpayne@68
|
6458 'purposes in literals.\n',
|
|
jpayne@68
|
6459 'lambda': 'Lambdas\n'
|
|
jpayne@68
|
6460 '*******\n'
|
|
jpayne@68
|
6461 '\n'
|
|
jpayne@68
|
6462 ' lambda_expr ::= "lambda" [parameter_list] ":" '
|
|
jpayne@68
|
6463 'expression\n'
|
|
jpayne@68
|
6464 ' lambda_expr_nocond ::= "lambda" [parameter_list] ":" '
|
|
jpayne@68
|
6465 'expression_nocond\n'
|
|
jpayne@68
|
6466 '\n'
|
|
jpayne@68
|
6467 'Lambda expressions (sometimes called lambda forms) are used to '
|
|
jpayne@68
|
6468 'create\n'
|
|
jpayne@68
|
6469 'anonymous functions. The expression "lambda parameters: '
|
|
jpayne@68
|
6470 'expression"\n'
|
|
jpayne@68
|
6471 'yields a function object. The unnamed object behaves like a '
|
|
jpayne@68
|
6472 'function\n'
|
|
jpayne@68
|
6473 'object defined with:\n'
|
|
jpayne@68
|
6474 '\n'
|
|
jpayne@68
|
6475 ' def <lambda>(parameters):\n'
|
|
jpayne@68
|
6476 ' return expression\n'
|
|
jpayne@68
|
6477 '\n'
|
|
jpayne@68
|
6478 'See section Function definitions for the syntax of parameter '
|
|
jpayne@68
|
6479 'lists.\n'
|
|
jpayne@68
|
6480 'Note that functions created with lambda expressions cannot '
|
|
jpayne@68
|
6481 'contain\n'
|
|
jpayne@68
|
6482 'statements or annotations.\n',
|
|
jpayne@68
|
6483 'lists': 'List displays\n'
|
|
jpayne@68
|
6484 '*************\n'
|
|
jpayne@68
|
6485 '\n'
|
|
jpayne@68
|
6486 'A list display is a possibly empty series of expressions enclosed '
|
|
jpayne@68
|
6487 'in\n'
|
|
jpayne@68
|
6488 'square brackets:\n'
|
|
jpayne@68
|
6489 '\n'
|
|
jpayne@68
|
6490 ' list_display ::= "[" [starred_list | comprehension] "]"\n'
|
|
jpayne@68
|
6491 '\n'
|
|
jpayne@68
|
6492 'A list display yields a new list object, the contents being '
|
|
jpayne@68
|
6493 'specified\n'
|
|
jpayne@68
|
6494 'by either a list of expressions or a comprehension. When a comma-\n'
|
|
jpayne@68
|
6495 'separated list of expressions is supplied, its elements are '
|
|
jpayne@68
|
6496 'evaluated\n'
|
|
jpayne@68
|
6497 'from left to right and placed into the list object in that order.\n'
|
|
jpayne@68
|
6498 'When a comprehension is supplied, the list is constructed from the\n'
|
|
jpayne@68
|
6499 'elements resulting from the comprehension.\n',
|
|
jpayne@68
|
6500 'naming': 'Naming and binding\n'
|
|
jpayne@68
|
6501 '******************\n'
|
|
jpayne@68
|
6502 '\n'
|
|
jpayne@68
|
6503 '\n'
|
|
jpayne@68
|
6504 'Binding of names\n'
|
|
jpayne@68
|
6505 '================\n'
|
|
jpayne@68
|
6506 '\n'
|
|
jpayne@68
|
6507 '*Names* refer to objects. Names are introduced by name binding\n'
|
|
jpayne@68
|
6508 'operations.\n'
|
|
jpayne@68
|
6509 '\n'
|
|
jpayne@68
|
6510 'The following constructs bind names: formal parameters to '
|
|
jpayne@68
|
6511 'functions,\n'
|
|
jpayne@68
|
6512 '"import" statements, class and function definitions (these bind '
|
|
jpayne@68
|
6513 'the\n'
|
|
jpayne@68
|
6514 'class or function name in the defining block), and targets that '
|
|
jpayne@68
|
6515 'are\n'
|
|
jpayne@68
|
6516 'identifiers if occurring in an assignment, "for" loop header, or '
|
|
jpayne@68
|
6517 'after\n'
|
|
jpayne@68
|
6518 '"as" in a "with" statement or "except" clause. The "import" '
|
|
jpayne@68
|
6519 'statement\n'
|
|
jpayne@68
|
6520 'of the form "from ... import *" binds all names defined in the\n'
|
|
jpayne@68
|
6521 'imported module, except those beginning with an underscore. This '
|
|
jpayne@68
|
6522 'form\n'
|
|
jpayne@68
|
6523 'may only be used at the module level.\n'
|
|
jpayne@68
|
6524 '\n'
|
|
jpayne@68
|
6525 'A target occurring in a "del" statement is also considered bound '
|
|
jpayne@68
|
6526 'for\n'
|
|
jpayne@68
|
6527 'this purpose (though the actual semantics are to unbind the '
|
|
jpayne@68
|
6528 'name).\n'
|
|
jpayne@68
|
6529 '\n'
|
|
jpayne@68
|
6530 'Each assignment or import statement occurs within a block defined '
|
|
jpayne@68
|
6531 'by a\n'
|
|
jpayne@68
|
6532 'class or function definition or at the module level (the '
|
|
jpayne@68
|
6533 'top-level\n'
|
|
jpayne@68
|
6534 'code block).\n'
|
|
jpayne@68
|
6535 '\n'
|
|
jpayne@68
|
6536 'If a name is bound in a block, it is a local variable of that '
|
|
jpayne@68
|
6537 'block,\n'
|
|
jpayne@68
|
6538 'unless declared as "nonlocal" or "global". If a name is bound at '
|
|
jpayne@68
|
6539 'the\n'
|
|
jpayne@68
|
6540 'module level, it is a global variable. (The variables of the '
|
|
jpayne@68
|
6541 'module\n'
|
|
jpayne@68
|
6542 'code block are local and global.) If a variable is used in a '
|
|
jpayne@68
|
6543 'code\n'
|
|
jpayne@68
|
6544 'block but not defined there, it is a *free variable*.\n'
|
|
jpayne@68
|
6545 '\n'
|
|
jpayne@68
|
6546 'Each occurrence of a name in the program text refers to the '
|
|
jpayne@68
|
6547 '*binding*\n'
|
|
jpayne@68
|
6548 'of that name established by the following name resolution rules.\n'
|
|
jpayne@68
|
6549 '\n'
|
|
jpayne@68
|
6550 '\n'
|
|
jpayne@68
|
6551 'Resolution of names\n'
|
|
jpayne@68
|
6552 '===================\n'
|
|
jpayne@68
|
6553 '\n'
|
|
jpayne@68
|
6554 'A *scope* defines the visibility of a name within a block. If a '
|
|
jpayne@68
|
6555 'local\n'
|
|
jpayne@68
|
6556 'variable is defined in a block, its scope includes that block. If '
|
|
jpayne@68
|
6557 'the\n'
|
|
jpayne@68
|
6558 'definition occurs in a function block, the scope extends to any '
|
|
jpayne@68
|
6559 'blocks\n'
|
|
jpayne@68
|
6560 'contained within the defining one, unless a contained block '
|
|
jpayne@68
|
6561 'introduces\n'
|
|
jpayne@68
|
6562 'a different binding for the name.\n'
|
|
jpayne@68
|
6563 '\n'
|
|
jpayne@68
|
6564 'When a name is used in a code block, it is resolved using the '
|
|
jpayne@68
|
6565 'nearest\n'
|
|
jpayne@68
|
6566 'enclosing scope. The set of all such scopes visible to a code '
|
|
jpayne@68
|
6567 'block\n'
|
|
jpayne@68
|
6568 'is called the block’s *environment*.\n'
|
|
jpayne@68
|
6569 '\n'
|
|
jpayne@68
|
6570 'When a name is not found at all, a "NameError" exception is '
|
|
jpayne@68
|
6571 'raised. If\n'
|
|
jpayne@68
|
6572 'the current scope is a function scope, and the name refers to a '
|
|
jpayne@68
|
6573 'local\n'
|
|
jpayne@68
|
6574 'variable that has not yet been bound to a value at the point where '
|
|
jpayne@68
|
6575 'the\n'
|
|
jpayne@68
|
6576 'name is used, an "UnboundLocalError" exception is raised.\n'
|
|
jpayne@68
|
6577 '"UnboundLocalError" is a subclass of "NameError".\n'
|
|
jpayne@68
|
6578 '\n'
|
|
jpayne@68
|
6579 'If a name binding operation occurs anywhere within a code block, '
|
|
jpayne@68
|
6580 'all\n'
|
|
jpayne@68
|
6581 'uses of the name within the block are treated as references to '
|
|
jpayne@68
|
6582 'the\n'
|
|
jpayne@68
|
6583 'current block. This can lead to errors when a name is used within '
|
|
jpayne@68
|
6584 'a\n'
|
|
jpayne@68
|
6585 'block before it is bound. This rule is subtle. Python lacks\n'
|
|
jpayne@68
|
6586 'declarations and allows name binding operations to occur anywhere\n'
|
|
jpayne@68
|
6587 'within a code block. The local variables of a code block can be\n'
|
|
jpayne@68
|
6588 'determined by scanning the entire text of the block for name '
|
|
jpayne@68
|
6589 'binding\n'
|
|
jpayne@68
|
6590 'operations.\n'
|
|
jpayne@68
|
6591 '\n'
|
|
jpayne@68
|
6592 'If the "global" statement occurs within a block, all uses of the '
|
|
jpayne@68
|
6593 'name\n'
|
|
jpayne@68
|
6594 'specified in the statement refer to the binding of that name in '
|
|
jpayne@68
|
6595 'the\n'
|
|
jpayne@68
|
6596 'top-level namespace. Names are resolved in the top-level '
|
|
jpayne@68
|
6597 'namespace by\n'
|
|
jpayne@68
|
6598 'searching the global namespace, i.e. the namespace of the module\n'
|
|
jpayne@68
|
6599 'containing the code block, and the builtins namespace, the '
|
|
jpayne@68
|
6600 'namespace\n'
|
|
jpayne@68
|
6601 'of the module "builtins". The global namespace is searched '
|
|
jpayne@68
|
6602 'first. If\n'
|
|
jpayne@68
|
6603 'the name is not found there, the builtins namespace is searched. '
|
|
jpayne@68
|
6604 'The\n'
|
|
jpayne@68
|
6605 '"global" statement must precede all uses of the name.\n'
|
|
jpayne@68
|
6606 '\n'
|
|
jpayne@68
|
6607 'The "global" statement has the same scope as a name binding '
|
|
jpayne@68
|
6608 'operation\n'
|
|
jpayne@68
|
6609 'in the same block. If the nearest enclosing scope for a free '
|
|
jpayne@68
|
6610 'variable\n'
|
|
jpayne@68
|
6611 'contains a global statement, the free variable is treated as a '
|
|
jpayne@68
|
6612 'global.\n'
|
|
jpayne@68
|
6613 '\n'
|
|
jpayne@68
|
6614 'The "nonlocal" statement causes corresponding names to refer to\n'
|
|
jpayne@68
|
6615 'previously bound variables in the nearest enclosing function '
|
|
jpayne@68
|
6616 'scope.\n'
|
|
jpayne@68
|
6617 '"SyntaxError" is raised at compile time if the given name does '
|
|
jpayne@68
|
6618 'not\n'
|
|
jpayne@68
|
6619 'exist in any enclosing function scope.\n'
|
|
jpayne@68
|
6620 '\n'
|
|
jpayne@68
|
6621 'The namespace for a module is automatically created the first time '
|
|
jpayne@68
|
6622 'a\n'
|
|
jpayne@68
|
6623 'module is imported. The main module for a script is always '
|
|
jpayne@68
|
6624 'called\n'
|
|
jpayne@68
|
6625 '"__main__".\n'
|
|
jpayne@68
|
6626 '\n'
|
|
jpayne@68
|
6627 'Class definition blocks and arguments to "exec()" and "eval()" '
|
|
jpayne@68
|
6628 'are\n'
|
|
jpayne@68
|
6629 'special in the context of name resolution. A class definition is '
|
|
jpayne@68
|
6630 'an\n'
|
|
jpayne@68
|
6631 'executable statement that may use and define names. These '
|
|
jpayne@68
|
6632 'references\n'
|
|
jpayne@68
|
6633 'follow the normal rules for name resolution with an exception '
|
|
jpayne@68
|
6634 'that\n'
|
|
jpayne@68
|
6635 'unbound local variables are looked up in the global namespace. '
|
|
jpayne@68
|
6636 'The\n'
|
|
jpayne@68
|
6637 'namespace of the class definition becomes the attribute dictionary '
|
|
jpayne@68
|
6638 'of\n'
|
|
jpayne@68
|
6639 'the class. The scope of names defined in a class block is limited '
|
|
jpayne@68
|
6640 'to\n'
|
|
jpayne@68
|
6641 'the class block; it does not extend to the code blocks of methods '
|
|
jpayne@68
|
6642 '–\n'
|
|
jpayne@68
|
6643 'this includes comprehensions and generator expressions since they '
|
|
jpayne@68
|
6644 'are\n'
|
|
jpayne@68
|
6645 'implemented using a function scope. This means that the '
|
|
jpayne@68
|
6646 'following\n'
|
|
jpayne@68
|
6647 'will fail:\n'
|
|
jpayne@68
|
6648 '\n'
|
|
jpayne@68
|
6649 ' class A:\n'
|
|
jpayne@68
|
6650 ' a = 42\n'
|
|
jpayne@68
|
6651 ' b = list(a + i for i in range(10))\n'
|
|
jpayne@68
|
6652 '\n'
|
|
jpayne@68
|
6653 '\n'
|
|
jpayne@68
|
6654 'Builtins and restricted execution\n'
|
|
jpayne@68
|
6655 '=================================\n'
|
|
jpayne@68
|
6656 '\n'
|
|
jpayne@68
|
6657 '**CPython implementation detail:** Users should not touch\n'
|
|
jpayne@68
|
6658 '"__builtins__"; it is strictly an implementation detail. Users\n'
|
|
jpayne@68
|
6659 'wanting to override values in the builtins namespace should '
|
|
jpayne@68
|
6660 '"import"\n'
|
|
jpayne@68
|
6661 'the "builtins" module and modify its attributes appropriately.\n'
|
|
jpayne@68
|
6662 '\n'
|
|
jpayne@68
|
6663 'The builtins namespace associated with the execution of a code '
|
|
jpayne@68
|
6664 'block\n'
|
|
jpayne@68
|
6665 'is actually found by looking up the name "__builtins__" in its '
|
|
jpayne@68
|
6666 'global\n'
|
|
jpayne@68
|
6667 'namespace; this should be a dictionary or a module (in the latter '
|
|
jpayne@68
|
6668 'case\n'
|
|
jpayne@68
|
6669 'the module’s dictionary is used). By default, when in the '
|
|
jpayne@68
|
6670 '"__main__"\n'
|
|
jpayne@68
|
6671 'module, "__builtins__" is the built-in module "builtins"; when in '
|
|
jpayne@68
|
6672 'any\n'
|
|
jpayne@68
|
6673 'other module, "__builtins__" is an alias for the dictionary of '
|
|
jpayne@68
|
6674 'the\n'
|
|
jpayne@68
|
6675 '"builtins" module itself.\n'
|
|
jpayne@68
|
6676 '\n'
|
|
jpayne@68
|
6677 '\n'
|
|
jpayne@68
|
6678 'Interaction with dynamic features\n'
|
|
jpayne@68
|
6679 '=================================\n'
|
|
jpayne@68
|
6680 '\n'
|
|
jpayne@68
|
6681 'Name resolution of free variables occurs at runtime, not at '
|
|
jpayne@68
|
6682 'compile\n'
|
|
jpayne@68
|
6683 'time. This means that the following code will print 42:\n'
|
|
jpayne@68
|
6684 '\n'
|
|
jpayne@68
|
6685 ' i = 10\n'
|
|
jpayne@68
|
6686 ' def f():\n'
|
|
jpayne@68
|
6687 ' print(i)\n'
|
|
jpayne@68
|
6688 ' i = 42\n'
|
|
jpayne@68
|
6689 ' f()\n'
|
|
jpayne@68
|
6690 '\n'
|
|
jpayne@68
|
6691 'The "eval()" and "exec()" functions do not have access to the '
|
|
jpayne@68
|
6692 'full\n'
|
|
jpayne@68
|
6693 'environment for resolving names. Names may be resolved in the '
|
|
jpayne@68
|
6694 'local\n'
|
|
jpayne@68
|
6695 'and global namespaces of the caller. Free variables are not '
|
|
jpayne@68
|
6696 'resolved\n'
|
|
jpayne@68
|
6697 'in the nearest enclosing namespace, but in the global namespace. '
|
|
jpayne@68
|
6698 '[1]\n'
|
|
jpayne@68
|
6699 'The "exec()" and "eval()" functions have optional arguments to\n'
|
|
jpayne@68
|
6700 'override the global and local namespace. If only one namespace '
|
|
jpayne@68
|
6701 'is\n'
|
|
jpayne@68
|
6702 'specified, it is used for both.\n',
|
|
jpayne@68
|
6703 'nonlocal': 'The "nonlocal" statement\n'
|
|
jpayne@68
|
6704 '************************\n'
|
|
jpayne@68
|
6705 '\n'
|
|
jpayne@68
|
6706 ' nonlocal_stmt ::= "nonlocal" identifier ("," identifier)*\n'
|
|
jpayne@68
|
6707 '\n'
|
|
jpayne@68
|
6708 'The "nonlocal" statement causes the listed identifiers to refer '
|
|
jpayne@68
|
6709 'to\n'
|
|
jpayne@68
|
6710 'previously bound variables in the nearest enclosing scope '
|
|
jpayne@68
|
6711 'excluding\n'
|
|
jpayne@68
|
6712 'globals. This is important because the default behavior for '
|
|
jpayne@68
|
6713 'binding is\n'
|
|
jpayne@68
|
6714 'to search the local namespace first. The statement allows\n'
|
|
jpayne@68
|
6715 'encapsulated code to rebind variables outside of the local '
|
|
jpayne@68
|
6716 'scope\n'
|
|
jpayne@68
|
6717 'besides the global (module) scope.\n'
|
|
jpayne@68
|
6718 '\n'
|
|
jpayne@68
|
6719 'Names listed in a "nonlocal" statement, unlike those listed in '
|
|
jpayne@68
|
6720 'a\n'
|
|
jpayne@68
|
6721 '"global" statement, must refer to pre-existing bindings in an\n'
|
|
jpayne@68
|
6722 'enclosing scope (the scope in which a new binding should be '
|
|
jpayne@68
|
6723 'created\n'
|
|
jpayne@68
|
6724 'cannot be determined unambiguously).\n'
|
|
jpayne@68
|
6725 '\n'
|
|
jpayne@68
|
6726 'Names listed in a "nonlocal" statement must not collide with '
|
|
jpayne@68
|
6727 'pre-\n'
|
|
jpayne@68
|
6728 'existing bindings in the local scope.\n'
|
|
jpayne@68
|
6729 '\n'
|
|
jpayne@68
|
6730 'See also:\n'
|
|
jpayne@68
|
6731 '\n'
|
|
jpayne@68
|
6732 ' **PEP 3104** - Access to Names in Outer Scopes\n'
|
|
jpayne@68
|
6733 ' The specification for the "nonlocal" statement.\n',
|
|
jpayne@68
|
6734 'numbers': 'Numeric literals\n'
|
|
jpayne@68
|
6735 '****************\n'
|
|
jpayne@68
|
6736 '\n'
|
|
jpayne@68
|
6737 'There are three types of numeric literals: integers, floating '
|
|
jpayne@68
|
6738 'point\n'
|
|
jpayne@68
|
6739 'numbers, and imaginary numbers. There are no complex literals\n'
|
|
jpayne@68
|
6740 '(complex numbers can be formed by adding a real number and an\n'
|
|
jpayne@68
|
6741 'imaginary number).\n'
|
|
jpayne@68
|
6742 '\n'
|
|
jpayne@68
|
6743 'Note that numeric literals do not include a sign; a phrase like '
|
|
jpayne@68
|
6744 '"-1"\n'
|
|
jpayne@68
|
6745 'is actually an expression composed of the unary operator ‘"-"‘ '
|
|
jpayne@68
|
6746 'and the\n'
|
|
jpayne@68
|
6747 'literal "1".\n',
|
|
jpayne@68
|
6748 'numeric-types': 'Emulating numeric types\n'
|
|
jpayne@68
|
6749 '***********************\n'
|
|
jpayne@68
|
6750 '\n'
|
|
jpayne@68
|
6751 'The following methods can be defined to emulate numeric '
|
|
jpayne@68
|
6752 'objects.\n'
|
|
jpayne@68
|
6753 'Methods corresponding to operations that are not supported '
|
|
jpayne@68
|
6754 'by the\n'
|
|
jpayne@68
|
6755 'particular kind of number implemented (e.g., bitwise '
|
|
jpayne@68
|
6756 'operations for\n'
|
|
jpayne@68
|
6757 'non-integral numbers) should be left undefined.\n'
|
|
jpayne@68
|
6758 '\n'
|
|
jpayne@68
|
6759 'object.__add__(self, other)\n'
|
|
jpayne@68
|
6760 'object.__sub__(self, other)\n'
|
|
jpayne@68
|
6761 'object.__mul__(self, other)\n'
|
|
jpayne@68
|
6762 'object.__matmul__(self, other)\n'
|
|
jpayne@68
|
6763 'object.__truediv__(self, other)\n'
|
|
jpayne@68
|
6764 'object.__floordiv__(self, other)\n'
|
|
jpayne@68
|
6765 'object.__mod__(self, other)\n'
|
|
jpayne@68
|
6766 'object.__divmod__(self, other)\n'
|
|
jpayne@68
|
6767 'object.__pow__(self, other[, modulo])\n'
|
|
jpayne@68
|
6768 'object.__lshift__(self, other)\n'
|
|
jpayne@68
|
6769 'object.__rshift__(self, other)\n'
|
|
jpayne@68
|
6770 'object.__and__(self, other)\n'
|
|
jpayne@68
|
6771 'object.__xor__(self, other)\n'
|
|
jpayne@68
|
6772 'object.__or__(self, other)\n'
|
|
jpayne@68
|
6773 '\n'
|
|
jpayne@68
|
6774 ' These methods are called to implement the binary '
|
|
jpayne@68
|
6775 'arithmetic\n'
|
|
jpayne@68
|
6776 ' operations ("+", "-", "*", "@", "/", "//", "%", '
|
|
jpayne@68
|
6777 '"divmod()",\n'
|
|
jpayne@68
|
6778 ' "pow()", "**", "<<", ">>", "&", "^", "|"). For '
|
|
jpayne@68
|
6779 'instance, to\n'
|
|
jpayne@68
|
6780 ' evaluate the expression "x + y", where *x* is an '
|
|
jpayne@68
|
6781 'instance of a\n'
|
|
jpayne@68
|
6782 ' class that has an "__add__()" method, "x.__add__(y)" is '
|
|
jpayne@68
|
6783 'called.\n'
|
|
jpayne@68
|
6784 ' The "__divmod__()" method should be the equivalent to '
|
|
jpayne@68
|
6785 'using\n'
|
|
jpayne@68
|
6786 ' "__floordiv__()" and "__mod__()"; it should not be '
|
|
jpayne@68
|
6787 'related to\n'
|
|
jpayne@68
|
6788 ' "__truediv__()". Note that "__pow__()" should be '
|
|
jpayne@68
|
6789 'defined to accept\n'
|
|
jpayne@68
|
6790 ' an optional third argument if the ternary version of the '
|
|
jpayne@68
|
6791 'built-in\n'
|
|
jpayne@68
|
6792 ' "pow()" function is to be supported.\n'
|
|
jpayne@68
|
6793 '\n'
|
|
jpayne@68
|
6794 ' If one of those methods does not support the operation '
|
|
jpayne@68
|
6795 'with the\n'
|
|
jpayne@68
|
6796 ' supplied arguments, it should return "NotImplemented".\n'
|
|
jpayne@68
|
6797 '\n'
|
|
jpayne@68
|
6798 'object.__radd__(self, other)\n'
|
|
jpayne@68
|
6799 'object.__rsub__(self, other)\n'
|
|
jpayne@68
|
6800 'object.__rmul__(self, other)\n'
|
|
jpayne@68
|
6801 'object.__rmatmul__(self, other)\n'
|
|
jpayne@68
|
6802 'object.__rtruediv__(self, other)\n'
|
|
jpayne@68
|
6803 'object.__rfloordiv__(self, other)\n'
|
|
jpayne@68
|
6804 'object.__rmod__(self, other)\n'
|
|
jpayne@68
|
6805 'object.__rdivmod__(self, other)\n'
|
|
jpayne@68
|
6806 'object.__rpow__(self, other)\n'
|
|
jpayne@68
|
6807 'object.__rlshift__(self, other)\n'
|
|
jpayne@68
|
6808 'object.__rrshift__(self, other)\n'
|
|
jpayne@68
|
6809 'object.__rand__(self, other)\n'
|
|
jpayne@68
|
6810 'object.__rxor__(self, other)\n'
|
|
jpayne@68
|
6811 'object.__ror__(self, other)\n'
|
|
jpayne@68
|
6812 '\n'
|
|
jpayne@68
|
6813 ' These methods are called to implement the binary '
|
|
jpayne@68
|
6814 'arithmetic\n'
|
|
jpayne@68
|
6815 ' operations ("+", "-", "*", "@", "/", "//", "%", '
|
|
jpayne@68
|
6816 '"divmod()",\n'
|
|
jpayne@68
|
6817 ' "pow()", "**", "<<", ">>", "&", "^", "|") with reflected '
|
|
jpayne@68
|
6818 '(swapped)\n'
|
|
jpayne@68
|
6819 ' operands. These functions are only called if the left '
|
|
jpayne@68
|
6820 'operand does\n'
|
|
jpayne@68
|
6821 ' not support the corresponding operation [3] and the '
|
|
jpayne@68
|
6822 'operands are of\n'
|
|
jpayne@68
|
6823 ' different types. [4] For instance, to evaluate the '
|
|
jpayne@68
|
6824 'expression "x -\n'
|
|
jpayne@68
|
6825 ' y", where *y* is an instance of a class that has an '
|
|
jpayne@68
|
6826 '"__rsub__()"\n'
|
|
jpayne@68
|
6827 ' method, "y.__rsub__(x)" is called if "x.__sub__(y)" '
|
|
jpayne@68
|
6828 'returns\n'
|
|
jpayne@68
|
6829 ' *NotImplemented*.\n'
|
|
jpayne@68
|
6830 '\n'
|
|
jpayne@68
|
6831 ' Note that ternary "pow()" will not try calling '
|
|
jpayne@68
|
6832 '"__rpow__()" (the\n'
|
|
jpayne@68
|
6833 ' coercion rules would become too complicated).\n'
|
|
jpayne@68
|
6834 '\n'
|
|
jpayne@68
|
6835 ' Note: If the right operand’s type is a subclass of the '
|
|
jpayne@68
|
6836 'left\n'
|
|
jpayne@68
|
6837 ' operand’s type and that subclass provides the '
|
|
jpayne@68
|
6838 'reflected method\n'
|
|
jpayne@68
|
6839 ' for the operation, this method will be called before '
|
|
jpayne@68
|
6840 'the left\n'
|
|
jpayne@68
|
6841 ' operand’s non-reflected method. This behavior allows '
|
|
jpayne@68
|
6842 'subclasses\n'
|
|
jpayne@68
|
6843 ' to override their ancestors’ operations.\n'
|
|
jpayne@68
|
6844 '\n'
|
|
jpayne@68
|
6845 'object.__iadd__(self, other)\n'
|
|
jpayne@68
|
6846 'object.__isub__(self, other)\n'
|
|
jpayne@68
|
6847 'object.__imul__(self, other)\n'
|
|
jpayne@68
|
6848 'object.__imatmul__(self, other)\n'
|
|
jpayne@68
|
6849 'object.__itruediv__(self, other)\n'
|
|
jpayne@68
|
6850 'object.__ifloordiv__(self, other)\n'
|
|
jpayne@68
|
6851 'object.__imod__(self, other)\n'
|
|
jpayne@68
|
6852 'object.__ipow__(self, other[, modulo])\n'
|
|
jpayne@68
|
6853 'object.__ilshift__(self, other)\n'
|
|
jpayne@68
|
6854 'object.__irshift__(self, other)\n'
|
|
jpayne@68
|
6855 'object.__iand__(self, other)\n'
|
|
jpayne@68
|
6856 'object.__ixor__(self, other)\n'
|
|
jpayne@68
|
6857 'object.__ior__(self, other)\n'
|
|
jpayne@68
|
6858 '\n'
|
|
jpayne@68
|
6859 ' These methods are called to implement the augmented '
|
|
jpayne@68
|
6860 'arithmetic\n'
|
|
jpayne@68
|
6861 ' assignments ("+=", "-=", "*=", "@=", "/=", "//=", "%=", '
|
|
jpayne@68
|
6862 '"**=",\n'
|
|
jpayne@68
|
6863 ' "<<=", ">>=", "&=", "^=", "|="). These methods should '
|
|
jpayne@68
|
6864 'attempt to\n'
|
|
jpayne@68
|
6865 ' do the operation in-place (modifying *self*) and return '
|
|
jpayne@68
|
6866 'the result\n'
|
|
jpayne@68
|
6867 ' (which could be, but does not have to be, *self*). If a '
|
|
jpayne@68
|
6868 'specific\n'
|
|
jpayne@68
|
6869 ' method is not defined, the augmented assignment falls '
|
|
jpayne@68
|
6870 'back to the\n'
|
|
jpayne@68
|
6871 ' normal methods. For instance, if *x* is an instance of '
|
|
jpayne@68
|
6872 'a class\n'
|
|
jpayne@68
|
6873 ' with an "__iadd__()" method, "x += y" is equivalent to '
|
|
jpayne@68
|
6874 '"x =\n'
|
|
jpayne@68
|
6875 ' x.__iadd__(y)" . Otherwise, "x.__add__(y)" and '
|
|
jpayne@68
|
6876 '"y.__radd__(x)" are\n'
|
|
jpayne@68
|
6877 ' considered, as with the evaluation of "x + y". In '
|
|
jpayne@68
|
6878 'certain\n'
|
|
jpayne@68
|
6879 ' situations, augmented assignment can result in '
|
|
jpayne@68
|
6880 'unexpected errors\n'
|
|
jpayne@68
|
6881 ' (see Why does a_tuple[i] += [‘item’] raise an exception '
|
|
jpayne@68
|
6882 'when the\n'
|
|
jpayne@68
|
6883 ' addition works?), but this behavior is in fact part of '
|
|
jpayne@68
|
6884 'the data\n'
|
|
jpayne@68
|
6885 ' model.\n'
|
|
jpayne@68
|
6886 '\n'
|
|
jpayne@68
|
6887 'object.__neg__(self)\n'
|
|
jpayne@68
|
6888 'object.__pos__(self)\n'
|
|
jpayne@68
|
6889 'object.__abs__(self)\n'
|
|
jpayne@68
|
6890 'object.__invert__(self)\n'
|
|
jpayne@68
|
6891 '\n'
|
|
jpayne@68
|
6892 ' Called to implement the unary arithmetic operations '
|
|
jpayne@68
|
6893 '("-", "+",\n'
|
|
jpayne@68
|
6894 ' "abs()" and "~").\n'
|
|
jpayne@68
|
6895 '\n'
|
|
jpayne@68
|
6896 'object.__complex__(self)\n'
|
|
jpayne@68
|
6897 'object.__int__(self)\n'
|
|
jpayne@68
|
6898 'object.__float__(self)\n'
|
|
jpayne@68
|
6899 '\n'
|
|
jpayne@68
|
6900 ' Called to implement the built-in functions "complex()", '
|
|
jpayne@68
|
6901 '"int()" and\n'
|
|
jpayne@68
|
6902 ' "float()". Should return a value of the appropriate '
|
|
jpayne@68
|
6903 'type.\n'
|
|
jpayne@68
|
6904 '\n'
|
|
jpayne@68
|
6905 'object.__index__(self)\n'
|
|
jpayne@68
|
6906 '\n'
|
|
jpayne@68
|
6907 ' Called to implement "operator.index()", and whenever '
|
|
jpayne@68
|
6908 'Python needs\n'
|
|
jpayne@68
|
6909 ' to losslessly convert the numeric object to an integer '
|
|
jpayne@68
|
6910 'object (such\n'
|
|
jpayne@68
|
6911 ' as in slicing, or in the built-in "bin()", "hex()" and '
|
|
jpayne@68
|
6912 '"oct()"\n'
|
|
jpayne@68
|
6913 ' functions). Presence of this method indicates that the '
|
|
jpayne@68
|
6914 'numeric\n'
|
|
jpayne@68
|
6915 ' object is an integer type. Must return an integer.\n'
|
|
jpayne@68
|
6916 '\n'
|
|
jpayne@68
|
6917 ' If "__int__()", "__float__()" and "__complex__()" are '
|
|
jpayne@68
|
6918 'not defined\n'
|
|
jpayne@68
|
6919 ' then corresponding built-in functions "int()", "float()" '
|
|
jpayne@68
|
6920 'and\n'
|
|
jpayne@68
|
6921 ' "complex()" fall back to "__index__()".\n'
|
|
jpayne@68
|
6922 '\n'
|
|
jpayne@68
|
6923 'object.__round__(self[, ndigits])\n'
|
|
jpayne@68
|
6924 'object.__trunc__(self)\n'
|
|
jpayne@68
|
6925 'object.__floor__(self)\n'
|
|
jpayne@68
|
6926 'object.__ceil__(self)\n'
|
|
jpayne@68
|
6927 '\n'
|
|
jpayne@68
|
6928 ' Called to implement the built-in function "round()" and '
|
|
jpayne@68
|
6929 '"math"\n'
|
|
jpayne@68
|
6930 ' functions "trunc()", "floor()" and "ceil()". Unless '
|
|
jpayne@68
|
6931 '*ndigits* is\n'
|
|
jpayne@68
|
6932 ' passed to "__round__()" all these methods should return '
|
|
jpayne@68
|
6933 'the value\n'
|
|
jpayne@68
|
6934 ' of the object truncated to an "Integral" (typically an '
|
|
jpayne@68
|
6935 '"int").\n'
|
|
jpayne@68
|
6936 '\n'
|
|
jpayne@68
|
6937 ' If "__int__()" is not defined then the built-in function '
|
|
jpayne@68
|
6938 '"int()"\n'
|
|
jpayne@68
|
6939 ' falls back to "__trunc__()".\n',
|
|
jpayne@68
|
6940 'objects': 'Objects, values and types\n'
|
|
jpayne@68
|
6941 '*************************\n'
|
|
jpayne@68
|
6942 '\n'
|
|
jpayne@68
|
6943 '*Objects* are Python’s abstraction for data. All data in a '
|
|
jpayne@68
|
6944 'Python\n'
|
|
jpayne@68
|
6945 'program is represented by objects or by relations between '
|
|
jpayne@68
|
6946 'objects. (In\n'
|
|
jpayne@68
|
6947 'a sense, and in conformance to Von Neumann’s model of a “stored\n'
|
|
jpayne@68
|
6948 'program computer,” code is also represented by objects.)\n'
|
|
jpayne@68
|
6949 '\n'
|
|
jpayne@68
|
6950 'Every object has an identity, a type and a value. An object’s\n'
|
|
jpayne@68
|
6951 '*identity* never changes once it has been created; you may think '
|
|
jpayne@68
|
6952 'of it\n'
|
|
jpayne@68
|
6953 'as the object’s address in memory. The ‘"is"’ operator compares '
|
|
jpayne@68
|
6954 'the\n'
|
|
jpayne@68
|
6955 'identity of two objects; the "id()" function returns an integer\n'
|
|
jpayne@68
|
6956 'representing its identity.\n'
|
|
jpayne@68
|
6957 '\n'
|
|
jpayne@68
|
6958 '**CPython implementation detail:** For CPython, "id(x)" is the '
|
|
jpayne@68
|
6959 'memory\n'
|
|
jpayne@68
|
6960 'address where "x" is stored.\n'
|
|
jpayne@68
|
6961 '\n'
|
|
jpayne@68
|
6962 'An object’s type determines the operations that the object '
|
|
jpayne@68
|
6963 'supports\n'
|
|
jpayne@68
|
6964 '(e.g., “does it have a length?”) and also defines the possible '
|
|
jpayne@68
|
6965 'values\n'
|
|
jpayne@68
|
6966 'for objects of that type. The "type()" function returns an '
|
|
jpayne@68
|
6967 'object’s\n'
|
|
jpayne@68
|
6968 'type (which is an object itself). Like its identity, an '
|
|
jpayne@68
|
6969 'object’s\n'
|
|
jpayne@68
|
6970 '*type* is also unchangeable. [1]\n'
|
|
jpayne@68
|
6971 '\n'
|
|
jpayne@68
|
6972 'The *value* of some objects can change. Objects whose value can\n'
|
|
jpayne@68
|
6973 'change are said to be *mutable*; objects whose value is '
|
|
jpayne@68
|
6974 'unchangeable\n'
|
|
jpayne@68
|
6975 'once they are created are called *immutable*. (The value of an\n'
|
|
jpayne@68
|
6976 'immutable container object that contains a reference to a '
|
|
jpayne@68
|
6977 'mutable\n'
|
|
jpayne@68
|
6978 'object can change when the latter’s value is changed; however '
|
|
jpayne@68
|
6979 'the\n'
|
|
jpayne@68
|
6980 'container is still considered immutable, because the collection '
|
|
jpayne@68
|
6981 'of\n'
|
|
jpayne@68
|
6982 'objects it contains cannot be changed. So, immutability is not\n'
|
|
jpayne@68
|
6983 'strictly the same as having an unchangeable value, it is more '
|
|
jpayne@68
|
6984 'subtle.)\n'
|
|
jpayne@68
|
6985 'An object’s mutability is determined by its type; for instance,\n'
|
|
jpayne@68
|
6986 'numbers, strings and tuples are immutable, while dictionaries '
|
|
jpayne@68
|
6987 'and\n'
|
|
jpayne@68
|
6988 'lists are mutable.\n'
|
|
jpayne@68
|
6989 '\n'
|
|
jpayne@68
|
6990 'Objects are never explicitly destroyed; however, when they '
|
|
jpayne@68
|
6991 'become\n'
|
|
jpayne@68
|
6992 'unreachable they may be garbage-collected. An implementation is\n'
|
|
jpayne@68
|
6993 'allowed to postpone garbage collection or omit it altogether — it '
|
|
jpayne@68
|
6994 'is a\n'
|
|
jpayne@68
|
6995 'matter of implementation quality how garbage collection is\n'
|
|
jpayne@68
|
6996 'implemented, as long as no objects are collected that are still\n'
|
|
jpayne@68
|
6997 'reachable.\n'
|
|
jpayne@68
|
6998 '\n'
|
|
jpayne@68
|
6999 '**CPython implementation detail:** CPython currently uses a '
|
|
jpayne@68
|
7000 'reference-\n'
|
|
jpayne@68
|
7001 'counting scheme with (optional) delayed detection of cyclically '
|
|
jpayne@68
|
7002 'linked\n'
|
|
jpayne@68
|
7003 'garbage, which collects most objects as soon as they become\n'
|
|
jpayne@68
|
7004 'unreachable, but is not guaranteed to collect garbage containing\n'
|
|
jpayne@68
|
7005 'circular references. See the documentation of the "gc" module '
|
|
jpayne@68
|
7006 'for\n'
|
|
jpayne@68
|
7007 'information on controlling the collection of cyclic garbage. '
|
|
jpayne@68
|
7008 'Other\n'
|
|
jpayne@68
|
7009 'implementations act differently and CPython may change. Do not '
|
|
jpayne@68
|
7010 'depend\n'
|
|
jpayne@68
|
7011 'on immediate finalization of objects when they become unreachable '
|
|
jpayne@68
|
7012 '(so\n'
|
|
jpayne@68
|
7013 'you should always close files explicitly).\n'
|
|
jpayne@68
|
7014 '\n'
|
|
jpayne@68
|
7015 'Note that the use of the implementation’s tracing or debugging\n'
|
|
jpayne@68
|
7016 'facilities may keep objects alive that would normally be '
|
|
jpayne@68
|
7017 'collectable.\n'
|
|
jpayne@68
|
7018 'Also note that catching an exception with a ‘"try"…"except"’ '
|
|
jpayne@68
|
7019 'statement\n'
|
|
jpayne@68
|
7020 'may keep objects alive.\n'
|
|
jpayne@68
|
7021 '\n'
|
|
jpayne@68
|
7022 'Some objects contain references to “external” resources such as '
|
|
jpayne@68
|
7023 'open\n'
|
|
jpayne@68
|
7024 'files or windows. It is understood that these resources are '
|
|
jpayne@68
|
7025 'freed\n'
|
|
jpayne@68
|
7026 'when the object is garbage-collected, but since garbage '
|
|
jpayne@68
|
7027 'collection is\n'
|
|
jpayne@68
|
7028 'not guaranteed to happen, such objects also provide an explicit '
|
|
jpayne@68
|
7029 'way to\n'
|
|
jpayne@68
|
7030 'release the external resource, usually a "close()" method. '
|
|
jpayne@68
|
7031 'Programs\n'
|
|
jpayne@68
|
7032 'are strongly recommended to explicitly close such objects. The\n'
|
|
jpayne@68
|
7033 '‘"try"…"finally"’ statement and the ‘"with"’ statement provide\n'
|
|
jpayne@68
|
7034 'convenient ways to do this.\n'
|
|
jpayne@68
|
7035 '\n'
|
|
jpayne@68
|
7036 'Some objects contain references to other objects; these are '
|
|
jpayne@68
|
7037 'called\n'
|
|
jpayne@68
|
7038 '*containers*. Examples of containers are tuples, lists and\n'
|
|
jpayne@68
|
7039 'dictionaries. The references are part of a container’s value. '
|
|
jpayne@68
|
7040 'In\n'
|
|
jpayne@68
|
7041 'most cases, when we talk about the value of a container, we imply '
|
|
jpayne@68
|
7042 'the\n'
|
|
jpayne@68
|
7043 'values, not the identities of the contained objects; however, '
|
|
jpayne@68
|
7044 'when we\n'
|
|
jpayne@68
|
7045 'talk about the mutability of a container, only the identities of '
|
|
jpayne@68
|
7046 'the\n'
|
|
jpayne@68
|
7047 'immediately contained objects are implied. So, if an immutable\n'
|
|
jpayne@68
|
7048 'container (like a tuple) contains a reference to a mutable '
|
|
jpayne@68
|
7049 'object, its\n'
|
|
jpayne@68
|
7050 'value changes if that mutable object is changed.\n'
|
|
jpayne@68
|
7051 '\n'
|
|
jpayne@68
|
7052 'Types affect almost all aspects of object behavior. Even the\n'
|
|
jpayne@68
|
7053 'importance of object identity is affected in some sense: for '
|
|
jpayne@68
|
7054 'immutable\n'
|
|
jpayne@68
|
7055 'types, operations that compute new values may actually return a\n'
|
|
jpayne@68
|
7056 'reference to any existing object with the same type and value, '
|
|
jpayne@68
|
7057 'while\n'
|
|
jpayne@68
|
7058 'for mutable objects this is not allowed. E.g., after "a = 1; b = '
|
|
jpayne@68
|
7059 '1",\n'
|
|
jpayne@68
|
7060 '"a" and "b" may or may not refer to the same object with the '
|
|
jpayne@68
|
7061 'value\n'
|
|
jpayne@68
|
7062 'one, depending on the implementation, but after "c = []; d = []", '
|
|
jpayne@68
|
7063 '"c"\n'
|
|
jpayne@68
|
7064 'and "d" are guaranteed to refer to two different, unique, newly\n'
|
|
jpayne@68
|
7065 'created empty lists. (Note that "c = d = []" assigns the same '
|
|
jpayne@68
|
7066 'object\n'
|
|
jpayne@68
|
7067 'to both "c" and "d".)\n',
|
|
jpayne@68
|
7068 'operator-summary': 'Operator precedence\n'
|
|
jpayne@68
|
7069 '*******************\n'
|
|
jpayne@68
|
7070 '\n'
|
|
jpayne@68
|
7071 'The following table summarizes the operator precedence '
|
|
jpayne@68
|
7072 'in Python, from\n'
|
|
jpayne@68
|
7073 'lowest precedence (least binding) to highest precedence '
|
|
jpayne@68
|
7074 '(most\n'
|
|
jpayne@68
|
7075 'binding). Operators in the same box have the same '
|
|
jpayne@68
|
7076 'precedence. Unless\n'
|
|
jpayne@68
|
7077 'the syntax is explicitly given, operators are binary. '
|
|
jpayne@68
|
7078 'Operators in\n'
|
|
jpayne@68
|
7079 'the same box group left to right (except for '
|
|
jpayne@68
|
7080 'exponentiation, which\n'
|
|
jpayne@68
|
7081 'groups from right to left).\n'
|
|
jpayne@68
|
7082 '\n'
|
|
jpayne@68
|
7083 'Note that comparisons, membership tests, and identity '
|
|
jpayne@68
|
7084 'tests, all have\n'
|
|
jpayne@68
|
7085 'the same precedence and have a left-to-right chaining '
|
|
jpayne@68
|
7086 'feature as\n'
|
|
jpayne@68
|
7087 'described in the Comparisons section.\n'
|
|
jpayne@68
|
7088 '\n'
|
|
jpayne@68
|
7089 '+-------------------------------------------------+---------------------------------------+\n'
|
|
jpayne@68
|
7090 '| Operator | '
|
|
jpayne@68
|
7091 'Description |\n'
|
|
jpayne@68
|
7092 '|=================================================|=======================================|\n'
|
|
jpayne@68
|
7093 '| ":=" | '
|
|
jpayne@68
|
7094 'Assignment expression |\n'
|
|
jpayne@68
|
7095 '+-------------------------------------------------+---------------------------------------+\n'
|
|
jpayne@68
|
7096 '| "lambda" | '
|
|
jpayne@68
|
7097 'Lambda expression |\n'
|
|
jpayne@68
|
7098 '+-------------------------------------------------+---------------------------------------+\n'
|
|
jpayne@68
|
7099 '| "if" – "else" | '
|
|
jpayne@68
|
7100 'Conditional expression |\n'
|
|
jpayne@68
|
7101 '+-------------------------------------------------+---------------------------------------+\n'
|
|
jpayne@68
|
7102 '| "or" | '
|
|
jpayne@68
|
7103 'Boolean OR |\n'
|
|
jpayne@68
|
7104 '+-------------------------------------------------+---------------------------------------+\n'
|
|
jpayne@68
|
7105 '| "and" | '
|
|
jpayne@68
|
7106 'Boolean AND |\n'
|
|
jpayne@68
|
7107 '+-------------------------------------------------+---------------------------------------+\n'
|
|
jpayne@68
|
7108 '| "not" "x" | '
|
|
jpayne@68
|
7109 'Boolean NOT |\n'
|
|
jpayne@68
|
7110 '+-------------------------------------------------+---------------------------------------+\n'
|
|
jpayne@68
|
7111 '| "in", "not in", "is", "is not", "<", "<=", ">", | '
|
|
jpayne@68
|
7112 'Comparisons, including membership |\n'
|
|
jpayne@68
|
7113 '| ">=", "!=", "==" | '
|
|
jpayne@68
|
7114 'tests and identity tests |\n'
|
|
jpayne@68
|
7115 '+-------------------------------------------------+---------------------------------------+\n'
|
|
jpayne@68
|
7116 '| "|" | '
|
|
jpayne@68
|
7117 'Bitwise OR |\n'
|
|
jpayne@68
|
7118 '+-------------------------------------------------+---------------------------------------+\n'
|
|
jpayne@68
|
7119 '| "^" | '
|
|
jpayne@68
|
7120 'Bitwise XOR |\n'
|
|
jpayne@68
|
7121 '+-------------------------------------------------+---------------------------------------+\n'
|
|
jpayne@68
|
7122 '| "&" | '
|
|
jpayne@68
|
7123 'Bitwise AND |\n'
|
|
jpayne@68
|
7124 '+-------------------------------------------------+---------------------------------------+\n'
|
|
jpayne@68
|
7125 '| "<<", ">>" | '
|
|
jpayne@68
|
7126 'Shifts |\n'
|
|
jpayne@68
|
7127 '+-------------------------------------------------+---------------------------------------+\n'
|
|
jpayne@68
|
7128 '| "+", "-" | '
|
|
jpayne@68
|
7129 'Addition and subtraction |\n'
|
|
jpayne@68
|
7130 '+-------------------------------------------------+---------------------------------------+\n'
|
|
jpayne@68
|
7131 '| "*", "@", "/", "//", "%" | '
|
|
jpayne@68
|
7132 'Multiplication, matrix |\n'
|
|
jpayne@68
|
7133 '| | '
|
|
jpayne@68
|
7134 'multiplication, division, floor |\n'
|
|
jpayne@68
|
7135 '| | '
|
|
jpayne@68
|
7136 'division, remainder [5] |\n'
|
|
jpayne@68
|
7137 '+-------------------------------------------------+---------------------------------------+\n'
|
|
jpayne@68
|
7138 '| "+x", "-x", "~x" | '
|
|
jpayne@68
|
7139 'Positive, negative, bitwise NOT |\n'
|
|
jpayne@68
|
7140 '+-------------------------------------------------+---------------------------------------+\n'
|
|
jpayne@68
|
7141 '| "**" | '
|
|
jpayne@68
|
7142 'Exponentiation [6] |\n'
|
|
jpayne@68
|
7143 '+-------------------------------------------------+---------------------------------------+\n'
|
|
jpayne@68
|
7144 '| "await" "x" | '
|
|
jpayne@68
|
7145 'Await expression |\n'
|
|
jpayne@68
|
7146 '+-------------------------------------------------+---------------------------------------+\n'
|
|
jpayne@68
|
7147 '| "x[index]", "x[index:index]", | '
|
|
jpayne@68
|
7148 'Subscription, slicing, call, |\n'
|
|
jpayne@68
|
7149 '| "x(arguments...)", "x.attribute" | '
|
|
jpayne@68
|
7150 'attribute reference |\n'
|
|
jpayne@68
|
7151 '+-------------------------------------------------+---------------------------------------+\n'
|
|
jpayne@68
|
7152 '| "(expressions...)", "[expressions...]", "{key: | '
|
|
jpayne@68
|
7153 'Binding or parenthesized expression, |\n'
|
|
jpayne@68
|
7154 '| value...}", "{expressions...}" | list '
|
|
jpayne@68
|
7155 'display, dictionary display, set |\n'
|
|
jpayne@68
|
7156 '| | '
|
|
jpayne@68
|
7157 'display |\n'
|
|
jpayne@68
|
7158 '+-------------------------------------------------+---------------------------------------+\n'
|
|
jpayne@68
|
7159 '\n'
|
|
jpayne@68
|
7160 '-[ Footnotes ]-\n'
|
|
jpayne@68
|
7161 '\n'
|
|
jpayne@68
|
7162 '[1] While "abs(x%y) < abs(y)" is true mathematically, '
|
|
jpayne@68
|
7163 'for floats\n'
|
|
jpayne@68
|
7164 ' it may not be true numerically due to roundoff. For '
|
|
jpayne@68
|
7165 'example, and\n'
|
|
jpayne@68
|
7166 ' assuming a platform on which a Python float is an '
|
|
jpayne@68
|
7167 'IEEE 754 double-\n'
|
|
jpayne@68
|
7168 ' precision number, in order that "-1e-100 % 1e100" '
|
|
jpayne@68
|
7169 'have the same\n'
|
|
jpayne@68
|
7170 ' sign as "1e100", the computed result is "-1e-100 + '
|
|
jpayne@68
|
7171 '1e100", which\n'
|
|
jpayne@68
|
7172 ' is numerically exactly equal to "1e100". The '
|
|
jpayne@68
|
7173 'function\n'
|
|
jpayne@68
|
7174 ' "math.fmod()" returns a result whose sign matches '
|
|
jpayne@68
|
7175 'the sign of the\n'
|
|
jpayne@68
|
7176 ' first argument instead, and so returns "-1e-100" in '
|
|
jpayne@68
|
7177 'this case.\n'
|
|
jpayne@68
|
7178 ' Which approach is more appropriate depends on the '
|
|
jpayne@68
|
7179 'application.\n'
|
|
jpayne@68
|
7180 '\n'
|
|
jpayne@68
|
7181 '[2] If x is very close to an exact integer multiple of '
|
|
jpayne@68
|
7182 'y, it’s\n'
|
|
jpayne@68
|
7183 ' possible for "x//y" to be one larger than '
|
|
jpayne@68
|
7184 '"(x-x%y)//y" due to\n'
|
|
jpayne@68
|
7185 ' rounding. In such cases, Python returns the latter '
|
|
jpayne@68
|
7186 'result, in\n'
|
|
jpayne@68
|
7187 ' order to preserve that "divmod(x,y)[0] * y + x % y" '
|
|
jpayne@68
|
7188 'be very close\n'
|
|
jpayne@68
|
7189 ' to "x".\n'
|
|
jpayne@68
|
7190 '\n'
|
|
jpayne@68
|
7191 '[3] The Unicode standard distinguishes between *code '
|
|
jpayne@68
|
7192 'points* (e.g.\n'
|
|
jpayne@68
|
7193 ' U+0041) and *abstract characters* (e.g. “LATIN '
|
|
jpayne@68
|
7194 'CAPITAL LETTER A”).\n'
|
|
jpayne@68
|
7195 ' While most abstract characters in Unicode are only '
|
|
jpayne@68
|
7196 'represented\n'
|
|
jpayne@68
|
7197 ' using one code point, there is a number of abstract '
|
|
jpayne@68
|
7198 'characters\n'
|
|
jpayne@68
|
7199 ' that can in addition be represented using a sequence '
|
|
jpayne@68
|
7200 'of more than\n'
|
|
jpayne@68
|
7201 ' one code point. For example, the abstract character '
|
|
jpayne@68
|
7202 '“LATIN\n'
|
|
jpayne@68
|
7203 ' CAPITAL LETTER C WITH CEDILLA” can be represented as '
|
|
jpayne@68
|
7204 'a single\n'
|
|
jpayne@68
|
7205 ' *precomposed character* at code position U+00C7, or '
|
|
jpayne@68
|
7206 'as a sequence\n'
|
|
jpayne@68
|
7207 ' of a *base character* at code position U+0043 (LATIN '
|
|
jpayne@68
|
7208 'CAPITAL\n'
|
|
jpayne@68
|
7209 ' LETTER C), followed by a *combining character* at '
|
|
jpayne@68
|
7210 'code position\n'
|
|
jpayne@68
|
7211 ' U+0327 (COMBINING CEDILLA).\n'
|
|
jpayne@68
|
7212 '\n'
|
|
jpayne@68
|
7213 ' The comparison operators on strings compare at the '
|
|
jpayne@68
|
7214 'level of\n'
|
|
jpayne@68
|
7215 ' Unicode code points. This may be counter-intuitive '
|
|
jpayne@68
|
7216 'to humans. For\n'
|
|
jpayne@68
|
7217 ' example, ""\\u00C7" == "\\u0043\\u0327"" is "False", '
|
|
jpayne@68
|
7218 'even though both\n'
|
|
jpayne@68
|
7219 ' strings represent the same abstract character “LATIN '
|
|
jpayne@68
|
7220 'CAPITAL\n'
|
|
jpayne@68
|
7221 ' LETTER C WITH CEDILLA”.\n'
|
|
jpayne@68
|
7222 '\n'
|
|
jpayne@68
|
7223 ' To compare strings at the level of abstract '
|
|
jpayne@68
|
7224 'characters (that is,\n'
|
|
jpayne@68
|
7225 ' in a way intuitive to humans), use '
|
|
jpayne@68
|
7226 '"unicodedata.normalize()".\n'
|
|
jpayne@68
|
7227 '\n'
|
|
jpayne@68
|
7228 '[4] Due to automatic garbage-collection, free lists, and '
|
|
jpayne@68
|
7229 'the\n'
|
|
jpayne@68
|
7230 ' dynamic nature of descriptors, you may notice '
|
|
jpayne@68
|
7231 'seemingly unusual\n'
|
|
jpayne@68
|
7232 ' behaviour in certain uses of the "is" operator, like '
|
|
jpayne@68
|
7233 'those\n'
|
|
jpayne@68
|
7234 ' involving comparisons between instance methods, or '
|
|
jpayne@68
|
7235 'constants.\n'
|
|
jpayne@68
|
7236 ' Check their documentation for more info.\n'
|
|
jpayne@68
|
7237 '\n'
|
|
jpayne@68
|
7238 '[5] The "%" operator is also used for string formatting; '
|
|
jpayne@68
|
7239 'the same\n'
|
|
jpayne@68
|
7240 ' precedence applies.\n'
|
|
jpayne@68
|
7241 '\n'
|
|
jpayne@68
|
7242 '[6] The power operator "**" binds less tightly than an '
|
|
jpayne@68
|
7243 'arithmetic\n'
|
|
jpayne@68
|
7244 ' or bitwise unary operator on its right, that is, '
|
|
jpayne@68
|
7245 '"2**-1" is "0.5".\n',
|
|
jpayne@68
|
7246 'pass': 'The "pass" statement\n'
|
|
jpayne@68
|
7247 '********************\n'
|
|
jpayne@68
|
7248 '\n'
|
|
jpayne@68
|
7249 ' pass_stmt ::= "pass"\n'
|
|
jpayne@68
|
7250 '\n'
|
|
jpayne@68
|
7251 '"pass" is a null operation — when it is executed, nothing happens. '
|
|
jpayne@68
|
7252 'It\n'
|
|
jpayne@68
|
7253 'is useful as a placeholder when a statement is required '
|
|
jpayne@68
|
7254 'syntactically,\n'
|
|
jpayne@68
|
7255 'but no code needs to be executed, for example:\n'
|
|
jpayne@68
|
7256 '\n'
|
|
jpayne@68
|
7257 ' def f(arg): pass # a function that does nothing (yet)\n'
|
|
jpayne@68
|
7258 '\n'
|
|
jpayne@68
|
7259 ' class C: pass # a class with no methods (yet)\n',
|
|
jpayne@68
|
7260 'power': 'The power operator\n'
|
|
jpayne@68
|
7261 '******************\n'
|
|
jpayne@68
|
7262 '\n'
|
|
jpayne@68
|
7263 'The power operator binds more tightly than unary operators on its\n'
|
|
jpayne@68
|
7264 'left; it binds less tightly than unary operators on its right. '
|
|
jpayne@68
|
7265 'The\n'
|
|
jpayne@68
|
7266 'syntax is:\n'
|
|
jpayne@68
|
7267 '\n'
|
|
jpayne@68
|
7268 ' power ::= (await_expr | primary) ["**" u_expr]\n'
|
|
jpayne@68
|
7269 '\n'
|
|
jpayne@68
|
7270 'Thus, in an unparenthesized sequence of power and unary operators, '
|
|
jpayne@68
|
7271 'the\n'
|
|
jpayne@68
|
7272 'operators are evaluated from right to left (this does not '
|
|
jpayne@68
|
7273 'constrain\n'
|
|
jpayne@68
|
7274 'the evaluation order for the operands): "-1**2" results in "-1".\n'
|
|
jpayne@68
|
7275 '\n'
|
|
jpayne@68
|
7276 'The power operator has the same semantics as the built-in "pow()"\n'
|
|
jpayne@68
|
7277 'function, when called with two arguments: it yields its left '
|
|
jpayne@68
|
7278 'argument\n'
|
|
jpayne@68
|
7279 'raised to the power of its right argument. The numeric arguments '
|
|
jpayne@68
|
7280 'are\n'
|
|
jpayne@68
|
7281 'first converted to a common type, and the result is of that type.\n'
|
|
jpayne@68
|
7282 '\n'
|
|
jpayne@68
|
7283 'For int operands, the result has the same type as the operands '
|
|
jpayne@68
|
7284 'unless\n'
|
|
jpayne@68
|
7285 'the second argument is negative; in that case, all arguments are\n'
|
|
jpayne@68
|
7286 'converted to float and a float result is delivered. For example,\n'
|
|
jpayne@68
|
7287 '"10**2" returns "100", but "10**-2" returns "0.01".\n'
|
|
jpayne@68
|
7288 '\n'
|
|
jpayne@68
|
7289 'Raising "0.0" to a negative power results in a '
|
|
jpayne@68
|
7290 '"ZeroDivisionError".\n'
|
|
jpayne@68
|
7291 'Raising a negative number to a fractional power results in a '
|
|
jpayne@68
|
7292 '"complex"\n'
|
|
jpayne@68
|
7293 'number. (In earlier versions it raised a "ValueError".)\n',
|
|
jpayne@68
|
7294 'raise': 'The "raise" statement\n'
|
|
jpayne@68
|
7295 '*********************\n'
|
|
jpayne@68
|
7296 '\n'
|
|
jpayne@68
|
7297 ' raise_stmt ::= "raise" [expression ["from" expression]]\n'
|
|
jpayne@68
|
7298 '\n'
|
|
jpayne@68
|
7299 'If no expressions are present, "raise" re-raises the last '
|
|
jpayne@68
|
7300 'exception\n'
|
|
jpayne@68
|
7301 'that was active in the current scope. If no exception is active '
|
|
jpayne@68
|
7302 'in\n'
|
|
jpayne@68
|
7303 'the current scope, a "RuntimeError" exception is raised indicating\n'
|
|
jpayne@68
|
7304 'that this is an error.\n'
|
|
jpayne@68
|
7305 '\n'
|
|
jpayne@68
|
7306 'Otherwise, "raise" evaluates the first expression as the exception\n'
|
|
jpayne@68
|
7307 'object. It must be either a subclass or an instance of\n'
|
|
jpayne@68
|
7308 '"BaseException". If it is a class, the exception instance will be\n'
|
|
jpayne@68
|
7309 'obtained when needed by instantiating the class with no arguments.\n'
|
|
jpayne@68
|
7310 '\n'
|
|
jpayne@68
|
7311 'The *type* of the exception is the exception instance’s class, the\n'
|
|
jpayne@68
|
7312 '*value* is the instance itself.\n'
|
|
jpayne@68
|
7313 '\n'
|
|
jpayne@68
|
7314 'A traceback object is normally created automatically when an '
|
|
jpayne@68
|
7315 'exception\n'
|
|
jpayne@68
|
7316 'is raised and attached to it as the "__traceback__" attribute, '
|
|
jpayne@68
|
7317 'which\n'
|
|
jpayne@68
|
7318 'is writable. You can create an exception and set your own traceback '
|
|
jpayne@68
|
7319 'in\n'
|
|
jpayne@68
|
7320 'one step using the "with_traceback()" exception method (which '
|
|
jpayne@68
|
7321 'returns\n'
|
|
jpayne@68
|
7322 'the same exception instance, with its traceback set to its '
|
|
jpayne@68
|
7323 'argument),\n'
|
|
jpayne@68
|
7324 'like so:\n'
|
|
jpayne@68
|
7325 '\n'
|
|
jpayne@68
|
7326 ' raise Exception("foo occurred").with_traceback(tracebackobj)\n'
|
|
jpayne@68
|
7327 '\n'
|
|
jpayne@68
|
7328 'The "from" clause is used for exception chaining: if given, the '
|
|
jpayne@68
|
7329 'second\n'
|
|
jpayne@68
|
7330 '*expression* must be another exception class or instance, which '
|
|
jpayne@68
|
7331 'will\n'
|
|
jpayne@68
|
7332 'then be attached to the raised exception as the "__cause__" '
|
|
jpayne@68
|
7333 'attribute\n'
|
|
jpayne@68
|
7334 '(which is writable). If the raised exception is not handled, both\n'
|
|
jpayne@68
|
7335 'exceptions will be printed:\n'
|
|
jpayne@68
|
7336 '\n'
|
|
jpayne@68
|
7337 ' >>> try:\n'
|
|
jpayne@68
|
7338 ' ... print(1 / 0)\n'
|
|
jpayne@68
|
7339 ' ... except Exception as exc:\n'
|
|
jpayne@68
|
7340 ' ... raise RuntimeError("Something bad happened") from exc\n'
|
|
jpayne@68
|
7341 ' ...\n'
|
|
jpayne@68
|
7342 ' Traceback (most recent call last):\n'
|
|
jpayne@68
|
7343 ' File "<stdin>", line 2, in <module>\n'
|
|
jpayne@68
|
7344 ' ZeroDivisionError: division by zero\n'
|
|
jpayne@68
|
7345 '\n'
|
|
jpayne@68
|
7346 ' The above exception was the direct cause of the following '
|
|
jpayne@68
|
7347 'exception:\n'
|
|
jpayne@68
|
7348 '\n'
|
|
jpayne@68
|
7349 ' Traceback (most recent call last):\n'
|
|
jpayne@68
|
7350 ' File "<stdin>", line 4, in <module>\n'
|
|
jpayne@68
|
7351 ' RuntimeError: Something bad happened\n'
|
|
jpayne@68
|
7352 '\n'
|
|
jpayne@68
|
7353 'A similar mechanism works implicitly if an exception is raised '
|
|
jpayne@68
|
7354 'inside\n'
|
|
jpayne@68
|
7355 'an exception handler or a "finally" clause: the previous exception '
|
|
jpayne@68
|
7356 'is\n'
|
|
jpayne@68
|
7357 'then attached as the new exception’s "__context__" attribute:\n'
|
|
jpayne@68
|
7358 '\n'
|
|
jpayne@68
|
7359 ' >>> try:\n'
|
|
jpayne@68
|
7360 ' ... print(1 / 0)\n'
|
|
jpayne@68
|
7361 ' ... except:\n'
|
|
jpayne@68
|
7362 ' ... raise RuntimeError("Something bad happened")\n'
|
|
jpayne@68
|
7363 ' ...\n'
|
|
jpayne@68
|
7364 ' Traceback (most recent call last):\n'
|
|
jpayne@68
|
7365 ' File "<stdin>", line 2, in <module>\n'
|
|
jpayne@68
|
7366 ' ZeroDivisionError: division by zero\n'
|
|
jpayne@68
|
7367 '\n'
|
|
jpayne@68
|
7368 ' During handling of the above exception, another exception '
|
|
jpayne@68
|
7369 'occurred:\n'
|
|
jpayne@68
|
7370 '\n'
|
|
jpayne@68
|
7371 ' Traceback (most recent call last):\n'
|
|
jpayne@68
|
7372 ' File "<stdin>", line 4, in <module>\n'
|
|
jpayne@68
|
7373 ' RuntimeError: Something bad happened\n'
|
|
jpayne@68
|
7374 '\n'
|
|
jpayne@68
|
7375 'Exception chaining can be explicitly suppressed by specifying '
|
|
jpayne@68
|
7376 '"None"\n'
|
|
jpayne@68
|
7377 'in the "from" clause:\n'
|
|
jpayne@68
|
7378 '\n'
|
|
jpayne@68
|
7379 ' >>> try:\n'
|
|
jpayne@68
|
7380 ' ... print(1 / 0)\n'
|
|
jpayne@68
|
7381 ' ... except:\n'
|
|
jpayne@68
|
7382 ' ... raise RuntimeError("Something bad happened") from None\n'
|
|
jpayne@68
|
7383 ' ...\n'
|
|
jpayne@68
|
7384 ' Traceback (most recent call last):\n'
|
|
jpayne@68
|
7385 ' File "<stdin>", line 4, in <module>\n'
|
|
jpayne@68
|
7386 ' RuntimeError: Something bad happened\n'
|
|
jpayne@68
|
7387 '\n'
|
|
jpayne@68
|
7388 'Additional information on exceptions can be found in section\n'
|
|
jpayne@68
|
7389 'Exceptions, and information about handling exceptions is in '
|
|
jpayne@68
|
7390 'section\n'
|
|
jpayne@68
|
7391 'The try statement.\n'
|
|
jpayne@68
|
7392 '\n'
|
|
jpayne@68
|
7393 'Changed in version 3.3: "None" is now permitted as "Y" in "raise X\n'
|
|
jpayne@68
|
7394 'from Y".\n'
|
|
jpayne@68
|
7395 '\n'
|
|
jpayne@68
|
7396 'New in version 3.3: The "__suppress_context__" attribute to '
|
|
jpayne@68
|
7397 'suppress\n'
|
|
jpayne@68
|
7398 'automatic display of the exception context.\n',
|
|
jpayne@68
|
7399 'return': 'The "return" statement\n'
|
|
jpayne@68
|
7400 '**********************\n'
|
|
jpayne@68
|
7401 '\n'
|
|
jpayne@68
|
7402 ' return_stmt ::= "return" [expression_list]\n'
|
|
jpayne@68
|
7403 '\n'
|
|
jpayne@68
|
7404 '"return" may only occur syntactically nested in a function '
|
|
jpayne@68
|
7405 'definition,\n'
|
|
jpayne@68
|
7406 'not within a nested class definition.\n'
|
|
jpayne@68
|
7407 '\n'
|
|
jpayne@68
|
7408 'If an expression list is present, it is evaluated, else "None" is\n'
|
|
jpayne@68
|
7409 'substituted.\n'
|
|
jpayne@68
|
7410 '\n'
|
|
jpayne@68
|
7411 '"return" leaves the current function call with the expression list '
|
|
jpayne@68
|
7412 '(or\n'
|
|
jpayne@68
|
7413 '"None") as return value.\n'
|
|
jpayne@68
|
7414 '\n'
|
|
jpayne@68
|
7415 'When "return" passes control out of a "try" statement with a '
|
|
jpayne@68
|
7416 '"finally"\n'
|
|
jpayne@68
|
7417 'clause, that "finally" clause is executed before really leaving '
|
|
jpayne@68
|
7418 'the\n'
|
|
jpayne@68
|
7419 'function.\n'
|
|
jpayne@68
|
7420 '\n'
|
|
jpayne@68
|
7421 'In a generator function, the "return" statement indicates that '
|
|
jpayne@68
|
7422 'the\n'
|
|
jpayne@68
|
7423 'generator is done and will cause "StopIteration" to be raised. '
|
|
jpayne@68
|
7424 'The\n'
|
|
jpayne@68
|
7425 'returned value (if any) is used as an argument to construct\n'
|
|
jpayne@68
|
7426 '"StopIteration" and becomes the "StopIteration.value" attribute.\n'
|
|
jpayne@68
|
7427 '\n'
|
|
jpayne@68
|
7428 'In an asynchronous generator function, an empty "return" '
|
|
jpayne@68
|
7429 'statement\n'
|
|
jpayne@68
|
7430 'indicates that the asynchronous generator is done and will cause\n'
|
|
jpayne@68
|
7431 '"StopAsyncIteration" to be raised. A non-empty "return" statement '
|
|
jpayne@68
|
7432 'is\n'
|
|
jpayne@68
|
7433 'a syntax error in an asynchronous generator function.\n',
|
|
jpayne@68
|
7434 'sequence-types': 'Emulating container types\n'
|
|
jpayne@68
|
7435 '*************************\n'
|
|
jpayne@68
|
7436 '\n'
|
|
jpayne@68
|
7437 'The following methods can be defined to implement '
|
|
jpayne@68
|
7438 'container objects.\n'
|
|
jpayne@68
|
7439 'Containers usually are sequences (such as lists or tuples) '
|
|
jpayne@68
|
7440 'or mappings\n'
|
|
jpayne@68
|
7441 '(like dictionaries), but can represent other containers as '
|
|
jpayne@68
|
7442 'well. The\n'
|
|
jpayne@68
|
7443 'first set of methods is used either to emulate a sequence '
|
|
jpayne@68
|
7444 'or to\n'
|
|
jpayne@68
|
7445 'emulate a mapping; the difference is that for a sequence, '
|
|
jpayne@68
|
7446 'the\n'
|
|
jpayne@68
|
7447 'allowable keys should be the integers *k* for which "0 <= '
|
|
jpayne@68
|
7448 'k < N" where\n'
|
|
jpayne@68
|
7449 '*N* is the length of the sequence, or slice objects, which '
|
|
jpayne@68
|
7450 'define a\n'
|
|
jpayne@68
|
7451 'range of items. It is also recommended that mappings '
|
|
jpayne@68
|
7452 'provide the\n'
|
|
jpayne@68
|
7453 'methods "keys()", "values()", "items()", "get()", '
|
|
jpayne@68
|
7454 '"clear()",\n'
|
|
jpayne@68
|
7455 '"setdefault()", "pop()", "popitem()", "copy()", and '
|
|
jpayne@68
|
7456 '"update()"\n'
|
|
jpayne@68
|
7457 'behaving similar to those for Python’s standard dictionary '
|
|
jpayne@68
|
7458 'objects.\n'
|
|
jpayne@68
|
7459 'The "collections.abc" module provides a "MutableMapping" '
|
|
jpayne@68
|
7460 'abstract base\n'
|
|
jpayne@68
|
7461 'class to help create those methods from a base set of '
|
|
jpayne@68
|
7462 '"__getitem__()",\n'
|
|
jpayne@68
|
7463 '"__setitem__()", "__delitem__()", and "keys()". Mutable '
|
|
jpayne@68
|
7464 'sequences\n'
|
|
jpayne@68
|
7465 'should provide methods "append()", "count()", "index()", '
|
|
jpayne@68
|
7466 '"extend()",\n'
|
|
jpayne@68
|
7467 '"insert()", "pop()", "remove()", "reverse()" and "sort()", '
|
|
jpayne@68
|
7468 'like Python\n'
|
|
jpayne@68
|
7469 'standard list objects. Finally, sequence types should '
|
|
jpayne@68
|
7470 'implement\n'
|
|
jpayne@68
|
7471 'addition (meaning concatenation) and multiplication '
|
|
jpayne@68
|
7472 '(meaning\n'
|
|
jpayne@68
|
7473 'repetition) by defining the methods "__add__()", '
|
|
jpayne@68
|
7474 '"__radd__()",\n'
|
|
jpayne@68
|
7475 '"__iadd__()", "__mul__()", "__rmul__()" and "__imul__()" '
|
|
jpayne@68
|
7476 'described\n'
|
|
jpayne@68
|
7477 'below; they should not define other numerical operators. '
|
|
jpayne@68
|
7478 'It is\n'
|
|
jpayne@68
|
7479 'recommended that both mappings and sequences implement '
|
|
jpayne@68
|
7480 'the\n'
|
|
jpayne@68
|
7481 '"__contains__()" method to allow efficient use of the "in" '
|
|
jpayne@68
|
7482 'operator;\n'
|
|
jpayne@68
|
7483 'for mappings, "in" should search the mapping’s keys; for '
|
|
jpayne@68
|
7484 'sequences, it\n'
|
|
jpayne@68
|
7485 'should search through the values. It is further '
|
|
jpayne@68
|
7486 'recommended that both\n'
|
|
jpayne@68
|
7487 'mappings and sequences implement the "__iter__()" method '
|
|
jpayne@68
|
7488 'to allow\n'
|
|
jpayne@68
|
7489 'efficient iteration through the container; for mappings, '
|
|
jpayne@68
|
7490 '"__iter__()"\n'
|
|
jpayne@68
|
7491 'should iterate through the object’s keys; for sequences, '
|
|
jpayne@68
|
7492 'it should\n'
|
|
jpayne@68
|
7493 'iterate through the values.\n'
|
|
jpayne@68
|
7494 '\n'
|
|
jpayne@68
|
7495 'object.__len__(self)\n'
|
|
jpayne@68
|
7496 '\n'
|
|
jpayne@68
|
7497 ' Called to implement the built-in function "len()". '
|
|
jpayne@68
|
7498 'Should return\n'
|
|
jpayne@68
|
7499 ' the length of the object, an integer ">=" 0. Also, an '
|
|
jpayne@68
|
7500 'object that\n'
|
|
jpayne@68
|
7501 ' doesn’t define a "__bool__()" method and whose '
|
|
jpayne@68
|
7502 '"__len__()" method\n'
|
|
jpayne@68
|
7503 ' returns zero is considered to be false in a Boolean '
|
|
jpayne@68
|
7504 'context.\n'
|
|
jpayne@68
|
7505 '\n'
|
|
jpayne@68
|
7506 ' **CPython implementation detail:** In CPython, the '
|
|
jpayne@68
|
7507 'length is\n'
|
|
jpayne@68
|
7508 ' required to be at most "sys.maxsize". If the length is '
|
|
jpayne@68
|
7509 'larger than\n'
|
|
jpayne@68
|
7510 ' "sys.maxsize" some features (such as "len()") may '
|
|
jpayne@68
|
7511 'raise\n'
|
|
jpayne@68
|
7512 ' "OverflowError". To prevent raising "OverflowError" by '
|
|
jpayne@68
|
7513 'truth value\n'
|
|
jpayne@68
|
7514 ' testing, an object must define a "__bool__()" method.\n'
|
|
jpayne@68
|
7515 '\n'
|
|
jpayne@68
|
7516 'object.__length_hint__(self)\n'
|
|
jpayne@68
|
7517 '\n'
|
|
jpayne@68
|
7518 ' Called to implement "operator.length_hint()". Should '
|
|
jpayne@68
|
7519 'return an\n'
|
|
jpayne@68
|
7520 ' estimated length for the object (which may be greater '
|
|
jpayne@68
|
7521 'or less than\n'
|
|
jpayne@68
|
7522 ' the actual length). The length must be an integer ">=" '
|
|
jpayne@68
|
7523 '0. The\n'
|
|
jpayne@68
|
7524 ' return value may also be "NotImplemented", which is '
|
|
jpayne@68
|
7525 'treated the\n'
|
|
jpayne@68
|
7526 ' same as if the "__length_hint__" method didn’t exist at '
|
|
jpayne@68
|
7527 'all. This\n'
|
|
jpayne@68
|
7528 ' method is purely an optimization and is never required '
|
|
jpayne@68
|
7529 'for\n'
|
|
jpayne@68
|
7530 ' correctness.\n'
|
|
jpayne@68
|
7531 '\n'
|
|
jpayne@68
|
7532 ' New in version 3.4.\n'
|
|
jpayne@68
|
7533 '\n'
|
|
jpayne@68
|
7534 'Note: Slicing is done exclusively with the following three '
|
|
jpayne@68
|
7535 'methods.\n'
|
|
jpayne@68
|
7536 ' A call like\n'
|
|
jpayne@68
|
7537 '\n'
|
|
jpayne@68
|
7538 ' a[1:2] = b\n'
|
|
jpayne@68
|
7539 '\n'
|
|
jpayne@68
|
7540 ' is translated to\n'
|
|
jpayne@68
|
7541 '\n'
|
|
jpayne@68
|
7542 ' a[slice(1, 2, None)] = b\n'
|
|
jpayne@68
|
7543 '\n'
|
|
jpayne@68
|
7544 ' and so forth. Missing slice items are always filled in '
|
|
jpayne@68
|
7545 'with "None".\n'
|
|
jpayne@68
|
7546 '\n'
|
|
jpayne@68
|
7547 'object.__getitem__(self, key)\n'
|
|
jpayne@68
|
7548 '\n'
|
|
jpayne@68
|
7549 ' Called to implement evaluation of "self[key]". For '
|
|
jpayne@68
|
7550 'sequence types,\n'
|
|
jpayne@68
|
7551 ' the accepted keys should be integers and slice '
|
|
jpayne@68
|
7552 'objects. Note that\n'
|
|
jpayne@68
|
7553 ' the special interpretation of negative indexes (if the '
|
|
jpayne@68
|
7554 'class wishes\n'
|
|
jpayne@68
|
7555 ' to emulate a sequence type) is up to the '
|
|
jpayne@68
|
7556 '"__getitem__()" method. If\n'
|
|
jpayne@68
|
7557 ' *key* is of an inappropriate type, "TypeError" may be '
|
|
jpayne@68
|
7558 'raised; if of\n'
|
|
jpayne@68
|
7559 ' a value outside the set of indexes for the sequence '
|
|
jpayne@68
|
7560 '(after any\n'
|
|
jpayne@68
|
7561 ' special interpretation of negative values), '
|
|
jpayne@68
|
7562 '"IndexError" should be\n'
|
|
jpayne@68
|
7563 ' raised. For mapping types, if *key* is missing (not in '
|
|
jpayne@68
|
7564 'the\n'
|
|
jpayne@68
|
7565 ' container), "KeyError" should be raised.\n'
|
|
jpayne@68
|
7566 '\n'
|
|
jpayne@68
|
7567 ' Note: "for" loops expect that an "IndexError" will be '
|
|
jpayne@68
|
7568 'raised for\n'
|
|
jpayne@68
|
7569 ' illegal indexes to allow proper detection of the end '
|
|
jpayne@68
|
7570 'of the\n'
|
|
jpayne@68
|
7571 ' sequence.\n'
|
|
jpayne@68
|
7572 '\n'
|
|
jpayne@68
|
7573 'object.__setitem__(self, key, value)\n'
|
|
jpayne@68
|
7574 '\n'
|
|
jpayne@68
|
7575 ' Called to implement assignment to "self[key]". Same '
|
|
jpayne@68
|
7576 'note as for\n'
|
|
jpayne@68
|
7577 ' "__getitem__()". This should only be implemented for '
|
|
jpayne@68
|
7578 'mappings if\n'
|
|
jpayne@68
|
7579 ' the objects support changes to the values for keys, or '
|
|
jpayne@68
|
7580 'if new keys\n'
|
|
jpayne@68
|
7581 ' can be added, or for sequences if elements can be '
|
|
jpayne@68
|
7582 'replaced. The\n'
|
|
jpayne@68
|
7583 ' same exceptions should be raised for improper *key* '
|
|
jpayne@68
|
7584 'values as for\n'
|
|
jpayne@68
|
7585 ' the "__getitem__()" method.\n'
|
|
jpayne@68
|
7586 '\n'
|
|
jpayne@68
|
7587 'object.__delitem__(self, key)\n'
|
|
jpayne@68
|
7588 '\n'
|
|
jpayne@68
|
7589 ' Called to implement deletion of "self[key]". Same note '
|
|
jpayne@68
|
7590 'as for\n'
|
|
jpayne@68
|
7591 ' "__getitem__()". This should only be implemented for '
|
|
jpayne@68
|
7592 'mappings if\n'
|
|
jpayne@68
|
7593 ' the objects support removal of keys, or for sequences '
|
|
jpayne@68
|
7594 'if elements\n'
|
|
jpayne@68
|
7595 ' can be removed from the sequence. The same exceptions '
|
|
jpayne@68
|
7596 'should be\n'
|
|
jpayne@68
|
7597 ' raised for improper *key* values as for the '
|
|
jpayne@68
|
7598 '"__getitem__()" method.\n'
|
|
jpayne@68
|
7599 '\n'
|
|
jpayne@68
|
7600 'object.__missing__(self, key)\n'
|
|
jpayne@68
|
7601 '\n'
|
|
jpayne@68
|
7602 ' Called by "dict"."__getitem__()" to implement '
|
|
jpayne@68
|
7603 '"self[key]" for dict\n'
|
|
jpayne@68
|
7604 ' subclasses when key is not in the dictionary.\n'
|
|
jpayne@68
|
7605 '\n'
|
|
jpayne@68
|
7606 'object.__iter__(self)\n'
|
|
jpayne@68
|
7607 '\n'
|
|
jpayne@68
|
7608 ' This method is called when an iterator is required for '
|
|
jpayne@68
|
7609 'a container.\n'
|
|
jpayne@68
|
7610 ' This method should return a new iterator object that '
|
|
jpayne@68
|
7611 'can iterate\n'
|
|
jpayne@68
|
7612 ' over all the objects in the container. For mappings, '
|
|
jpayne@68
|
7613 'it should\n'
|
|
jpayne@68
|
7614 ' iterate over the keys of the container.\n'
|
|
jpayne@68
|
7615 '\n'
|
|
jpayne@68
|
7616 ' Iterator objects also need to implement this method; '
|
|
jpayne@68
|
7617 'they are\n'
|
|
jpayne@68
|
7618 ' required to return themselves. For more information on '
|
|
jpayne@68
|
7619 'iterator\n'
|
|
jpayne@68
|
7620 ' objects, see Iterator Types.\n'
|
|
jpayne@68
|
7621 '\n'
|
|
jpayne@68
|
7622 'object.__reversed__(self)\n'
|
|
jpayne@68
|
7623 '\n'
|
|
jpayne@68
|
7624 ' Called (if present) by the "reversed()" built-in to '
|
|
jpayne@68
|
7625 'implement\n'
|
|
jpayne@68
|
7626 ' reverse iteration. It should return a new iterator '
|
|
jpayne@68
|
7627 'object that\n'
|
|
jpayne@68
|
7628 ' iterates over all the objects in the container in '
|
|
jpayne@68
|
7629 'reverse order.\n'
|
|
jpayne@68
|
7630 '\n'
|
|
jpayne@68
|
7631 ' If the "__reversed__()" method is not provided, the '
|
|
jpayne@68
|
7632 '"reversed()"\n'
|
|
jpayne@68
|
7633 ' built-in will fall back to using the sequence protocol '
|
|
jpayne@68
|
7634 '("__len__()"\n'
|
|
jpayne@68
|
7635 ' and "__getitem__()"). Objects that support the '
|
|
jpayne@68
|
7636 'sequence protocol\n'
|
|
jpayne@68
|
7637 ' should only provide "__reversed__()" if they can '
|
|
jpayne@68
|
7638 'provide an\n'
|
|
jpayne@68
|
7639 ' implementation that is more efficient than the one '
|
|
jpayne@68
|
7640 'provided by\n'
|
|
jpayne@68
|
7641 ' "reversed()".\n'
|
|
jpayne@68
|
7642 '\n'
|
|
jpayne@68
|
7643 'The membership test operators ("in" and "not in") are '
|
|
jpayne@68
|
7644 'normally\n'
|
|
jpayne@68
|
7645 'implemented as an iteration through a container. However, '
|
|
jpayne@68
|
7646 'container\n'
|
|
jpayne@68
|
7647 'objects can supply the following special method with a '
|
|
jpayne@68
|
7648 'more efficient\n'
|
|
jpayne@68
|
7649 'implementation, which also does not require the object be '
|
|
jpayne@68
|
7650 'iterable.\n'
|
|
jpayne@68
|
7651 '\n'
|
|
jpayne@68
|
7652 'object.__contains__(self, item)\n'
|
|
jpayne@68
|
7653 '\n'
|
|
jpayne@68
|
7654 ' Called to implement membership test operators. Should '
|
|
jpayne@68
|
7655 'return true\n'
|
|
jpayne@68
|
7656 ' if *item* is in *self*, false otherwise. For mapping '
|
|
jpayne@68
|
7657 'objects, this\n'
|
|
jpayne@68
|
7658 ' should consider the keys of the mapping rather than the '
|
|
jpayne@68
|
7659 'values or\n'
|
|
jpayne@68
|
7660 ' the key-item pairs.\n'
|
|
jpayne@68
|
7661 '\n'
|
|
jpayne@68
|
7662 ' For objects that don’t define "__contains__()", the '
|
|
jpayne@68
|
7663 'membership test\n'
|
|
jpayne@68
|
7664 ' first tries iteration via "__iter__()", then the old '
|
|
jpayne@68
|
7665 'sequence\n'
|
|
jpayne@68
|
7666 ' iteration protocol via "__getitem__()", see this '
|
|
jpayne@68
|
7667 'section in the\n'
|
|
jpayne@68
|
7668 ' language reference.\n',
|
|
jpayne@68
|
7669 'shifting': 'Shifting operations\n'
|
|
jpayne@68
|
7670 '*******************\n'
|
|
jpayne@68
|
7671 '\n'
|
|
jpayne@68
|
7672 'The shifting operations have lower priority than the arithmetic\n'
|
|
jpayne@68
|
7673 'operations:\n'
|
|
jpayne@68
|
7674 '\n'
|
|
jpayne@68
|
7675 ' shift_expr ::= a_expr | shift_expr ("<<" | ">>") a_expr\n'
|
|
jpayne@68
|
7676 '\n'
|
|
jpayne@68
|
7677 'These operators accept integers as arguments. They shift the '
|
|
jpayne@68
|
7678 'first\n'
|
|
jpayne@68
|
7679 'argument to the left or right by the number of bits given by '
|
|
jpayne@68
|
7680 'the\n'
|
|
jpayne@68
|
7681 'second argument.\n'
|
|
jpayne@68
|
7682 '\n'
|
|
jpayne@68
|
7683 'A right shift by *n* bits is defined as floor division by '
|
|
jpayne@68
|
7684 '"pow(2,n)".\n'
|
|
jpayne@68
|
7685 'A left shift by *n* bits is defined as multiplication with '
|
|
jpayne@68
|
7686 '"pow(2,n)".\n',
|
|
jpayne@68
|
7687 'slicings': 'Slicings\n'
|
|
jpayne@68
|
7688 '********\n'
|
|
jpayne@68
|
7689 '\n'
|
|
jpayne@68
|
7690 'A slicing selects a range of items in a sequence object (e.g., '
|
|
jpayne@68
|
7691 'a\n'
|
|
jpayne@68
|
7692 'string, tuple or list). Slicings may be used as expressions or '
|
|
jpayne@68
|
7693 'as\n'
|
|
jpayne@68
|
7694 'targets in assignment or "del" statements. The syntax for a '
|
|
jpayne@68
|
7695 'slicing:\n'
|
|
jpayne@68
|
7696 '\n'
|
|
jpayne@68
|
7697 ' slicing ::= primary "[" slice_list "]"\n'
|
|
jpayne@68
|
7698 ' slice_list ::= slice_item ("," slice_item)* [","]\n'
|
|
jpayne@68
|
7699 ' slice_item ::= expression | proper_slice\n'
|
|
jpayne@68
|
7700 ' proper_slice ::= [lower_bound] ":" [upper_bound] [ ":" '
|
|
jpayne@68
|
7701 '[stride] ]\n'
|
|
jpayne@68
|
7702 ' lower_bound ::= expression\n'
|
|
jpayne@68
|
7703 ' upper_bound ::= expression\n'
|
|
jpayne@68
|
7704 ' stride ::= expression\n'
|
|
jpayne@68
|
7705 '\n'
|
|
jpayne@68
|
7706 'There is ambiguity in the formal syntax here: anything that '
|
|
jpayne@68
|
7707 'looks like\n'
|
|
jpayne@68
|
7708 'an expression list also looks like a slice list, so any '
|
|
jpayne@68
|
7709 'subscription\n'
|
|
jpayne@68
|
7710 'can be interpreted as a slicing. Rather than further '
|
|
jpayne@68
|
7711 'complicating the\n'
|
|
jpayne@68
|
7712 'syntax, this is disambiguated by defining that in this case the\n'
|
|
jpayne@68
|
7713 'interpretation as a subscription takes priority over the\n'
|
|
jpayne@68
|
7714 'interpretation as a slicing (this is the case if the slice list\n'
|
|
jpayne@68
|
7715 'contains no proper slice).\n'
|
|
jpayne@68
|
7716 '\n'
|
|
jpayne@68
|
7717 'The semantics for a slicing are as follows. The primary is '
|
|
jpayne@68
|
7718 'indexed\n'
|
|
jpayne@68
|
7719 '(using the same "__getitem__()" method as normal subscription) '
|
|
jpayne@68
|
7720 'with a\n'
|
|
jpayne@68
|
7721 'key that is constructed from the slice list, as follows. If the '
|
|
jpayne@68
|
7722 'slice\n'
|
|
jpayne@68
|
7723 'list contains at least one comma, the key is a tuple containing '
|
|
jpayne@68
|
7724 'the\n'
|
|
jpayne@68
|
7725 'conversion of the slice items; otherwise, the conversion of the '
|
|
jpayne@68
|
7726 'lone\n'
|
|
jpayne@68
|
7727 'slice item is the key. The conversion of a slice item that is '
|
|
jpayne@68
|
7728 'an\n'
|
|
jpayne@68
|
7729 'expression is that expression. The conversion of a proper slice '
|
|
jpayne@68
|
7730 'is a\n'
|
|
jpayne@68
|
7731 'slice object (see section The standard type hierarchy) whose '
|
|
jpayne@68
|
7732 '"start",\n'
|
|
jpayne@68
|
7733 '"stop" and "step" attributes are the values of the expressions '
|
|
jpayne@68
|
7734 'given\n'
|
|
jpayne@68
|
7735 'as lower bound, upper bound and stride, respectively, '
|
|
jpayne@68
|
7736 'substituting\n'
|
|
jpayne@68
|
7737 '"None" for missing expressions.\n',
|
|
jpayne@68
|
7738 'specialattrs': 'Special Attributes\n'
|
|
jpayne@68
|
7739 '******************\n'
|
|
jpayne@68
|
7740 '\n'
|
|
jpayne@68
|
7741 'The implementation adds a few special read-only attributes '
|
|
jpayne@68
|
7742 'to several\n'
|
|
jpayne@68
|
7743 'object types, where they are relevant. Some of these are '
|
|
jpayne@68
|
7744 'not reported\n'
|
|
jpayne@68
|
7745 'by the "dir()" built-in function.\n'
|
|
jpayne@68
|
7746 '\n'
|
|
jpayne@68
|
7747 'object.__dict__\n'
|
|
jpayne@68
|
7748 '\n'
|
|
jpayne@68
|
7749 ' A dictionary or other mapping object used to store an '
|
|
jpayne@68
|
7750 'object’s\n'
|
|
jpayne@68
|
7751 ' (writable) attributes.\n'
|
|
jpayne@68
|
7752 '\n'
|
|
jpayne@68
|
7753 'instance.__class__\n'
|
|
jpayne@68
|
7754 '\n'
|
|
jpayne@68
|
7755 ' The class to which a class instance belongs.\n'
|
|
jpayne@68
|
7756 '\n'
|
|
jpayne@68
|
7757 'class.__bases__\n'
|
|
jpayne@68
|
7758 '\n'
|
|
jpayne@68
|
7759 ' The tuple of base classes of a class object.\n'
|
|
jpayne@68
|
7760 '\n'
|
|
jpayne@68
|
7761 'definition.__name__\n'
|
|
jpayne@68
|
7762 '\n'
|
|
jpayne@68
|
7763 ' The name of the class, function, method, descriptor, or '
|
|
jpayne@68
|
7764 'generator\n'
|
|
jpayne@68
|
7765 ' instance.\n'
|
|
jpayne@68
|
7766 '\n'
|
|
jpayne@68
|
7767 'definition.__qualname__\n'
|
|
jpayne@68
|
7768 '\n'
|
|
jpayne@68
|
7769 ' The *qualified name* of the class, function, method, '
|
|
jpayne@68
|
7770 'descriptor, or\n'
|
|
jpayne@68
|
7771 ' generator instance.\n'
|
|
jpayne@68
|
7772 '\n'
|
|
jpayne@68
|
7773 ' New in version 3.3.\n'
|
|
jpayne@68
|
7774 '\n'
|
|
jpayne@68
|
7775 'class.__mro__\n'
|
|
jpayne@68
|
7776 '\n'
|
|
jpayne@68
|
7777 ' This attribute is a tuple of classes that are considered '
|
|
jpayne@68
|
7778 'when\n'
|
|
jpayne@68
|
7779 ' looking for base classes during method resolution.\n'
|
|
jpayne@68
|
7780 '\n'
|
|
jpayne@68
|
7781 'class.mro()\n'
|
|
jpayne@68
|
7782 '\n'
|
|
jpayne@68
|
7783 ' This method can be overridden by a metaclass to customize '
|
|
jpayne@68
|
7784 'the\n'
|
|
jpayne@68
|
7785 ' method resolution order for its instances. It is called '
|
|
jpayne@68
|
7786 'at class\n'
|
|
jpayne@68
|
7787 ' instantiation, and its result is stored in "__mro__".\n'
|
|
jpayne@68
|
7788 '\n'
|
|
jpayne@68
|
7789 'class.__subclasses__()\n'
|
|
jpayne@68
|
7790 '\n'
|
|
jpayne@68
|
7791 ' Each class keeps a list of weak references to its '
|
|
jpayne@68
|
7792 'immediate\n'
|
|
jpayne@68
|
7793 ' subclasses. This method returns a list of all those '
|
|
jpayne@68
|
7794 'references\n'
|
|
jpayne@68
|
7795 ' still alive. Example:\n'
|
|
jpayne@68
|
7796 '\n'
|
|
jpayne@68
|
7797 ' >>> int.__subclasses__()\n'
|
|
jpayne@68
|
7798 " [<class 'bool'>]\n"
|
|
jpayne@68
|
7799 '\n'
|
|
jpayne@68
|
7800 '-[ Footnotes ]-\n'
|
|
jpayne@68
|
7801 '\n'
|
|
jpayne@68
|
7802 '[1] Additional information on these special methods may be '
|
|
jpayne@68
|
7803 'found\n'
|
|
jpayne@68
|
7804 ' in the Python Reference Manual (Basic customization).\n'
|
|
jpayne@68
|
7805 '\n'
|
|
jpayne@68
|
7806 '[2] As a consequence, the list "[1, 2]" is considered equal '
|
|
jpayne@68
|
7807 'to\n'
|
|
jpayne@68
|
7808 ' "[1.0, 2.0]", and similarly for tuples.\n'
|
|
jpayne@68
|
7809 '\n'
|
|
jpayne@68
|
7810 '[3] They must have since the parser can’t tell the type of '
|
|
jpayne@68
|
7811 'the\n'
|
|
jpayne@68
|
7812 ' operands.\n'
|
|
jpayne@68
|
7813 '\n'
|
|
jpayne@68
|
7814 '[4] Cased characters are those with general category '
|
|
jpayne@68
|
7815 'property\n'
|
|
jpayne@68
|
7816 ' being one of “Lu” (Letter, uppercase), “Ll” (Letter, '
|
|
jpayne@68
|
7817 'lowercase),\n'
|
|
jpayne@68
|
7818 ' or “Lt” (Letter, titlecase).\n'
|
|
jpayne@68
|
7819 '\n'
|
|
jpayne@68
|
7820 '[5] To format only a tuple you should therefore provide a\n'
|
|
jpayne@68
|
7821 ' singleton tuple whose only element is the tuple to be '
|
|
jpayne@68
|
7822 'formatted.\n',
|
|
jpayne@68
|
7823 'specialnames': 'Special method names\n'
|
|
jpayne@68
|
7824 '********************\n'
|
|
jpayne@68
|
7825 '\n'
|
|
jpayne@68
|
7826 'A class can implement certain operations that are invoked by '
|
|
jpayne@68
|
7827 'special\n'
|
|
jpayne@68
|
7828 'syntax (such as arithmetic operations or subscripting and '
|
|
jpayne@68
|
7829 'slicing) by\n'
|
|
jpayne@68
|
7830 'defining methods with special names. This is Python’s '
|
|
jpayne@68
|
7831 'approach to\n'
|
|
jpayne@68
|
7832 '*operator overloading*, allowing classes to define their own '
|
|
jpayne@68
|
7833 'behavior\n'
|
|
jpayne@68
|
7834 'with respect to language operators. For instance, if a '
|
|
jpayne@68
|
7835 'class defines\n'
|
|
jpayne@68
|
7836 'a method named "__getitem__()", and "x" is an instance of '
|
|
jpayne@68
|
7837 'this class,\n'
|
|
jpayne@68
|
7838 'then "x[i]" is roughly equivalent to "type(x).__getitem__(x, '
|
|
jpayne@68
|
7839 'i)".\n'
|
|
jpayne@68
|
7840 'Except where mentioned, attempts to execute an operation '
|
|
jpayne@68
|
7841 'raise an\n'
|
|
jpayne@68
|
7842 'exception when no appropriate method is defined (typically\n'
|
|
jpayne@68
|
7843 '"AttributeError" or "TypeError").\n'
|
|
jpayne@68
|
7844 '\n'
|
|
jpayne@68
|
7845 'Setting a special method to "None" indicates that the '
|
|
jpayne@68
|
7846 'corresponding\n'
|
|
jpayne@68
|
7847 'operation is not available. For example, if a class sets '
|
|
jpayne@68
|
7848 '"__iter__()"\n'
|
|
jpayne@68
|
7849 'to "None", the class is not iterable, so calling "iter()" on '
|
|
jpayne@68
|
7850 'its\n'
|
|
jpayne@68
|
7851 'instances will raise a "TypeError" (without falling back to\n'
|
|
jpayne@68
|
7852 '"__getitem__()"). [2]\n'
|
|
jpayne@68
|
7853 '\n'
|
|
jpayne@68
|
7854 'When implementing a class that emulates any built-in type, '
|
|
jpayne@68
|
7855 'it is\n'
|
|
jpayne@68
|
7856 'important that the emulation only be implemented to the '
|
|
jpayne@68
|
7857 'degree that it\n'
|
|
jpayne@68
|
7858 'makes sense for the object being modelled. For example, '
|
|
jpayne@68
|
7859 'some\n'
|
|
jpayne@68
|
7860 'sequences may work well with retrieval of individual '
|
|
jpayne@68
|
7861 'elements, but\n'
|
|
jpayne@68
|
7862 'extracting a slice may not make sense. (One example of this '
|
|
jpayne@68
|
7863 'is the\n'
|
|
jpayne@68
|
7864 '"NodeList" interface in the W3C’s Document Object Model.)\n'
|
|
jpayne@68
|
7865 '\n'
|
|
jpayne@68
|
7866 '\n'
|
|
jpayne@68
|
7867 'Basic customization\n'
|
|
jpayne@68
|
7868 '===================\n'
|
|
jpayne@68
|
7869 '\n'
|
|
jpayne@68
|
7870 'object.__new__(cls[, ...])\n'
|
|
jpayne@68
|
7871 '\n'
|
|
jpayne@68
|
7872 ' Called to create a new instance of class *cls*. '
|
|
jpayne@68
|
7873 '"__new__()" is a\n'
|
|
jpayne@68
|
7874 ' static method (special-cased so you need not declare it '
|
|
jpayne@68
|
7875 'as such)\n'
|
|
jpayne@68
|
7876 ' that takes the class of which an instance was requested '
|
|
jpayne@68
|
7877 'as its\n'
|
|
jpayne@68
|
7878 ' first argument. The remaining arguments are those passed '
|
|
jpayne@68
|
7879 'to the\n'
|
|
jpayne@68
|
7880 ' object constructor expression (the call to the class). '
|
|
jpayne@68
|
7881 'The return\n'
|
|
jpayne@68
|
7882 ' value of "__new__()" should be the new object instance '
|
|
jpayne@68
|
7883 '(usually an\n'
|
|
jpayne@68
|
7884 ' instance of *cls*).\n'
|
|
jpayne@68
|
7885 '\n'
|
|
jpayne@68
|
7886 ' Typical implementations create a new instance of the '
|
|
jpayne@68
|
7887 'class by\n'
|
|
jpayne@68
|
7888 ' invoking the superclass’s "__new__()" method using\n'
|
|
jpayne@68
|
7889 ' "super().__new__(cls[, ...])" with appropriate arguments '
|
|
jpayne@68
|
7890 'and then\n'
|
|
jpayne@68
|
7891 ' modifying the newly-created instance as necessary before '
|
|
jpayne@68
|
7892 'returning\n'
|
|
jpayne@68
|
7893 ' it.\n'
|
|
jpayne@68
|
7894 '\n'
|
|
jpayne@68
|
7895 ' If "__new__()" is invoked during object construction and '
|
|
jpayne@68
|
7896 'it returns\n'
|
|
jpayne@68
|
7897 ' an instance or subclass of *cls*, then the new '
|
|
jpayne@68
|
7898 'instance’s\n'
|
|
jpayne@68
|
7899 ' "__init__()" method will be invoked like "__init__(self[, '
|
|
jpayne@68
|
7900 '...])",\n'
|
|
jpayne@68
|
7901 ' where *self* is the new instance and the remaining '
|
|
jpayne@68
|
7902 'arguments are\n'
|
|
jpayne@68
|
7903 ' the same as were passed to the object constructor.\n'
|
|
jpayne@68
|
7904 '\n'
|
|
jpayne@68
|
7905 ' If "__new__()" does not return an instance of *cls*, then '
|
|
jpayne@68
|
7906 'the new\n'
|
|
jpayne@68
|
7907 ' instance’s "__init__()" method will not be invoked.\n'
|
|
jpayne@68
|
7908 '\n'
|
|
jpayne@68
|
7909 ' "__new__()" is intended mainly to allow subclasses of '
|
|
jpayne@68
|
7910 'immutable\n'
|
|
jpayne@68
|
7911 ' types (like int, str, or tuple) to customize instance '
|
|
jpayne@68
|
7912 'creation. It\n'
|
|
jpayne@68
|
7913 ' is also commonly overridden in custom metaclasses in '
|
|
jpayne@68
|
7914 'order to\n'
|
|
jpayne@68
|
7915 ' customize class creation.\n'
|
|
jpayne@68
|
7916 '\n'
|
|
jpayne@68
|
7917 'object.__init__(self[, ...])\n'
|
|
jpayne@68
|
7918 '\n'
|
|
jpayne@68
|
7919 ' Called after the instance has been created (by '
|
|
jpayne@68
|
7920 '"__new__()"), but\n'
|
|
jpayne@68
|
7921 ' before it is returned to the caller. The arguments are '
|
|
jpayne@68
|
7922 'those\n'
|
|
jpayne@68
|
7923 ' passed to the class constructor expression. If a base '
|
|
jpayne@68
|
7924 'class has an\n'
|
|
jpayne@68
|
7925 ' "__init__()" method, the derived class’s "__init__()" '
|
|
jpayne@68
|
7926 'method, if\n'
|
|
jpayne@68
|
7927 ' any, must explicitly call it to ensure proper '
|
|
jpayne@68
|
7928 'initialization of the\n'
|
|
jpayne@68
|
7929 ' base class part of the instance; for example:\n'
|
|
jpayne@68
|
7930 ' "super().__init__([args...])".\n'
|
|
jpayne@68
|
7931 '\n'
|
|
jpayne@68
|
7932 ' Because "__new__()" and "__init__()" work together in '
|
|
jpayne@68
|
7933 'constructing\n'
|
|
jpayne@68
|
7934 ' objects ("__new__()" to create it, and "__init__()" to '
|
|
jpayne@68
|
7935 'customize\n'
|
|
jpayne@68
|
7936 ' it), no non-"None" value may be returned by "__init__()"; '
|
|
jpayne@68
|
7937 'doing so\n'
|
|
jpayne@68
|
7938 ' will cause a "TypeError" to be raised at runtime.\n'
|
|
jpayne@68
|
7939 '\n'
|
|
jpayne@68
|
7940 'object.__del__(self)\n'
|
|
jpayne@68
|
7941 '\n'
|
|
jpayne@68
|
7942 ' Called when the instance is about to be destroyed. This '
|
|
jpayne@68
|
7943 'is also\n'
|
|
jpayne@68
|
7944 ' called a finalizer or (improperly) a destructor. If a '
|
|
jpayne@68
|
7945 'base class\n'
|
|
jpayne@68
|
7946 ' has a "__del__()" method, the derived class’s "__del__()" '
|
|
jpayne@68
|
7947 'method,\n'
|
|
jpayne@68
|
7948 ' if any, must explicitly call it to ensure proper deletion '
|
|
jpayne@68
|
7949 'of the\n'
|
|
jpayne@68
|
7950 ' base class part of the instance.\n'
|
|
jpayne@68
|
7951 '\n'
|
|
jpayne@68
|
7952 ' It is possible (though not recommended!) for the '
|
|
jpayne@68
|
7953 '"__del__()" method\n'
|
|
jpayne@68
|
7954 ' to postpone destruction of the instance by creating a new '
|
|
jpayne@68
|
7955 'reference\n'
|
|
jpayne@68
|
7956 ' to it. This is called object *resurrection*. It is\n'
|
|
jpayne@68
|
7957 ' implementation-dependent whether "__del__()" is called a '
|
|
jpayne@68
|
7958 'second\n'
|
|
jpayne@68
|
7959 ' time when a resurrected object is about to be destroyed; '
|
|
jpayne@68
|
7960 'the\n'
|
|
jpayne@68
|
7961 ' current *CPython* implementation only calls it once.\n'
|
|
jpayne@68
|
7962 '\n'
|
|
jpayne@68
|
7963 ' It is not guaranteed that "__del__()" methods are called '
|
|
jpayne@68
|
7964 'for\n'
|
|
jpayne@68
|
7965 ' objects that still exist when the interpreter exits.\n'
|
|
jpayne@68
|
7966 '\n'
|
|
jpayne@68
|
7967 ' Note: "del x" doesn’t directly call "x.__del__()" — the '
|
|
jpayne@68
|
7968 'former\n'
|
|
jpayne@68
|
7969 ' decrements the reference count for "x" by one, and the '
|
|
jpayne@68
|
7970 'latter is\n'
|
|
jpayne@68
|
7971 ' only called when "x"’s reference count reaches zero.\n'
|
|
jpayne@68
|
7972 '\n'
|
|
jpayne@68
|
7973 ' **CPython implementation detail:** It is possible for a '
|
|
jpayne@68
|
7974 'reference\n'
|
|
jpayne@68
|
7975 ' cycle to prevent the reference count of an object from '
|
|
jpayne@68
|
7976 'going to\n'
|
|
jpayne@68
|
7977 ' zero. In this case, the cycle will be later detected and '
|
|
jpayne@68
|
7978 'deleted\n'
|
|
jpayne@68
|
7979 ' by the *cyclic garbage collector*. A common cause of '
|
|
jpayne@68
|
7980 'reference\n'
|
|
jpayne@68
|
7981 ' cycles is when an exception has been caught in a local '
|
|
jpayne@68
|
7982 'variable.\n'
|
|
jpayne@68
|
7983 ' The frame’s locals then reference the exception, which '
|
|
jpayne@68
|
7984 'references\n'
|
|
jpayne@68
|
7985 ' its own traceback, which references the locals of all '
|
|
jpayne@68
|
7986 'frames caught\n'
|
|
jpayne@68
|
7987 ' in the traceback.\n'
|
|
jpayne@68
|
7988 '\n'
|
|
jpayne@68
|
7989 ' See also: Documentation for the "gc" module.\n'
|
|
jpayne@68
|
7990 '\n'
|
|
jpayne@68
|
7991 ' Warning: Due to the precarious circumstances under which\n'
|
|
jpayne@68
|
7992 ' "__del__()" methods are invoked, exceptions that occur '
|
|
jpayne@68
|
7993 'during\n'
|
|
jpayne@68
|
7994 ' their execution are ignored, and a warning is printed '
|
|
jpayne@68
|
7995 'to\n'
|
|
jpayne@68
|
7996 ' "sys.stderr" instead. In particular:\n'
|
|
jpayne@68
|
7997 '\n'
|
|
jpayne@68
|
7998 ' * "__del__()" can be invoked when arbitrary code is '
|
|
jpayne@68
|
7999 'being\n'
|
|
jpayne@68
|
8000 ' executed, including from any arbitrary thread. If '
|
|
jpayne@68
|
8001 '"__del__()"\n'
|
|
jpayne@68
|
8002 ' needs to take a lock or invoke any other blocking '
|
|
jpayne@68
|
8003 'resource, it\n'
|
|
jpayne@68
|
8004 ' may deadlock as the resource may already be taken by '
|
|
jpayne@68
|
8005 'the code\n'
|
|
jpayne@68
|
8006 ' that gets interrupted to execute "__del__()".\n'
|
|
jpayne@68
|
8007 '\n'
|
|
jpayne@68
|
8008 ' * "__del__()" can be executed during interpreter '
|
|
jpayne@68
|
8009 'shutdown. As\n'
|
|
jpayne@68
|
8010 ' a consequence, the global variables it needs to '
|
|
jpayne@68
|
8011 'access\n'
|
|
jpayne@68
|
8012 ' (including other modules) may already have been '
|
|
jpayne@68
|
8013 'deleted or set\n'
|
|
jpayne@68
|
8014 ' to "None". Python guarantees that globals whose name '
|
|
jpayne@68
|
8015 'begins\n'
|
|
jpayne@68
|
8016 ' with a single underscore are deleted from their '
|
|
jpayne@68
|
8017 'module before\n'
|
|
jpayne@68
|
8018 ' other globals are deleted; if no other references to '
|
|
jpayne@68
|
8019 'such\n'
|
|
jpayne@68
|
8020 ' globals exist, this may help in assuring that '
|
|
jpayne@68
|
8021 'imported modules\n'
|
|
jpayne@68
|
8022 ' are still available at the time when the "__del__()" '
|
|
jpayne@68
|
8023 'method is\n'
|
|
jpayne@68
|
8024 ' called.\n'
|
|
jpayne@68
|
8025 '\n'
|
|
jpayne@68
|
8026 'object.__repr__(self)\n'
|
|
jpayne@68
|
8027 '\n'
|
|
jpayne@68
|
8028 ' Called by the "repr()" built-in function to compute the '
|
|
jpayne@68
|
8029 '“official”\n'
|
|
jpayne@68
|
8030 ' string representation of an object. If at all possible, '
|
|
jpayne@68
|
8031 'this\n'
|
|
jpayne@68
|
8032 ' should look like a valid Python expression that could be '
|
|
jpayne@68
|
8033 'used to\n'
|
|
jpayne@68
|
8034 ' recreate an object with the same value (given an '
|
|
jpayne@68
|
8035 'appropriate\n'
|
|
jpayne@68
|
8036 ' environment). If this is not possible, a string of the '
|
|
jpayne@68
|
8037 'form\n'
|
|
jpayne@68
|
8038 ' "<...some useful description...>" should be returned. The '
|
|
jpayne@68
|
8039 'return\n'
|
|
jpayne@68
|
8040 ' value must be a string object. If a class defines '
|
|
jpayne@68
|
8041 '"__repr__()" but\n'
|
|
jpayne@68
|
8042 ' not "__str__()", then "__repr__()" is also used when an '
|
|
jpayne@68
|
8043 '“informal”\n'
|
|
jpayne@68
|
8044 ' string representation of instances of that class is '
|
|
jpayne@68
|
8045 'required.\n'
|
|
jpayne@68
|
8046 '\n'
|
|
jpayne@68
|
8047 ' This is typically used for debugging, so it is important '
|
|
jpayne@68
|
8048 'that the\n'
|
|
jpayne@68
|
8049 ' representation is information-rich and unambiguous.\n'
|
|
jpayne@68
|
8050 '\n'
|
|
jpayne@68
|
8051 'object.__str__(self)\n'
|
|
jpayne@68
|
8052 '\n'
|
|
jpayne@68
|
8053 ' Called by "str(object)" and the built-in functions '
|
|
jpayne@68
|
8054 '"format()" and\n'
|
|
jpayne@68
|
8055 ' "print()" to compute the “informal” or nicely printable '
|
|
jpayne@68
|
8056 'string\n'
|
|
jpayne@68
|
8057 ' representation of an object. The return value must be a '
|
|
jpayne@68
|
8058 'string\n'
|
|
jpayne@68
|
8059 ' object.\n'
|
|
jpayne@68
|
8060 '\n'
|
|
jpayne@68
|
8061 ' This method differs from "object.__repr__()" in that '
|
|
jpayne@68
|
8062 'there is no\n'
|
|
jpayne@68
|
8063 ' expectation that "__str__()" return a valid Python '
|
|
jpayne@68
|
8064 'expression: a\n'
|
|
jpayne@68
|
8065 ' more convenient or concise representation can be used.\n'
|
|
jpayne@68
|
8066 '\n'
|
|
jpayne@68
|
8067 ' The default implementation defined by the built-in type '
|
|
jpayne@68
|
8068 '"object"\n'
|
|
jpayne@68
|
8069 ' calls "object.__repr__()".\n'
|
|
jpayne@68
|
8070 '\n'
|
|
jpayne@68
|
8071 'object.__bytes__(self)\n'
|
|
jpayne@68
|
8072 '\n'
|
|
jpayne@68
|
8073 ' Called by bytes to compute a byte-string representation '
|
|
jpayne@68
|
8074 'of an\n'
|
|
jpayne@68
|
8075 ' object. This should return a "bytes" object.\n'
|
|
jpayne@68
|
8076 '\n'
|
|
jpayne@68
|
8077 'object.__format__(self, format_spec)\n'
|
|
jpayne@68
|
8078 '\n'
|
|
jpayne@68
|
8079 ' Called by the "format()" built-in function, and by '
|
|
jpayne@68
|
8080 'extension,\n'
|
|
jpayne@68
|
8081 ' evaluation of formatted string literals and the '
|
|
jpayne@68
|
8082 '"str.format()"\n'
|
|
jpayne@68
|
8083 ' method, to produce a “formatted” string representation of '
|
|
jpayne@68
|
8084 'an\n'
|
|
jpayne@68
|
8085 ' object. The *format_spec* argument is a string that '
|
|
jpayne@68
|
8086 'contains a\n'
|
|
jpayne@68
|
8087 ' description of the formatting options desired. The '
|
|
jpayne@68
|
8088 'interpretation\n'
|
|
jpayne@68
|
8089 ' of the *format_spec* argument is up to the type '
|
|
jpayne@68
|
8090 'implementing\n'
|
|
jpayne@68
|
8091 ' "__format__()", however most classes will either '
|
|
jpayne@68
|
8092 'delegate\n'
|
|
jpayne@68
|
8093 ' formatting to one of the built-in types, or use a '
|
|
jpayne@68
|
8094 'similar\n'
|
|
jpayne@68
|
8095 ' formatting option syntax.\n'
|
|
jpayne@68
|
8096 '\n'
|
|
jpayne@68
|
8097 ' See Format Specification Mini-Language for a description '
|
|
jpayne@68
|
8098 'of the\n'
|
|
jpayne@68
|
8099 ' standard formatting syntax.\n'
|
|
jpayne@68
|
8100 '\n'
|
|
jpayne@68
|
8101 ' The return value must be a string object.\n'
|
|
jpayne@68
|
8102 '\n'
|
|
jpayne@68
|
8103 ' Changed in version 3.4: The __format__ method of "object" '
|
|
jpayne@68
|
8104 'itself\n'
|
|
jpayne@68
|
8105 ' raises a "TypeError" if passed any non-empty string.\n'
|
|
jpayne@68
|
8106 '\n'
|
|
jpayne@68
|
8107 ' Changed in version 3.7: "object.__format__(x, \'\')" is '
|
|
jpayne@68
|
8108 'now\n'
|
|
jpayne@68
|
8109 ' equivalent to "str(x)" rather than "format(str(self), '
|
|
jpayne@68
|
8110 '\'\')".\n'
|
|
jpayne@68
|
8111 '\n'
|
|
jpayne@68
|
8112 'object.__lt__(self, other)\n'
|
|
jpayne@68
|
8113 'object.__le__(self, other)\n'
|
|
jpayne@68
|
8114 'object.__eq__(self, other)\n'
|
|
jpayne@68
|
8115 'object.__ne__(self, other)\n'
|
|
jpayne@68
|
8116 'object.__gt__(self, other)\n'
|
|
jpayne@68
|
8117 'object.__ge__(self, other)\n'
|
|
jpayne@68
|
8118 '\n'
|
|
jpayne@68
|
8119 ' These are the so-called “rich comparison” methods. The\n'
|
|
jpayne@68
|
8120 ' correspondence between operator symbols and method names '
|
|
jpayne@68
|
8121 'is as\n'
|
|
jpayne@68
|
8122 ' follows: "x<y" calls "x.__lt__(y)", "x<=y" calls '
|
|
jpayne@68
|
8123 '"x.__le__(y)",\n'
|
|
jpayne@68
|
8124 ' "x==y" calls "x.__eq__(y)", "x!=y" calls "x.__ne__(y)", '
|
|
jpayne@68
|
8125 '"x>y" calls\n'
|
|
jpayne@68
|
8126 ' "x.__gt__(y)", and "x>=y" calls "x.__ge__(y)".\n'
|
|
jpayne@68
|
8127 '\n'
|
|
jpayne@68
|
8128 ' A rich comparison method may return the singleton '
|
|
jpayne@68
|
8129 '"NotImplemented"\n'
|
|
jpayne@68
|
8130 ' if it does not implement the operation for a given pair '
|
|
jpayne@68
|
8131 'of\n'
|
|
jpayne@68
|
8132 ' arguments. By convention, "False" and "True" are returned '
|
|
jpayne@68
|
8133 'for a\n'
|
|
jpayne@68
|
8134 ' successful comparison. However, these methods can return '
|
|
jpayne@68
|
8135 'any value,\n'
|
|
jpayne@68
|
8136 ' so if the comparison operator is used in a Boolean '
|
|
jpayne@68
|
8137 'context (e.g.,\n'
|
|
jpayne@68
|
8138 ' in the condition of an "if" statement), Python will call '
|
|
jpayne@68
|
8139 '"bool()"\n'
|
|
jpayne@68
|
8140 ' on the value to determine if the result is true or '
|
|
jpayne@68
|
8141 'false.\n'
|
|
jpayne@68
|
8142 '\n'
|
|
jpayne@68
|
8143 ' By default, "__ne__()" delegates to "__eq__()" and '
|
|
jpayne@68
|
8144 'inverts the\n'
|
|
jpayne@68
|
8145 ' result unless it is "NotImplemented". There are no other '
|
|
jpayne@68
|
8146 'implied\n'
|
|
jpayne@68
|
8147 ' relationships among the comparison operators, for '
|
|
jpayne@68
|
8148 'example, the\n'
|
|
jpayne@68
|
8149 ' truth of "(x<y or x==y)" does not imply "x<=y". To '
|
|
jpayne@68
|
8150 'automatically\n'
|
|
jpayne@68
|
8151 ' generate ordering operations from a single root '
|
|
jpayne@68
|
8152 'operation, see\n'
|
|
jpayne@68
|
8153 ' "functools.total_ordering()".\n'
|
|
jpayne@68
|
8154 '\n'
|
|
jpayne@68
|
8155 ' See the paragraph on "__hash__()" for some important '
|
|
jpayne@68
|
8156 'notes on\n'
|
|
jpayne@68
|
8157 ' creating *hashable* objects which support custom '
|
|
jpayne@68
|
8158 'comparison\n'
|
|
jpayne@68
|
8159 ' operations and are usable as dictionary keys.\n'
|
|
jpayne@68
|
8160 '\n'
|
|
jpayne@68
|
8161 ' There are no swapped-argument versions of these methods '
|
|
jpayne@68
|
8162 '(to be used\n'
|
|
jpayne@68
|
8163 ' when the left argument does not support the operation but '
|
|
jpayne@68
|
8164 'the right\n'
|
|
jpayne@68
|
8165 ' argument does); rather, "__lt__()" and "__gt__()" are '
|
|
jpayne@68
|
8166 'each other’s\n'
|
|
jpayne@68
|
8167 ' reflection, "__le__()" and "__ge__()" are each other’s '
|
|
jpayne@68
|
8168 'reflection,\n'
|
|
jpayne@68
|
8169 ' and "__eq__()" and "__ne__()" are their own reflection. '
|
|
jpayne@68
|
8170 'If the\n'
|
|
jpayne@68
|
8171 ' operands are of different types, and right operand’s type '
|
|
jpayne@68
|
8172 'is a\n'
|
|
jpayne@68
|
8173 ' direct or indirect subclass of the left operand’s type, '
|
|
jpayne@68
|
8174 'the\n'
|
|
jpayne@68
|
8175 ' reflected method of the right operand has priority, '
|
|
jpayne@68
|
8176 'otherwise the\n'
|
|
jpayne@68
|
8177 ' left operand’s method has priority. Virtual subclassing '
|
|
jpayne@68
|
8178 'is not\n'
|
|
jpayne@68
|
8179 ' considered.\n'
|
|
jpayne@68
|
8180 '\n'
|
|
jpayne@68
|
8181 'object.__hash__(self)\n'
|
|
jpayne@68
|
8182 '\n'
|
|
jpayne@68
|
8183 ' Called by built-in function "hash()" and for operations '
|
|
jpayne@68
|
8184 'on members\n'
|
|
jpayne@68
|
8185 ' of hashed collections including "set", "frozenset", and '
|
|
jpayne@68
|
8186 '"dict".\n'
|
|
jpayne@68
|
8187 ' "__hash__()" should return an integer. The only required '
|
|
jpayne@68
|
8188 'property\n'
|
|
jpayne@68
|
8189 ' is that objects which compare equal have the same hash '
|
|
jpayne@68
|
8190 'value; it is\n'
|
|
jpayne@68
|
8191 ' advised to mix together the hash values of the components '
|
|
jpayne@68
|
8192 'of the\n'
|
|
jpayne@68
|
8193 ' object that also play a part in comparison of objects by '
|
|
jpayne@68
|
8194 'packing\n'
|
|
jpayne@68
|
8195 ' them into a tuple and hashing the tuple. Example:\n'
|
|
jpayne@68
|
8196 '\n'
|
|
jpayne@68
|
8197 ' def __hash__(self):\n'
|
|
jpayne@68
|
8198 ' return hash((self.name, self.nick, self.color))\n'
|
|
jpayne@68
|
8199 '\n'
|
|
jpayne@68
|
8200 ' Note: "hash()" truncates the value returned from an '
|
|
jpayne@68
|
8201 'object’s\n'
|
|
jpayne@68
|
8202 ' custom "__hash__()" method to the size of a '
|
|
jpayne@68
|
8203 '"Py_ssize_t". This\n'
|
|
jpayne@68
|
8204 ' is typically 8 bytes on 64-bit builds and 4 bytes on '
|
|
jpayne@68
|
8205 '32-bit\n'
|
|
jpayne@68
|
8206 ' builds. If an object’s "__hash__()" must interoperate '
|
|
jpayne@68
|
8207 'on builds\n'
|
|
jpayne@68
|
8208 ' of different bit sizes, be sure to check the width on '
|
|
jpayne@68
|
8209 'all\n'
|
|
jpayne@68
|
8210 ' supported builds. An easy way to do this is with '
|
|
jpayne@68
|
8211 '"python -c\n'
|
|
jpayne@68
|
8212 ' "import sys; print(sys.hash_info.width)"".\n'
|
|
jpayne@68
|
8213 '\n'
|
|
jpayne@68
|
8214 ' If a class does not define an "__eq__()" method it should '
|
|
jpayne@68
|
8215 'not\n'
|
|
jpayne@68
|
8216 ' define a "__hash__()" operation either; if it defines '
|
|
jpayne@68
|
8217 '"__eq__()"\n'
|
|
jpayne@68
|
8218 ' but not "__hash__()", its instances will not be usable as '
|
|
jpayne@68
|
8219 'items in\n'
|
|
jpayne@68
|
8220 ' hashable collections. If a class defines mutable objects '
|
|
jpayne@68
|
8221 'and\n'
|
|
jpayne@68
|
8222 ' implements an "__eq__()" method, it should not implement\n'
|
|
jpayne@68
|
8223 ' "__hash__()", since the implementation of hashable '
|
|
jpayne@68
|
8224 'collections\n'
|
|
jpayne@68
|
8225 ' requires that a key’s hash value is immutable (if the '
|
|
jpayne@68
|
8226 'object’s hash\n'
|
|
jpayne@68
|
8227 ' value changes, it will be in the wrong hash bucket).\n'
|
|
jpayne@68
|
8228 '\n'
|
|
jpayne@68
|
8229 ' User-defined classes have "__eq__()" and "__hash__()" '
|
|
jpayne@68
|
8230 'methods by\n'
|
|
jpayne@68
|
8231 ' default; with them, all objects compare unequal (except '
|
|
jpayne@68
|
8232 'with\n'
|
|
jpayne@68
|
8233 ' themselves) and "x.__hash__()" returns an appropriate '
|
|
jpayne@68
|
8234 'value such\n'
|
|
jpayne@68
|
8235 ' that "x == y" implies both that "x is y" and "hash(x) == '
|
|
jpayne@68
|
8236 'hash(y)".\n'
|
|
jpayne@68
|
8237 '\n'
|
|
jpayne@68
|
8238 ' A class that overrides "__eq__()" and does not define '
|
|
jpayne@68
|
8239 '"__hash__()"\n'
|
|
jpayne@68
|
8240 ' will have its "__hash__()" implicitly set to "None". '
|
|
jpayne@68
|
8241 'When the\n'
|
|
jpayne@68
|
8242 ' "__hash__()" method of a class is "None", instances of '
|
|
jpayne@68
|
8243 'the class\n'
|
|
jpayne@68
|
8244 ' will raise an appropriate "TypeError" when a program '
|
|
jpayne@68
|
8245 'attempts to\n'
|
|
jpayne@68
|
8246 ' retrieve their hash value, and will also be correctly '
|
|
jpayne@68
|
8247 'identified as\n'
|
|
jpayne@68
|
8248 ' unhashable when checking "isinstance(obj,\n'
|
|
jpayne@68
|
8249 ' collections.abc.Hashable)".\n'
|
|
jpayne@68
|
8250 '\n'
|
|
jpayne@68
|
8251 ' If a class that overrides "__eq__()" needs to retain the\n'
|
|
jpayne@68
|
8252 ' implementation of "__hash__()" from a parent class, the '
|
|
jpayne@68
|
8253 'interpreter\n'
|
|
jpayne@68
|
8254 ' must be told this explicitly by setting "__hash__ =\n'
|
|
jpayne@68
|
8255 ' <ParentClass>.__hash__".\n'
|
|
jpayne@68
|
8256 '\n'
|
|
jpayne@68
|
8257 ' If a class that does not override "__eq__()" wishes to '
|
|
jpayne@68
|
8258 'suppress\n'
|
|
jpayne@68
|
8259 ' hash support, it should include "__hash__ = None" in the '
|
|
jpayne@68
|
8260 'class\n'
|
|
jpayne@68
|
8261 ' definition. A class which defines its own "__hash__()" '
|
|
jpayne@68
|
8262 'that\n'
|
|
jpayne@68
|
8263 ' explicitly raises a "TypeError" would be incorrectly '
|
|
jpayne@68
|
8264 'identified as\n'
|
|
jpayne@68
|
8265 ' hashable by an "isinstance(obj, '
|
|
jpayne@68
|
8266 'collections.abc.Hashable)" call.\n'
|
|
jpayne@68
|
8267 '\n'
|
|
jpayne@68
|
8268 ' Note: By default, the "__hash__()" values of str and '
|
|
jpayne@68
|
8269 'bytes\n'
|
|
jpayne@68
|
8270 ' objects are “salted” with an unpredictable random '
|
|
jpayne@68
|
8271 'value.\n'
|
|
jpayne@68
|
8272 ' Although they remain constant within an individual '
|
|
jpayne@68
|
8273 'Python\n'
|
|
jpayne@68
|
8274 ' process, they are not predictable between repeated '
|
|
jpayne@68
|
8275 'invocations of\n'
|
|
jpayne@68
|
8276 ' Python.This is intended to provide protection against a '
|
|
jpayne@68
|
8277 'denial-\n'
|
|
jpayne@68
|
8278 ' of-service caused by carefully-chosen inputs that '
|
|
jpayne@68
|
8279 'exploit the\n'
|
|
jpayne@68
|
8280 ' worst case performance of a dict insertion, O(n^2) '
|
|
jpayne@68
|
8281 'complexity.\n'
|
|
jpayne@68
|
8282 ' See http://www.ocert.org/advisories/ocert-2011-003.html '
|
|
jpayne@68
|
8283 'for\n'
|
|
jpayne@68
|
8284 ' details.Changing hash values affects the iteration '
|
|
jpayne@68
|
8285 'order of sets.\n'
|
|
jpayne@68
|
8286 ' Python has never made guarantees about this ordering '
|
|
jpayne@68
|
8287 '(and it\n'
|
|
jpayne@68
|
8288 ' typically varies between 32-bit and 64-bit builds).See '
|
|
jpayne@68
|
8289 'also\n'
|
|
jpayne@68
|
8290 ' "PYTHONHASHSEED".\n'
|
|
jpayne@68
|
8291 '\n'
|
|
jpayne@68
|
8292 ' Changed in version 3.3: Hash randomization is enabled by '
|
|
jpayne@68
|
8293 'default.\n'
|
|
jpayne@68
|
8294 '\n'
|
|
jpayne@68
|
8295 'object.__bool__(self)\n'
|
|
jpayne@68
|
8296 '\n'
|
|
jpayne@68
|
8297 ' Called to implement truth value testing and the built-in '
|
|
jpayne@68
|
8298 'operation\n'
|
|
jpayne@68
|
8299 ' "bool()"; should return "False" or "True". When this '
|
|
jpayne@68
|
8300 'method is not\n'
|
|
jpayne@68
|
8301 ' defined, "__len__()" is called, if it is defined, and the '
|
|
jpayne@68
|
8302 'object is\n'
|
|
jpayne@68
|
8303 ' considered true if its result is nonzero. If a class '
|
|
jpayne@68
|
8304 'defines\n'
|
|
jpayne@68
|
8305 ' neither "__len__()" nor "__bool__()", all its instances '
|
|
jpayne@68
|
8306 'are\n'
|
|
jpayne@68
|
8307 ' considered true.\n'
|
|
jpayne@68
|
8308 '\n'
|
|
jpayne@68
|
8309 '\n'
|
|
jpayne@68
|
8310 'Customizing attribute access\n'
|
|
jpayne@68
|
8311 '============================\n'
|
|
jpayne@68
|
8312 '\n'
|
|
jpayne@68
|
8313 'The following methods can be defined to customize the '
|
|
jpayne@68
|
8314 'meaning of\n'
|
|
jpayne@68
|
8315 'attribute access (use of, assignment to, or deletion of '
|
|
jpayne@68
|
8316 '"x.name") for\n'
|
|
jpayne@68
|
8317 'class instances.\n'
|
|
jpayne@68
|
8318 '\n'
|
|
jpayne@68
|
8319 'object.__getattr__(self, name)\n'
|
|
jpayne@68
|
8320 '\n'
|
|
jpayne@68
|
8321 ' Called when the default attribute access fails with an\n'
|
|
jpayne@68
|
8322 ' "AttributeError" (either "__getattribute__()" raises an\n'
|
|
jpayne@68
|
8323 ' "AttributeError" because *name* is not an instance '
|
|
jpayne@68
|
8324 'attribute or an\n'
|
|
jpayne@68
|
8325 ' attribute in the class tree for "self"; or "__get__()" of '
|
|
jpayne@68
|
8326 'a *name*\n'
|
|
jpayne@68
|
8327 ' property raises "AttributeError"). This method should '
|
|
jpayne@68
|
8328 'either\n'
|
|
jpayne@68
|
8329 ' return the (computed) attribute value or raise an '
|
|
jpayne@68
|
8330 '"AttributeError"\n'
|
|
jpayne@68
|
8331 ' exception.\n'
|
|
jpayne@68
|
8332 '\n'
|
|
jpayne@68
|
8333 ' Note that if the attribute is found through the normal '
|
|
jpayne@68
|
8334 'mechanism,\n'
|
|
jpayne@68
|
8335 ' "__getattr__()" is not called. (This is an intentional '
|
|
jpayne@68
|
8336 'asymmetry\n'
|
|
jpayne@68
|
8337 ' between "__getattr__()" and "__setattr__()".) This is '
|
|
jpayne@68
|
8338 'done both for\n'
|
|
jpayne@68
|
8339 ' efficiency reasons and because otherwise "__getattr__()" '
|
|
jpayne@68
|
8340 'would have\n'
|
|
jpayne@68
|
8341 ' no way to access other attributes of the instance. Note '
|
|
jpayne@68
|
8342 'that at\n'
|
|
jpayne@68
|
8343 ' least for instance variables, you can fake total control '
|
|
jpayne@68
|
8344 'by not\n'
|
|
jpayne@68
|
8345 ' inserting any values in the instance attribute dictionary '
|
|
jpayne@68
|
8346 '(but\n'
|
|
jpayne@68
|
8347 ' instead inserting them in another object). See the\n'
|
|
jpayne@68
|
8348 ' "__getattribute__()" method below for a way to actually '
|
|
jpayne@68
|
8349 'get total\n'
|
|
jpayne@68
|
8350 ' control over attribute access.\n'
|
|
jpayne@68
|
8351 '\n'
|
|
jpayne@68
|
8352 'object.__getattribute__(self, name)\n'
|
|
jpayne@68
|
8353 '\n'
|
|
jpayne@68
|
8354 ' Called unconditionally to implement attribute accesses '
|
|
jpayne@68
|
8355 'for\n'
|
|
jpayne@68
|
8356 ' instances of the class. If the class also defines '
|
|
jpayne@68
|
8357 '"__getattr__()",\n'
|
|
jpayne@68
|
8358 ' the latter will not be called unless "__getattribute__()" '
|
|
jpayne@68
|
8359 'either\n'
|
|
jpayne@68
|
8360 ' calls it explicitly or raises an "AttributeError". This '
|
|
jpayne@68
|
8361 'method\n'
|
|
jpayne@68
|
8362 ' should return the (computed) attribute value or raise an\n'
|
|
jpayne@68
|
8363 ' "AttributeError" exception. In order to avoid infinite '
|
|
jpayne@68
|
8364 'recursion in\n'
|
|
jpayne@68
|
8365 ' this method, its implementation should always call the '
|
|
jpayne@68
|
8366 'base class\n'
|
|
jpayne@68
|
8367 ' method with the same name to access any attributes it '
|
|
jpayne@68
|
8368 'needs, for\n'
|
|
jpayne@68
|
8369 ' example, "object.__getattribute__(self, name)".\n'
|
|
jpayne@68
|
8370 '\n'
|
|
jpayne@68
|
8371 ' Note: This method may still be bypassed when looking up '
|
|
jpayne@68
|
8372 'special\n'
|
|
jpayne@68
|
8373 ' methods as the result of implicit invocation via '
|
|
jpayne@68
|
8374 'language syntax\n'
|
|
jpayne@68
|
8375 ' or built-in functions. See Special method lookup.\n'
|
|
jpayne@68
|
8376 '\n'
|
|
jpayne@68
|
8377 'object.__setattr__(self, name, value)\n'
|
|
jpayne@68
|
8378 '\n'
|
|
jpayne@68
|
8379 ' Called when an attribute assignment is attempted. This '
|
|
jpayne@68
|
8380 'is called\n'
|
|
jpayne@68
|
8381 ' instead of the normal mechanism (i.e. store the value in '
|
|
jpayne@68
|
8382 'the\n'
|
|
jpayne@68
|
8383 ' instance dictionary). *name* is the attribute name, '
|
|
jpayne@68
|
8384 '*value* is the\n'
|
|
jpayne@68
|
8385 ' value to be assigned to it.\n'
|
|
jpayne@68
|
8386 '\n'
|
|
jpayne@68
|
8387 ' If "__setattr__()" wants to assign to an instance '
|
|
jpayne@68
|
8388 'attribute, it\n'
|
|
jpayne@68
|
8389 ' should call the base class method with the same name, for '
|
|
jpayne@68
|
8390 'example,\n'
|
|
jpayne@68
|
8391 ' "object.__setattr__(self, name, value)".\n'
|
|
jpayne@68
|
8392 '\n'
|
|
jpayne@68
|
8393 'object.__delattr__(self, name)\n'
|
|
jpayne@68
|
8394 '\n'
|
|
jpayne@68
|
8395 ' Like "__setattr__()" but for attribute deletion instead '
|
|
jpayne@68
|
8396 'of\n'
|
|
jpayne@68
|
8397 ' assignment. This should only be implemented if "del '
|
|
jpayne@68
|
8398 'obj.name" is\n'
|
|
jpayne@68
|
8399 ' meaningful for the object.\n'
|
|
jpayne@68
|
8400 '\n'
|
|
jpayne@68
|
8401 'object.__dir__(self)\n'
|
|
jpayne@68
|
8402 '\n'
|
|
jpayne@68
|
8403 ' Called when "dir()" is called on the object. A sequence '
|
|
jpayne@68
|
8404 'must be\n'
|
|
jpayne@68
|
8405 ' returned. "dir()" converts the returned sequence to a '
|
|
jpayne@68
|
8406 'list and\n'
|
|
jpayne@68
|
8407 ' sorts it.\n'
|
|
jpayne@68
|
8408 '\n'
|
|
jpayne@68
|
8409 '\n'
|
|
jpayne@68
|
8410 'Customizing module attribute access\n'
|
|
jpayne@68
|
8411 '-----------------------------------\n'
|
|
jpayne@68
|
8412 '\n'
|
|
jpayne@68
|
8413 'Special names "__getattr__" and "__dir__" can be also used '
|
|
jpayne@68
|
8414 'to\n'
|
|
jpayne@68
|
8415 'customize access to module attributes. The "__getattr__" '
|
|
jpayne@68
|
8416 'function at\n'
|
|
jpayne@68
|
8417 'the module level should accept one argument which is the '
|
|
jpayne@68
|
8418 'name of an\n'
|
|
jpayne@68
|
8419 'attribute and return the computed value or raise an '
|
|
jpayne@68
|
8420 '"AttributeError".\n'
|
|
jpayne@68
|
8421 'If an attribute is not found on a module object through the '
|
|
jpayne@68
|
8422 'normal\n'
|
|
jpayne@68
|
8423 'lookup, i.e. "object.__getattribute__()", then "__getattr__" '
|
|
jpayne@68
|
8424 'is\n'
|
|
jpayne@68
|
8425 'searched in the module "__dict__" before raising an '
|
|
jpayne@68
|
8426 '"AttributeError".\n'
|
|
jpayne@68
|
8427 'If found, it is called with the attribute name and the '
|
|
jpayne@68
|
8428 'result is\n'
|
|
jpayne@68
|
8429 'returned.\n'
|
|
jpayne@68
|
8430 '\n'
|
|
jpayne@68
|
8431 'The "__dir__" function should accept no arguments, and '
|
|
jpayne@68
|
8432 'return a\n'
|
|
jpayne@68
|
8433 'sequence of strings that represents the names accessible on '
|
|
jpayne@68
|
8434 'module. If\n'
|
|
jpayne@68
|
8435 'present, this function overrides the standard "dir()" search '
|
|
jpayne@68
|
8436 'on a\n'
|
|
jpayne@68
|
8437 'module.\n'
|
|
jpayne@68
|
8438 '\n'
|
|
jpayne@68
|
8439 'For a more fine grained customization of the module behavior '
|
|
jpayne@68
|
8440 '(setting\n'
|
|
jpayne@68
|
8441 'attributes, properties, etc.), one can set the "__class__" '
|
|
jpayne@68
|
8442 'attribute\n'
|
|
jpayne@68
|
8443 'of a module object to a subclass of "types.ModuleType". For '
|
|
jpayne@68
|
8444 'example:\n'
|
|
jpayne@68
|
8445 '\n'
|
|
jpayne@68
|
8446 ' import sys\n'
|
|
jpayne@68
|
8447 ' from types import ModuleType\n'
|
|
jpayne@68
|
8448 '\n'
|
|
jpayne@68
|
8449 ' class VerboseModule(ModuleType):\n'
|
|
jpayne@68
|
8450 ' def __repr__(self):\n'
|
|
jpayne@68
|
8451 " return f'Verbose {self.__name__}'\n"
|
|
jpayne@68
|
8452 '\n'
|
|
jpayne@68
|
8453 ' def __setattr__(self, attr, value):\n'
|
|
jpayne@68
|
8454 " print(f'Setting {attr}...')\n"
|
|
jpayne@68
|
8455 ' super().__setattr__(attr, value)\n'
|
|
jpayne@68
|
8456 '\n'
|
|
jpayne@68
|
8457 ' sys.modules[__name__].__class__ = VerboseModule\n'
|
|
jpayne@68
|
8458 '\n'
|
|
jpayne@68
|
8459 'Note: Defining module "__getattr__" and setting module '
|
|
jpayne@68
|
8460 '"__class__"\n'
|
|
jpayne@68
|
8461 ' only affect lookups made using the attribute access syntax '
|
|
jpayne@68
|
8462 '–\n'
|
|
jpayne@68
|
8463 ' directly accessing the module globals (whether by code '
|
|
jpayne@68
|
8464 'within the\n'
|
|
jpayne@68
|
8465 ' module, or via a reference to the module’s globals '
|
|
jpayne@68
|
8466 'dictionary) is\n'
|
|
jpayne@68
|
8467 ' unaffected.\n'
|
|
jpayne@68
|
8468 '\n'
|
|
jpayne@68
|
8469 'Changed in version 3.5: "__class__" module attribute is now '
|
|
jpayne@68
|
8470 'writable.\n'
|
|
jpayne@68
|
8471 '\n'
|
|
jpayne@68
|
8472 'New in version 3.7: "__getattr__" and "__dir__" module '
|
|
jpayne@68
|
8473 'attributes.\n'
|
|
jpayne@68
|
8474 '\n'
|
|
jpayne@68
|
8475 'See also:\n'
|
|
jpayne@68
|
8476 '\n'
|
|
jpayne@68
|
8477 ' **PEP 562** - Module __getattr__ and __dir__\n'
|
|
jpayne@68
|
8478 ' Describes the "__getattr__" and "__dir__" functions on '
|
|
jpayne@68
|
8479 'modules.\n'
|
|
jpayne@68
|
8480 '\n'
|
|
jpayne@68
|
8481 '\n'
|
|
jpayne@68
|
8482 'Implementing Descriptors\n'
|
|
jpayne@68
|
8483 '------------------------\n'
|
|
jpayne@68
|
8484 '\n'
|
|
jpayne@68
|
8485 'The following methods only apply when an instance of the '
|
|
jpayne@68
|
8486 'class\n'
|
|
jpayne@68
|
8487 'containing the method (a so-called *descriptor* class) '
|
|
jpayne@68
|
8488 'appears in an\n'
|
|
jpayne@68
|
8489 '*owner* class (the descriptor must be in either the owner’s '
|
|
jpayne@68
|
8490 'class\n'
|
|
jpayne@68
|
8491 'dictionary or in the class dictionary for one of its '
|
|
jpayne@68
|
8492 'parents). In the\n'
|
|
jpayne@68
|
8493 'examples below, “the attribute” refers to the attribute '
|
|
jpayne@68
|
8494 'whose name is\n'
|
|
jpayne@68
|
8495 'the key of the property in the owner class’ "__dict__".\n'
|
|
jpayne@68
|
8496 '\n'
|
|
jpayne@68
|
8497 'object.__get__(self, instance, owner=None)\n'
|
|
jpayne@68
|
8498 '\n'
|
|
jpayne@68
|
8499 ' Called to get the attribute of the owner class (class '
|
|
jpayne@68
|
8500 'attribute\n'
|
|
jpayne@68
|
8501 ' access) or of an instance of that class (instance '
|
|
jpayne@68
|
8502 'attribute\n'
|
|
jpayne@68
|
8503 ' access). The optional *owner* argument is the owner '
|
|
jpayne@68
|
8504 'class, while\n'
|
|
jpayne@68
|
8505 ' *instance* is the instance that the attribute was '
|
|
jpayne@68
|
8506 'accessed through,\n'
|
|
jpayne@68
|
8507 ' or "None" when the attribute is accessed through the '
|
|
jpayne@68
|
8508 '*owner*.\n'
|
|
jpayne@68
|
8509 '\n'
|
|
jpayne@68
|
8510 ' This method should return the computed attribute value or '
|
|
jpayne@68
|
8511 'raise an\n'
|
|
jpayne@68
|
8512 ' "AttributeError" exception.\n'
|
|
jpayne@68
|
8513 '\n'
|
|
jpayne@68
|
8514 ' **PEP 252** specifies that "__get__()" is callable with '
|
|
jpayne@68
|
8515 'one or two\n'
|
|
jpayne@68
|
8516 ' arguments. Python’s own built-in descriptors support '
|
|
jpayne@68
|
8517 'this\n'
|
|
jpayne@68
|
8518 ' specification; however, it is likely that some '
|
|
jpayne@68
|
8519 'third-party tools\n'
|
|
jpayne@68
|
8520 ' have descriptors that require both arguments. Python’s '
|
|
jpayne@68
|
8521 'own\n'
|
|
jpayne@68
|
8522 ' "__getattribute__()" implementation always passes in both '
|
|
jpayne@68
|
8523 'arguments\n'
|
|
jpayne@68
|
8524 ' whether they are required or not.\n'
|
|
jpayne@68
|
8525 '\n'
|
|
jpayne@68
|
8526 'object.__set__(self, instance, value)\n'
|
|
jpayne@68
|
8527 '\n'
|
|
jpayne@68
|
8528 ' Called to set the attribute on an instance *instance* of '
|
|
jpayne@68
|
8529 'the owner\n'
|
|
jpayne@68
|
8530 ' class to a new value, *value*.\n'
|
|
jpayne@68
|
8531 '\n'
|
|
jpayne@68
|
8532 ' Note, adding "__set__()" or "__delete__()" changes the '
|
|
jpayne@68
|
8533 'kind of\n'
|
|
jpayne@68
|
8534 ' descriptor to a “data descriptor”. See Invoking '
|
|
jpayne@68
|
8535 'Descriptors for\n'
|
|
jpayne@68
|
8536 ' more details.\n'
|
|
jpayne@68
|
8537 '\n'
|
|
jpayne@68
|
8538 'object.__delete__(self, instance)\n'
|
|
jpayne@68
|
8539 '\n'
|
|
jpayne@68
|
8540 ' Called to delete the attribute on an instance *instance* '
|
|
jpayne@68
|
8541 'of the\n'
|
|
jpayne@68
|
8542 ' owner class.\n'
|
|
jpayne@68
|
8543 '\n'
|
|
jpayne@68
|
8544 'object.__set_name__(self, owner, name)\n'
|
|
jpayne@68
|
8545 '\n'
|
|
jpayne@68
|
8546 ' Called at the time the owning class *owner* is created. '
|
|
jpayne@68
|
8547 'The\n'
|
|
jpayne@68
|
8548 ' descriptor has been assigned to *name*.\n'
|
|
jpayne@68
|
8549 '\n'
|
|
jpayne@68
|
8550 ' Note: "__set_name__()" is only called implicitly as part '
|
|
jpayne@68
|
8551 'of the\n'
|
|
jpayne@68
|
8552 ' "type" constructor, so it will need to be called '
|
|
jpayne@68
|
8553 'explicitly with\n'
|
|
jpayne@68
|
8554 ' the appropriate parameters when a descriptor is added '
|
|
jpayne@68
|
8555 'to a class\n'
|
|
jpayne@68
|
8556 ' after initial creation:\n'
|
|
jpayne@68
|
8557 '\n'
|
|
jpayne@68
|
8558 ' class A:\n'
|
|
jpayne@68
|
8559 ' pass\n'
|
|
jpayne@68
|
8560 ' descr = custom_descriptor()\n'
|
|
jpayne@68
|
8561 ' A.attr = descr\n'
|
|
jpayne@68
|
8562 " descr.__set_name__(A, 'attr')\n"
|
|
jpayne@68
|
8563 '\n'
|
|
jpayne@68
|
8564 ' See Creating the class object for more details.\n'
|
|
jpayne@68
|
8565 '\n'
|
|
jpayne@68
|
8566 ' New in version 3.6.\n'
|
|
jpayne@68
|
8567 '\n'
|
|
jpayne@68
|
8568 'The attribute "__objclass__" is interpreted by the "inspect" '
|
|
jpayne@68
|
8569 'module as\n'
|
|
jpayne@68
|
8570 'specifying the class where this object was defined (setting '
|
|
jpayne@68
|
8571 'this\n'
|
|
jpayne@68
|
8572 'appropriately can assist in runtime introspection of dynamic '
|
|
jpayne@68
|
8573 'class\n'
|
|
jpayne@68
|
8574 'attributes). For callables, it may indicate that an instance '
|
|
jpayne@68
|
8575 'of the\n'
|
|
jpayne@68
|
8576 'given type (or a subclass) is expected or required as the '
|
|
jpayne@68
|
8577 'first\n'
|
|
jpayne@68
|
8578 'positional argument (for example, CPython sets this '
|
|
jpayne@68
|
8579 'attribute for\n'
|
|
jpayne@68
|
8580 'unbound methods that are implemented in C).\n'
|
|
jpayne@68
|
8581 '\n'
|
|
jpayne@68
|
8582 '\n'
|
|
jpayne@68
|
8583 'Invoking Descriptors\n'
|
|
jpayne@68
|
8584 '--------------------\n'
|
|
jpayne@68
|
8585 '\n'
|
|
jpayne@68
|
8586 'In general, a descriptor is an object attribute with '
|
|
jpayne@68
|
8587 '“binding\n'
|
|
jpayne@68
|
8588 'behavior”, one whose attribute access has been overridden by '
|
|
jpayne@68
|
8589 'methods\n'
|
|
jpayne@68
|
8590 'in the descriptor protocol: "__get__()", "__set__()", and\n'
|
|
jpayne@68
|
8591 '"__delete__()". If any of those methods are defined for an '
|
|
jpayne@68
|
8592 'object, it\n'
|
|
jpayne@68
|
8593 'is said to be a descriptor.\n'
|
|
jpayne@68
|
8594 '\n'
|
|
jpayne@68
|
8595 'The default behavior for attribute access is to get, set, or '
|
|
jpayne@68
|
8596 'delete\n'
|
|
jpayne@68
|
8597 'the attribute from an object’s dictionary. For instance, '
|
|
jpayne@68
|
8598 '"a.x" has a\n'
|
|
jpayne@68
|
8599 'lookup chain starting with "a.__dict__[\'x\']", then\n'
|
|
jpayne@68
|
8600 '"type(a).__dict__[\'x\']", and continuing through the base '
|
|
jpayne@68
|
8601 'classes of\n'
|
|
jpayne@68
|
8602 '"type(a)" excluding metaclasses.\n'
|
|
jpayne@68
|
8603 '\n'
|
|
jpayne@68
|
8604 'However, if the looked-up value is an object defining one of '
|
|
jpayne@68
|
8605 'the\n'
|
|
jpayne@68
|
8606 'descriptor methods, then Python may override the default '
|
|
jpayne@68
|
8607 'behavior and\n'
|
|
jpayne@68
|
8608 'invoke the descriptor method instead. Where this occurs in '
|
|
jpayne@68
|
8609 'the\n'
|
|
jpayne@68
|
8610 'precedence chain depends on which descriptor methods were '
|
|
jpayne@68
|
8611 'defined and\n'
|
|
jpayne@68
|
8612 'how they were called.\n'
|
|
jpayne@68
|
8613 '\n'
|
|
jpayne@68
|
8614 'The starting point for descriptor invocation is a binding, '
|
|
jpayne@68
|
8615 '"a.x". How\n'
|
|
jpayne@68
|
8616 'the arguments are assembled depends on "a":\n'
|
|
jpayne@68
|
8617 '\n'
|
|
jpayne@68
|
8618 'Direct Call\n'
|
|
jpayne@68
|
8619 ' The simplest and least common call is when user code '
|
|
jpayne@68
|
8620 'directly\n'
|
|
jpayne@68
|
8621 ' invokes a descriptor method: "x.__get__(a)".\n'
|
|
jpayne@68
|
8622 '\n'
|
|
jpayne@68
|
8623 'Instance Binding\n'
|
|
jpayne@68
|
8624 ' If binding to an object instance, "a.x" is transformed '
|
|
jpayne@68
|
8625 'into the\n'
|
|
jpayne@68
|
8626 ' call: "type(a).__dict__[\'x\'].__get__(a, type(a))".\n'
|
|
jpayne@68
|
8627 '\n'
|
|
jpayne@68
|
8628 'Class Binding\n'
|
|
jpayne@68
|
8629 ' If binding to a class, "A.x" is transformed into the '
|
|
jpayne@68
|
8630 'call:\n'
|
|
jpayne@68
|
8631 ' "A.__dict__[\'x\'].__get__(None, A)".\n'
|
|
jpayne@68
|
8632 '\n'
|
|
jpayne@68
|
8633 'Super Binding\n'
|
|
jpayne@68
|
8634 ' If "a" is an instance of "super", then the binding '
|
|
jpayne@68
|
8635 '"super(B,\n'
|
|
jpayne@68
|
8636 ' obj).m()" searches "obj.__class__.__mro__" for the base '
|
|
jpayne@68
|
8637 'class "A"\n'
|
|
jpayne@68
|
8638 ' immediately preceding "B" and then invokes the descriptor '
|
|
jpayne@68
|
8639 'with the\n'
|
|
jpayne@68
|
8640 ' call: "A.__dict__[\'m\'].__get__(obj, obj.__class__)".\n'
|
|
jpayne@68
|
8641 '\n'
|
|
jpayne@68
|
8642 'For instance bindings, the precedence of descriptor '
|
|
jpayne@68
|
8643 'invocation depends\n'
|
|
jpayne@68
|
8644 'on the which descriptor methods are defined. A descriptor '
|
|
jpayne@68
|
8645 'can define\n'
|
|
jpayne@68
|
8646 'any combination of "__get__()", "__set__()" and '
|
|
jpayne@68
|
8647 '"__delete__()". If it\n'
|
|
jpayne@68
|
8648 'does not define "__get__()", then accessing the attribute '
|
|
jpayne@68
|
8649 'will return\n'
|
|
jpayne@68
|
8650 'the descriptor object itself unless there is a value in the '
|
|
jpayne@68
|
8651 'object’s\n'
|
|
jpayne@68
|
8652 'instance dictionary. If the descriptor defines "__set__()" '
|
|
jpayne@68
|
8653 'and/or\n'
|
|
jpayne@68
|
8654 '"__delete__()", it is a data descriptor; if it defines '
|
|
jpayne@68
|
8655 'neither, it is\n'
|
|
jpayne@68
|
8656 'a non-data descriptor. Normally, data descriptors define '
|
|
jpayne@68
|
8657 'both\n'
|
|
jpayne@68
|
8658 '"__get__()" and "__set__()", while non-data descriptors have '
|
|
jpayne@68
|
8659 'just the\n'
|
|
jpayne@68
|
8660 '"__get__()" method. Data descriptors with "__set__()" and '
|
|
jpayne@68
|
8661 '"__get__()"\n'
|
|
jpayne@68
|
8662 'defined always override a redefinition in an instance '
|
|
jpayne@68
|
8663 'dictionary. In\n'
|
|
jpayne@68
|
8664 'contrast, non-data descriptors can be overridden by '
|
|
jpayne@68
|
8665 'instances.\n'
|
|
jpayne@68
|
8666 '\n'
|
|
jpayne@68
|
8667 'Python methods (including "staticmethod()" and '
|
|
jpayne@68
|
8668 '"classmethod()") are\n'
|
|
jpayne@68
|
8669 'implemented as non-data descriptors. Accordingly, instances '
|
|
jpayne@68
|
8670 'can\n'
|
|
jpayne@68
|
8671 'redefine and override methods. This allows individual '
|
|
jpayne@68
|
8672 'instances to\n'
|
|
jpayne@68
|
8673 'acquire behaviors that differ from other instances of the '
|
|
jpayne@68
|
8674 'same class.\n'
|
|
jpayne@68
|
8675 '\n'
|
|
jpayne@68
|
8676 'The "property()" function is implemented as a data '
|
|
jpayne@68
|
8677 'descriptor.\n'
|
|
jpayne@68
|
8678 'Accordingly, instances cannot override the behavior of a '
|
|
jpayne@68
|
8679 'property.\n'
|
|
jpayne@68
|
8680 '\n'
|
|
jpayne@68
|
8681 '\n'
|
|
jpayne@68
|
8682 '__slots__\n'
|
|
jpayne@68
|
8683 '---------\n'
|
|
jpayne@68
|
8684 '\n'
|
|
jpayne@68
|
8685 '*__slots__* allow us to explicitly declare data members '
|
|
jpayne@68
|
8686 '(like\n'
|
|
jpayne@68
|
8687 'properties) and deny the creation of *__dict__* and '
|
|
jpayne@68
|
8688 '*__weakref__*\n'
|
|
jpayne@68
|
8689 '(unless explicitly declared in *__slots__* or available in a '
|
|
jpayne@68
|
8690 'parent.)\n'
|
|
jpayne@68
|
8691 '\n'
|
|
jpayne@68
|
8692 'The space saved over using *__dict__* can be significant. '
|
|
jpayne@68
|
8693 'Attribute\n'
|
|
jpayne@68
|
8694 'lookup speed can be significantly improved as well.\n'
|
|
jpayne@68
|
8695 '\n'
|
|
jpayne@68
|
8696 'object.__slots__\n'
|
|
jpayne@68
|
8697 '\n'
|
|
jpayne@68
|
8698 ' This class variable can be assigned a string, iterable, '
|
|
jpayne@68
|
8699 'or sequence\n'
|
|
jpayne@68
|
8700 ' of strings with variable names used by instances. '
|
|
jpayne@68
|
8701 '*__slots__*\n'
|
|
jpayne@68
|
8702 ' reserves space for the declared variables and prevents '
|
|
jpayne@68
|
8703 'the\n'
|
|
jpayne@68
|
8704 ' automatic creation of *__dict__* and *__weakref__* for '
|
|
jpayne@68
|
8705 'each\n'
|
|
jpayne@68
|
8706 ' instance.\n'
|
|
jpayne@68
|
8707 '\n'
|
|
jpayne@68
|
8708 '\n'
|
|
jpayne@68
|
8709 'Notes on using *__slots__*\n'
|
|
jpayne@68
|
8710 '~~~~~~~~~~~~~~~~~~~~~~~~~~\n'
|
|
jpayne@68
|
8711 '\n'
|
|
jpayne@68
|
8712 '* When inheriting from a class without *__slots__*, the '
|
|
jpayne@68
|
8713 '*__dict__*\n'
|
|
jpayne@68
|
8714 ' and *__weakref__* attribute of the instances will always '
|
|
jpayne@68
|
8715 'be\n'
|
|
jpayne@68
|
8716 ' accessible.\n'
|
|
jpayne@68
|
8717 '\n'
|
|
jpayne@68
|
8718 '* Without a *__dict__* variable, instances cannot be '
|
|
jpayne@68
|
8719 'assigned new\n'
|
|
jpayne@68
|
8720 ' variables not listed in the *__slots__* definition. '
|
|
jpayne@68
|
8721 'Attempts to\n'
|
|
jpayne@68
|
8722 ' assign to an unlisted variable name raises '
|
|
jpayne@68
|
8723 '"AttributeError". If\n'
|
|
jpayne@68
|
8724 ' dynamic assignment of new variables is desired, then add\n'
|
|
jpayne@68
|
8725 ' "\'__dict__\'" to the sequence of strings in the '
|
|
jpayne@68
|
8726 '*__slots__*\n'
|
|
jpayne@68
|
8727 ' declaration.\n'
|
|
jpayne@68
|
8728 '\n'
|
|
jpayne@68
|
8729 '* Without a *__weakref__* variable for each instance, '
|
|
jpayne@68
|
8730 'classes\n'
|
|
jpayne@68
|
8731 ' defining *__slots__* do not support weak references to '
|
|
jpayne@68
|
8732 'its\n'
|
|
jpayne@68
|
8733 ' instances. If weak reference support is needed, then add\n'
|
|
jpayne@68
|
8734 ' "\'__weakref__\'" to the sequence of strings in the '
|
|
jpayne@68
|
8735 '*__slots__*\n'
|
|
jpayne@68
|
8736 ' declaration.\n'
|
|
jpayne@68
|
8737 '\n'
|
|
jpayne@68
|
8738 '* *__slots__* are implemented at the class level by '
|
|
jpayne@68
|
8739 'creating\n'
|
|
jpayne@68
|
8740 ' descriptors (Implementing Descriptors) for each variable '
|
|
jpayne@68
|
8741 'name. As a\n'
|
|
jpayne@68
|
8742 ' result, class attributes cannot be used to set default '
|
|
jpayne@68
|
8743 'values for\n'
|
|
jpayne@68
|
8744 ' instance variables defined by *__slots__*; otherwise, the '
|
|
jpayne@68
|
8745 'class\n'
|
|
jpayne@68
|
8746 ' attribute would overwrite the descriptor assignment.\n'
|
|
jpayne@68
|
8747 '\n'
|
|
jpayne@68
|
8748 '* The action of a *__slots__* declaration is not limited to '
|
|
jpayne@68
|
8749 'the\n'
|
|
jpayne@68
|
8750 ' class where it is defined. *__slots__* declared in '
|
|
jpayne@68
|
8751 'parents are\n'
|
|
jpayne@68
|
8752 ' available in child classes. However, child subclasses will '
|
|
jpayne@68
|
8753 'get a\n'
|
|
jpayne@68
|
8754 ' *__dict__* and *__weakref__* unless they also define '
|
|
jpayne@68
|
8755 '*__slots__*\n'
|
|
jpayne@68
|
8756 ' (which should only contain names of any *additional* '
|
|
jpayne@68
|
8757 'slots).\n'
|
|
jpayne@68
|
8758 '\n'
|
|
jpayne@68
|
8759 '* If a class defines a slot also defined in a base class, '
|
|
jpayne@68
|
8760 'the\n'
|
|
jpayne@68
|
8761 ' instance variable defined by the base class slot is '
|
|
jpayne@68
|
8762 'inaccessible\n'
|
|
jpayne@68
|
8763 ' (except by retrieving its descriptor directly from the '
|
|
jpayne@68
|
8764 'base class).\n'
|
|
jpayne@68
|
8765 ' This renders the meaning of the program undefined. In the '
|
|
jpayne@68
|
8766 'future, a\n'
|
|
jpayne@68
|
8767 ' check may be added to prevent this.\n'
|
|
jpayne@68
|
8768 '\n'
|
|
jpayne@68
|
8769 '* Nonempty *__slots__* does not work for classes derived '
|
|
jpayne@68
|
8770 'from\n'
|
|
jpayne@68
|
8771 ' “variable-length” built-in types such as "int", "bytes" '
|
|
jpayne@68
|
8772 'and "tuple".\n'
|
|
jpayne@68
|
8773 '\n'
|
|
jpayne@68
|
8774 '* Any non-string iterable may be assigned to *__slots__*. '
|
|
jpayne@68
|
8775 'Mappings\n'
|
|
jpayne@68
|
8776 ' may also be used; however, in the future, special meaning '
|
|
jpayne@68
|
8777 'may be\n'
|
|
jpayne@68
|
8778 ' assigned to the values corresponding to each key.\n'
|
|
jpayne@68
|
8779 '\n'
|
|
jpayne@68
|
8780 '* *__class__* assignment works only if both classes have the '
|
|
jpayne@68
|
8781 'same\n'
|
|
jpayne@68
|
8782 ' *__slots__*.\n'
|
|
jpayne@68
|
8783 '\n'
|
|
jpayne@68
|
8784 '* Multiple inheritance with multiple slotted parent classes '
|
|
jpayne@68
|
8785 'can be\n'
|
|
jpayne@68
|
8786 ' used, but only one parent is allowed to have attributes '
|
|
jpayne@68
|
8787 'created by\n'
|
|
jpayne@68
|
8788 ' slots (the other bases must have empty slot layouts) - '
|
|
jpayne@68
|
8789 'violations\n'
|
|
jpayne@68
|
8790 ' raise "TypeError".\n'
|
|
jpayne@68
|
8791 '\n'
|
|
jpayne@68
|
8792 '* If an iterator is used for *__slots__* then a descriptor '
|
|
jpayne@68
|
8793 'is\n'
|
|
jpayne@68
|
8794 ' created for each of the iterator’s values. However, the '
|
|
jpayne@68
|
8795 '*__slots__*\n'
|
|
jpayne@68
|
8796 ' attribute will be an empty iterator.\n'
|
|
jpayne@68
|
8797 '\n'
|
|
jpayne@68
|
8798 '\n'
|
|
jpayne@68
|
8799 'Customizing class creation\n'
|
|
jpayne@68
|
8800 '==========================\n'
|
|
jpayne@68
|
8801 '\n'
|
|
jpayne@68
|
8802 'Whenever a class inherits from another class, '
|
|
jpayne@68
|
8803 '*__init_subclass__* is\n'
|
|
jpayne@68
|
8804 'called on that class. This way, it is possible to write '
|
|
jpayne@68
|
8805 'classes which\n'
|
|
jpayne@68
|
8806 'change the behavior of subclasses. This is closely related '
|
|
jpayne@68
|
8807 'to class\n'
|
|
jpayne@68
|
8808 'decorators, but where class decorators only affect the '
|
|
jpayne@68
|
8809 'specific class\n'
|
|
jpayne@68
|
8810 'they’re applied to, "__init_subclass__" solely applies to '
|
|
jpayne@68
|
8811 'future\n'
|
|
jpayne@68
|
8812 'subclasses of the class defining the method.\n'
|
|
jpayne@68
|
8813 '\n'
|
|
jpayne@68
|
8814 'classmethod object.__init_subclass__(cls)\n'
|
|
jpayne@68
|
8815 '\n'
|
|
jpayne@68
|
8816 ' This method is called whenever the containing class is '
|
|
jpayne@68
|
8817 'subclassed.\n'
|
|
jpayne@68
|
8818 ' *cls* is then the new subclass. If defined as a normal '
|
|
jpayne@68
|
8819 'instance\n'
|
|
jpayne@68
|
8820 ' method, this method is implicitly converted to a class '
|
|
jpayne@68
|
8821 'method.\n'
|
|
jpayne@68
|
8822 '\n'
|
|
jpayne@68
|
8823 ' Keyword arguments which are given to a new class are '
|
|
jpayne@68
|
8824 'passed to the\n'
|
|
jpayne@68
|
8825 ' parent’s class "__init_subclass__". For compatibility '
|
|
jpayne@68
|
8826 'with other\n'
|
|
jpayne@68
|
8827 ' classes using "__init_subclass__", one should take out '
|
|
jpayne@68
|
8828 'the needed\n'
|
|
jpayne@68
|
8829 ' keyword arguments and pass the others over to the base '
|
|
jpayne@68
|
8830 'class, as\n'
|
|
jpayne@68
|
8831 ' in:\n'
|
|
jpayne@68
|
8832 '\n'
|
|
jpayne@68
|
8833 ' class Philosopher:\n'
|
|
jpayne@68
|
8834 ' def __init_subclass__(cls, /, default_name, '
|
|
jpayne@68
|
8835 '**kwargs):\n'
|
|
jpayne@68
|
8836 ' super().__init_subclass__(**kwargs)\n'
|
|
jpayne@68
|
8837 ' cls.default_name = default_name\n'
|
|
jpayne@68
|
8838 '\n'
|
|
jpayne@68
|
8839 ' class AustralianPhilosopher(Philosopher, '
|
|
jpayne@68
|
8840 'default_name="Bruce"):\n'
|
|
jpayne@68
|
8841 ' pass\n'
|
|
jpayne@68
|
8842 '\n'
|
|
jpayne@68
|
8843 ' The default implementation "object.__init_subclass__" '
|
|
jpayne@68
|
8844 'does nothing,\n'
|
|
jpayne@68
|
8845 ' but raises an error if it is called with any arguments.\n'
|
|
jpayne@68
|
8846 '\n'
|
|
jpayne@68
|
8847 ' Note: The metaclass hint "metaclass" is consumed by the '
|
|
jpayne@68
|
8848 'rest of\n'
|
|
jpayne@68
|
8849 ' the type machinery, and is never passed to '
|
|
jpayne@68
|
8850 '"__init_subclass__"\n'
|
|
jpayne@68
|
8851 ' implementations. The actual metaclass (rather than the '
|
|
jpayne@68
|
8852 'explicit\n'
|
|
jpayne@68
|
8853 ' hint) can be accessed as "type(cls)".\n'
|
|
jpayne@68
|
8854 '\n'
|
|
jpayne@68
|
8855 ' New in version 3.6.\n'
|
|
jpayne@68
|
8856 '\n'
|
|
jpayne@68
|
8857 '\n'
|
|
jpayne@68
|
8858 'Metaclasses\n'
|
|
jpayne@68
|
8859 '-----------\n'
|
|
jpayne@68
|
8860 '\n'
|
|
jpayne@68
|
8861 'By default, classes are constructed using "type()". The '
|
|
jpayne@68
|
8862 'class body is\n'
|
|
jpayne@68
|
8863 'executed in a new namespace and the class name is bound '
|
|
jpayne@68
|
8864 'locally to the\n'
|
|
jpayne@68
|
8865 'result of "type(name, bases, namespace)".\n'
|
|
jpayne@68
|
8866 '\n'
|
|
jpayne@68
|
8867 'The class creation process can be customized by passing the\n'
|
|
jpayne@68
|
8868 '"metaclass" keyword argument in the class definition line, '
|
|
jpayne@68
|
8869 'or by\n'
|
|
jpayne@68
|
8870 'inheriting from an existing class that included such an '
|
|
jpayne@68
|
8871 'argument. In\n'
|
|
jpayne@68
|
8872 'the following example, both "MyClass" and "MySubclass" are '
|
|
jpayne@68
|
8873 'instances\n'
|
|
jpayne@68
|
8874 'of "Meta":\n'
|
|
jpayne@68
|
8875 '\n'
|
|
jpayne@68
|
8876 ' class Meta(type):\n'
|
|
jpayne@68
|
8877 ' pass\n'
|
|
jpayne@68
|
8878 '\n'
|
|
jpayne@68
|
8879 ' class MyClass(metaclass=Meta):\n'
|
|
jpayne@68
|
8880 ' pass\n'
|
|
jpayne@68
|
8881 '\n'
|
|
jpayne@68
|
8882 ' class MySubclass(MyClass):\n'
|
|
jpayne@68
|
8883 ' pass\n'
|
|
jpayne@68
|
8884 '\n'
|
|
jpayne@68
|
8885 'Any other keyword arguments that are specified in the class '
|
|
jpayne@68
|
8886 'definition\n'
|
|
jpayne@68
|
8887 'are passed through to all metaclass operations described '
|
|
jpayne@68
|
8888 'below.\n'
|
|
jpayne@68
|
8889 '\n'
|
|
jpayne@68
|
8890 'When a class definition is executed, the following steps '
|
|
jpayne@68
|
8891 'occur:\n'
|
|
jpayne@68
|
8892 '\n'
|
|
jpayne@68
|
8893 '* MRO entries are resolved;\n'
|
|
jpayne@68
|
8894 '\n'
|
|
jpayne@68
|
8895 '* the appropriate metaclass is determined;\n'
|
|
jpayne@68
|
8896 '\n'
|
|
jpayne@68
|
8897 '* the class namespace is prepared;\n'
|
|
jpayne@68
|
8898 '\n'
|
|
jpayne@68
|
8899 '* the class body is executed;\n'
|
|
jpayne@68
|
8900 '\n'
|
|
jpayne@68
|
8901 '* the class object is created.\n'
|
|
jpayne@68
|
8902 '\n'
|
|
jpayne@68
|
8903 '\n'
|
|
jpayne@68
|
8904 'Resolving MRO entries\n'
|
|
jpayne@68
|
8905 '---------------------\n'
|
|
jpayne@68
|
8906 '\n'
|
|
jpayne@68
|
8907 'If a base that appears in class definition is not an '
|
|
jpayne@68
|
8908 'instance of\n'
|
|
jpayne@68
|
8909 '"type", then an "__mro_entries__" method is searched on it. '
|
|
jpayne@68
|
8910 'If found,\n'
|
|
jpayne@68
|
8911 'it is called with the original bases tuple. This method must '
|
|
jpayne@68
|
8912 'return a\n'
|
|
jpayne@68
|
8913 'tuple of classes that will be used instead of this base. The '
|
|
jpayne@68
|
8914 'tuple may\n'
|
|
jpayne@68
|
8915 'be empty, in such case the original base is ignored.\n'
|
|
jpayne@68
|
8916 '\n'
|
|
jpayne@68
|
8917 'See also: **PEP 560** - Core support for typing module and '
|
|
jpayne@68
|
8918 'generic\n'
|
|
jpayne@68
|
8919 ' types\n'
|
|
jpayne@68
|
8920 '\n'
|
|
jpayne@68
|
8921 '\n'
|
|
jpayne@68
|
8922 'Determining the appropriate metaclass\n'
|
|
jpayne@68
|
8923 '-------------------------------------\n'
|
|
jpayne@68
|
8924 '\n'
|
|
jpayne@68
|
8925 'The appropriate metaclass for a class definition is '
|
|
jpayne@68
|
8926 'determined as\n'
|
|
jpayne@68
|
8927 'follows:\n'
|
|
jpayne@68
|
8928 '\n'
|
|
jpayne@68
|
8929 '* if no bases and no explicit metaclass are given, then '
|
|
jpayne@68
|
8930 '"type()" is\n'
|
|
jpayne@68
|
8931 ' used;\n'
|
|
jpayne@68
|
8932 '\n'
|
|
jpayne@68
|
8933 '* if an explicit metaclass is given and it is *not* an '
|
|
jpayne@68
|
8934 'instance of\n'
|
|
jpayne@68
|
8935 ' "type()", then it is used directly as the metaclass;\n'
|
|
jpayne@68
|
8936 '\n'
|
|
jpayne@68
|
8937 '* if an instance of "type()" is given as the explicit '
|
|
jpayne@68
|
8938 'metaclass, or\n'
|
|
jpayne@68
|
8939 ' bases are defined, then the most derived metaclass is '
|
|
jpayne@68
|
8940 'used.\n'
|
|
jpayne@68
|
8941 '\n'
|
|
jpayne@68
|
8942 'The most derived metaclass is selected from the explicitly '
|
|
jpayne@68
|
8943 'specified\n'
|
|
jpayne@68
|
8944 'metaclass (if any) and the metaclasses (i.e. "type(cls)") of '
|
|
jpayne@68
|
8945 'all\n'
|
|
jpayne@68
|
8946 'specified base classes. The most derived metaclass is one '
|
|
jpayne@68
|
8947 'which is a\n'
|
|
jpayne@68
|
8948 'subtype of *all* of these candidate metaclasses. If none of '
|
|
jpayne@68
|
8949 'the\n'
|
|
jpayne@68
|
8950 'candidate metaclasses meets that criterion, then the class '
|
|
jpayne@68
|
8951 'definition\n'
|
|
jpayne@68
|
8952 'will fail with "TypeError".\n'
|
|
jpayne@68
|
8953 '\n'
|
|
jpayne@68
|
8954 '\n'
|
|
jpayne@68
|
8955 'Preparing the class namespace\n'
|
|
jpayne@68
|
8956 '-----------------------------\n'
|
|
jpayne@68
|
8957 '\n'
|
|
jpayne@68
|
8958 'Once the appropriate metaclass has been identified, then the '
|
|
jpayne@68
|
8959 'class\n'
|
|
jpayne@68
|
8960 'namespace is prepared. If the metaclass has a "__prepare__" '
|
|
jpayne@68
|
8961 'attribute,\n'
|
|
jpayne@68
|
8962 'it is called as "namespace = metaclass.__prepare__(name, '
|
|
jpayne@68
|
8963 'bases,\n'
|
|
jpayne@68
|
8964 '**kwds)" (where the additional keyword arguments, if any, '
|
|
jpayne@68
|
8965 'come from\n'
|
|
jpayne@68
|
8966 'the class definition).\n'
|
|
jpayne@68
|
8967 '\n'
|
|
jpayne@68
|
8968 'If the metaclass has no "__prepare__" attribute, then the '
|
|
jpayne@68
|
8969 'class\n'
|
|
jpayne@68
|
8970 'namespace is initialised as an empty ordered mapping.\n'
|
|
jpayne@68
|
8971 '\n'
|
|
jpayne@68
|
8972 'See also:\n'
|
|
jpayne@68
|
8973 '\n'
|
|
jpayne@68
|
8974 ' **PEP 3115** - Metaclasses in Python 3000\n'
|
|
jpayne@68
|
8975 ' Introduced the "__prepare__" namespace hook\n'
|
|
jpayne@68
|
8976 '\n'
|
|
jpayne@68
|
8977 '\n'
|
|
jpayne@68
|
8978 'Executing the class body\n'
|
|
jpayne@68
|
8979 '------------------------\n'
|
|
jpayne@68
|
8980 '\n'
|
|
jpayne@68
|
8981 'The class body is executed (approximately) as "exec(body, '
|
|
jpayne@68
|
8982 'globals(),\n'
|
|
jpayne@68
|
8983 'namespace)". The key difference from a normal call to '
|
|
jpayne@68
|
8984 '"exec()" is that\n'
|
|
jpayne@68
|
8985 'lexical scoping allows the class body (including any '
|
|
jpayne@68
|
8986 'methods) to\n'
|
|
jpayne@68
|
8987 'reference names from the current and outer scopes when the '
|
|
jpayne@68
|
8988 'class\n'
|
|
jpayne@68
|
8989 'definition occurs inside a function.\n'
|
|
jpayne@68
|
8990 '\n'
|
|
jpayne@68
|
8991 'However, even when the class definition occurs inside the '
|
|
jpayne@68
|
8992 'function,\n'
|
|
jpayne@68
|
8993 'methods defined inside the class still cannot see names '
|
|
jpayne@68
|
8994 'defined at the\n'
|
|
jpayne@68
|
8995 'class scope. Class variables must be accessed through the '
|
|
jpayne@68
|
8996 'first\n'
|
|
jpayne@68
|
8997 'parameter of instance or class methods, or through the '
|
|
jpayne@68
|
8998 'implicit\n'
|
|
jpayne@68
|
8999 'lexically scoped "__class__" reference described in the next '
|
|
jpayne@68
|
9000 'section.\n'
|
|
jpayne@68
|
9001 '\n'
|
|
jpayne@68
|
9002 '\n'
|
|
jpayne@68
|
9003 'Creating the class object\n'
|
|
jpayne@68
|
9004 '-------------------------\n'
|
|
jpayne@68
|
9005 '\n'
|
|
jpayne@68
|
9006 'Once the class namespace has been populated by executing the '
|
|
jpayne@68
|
9007 'class\n'
|
|
jpayne@68
|
9008 'body, the class object is created by calling '
|
|
jpayne@68
|
9009 '"metaclass(name, bases,\n'
|
|
jpayne@68
|
9010 'namespace, **kwds)" (the additional keywords passed here are '
|
|
jpayne@68
|
9011 'the same\n'
|
|
jpayne@68
|
9012 'as those passed to "__prepare__").\n'
|
|
jpayne@68
|
9013 '\n'
|
|
jpayne@68
|
9014 'This class object is the one that will be referenced by the '
|
|
jpayne@68
|
9015 'zero-\n'
|
|
jpayne@68
|
9016 'argument form of "super()". "__class__" is an implicit '
|
|
jpayne@68
|
9017 'closure\n'
|
|
jpayne@68
|
9018 'reference created by the compiler if any methods in a class '
|
|
jpayne@68
|
9019 'body refer\n'
|
|
jpayne@68
|
9020 'to either "__class__" or "super". This allows the zero '
|
|
jpayne@68
|
9021 'argument form\n'
|
|
jpayne@68
|
9022 'of "super()" to correctly identify the class being defined '
|
|
jpayne@68
|
9023 'based on\n'
|
|
jpayne@68
|
9024 'lexical scoping, while the class or instance that was used '
|
|
jpayne@68
|
9025 'to make the\n'
|
|
jpayne@68
|
9026 'current call is identified based on the first argument '
|
|
jpayne@68
|
9027 'passed to the\n'
|
|
jpayne@68
|
9028 'method.\n'
|
|
jpayne@68
|
9029 '\n'
|
|
jpayne@68
|
9030 '**CPython implementation detail:** In CPython 3.6 and later, '
|
|
jpayne@68
|
9031 'the\n'
|
|
jpayne@68
|
9032 '"__class__" cell is passed to the metaclass as a '
|
|
jpayne@68
|
9033 '"__classcell__" entry\n'
|
|
jpayne@68
|
9034 'in the class namespace. If present, this must be propagated '
|
|
jpayne@68
|
9035 'up to the\n'
|
|
jpayne@68
|
9036 '"type.__new__" call in order for the class to be '
|
|
jpayne@68
|
9037 'initialised\n'
|
|
jpayne@68
|
9038 'correctly. Failing to do so will result in a "RuntimeError" '
|
|
jpayne@68
|
9039 'in Python\n'
|
|
jpayne@68
|
9040 '3.8.\n'
|
|
jpayne@68
|
9041 '\n'
|
|
jpayne@68
|
9042 'When using the default metaclass "type", or any metaclass '
|
|
jpayne@68
|
9043 'that\n'
|
|
jpayne@68
|
9044 'ultimately calls "type.__new__", the following additional\n'
|
|
jpayne@68
|
9045 'customisation steps are invoked after creating the class '
|
|
jpayne@68
|
9046 'object:\n'
|
|
jpayne@68
|
9047 '\n'
|
|
jpayne@68
|
9048 '* first, "type.__new__" collects all of the descriptors in '
|
|
jpayne@68
|
9049 'the class\n'
|
|
jpayne@68
|
9050 ' namespace that define a "__set_name__()" method;\n'
|
|
jpayne@68
|
9051 '\n'
|
|
jpayne@68
|
9052 '* second, all of these "__set_name__" methods are called '
|
|
jpayne@68
|
9053 'with the\n'
|
|
jpayne@68
|
9054 ' class being defined and the assigned name of that '
|
|
jpayne@68
|
9055 'particular\n'
|
|
jpayne@68
|
9056 ' descriptor;\n'
|
|
jpayne@68
|
9057 '\n'
|
|
jpayne@68
|
9058 '* finally, the "__init_subclass__()" hook is called on the '
|
|
jpayne@68
|
9059 'immediate\n'
|
|
jpayne@68
|
9060 ' parent of the new class in its method resolution order.\n'
|
|
jpayne@68
|
9061 '\n'
|
|
jpayne@68
|
9062 'After the class object is created, it is passed to the '
|
|
jpayne@68
|
9063 'class\n'
|
|
jpayne@68
|
9064 'decorators included in the class definition (if any) and the '
|
|
jpayne@68
|
9065 'resulting\n'
|
|
jpayne@68
|
9066 'object is bound in the local namespace as the defined '
|
|
jpayne@68
|
9067 'class.\n'
|
|
jpayne@68
|
9068 '\n'
|
|
jpayne@68
|
9069 'When a new class is created by "type.__new__", the object '
|
|
jpayne@68
|
9070 'provided as\n'
|
|
jpayne@68
|
9071 'the namespace parameter is copied to a new ordered mapping '
|
|
jpayne@68
|
9072 'and the\n'
|
|
jpayne@68
|
9073 'original object is discarded. The new copy is wrapped in a '
|
|
jpayne@68
|
9074 'read-only\n'
|
|
jpayne@68
|
9075 'proxy, which becomes the "__dict__" attribute of the class '
|
|
jpayne@68
|
9076 'object.\n'
|
|
jpayne@68
|
9077 '\n'
|
|
jpayne@68
|
9078 'See also:\n'
|
|
jpayne@68
|
9079 '\n'
|
|
jpayne@68
|
9080 ' **PEP 3135** - New super\n'
|
|
jpayne@68
|
9081 ' Describes the implicit "__class__" closure reference\n'
|
|
jpayne@68
|
9082 '\n'
|
|
jpayne@68
|
9083 '\n'
|
|
jpayne@68
|
9084 'Uses for metaclasses\n'
|
|
jpayne@68
|
9085 '--------------------\n'
|
|
jpayne@68
|
9086 '\n'
|
|
jpayne@68
|
9087 'The potential uses for metaclasses are boundless. Some ideas '
|
|
jpayne@68
|
9088 'that have\n'
|
|
jpayne@68
|
9089 'been explored include enum, logging, interface checking, '
|
|
jpayne@68
|
9090 'automatic\n'
|
|
jpayne@68
|
9091 'delegation, automatic property creation, proxies, '
|
|
jpayne@68
|
9092 'frameworks, and\n'
|
|
jpayne@68
|
9093 'automatic resource locking/synchronization.\n'
|
|
jpayne@68
|
9094 '\n'
|
|
jpayne@68
|
9095 '\n'
|
|
jpayne@68
|
9096 'Customizing instance and subclass checks\n'
|
|
jpayne@68
|
9097 '========================================\n'
|
|
jpayne@68
|
9098 '\n'
|
|
jpayne@68
|
9099 'The following methods are used to override the default '
|
|
jpayne@68
|
9100 'behavior of the\n'
|
|
jpayne@68
|
9101 '"isinstance()" and "issubclass()" built-in functions.\n'
|
|
jpayne@68
|
9102 '\n'
|
|
jpayne@68
|
9103 'In particular, the metaclass "abc.ABCMeta" implements these '
|
|
jpayne@68
|
9104 'methods in\n'
|
|
jpayne@68
|
9105 'order to allow the addition of Abstract Base Classes (ABCs) '
|
|
jpayne@68
|
9106 'as\n'
|
|
jpayne@68
|
9107 '“virtual base classes” to any class or type (including '
|
|
jpayne@68
|
9108 'built-in\n'
|
|
jpayne@68
|
9109 'types), including other ABCs.\n'
|
|
jpayne@68
|
9110 '\n'
|
|
jpayne@68
|
9111 'class.__instancecheck__(self, instance)\n'
|
|
jpayne@68
|
9112 '\n'
|
|
jpayne@68
|
9113 ' Return true if *instance* should be considered a (direct '
|
|
jpayne@68
|
9114 'or\n'
|
|
jpayne@68
|
9115 ' indirect) instance of *class*. If defined, called to '
|
|
jpayne@68
|
9116 'implement\n'
|
|
jpayne@68
|
9117 ' "isinstance(instance, class)".\n'
|
|
jpayne@68
|
9118 '\n'
|
|
jpayne@68
|
9119 'class.__subclasscheck__(self, subclass)\n'
|
|
jpayne@68
|
9120 '\n'
|
|
jpayne@68
|
9121 ' Return true if *subclass* should be considered a (direct '
|
|
jpayne@68
|
9122 'or\n'
|
|
jpayne@68
|
9123 ' indirect) subclass of *class*. If defined, called to '
|
|
jpayne@68
|
9124 'implement\n'
|
|
jpayne@68
|
9125 ' "issubclass(subclass, class)".\n'
|
|
jpayne@68
|
9126 '\n'
|
|
jpayne@68
|
9127 'Note that these methods are looked up on the type '
|
|
jpayne@68
|
9128 '(metaclass) of a\n'
|
|
jpayne@68
|
9129 'class. They cannot be defined as class methods in the '
|
|
jpayne@68
|
9130 'actual class.\n'
|
|
jpayne@68
|
9131 'This is consistent with the lookup of special methods that '
|
|
jpayne@68
|
9132 'are called\n'
|
|
jpayne@68
|
9133 'on instances, only in this case the instance is itself a '
|
|
jpayne@68
|
9134 'class.\n'
|
|
jpayne@68
|
9135 '\n'
|
|
jpayne@68
|
9136 'See also:\n'
|
|
jpayne@68
|
9137 '\n'
|
|
jpayne@68
|
9138 ' **PEP 3119** - Introducing Abstract Base Classes\n'
|
|
jpayne@68
|
9139 ' Includes the specification for customizing '
|
|
jpayne@68
|
9140 '"isinstance()" and\n'
|
|
jpayne@68
|
9141 ' "issubclass()" behavior through "__instancecheck__()" '
|
|
jpayne@68
|
9142 'and\n'
|
|
jpayne@68
|
9143 ' "__subclasscheck__()", with motivation for this '
|
|
jpayne@68
|
9144 'functionality in\n'
|
|
jpayne@68
|
9145 ' the context of adding Abstract Base Classes (see the '
|
|
jpayne@68
|
9146 '"abc"\n'
|
|
jpayne@68
|
9147 ' module) to the language.\n'
|
|
jpayne@68
|
9148 '\n'
|
|
jpayne@68
|
9149 '\n'
|
|
jpayne@68
|
9150 'Emulating generic types\n'
|
|
jpayne@68
|
9151 '=======================\n'
|
|
jpayne@68
|
9152 '\n'
|
|
jpayne@68
|
9153 'One can implement the generic class syntax as specified by '
|
|
jpayne@68
|
9154 '**PEP 484**\n'
|
|
jpayne@68
|
9155 '(for example "List[int]") by defining a special method:\n'
|
|
jpayne@68
|
9156 '\n'
|
|
jpayne@68
|
9157 'classmethod object.__class_getitem__(cls, key)\n'
|
|
jpayne@68
|
9158 '\n'
|
|
jpayne@68
|
9159 ' Return an object representing the specialization of a '
|
|
jpayne@68
|
9160 'generic class\n'
|
|
jpayne@68
|
9161 ' by type arguments found in *key*.\n'
|
|
jpayne@68
|
9162 '\n'
|
|
jpayne@68
|
9163 'This method is looked up on the class object itself, and '
|
|
jpayne@68
|
9164 'when defined\n'
|
|
jpayne@68
|
9165 'in the class body, this method is implicitly a class '
|
|
jpayne@68
|
9166 'method. Note,\n'
|
|
jpayne@68
|
9167 'this mechanism is primarily reserved for use with static '
|
|
jpayne@68
|
9168 'type hints,\n'
|
|
jpayne@68
|
9169 'other usage is discouraged.\n'
|
|
jpayne@68
|
9170 '\n'
|
|
jpayne@68
|
9171 'See also: **PEP 560** - Core support for typing module and '
|
|
jpayne@68
|
9172 'generic\n'
|
|
jpayne@68
|
9173 ' types\n'
|
|
jpayne@68
|
9174 '\n'
|
|
jpayne@68
|
9175 '\n'
|
|
jpayne@68
|
9176 'Emulating callable objects\n'
|
|
jpayne@68
|
9177 '==========================\n'
|
|
jpayne@68
|
9178 '\n'
|
|
jpayne@68
|
9179 'object.__call__(self[, args...])\n'
|
|
jpayne@68
|
9180 '\n'
|
|
jpayne@68
|
9181 ' Called when the instance is “called” as a function; if '
|
|
jpayne@68
|
9182 'this method\n'
|
|
jpayne@68
|
9183 ' is defined, "x(arg1, arg2, ...)" is a shorthand for\n'
|
|
jpayne@68
|
9184 ' "x.__call__(arg1, arg2, ...)".\n'
|
|
jpayne@68
|
9185 '\n'
|
|
jpayne@68
|
9186 '\n'
|
|
jpayne@68
|
9187 'Emulating container types\n'
|
|
jpayne@68
|
9188 '=========================\n'
|
|
jpayne@68
|
9189 '\n'
|
|
jpayne@68
|
9190 'The following methods can be defined to implement container '
|
|
jpayne@68
|
9191 'objects.\n'
|
|
jpayne@68
|
9192 'Containers usually are sequences (such as lists or tuples) '
|
|
jpayne@68
|
9193 'or mappings\n'
|
|
jpayne@68
|
9194 '(like dictionaries), but can represent other containers as '
|
|
jpayne@68
|
9195 'well. The\n'
|
|
jpayne@68
|
9196 'first set of methods is used either to emulate a sequence or '
|
|
jpayne@68
|
9197 'to\n'
|
|
jpayne@68
|
9198 'emulate a mapping; the difference is that for a sequence, '
|
|
jpayne@68
|
9199 'the\n'
|
|
jpayne@68
|
9200 'allowable keys should be the integers *k* for which "0 <= k '
|
|
jpayne@68
|
9201 '< N" where\n'
|
|
jpayne@68
|
9202 '*N* is the length of the sequence, or slice objects, which '
|
|
jpayne@68
|
9203 'define a\n'
|
|
jpayne@68
|
9204 'range of items. It is also recommended that mappings '
|
|
jpayne@68
|
9205 'provide the\n'
|
|
jpayne@68
|
9206 'methods "keys()", "values()", "items()", "get()", '
|
|
jpayne@68
|
9207 '"clear()",\n'
|
|
jpayne@68
|
9208 '"setdefault()", "pop()", "popitem()", "copy()", and '
|
|
jpayne@68
|
9209 '"update()"\n'
|
|
jpayne@68
|
9210 'behaving similar to those for Python’s standard dictionary '
|
|
jpayne@68
|
9211 'objects.\n'
|
|
jpayne@68
|
9212 'The "collections.abc" module provides a "MutableMapping" '
|
|
jpayne@68
|
9213 'abstract base\n'
|
|
jpayne@68
|
9214 'class to help create those methods from a base set of '
|
|
jpayne@68
|
9215 '"__getitem__()",\n'
|
|
jpayne@68
|
9216 '"__setitem__()", "__delitem__()", and "keys()". Mutable '
|
|
jpayne@68
|
9217 'sequences\n'
|
|
jpayne@68
|
9218 'should provide methods "append()", "count()", "index()", '
|
|
jpayne@68
|
9219 '"extend()",\n'
|
|
jpayne@68
|
9220 '"insert()", "pop()", "remove()", "reverse()" and "sort()", '
|
|
jpayne@68
|
9221 'like Python\n'
|
|
jpayne@68
|
9222 'standard list objects. Finally, sequence types should '
|
|
jpayne@68
|
9223 'implement\n'
|
|
jpayne@68
|
9224 'addition (meaning concatenation) and multiplication '
|
|
jpayne@68
|
9225 '(meaning\n'
|
|
jpayne@68
|
9226 'repetition) by defining the methods "__add__()", '
|
|
jpayne@68
|
9227 '"__radd__()",\n'
|
|
jpayne@68
|
9228 '"__iadd__()", "__mul__()", "__rmul__()" and "__imul__()" '
|
|
jpayne@68
|
9229 'described\n'
|
|
jpayne@68
|
9230 'below; they should not define other numerical operators. It '
|
|
jpayne@68
|
9231 'is\n'
|
|
jpayne@68
|
9232 'recommended that both mappings and sequences implement the\n'
|
|
jpayne@68
|
9233 '"__contains__()" method to allow efficient use of the "in" '
|
|
jpayne@68
|
9234 'operator;\n'
|
|
jpayne@68
|
9235 'for mappings, "in" should search the mapping’s keys; for '
|
|
jpayne@68
|
9236 'sequences, it\n'
|
|
jpayne@68
|
9237 'should search through the values. It is further recommended '
|
|
jpayne@68
|
9238 'that both\n'
|
|
jpayne@68
|
9239 'mappings and sequences implement the "__iter__()" method to '
|
|
jpayne@68
|
9240 'allow\n'
|
|
jpayne@68
|
9241 'efficient iteration through the container; for mappings, '
|
|
jpayne@68
|
9242 '"__iter__()"\n'
|
|
jpayne@68
|
9243 'should iterate through the object’s keys; for sequences, it '
|
|
jpayne@68
|
9244 'should\n'
|
|
jpayne@68
|
9245 'iterate through the values.\n'
|
|
jpayne@68
|
9246 '\n'
|
|
jpayne@68
|
9247 'object.__len__(self)\n'
|
|
jpayne@68
|
9248 '\n'
|
|
jpayne@68
|
9249 ' Called to implement the built-in function "len()". '
|
|
jpayne@68
|
9250 'Should return\n'
|
|
jpayne@68
|
9251 ' the length of the object, an integer ">=" 0. Also, an '
|
|
jpayne@68
|
9252 'object that\n'
|
|
jpayne@68
|
9253 ' doesn’t define a "__bool__()" method and whose '
|
|
jpayne@68
|
9254 '"__len__()" method\n'
|
|
jpayne@68
|
9255 ' returns zero is considered to be false in a Boolean '
|
|
jpayne@68
|
9256 'context.\n'
|
|
jpayne@68
|
9257 '\n'
|
|
jpayne@68
|
9258 ' **CPython implementation detail:** In CPython, the length '
|
|
jpayne@68
|
9259 'is\n'
|
|
jpayne@68
|
9260 ' required to be at most "sys.maxsize". If the length is '
|
|
jpayne@68
|
9261 'larger than\n'
|
|
jpayne@68
|
9262 ' "sys.maxsize" some features (such as "len()") may raise\n'
|
|
jpayne@68
|
9263 ' "OverflowError". To prevent raising "OverflowError" by '
|
|
jpayne@68
|
9264 'truth value\n'
|
|
jpayne@68
|
9265 ' testing, an object must define a "__bool__()" method.\n'
|
|
jpayne@68
|
9266 '\n'
|
|
jpayne@68
|
9267 'object.__length_hint__(self)\n'
|
|
jpayne@68
|
9268 '\n'
|
|
jpayne@68
|
9269 ' Called to implement "operator.length_hint()". Should '
|
|
jpayne@68
|
9270 'return an\n'
|
|
jpayne@68
|
9271 ' estimated length for the object (which may be greater or '
|
|
jpayne@68
|
9272 'less than\n'
|
|
jpayne@68
|
9273 ' the actual length). The length must be an integer ">=" 0. '
|
|
jpayne@68
|
9274 'The\n'
|
|
jpayne@68
|
9275 ' return value may also be "NotImplemented", which is '
|
|
jpayne@68
|
9276 'treated the\n'
|
|
jpayne@68
|
9277 ' same as if the "__length_hint__" method didn’t exist at '
|
|
jpayne@68
|
9278 'all. This\n'
|
|
jpayne@68
|
9279 ' method is purely an optimization and is never required '
|
|
jpayne@68
|
9280 'for\n'
|
|
jpayne@68
|
9281 ' correctness.\n'
|
|
jpayne@68
|
9282 '\n'
|
|
jpayne@68
|
9283 ' New in version 3.4.\n'
|
|
jpayne@68
|
9284 '\n'
|
|
jpayne@68
|
9285 'Note: Slicing is done exclusively with the following three '
|
|
jpayne@68
|
9286 'methods.\n'
|
|
jpayne@68
|
9287 ' A call like\n'
|
|
jpayne@68
|
9288 '\n'
|
|
jpayne@68
|
9289 ' a[1:2] = b\n'
|
|
jpayne@68
|
9290 '\n'
|
|
jpayne@68
|
9291 ' is translated to\n'
|
|
jpayne@68
|
9292 '\n'
|
|
jpayne@68
|
9293 ' a[slice(1, 2, None)] = b\n'
|
|
jpayne@68
|
9294 '\n'
|
|
jpayne@68
|
9295 ' and so forth. Missing slice items are always filled in '
|
|
jpayne@68
|
9296 'with "None".\n'
|
|
jpayne@68
|
9297 '\n'
|
|
jpayne@68
|
9298 'object.__getitem__(self, key)\n'
|
|
jpayne@68
|
9299 '\n'
|
|
jpayne@68
|
9300 ' Called to implement evaluation of "self[key]". For '
|
|
jpayne@68
|
9301 'sequence types,\n'
|
|
jpayne@68
|
9302 ' the accepted keys should be integers and slice objects. '
|
|
jpayne@68
|
9303 'Note that\n'
|
|
jpayne@68
|
9304 ' the special interpretation of negative indexes (if the '
|
|
jpayne@68
|
9305 'class wishes\n'
|
|
jpayne@68
|
9306 ' to emulate a sequence type) is up to the "__getitem__()" '
|
|
jpayne@68
|
9307 'method. If\n'
|
|
jpayne@68
|
9308 ' *key* is of an inappropriate type, "TypeError" may be '
|
|
jpayne@68
|
9309 'raised; if of\n'
|
|
jpayne@68
|
9310 ' a value outside the set of indexes for the sequence '
|
|
jpayne@68
|
9311 '(after any\n'
|
|
jpayne@68
|
9312 ' special interpretation of negative values), "IndexError" '
|
|
jpayne@68
|
9313 'should be\n'
|
|
jpayne@68
|
9314 ' raised. For mapping types, if *key* is missing (not in '
|
|
jpayne@68
|
9315 'the\n'
|
|
jpayne@68
|
9316 ' container), "KeyError" should be raised.\n'
|
|
jpayne@68
|
9317 '\n'
|
|
jpayne@68
|
9318 ' Note: "for" loops expect that an "IndexError" will be '
|
|
jpayne@68
|
9319 'raised for\n'
|
|
jpayne@68
|
9320 ' illegal indexes to allow proper detection of the end of '
|
|
jpayne@68
|
9321 'the\n'
|
|
jpayne@68
|
9322 ' sequence.\n'
|
|
jpayne@68
|
9323 '\n'
|
|
jpayne@68
|
9324 'object.__setitem__(self, key, value)\n'
|
|
jpayne@68
|
9325 '\n'
|
|
jpayne@68
|
9326 ' Called to implement assignment to "self[key]". Same note '
|
|
jpayne@68
|
9327 'as for\n'
|
|
jpayne@68
|
9328 ' "__getitem__()". This should only be implemented for '
|
|
jpayne@68
|
9329 'mappings if\n'
|
|
jpayne@68
|
9330 ' the objects support changes to the values for keys, or if '
|
|
jpayne@68
|
9331 'new keys\n'
|
|
jpayne@68
|
9332 ' can be added, or for sequences if elements can be '
|
|
jpayne@68
|
9333 'replaced. The\n'
|
|
jpayne@68
|
9334 ' same exceptions should be raised for improper *key* '
|
|
jpayne@68
|
9335 'values as for\n'
|
|
jpayne@68
|
9336 ' the "__getitem__()" method.\n'
|
|
jpayne@68
|
9337 '\n'
|
|
jpayne@68
|
9338 'object.__delitem__(self, key)\n'
|
|
jpayne@68
|
9339 '\n'
|
|
jpayne@68
|
9340 ' Called to implement deletion of "self[key]". Same note '
|
|
jpayne@68
|
9341 'as for\n'
|
|
jpayne@68
|
9342 ' "__getitem__()". This should only be implemented for '
|
|
jpayne@68
|
9343 'mappings if\n'
|
|
jpayne@68
|
9344 ' the objects support removal of keys, or for sequences if '
|
|
jpayne@68
|
9345 'elements\n'
|
|
jpayne@68
|
9346 ' can be removed from the sequence. The same exceptions '
|
|
jpayne@68
|
9347 'should be\n'
|
|
jpayne@68
|
9348 ' raised for improper *key* values as for the '
|
|
jpayne@68
|
9349 '"__getitem__()" method.\n'
|
|
jpayne@68
|
9350 '\n'
|
|
jpayne@68
|
9351 'object.__missing__(self, key)\n'
|
|
jpayne@68
|
9352 '\n'
|
|
jpayne@68
|
9353 ' Called by "dict"."__getitem__()" to implement "self[key]" '
|
|
jpayne@68
|
9354 'for dict\n'
|
|
jpayne@68
|
9355 ' subclasses when key is not in the dictionary.\n'
|
|
jpayne@68
|
9356 '\n'
|
|
jpayne@68
|
9357 'object.__iter__(self)\n'
|
|
jpayne@68
|
9358 '\n'
|
|
jpayne@68
|
9359 ' This method is called when an iterator is required for a '
|
|
jpayne@68
|
9360 'container.\n'
|
|
jpayne@68
|
9361 ' This method should return a new iterator object that can '
|
|
jpayne@68
|
9362 'iterate\n'
|
|
jpayne@68
|
9363 ' over all the objects in the container. For mappings, it '
|
|
jpayne@68
|
9364 'should\n'
|
|
jpayne@68
|
9365 ' iterate over the keys of the container.\n'
|
|
jpayne@68
|
9366 '\n'
|
|
jpayne@68
|
9367 ' Iterator objects also need to implement this method; they '
|
|
jpayne@68
|
9368 'are\n'
|
|
jpayne@68
|
9369 ' required to return themselves. For more information on '
|
|
jpayne@68
|
9370 'iterator\n'
|
|
jpayne@68
|
9371 ' objects, see Iterator Types.\n'
|
|
jpayne@68
|
9372 '\n'
|
|
jpayne@68
|
9373 'object.__reversed__(self)\n'
|
|
jpayne@68
|
9374 '\n'
|
|
jpayne@68
|
9375 ' Called (if present) by the "reversed()" built-in to '
|
|
jpayne@68
|
9376 'implement\n'
|
|
jpayne@68
|
9377 ' reverse iteration. It should return a new iterator '
|
|
jpayne@68
|
9378 'object that\n'
|
|
jpayne@68
|
9379 ' iterates over all the objects in the container in reverse '
|
|
jpayne@68
|
9380 'order.\n'
|
|
jpayne@68
|
9381 '\n'
|
|
jpayne@68
|
9382 ' If the "__reversed__()" method is not provided, the '
|
|
jpayne@68
|
9383 '"reversed()"\n'
|
|
jpayne@68
|
9384 ' built-in will fall back to using the sequence protocol '
|
|
jpayne@68
|
9385 '("__len__()"\n'
|
|
jpayne@68
|
9386 ' and "__getitem__()"). Objects that support the sequence '
|
|
jpayne@68
|
9387 'protocol\n'
|
|
jpayne@68
|
9388 ' should only provide "__reversed__()" if they can provide '
|
|
jpayne@68
|
9389 'an\n'
|
|
jpayne@68
|
9390 ' implementation that is more efficient than the one '
|
|
jpayne@68
|
9391 'provided by\n'
|
|
jpayne@68
|
9392 ' "reversed()".\n'
|
|
jpayne@68
|
9393 '\n'
|
|
jpayne@68
|
9394 'The membership test operators ("in" and "not in") are '
|
|
jpayne@68
|
9395 'normally\n'
|
|
jpayne@68
|
9396 'implemented as an iteration through a container. However, '
|
|
jpayne@68
|
9397 'container\n'
|
|
jpayne@68
|
9398 'objects can supply the following special method with a more '
|
|
jpayne@68
|
9399 'efficient\n'
|
|
jpayne@68
|
9400 'implementation, which also does not require the object be '
|
|
jpayne@68
|
9401 'iterable.\n'
|
|
jpayne@68
|
9402 '\n'
|
|
jpayne@68
|
9403 'object.__contains__(self, item)\n'
|
|
jpayne@68
|
9404 '\n'
|
|
jpayne@68
|
9405 ' Called to implement membership test operators. Should '
|
|
jpayne@68
|
9406 'return true\n'
|
|
jpayne@68
|
9407 ' if *item* is in *self*, false otherwise. For mapping '
|
|
jpayne@68
|
9408 'objects, this\n'
|
|
jpayne@68
|
9409 ' should consider the keys of the mapping rather than the '
|
|
jpayne@68
|
9410 'values or\n'
|
|
jpayne@68
|
9411 ' the key-item pairs.\n'
|
|
jpayne@68
|
9412 '\n'
|
|
jpayne@68
|
9413 ' For objects that don’t define "__contains__()", the '
|
|
jpayne@68
|
9414 'membership test\n'
|
|
jpayne@68
|
9415 ' first tries iteration via "__iter__()", then the old '
|
|
jpayne@68
|
9416 'sequence\n'
|
|
jpayne@68
|
9417 ' iteration protocol via "__getitem__()", see this section '
|
|
jpayne@68
|
9418 'in the\n'
|
|
jpayne@68
|
9419 ' language reference.\n'
|
|
jpayne@68
|
9420 '\n'
|
|
jpayne@68
|
9421 '\n'
|
|
jpayne@68
|
9422 'Emulating numeric types\n'
|
|
jpayne@68
|
9423 '=======================\n'
|
|
jpayne@68
|
9424 '\n'
|
|
jpayne@68
|
9425 'The following methods can be defined to emulate numeric '
|
|
jpayne@68
|
9426 'objects.\n'
|
|
jpayne@68
|
9427 'Methods corresponding to operations that are not supported '
|
|
jpayne@68
|
9428 'by the\n'
|
|
jpayne@68
|
9429 'particular kind of number implemented (e.g., bitwise '
|
|
jpayne@68
|
9430 'operations for\n'
|
|
jpayne@68
|
9431 'non-integral numbers) should be left undefined.\n'
|
|
jpayne@68
|
9432 '\n'
|
|
jpayne@68
|
9433 'object.__add__(self, other)\n'
|
|
jpayne@68
|
9434 'object.__sub__(self, other)\n'
|
|
jpayne@68
|
9435 'object.__mul__(self, other)\n'
|
|
jpayne@68
|
9436 'object.__matmul__(self, other)\n'
|
|
jpayne@68
|
9437 'object.__truediv__(self, other)\n'
|
|
jpayne@68
|
9438 'object.__floordiv__(self, other)\n'
|
|
jpayne@68
|
9439 'object.__mod__(self, other)\n'
|
|
jpayne@68
|
9440 'object.__divmod__(self, other)\n'
|
|
jpayne@68
|
9441 'object.__pow__(self, other[, modulo])\n'
|
|
jpayne@68
|
9442 'object.__lshift__(self, other)\n'
|
|
jpayne@68
|
9443 'object.__rshift__(self, other)\n'
|
|
jpayne@68
|
9444 'object.__and__(self, other)\n'
|
|
jpayne@68
|
9445 'object.__xor__(self, other)\n'
|
|
jpayne@68
|
9446 'object.__or__(self, other)\n'
|
|
jpayne@68
|
9447 '\n'
|
|
jpayne@68
|
9448 ' These methods are called to implement the binary '
|
|
jpayne@68
|
9449 'arithmetic\n'
|
|
jpayne@68
|
9450 ' operations ("+", "-", "*", "@", "/", "//", "%", '
|
|
jpayne@68
|
9451 '"divmod()",\n'
|
|
jpayne@68
|
9452 ' "pow()", "**", "<<", ">>", "&", "^", "|"). For instance, '
|
|
jpayne@68
|
9453 'to\n'
|
|
jpayne@68
|
9454 ' evaluate the expression "x + y", where *x* is an instance '
|
|
jpayne@68
|
9455 'of a\n'
|
|
jpayne@68
|
9456 ' class that has an "__add__()" method, "x.__add__(y)" is '
|
|
jpayne@68
|
9457 'called.\n'
|
|
jpayne@68
|
9458 ' The "__divmod__()" method should be the equivalent to '
|
|
jpayne@68
|
9459 'using\n'
|
|
jpayne@68
|
9460 ' "__floordiv__()" and "__mod__()"; it should not be '
|
|
jpayne@68
|
9461 'related to\n'
|
|
jpayne@68
|
9462 ' "__truediv__()". Note that "__pow__()" should be defined '
|
|
jpayne@68
|
9463 'to accept\n'
|
|
jpayne@68
|
9464 ' an optional third argument if the ternary version of the '
|
|
jpayne@68
|
9465 'built-in\n'
|
|
jpayne@68
|
9466 ' "pow()" function is to be supported.\n'
|
|
jpayne@68
|
9467 '\n'
|
|
jpayne@68
|
9468 ' If one of those methods does not support the operation '
|
|
jpayne@68
|
9469 'with the\n'
|
|
jpayne@68
|
9470 ' supplied arguments, it should return "NotImplemented".\n'
|
|
jpayne@68
|
9471 '\n'
|
|
jpayne@68
|
9472 'object.__radd__(self, other)\n'
|
|
jpayne@68
|
9473 'object.__rsub__(self, other)\n'
|
|
jpayne@68
|
9474 'object.__rmul__(self, other)\n'
|
|
jpayne@68
|
9475 'object.__rmatmul__(self, other)\n'
|
|
jpayne@68
|
9476 'object.__rtruediv__(self, other)\n'
|
|
jpayne@68
|
9477 'object.__rfloordiv__(self, other)\n'
|
|
jpayne@68
|
9478 'object.__rmod__(self, other)\n'
|
|
jpayne@68
|
9479 'object.__rdivmod__(self, other)\n'
|
|
jpayne@68
|
9480 'object.__rpow__(self, other)\n'
|
|
jpayne@68
|
9481 'object.__rlshift__(self, other)\n'
|
|
jpayne@68
|
9482 'object.__rrshift__(self, other)\n'
|
|
jpayne@68
|
9483 'object.__rand__(self, other)\n'
|
|
jpayne@68
|
9484 'object.__rxor__(self, other)\n'
|
|
jpayne@68
|
9485 'object.__ror__(self, other)\n'
|
|
jpayne@68
|
9486 '\n'
|
|
jpayne@68
|
9487 ' These methods are called to implement the binary '
|
|
jpayne@68
|
9488 'arithmetic\n'
|
|
jpayne@68
|
9489 ' operations ("+", "-", "*", "@", "/", "//", "%", '
|
|
jpayne@68
|
9490 '"divmod()",\n'
|
|
jpayne@68
|
9491 ' "pow()", "**", "<<", ">>", "&", "^", "|") with reflected '
|
|
jpayne@68
|
9492 '(swapped)\n'
|
|
jpayne@68
|
9493 ' operands. These functions are only called if the left '
|
|
jpayne@68
|
9494 'operand does\n'
|
|
jpayne@68
|
9495 ' not support the corresponding operation [3] and the '
|
|
jpayne@68
|
9496 'operands are of\n'
|
|
jpayne@68
|
9497 ' different types. [4] For instance, to evaluate the '
|
|
jpayne@68
|
9498 'expression "x -\n'
|
|
jpayne@68
|
9499 ' y", where *y* is an instance of a class that has an '
|
|
jpayne@68
|
9500 '"__rsub__()"\n'
|
|
jpayne@68
|
9501 ' method, "y.__rsub__(x)" is called if "x.__sub__(y)" '
|
|
jpayne@68
|
9502 'returns\n'
|
|
jpayne@68
|
9503 ' *NotImplemented*.\n'
|
|
jpayne@68
|
9504 '\n'
|
|
jpayne@68
|
9505 ' Note that ternary "pow()" will not try calling '
|
|
jpayne@68
|
9506 '"__rpow__()" (the\n'
|
|
jpayne@68
|
9507 ' coercion rules would become too complicated).\n'
|
|
jpayne@68
|
9508 '\n'
|
|
jpayne@68
|
9509 ' Note: If the right operand’s type is a subclass of the '
|
|
jpayne@68
|
9510 'left\n'
|
|
jpayne@68
|
9511 ' operand’s type and that subclass provides the reflected '
|
|
jpayne@68
|
9512 'method\n'
|
|
jpayne@68
|
9513 ' for the operation, this method will be called before '
|
|
jpayne@68
|
9514 'the left\n'
|
|
jpayne@68
|
9515 ' operand’s non-reflected method. This behavior allows '
|
|
jpayne@68
|
9516 'subclasses\n'
|
|
jpayne@68
|
9517 ' to override their ancestors’ operations.\n'
|
|
jpayne@68
|
9518 '\n'
|
|
jpayne@68
|
9519 'object.__iadd__(self, other)\n'
|
|
jpayne@68
|
9520 'object.__isub__(self, other)\n'
|
|
jpayne@68
|
9521 'object.__imul__(self, other)\n'
|
|
jpayne@68
|
9522 'object.__imatmul__(self, other)\n'
|
|
jpayne@68
|
9523 'object.__itruediv__(self, other)\n'
|
|
jpayne@68
|
9524 'object.__ifloordiv__(self, other)\n'
|
|
jpayne@68
|
9525 'object.__imod__(self, other)\n'
|
|
jpayne@68
|
9526 'object.__ipow__(self, other[, modulo])\n'
|
|
jpayne@68
|
9527 'object.__ilshift__(self, other)\n'
|
|
jpayne@68
|
9528 'object.__irshift__(self, other)\n'
|
|
jpayne@68
|
9529 'object.__iand__(self, other)\n'
|
|
jpayne@68
|
9530 'object.__ixor__(self, other)\n'
|
|
jpayne@68
|
9531 'object.__ior__(self, other)\n'
|
|
jpayne@68
|
9532 '\n'
|
|
jpayne@68
|
9533 ' These methods are called to implement the augmented '
|
|
jpayne@68
|
9534 'arithmetic\n'
|
|
jpayne@68
|
9535 ' assignments ("+=", "-=", "*=", "@=", "/=", "//=", "%=", '
|
|
jpayne@68
|
9536 '"**=",\n'
|
|
jpayne@68
|
9537 ' "<<=", ">>=", "&=", "^=", "|="). These methods should '
|
|
jpayne@68
|
9538 'attempt to\n'
|
|
jpayne@68
|
9539 ' do the operation in-place (modifying *self*) and return '
|
|
jpayne@68
|
9540 'the result\n'
|
|
jpayne@68
|
9541 ' (which could be, but does not have to be, *self*). If a '
|
|
jpayne@68
|
9542 'specific\n'
|
|
jpayne@68
|
9543 ' method is not defined, the augmented assignment falls '
|
|
jpayne@68
|
9544 'back to the\n'
|
|
jpayne@68
|
9545 ' normal methods. For instance, if *x* is an instance of a '
|
|
jpayne@68
|
9546 'class\n'
|
|
jpayne@68
|
9547 ' with an "__iadd__()" method, "x += y" is equivalent to "x '
|
|
jpayne@68
|
9548 '=\n'
|
|
jpayne@68
|
9549 ' x.__iadd__(y)" . Otherwise, "x.__add__(y)" and '
|
|
jpayne@68
|
9550 '"y.__radd__(x)" are\n'
|
|
jpayne@68
|
9551 ' considered, as with the evaluation of "x + y". In '
|
|
jpayne@68
|
9552 'certain\n'
|
|
jpayne@68
|
9553 ' situations, augmented assignment can result in unexpected '
|
|
jpayne@68
|
9554 'errors\n'
|
|
jpayne@68
|
9555 ' (see Why does a_tuple[i] += [‘item’] raise an exception '
|
|
jpayne@68
|
9556 'when the\n'
|
|
jpayne@68
|
9557 ' addition works?), but this behavior is in fact part of '
|
|
jpayne@68
|
9558 'the data\n'
|
|
jpayne@68
|
9559 ' model.\n'
|
|
jpayne@68
|
9560 '\n'
|
|
jpayne@68
|
9561 'object.__neg__(self)\n'
|
|
jpayne@68
|
9562 'object.__pos__(self)\n'
|
|
jpayne@68
|
9563 'object.__abs__(self)\n'
|
|
jpayne@68
|
9564 'object.__invert__(self)\n'
|
|
jpayne@68
|
9565 '\n'
|
|
jpayne@68
|
9566 ' Called to implement the unary arithmetic operations ("-", '
|
|
jpayne@68
|
9567 '"+",\n'
|
|
jpayne@68
|
9568 ' "abs()" and "~").\n'
|
|
jpayne@68
|
9569 '\n'
|
|
jpayne@68
|
9570 'object.__complex__(self)\n'
|
|
jpayne@68
|
9571 'object.__int__(self)\n'
|
|
jpayne@68
|
9572 'object.__float__(self)\n'
|
|
jpayne@68
|
9573 '\n'
|
|
jpayne@68
|
9574 ' Called to implement the built-in functions "complex()", '
|
|
jpayne@68
|
9575 '"int()" and\n'
|
|
jpayne@68
|
9576 ' "float()". Should return a value of the appropriate '
|
|
jpayne@68
|
9577 'type.\n'
|
|
jpayne@68
|
9578 '\n'
|
|
jpayne@68
|
9579 'object.__index__(self)\n'
|
|
jpayne@68
|
9580 '\n'
|
|
jpayne@68
|
9581 ' Called to implement "operator.index()", and whenever '
|
|
jpayne@68
|
9582 'Python needs\n'
|
|
jpayne@68
|
9583 ' to losslessly convert the numeric object to an integer '
|
|
jpayne@68
|
9584 'object (such\n'
|
|
jpayne@68
|
9585 ' as in slicing, or in the built-in "bin()", "hex()" and '
|
|
jpayne@68
|
9586 '"oct()"\n'
|
|
jpayne@68
|
9587 ' functions). Presence of this method indicates that the '
|
|
jpayne@68
|
9588 'numeric\n'
|
|
jpayne@68
|
9589 ' object is an integer type. Must return an integer.\n'
|
|
jpayne@68
|
9590 '\n'
|
|
jpayne@68
|
9591 ' If "__int__()", "__float__()" and "__complex__()" are not '
|
|
jpayne@68
|
9592 'defined\n'
|
|
jpayne@68
|
9593 ' then corresponding built-in functions "int()", "float()" '
|
|
jpayne@68
|
9594 'and\n'
|
|
jpayne@68
|
9595 ' "complex()" fall back to "__index__()".\n'
|
|
jpayne@68
|
9596 '\n'
|
|
jpayne@68
|
9597 'object.__round__(self[, ndigits])\n'
|
|
jpayne@68
|
9598 'object.__trunc__(self)\n'
|
|
jpayne@68
|
9599 'object.__floor__(self)\n'
|
|
jpayne@68
|
9600 'object.__ceil__(self)\n'
|
|
jpayne@68
|
9601 '\n'
|
|
jpayne@68
|
9602 ' Called to implement the built-in function "round()" and '
|
|
jpayne@68
|
9603 '"math"\n'
|
|
jpayne@68
|
9604 ' functions "trunc()", "floor()" and "ceil()". Unless '
|
|
jpayne@68
|
9605 '*ndigits* is\n'
|
|
jpayne@68
|
9606 ' passed to "__round__()" all these methods should return '
|
|
jpayne@68
|
9607 'the value\n'
|
|
jpayne@68
|
9608 ' of the object truncated to an "Integral" (typically an '
|
|
jpayne@68
|
9609 '"int").\n'
|
|
jpayne@68
|
9610 '\n'
|
|
jpayne@68
|
9611 ' If "__int__()" is not defined then the built-in function '
|
|
jpayne@68
|
9612 '"int()"\n'
|
|
jpayne@68
|
9613 ' falls back to "__trunc__()".\n'
|
|
jpayne@68
|
9614 '\n'
|
|
jpayne@68
|
9615 '\n'
|
|
jpayne@68
|
9616 'With Statement Context Managers\n'
|
|
jpayne@68
|
9617 '===============================\n'
|
|
jpayne@68
|
9618 '\n'
|
|
jpayne@68
|
9619 'A *context manager* is an object that defines the runtime '
|
|
jpayne@68
|
9620 'context to\n'
|
|
jpayne@68
|
9621 'be established when executing a "with" statement. The '
|
|
jpayne@68
|
9622 'context manager\n'
|
|
jpayne@68
|
9623 'handles the entry into, and the exit from, the desired '
|
|
jpayne@68
|
9624 'runtime context\n'
|
|
jpayne@68
|
9625 'for the execution of the block of code. Context managers '
|
|
jpayne@68
|
9626 'are normally\n'
|
|
jpayne@68
|
9627 'invoked using the "with" statement (described in section The '
|
|
jpayne@68
|
9628 'with\n'
|
|
jpayne@68
|
9629 'statement), but can also be used by directly invoking their '
|
|
jpayne@68
|
9630 'methods.\n'
|
|
jpayne@68
|
9631 '\n'
|
|
jpayne@68
|
9632 'Typical uses of context managers include saving and '
|
|
jpayne@68
|
9633 'restoring various\n'
|
|
jpayne@68
|
9634 'kinds of global state, locking and unlocking resources, '
|
|
jpayne@68
|
9635 'closing opened\n'
|
|
jpayne@68
|
9636 'files, etc.\n'
|
|
jpayne@68
|
9637 '\n'
|
|
jpayne@68
|
9638 'For more information on context managers, see Context '
|
|
jpayne@68
|
9639 'Manager Types.\n'
|
|
jpayne@68
|
9640 '\n'
|
|
jpayne@68
|
9641 'object.__enter__(self)\n'
|
|
jpayne@68
|
9642 '\n'
|
|
jpayne@68
|
9643 ' Enter the runtime context related to this object. The '
|
|
jpayne@68
|
9644 '"with"\n'
|
|
jpayne@68
|
9645 ' statement will bind this method’s return value to the '
|
|
jpayne@68
|
9646 'target(s)\n'
|
|
jpayne@68
|
9647 ' specified in the "as" clause of the statement, if any.\n'
|
|
jpayne@68
|
9648 '\n'
|
|
jpayne@68
|
9649 'object.__exit__(self, exc_type, exc_value, traceback)\n'
|
|
jpayne@68
|
9650 '\n'
|
|
jpayne@68
|
9651 ' Exit the runtime context related to this object. The '
|
|
jpayne@68
|
9652 'parameters\n'
|
|
jpayne@68
|
9653 ' describe the exception that caused the context to be '
|
|
jpayne@68
|
9654 'exited. If the\n'
|
|
jpayne@68
|
9655 ' context was exited without an exception, all three '
|
|
jpayne@68
|
9656 'arguments will\n'
|
|
jpayne@68
|
9657 ' be "None".\n'
|
|
jpayne@68
|
9658 '\n'
|
|
jpayne@68
|
9659 ' If an exception is supplied, and the method wishes to '
|
|
jpayne@68
|
9660 'suppress the\n'
|
|
jpayne@68
|
9661 ' exception (i.e., prevent it from being propagated), it '
|
|
jpayne@68
|
9662 'should\n'
|
|
jpayne@68
|
9663 ' return a true value. Otherwise, the exception will be '
|
|
jpayne@68
|
9664 'processed\n'
|
|
jpayne@68
|
9665 ' normally upon exit from this method.\n'
|
|
jpayne@68
|
9666 '\n'
|
|
jpayne@68
|
9667 ' Note that "__exit__()" methods should not reraise the '
|
|
jpayne@68
|
9668 'passed-in\n'
|
|
jpayne@68
|
9669 ' exception; this is the caller’s responsibility.\n'
|
|
jpayne@68
|
9670 '\n'
|
|
jpayne@68
|
9671 'See also:\n'
|
|
jpayne@68
|
9672 '\n'
|
|
jpayne@68
|
9673 ' **PEP 343** - The “with” statement\n'
|
|
jpayne@68
|
9674 ' The specification, background, and examples for the '
|
|
jpayne@68
|
9675 'Python "with"\n'
|
|
jpayne@68
|
9676 ' statement.\n'
|
|
jpayne@68
|
9677 '\n'
|
|
jpayne@68
|
9678 '\n'
|
|
jpayne@68
|
9679 'Special method lookup\n'
|
|
jpayne@68
|
9680 '=====================\n'
|
|
jpayne@68
|
9681 '\n'
|
|
jpayne@68
|
9682 'For custom classes, implicit invocations of special methods '
|
|
jpayne@68
|
9683 'are only\n'
|
|
jpayne@68
|
9684 'guaranteed to work correctly if defined on an object’s type, '
|
|
jpayne@68
|
9685 'not in\n'
|
|
jpayne@68
|
9686 'the object’s instance dictionary. That behaviour is the '
|
|
jpayne@68
|
9687 'reason why\n'
|
|
jpayne@68
|
9688 'the following code raises an exception:\n'
|
|
jpayne@68
|
9689 '\n'
|
|
jpayne@68
|
9690 ' >>> class C:\n'
|
|
jpayne@68
|
9691 ' ... pass\n'
|
|
jpayne@68
|
9692 ' ...\n'
|
|
jpayne@68
|
9693 ' >>> c = C()\n'
|
|
jpayne@68
|
9694 ' >>> c.__len__ = lambda: 5\n'
|
|
jpayne@68
|
9695 ' >>> len(c)\n'
|
|
jpayne@68
|
9696 ' Traceback (most recent call last):\n'
|
|
jpayne@68
|
9697 ' File "<stdin>", line 1, in <module>\n'
|
|
jpayne@68
|
9698 " TypeError: object of type 'C' has no len()\n"
|
|
jpayne@68
|
9699 '\n'
|
|
jpayne@68
|
9700 'The rationale behind this behaviour lies with a number of '
|
|
jpayne@68
|
9701 'special\n'
|
|
jpayne@68
|
9702 'methods such as "__hash__()" and "__repr__()" that are '
|
|
jpayne@68
|
9703 'implemented by\n'
|
|
jpayne@68
|
9704 'all objects, including type objects. If the implicit lookup '
|
|
jpayne@68
|
9705 'of these\n'
|
|
jpayne@68
|
9706 'methods used the conventional lookup process, they would '
|
|
jpayne@68
|
9707 'fail when\n'
|
|
jpayne@68
|
9708 'invoked on the type object itself:\n'
|
|
jpayne@68
|
9709 '\n'
|
|
jpayne@68
|
9710 ' >>> 1 .__hash__() == hash(1)\n'
|
|
jpayne@68
|
9711 ' True\n'
|
|
jpayne@68
|
9712 ' >>> int.__hash__() == hash(int)\n'
|
|
jpayne@68
|
9713 ' Traceback (most recent call last):\n'
|
|
jpayne@68
|
9714 ' File "<stdin>", line 1, in <module>\n'
|
|
jpayne@68
|
9715 " TypeError: descriptor '__hash__' of 'int' object needs an "
|
|
jpayne@68
|
9716 'argument\n'
|
|
jpayne@68
|
9717 '\n'
|
|
jpayne@68
|
9718 'Incorrectly attempting to invoke an unbound method of a '
|
|
jpayne@68
|
9719 'class in this\n'
|
|
jpayne@68
|
9720 'way is sometimes referred to as ‘metaclass confusion’, and '
|
|
jpayne@68
|
9721 'is avoided\n'
|
|
jpayne@68
|
9722 'by bypassing the instance when looking up special methods:\n'
|
|
jpayne@68
|
9723 '\n'
|
|
jpayne@68
|
9724 ' >>> type(1).__hash__(1) == hash(1)\n'
|
|
jpayne@68
|
9725 ' True\n'
|
|
jpayne@68
|
9726 ' >>> type(int).__hash__(int) == hash(int)\n'
|
|
jpayne@68
|
9727 ' True\n'
|
|
jpayne@68
|
9728 '\n'
|
|
jpayne@68
|
9729 'In addition to bypassing any instance attributes in the '
|
|
jpayne@68
|
9730 'interest of\n'
|
|
jpayne@68
|
9731 'correctness, implicit special method lookup generally also '
|
|
jpayne@68
|
9732 'bypasses\n'
|
|
jpayne@68
|
9733 'the "__getattribute__()" method even of the object’s '
|
|
jpayne@68
|
9734 'metaclass:\n'
|
|
jpayne@68
|
9735 '\n'
|
|
jpayne@68
|
9736 ' >>> class Meta(type):\n'
|
|
jpayne@68
|
9737 ' ... def __getattribute__(*args):\n'
|
|
jpayne@68
|
9738 ' ... print("Metaclass getattribute invoked")\n'
|
|
jpayne@68
|
9739 ' ... return type.__getattribute__(*args)\n'
|
|
jpayne@68
|
9740 ' ...\n'
|
|
jpayne@68
|
9741 ' >>> class C(object, metaclass=Meta):\n'
|
|
jpayne@68
|
9742 ' ... def __len__(self):\n'
|
|
jpayne@68
|
9743 ' ... return 10\n'
|
|
jpayne@68
|
9744 ' ... def __getattribute__(*args):\n'
|
|
jpayne@68
|
9745 ' ... print("Class getattribute invoked")\n'
|
|
jpayne@68
|
9746 ' ... return object.__getattribute__(*args)\n'
|
|
jpayne@68
|
9747 ' ...\n'
|
|
jpayne@68
|
9748 ' >>> c = C()\n'
|
|
jpayne@68
|
9749 ' >>> c.__len__() # Explicit lookup via '
|
|
jpayne@68
|
9750 'instance\n'
|
|
jpayne@68
|
9751 ' Class getattribute invoked\n'
|
|
jpayne@68
|
9752 ' 10\n'
|
|
jpayne@68
|
9753 ' >>> type(c).__len__(c) # Explicit lookup via '
|
|
jpayne@68
|
9754 'type\n'
|
|
jpayne@68
|
9755 ' Metaclass getattribute invoked\n'
|
|
jpayne@68
|
9756 ' 10\n'
|
|
jpayne@68
|
9757 ' >>> len(c) # Implicit lookup\n'
|
|
jpayne@68
|
9758 ' 10\n'
|
|
jpayne@68
|
9759 '\n'
|
|
jpayne@68
|
9760 'Bypassing the "__getattribute__()" machinery in this fashion '
|
|
jpayne@68
|
9761 'provides\n'
|
|
jpayne@68
|
9762 'significant scope for speed optimisations within the '
|
|
jpayne@68
|
9763 'interpreter, at\n'
|
|
jpayne@68
|
9764 'the cost of some flexibility in the handling of special '
|
|
jpayne@68
|
9765 'methods (the\n'
|
|
jpayne@68
|
9766 'special method *must* be set on the class object itself in '
|
|
jpayne@68
|
9767 'order to be\n'
|
|
jpayne@68
|
9768 'consistently invoked by the interpreter).\n',
|
|
jpayne@68
|
9769 'string-methods': 'String Methods\n'
|
|
jpayne@68
|
9770 '**************\n'
|
|
jpayne@68
|
9771 '\n'
|
|
jpayne@68
|
9772 'Strings implement all of the common sequence operations, '
|
|
jpayne@68
|
9773 'along with\n'
|
|
jpayne@68
|
9774 'the additional methods described below.\n'
|
|
jpayne@68
|
9775 '\n'
|
|
jpayne@68
|
9776 'Strings also support two styles of string formatting, one '
|
|
jpayne@68
|
9777 'providing a\n'
|
|
jpayne@68
|
9778 'large degree of flexibility and customization (see '
|
|
jpayne@68
|
9779 '"str.format()",\n'
|
|
jpayne@68
|
9780 'Format String Syntax and Custom String Formatting) and the '
|
|
jpayne@68
|
9781 'other based\n'
|
|
jpayne@68
|
9782 'on C "printf" style formatting that handles a narrower '
|
|
jpayne@68
|
9783 'range of types\n'
|
|
jpayne@68
|
9784 'and is slightly harder to use correctly, but is often '
|
|
jpayne@68
|
9785 'faster for the\n'
|
|
jpayne@68
|
9786 'cases it can handle (printf-style String Formatting).\n'
|
|
jpayne@68
|
9787 '\n'
|
|
jpayne@68
|
9788 'The Text Processing Services section of the standard '
|
|
jpayne@68
|
9789 'library covers a\n'
|
|
jpayne@68
|
9790 'number of other modules that provide various text related '
|
|
jpayne@68
|
9791 'utilities\n'
|
|
jpayne@68
|
9792 '(including regular expression support in the "re" '
|
|
jpayne@68
|
9793 'module).\n'
|
|
jpayne@68
|
9794 '\n'
|
|
jpayne@68
|
9795 'str.capitalize()\n'
|
|
jpayne@68
|
9796 '\n'
|
|
jpayne@68
|
9797 ' Return a copy of the string with its first character '
|
|
jpayne@68
|
9798 'capitalized\n'
|
|
jpayne@68
|
9799 ' and the rest lowercased.\n'
|
|
jpayne@68
|
9800 '\n'
|
|
jpayne@68
|
9801 ' Changed in version 3.8: The first character is now put '
|
|
jpayne@68
|
9802 'into\n'
|
|
jpayne@68
|
9803 ' titlecase rather than uppercase. This means that '
|
|
jpayne@68
|
9804 'characters like\n'
|
|
jpayne@68
|
9805 ' digraphs will only have their first letter capitalized, '
|
|
jpayne@68
|
9806 'instead of\n'
|
|
jpayne@68
|
9807 ' the full character.\n'
|
|
jpayne@68
|
9808 '\n'
|
|
jpayne@68
|
9809 'str.casefold()\n'
|
|
jpayne@68
|
9810 '\n'
|
|
jpayne@68
|
9811 ' Return a casefolded copy of the string. Casefolded '
|
|
jpayne@68
|
9812 'strings may be\n'
|
|
jpayne@68
|
9813 ' used for caseless matching.\n'
|
|
jpayne@68
|
9814 '\n'
|
|
jpayne@68
|
9815 ' Casefolding is similar to lowercasing but more '
|
|
jpayne@68
|
9816 'aggressive because\n'
|
|
jpayne@68
|
9817 ' it is intended to remove all case distinctions in a '
|
|
jpayne@68
|
9818 'string. For\n'
|
|
jpayne@68
|
9819 ' example, the German lowercase letter "\'ß\'" is '
|
|
jpayne@68
|
9820 'equivalent to ""ss"".\n'
|
|
jpayne@68
|
9821 ' Since it is already lowercase, "lower()" would do '
|
|
jpayne@68
|
9822 'nothing to "\'ß\'";\n'
|
|
jpayne@68
|
9823 ' "casefold()" converts it to ""ss"".\n'
|
|
jpayne@68
|
9824 '\n'
|
|
jpayne@68
|
9825 ' The casefolding algorithm is described in section 3.13 '
|
|
jpayne@68
|
9826 'of the\n'
|
|
jpayne@68
|
9827 ' Unicode Standard.\n'
|
|
jpayne@68
|
9828 '\n'
|
|
jpayne@68
|
9829 ' New in version 3.3.\n'
|
|
jpayne@68
|
9830 '\n'
|
|
jpayne@68
|
9831 'str.center(width[, fillchar])\n'
|
|
jpayne@68
|
9832 '\n'
|
|
jpayne@68
|
9833 ' Return centered in a string of length *width*. Padding '
|
|
jpayne@68
|
9834 'is done\n'
|
|
jpayne@68
|
9835 ' using the specified *fillchar* (default is an ASCII '
|
|
jpayne@68
|
9836 'space). The\n'
|
|
jpayne@68
|
9837 ' original string is returned if *width* is less than or '
|
|
jpayne@68
|
9838 'equal to\n'
|
|
jpayne@68
|
9839 ' "len(s)".\n'
|
|
jpayne@68
|
9840 '\n'
|
|
jpayne@68
|
9841 'str.count(sub[, start[, end]])\n'
|
|
jpayne@68
|
9842 '\n'
|
|
jpayne@68
|
9843 ' Return the number of non-overlapping occurrences of '
|
|
jpayne@68
|
9844 'substring *sub*\n'
|
|
jpayne@68
|
9845 ' in the range [*start*, *end*]. Optional arguments '
|
|
jpayne@68
|
9846 '*start* and\n'
|
|
jpayne@68
|
9847 ' *end* are interpreted as in slice notation.\n'
|
|
jpayne@68
|
9848 '\n'
|
|
jpayne@68
|
9849 'str.encode(encoding="utf-8", errors="strict")\n'
|
|
jpayne@68
|
9850 '\n'
|
|
jpayne@68
|
9851 ' Return an encoded version of the string as a bytes '
|
|
jpayne@68
|
9852 'object. Default\n'
|
|
jpayne@68
|
9853 ' encoding is "\'utf-8\'". *errors* may be given to set a '
|
|
jpayne@68
|
9854 'different\n'
|
|
jpayne@68
|
9855 ' error handling scheme. The default for *errors* is '
|
|
jpayne@68
|
9856 '"\'strict\'",\n'
|
|
jpayne@68
|
9857 ' meaning that encoding errors raise a "UnicodeError". '
|
|
jpayne@68
|
9858 'Other possible\n'
|
|
jpayne@68
|
9859 ' values are "\'ignore\'", "\'replace\'", '
|
|
jpayne@68
|
9860 '"\'xmlcharrefreplace\'",\n'
|
|
jpayne@68
|
9861 ' "\'backslashreplace\'" and any other name registered '
|
|
jpayne@68
|
9862 'via\n'
|
|
jpayne@68
|
9863 ' "codecs.register_error()", see section Error Handlers. '
|
|
jpayne@68
|
9864 'For a list\n'
|
|
jpayne@68
|
9865 ' of possible encodings, see section Standard Encodings.\n'
|
|
jpayne@68
|
9866 '\n'
|
|
jpayne@68
|
9867 ' Changed in version 3.1: Support for keyword arguments '
|
|
jpayne@68
|
9868 'added.\n'
|
|
jpayne@68
|
9869 '\n'
|
|
jpayne@68
|
9870 'str.endswith(suffix[, start[, end]])\n'
|
|
jpayne@68
|
9871 '\n'
|
|
jpayne@68
|
9872 ' Return "True" if the string ends with the specified '
|
|
jpayne@68
|
9873 '*suffix*,\n'
|
|
jpayne@68
|
9874 ' otherwise return "False". *suffix* can also be a tuple '
|
|
jpayne@68
|
9875 'of suffixes\n'
|
|
jpayne@68
|
9876 ' to look for. With optional *start*, test beginning at '
|
|
jpayne@68
|
9877 'that\n'
|
|
jpayne@68
|
9878 ' position. With optional *end*, stop comparing at that '
|
|
jpayne@68
|
9879 'position.\n'
|
|
jpayne@68
|
9880 '\n'
|
|
jpayne@68
|
9881 'str.expandtabs(tabsize=8)\n'
|
|
jpayne@68
|
9882 '\n'
|
|
jpayne@68
|
9883 ' Return a copy of the string where all tab characters '
|
|
jpayne@68
|
9884 'are replaced\n'
|
|
jpayne@68
|
9885 ' by one or more spaces, depending on the current column '
|
|
jpayne@68
|
9886 'and the\n'
|
|
jpayne@68
|
9887 ' given tab size. Tab positions occur every *tabsize* '
|
|
jpayne@68
|
9888 'characters\n'
|
|
jpayne@68
|
9889 ' (default is 8, giving tab positions at columns 0, 8, 16 '
|
|
jpayne@68
|
9890 'and so on).\n'
|
|
jpayne@68
|
9891 ' To expand the string, the current column is set to zero '
|
|
jpayne@68
|
9892 'and the\n'
|
|
jpayne@68
|
9893 ' string is examined character by character. If the '
|
|
jpayne@68
|
9894 'character is a\n'
|
|
jpayne@68
|
9895 ' tab ("\\t"), one or more space characters are inserted '
|
|
jpayne@68
|
9896 'in the result\n'
|
|
jpayne@68
|
9897 ' until the current column is equal to the next tab '
|
|
jpayne@68
|
9898 'position. (The\n'
|
|
jpayne@68
|
9899 ' tab character itself is not copied.) If the character '
|
|
jpayne@68
|
9900 'is a newline\n'
|
|
jpayne@68
|
9901 ' ("\\n") or return ("\\r"), it is copied and the current '
|
|
jpayne@68
|
9902 'column is\n'
|
|
jpayne@68
|
9903 ' reset to zero. Any other character is copied unchanged '
|
|
jpayne@68
|
9904 'and the\n'
|
|
jpayne@68
|
9905 ' current column is incremented by one regardless of how '
|
|
jpayne@68
|
9906 'the\n'
|
|
jpayne@68
|
9907 ' character is represented when printed.\n'
|
|
jpayne@68
|
9908 '\n'
|
|
jpayne@68
|
9909 " >>> '01\\t012\\t0123\\t01234'.expandtabs()\n"
|
|
jpayne@68
|
9910 " '01 012 0123 01234'\n"
|
|
jpayne@68
|
9911 " >>> '01\\t012\\t0123\\t01234'.expandtabs(4)\n"
|
|
jpayne@68
|
9912 " '01 012 0123 01234'\n"
|
|
jpayne@68
|
9913 '\n'
|
|
jpayne@68
|
9914 'str.find(sub[, start[, end]])\n'
|
|
jpayne@68
|
9915 '\n'
|
|
jpayne@68
|
9916 ' Return the lowest index in the string where substring '
|
|
jpayne@68
|
9917 '*sub* is\n'
|
|
jpayne@68
|
9918 ' found within the slice "s[start:end]". Optional '
|
|
jpayne@68
|
9919 'arguments *start*\n'
|
|
jpayne@68
|
9920 ' and *end* are interpreted as in slice notation. Return '
|
|
jpayne@68
|
9921 '"-1" if\n'
|
|
jpayne@68
|
9922 ' *sub* is not found.\n'
|
|
jpayne@68
|
9923 '\n'
|
|
jpayne@68
|
9924 ' Note: The "find()" method should be used only if you '
|
|
jpayne@68
|
9925 'need to know\n'
|
|
jpayne@68
|
9926 ' the position of *sub*. To check if *sub* is a '
|
|
jpayne@68
|
9927 'substring or not,\n'
|
|
jpayne@68
|
9928 ' use the "in" operator:\n'
|
|
jpayne@68
|
9929 '\n'
|
|
jpayne@68
|
9930 " >>> 'Py' in 'Python'\n"
|
|
jpayne@68
|
9931 ' True\n'
|
|
jpayne@68
|
9932 '\n'
|
|
jpayne@68
|
9933 'str.format(*args, **kwargs)\n'
|
|
jpayne@68
|
9934 '\n'
|
|
jpayne@68
|
9935 ' Perform a string formatting operation. The string on '
|
|
jpayne@68
|
9936 'which this\n'
|
|
jpayne@68
|
9937 ' method is called can contain literal text or '
|
|
jpayne@68
|
9938 'replacement fields\n'
|
|
jpayne@68
|
9939 ' delimited by braces "{}". Each replacement field '
|
|
jpayne@68
|
9940 'contains either\n'
|
|
jpayne@68
|
9941 ' the numeric index of a positional argument, or the name '
|
|
jpayne@68
|
9942 'of a\n'
|
|
jpayne@68
|
9943 ' keyword argument. Returns a copy of the string where '
|
|
jpayne@68
|
9944 'each\n'
|
|
jpayne@68
|
9945 ' replacement field is replaced with the string value of '
|
|
jpayne@68
|
9946 'the\n'
|
|
jpayne@68
|
9947 ' corresponding argument.\n'
|
|
jpayne@68
|
9948 '\n'
|
|
jpayne@68
|
9949 ' >>> "The sum of 1 + 2 is {0}".format(1+2)\n'
|
|
jpayne@68
|
9950 " 'The sum of 1 + 2 is 3'\n"
|
|
jpayne@68
|
9951 '\n'
|
|
jpayne@68
|
9952 ' See Format String Syntax for a description of the '
|
|
jpayne@68
|
9953 'various\n'
|
|
jpayne@68
|
9954 ' formatting options that can be specified in format '
|
|
jpayne@68
|
9955 'strings.\n'
|
|
jpayne@68
|
9956 '\n'
|
|
jpayne@68
|
9957 ' Note: When formatting a number ("int", "float", '
|
|
jpayne@68
|
9958 '"complex",\n'
|
|
jpayne@68
|
9959 ' "decimal.Decimal" and subclasses) with the "n" type '
|
|
jpayne@68
|
9960 '(ex:\n'
|
|
jpayne@68
|
9961 ' "\'{:n}\'.format(1234)"), the function temporarily '
|
|
jpayne@68
|
9962 'sets the\n'
|
|
jpayne@68
|
9963 ' "LC_CTYPE" locale to the "LC_NUMERIC" locale to '
|
|
jpayne@68
|
9964 'decode\n'
|
|
jpayne@68
|
9965 ' "decimal_point" and "thousands_sep" fields of '
|
|
jpayne@68
|
9966 '"localeconv()" if\n'
|
|
jpayne@68
|
9967 ' they are non-ASCII or longer than 1 byte, and the '
|
|
jpayne@68
|
9968 '"LC_NUMERIC"\n'
|
|
jpayne@68
|
9969 ' locale is different than the "LC_CTYPE" locale. This '
|
|
jpayne@68
|
9970 'temporary\n'
|
|
jpayne@68
|
9971 ' change affects other threads.\n'
|
|
jpayne@68
|
9972 '\n'
|
|
jpayne@68
|
9973 ' Changed in version 3.7: When formatting a number with '
|
|
jpayne@68
|
9974 'the "n" type,\n'
|
|
jpayne@68
|
9975 ' the function sets temporarily the "LC_CTYPE" locale to '
|
|
jpayne@68
|
9976 'the\n'
|
|
jpayne@68
|
9977 ' "LC_NUMERIC" locale in some cases.\n'
|
|
jpayne@68
|
9978 '\n'
|
|
jpayne@68
|
9979 'str.format_map(mapping)\n'
|
|
jpayne@68
|
9980 '\n'
|
|
jpayne@68
|
9981 ' Similar to "str.format(**mapping)", except that '
|
|
jpayne@68
|
9982 '"mapping" is used\n'
|
|
jpayne@68
|
9983 ' directly and not copied to a "dict". This is useful if '
|
|
jpayne@68
|
9984 'for example\n'
|
|
jpayne@68
|
9985 ' "mapping" is a dict subclass:\n'
|
|
jpayne@68
|
9986 '\n'
|
|
jpayne@68
|
9987 ' >>> class Default(dict):\n'
|
|
jpayne@68
|
9988 ' ... def __missing__(self, key):\n'
|
|
jpayne@68
|
9989 ' ... return key\n'
|
|
jpayne@68
|
9990 ' ...\n'
|
|
jpayne@68
|
9991 " >>> '{name} was born in "
|
|
jpayne@68
|
9992 "{country}'.format_map(Default(name='Guido'))\n"
|
|
jpayne@68
|
9993 " 'Guido was born in country'\n"
|
|
jpayne@68
|
9994 '\n'
|
|
jpayne@68
|
9995 ' New in version 3.2.\n'
|
|
jpayne@68
|
9996 '\n'
|
|
jpayne@68
|
9997 'str.index(sub[, start[, end]])\n'
|
|
jpayne@68
|
9998 '\n'
|
|
jpayne@68
|
9999 ' Like "find()", but raise "ValueError" when the '
|
|
jpayne@68
|
10000 'substring is not\n'
|
|
jpayne@68
|
10001 ' found.\n'
|
|
jpayne@68
|
10002 '\n'
|
|
jpayne@68
|
10003 'str.isalnum()\n'
|
|
jpayne@68
|
10004 '\n'
|
|
jpayne@68
|
10005 ' Return "True" if all characters in the string are '
|
|
jpayne@68
|
10006 'alphanumeric and\n'
|
|
jpayne@68
|
10007 ' there is at least one character, "False" otherwise. A '
|
|
jpayne@68
|
10008 'character\n'
|
|
jpayne@68
|
10009 ' "c" is alphanumeric if one of the following returns '
|
|
jpayne@68
|
10010 '"True":\n'
|
|
jpayne@68
|
10011 ' "c.isalpha()", "c.isdecimal()", "c.isdigit()", or '
|
|
jpayne@68
|
10012 '"c.isnumeric()".\n'
|
|
jpayne@68
|
10013 '\n'
|
|
jpayne@68
|
10014 'str.isalpha()\n'
|
|
jpayne@68
|
10015 '\n'
|
|
jpayne@68
|
10016 ' Return "True" if all characters in the string are '
|
|
jpayne@68
|
10017 'alphabetic and\n'
|
|
jpayne@68
|
10018 ' there is at least one character, "False" otherwise. '
|
|
jpayne@68
|
10019 'Alphabetic\n'
|
|
jpayne@68
|
10020 ' characters are those characters defined in the Unicode '
|
|
jpayne@68
|
10021 'character\n'
|
|
jpayne@68
|
10022 ' database as “Letter”, i.e., those with general category '
|
|
jpayne@68
|
10023 'property\n'
|
|
jpayne@68
|
10024 ' being one of “Lm”, “Lt”, “Lu”, “Ll”, or “Lo”. Note '
|
|
jpayne@68
|
10025 'that this is\n'
|
|
jpayne@68
|
10026 ' different from the “Alphabetic” property defined in the '
|
|
jpayne@68
|
10027 'Unicode\n'
|
|
jpayne@68
|
10028 ' Standard.\n'
|
|
jpayne@68
|
10029 '\n'
|
|
jpayne@68
|
10030 'str.isascii()\n'
|
|
jpayne@68
|
10031 '\n'
|
|
jpayne@68
|
10032 ' Return "True" if the string is empty or all characters '
|
|
jpayne@68
|
10033 'in the\n'
|
|
jpayne@68
|
10034 ' string are ASCII, "False" otherwise. ASCII characters '
|
|
jpayne@68
|
10035 'have code\n'
|
|
jpayne@68
|
10036 ' points in the range U+0000-U+007F.\n'
|
|
jpayne@68
|
10037 '\n'
|
|
jpayne@68
|
10038 ' New in version 3.7.\n'
|
|
jpayne@68
|
10039 '\n'
|
|
jpayne@68
|
10040 'str.isdecimal()\n'
|
|
jpayne@68
|
10041 '\n'
|
|
jpayne@68
|
10042 ' Return "True" if all characters in the string are '
|
|
jpayne@68
|
10043 'decimal\n'
|
|
jpayne@68
|
10044 ' characters and there is at least one character, "False" '
|
|
jpayne@68
|
10045 'otherwise.\n'
|
|
jpayne@68
|
10046 ' Decimal characters are those that can be used to form '
|
|
jpayne@68
|
10047 'numbers in\n'
|
|
jpayne@68
|
10048 ' base 10, e.g. U+0660, ARABIC-INDIC DIGIT ZERO. '
|
|
jpayne@68
|
10049 'Formally a decimal\n'
|
|
jpayne@68
|
10050 ' character is a character in the Unicode General '
|
|
jpayne@68
|
10051 'Category “Nd”.\n'
|
|
jpayne@68
|
10052 '\n'
|
|
jpayne@68
|
10053 'str.isdigit()\n'
|
|
jpayne@68
|
10054 '\n'
|
|
jpayne@68
|
10055 ' Return "True" if all characters in the string are '
|
|
jpayne@68
|
10056 'digits and there\n'
|
|
jpayne@68
|
10057 ' is at least one character, "False" otherwise. Digits '
|
|
jpayne@68
|
10058 'include\n'
|
|
jpayne@68
|
10059 ' decimal characters and digits that need special '
|
|
jpayne@68
|
10060 'handling, such as\n'
|
|
jpayne@68
|
10061 ' the compatibility superscript digits. This covers '
|
|
jpayne@68
|
10062 'digits which\n'
|
|
jpayne@68
|
10063 ' cannot be used to form numbers in base 10, like the '
|
|
jpayne@68
|
10064 'Kharosthi\n'
|
|
jpayne@68
|
10065 ' numbers. Formally, a digit is a character that has the '
|
|
jpayne@68
|
10066 'property\n'
|
|
jpayne@68
|
10067 ' value Numeric_Type=Digit or Numeric_Type=Decimal.\n'
|
|
jpayne@68
|
10068 '\n'
|
|
jpayne@68
|
10069 'str.isidentifier()\n'
|
|
jpayne@68
|
10070 '\n'
|
|
jpayne@68
|
10071 ' Return "True" if the string is a valid identifier '
|
|
jpayne@68
|
10072 'according to the\n'
|
|
jpayne@68
|
10073 ' language definition, section Identifiers and keywords.\n'
|
|
jpayne@68
|
10074 '\n'
|
|
jpayne@68
|
10075 ' Call "keyword.iskeyword()" to test whether string "s" '
|
|
jpayne@68
|
10076 'is a reserved\n'
|
|
jpayne@68
|
10077 ' identifier, such as "def" and "class".\n'
|
|
jpayne@68
|
10078 '\n'
|
|
jpayne@68
|
10079 ' Example:\n'
|
|
jpayne@68
|
10080 '\n'
|
|
jpayne@68
|
10081 ' >>> from keyword import iskeyword\n'
|
|
jpayne@68
|
10082 '\n'
|
|
jpayne@68
|
10083 " >>> 'hello'.isidentifier(), iskeyword('hello')\n"
|
|
jpayne@68
|
10084 ' True, False\n'
|
|
jpayne@68
|
10085 " >>> 'def'.isidentifier(), iskeyword('def')\n"
|
|
jpayne@68
|
10086 ' True, True\n'
|
|
jpayne@68
|
10087 '\n'
|
|
jpayne@68
|
10088 'str.islower()\n'
|
|
jpayne@68
|
10089 '\n'
|
|
jpayne@68
|
10090 ' Return "True" if all cased characters [4] in the string '
|
|
jpayne@68
|
10091 'are\n'
|
|
jpayne@68
|
10092 ' lowercase and there is at least one cased character, '
|
|
jpayne@68
|
10093 '"False"\n'
|
|
jpayne@68
|
10094 ' otherwise.\n'
|
|
jpayne@68
|
10095 '\n'
|
|
jpayne@68
|
10096 'str.isnumeric()\n'
|
|
jpayne@68
|
10097 '\n'
|
|
jpayne@68
|
10098 ' Return "True" if all characters in the string are '
|
|
jpayne@68
|
10099 'numeric\n'
|
|
jpayne@68
|
10100 ' characters, and there is at least one character, '
|
|
jpayne@68
|
10101 '"False" otherwise.\n'
|
|
jpayne@68
|
10102 ' Numeric characters include digit characters, and all '
|
|
jpayne@68
|
10103 'characters\n'
|
|
jpayne@68
|
10104 ' that have the Unicode numeric value property, e.g. '
|
|
jpayne@68
|
10105 'U+2155, VULGAR\n'
|
|
jpayne@68
|
10106 ' FRACTION ONE FIFTH. Formally, numeric characters are '
|
|
jpayne@68
|
10107 'those with\n'
|
|
jpayne@68
|
10108 ' the property value Numeric_Type=Digit, '
|
|
jpayne@68
|
10109 'Numeric_Type=Decimal or\n'
|
|
jpayne@68
|
10110 ' Numeric_Type=Numeric.\n'
|
|
jpayne@68
|
10111 '\n'
|
|
jpayne@68
|
10112 'str.isprintable()\n'
|
|
jpayne@68
|
10113 '\n'
|
|
jpayne@68
|
10114 ' Return "True" if all characters in the string are '
|
|
jpayne@68
|
10115 'printable or the\n'
|
|
jpayne@68
|
10116 ' string is empty, "False" otherwise. Nonprintable '
|
|
jpayne@68
|
10117 'characters are\n'
|
|
jpayne@68
|
10118 ' those characters defined in the Unicode character '
|
|
jpayne@68
|
10119 'database as\n'
|
|
jpayne@68
|
10120 ' “Other” or “Separator”, excepting the ASCII space '
|
|
jpayne@68
|
10121 '(0x20) which is\n'
|
|
jpayne@68
|
10122 ' considered printable. (Note that printable characters '
|
|
jpayne@68
|
10123 'in this\n'
|
|
jpayne@68
|
10124 ' context are those which should not be escaped when '
|
|
jpayne@68
|
10125 '"repr()" is\n'
|
|
jpayne@68
|
10126 ' invoked on a string. It has no bearing on the handling '
|
|
jpayne@68
|
10127 'of strings\n'
|
|
jpayne@68
|
10128 ' written to "sys.stdout" or "sys.stderr".)\n'
|
|
jpayne@68
|
10129 '\n'
|
|
jpayne@68
|
10130 'str.isspace()\n'
|
|
jpayne@68
|
10131 '\n'
|
|
jpayne@68
|
10132 ' Return "True" if there are only whitespace characters '
|
|
jpayne@68
|
10133 'in the string\n'
|
|
jpayne@68
|
10134 ' and there is at least one character, "False" '
|
|
jpayne@68
|
10135 'otherwise.\n'
|
|
jpayne@68
|
10136 '\n'
|
|
jpayne@68
|
10137 ' A character is *whitespace* if in the Unicode character '
|
|
jpayne@68
|
10138 'database\n'
|
|
jpayne@68
|
10139 ' (see "unicodedata"), either its general category is '
|
|
jpayne@68
|
10140 '"Zs"\n'
|
|
jpayne@68
|
10141 ' (“Separator, space”), or its bidirectional class is one '
|
|
jpayne@68
|
10142 'of "WS",\n'
|
|
jpayne@68
|
10143 ' "B", or "S".\n'
|
|
jpayne@68
|
10144 '\n'
|
|
jpayne@68
|
10145 'str.istitle()\n'
|
|
jpayne@68
|
10146 '\n'
|
|
jpayne@68
|
10147 ' Return "True" if the string is a titlecased string and '
|
|
jpayne@68
|
10148 'there is at\n'
|
|
jpayne@68
|
10149 ' least one character, for example uppercase characters '
|
|
jpayne@68
|
10150 'may only\n'
|
|
jpayne@68
|
10151 ' follow uncased characters and lowercase characters only '
|
|
jpayne@68
|
10152 'cased ones.\n'
|
|
jpayne@68
|
10153 ' Return "False" otherwise.\n'
|
|
jpayne@68
|
10154 '\n'
|
|
jpayne@68
|
10155 'str.isupper()\n'
|
|
jpayne@68
|
10156 '\n'
|
|
jpayne@68
|
10157 ' Return "True" if all cased characters [4] in the string '
|
|
jpayne@68
|
10158 'are\n'
|
|
jpayne@68
|
10159 ' uppercase and there is at least one cased character, '
|
|
jpayne@68
|
10160 '"False"\n'
|
|
jpayne@68
|
10161 ' otherwise.\n'
|
|
jpayne@68
|
10162 '\n'
|
|
jpayne@68
|
10163 'str.join(iterable)\n'
|
|
jpayne@68
|
10164 '\n'
|
|
jpayne@68
|
10165 ' Return a string which is the concatenation of the '
|
|
jpayne@68
|
10166 'strings in\n'
|
|
jpayne@68
|
10167 ' *iterable*. A "TypeError" will be raised if there are '
|
|
jpayne@68
|
10168 'any non-\n'
|
|
jpayne@68
|
10169 ' string values in *iterable*, including "bytes" '
|
|
jpayne@68
|
10170 'objects. The\n'
|
|
jpayne@68
|
10171 ' separator between elements is the string providing this '
|
|
jpayne@68
|
10172 'method.\n'
|
|
jpayne@68
|
10173 '\n'
|
|
jpayne@68
|
10174 'str.ljust(width[, fillchar])\n'
|
|
jpayne@68
|
10175 '\n'
|
|
jpayne@68
|
10176 ' Return the string left justified in a string of length '
|
|
jpayne@68
|
10177 '*width*.\n'
|
|
jpayne@68
|
10178 ' Padding is done using the specified *fillchar* (default '
|
|
jpayne@68
|
10179 'is an ASCII\n'
|
|
jpayne@68
|
10180 ' space). The original string is returned if *width* is '
|
|
jpayne@68
|
10181 'less than or\n'
|
|
jpayne@68
|
10182 ' equal to "len(s)".\n'
|
|
jpayne@68
|
10183 '\n'
|
|
jpayne@68
|
10184 'str.lower()\n'
|
|
jpayne@68
|
10185 '\n'
|
|
jpayne@68
|
10186 ' Return a copy of the string with all the cased '
|
|
jpayne@68
|
10187 'characters [4]\n'
|
|
jpayne@68
|
10188 ' converted to lowercase.\n'
|
|
jpayne@68
|
10189 '\n'
|
|
jpayne@68
|
10190 ' The lowercasing algorithm used is described in section '
|
|
jpayne@68
|
10191 '3.13 of the\n'
|
|
jpayne@68
|
10192 ' Unicode Standard.\n'
|
|
jpayne@68
|
10193 '\n'
|
|
jpayne@68
|
10194 'str.lstrip([chars])\n'
|
|
jpayne@68
|
10195 '\n'
|
|
jpayne@68
|
10196 ' Return a copy of the string with leading characters '
|
|
jpayne@68
|
10197 'removed. The\n'
|
|
jpayne@68
|
10198 ' *chars* argument is a string specifying the set of '
|
|
jpayne@68
|
10199 'characters to be\n'
|
|
jpayne@68
|
10200 ' removed. If omitted or "None", the *chars* argument '
|
|
jpayne@68
|
10201 'defaults to\n'
|
|
jpayne@68
|
10202 ' removing whitespace. The *chars* argument is not a '
|
|
jpayne@68
|
10203 'prefix; rather,\n'
|
|
jpayne@68
|
10204 ' all combinations of its values are stripped:\n'
|
|
jpayne@68
|
10205 '\n'
|
|
jpayne@68
|
10206 " >>> ' spacious '.lstrip()\n"
|
|
jpayne@68
|
10207 " 'spacious '\n"
|
|
jpayne@68
|
10208 " >>> 'www.example.com'.lstrip('cmowz.')\n"
|
|
jpayne@68
|
10209 " 'example.com'\n"
|
|
jpayne@68
|
10210 '\n'
|
|
jpayne@68
|
10211 'static str.maketrans(x[, y[, z]])\n'
|
|
jpayne@68
|
10212 '\n'
|
|
jpayne@68
|
10213 ' This static method returns a translation table usable '
|
|
jpayne@68
|
10214 'for\n'
|
|
jpayne@68
|
10215 ' "str.translate()".\n'
|
|
jpayne@68
|
10216 '\n'
|
|
jpayne@68
|
10217 ' If there is only one argument, it must be a dictionary '
|
|
jpayne@68
|
10218 'mapping\n'
|
|
jpayne@68
|
10219 ' Unicode ordinals (integers) or characters (strings of '
|
|
jpayne@68
|
10220 'length 1) to\n'
|
|
jpayne@68
|
10221 ' Unicode ordinals, strings (of arbitrary lengths) or '
|
|
jpayne@68
|
10222 '"None".\n'
|
|
jpayne@68
|
10223 ' Character keys will then be converted to ordinals.\n'
|
|
jpayne@68
|
10224 '\n'
|
|
jpayne@68
|
10225 ' If there are two arguments, they must be strings of '
|
|
jpayne@68
|
10226 'equal length,\n'
|
|
jpayne@68
|
10227 ' and in the resulting dictionary, each character in x '
|
|
jpayne@68
|
10228 'will be mapped\n'
|
|
jpayne@68
|
10229 ' to the character at the same position in y. If there '
|
|
jpayne@68
|
10230 'is a third\n'
|
|
jpayne@68
|
10231 ' argument, it must be a string, whose characters will be '
|
|
jpayne@68
|
10232 'mapped to\n'
|
|
jpayne@68
|
10233 ' "None" in the result.\n'
|
|
jpayne@68
|
10234 '\n'
|
|
jpayne@68
|
10235 'str.partition(sep)\n'
|
|
jpayne@68
|
10236 '\n'
|
|
jpayne@68
|
10237 ' Split the string at the first occurrence of *sep*, and '
|
|
jpayne@68
|
10238 'return a\n'
|
|
jpayne@68
|
10239 ' 3-tuple containing the part before the separator, the '
|
|
jpayne@68
|
10240 'separator\n'
|
|
jpayne@68
|
10241 ' itself, and the part after the separator. If the '
|
|
jpayne@68
|
10242 'separator is not\n'
|
|
jpayne@68
|
10243 ' found, return a 3-tuple containing the string itself, '
|
|
jpayne@68
|
10244 'followed by\n'
|
|
jpayne@68
|
10245 ' two empty strings.\n'
|
|
jpayne@68
|
10246 '\n'
|
|
jpayne@68
|
10247 'str.replace(old, new[, count])\n'
|
|
jpayne@68
|
10248 '\n'
|
|
jpayne@68
|
10249 ' Return a copy of the string with all occurrences of '
|
|
jpayne@68
|
10250 'substring *old*\n'
|
|
jpayne@68
|
10251 ' replaced by *new*. If the optional argument *count* is '
|
|
jpayne@68
|
10252 'given, only\n'
|
|
jpayne@68
|
10253 ' the first *count* occurrences are replaced.\n'
|
|
jpayne@68
|
10254 '\n'
|
|
jpayne@68
|
10255 'str.rfind(sub[, start[, end]])\n'
|
|
jpayne@68
|
10256 '\n'
|
|
jpayne@68
|
10257 ' Return the highest index in the string where substring '
|
|
jpayne@68
|
10258 '*sub* is\n'
|
|
jpayne@68
|
10259 ' found, such that *sub* is contained within '
|
|
jpayne@68
|
10260 '"s[start:end]".\n'
|
|
jpayne@68
|
10261 ' Optional arguments *start* and *end* are interpreted as '
|
|
jpayne@68
|
10262 'in slice\n'
|
|
jpayne@68
|
10263 ' notation. Return "-1" on failure.\n'
|
|
jpayne@68
|
10264 '\n'
|
|
jpayne@68
|
10265 'str.rindex(sub[, start[, end]])\n'
|
|
jpayne@68
|
10266 '\n'
|
|
jpayne@68
|
10267 ' Like "rfind()" but raises "ValueError" when the '
|
|
jpayne@68
|
10268 'substring *sub* is\n'
|
|
jpayne@68
|
10269 ' not found.\n'
|
|
jpayne@68
|
10270 '\n'
|
|
jpayne@68
|
10271 'str.rjust(width[, fillchar])\n'
|
|
jpayne@68
|
10272 '\n'
|
|
jpayne@68
|
10273 ' Return the string right justified in a string of length '
|
|
jpayne@68
|
10274 '*width*.\n'
|
|
jpayne@68
|
10275 ' Padding is done using the specified *fillchar* (default '
|
|
jpayne@68
|
10276 'is an ASCII\n'
|
|
jpayne@68
|
10277 ' space). The original string is returned if *width* is '
|
|
jpayne@68
|
10278 'less than or\n'
|
|
jpayne@68
|
10279 ' equal to "len(s)".\n'
|
|
jpayne@68
|
10280 '\n'
|
|
jpayne@68
|
10281 'str.rpartition(sep)\n'
|
|
jpayne@68
|
10282 '\n'
|
|
jpayne@68
|
10283 ' Split the string at the last occurrence of *sep*, and '
|
|
jpayne@68
|
10284 'return a\n'
|
|
jpayne@68
|
10285 ' 3-tuple containing the part before the separator, the '
|
|
jpayne@68
|
10286 'separator\n'
|
|
jpayne@68
|
10287 ' itself, and the part after the separator. If the '
|
|
jpayne@68
|
10288 'separator is not\n'
|
|
jpayne@68
|
10289 ' found, return a 3-tuple containing two empty strings, '
|
|
jpayne@68
|
10290 'followed by\n'
|
|
jpayne@68
|
10291 ' the string itself.\n'
|
|
jpayne@68
|
10292 '\n'
|
|
jpayne@68
|
10293 'str.rsplit(sep=None, maxsplit=-1)\n'
|
|
jpayne@68
|
10294 '\n'
|
|
jpayne@68
|
10295 ' Return a list of the words in the string, using *sep* '
|
|
jpayne@68
|
10296 'as the\n'
|
|
jpayne@68
|
10297 ' delimiter string. If *maxsplit* is given, at most '
|
|
jpayne@68
|
10298 '*maxsplit* splits\n'
|
|
jpayne@68
|
10299 ' are done, the *rightmost* ones. If *sep* is not '
|
|
jpayne@68
|
10300 'specified or\n'
|
|
jpayne@68
|
10301 ' "None", any whitespace string is a separator. Except '
|
|
jpayne@68
|
10302 'for splitting\n'
|
|
jpayne@68
|
10303 ' from the right, "rsplit()" behaves like "split()" which '
|
|
jpayne@68
|
10304 'is\n'
|
|
jpayne@68
|
10305 ' described in detail below.\n'
|
|
jpayne@68
|
10306 '\n'
|
|
jpayne@68
|
10307 'str.rstrip([chars])\n'
|
|
jpayne@68
|
10308 '\n'
|
|
jpayne@68
|
10309 ' Return a copy of the string with trailing characters '
|
|
jpayne@68
|
10310 'removed. The\n'
|
|
jpayne@68
|
10311 ' *chars* argument is a string specifying the set of '
|
|
jpayne@68
|
10312 'characters to be\n'
|
|
jpayne@68
|
10313 ' removed. If omitted or "None", the *chars* argument '
|
|
jpayne@68
|
10314 'defaults to\n'
|
|
jpayne@68
|
10315 ' removing whitespace. The *chars* argument is not a '
|
|
jpayne@68
|
10316 'suffix; rather,\n'
|
|
jpayne@68
|
10317 ' all combinations of its values are stripped:\n'
|
|
jpayne@68
|
10318 '\n'
|
|
jpayne@68
|
10319 " >>> ' spacious '.rstrip()\n"
|
|
jpayne@68
|
10320 " ' spacious'\n"
|
|
jpayne@68
|
10321 " >>> 'mississippi'.rstrip('ipz')\n"
|
|
jpayne@68
|
10322 " 'mississ'\n"
|
|
jpayne@68
|
10323 '\n'
|
|
jpayne@68
|
10324 'str.split(sep=None, maxsplit=-1)\n'
|
|
jpayne@68
|
10325 '\n'
|
|
jpayne@68
|
10326 ' Return a list of the words in the string, using *sep* '
|
|
jpayne@68
|
10327 'as the\n'
|
|
jpayne@68
|
10328 ' delimiter string. If *maxsplit* is given, at most '
|
|
jpayne@68
|
10329 '*maxsplit*\n'
|
|
jpayne@68
|
10330 ' splits are done (thus, the list will have at most '
|
|
jpayne@68
|
10331 '"maxsplit+1"\n'
|
|
jpayne@68
|
10332 ' elements). If *maxsplit* is not specified or "-1", '
|
|
jpayne@68
|
10333 'then there is\n'
|
|
jpayne@68
|
10334 ' no limit on the number of splits (all possible splits '
|
|
jpayne@68
|
10335 'are made).\n'
|
|
jpayne@68
|
10336 '\n'
|
|
jpayne@68
|
10337 ' If *sep* is given, consecutive delimiters are not '
|
|
jpayne@68
|
10338 'grouped together\n'
|
|
jpayne@68
|
10339 ' and are deemed to delimit empty strings (for example,\n'
|
|
jpayne@68
|
10340 ' "\'1,,2\'.split(\',\')" returns "[\'1\', \'\', '
|
|
jpayne@68
|
10341 '\'2\']"). The *sep* argument\n'
|
|
jpayne@68
|
10342 ' may consist of multiple characters (for example,\n'
|
|
jpayne@68
|
10343 ' "\'1<>2<>3\'.split(\'<>\')" returns "[\'1\', \'2\', '
|
|
jpayne@68
|
10344 '\'3\']"). Splitting an\n'
|
|
jpayne@68
|
10345 ' empty string with a specified separator returns '
|
|
jpayne@68
|
10346 '"[\'\']".\n'
|
|
jpayne@68
|
10347 '\n'
|
|
jpayne@68
|
10348 ' For example:\n'
|
|
jpayne@68
|
10349 '\n'
|
|
jpayne@68
|
10350 " >>> '1,2,3'.split(',')\n"
|
|
jpayne@68
|
10351 " ['1', '2', '3']\n"
|
|
jpayne@68
|
10352 " >>> '1,2,3'.split(',', maxsplit=1)\n"
|
|
jpayne@68
|
10353 " ['1', '2,3']\n"
|
|
jpayne@68
|
10354 " >>> '1,2,,3,'.split(',')\n"
|
|
jpayne@68
|
10355 " ['1', '2', '', '3', '']\n"
|
|
jpayne@68
|
10356 '\n'
|
|
jpayne@68
|
10357 ' If *sep* is not specified or is "None", a different '
|
|
jpayne@68
|
10358 'splitting\n'
|
|
jpayne@68
|
10359 ' algorithm is applied: runs of consecutive whitespace '
|
|
jpayne@68
|
10360 'are regarded\n'
|
|
jpayne@68
|
10361 ' as a single separator, and the result will contain no '
|
|
jpayne@68
|
10362 'empty strings\n'
|
|
jpayne@68
|
10363 ' at the start or end if the string has leading or '
|
|
jpayne@68
|
10364 'trailing\n'
|
|
jpayne@68
|
10365 ' whitespace. Consequently, splitting an empty string or '
|
|
jpayne@68
|
10366 'a string\n'
|
|
jpayne@68
|
10367 ' consisting of just whitespace with a "None" separator '
|
|
jpayne@68
|
10368 'returns "[]".\n'
|
|
jpayne@68
|
10369 '\n'
|
|
jpayne@68
|
10370 ' For example:\n'
|
|
jpayne@68
|
10371 '\n'
|
|
jpayne@68
|
10372 " >>> '1 2 3'.split()\n"
|
|
jpayne@68
|
10373 " ['1', '2', '3']\n"
|
|
jpayne@68
|
10374 " >>> '1 2 3'.split(maxsplit=1)\n"
|
|
jpayne@68
|
10375 " ['1', '2 3']\n"
|
|
jpayne@68
|
10376 " >>> ' 1 2 3 '.split()\n"
|
|
jpayne@68
|
10377 " ['1', '2', '3']\n"
|
|
jpayne@68
|
10378 '\n'
|
|
jpayne@68
|
10379 'str.splitlines([keepends])\n'
|
|
jpayne@68
|
10380 '\n'
|
|
jpayne@68
|
10381 ' Return a list of the lines in the string, breaking at '
|
|
jpayne@68
|
10382 'line\n'
|
|
jpayne@68
|
10383 ' boundaries. Line breaks are not included in the '
|
|
jpayne@68
|
10384 'resulting list\n'
|
|
jpayne@68
|
10385 ' unless *keepends* is given and true.\n'
|
|
jpayne@68
|
10386 '\n'
|
|
jpayne@68
|
10387 ' This method splits on the following line boundaries. '
|
|
jpayne@68
|
10388 'In\n'
|
|
jpayne@68
|
10389 ' particular, the boundaries are a superset of *universal '
|
|
jpayne@68
|
10390 'newlines*.\n'
|
|
jpayne@68
|
10391 '\n'
|
|
jpayne@68
|
10392 ' '
|
|
jpayne@68
|
10393 '+-------------------------+-------------------------------+\n'
|
|
jpayne@68
|
10394 ' | Representation | '
|
|
jpayne@68
|
10395 'Description |\n'
|
|
jpayne@68
|
10396 ' '
|
|
jpayne@68
|
10397 '|=========================|===============================|\n'
|
|
jpayne@68
|
10398 ' | "\\n" | Line '
|
|
jpayne@68
|
10399 'Feed |\n'
|
|
jpayne@68
|
10400 ' '
|
|
jpayne@68
|
10401 '+-------------------------+-------------------------------+\n'
|
|
jpayne@68
|
10402 ' | "\\r" | Carriage '
|
|
jpayne@68
|
10403 'Return |\n'
|
|
jpayne@68
|
10404 ' '
|
|
jpayne@68
|
10405 '+-------------------------+-------------------------------+\n'
|
|
jpayne@68
|
10406 ' | "\\r\\n" | Carriage Return + Line '
|
|
jpayne@68
|
10407 'Feed |\n'
|
|
jpayne@68
|
10408 ' '
|
|
jpayne@68
|
10409 '+-------------------------+-------------------------------+\n'
|
|
jpayne@68
|
10410 ' | "\\v" or "\\x0b" | Line '
|
|
jpayne@68
|
10411 'Tabulation |\n'
|
|
jpayne@68
|
10412 ' '
|
|
jpayne@68
|
10413 '+-------------------------+-------------------------------+\n'
|
|
jpayne@68
|
10414 ' | "\\f" or "\\x0c" | Form '
|
|
jpayne@68
|
10415 'Feed |\n'
|
|
jpayne@68
|
10416 ' '
|
|
jpayne@68
|
10417 '+-------------------------+-------------------------------+\n'
|
|
jpayne@68
|
10418 ' | "\\x1c" | File '
|
|
jpayne@68
|
10419 'Separator |\n'
|
|
jpayne@68
|
10420 ' '
|
|
jpayne@68
|
10421 '+-------------------------+-------------------------------+\n'
|
|
jpayne@68
|
10422 ' | "\\x1d" | Group '
|
|
jpayne@68
|
10423 'Separator |\n'
|
|
jpayne@68
|
10424 ' '
|
|
jpayne@68
|
10425 '+-------------------------+-------------------------------+\n'
|
|
jpayne@68
|
10426 ' | "\\x1e" | Record '
|
|
jpayne@68
|
10427 'Separator |\n'
|
|
jpayne@68
|
10428 ' '
|
|
jpayne@68
|
10429 '+-------------------------+-------------------------------+\n'
|
|
jpayne@68
|
10430 ' | "\\x85" | Next Line (C1 Control '
|
|
jpayne@68
|
10431 'Code) |\n'
|
|
jpayne@68
|
10432 ' '
|
|
jpayne@68
|
10433 '+-------------------------+-------------------------------+\n'
|
|
jpayne@68
|
10434 ' | "\\u2028" | Line '
|
|
jpayne@68
|
10435 'Separator |\n'
|
|
jpayne@68
|
10436 ' '
|
|
jpayne@68
|
10437 '+-------------------------+-------------------------------+\n'
|
|
jpayne@68
|
10438 ' | "\\u2029" | Paragraph '
|
|
jpayne@68
|
10439 'Separator |\n'
|
|
jpayne@68
|
10440 ' '
|
|
jpayne@68
|
10441 '+-------------------------+-------------------------------+\n'
|
|
jpayne@68
|
10442 '\n'
|
|
jpayne@68
|
10443 ' Changed in version 3.2: "\\v" and "\\f" added to list '
|
|
jpayne@68
|
10444 'of line\n'
|
|
jpayne@68
|
10445 ' boundaries.\n'
|
|
jpayne@68
|
10446 '\n'
|
|
jpayne@68
|
10447 ' For example:\n'
|
|
jpayne@68
|
10448 '\n'
|
|
jpayne@68
|
10449 " >>> 'ab c\\n\\nde fg\\rkl\\r\\n'.splitlines()\n"
|
|
jpayne@68
|
10450 " ['ab c', '', 'de fg', 'kl']\n"
|
|
jpayne@68
|
10451 " >>> 'ab c\\n\\nde "
|
|
jpayne@68
|
10452 "fg\\rkl\\r\\n'.splitlines(keepends=True)\n"
|
|
jpayne@68
|
10453 " ['ab c\\n', '\\n', 'de fg\\r', 'kl\\r\\n']\n"
|
|
jpayne@68
|
10454 '\n'
|
|
jpayne@68
|
10455 ' Unlike "split()" when a delimiter string *sep* is '
|
|
jpayne@68
|
10456 'given, this\n'
|
|
jpayne@68
|
10457 ' method returns an empty list for the empty string, and '
|
|
jpayne@68
|
10458 'a terminal\n'
|
|
jpayne@68
|
10459 ' line break does not result in an extra line:\n'
|
|
jpayne@68
|
10460 '\n'
|
|
jpayne@68
|
10461 ' >>> "".splitlines()\n'
|
|
jpayne@68
|
10462 ' []\n'
|
|
jpayne@68
|
10463 ' >>> "One line\\n".splitlines()\n'
|
|
jpayne@68
|
10464 " ['One line']\n"
|
|
jpayne@68
|
10465 '\n'
|
|
jpayne@68
|
10466 ' For comparison, "split(\'\\n\')" gives:\n'
|
|
jpayne@68
|
10467 '\n'
|
|
jpayne@68
|
10468 " >>> ''.split('\\n')\n"
|
|
jpayne@68
|
10469 " ['']\n"
|
|
jpayne@68
|
10470 " >>> 'Two lines\\n'.split('\\n')\n"
|
|
jpayne@68
|
10471 " ['Two lines', '']\n"
|
|
jpayne@68
|
10472 '\n'
|
|
jpayne@68
|
10473 'str.startswith(prefix[, start[, end]])\n'
|
|
jpayne@68
|
10474 '\n'
|
|
jpayne@68
|
10475 ' Return "True" if string starts with the *prefix*, '
|
|
jpayne@68
|
10476 'otherwise return\n'
|
|
jpayne@68
|
10477 ' "False". *prefix* can also be a tuple of prefixes to '
|
|
jpayne@68
|
10478 'look for.\n'
|
|
jpayne@68
|
10479 ' With optional *start*, test string beginning at that '
|
|
jpayne@68
|
10480 'position.\n'
|
|
jpayne@68
|
10481 ' With optional *end*, stop comparing string at that '
|
|
jpayne@68
|
10482 'position.\n'
|
|
jpayne@68
|
10483 '\n'
|
|
jpayne@68
|
10484 'str.strip([chars])\n'
|
|
jpayne@68
|
10485 '\n'
|
|
jpayne@68
|
10486 ' Return a copy of the string with the leading and '
|
|
jpayne@68
|
10487 'trailing\n'
|
|
jpayne@68
|
10488 ' characters removed. The *chars* argument is a string '
|
|
jpayne@68
|
10489 'specifying the\n'
|
|
jpayne@68
|
10490 ' set of characters to be removed. If omitted or "None", '
|
|
jpayne@68
|
10491 'the *chars*\n'
|
|
jpayne@68
|
10492 ' argument defaults to removing whitespace. The *chars* '
|
|
jpayne@68
|
10493 'argument is\n'
|
|
jpayne@68
|
10494 ' not a prefix or suffix; rather, all combinations of its '
|
|
jpayne@68
|
10495 'values are\n'
|
|
jpayne@68
|
10496 ' stripped:\n'
|
|
jpayne@68
|
10497 '\n'
|
|
jpayne@68
|
10498 " >>> ' spacious '.strip()\n"
|
|
jpayne@68
|
10499 " 'spacious'\n"
|
|
jpayne@68
|
10500 " >>> 'www.example.com'.strip('cmowz.')\n"
|
|
jpayne@68
|
10501 " 'example'\n"
|
|
jpayne@68
|
10502 '\n'
|
|
jpayne@68
|
10503 ' The outermost leading and trailing *chars* argument '
|
|
jpayne@68
|
10504 'values are\n'
|
|
jpayne@68
|
10505 ' stripped from the string. Characters are removed from '
|
|
jpayne@68
|
10506 'the leading\n'
|
|
jpayne@68
|
10507 ' end until reaching a string character that is not '
|
|
jpayne@68
|
10508 'contained in the\n'
|
|
jpayne@68
|
10509 ' set of characters in *chars*. A similar action takes '
|
|
jpayne@68
|
10510 'place on the\n'
|
|
jpayne@68
|
10511 ' trailing end. For example:\n'
|
|
jpayne@68
|
10512 '\n'
|
|
jpayne@68
|
10513 " >>> comment_string = '#....... Section 3.2.1 Issue "
|
|
jpayne@68
|
10514 "#32 .......'\n"
|
|
jpayne@68
|
10515 " >>> comment_string.strip('.#! ')\n"
|
|
jpayne@68
|
10516 " 'Section 3.2.1 Issue #32'\n"
|
|
jpayne@68
|
10517 '\n'
|
|
jpayne@68
|
10518 'str.swapcase()\n'
|
|
jpayne@68
|
10519 '\n'
|
|
jpayne@68
|
10520 ' Return a copy of the string with uppercase characters '
|
|
jpayne@68
|
10521 'converted to\n'
|
|
jpayne@68
|
10522 ' lowercase and vice versa. Note that it is not '
|
|
jpayne@68
|
10523 'necessarily true that\n'
|
|
jpayne@68
|
10524 ' "s.swapcase().swapcase() == s".\n'
|
|
jpayne@68
|
10525 '\n'
|
|
jpayne@68
|
10526 'str.title()\n'
|
|
jpayne@68
|
10527 '\n'
|
|
jpayne@68
|
10528 ' Return a titlecased version of the string where words '
|
|
jpayne@68
|
10529 'start with an\n'
|
|
jpayne@68
|
10530 ' uppercase character and the remaining characters are '
|
|
jpayne@68
|
10531 'lowercase.\n'
|
|
jpayne@68
|
10532 '\n'
|
|
jpayne@68
|
10533 ' For example:\n'
|
|
jpayne@68
|
10534 '\n'
|
|
jpayne@68
|
10535 " >>> 'Hello world'.title()\n"
|
|
jpayne@68
|
10536 " 'Hello World'\n"
|
|
jpayne@68
|
10537 '\n'
|
|
jpayne@68
|
10538 ' The algorithm uses a simple language-independent '
|
|
jpayne@68
|
10539 'definition of a\n'
|
|
jpayne@68
|
10540 ' word as groups of consecutive letters. The definition '
|
|
jpayne@68
|
10541 'works in\n'
|
|
jpayne@68
|
10542 ' many contexts but it means that apostrophes in '
|
|
jpayne@68
|
10543 'contractions and\n'
|
|
jpayne@68
|
10544 ' possessives form word boundaries, which may not be the '
|
|
jpayne@68
|
10545 'desired\n'
|
|
jpayne@68
|
10546 ' result:\n'
|
|
jpayne@68
|
10547 '\n'
|
|
jpayne@68
|
10548 ' >>> "they\'re bill\'s friends from the UK".title()\n'
|
|
jpayne@68
|
10549 ' "They\'Re Bill\'S Friends From The Uk"\n'
|
|
jpayne@68
|
10550 '\n'
|
|
jpayne@68
|
10551 ' A workaround for apostrophes can be constructed using '
|
|
jpayne@68
|
10552 'regular\n'
|
|
jpayne@68
|
10553 ' expressions:\n'
|
|
jpayne@68
|
10554 '\n'
|
|
jpayne@68
|
10555 ' >>> import re\n'
|
|
jpayne@68
|
10556 ' >>> def titlecase(s):\n'
|
|
jpayne@68
|
10557 ' ... return re.sub(r"[A-Za-z]+(\'[A-Za-z]+)?",\n'
|
|
jpayne@68
|
10558 ' ... lambda mo: '
|
|
jpayne@68
|
10559 'mo.group(0).capitalize(),\n'
|
|
jpayne@68
|
10560 ' ... s)\n'
|
|
jpayne@68
|
10561 ' ...\n'
|
|
jpayne@68
|
10562 ' >>> titlecase("they\'re bill\'s friends.")\n'
|
|
jpayne@68
|
10563 ' "They\'re Bill\'s Friends."\n'
|
|
jpayne@68
|
10564 '\n'
|
|
jpayne@68
|
10565 'str.translate(table)\n'
|
|
jpayne@68
|
10566 '\n'
|
|
jpayne@68
|
10567 ' Return a copy of the string in which each character has '
|
|
jpayne@68
|
10568 'been mapped\n'
|
|
jpayne@68
|
10569 ' through the given translation table. The table must be '
|
|
jpayne@68
|
10570 'an object\n'
|
|
jpayne@68
|
10571 ' that implements indexing via "__getitem__()", typically '
|
|
jpayne@68
|
10572 'a *mapping*\n'
|
|
jpayne@68
|
10573 ' or *sequence*. When indexed by a Unicode ordinal (an '
|
|
jpayne@68
|
10574 'integer), the\n'
|
|
jpayne@68
|
10575 ' table object can do any of the following: return a '
|
|
jpayne@68
|
10576 'Unicode ordinal\n'
|
|
jpayne@68
|
10577 ' or a string, to map the character to one or more other '
|
|
jpayne@68
|
10578 'characters;\n'
|
|
jpayne@68
|
10579 ' return "None", to delete the character from the return '
|
|
jpayne@68
|
10580 'string; or\n'
|
|
jpayne@68
|
10581 ' raise a "LookupError" exception, to map the character '
|
|
jpayne@68
|
10582 'to itself.\n'
|
|
jpayne@68
|
10583 '\n'
|
|
jpayne@68
|
10584 ' You can use "str.maketrans()" to create a translation '
|
|
jpayne@68
|
10585 'map from\n'
|
|
jpayne@68
|
10586 ' character-to-character mappings in different formats.\n'
|
|
jpayne@68
|
10587 '\n'
|
|
jpayne@68
|
10588 ' See also the "codecs" module for a more flexible '
|
|
jpayne@68
|
10589 'approach to custom\n'
|
|
jpayne@68
|
10590 ' character mappings.\n'
|
|
jpayne@68
|
10591 '\n'
|
|
jpayne@68
|
10592 'str.upper()\n'
|
|
jpayne@68
|
10593 '\n'
|
|
jpayne@68
|
10594 ' Return a copy of the string with all the cased '
|
|
jpayne@68
|
10595 'characters [4]\n'
|
|
jpayne@68
|
10596 ' converted to uppercase. Note that '
|
|
jpayne@68
|
10597 '"s.upper().isupper()" might be\n'
|
|
jpayne@68
|
10598 ' "False" if "s" contains uncased characters or if the '
|
|
jpayne@68
|
10599 'Unicode\n'
|
|
jpayne@68
|
10600 ' category of the resulting character(s) is not “Lu” '
|
|
jpayne@68
|
10601 '(Letter,\n'
|
|
jpayne@68
|
10602 ' uppercase), but e.g. “Lt” (Letter, titlecase).\n'
|
|
jpayne@68
|
10603 '\n'
|
|
jpayne@68
|
10604 ' The uppercasing algorithm used is described in section '
|
|
jpayne@68
|
10605 '3.13 of the\n'
|
|
jpayne@68
|
10606 ' Unicode Standard.\n'
|
|
jpayne@68
|
10607 '\n'
|
|
jpayne@68
|
10608 'str.zfill(width)\n'
|
|
jpayne@68
|
10609 '\n'
|
|
jpayne@68
|
10610 ' Return a copy of the string left filled with ASCII '
|
|
jpayne@68
|
10611 '"\'0\'" digits to\n'
|
|
jpayne@68
|
10612 ' make a string of length *width*. A leading sign prefix\n'
|
|
jpayne@68
|
10613 ' ("\'+\'"/"\'-\'") is handled by inserting the padding '
|
|
jpayne@68
|
10614 '*after* the sign\n'
|
|
jpayne@68
|
10615 ' character rather than before. The original string is '
|
|
jpayne@68
|
10616 'returned if\n'
|
|
jpayne@68
|
10617 ' *width* is less than or equal to "len(s)".\n'
|
|
jpayne@68
|
10618 '\n'
|
|
jpayne@68
|
10619 ' For example:\n'
|
|
jpayne@68
|
10620 '\n'
|
|
jpayne@68
|
10621 ' >>> "42".zfill(5)\n'
|
|
jpayne@68
|
10622 " '00042'\n"
|
|
jpayne@68
|
10623 ' >>> "-42".zfill(5)\n'
|
|
jpayne@68
|
10624 " '-0042'\n",
|
|
jpayne@68
|
10625 'strings': 'String and Bytes literals\n'
|
|
jpayne@68
|
10626 '*************************\n'
|
|
jpayne@68
|
10627 '\n'
|
|
jpayne@68
|
10628 'String literals are described by the following lexical '
|
|
jpayne@68
|
10629 'definitions:\n'
|
|
jpayne@68
|
10630 '\n'
|
|
jpayne@68
|
10631 ' stringliteral ::= [stringprefix](shortstring | longstring)\n'
|
|
jpayne@68
|
10632 ' stringprefix ::= "r" | "u" | "R" | "U" | "f" | "F"\n'
|
|
jpayne@68
|
10633 ' | "fr" | "Fr" | "fR" | "FR" | "rf" | "rF" | '
|
|
jpayne@68
|
10634 '"Rf" | "RF"\n'
|
|
jpayne@68
|
10635 ' shortstring ::= "\'" shortstringitem* "\'" | \'"\' '
|
|
jpayne@68
|
10636 'shortstringitem* \'"\'\n'
|
|
jpayne@68
|
10637 ' longstring ::= "\'\'\'" longstringitem* "\'\'\'" | '
|
|
jpayne@68
|
10638 '\'"""\' longstringitem* \'"""\'\n'
|
|
jpayne@68
|
10639 ' shortstringitem ::= shortstringchar | stringescapeseq\n'
|
|
jpayne@68
|
10640 ' longstringitem ::= longstringchar | stringescapeseq\n'
|
|
jpayne@68
|
10641 ' shortstringchar ::= <any source character except "\\" or '
|
|
jpayne@68
|
10642 'newline or the quote>\n'
|
|
jpayne@68
|
10643 ' longstringchar ::= <any source character except "\\">\n'
|
|
jpayne@68
|
10644 ' stringescapeseq ::= "\\" <any source character>\n'
|
|
jpayne@68
|
10645 '\n'
|
|
jpayne@68
|
10646 ' bytesliteral ::= bytesprefix(shortbytes | longbytes)\n'
|
|
jpayne@68
|
10647 ' bytesprefix ::= "b" | "B" | "br" | "Br" | "bR" | "BR" | '
|
|
jpayne@68
|
10648 '"rb" | "rB" | "Rb" | "RB"\n'
|
|
jpayne@68
|
10649 ' shortbytes ::= "\'" shortbytesitem* "\'" | \'"\' '
|
|
jpayne@68
|
10650 'shortbytesitem* \'"\'\n'
|
|
jpayne@68
|
10651 ' longbytes ::= "\'\'\'" longbytesitem* "\'\'\'" | \'"""\' '
|
|
jpayne@68
|
10652 'longbytesitem* \'"""\'\n'
|
|
jpayne@68
|
10653 ' shortbytesitem ::= shortbyteschar | bytesescapeseq\n'
|
|
jpayne@68
|
10654 ' longbytesitem ::= longbyteschar | bytesescapeseq\n'
|
|
jpayne@68
|
10655 ' shortbyteschar ::= <any ASCII character except "\\" or newline '
|
|
jpayne@68
|
10656 'or the quote>\n'
|
|
jpayne@68
|
10657 ' longbyteschar ::= <any ASCII character except "\\">\n'
|
|
jpayne@68
|
10658 ' bytesescapeseq ::= "\\" <any ASCII character>\n'
|
|
jpayne@68
|
10659 '\n'
|
|
jpayne@68
|
10660 'One syntactic restriction not indicated by these productions is '
|
|
jpayne@68
|
10661 'that\n'
|
|
jpayne@68
|
10662 'whitespace is not allowed between the "stringprefix" or '
|
|
jpayne@68
|
10663 '"bytesprefix"\n'
|
|
jpayne@68
|
10664 'and the rest of the literal. The source character set is defined '
|
|
jpayne@68
|
10665 'by\n'
|
|
jpayne@68
|
10666 'the encoding declaration; it is UTF-8 if no encoding declaration '
|
|
jpayne@68
|
10667 'is\n'
|
|
jpayne@68
|
10668 'given in the source file; see section Encoding declarations.\n'
|
|
jpayne@68
|
10669 '\n'
|
|
jpayne@68
|
10670 'In plain English: Both types of literals can be enclosed in '
|
|
jpayne@68
|
10671 'matching\n'
|
|
jpayne@68
|
10672 'single quotes ("\'") or double quotes ("""). They can also be '
|
|
jpayne@68
|
10673 'enclosed\n'
|
|
jpayne@68
|
10674 'in matching groups of three single or double quotes (these are\n'
|
|
jpayne@68
|
10675 'generally referred to as *triple-quoted strings*). The '
|
|
jpayne@68
|
10676 'backslash\n'
|
|
jpayne@68
|
10677 '("\\") character is used to escape characters that otherwise have '
|
|
jpayne@68
|
10678 'a\n'
|
|
jpayne@68
|
10679 'special meaning, such as newline, backslash itself, or the quote\n'
|
|
jpayne@68
|
10680 'character.\n'
|
|
jpayne@68
|
10681 '\n'
|
|
jpayne@68
|
10682 'Bytes literals are always prefixed with "\'b\'" or "\'B\'"; they '
|
|
jpayne@68
|
10683 'produce\n'
|
|
jpayne@68
|
10684 'an instance of the "bytes" type instead of the "str" type. They '
|
|
jpayne@68
|
10685 'may\n'
|
|
jpayne@68
|
10686 'only contain ASCII characters; bytes with a numeric value of 128 '
|
|
jpayne@68
|
10687 'or\n'
|
|
jpayne@68
|
10688 'greater must be expressed with escapes.\n'
|
|
jpayne@68
|
10689 '\n'
|
|
jpayne@68
|
10690 'Both string and bytes literals may optionally be prefixed with a\n'
|
|
jpayne@68
|
10691 'letter "\'r\'" or "\'R\'"; such strings are called *raw strings* '
|
|
jpayne@68
|
10692 'and treat\n'
|
|
jpayne@68
|
10693 'backslashes as literal characters. As a result, in string '
|
|
jpayne@68
|
10694 'literals,\n'
|
|
jpayne@68
|
10695 '"\'\\U\'" and "\'\\u\'" escapes in raw strings are not treated '
|
|
jpayne@68
|
10696 'specially.\n'
|
|
jpayne@68
|
10697 'Given that Python 2.x’s raw unicode literals behave differently '
|
|
jpayne@68
|
10698 'than\n'
|
|
jpayne@68
|
10699 'Python 3.x’s the "\'ur\'" syntax is not supported.\n'
|
|
jpayne@68
|
10700 '\n'
|
|
jpayne@68
|
10701 'New in version 3.3: The "\'rb\'" prefix of raw bytes literals has '
|
|
jpayne@68
|
10702 'been\n'
|
|
jpayne@68
|
10703 'added as a synonym of "\'br\'".\n'
|
|
jpayne@68
|
10704 '\n'
|
|
jpayne@68
|
10705 'New in version 3.3: Support for the unicode legacy literal\n'
|
|
jpayne@68
|
10706 '("u\'value\'") was reintroduced to simplify the maintenance of '
|
|
jpayne@68
|
10707 'dual\n'
|
|
jpayne@68
|
10708 'Python 2.x and 3.x codebases. See **PEP 414** for more '
|
|
jpayne@68
|
10709 'information.\n'
|
|
jpayne@68
|
10710 '\n'
|
|
jpayne@68
|
10711 'A string literal with "\'f\'" or "\'F\'" in its prefix is a '
|
|
jpayne@68
|
10712 '*formatted\n'
|
|
jpayne@68
|
10713 'string literal*; see Formatted string literals. The "\'f\'" may '
|
|
jpayne@68
|
10714 'be\n'
|
|
jpayne@68
|
10715 'combined with "\'r\'", but not with "\'b\'" or "\'u\'", therefore '
|
|
jpayne@68
|
10716 'raw\n'
|
|
jpayne@68
|
10717 'formatted strings are possible, but formatted bytes literals are '
|
|
jpayne@68
|
10718 'not.\n'
|
|
jpayne@68
|
10719 '\n'
|
|
jpayne@68
|
10720 'In triple-quoted literals, unescaped newlines and quotes are '
|
|
jpayne@68
|
10721 'allowed\n'
|
|
jpayne@68
|
10722 '(and are retained), except that three unescaped quotes in a row\n'
|
|
jpayne@68
|
10723 'terminate the literal. (A “quote” is the character used to open '
|
|
jpayne@68
|
10724 'the\n'
|
|
jpayne@68
|
10725 'literal, i.e. either "\'" or """.)\n'
|
|
jpayne@68
|
10726 '\n'
|
|
jpayne@68
|
10727 'Unless an "\'r\'" or "\'R\'" prefix is present, escape sequences '
|
|
jpayne@68
|
10728 'in string\n'
|
|
jpayne@68
|
10729 'and bytes literals are interpreted according to rules similar to '
|
|
jpayne@68
|
10730 'those\n'
|
|
jpayne@68
|
10731 'used by Standard C. The recognized escape sequences are:\n'
|
|
jpayne@68
|
10732 '\n'
|
|
jpayne@68
|
10733 '+-------------------+-----------------------------------+---------+\n'
|
|
jpayne@68
|
10734 '| Escape Sequence | Meaning | Notes '
|
|
jpayne@68
|
10735 '|\n'
|
|
jpayne@68
|
10736 '|===================|===================================|=========|\n'
|
|
jpayne@68
|
10737 '| "\\newline" | Backslash and newline ignored '
|
|
jpayne@68
|
10738 '| |\n'
|
|
jpayne@68
|
10739 '+-------------------+-----------------------------------+---------+\n'
|
|
jpayne@68
|
10740 '| "\\\\" | Backslash ("\\") '
|
|
jpayne@68
|
10741 '| |\n'
|
|
jpayne@68
|
10742 '+-------------------+-----------------------------------+---------+\n'
|
|
jpayne@68
|
10743 '| "\\\'" | Single quote ("\'") '
|
|
jpayne@68
|
10744 '| |\n'
|
|
jpayne@68
|
10745 '+-------------------+-----------------------------------+---------+\n'
|
|
jpayne@68
|
10746 '| "\\"" | Double quote (""") '
|
|
jpayne@68
|
10747 '| |\n'
|
|
jpayne@68
|
10748 '+-------------------+-----------------------------------+---------+\n'
|
|
jpayne@68
|
10749 '| "\\a" | ASCII Bell (BEL) '
|
|
jpayne@68
|
10750 '| |\n'
|
|
jpayne@68
|
10751 '+-------------------+-----------------------------------+---------+\n'
|
|
jpayne@68
|
10752 '| "\\b" | ASCII Backspace (BS) '
|
|
jpayne@68
|
10753 '| |\n'
|
|
jpayne@68
|
10754 '+-------------------+-----------------------------------+---------+\n'
|
|
jpayne@68
|
10755 '| "\\f" | ASCII Formfeed (FF) '
|
|
jpayne@68
|
10756 '| |\n'
|
|
jpayne@68
|
10757 '+-------------------+-----------------------------------+---------+\n'
|
|
jpayne@68
|
10758 '| "\\n" | ASCII Linefeed (LF) '
|
|
jpayne@68
|
10759 '| |\n'
|
|
jpayne@68
|
10760 '+-------------------+-----------------------------------+---------+\n'
|
|
jpayne@68
|
10761 '| "\\r" | ASCII Carriage Return (CR) '
|
|
jpayne@68
|
10762 '| |\n'
|
|
jpayne@68
|
10763 '+-------------------+-----------------------------------+---------+\n'
|
|
jpayne@68
|
10764 '| "\\t" | ASCII Horizontal Tab (TAB) '
|
|
jpayne@68
|
10765 '| |\n'
|
|
jpayne@68
|
10766 '+-------------------+-----------------------------------+---------+\n'
|
|
jpayne@68
|
10767 '| "\\v" | ASCII Vertical Tab (VT) '
|
|
jpayne@68
|
10768 '| |\n'
|
|
jpayne@68
|
10769 '+-------------------+-----------------------------------+---------+\n'
|
|
jpayne@68
|
10770 '| "\\ooo" | Character with octal value *ooo* | '
|
|
jpayne@68
|
10771 '(1,3) |\n'
|
|
jpayne@68
|
10772 '+-------------------+-----------------------------------+---------+\n'
|
|
jpayne@68
|
10773 '| "\\xhh" | Character with hex value *hh* | '
|
|
jpayne@68
|
10774 '(2,3) |\n'
|
|
jpayne@68
|
10775 '+-------------------+-----------------------------------+---------+\n'
|
|
jpayne@68
|
10776 '\n'
|
|
jpayne@68
|
10777 'Escape sequences only recognized in string literals are:\n'
|
|
jpayne@68
|
10778 '\n'
|
|
jpayne@68
|
10779 '+-------------------+-----------------------------------+---------+\n'
|
|
jpayne@68
|
10780 '| Escape Sequence | Meaning | Notes '
|
|
jpayne@68
|
10781 '|\n'
|
|
jpayne@68
|
10782 '|===================|===================================|=========|\n'
|
|
jpayne@68
|
10783 '| "\\N{name}" | Character named *name* in the | '
|
|
jpayne@68
|
10784 '(4) |\n'
|
|
jpayne@68
|
10785 '| | Unicode database | '
|
|
jpayne@68
|
10786 '|\n'
|
|
jpayne@68
|
10787 '+-------------------+-----------------------------------+---------+\n'
|
|
jpayne@68
|
10788 '| "\\uxxxx" | Character with 16-bit hex value | '
|
|
jpayne@68
|
10789 '(5) |\n'
|
|
jpayne@68
|
10790 '| | *xxxx* | '
|
|
jpayne@68
|
10791 '|\n'
|
|
jpayne@68
|
10792 '+-------------------+-----------------------------------+---------+\n'
|
|
jpayne@68
|
10793 '| "\\Uxxxxxxxx" | Character with 32-bit hex value | '
|
|
jpayne@68
|
10794 '(6) |\n'
|
|
jpayne@68
|
10795 '| | *xxxxxxxx* | '
|
|
jpayne@68
|
10796 '|\n'
|
|
jpayne@68
|
10797 '+-------------------+-----------------------------------+---------+\n'
|
|
jpayne@68
|
10798 '\n'
|
|
jpayne@68
|
10799 'Notes:\n'
|
|
jpayne@68
|
10800 '\n'
|
|
jpayne@68
|
10801 '1. As in Standard C, up to three octal digits are accepted.\n'
|
|
jpayne@68
|
10802 '\n'
|
|
jpayne@68
|
10803 '2. Unlike in Standard C, exactly two hex digits are required.\n'
|
|
jpayne@68
|
10804 '\n'
|
|
jpayne@68
|
10805 '3. In a bytes literal, hexadecimal and octal escapes denote the\n'
|
|
jpayne@68
|
10806 ' byte with the given value. In a string literal, these escapes\n'
|
|
jpayne@68
|
10807 ' denote a Unicode character with the given value.\n'
|
|
jpayne@68
|
10808 '\n'
|
|
jpayne@68
|
10809 '4. Changed in version 3.3: Support for name aliases [1] has been\n'
|
|
jpayne@68
|
10810 ' added.\n'
|
|
jpayne@68
|
10811 '\n'
|
|
jpayne@68
|
10812 '5. Exactly four hex digits are required.\n'
|
|
jpayne@68
|
10813 '\n'
|
|
jpayne@68
|
10814 '6. Any Unicode character can be encoded this way. Exactly eight\n'
|
|
jpayne@68
|
10815 ' hex digits are required.\n'
|
|
jpayne@68
|
10816 '\n'
|
|
jpayne@68
|
10817 'Unlike Standard C, all unrecognized escape sequences are left in '
|
|
jpayne@68
|
10818 'the\n'
|
|
jpayne@68
|
10819 'string unchanged, i.e., *the backslash is left in the result*. '
|
|
jpayne@68
|
10820 '(This\n'
|
|
jpayne@68
|
10821 'behavior is useful when debugging: if an escape sequence is '
|
|
jpayne@68
|
10822 'mistyped,\n'
|
|
jpayne@68
|
10823 'the resulting output is more easily recognized as broken.) It is '
|
|
jpayne@68
|
10824 'also\n'
|
|
jpayne@68
|
10825 'important to note that the escape sequences only recognized in '
|
|
jpayne@68
|
10826 'string\n'
|
|
jpayne@68
|
10827 'literals fall into the category of unrecognized escapes for '
|
|
jpayne@68
|
10828 'bytes\n'
|
|
jpayne@68
|
10829 'literals.\n'
|
|
jpayne@68
|
10830 '\n'
|
|
jpayne@68
|
10831 ' Changed in version 3.6: Unrecognized escape sequences produce '
|
|
jpayne@68
|
10832 'a\n'
|
|
jpayne@68
|
10833 ' "DeprecationWarning". In a future Python version they will be '
|
|
jpayne@68
|
10834 'a\n'
|
|
jpayne@68
|
10835 ' "SyntaxWarning" and eventually a "SyntaxError".\n'
|
|
jpayne@68
|
10836 '\n'
|
|
jpayne@68
|
10837 'Even in a raw literal, quotes can be escaped with a backslash, '
|
|
jpayne@68
|
10838 'but the\n'
|
|
jpayne@68
|
10839 'backslash remains in the result; for example, "r"\\""" is a '
|
|
jpayne@68
|
10840 'valid\n'
|
|
jpayne@68
|
10841 'string literal consisting of two characters: a backslash and a '
|
|
jpayne@68
|
10842 'double\n'
|
|
jpayne@68
|
10843 'quote; "r"\\"" is not a valid string literal (even a raw string '
|
|
jpayne@68
|
10844 'cannot\n'
|
|
jpayne@68
|
10845 'end in an odd number of backslashes). Specifically, *a raw '
|
|
jpayne@68
|
10846 'literal\n'
|
|
jpayne@68
|
10847 'cannot end in a single backslash* (since the backslash would '
|
|
jpayne@68
|
10848 'escape\n'
|
|
jpayne@68
|
10849 'the following quote character). Note also that a single '
|
|
jpayne@68
|
10850 'backslash\n'
|
|
jpayne@68
|
10851 'followed by a newline is interpreted as those two characters as '
|
|
jpayne@68
|
10852 'part\n'
|
|
jpayne@68
|
10853 'of the literal, *not* as a line continuation.\n',
|
|
jpayne@68
|
10854 'subscriptions': 'Subscriptions\n'
|
|
jpayne@68
|
10855 '*************\n'
|
|
jpayne@68
|
10856 '\n'
|
|
jpayne@68
|
10857 'A subscription selects an item of a sequence (string, tuple '
|
|
jpayne@68
|
10858 'or list)\n'
|
|
jpayne@68
|
10859 'or mapping (dictionary) object:\n'
|
|
jpayne@68
|
10860 '\n'
|
|
jpayne@68
|
10861 ' subscription ::= primary "[" expression_list "]"\n'
|
|
jpayne@68
|
10862 '\n'
|
|
jpayne@68
|
10863 'The primary must evaluate to an object that supports '
|
|
jpayne@68
|
10864 'subscription\n'
|
|
jpayne@68
|
10865 '(lists or dictionaries for example). User-defined objects '
|
|
jpayne@68
|
10866 'can support\n'
|
|
jpayne@68
|
10867 'subscription by defining a "__getitem__()" method.\n'
|
|
jpayne@68
|
10868 '\n'
|
|
jpayne@68
|
10869 'For built-in objects, there are two types of objects that '
|
|
jpayne@68
|
10870 'support\n'
|
|
jpayne@68
|
10871 'subscription:\n'
|
|
jpayne@68
|
10872 '\n'
|
|
jpayne@68
|
10873 'If the primary is a mapping, the expression list must '
|
|
jpayne@68
|
10874 'evaluate to an\n'
|
|
jpayne@68
|
10875 'object whose value is one of the keys of the mapping, and '
|
|
jpayne@68
|
10876 'the\n'
|
|
jpayne@68
|
10877 'subscription selects the value in the mapping that '
|
|
jpayne@68
|
10878 'corresponds to that\n'
|
|
jpayne@68
|
10879 'key. (The expression list is a tuple except if it has '
|
|
jpayne@68
|
10880 'exactly one\n'
|
|
jpayne@68
|
10881 'item.)\n'
|
|
jpayne@68
|
10882 '\n'
|
|
jpayne@68
|
10883 'If the primary is a sequence, the expression list must '
|
|
jpayne@68
|
10884 'evaluate to an\n'
|
|
jpayne@68
|
10885 'integer or a slice (as discussed in the following '
|
|
jpayne@68
|
10886 'section).\n'
|
|
jpayne@68
|
10887 '\n'
|
|
jpayne@68
|
10888 'The formal syntax makes no special provision for negative '
|
|
jpayne@68
|
10889 'indices in\n'
|
|
jpayne@68
|
10890 'sequences; however, built-in sequences all provide a '
|
|
jpayne@68
|
10891 '"__getitem__()"\n'
|
|
jpayne@68
|
10892 'method that interprets negative indices by adding the '
|
|
jpayne@68
|
10893 'length of the\n'
|
|
jpayne@68
|
10894 'sequence to the index (so that "x[-1]" selects the last '
|
|
jpayne@68
|
10895 'item of "x").\n'
|
|
jpayne@68
|
10896 'The resulting value must be a nonnegative integer less than '
|
|
jpayne@68
|
10897 'the number\n'
|
|
jpayne@68
|
10898 'of items in the sequence, and the subscription selects the '
|
|
jpayne@68
|
10899 'item whose\n'
|
|
jpayne@68
|
10900 'index is that value (counting from zero). Since the support '
|
|
jpayne@68
|
10901 'for\n'
|
|
jpayne@68
|
10902 'negative indices and slicing occurs in the object’s '
|
|
jpayne@68
|
10903 '"__getitem__()"\n'
|
|
jpayne@68
|
10904 'method, subclasses overriding this method will need to '
|
|
jpayne@68
|
10905 'explicitly add\n'
|
|
jpayne@68
|
10906 'that support.\n'
|
|
jpayne@68
|
10907 '\n'
|
|
jpayne@68
|
10908 'A string’s items are characters. A character is not a '
|
|
jpayne@68
|
10909 'separate data\n'
|
|
jpayne@68
|
10910 'type but a string of exactly one character.\n',
|
|
jpayne@68
|
10911 'truth': 'Truth Value Testing\n'
|
|
jpayne@68
|
10912 '*******************\n'
|
|
jpayne@68
|
10913 '\n'
|
|
jpayne@68
|
10914 'Any object can be tested for truth value, for use in an "if" or\n'
|
|
jpayne@68
|
10915 '"while" condition or as operand of the Boolean operations below.\n'
|
|
jpayne@68
|
10916 '\n'
|
|
jpayne@68
|
10917 'By default, an object is considered true unless its class defines\n'
|
|
jpayne@68
|
10918 'either a "__bool__()" method that returns "False" or a "__len__()"\n'
|
|
jpayne@68
|
10919 'method that returns zero, when called with the object. [1] Here '
|
|
jpayne@68
|
10920 'are\n'
|
|
jpayne@68
|
10921 'most of the built-in objects considered false:\n'
|
|
jpayne@68
|
10922 '\n'
|
|
jpayne@68
|
10923 '* constants defined to be false: "None" and "False".\n'
|
|
jpayne@68
|
10924 '\n'
|
|
jpayne@68
|
10925 '* zero of any numeric type: "0", "0.0", "0j", "Decimal(0)",\n'
|
|
jpayne@68
|
10926 ' "Fraction(0, 1)"\n'
|
|
jpayne@68
|
10927 '\n'
|
|
jpayne@68
|
10928 '* empty sequences and collections: "\'\'", "()", "[]", "{}", '
|
|
jpayne@68
|
10929 '"set()",\n'
|
|
jpayne@68
|
10930 ' "range(0)"\n'
|
|
jpayne@68
|
10931 '\n'
|
|
jpayne@68
|
10932 'Operations and built-in functions that have a Boolean result '
|
|
jpayne@68
|
10933 'always\n'
|
|
jpayne@68
|
10934 'return "0" or "False" for false and "1" or "True" for true, unless\n'
|
|
jpayne@68
|
10935 'otherwise stated. (Important exception: the Boolean operations '
|
|
jpayne@68
|
10936 '"or"\n'
|
|
jpayne@68
|
10937 'and "and" always return one of their operands.)\n',
|
|
jpayne@68
|
10938 'try': 'The "try" statement\n'
|
|
jpayne@68
|
10939 '*******************\n'
|
|
jpayne@68
|
10940 '\n'
|
|
jpayne@68
|
10941 'The "try" statement specifies exception handlers and/or cleanup code\n'
|
|
jpayne@68
|
10942 'for a group of statements:\n'
|
|
jpayne@68
|
10943 '\n'
|
|
jpayne@68
|
10944 ' try_stmt ::= try1_stmt | try2_stmt\n'
|
|
jpayne@68
|
10945 ' try1_stmt ::= "try" ":" suite\n'
|
|
jpayne@68
|
10946 ' ("except" [expression ["as" identifier]] ":" '
|
|
jpayne@68
|
10947 'suite)+\n'
|
|
jpayne@68
|
10948 ' ["else" ":" suite]\n'
|
|
jpayne@68
|
10949 ' ["finally" ":" suite]\n'
|
|
jpayne@68
|
10950 ' try2_stmt ::= "try" ":" suite\n'
|
|
jpayne@68
|
10951 ' "finally" ":" suite\n'
|
|
jpayne@68
|
10952 '\n'
|
|
jpayne@68
|
10953 'The "except" clause(s) specify one or more exception handlers. When '
|
|
jpayne@68
|
10954 'no\n'
|
|
jpayne@68
|
10955 'exception occurs in the "try" clause, no exception handler is\n'
|
|
jpayne@68
|
10956 'executed. When an exception occurs in the "try" suite, a search for '
|
|
jpayne@68
|
10957 'an\n'
|
|
jpayne@68
|
10958 'exception handler is started. This search inspects the except '
|
|
jpayne@68
|
10959 'clauses\n'
|
|
jpayne@68
|
10960 'in turn until one is found that matches the exception. An '
|
|
jpayne@68
|
10961 'expression-\n'
|
|
jpayne@68
|
10962 'less except clause, if present, must be last; it matches any\n'
|
|
jpayne@68
|
10963 'exception. For an except clause with an expression, that expression\n'
|
|
jpayne@68
|
10964 'is evaluated, and the clause matches the exception if the resulting\n'
|
|
jpayne@68
|
10965 'object is “compatible” with the exception. An object is compatible\n'
|
|
jpayne@68
|
10966 'with an exception if it is the class or a base class of the '
|
|
jpayne@68
|
10967 'exception\n'
|
|
jpayne@68
|
10968 'object or a tuple containing an item compatible with the exception.\n'
|
|
jpayne@68
|
10969 '\n'
|
|
jpayne@68
|
10970 'If no except clause matches the exception, the search for an '
|
|
jpayne@68
|
10971 'exception\n'
|
|
jpayne@68
|
10972 'handler continues in the surrounding code and on the invocation '
|
|
jpayne@68
|
10973 'stack.\n'
|
|
jpayne@68
|
10974 '[1]\n'
|
|
jpayne@68
|
10975 '\n'
|
|
jpayne@68
|
10976 'If the evaluation of an expression in the header of an except clause\n'
|
|
jpayne@68
|
10977 'raises an exception, the original search for a handler is canceled '
|
|
jpayne@68
|
10978 'and\n'
|
|
jpayne@68
|
10979 'a search starts for the new exception in the surrounding code and on\n'
|
|
jpayne@68
|
10980 'the call stack (it is treated as if the entire "try" statement '
|
|
jpayne@68
|
10981 'raised\n'
|
|
jpayne@68
|
10982 'the exception).\n'
|
|
jpayne@68
|
10983 '\n'
|
|
jpayne@68
|
10984 'When a matching except clause is found, the exception is assigned to\n'
|
|
jpayne@68
|
10985 'the target specified after the "as" keyword in that except clause, '
|
|
jpayne@68
|
10986 'if\n'
|
|
jpayne@68
|
10987 'present, and the except clause’s suite is executed. All except\n'
|
|
jpayne@68
|
10988 'clauses must have an executable block. When the end of this block '
|
|
jpayne@68
|
10989 'is\n'
|
|
jpayne@68
|
10990 'reached, execution continues normally after the entire try '
|
|
jpayne@68
|
10991 'statement.\n'
|
|
jpayne@68
|
10992 '(This means that if two nested handlers exist for the same '
|
|
jpayne@68
|
10993 'exception,\n'
|
|
jpayne@68
|
10994 'and the exception occurs in the try clause of the inner handler, the\n'
|
|
jpayne@68
|
10995 'outer handler will not handle the exception.)\n'
|
|
jpayne@68
|
10996 '\n'
|
|
jpayne@68
|
10997 'When an exception has been assigned using "as target", it is cleared\n'
|
|
jpayne@68
|
10998 'at the end of the except clause. This is as if\n'
|
|
jpayne@68
|
10999 '\n'
|
|
jpayne@68
|
11000 ' except E as N:\n'
|
|
jpayne@68
|
11001 ' foo\n'
|
|
jpayne@68
|
11002 '\n'
|
|
jpayne@68
|
11003 'was translated to\n'
|
|
jpayne@68
|
11004 '\n'
|
|
jpayne@68
|
11005 ' except E as N:\n'
|
|
jpayne@68
|
11006 ' try:\n'
|
|
jpayne@68
|
11007 ' foo\n'
|
|
jpayne@68
|
11008 ' finally:\n'
|
|
jpayne@68
|
11009 ' del N\n'
|
|
jpayne@68
|
11010 '\n'
|
|
jpayne@68
|
11011 'This means the exception must be assigned to a different name to be\n'
|
|
jpayne@68
|
11012 'able to refer to it after the except clause. Exceptions are cleared\n'
|
|
jpayne@68
|
11013 'because with the traceback attached to them, they form a reference\n'
|
|
jpayne@68
|
11014 'cycle with the stack frame, keeping all locals in that frame alive\n'
|
|
jpayne@68
|
11015 'until the next garbage collection occurs.\n'
|
|
jpayne@68
|
11016 '\n'
|
|
jpayne@68
|
11017 'Before an except clause’s suite is executed, details about the\n'
|
|
jpayne@68
|
11018 'exception are stored in the "sys" module and can be accessed via\n'
|
|
jpayne@68
|
11019 '"sys.exc_info()". "sys.exc_info()" returns a 3-tuple consisting of '
|
|
jpayne@68
|
11020 'the\n'
|
|
jpayne@68
|
11021 'exception class, the exception instance and a traceback object (see\n'
|
|
jpayne@68
|
11022 'section The standard type hierarchy) identifying the point in the\n'
|
|
jpayne@68
|
11023 'program where the exception occurred. "sys.exc_info()" values are\n'
|
|
jpayne@68
|
11024 'restored to their previous values (before the call) when returning\n'
|
|
jpayne@68
|
11025 'from a function that handled an exception.\n'
|
|
jpayne@68
|
11026 '\n'
|
|
jpayne@68
|
11027 'The optional "else" clause is executed if the control flow leaves '
|
|
jpayne@68
|
11028 'the\n'
|
|
jpayne@68
|
11029 '"try" suite, no exception was raised, and no "return", "continue", '
|
|
jpayne@68
|
11030 'or\n'
|
|
jpayne@68
|
11031 '"break" statement was executed. Exceptions in the "else" clause are\n'
|
|
jpayne@68
|
11032 'not handled by the preceding "except" clauses.\n'
|
|
jpayne@68
|
11033 '\n'
|
|
jpayne@68
|
11034 'If "finally" is present, it specifies a ‘cleanup’ handler. The '
|
|
jpayne@68
|
11035 '"try"\n'
|
|
jpayne@68
|
11036 'clause is executed, including any "except" and "else" clauses. If '
|
|
jpayne@68
|
11037 'an\n'
|
|
jpayne@68
|
11038 'exception occurs in any of the clauses and is not handled, the\n'
|
|
jpayne@68
|
11039 'exception is temporarily saved. The "finally" clause is executed. '
|
|
jpayne@68
|
11040 'If\n'
|
|
jpayne@68
|
11041 'there is a saved exception it is re-raised at the end of the '
|
|
jpayne@68
|
11042 '"finally"\n'
|
|
jpayne@68
|
11043 'clause. If the "finally" clause raises another exception, the saved\n'
|
|
jpayne@68
|
11044 'exception is set as the context of the new exception. If the '
|
|
jpayne@68
|
11045 '"finally"\n'
|
|
jpayne@68
|
11046 'clause executes a "return", "break" or "continue" statement, the '
|
|
jpayne@68
|
11047 'saved\n'
|
|
jpayne@68
|
11048 'exception is discarded:\n'
|
|
jpayne@68
|
11049 '\n'
|
|
jpayne@68
|
11050 ' >>> def f():\n'
|
|
jpayne@68
|
11051 ' ... try:\n'
|
|
jpayne@68
|
11052 ' ... 1/0\n'
|
|
jpayne@68
|
11053 ' ... finally:\n'
|
|
jpayne@68
|
11054 ' ... return 42\n'
|
|
jpayne@68
|
11055 ' ...\n'
|
|
jpayne@68
|
11056 ' >>> f()\n'
|
|
jpayne@68
|
11057 ' 42\n'
|
|
jpayne@68
|
11058 '\n'
|
|
jpayne@68
|
11059 'The exception information is not available to the program during\n'
|
|
jpayne@68
|
11060 'execution of the "finally" clause.\n'
|
|
jpayne@68
|
11061 '\n'
|
|
jpayne@68
|
11062 'When a "return", "break" or "continue" statement is executed in the\n'
|
|
jpayne@68
|
11063 '"try" suite of a "try"…"finally" statement, the "finally" clause is\n'
|
|
jpayne@68
|
11064 'also executed ‘on the way out.’\n'
|
|
jpayne@68
|
11065 '\n'
|
|
jpayne@68
|
11066 'The return value of a function is determined by the last "return"\n'
|
|
jpayne@68
|
11067 'statement executed. Since the "finally" clause always executes, a\n'
|
|
jpayne@68
|
11068 '"return" statement executed in the "finally" clause will always be '
|
|
jpayne@68
|
11069 'the\n'
|
|
jpayne@68
|
11070 'last one executed:\n'
|
|
jpayne@68
|
11071 '\n'
|
|
jpayne@68
|
11072 ' >>> def foo():\n'
|
|
jpayne@68
|
11073 ' ... try:\n'
|
|
jpayne@68
|
11074 " ... return 'try'\n"
|
|
jpayne@68
|
11075 ' ... finally:\n'
|
|
jpayne@68
|
11076 " ... return 'finally'\n"
|
|
jpayne@68
|
11077 ' ...\n'
|
|
jpayne@68
|
11078 ' >>> foo()\n'
|
|
jpayne@68
|
11079 " 'finally'\n"
|
|
jpayne@68
|
11080 '\n'
|
|
jpayne@68
|
11081 'Additional information on exceptions can be found in section\n'
|
|
jpayne@68
|
11082 'Exceptions, and information on using the "raise" statement to '
|
|
jpayne@68
|
11083 'generate\n'
|
|
jpayne@68
|
11084 'exceptions may be found in section The raise statement.\n'
|
|
jpayne@68
|
11085 '\n'
|
|
jpayne@68
|
11086 'Changed in version 3.8: Prior to Python 3.8, a "continue" statement\n'
|
|
jpayne@68
|
11087 'was illegal in the "finally" clause due to a problem with the\n'
|
|
jpayne@68
|
11088 'implementation.\n',
|
|
jpayne@68
|
11089 'types': 'The standard type hierarchy\n'
|
|
jpayne@68
|
11090 '***************************\n'
|
|
jpayne@68
|
11091 '\n'
|
|
jpayne@68
|
11092 'Below is a list of the types that are built into Python. '
|
|
jpayne@68
|
11093 'Extension\n'
|
|
jpayne@68
|
11094 'modules (written in C, Java, or other languages, depending on the\n'
|
|
jpayne@68
|
11095 'implementation) can define additional types. Future versions of\n'
|
|
jpayne@68
|
11096 'Python may add types to the type hierarchy (e.g., rational '
|
|
jpayne@68
|
11097 'numbers,\n'
|
|
jpayne@68
|
11098 'efficiently stored arrays of integers, etc.), although such '
|
|
jpayne@68
|
11099 'additions\n'
|
|
jpayne@68
|
11100 'will often be provided via the standard library instead.\n'
|
|
jpayne@68
|
11101 '\n'
|
|
jpayne@68
|
11102 'Some of the type descriptions below contain a paragraph listing\n'
|
|
jpayne@68
|
11103 '‘special attributes.’ These are attributes that provide access to '
|
|
jpayne@68
|
11104 'the\n'
|
|
jpayne@68
|
11105 'implementation and are not intended for general use. Their '
|
|
jpayne@68
|
11106 'definition\n'
|
|
jpayne@68
|
11107 'may change in the future.\n'
|
|
jpayne@68
|
11108 '\n'
|
|
jpayne@68
|
11109 'None\n'
|
|
jpayne@68
|
11110 ' This type has a single value. There is a single object with '
|
|
jpayne@68
|
11111 'this\n'
|
|
jpayne@68
|
11112 ' value. This object is accessed through the built-in name "None". '
|
|
jpayne@68
|
11113 'It\n'
|
|
jpayne@68
|
11114 ' is used to signify the absence of a value in many situations, '
|
|
jpayne@68
|
11115 'e.g.,\n'
|
|
jpayne@68
|
11116 ' it is returned from functions that don’t explicitly return\n'
|
|
jpayne@68
|
11117 ' anything. Its truth value is false.\n'
|
|
jpayne@68
|
11118 '\n'
|
|
jpayne@68
|
11119 'NotImplemented\n'
|
|
jpayne@68
|
11120 ' This type has a single value. There is a single object with '
|
|
jpayne@68
|
11121 'this\n'
|
|
jpayne@68
|
11122 ' value. This object is accessed through the built-in name\n'
|
|
jpayne@68
|
11123 ' "NotImplemented". Numeric methods and rich comparison methods\n'
|
|
jpayne@68
|
11124 ' should return this value if they do not implement the operation '
|
|
jpayne@68
|
11125 'for\n'
|
|
jpayne@68
|
11126 ' the operands provided. (The interpreter will then try the\n'
|
|
jpayne@68
|
11127 ' reflected operation, or some other fallback, depending on the\n'
|
|
jpayne@68
|
11128 ' operator.) Its truth value is true.\n'
|
|
jpayne@68
|
11129 '\n'
|
|
jpayne@68
|
11130 ' See Implementing the arithmetic operations for more details.\n'
|
|
jpayne@68
|
11131 '\n'
|
|
jpayne@68
|
11132 'Ellipsis\n'
|
|
jpayne@68
|
11133 ' This type has a single value. There is a single object with '
|
|
jpayne@68
|
11134 'this\n'
|
|
jpayne@68
|
11135 ' value. This object is accessed through the literal "..." or the\n'
|
|
jpayne@68
|
11136 ' built-in name "Ellipsis". Its truth value is true.\n'
|
|
jpayne@68
|
11137 '\n'
|
|
jpayne@68
|
11138 '"numbers.Number"\n'
|
|
jpayne@68
|
11139 ' These are created by numeric literals and returned as results '
|
|
jpayne@68
|
11140 'by\n'
|
|
jpayne@68
|
11141 ' arithmetic operators and arithmetic built-in functions. '
|
|
jpayne@68
|
11142 'Numeric\n'
|
|
jpayne@68
|
11143 ' objects are immutable; once created their value never changes.\n'
|
|
jpayne@68
|
11144 ' Python numbers are of course strongly related to mathematical\n'
|
|
jpayne@68
|
11145 ' numbers, but subject to the limitations of numerical '
|
|
jpayne@68
|
11146 'representation\n'
|
|
jpayne@68
|
11147 ' in computers.\n'
|
|
jpayne@68
|
11148 '\n'
|
|
jpayne@68
|
11149 ' Python distinguishes between integers, floating point numbers, '
|
|
jpayne@68
|
11150 'and\n'
|
|
jpayne@68
|
11151 ' complex numbers:\n'
|
|
jpayne@68
|
11152 '\n'
|
|
jpayne@68
|
11153 ' "numbers.Integral"\n'
|
|
jpayne@68
|
11154 ' These represent elements from the mathematical set of '
|
|
jpayne@68
|
11155 'integers\n'
|
|
jpayne@68
|
11156 ' (positive and negative).\n'
|
|
jpayne@68
|
11157 '\n'
|
|
jpayne@68
|
11158 ' There are two types of integers:\n'
|
|
jpayne@68
|
11159 '\n'
|
|
jpayne@68
|
11160 ' Integers ("int")\n'
|
|
jpayne@68
|
11161 '\n'
|
|
jpayne@68
|
11162 ' These represent numbers in an unlimited range, subject to\n'
|
|
jpayne@68
|
11163 ' available (virtual) memory only. For the purpose of '
|
|
jpayne@68
|
11164 'shift\n'
|
|
jpayne@68
|
11165 ' and mask operations, a binary representation is assumed, '
|
|
jpayne@68
|
11166 'and\n'
|
|
jpayne@68
|
11167 ' negative numbers are represented in a variant of 2’s\n'
|
|
jpayne@68
|
11168 ' complement which gives the illusion of an infinite string '
|
|
jpayne@68
|
11169 'of\n'
|
|
jpayne@68
|
11170 ' sign bits extending to the left.\n'
|
|
jpayne@68
|
11171 '\n'
|
|
jpayne@68
|
11172 ' Booleans ("bool")\n'
|
|
jpayne@68
|
11173 ' These represent the truth values False and True. The two\n'
|
|
jpayne@68
|
11174 ' objects representing the values "False" and "True" are '
|
|
jpayne@68
|
11175 'the\n'
|
|
jpayne@68
|
11176 ' only Boolean objects. The Boolean type is a subtype of '
|
|
jpayne@68
|
11177 'the\n'
|
|
jpayne@68
|
11178 ' integer type, and Boolean values behave like the values 0 '
|
|
jpayne@68
|
11179 'and\n'
|
|
jpayne@68
|
11180 ' 1, respectively, in almost all contexts, the exception '
|
|
jpayne@68
|
11181 'being\n'
|
|
jpayne@68
|
11182 ' that when converted to a string, the strings ""False"" or\n'
|
|
jpayne@68
|
11183 ' ""True"" are returned, respectively.\n'
|
|
jpayne@68
|
11184 '\n'
|
|
jpayne@68
|
11185 ' The rules for integer representation are intended to give '
|
|
jpayne@68
|
11186 'the\n'
|
|
jpayne@68
|
11187 ' most meaningful interpretation of shift and mask operations\n'
|
|
jpayne@68
|
11188 ' involving negative integers.\n'
|
|
jpayne@68
|
11189 '\n'
|
|
jpayne@68
|
11190 ' "numbers.Real" ("float")\n'
|
|
jpayne@68
|
11191 ' These represent machine-level double precision floating '
|
|
jpayne@68
|
11192 'point\n'
|
|
jpayne@68
|
11193 ' numbers. You are at the mercy of the underlying machine\n'
|
|
jpayne@68
|
11194 ' architecture (and C or Java implementation) for the accepted\n'
|
|
jpayne@68
|
11195 ' range and handling of overflow. Python does not support '
|
|
jpayne@68
|
11196 'single-\n'
|
|
jpayne@68
|
11197 ' precision floating point numbers; the savings in processor '
|
|
jpayne@68
|
11198 'and\n'
|
|
jpayne@68
|
11199 ' memory usage that are usually the reason for using these are\n'
|
|
jpayne@68
|
11200 ' dwarfed by the overhead of using objects in Python, so there '
|
|
jpayne@68
|
11201 'is\n'
|
|
jpayne@68
|
11202 ' no reason to complicate the language with two kinds of '
|
|
jpayne@68
|
11203 'floating\n'
|
|
jpayne@68
|
11204 ' point numbers.\n'
|
|
jpayne@68
|
11205 '\n'
|
|
jpayne@68
|
11206 ' "numbers.Complex" ("complex")\n'
|
|
jpayne@68
|
11207 ' These represent complex numbers as a pair of machine-level\n'
|
|
jpayne@68
|
11208 ' double precision floating point numbers. The same caveats '
|
|
jpayne@68
|
11209 'apply\n'
|
|
jpayne@68
|
11210 ' as for floating point numbers. The real and imaginary parts '
|
|
jpayne@68
|
11211 'of a\n'
|
|
jpayne@68
|
11212 ' complex number "z" can be retrieved through the read-only\n'
|
|
jpayne@68
|
11213 ' attributes "z.real" and "z.imag".\n'
|
|
jpayne@68
|
11214 '\n'
|
|
jpayne@68
|
11215 'Sequences\n'
|
|
jpayne@68
|
11216 ' These represent finite ordered sets indexed by non-negative\n'
|
|
jpayne@68
|
11217 ' numbers. The built-in function "len()" returns the number of '
|
|
jpayne@68
|
11218 'items\n'
|
|
jpayne@68
|
11219 ' of a sequence. When the length of a sequence is *n*, the index '
|
|
jpayne@68
|
11220 'set\n'
|
|
jpayne@68
|
11221 ' contains the numbers 0, 1, …, *n*-1. Item *i* of sequence *a* '
|
|
jpayne@68
|
11222 'is\n'
|
|
jpayne@68
|
11223 ' selected by "a[i]".\n'
|
|
jpayne@68
|
11224 '\n'
|
|
jpayne@68
|
11225 ' Sequences also support slicing: "a[i:j]" selects all items with\n'
|
|
jpayne@68
|
11226 ' index *k* such that *i* "<=" *k* "<" *j*. When used as an\n'
|
|
jpayne@68
|
11227 ' expression, a slice is a sequence of the same type. This '
|
|
jpayne@68
|
11228 'implies\n'
|
|
jpayne@68
|
11229 ' that the index set is renumbered so that it starts at 0.\n'
|
|
jpayne@68
|
11230 '\n'
|
|
jpayne@68
|
11231 ' Some sequences also support “extended slicing” with a third '
|
|
jpayne@68
|
11232 '“step”\n'
|
|
jpayne@68
|
11233 ' parameter: "a[i:j:k]" selects all items of *a* with index *x* '
|
|
jpayne@68
|
11234 'where\n'
|
|
jpayne@68
|
11235 ' "x = i + n*k", *n* ">=" "0" and *i* "<=" *x* "<" *j*.\n'
|
|
jpayne@68
|
11236 '\n'
|
|
jpayne@68
|
11237 ' Sequences are distinguished according to their mutability:\n'
|
|
jpayne@68
|
11238 '\n'
|
|
jpayne@68
|
11239 ' Immutable sequences\n'
|
|
jpayne@68
|
11240 ' An object of an immutable sequence type cannot change once it '
|
|
jpayne@68
|
11241 'is\n'
|
|
jpayne@68
|
11242 ' created. (If the object contains references to other '
|
|
jpayne@68
|
11243 'objects,\n'
|
|
jpayne@68
|
11244 ' these other objects may be mutable and may be changed; '
|
|
jpayne@68
|
11245 'however,\n'
|
|
jpayne@68
|
11246 ' the collection of objects directly referenced by an '
|
|
jpayne@68
|
11247 'immutable\n'
|
|
jpayne@68
|
11248 ' object cannot change.)\n'
|
|
jpayne@68
|
11249 '\n'
|
|
jpayne@68
|
11250 ' The following types are immutable sequences:\n'
|
|
jpayne@68
|
11251 '\n'
|
|
jpayne@68
|
11252 ' Strings\n'
|
|
jpayne@68
|
11253 ' A string is a sequence of values that represent Unicode '
|
|
jpayne@68
|
11254 'code\n'
|
|
jpayne@68
|
11255 ' points. All the code points in the range "U+0000 - '
|
|
jpayne@68
|
11256 'U+10FFFF"\n'
|
|
jpayne@68
|
11257 ' can be represented in a string. Python doesn’t have a '
|
|
jpayne@68
|
11258 '"char"\n'
|
|
jpayne@68
|
11259 ' type; instead, every code point in the string is '
|
|
jpayne@68
|
11260 'represented\n'
|
|
jpayne@68
|
11261 ' as a string object with length "1". The built-in '
|
|
jpayne@68
|
11262 'function\n'
|
|
jpayne@68
|
11263 ' "ord()" converts a code point from its string form to an\n'
|
|
jpayne@68
|
11264 ' integer in the range "0 - 10FFFF"; "chr()" converts an\n'
|
|
jpayne@68
|
11265 ' integer in the range "0 - 10FFFF" to the corresponding '
|
|
jpayne@68
|
11266 'length\n'
|
|
jpayne@68
|
11267 ' "1" string object. "str.encode()" can be used to convert '
|
|
jpayne@68
|
11268 'a\n'
|
|
jpayne@68
|
11269 ' "str" to "bytes" using the given text encoding, and\n'
|
|
jpayne@68
|
11270 ' "bytes.decode()" can be used to achieve the opposite.\n'
|
|
jpayne@68
|
11271 '\n'
|
|
jpayne@68
|
11272 ' Tuples\n'
|
|
jpayne@68
|
11273 ' The items of a tuple are arbitrary Python objects. Tuples '
|
|
jpayne@68
|
11274 'of\n'
|
|
jpayne@68
|
11275 ' two or more items are formed by comma-separated lists of\n'
|
|
jpayne@68
|
11276 ' expressions. A tuple of one item (a ‘singleton’) can be\n'
|
|
jpayne@68
|
11277 ' formed by affixing a comma to an expression (an expression '
|
|
jpayne@68
|
11278 'by\n'
|
|
jpayne@68
|
11279 ' itself does not create a tuple, since parentheses must be\n'
|
|
jpayne@68
|
11280 ' usable for grouping of expressions). An empty tuple can '
|
|
jpayne@68
|
11281 'be\n'
|
|
jpayne@68
|
11282 ' formed by an empty pair of parentheses.\n'
|
|
jpayne@68
|
11283 '\n'
|
|
jpayne@68
|
11284 ' Bytes\n'
|
|
jpayne@68
|
11285 ' A bytes object is an immutable array. The items are '
|
|
jpayne@68
|
11286 '8-bit\n'
|
|
jpayne@68
|
11287 ' bytes, represented by integers in the range 0 <= x < 256.\n'
|
|
jpayne@68
|
11288 ' Bytes literals (like "b\'abc\'") and the built-in '
|
|
jpayne@68
|
11289 '"bytes()"\n'
|
|
jpayne@68
|
11290 ' constructor can be used to create bytes objects. Also, '
|
|
jpayne@68
|
11291 'bytes\n'
|
|
jpayne@68
|
11292 ' objects can be decoded to strings via the "decode()" '
|
|
jpayne@68
|
11293 'method.\n'
|
|
jpayne@68
|
11294 '\n'
|
|
jpayne@68
|
11295 ' Mutable sequences\n'
|
|
jpayne@68
|
11296 ' Mutable sequences can be changed after they are created. '
|
|
jpayne@68
|
11297 'The\n'
|
|
jpayne@68
|
11298 ' subscription and slicing notations can be used as the target '
|
|
jpayne@68
|
11299 'of\n'
|
|
jpayne@68
|
11300 ' assignment and "del" (delete) statements.\n'
|
|
jpayne@68
|
11301 '\n'
|
|
jpayne@68
|
11302 ' There are currently two intrinsic mutable sequence types:\n'
|
|
jpayne@68
|
11303 '\n'
|
|
jpayne@68
|
11304 ' Lists\n'
|
|
jpayne@68
|
11305 ' The items of a list are arbitrary Python objects. Lists '
|
|
jpayne@68
|
11306 'are\n'
|
|
jpayne@68
|
11307 ' formed by placing a comma-separated list of expressions '
|
|
jpayne@68
|
11308 'in\n'
|
|
jpayne@68
|
11309 ' square brackets. (Note that there are no special cases '
|
|
jpayne@68
|
11310 'needed\n'
|
|
jpayne@68
|
11311 ' to form lists of length 0 or 1.)\n'
|
|
jpayne@68
|
11312 '\n'
|
|
jpayne@68
|
11313 ' Byte Arrays\n'
|
|
jpayne@68
|
11314 ' A bytearray object is a mutable array. They are created '
|
|
jpayne@68
|
11315 'by\n'
|
|
jpayne@68
|
11316 ' the built-in "bytearray()" constructor. Aside from being\n'
|
|
jpayne@68
|
11317 ' mutable (and hence unhashable), byte arrays otherwise '
|
|
jpayne@68
|
11318 'provide\n'
|
|
jpayne@68
|
11319 ' the same interface and functionality as immutable "bytes"\n'
|
|
jpayne@68
|
11320 ' objects.\n'
|
|
jpayne@68
|
11321 '\n'
|
|
jpayne@68
|
11322 ' The extension module "array" provides an additional example '
|
|
jpayne@68
|
11323 'of a\n'
|
|
jpayne@68
|
11324 ' mutable sequence type, as does the "collections" module.\n'
|
|
jpayne@68
|
11325 '\n'
|
|
jpayne@68
|
11326 'Set types\n'
|
|
jpayne@68
|
11327 ' These represent unordered, finite sets of unique, immutable\n'
|
|
jpayne@68
|
11328 ' objects. As such, they cannot be indexed by any subscript. '
|
|
jpayne@68
|
11329 'However,\n'
|
|
jpayne@68
|
11330 ' they can be iterated over, and the built-in function "len()"\n'
|
|
jpayne@68
|
11331 ' returns the number of items in a set. Common uses for sets are '
|
|
jpayne@68
|
11332 'fast\n'
|
|
jpayne@68
|
11333 ' membership testing, removing duplicates from a sequence, and\n'
|
|
jpayne@68
|
11334 ' computing mathematical operations such as intersection, union,\n'
|
|
jpayne@68
|
11335 ' difference, and symmetric difference.\n'
|
|
jpayne@68
|
11336 '\n'
|
|
jpayne@68
|
11337 ' For set elements, the same immutability rules apply as for\n'
|
|
jpayne@68
|
11338 ' dictionary keys. Note that numeric types obey the normal rules '
|
|
jpayne@68
|
11339 'for\n'
|
|
jpayne@68
|
11340 ' numeric comparison: if two numbers compare equal (e.g., "1" and\n'
|
|
jpayne@68
|
11341 ' "1.0"), only one of them can be contained in a set.\n'
|
|
jpayne@68
|
11342 '\n'
|
|
jpayne@68
|
11343 ' There are currently two intrinsic set types:\n'
|
|
jpayne@68
|
11344 '\n'
|
|
jpayne@68
|
11345 ' Sets\n'
|
|
jpayne@68
|
11346 ' These represent a mutable set. They are created by the '
|
|
jpayne@68
|
11347 'built-in\n'
|
|
jpayne@68
|
11348 ' "set()" constructor and can be modified afterwards by '
|
|
jpayne@68
|
11349 'several\n'
|
|
jpayne@68
|
11350 ' methods, such as "add()".\n'
|
|
jpayne@68
|
11351 '\n'
|
|
jpayne@68
|
11352 ' Frozen sets\n'
|
|
jpayne@68
|
11353 ' These represent an immutable set. They are created by the\n'
|
|
jpayne@68
|
11354 ' built-in "frozenset()" constructor. As a frozenset is '
|
|
jpayne@68
|
11355 'immutable\n'
|
|
jpayne@68
|
11356 ' and *hashable*, it can be used again as an element of '
|
|
jpayne@68
|
11357 'another\n'
|
|
jpayne@68
|
11358 ' set, or as a dictionary key.\n'
|
|
jpayne@68
|
11359 '\n'
|
|
jpayne@68
|
11360 'Mappings\n'
|
|
jpayne@68
|
11361 ' These represent finite sets of objects indexed by arbitrary '
|
|
jpayne@68
|
11362 'index\n'
|
|
jpayne@68
|
11363 ' sets. The subscript notation "a[k]" selects the item indexed by '
|
|
jpayne@68
|
11364 '"k"\n'
|
|
jpayne@68
|
11365 ' from the mapping "a"; this can be used in expressions and as '
|
|
jpayne@68
|
11366 'the\n'
|
|
jpayne@68
|
11367 ' target of assignments or "del" statements. The built-in '
|
|
jpayne@68
|
11368 'function\n'
|
|
jpayne@68
|
11369 ' "len()" returns the number of items in a mapping.\n'
|
|
jpayne@68
|
11370 '\n'
|
|
jpayne@68
|
11371 ' There is currently a single intrinsic mapping type:\n'
|
|
jpayne@68
|
11372 '\n'
|
|
jpayne@68
|
11373 ' Dictionaries\n'
|
|
jpayne@68
|
11374 ' These represent finite sets of objects indexed by nearly\n'
|
|
jpayne@68
|
11375 ' arbitrary values. The only types of values not acceptable '
|
|
jpayne@68
|
11376 'as\n'
|
|
jpayne@68
|
11377 ' keys are values containing lists or dictionaries or other\n'
|
|
jpayne@68
|
11378 ' mutable types that are compared by value rather than by '
|
|
jpayne@68
|
11379 'object\n'
|
|
jpayne@68
|
11380 ' identity, the reason being that the efficient implementation '
|
|
jpayne@68
|
11381 'of\n'
|
|
jpayne@68
|
11382 ' dictionaries requires a key’s hash value to remain constant.\n'
|
|
jpayne@68
|
11383 ' Numeric types used for keys obey the normal rules for '
|
|
jpayne@68
|
11384 'numeric\n'
|
|
jpayne@68
|
11385 ' comparison: if two numbers compare equal (e.g., "1" and '
|
|
jpayne@68
|
11386 '"1.0")\n'
|
|
jpayne@68
|
11387 ' then they can be used interchangeably to index the same\n'
|
|
jpayne@68
|
11388 ' dictionary entry.\n'
|
|
jpayne@68
|
11389 '\n'
|
|
jpayne@68
|
11390 ' Dictionaries are mutable; they can be created by the "{...}"\n'
|
|
jpayne@68
|
11391 ' notation (see section Dictionary displays).\n'
|
|
jpayne@68
|
11392 '\n'
|
|
jpayne@68
|
11393 ' The extension modules "dbm.ndbm" and "dbm.gnu" provide\n'
|
|
jpayne@68
|
11394 ' additional examples of mapping types, as does the '
|
|
jpayne@68
|
11395 '"collections"\n'
|
|
jpayne@68
|
11396 ' module.\n'
|
|
jpayne@68
|
11397 '\n'
|
|
jpayne@68
|
11398 'Callable types\n'
|
|
jpayne@68
|
11399 ' These are the types to which the function call operation (see\n'
|
|
jpayne@68
|
11400 ' section Calls) can be applied:\n'
|
|
jpayne@68
|
11401 '\n'
|
|
jpayne@68
|
11402 ' User-defined functions\n'
|
|
jpayne@68
|
11403 ' A user-defined function object is created by a function\n'
|
|
jpayne@68
|
11404 ' definition (see section Function definitions). It should be\n'
|
|
jpayne@68
|
11405 ' called with an argument list containing the same number of '
|
|
jpayne@68
|
11406 'items\n'
|
|
jpayne@68
|
11407 ' as the function’s formal parameter list.\n'
|
|
jpayne@68
|
11408 '\n'
|
|
jpayne@68
|
11409 ' Special attributes:\n'
|
|
jpayne@68
|
11410 '\n'
|
|
jpayne@68
|
11411 ' '
|
|
jpayne@68
|
11412 '+---------------------------+---------------------------------+-------------+\n'
|
|
jpayne@68
|
11413 ' | Attribute | Meaning '
|
|
jpayne@68
|
11414 '| |\n'
|
|
jpayne@68
|
11415 ' '
|
|
jpayne@68
|
11416 '|===========================|=================================|=============|\n'
|
|
jpayne@68
|
11417 ' | "__doc__" | The function’s documentation '
|
|
jpayne@68
|
11418 '| Writable |\n'
|
|
jpayne@68
|
11419 ' | | string, or "None" if '
|
|
jpayne@68
|
11420 '| |\n'
|
|
jpayne@68
|
11421 ' | | unavailable; not inherited by '
|
|
jpayne@68
|
11422 '| |\n'
|
|
jpayne@68
|
11423 ' | | subclasses. '
|
|
jpayne@68
|
11424 '| |\n'
|
|
jpayne@68
|
11425 ' '
|
|
jpayne@68
|
11426 '+---------------------------+---------------------------------+-------------+\n'
|
|
jpayne@68
|
11427 ' | "__name__" | The function’s name. '
|
|
jpayne@68
|
11428 '| Writable |\n'
|
|
jpayne@68
|
11429 ' '
|
|
jpayne@68
|
11430 '+---------------------------+---------------------------------+-------------+\n'
|
|
jpayne@68
|
11431 ' | "__qualname__" | The function’s *qualified '
|
|
jpayne@68
|
11432 '| Writable |\n'
|
|
jpayne@68
|
11433 ' | | name*. New in version 3.3. '
|
|
jpayne@68
|
11434 '| |\n'
|
|
jpayne@68
|
11435 ' '
|
|
jpayne@68
|
11436 '+---------------------------+---------------------------------+-------------+\n'
|
|
jpayne@68
|
11437 ' | "__module__" | The name of the module the '
|
|
jpayne@68
|
11438 '| Writable |\n'
|
|
jpayne@68
|
11439 ' | | function was defined in, or '
|
|
jpayne@68
|
11440 '| |\n'
|
|
jpayne@68
|
11441 ' | | "None" if unavailable. '
|
|
jpayne@68
|
11442 '| |\n'
|
|
jpayne@68
|
11443 ' '
|
|
jpayne@68
|
11444 '+---------------------------+---------------------------------+-------------+\n'
|
|
jpayne@68
|
11445 ' | "__defaults__" | A tuple containing default '
|
|
jpayne@68
|
11446 '| Writable |\n'
|
|
jpayne@68
|
11447 ' | | argument values for those '
|
|
jpayne@68
|
11448 '| |\n'
|
|
jpayne@68
|
11449 ' | | arguments that have defaults, '
|
|
jpayne@68
|
11450 '| |\n'
|
|
jpayne@68
|
11451 ' | | or "None" if no arguments have '
|
|
jpayne@68
|
11452 '| |\n'
|
|
jpayne@68
|
11453 ' | | a default value. '
|
|
jpayne@68
|
11454 '| |\n'
|
|
jpayne@68
|
11455 ' '
|
|
jpayne@68
|
11456 '+---------------------------+---------------------------------+-------------+\n'
|
|
jpayne@68
|
11457 ' | "__code__" | The code object representing '
|
|
jpayne@68
|
11458 '| Writable |\n'
|
|
jpayne@68
|
11459 ' | | the compiled function body. '
|
|
jpayne@68
|
11460 '| |\n'
|
|
jpayne@68
|
11461 ' '
|
|
jpayne@68
|
11462 '+---------------------------+---------------------------------+-------------+\n'
|
|
jpayne@68
|
11463 ' | "__globals__" | A reference to the dictionary '
|
|
jpayne@68
|
11464 '| Read-only |\n'
|
|
jpayne@68
|
11465 ' | | that holds the function’s '
|
|
jpayne@68
|
11466 '| |\n'
|
|
jpayne@68
|
11467 ' | | global variables — the global '
|
|
jpayne@68
|
11468 '| |\n'
|
|
jpayne@68
|
11469 ' | | namespace of the module in '
|
|
jpayne@68
|
11470 '| |\n'
|
|
jpayne@68
|
11471 ' | | which the function was defined. '
|
|
jpayne@68
|
11472 '| |\n'
|
|
jpayne@68
|
11473 ' '
|
|
jpayne@68
|
11474 '+---------------------------+---------------------------------+-------------+\n'
|
|
jpayne@68
|
11475 ' | "__dict__" | The namespace supporting '
|
|
jpayne@68
|
11476 '| Writable |\n'
|
|
jpayne@68
|
11477 ' | | arbitrary function attributes. '
|
|
jpayne@68
|
11478 '| |\n'
|
|
jpayne@68
|
11479 ' '
|
|
jpayne@68
|
11480 '+---------------------------+---------------------------------+-------------+\n'
|
|
jpayne@68
|
11481 ' | "__closure__" | "None" or a tuple of cells that '
|
|
jpayne@68
|
11482 '| Read-only |\n'
|
|
jpayne@68
|
11483 ' | | contain bindings for the '
|
|
jpayne@68
|
11484 '| |\n'
|
|
jpayne@68
|
11485 ' | | function’s free variables. See '
|
|
jpayne@68
|
11486 '| |\n'
|
|
jpayne@68
|
11487 ' | | below for information on the '
|
|
jpayne@68
|
11488 '| |\n'
|
|
jpayne@68
|
11489 ' | | "cell_contents" attribute. '
|
|
jpayne@68
|
11490 '| |\n'
|
|
jpayne@68
|
11491 ' '
|
|
jpayne@68
|
11492 '+---------------------------+---------------------------------+-------------+\n'
|
|
jpayne@68
|
11493 ' | "__annotations__" | A dict containing annotations '
|
|
jpayne@68
|
11494 '| Writable |\n'
|
|
jpayne@68
|
11495 ' | | of parameters. The keys of the '
|
|
jpayne@68
|
11496 '| |\n'
|
|
jpayne@68
|
11497 ' | | dict are the parameter names, '
|
|
jpayne@68
|
11498 '| |\n'
|
|
jpayne@68
|
11499 ' | | and "\'return\'" for the '
|
|
jpayne@68
|
11500 'return | |\n'
|
|
jpayne@68
|
11501 ' | | annotation, if provided. '
|
|
jpayne@68
|
11502 '| |\n'
|
|
jpayne@68
|
11503 ' '
|
|
jpayne@68
|
11504 '+---------------------------+---------------------------------+-------------+\n'
|
|
jpayne@68
|
11505 ' | "__kwdefaults__" | A dict containing defaults for '
|
|
jpayne@68
|
11506 '| Writable |\n'
|
|
jpayne@68
|
11507 ' | | keyword-only parameters. '
|
|
jpayne@68
|
11508 '| |\n'
|
|
jpayne@68
|
11509 ' '
|
|
jpayne@68
|
11510 '+---------------------------+---------------------------------+-------------+\n'
|
|
jpayne@68
|
11511 '\n'
|
|
jpayne@68
|
11512 ' Most of the attributes labelled “Writable” check the type of '
|
|
jpayne@68
|
11513 'the\n'
|
|
jpayne@68
|
11514 ' assigned value.\n'
|
|
jpayne@68
|
11515 '\n'
|
|
jpayne@68
|
11516 ' Function objects also support getting and setting arbitrary\n'
|
|
jpayne@68
|
11517 ' attributes, which can be used, for example, to attach '
|
|
jpayne@68
|
11518 'metadata\n'
|
|
jpayne@68
|
11519 ' to functions. Regular attribute dot-notation is used to get '
|
|
jpayne@68
|
11520 'and\n'
|
|
jpayne@68
|
11521 ' set such attributes. *Note that the current implementation '
|
|
jpayne@68
|
11522 'only\n'
|
|
jpayne@68
|
11523 ' supports function attributes on user-defined functions. '
|
|
jpayne@68
|
11524 'Function\n'
|
|
jpayne@68
|
11525 ' attributes on built-in functions may be supported in the\n'
|
|
jpayne@68
|
11526 ' future.*\n'
|
|
jpayne@68
|
11527 '\n'
|
|
jpayne@68
|
11528 ' A cell object has the attribute "cell_contents". This can be\n'
|
|
jpayne@68
|
11529 ' used to get the value of the cell, as well as set the value.\n'
|
|
jpayne@68
|
11530 '\n'
|
|
jpayne@68
|
11531 ' Additional information about a function’s definition can be\n'
|
|
jpayne@68
|
11532 ' retrieved from its code object; see the description of '
|
|
jpayne@68
|
11533 'internal\n'
|
|
jpayne@68
|
11534 ' types below. The "cell" type can be accessed in the "types"\n'
|
|
jpayne@68
|
11535 ' module.\n'
|
|
jpayne@68
|
11536 '\n'
|
|
jpayne@68
|
11537 ' Instance methods\n'
|
|
jpayne@68
|
11538 ' An instance method object combines a class, a class instance '
|
|
jpayne@68
|
11539 'and\n'
|
|
jpayne@68
|
11540 ' any callable object (normally a user-defined function).\n'
|
|
jpayne@68
|
11541 '\n'
|
|
jpayne@68
|
11542 ' Special read-only attributes: "__self__" is the class '
|
|
jpayne@68
|
11543 'instance\n'
|
|
jpayne@68
|
11544 ' object, "__func__" is the function object; "__doc__" is the\n'
|
|
jpayne@68
|
11545 ' method’s documentation (same as "__func__.__doc__"); '
|
|
jpayne@68
|
11546 '"__name__"\n'
|
|
jpayne@68
|
11547 ' is the method name (same as "__func__.__name__"); '
|
|
jpayne@68
|
11548 '"__module__"\n'
|
|
jpayne@68
|
11549 ' is the name of the module the method was defined in, or '
|
|
jpayne@68
|
11550 '"None"\n'
|
|
jpayne@68
|
11551 ' if unavailable.\n'
|
|
jpayne@68
|
11552 '\n'
|
|
jpayne@68
|
11553 ' Methods also support accessing (but not setting) the '
|
|
jpayne@68
|
11554 'arbitrary\n'
|
|
jpayne@68
|
11555 ' function attributes on the underlying function object.\n'
|
|
jpayne@68
|
11556 '\n'
|
|
jpayne@68
|
11557 ' User-defined method objects may be created when getting an\n'
|
|
jpayne@68
|
11558 ' attribute of a class (perhaps via an instance of that class), '
|
|
jpayne@68
|
11559 'if\n'
|
|
jpayne@68
|
11560 ' that attribute is a user-defined function object or a class\n'
|
|
jpayne@68
|
11561 ' method object.\n'
|
|
jpayne@68
|
11562 '\n'
|
|
jpayne@68
|
11563 ' When an instance method object is created by retrieving a '
|
|
jpayne@68
|
11564 'user-\n'
|
|
jpayne@68
|
11565 ' defined function object from a class via one of its '
|
|
jpayne@68
|
11566 'instances,\n'
|
|
jpayne@68
|
11567 ' its "__self__" attribute is the instance, and the method '
|
|
jpayne@68
|
11568 'object\n'
|
|
jpayne@68
|
11569 ' is said to be bound. The new method’s "__func__" attribute '
|
|
jpayne@68
|
11570 'is\n'
|
|
jpayne@68
|
11571 ' the original function object.\n'
|
|
jpayne@68
|
11572 '\n'
|
|
jpayne@68
|
11573 ' When an instance method object is created by retrieving a '
|
|
jpayne@68
|
11574 'class\n'
|
|
jpayne@68
|
11575 ' method object from a class or instance, its "__self__" '
|
|
jpayne@68
|
11576 'attribute\n'
|
|
jpayne@68
|
11577 ' is the class itself, and its "__func__" attribute is the\n'
|
|
jpayne@68
|
11578 ' function object underlying the class method.\n'
|
|
jpayne@68
|
11579 '\n'
|
|
jpayne@68
|
11580 ' When an instance method object is called, the underlying\n'
|
|
jpayne@68
|
11581 ' function ("__func__") is called, inserting the class '
|
|
jpayne@68
|
11582 'instance\n'
|
|
jpayne@68
|
11583 ' ("__self__") in front of the argument list. For instance, '
|
|
jpayne@68
|
11584 'when\n'
|
|
jpayne@68
|
11585 ' "C" is a class which contains a definition for a function '
|
|
jpayne@68
|
11586 '"f()",\n'
|
|
jpayne@68
|
11587 ' and "x" is an instance of "C", calling "x.f(1)" is equivalent '
|
|
jpayne@68
|
11588 'to\n'
|
|
jpayne@68
|
11589 ' calling "C.f(x, 1)".\n'
|
|
jpayne@68
|
11590 '\n'
|
|
jpayne@68
|
11591 ' When an instance method object is derived from a class '
|
|
jpayne@68
|
11592 'method\n'
|
|
jpayne@68
|
11593 ' object, the “class instance” stored in "__self__" will '
|
|
jpayne@68
|
11594 'actually\n'
|
|
jpayne@68
|
11595 ' be the class itself, so that calling either "x.f(1)" or '
|
|
jpayne@68
|
11596 '"C.f(1)"\n'
|
|
jpayne@68
|
11597 ' is equivalent to calling "f(C,1)" where "f" is the '
|
|
jpayne@68
|
11598 'underlying\n'
|
|
jpayne@68
|
11599 ' function.\n'
|
|
jpayne@68
|
11600 '\n'
|
|
jpayne@68
|
11601 ' Note that the transformation from function object to '
|
|
jpayne@68
|
11602 'instance\n'
|
|
jpayne@68
|
11603 ' method object happens each time the attribute is retrieved '
|
|
jpayne@68
|
11604 'from\n'
|
|
jpayne@68
|
11605 ' the instance. In some cases, a fruitful optimization is to\n'
|
|
jpayne@68
|
11606 ' assign the attribute to a local variable and call that local\n'
|
|
jpayne@68
|
11607 ' variable. Also notice that this transformation only happens '
|
|
jpayne@68
|
11608 'for\n'
|
|
jpayne@68
|
11609 ' user-defined functions; other callable objects (and all non-\n'
|
|
jpayne@68
|
11610 ' callable objects) are retrieved without transformation. It '
|
|
jpayne@68
|
11611 'is\n'
|
|
jpayne@68
|
11612 ' also important to note that user-defined functions which are\n'
|
|
jpayne@68
|
11613 ' attributes of a class instance are not converted to bound\n'
|
|
jpayne@68
|
11614 ' methods; this *only* happens when the function is an '
|
|
jpayne@68
|
11615 'attribute\n'
|
|
jpayne@68
|
11616 ' of the class.\n'
|
|
jpayne@68
|
11617 '\n'
|
|
jpayne@68
|
11618 ' Generator functions\n'
|
|
jpayne@68
|
11619 ' A function or method which uses the "yield" statement (see\n'
|
|
jpayne@68
|
11620 ' section The yield statement) is called a *generator '
|
|
jpayne@68
|
11621 'function*.\n'
|
|
jpayne@68
|
11622 ' Such a function, when called, always returns an iterator '
|
|
jpayne@68
|
11623 'object\n'
|
|
jpayne@68
|
11624 ' which can be used to execute the body of the function: '
|
|
jpayne@68
|
11625 'calling\n'
|
|
jpayne@68
|
11626 ' the iterator’s "iterator.__next__()" method will cause the\n'
|
|
jpayne@68
|
11627 ' function to execute until it provides a value using the '
|
|
jpayne@68
|
11628 '"yield"\n'
|
|
jpayne@68
|
11629 ' statement. When the function executes a "return" statement '
|
|
jpayne@68
|
11630 'or\n'
|
|
jpayne@68
|
11631 ' falls off the end, a "StopIteration" exception is raised and '
|
|
jpayne@68
|
11632 'the\n'
|
|
jpayne@68
|
11633 ' iterator will have reached the end of the set of values to '
|
|
jpayne@68
|
11634 'be\n'
|
|
jpayne@68
|
11635 ' returned.\n'
|
|
jpayne@68
|
11636 '\n'
|
|
jpayne@68
|
11637 ' Coroutine functions\n'
|
|
jpayne@68
|
11638 ' A function or method which is defined using "async def" is\n'
|
|
jpayne@68
|
11639 ' called a *coroutine function*. Such a function, when '
|
|
jpayne@68
|
11640 'called,\n'
|
|
jpayne@68
|
11641 ' returns a *coroutine* object. It may contain "await"\n'
|
|
jpayne@68
|
11642 ' expressions, as well as "async with" and "async for" '
|
|
jpayne@68
|
11643 'statements.\n'
|
|
jpayne@68
|
11644 ' See also the Coroutine Objects section.\n'
|
|
jpayne@68
|
11645 '\n'
|
|
jpayne@68
|
11646 ' Asynchronous generator functions\n'
|
|
jpayne@68
|
11647 ' A function or method which is defined using "async def" and\n'
|
|
jpayne@68
|
11648 ' which uses the "yield" statement is called a *asynchronous\n'
|
|
jpayne@68
|
11649 ' generator function*. Such a function, when called, returns '
|
|
jpayne@68
|
11650 'an\n'
|
|
jpayne@68
|
11651 ' asynchronous iterator object which can be used in an "async '
|
|
jpayne@68
|
11652 'for"\n'
|
|
jpayne@68
|
11653 ' statement to execute the body of the function.\n'
|
|
jpayne@68
|
11654 '\n'
|
|
jpayne@68
|
11655 ' Calling the asynchronous iterator’s "aiterator.__anext__()"\n'
|
|
jpayne@68
|
11656 ' method will return an *awaitable* which when awaited will\n'
|
|
jpayne@68
|
11657 ' execute until it provides a value using the "yield" '
|
|
jpayne@68
|
11658 'expression.\n'
|
|
jpayne@68
|
11659 ' When the function executes an empty "return" statement or '
|
|
jpayne@68
|
11660 'falls\n'
|
|
jpayne@68
|
11661 ' off the end, a "StopAsyncIteration" exception is raised and '
|
|
jpayne@68
|
11662 'the\n'
|
|
jpayne@68
|
11663 ' asynchronous iterator will have reached the end of the set '
|
|
jpayne@68
|
11664 'of\n'
|
|
jpayne@68
|
11665 ' values to be yielded.\n'
|
|
jpayne@68
|
11666 '\n'
|
|
jpayne@68
|
11667 ' Built-in functions\n'
|
|
jpayne@68
|
11668 ' A built-in function object is a wrapper around a C function.\n'
|
|
jpayne@68
|
11669 ' Examples of built-in functions are "len()" and "math.sin()"\n'
|
|
jpayne@68
|
11670 ' ("math" is a standard built-in module). The number and type '
|
|
jpayne@68
|
11671 'of\n'
|
|
jpayne@68
|
11672 ' the arguments are determined by the C function. Special '
|
|
jpayne@68
|
11673 'read-\n'
|
|
jpayne@68
|
11674 ' only attributes: "__doc__" is the function’s documentation\n'
|
|
jpayne@68
|
11675 ' string, or "None" if unavailable; "__name__" is the '
|
|
jpayne@68
|
11676 'function’s\n'
|
|
jpayne@68
|
11677 ' name; "__self__" is set to "None" (but see the next item);\n'
|
|
jpayne@68
|
11678 ' "__module__" is the name of the module the function was '
|
|
jpayne@68
|
11679 'defined\n'
|
|
jpayne@68
|
11680 ' in or "None" if unavailable.\n'
|
|
jpayne@68
|
11681 '\n'
|
|
jpayne@68
|
11682 ' Built-in methods\n'
|
|
jpayne@68
|
11683 ' This is really a different disguise of a built-in function, '
|
|
jpayne@68
|
11684 'this\n'
|
|
jpayne@68
|
11685 ' time containing an object passed to the C function as an\n'
|
|
jpayne@68
|
11686 ' implicit extra argument. An example of a built-in method is\n'
|
|
jpayne@68
|
11687 ' "alist.append()", assuming *alist* is a list object. In this\n'
|
|
jpayne@68
|
11688 ' case, the special read-only attribute "__self__" is set to '
|
|
jpayne@68
|
11689 'the\n'
|
|
jpayne@68
|
11690 ' object denoted by *alist*.\n'
|
|
jpayne@68
|
11691 '\n'
|
|
jpayne@68
|
11692 ' Classes\n'
|
|
jpayne@68
|
11693 ' Classes are callable. These objects normally act as '
|
|
jpayne@68
|
11694 'factories\n'
|
|
jpayne@68
|
11695 ' for new instances of themselves, but variations are possible '
|
|
jpayne@68
|
11696 'for\n'
|
|
jpayne@68
|
11697 ' class types that override "__new__()". The arguments of the\n'
|
|
jpayne@68
|
11698 ' call are passed to "__new__()" and, in the typical case, to\n'
|
|
jpayne@68
|
11699 ' "__init__()" to initialize the new instance.\n'
|
|
jpayne@68
|
11700 '\n'
|
|
jpayne@68
|
11701 ' Class Instances\n'
|
|
jpayne@68
|
11702 ' Instances of arbitrary classes can be made callable by '
|
|
jpayne@68
|
11703 'defining\n'
|
|
jpayne@68
|
11704 ' a "__call__()" method in their class.\n'
|
|
jpayne@68
|
11705 '\n'
|
|
jpayne@68
|
11706 'Modules\n'
|
|
jpayne@68
|
11707 ' Modules are a basic organizational unit of Python code, and are\n'
|
|
jpayne@68
|
11708 ' created by the import system as invoked either by the "import"\n'
|
|
jpayne@68
|
11709 ' statement, or by calling functions such as\n'
|
|
jpayne@68
|
11710 ' "importlib.import_module()" and built-in "__import__()". A '
|
|
jpayne@68
|
11711 'module\n'
|
|
jpayne@68
|
11712 ' object has a namespace implemented by a dictionary object (this '
|
|
jpayne@68
|
11713 'is\n'
|
|
jpayne@68
|
11714 ' the dictionary referenced by the "__globals__" attribute of\n'
|
|
jpayne@68
|
11715 ' functions defined in the module). Attribute references are\n'
|
|
jpayne@68
|
11716 ' translated to lookups in this dictionary, e.g., "m.x" is '
|
|
jpayne@68
|
11717 'equivalent\n'
|
|
jpayne@68
|
11718 ' to "m.__dict__["x"]". A module object does not contain the code\n'
|
|
jpayne@68
|
11719 ' object used to initialize the module (since it isn’t needed '
|
|
jpayne@68
|
11720 'once\n'
|
|
jpayne@68
|
11721 ' the initialization is done).\n'
|
|
jpayne@68
|
11722 '\n'
|
|
jpayne@68
|
11723 ' Attribute assignment updates the module’s namespace dictionary,\n'
|
|
jpayne@68
|
11724 ' e.g., "m.x = 1" is equivalent to "m.__dict__["x"] = 1".\n'
|
|
jpayne@68
|
11725 '\n'
|
|
jpayne@68
|
11726 ' Predefined (writable) attributes: "__name__" is the module’s '
|
|
jpayne@68
|
11727 'name;\n'
|
|
jpayne@68
|
11728 ' "__doc__" is the module’s documentation string, or "None" if\n'
|
|
jpayne@68
|
11729 ' unavailable; "__annotations__" (optional) is a dictionary\n'
|
|
jpayne@68
|
11730 ' containing *variable annotations* collected during module body\n'
|
|
jpayne@68
|
11731 ' execution; "__file__" is the pathname of the file from which '
|
|
jpayne@68
|
11732 'the\n'
|
|
jpayne@68
|
11733 ' module was loaded, if it was loaded from a file. The "__file__"\n'
|
|
jpayne@68
|
11734 ' attribute may be missing for certain types of modules, such as '
|
|
jpayne@68
|
11735 'C\n'
|
|
jpayne@68
|
11736 ' modules that are statically linked into the interpreter; for\n'
|
|
jpayne@68
|
11737 ' extension modules loaded dynamically from a shared library, it '
|
|
jpayne@68
|
11738 'is\n'
|
|
jpayne@68
|
11739 ' the pathname of the shared library file.\n'
|
|
jpayne@68
|
11740 '\n'
|
|
jpayne@68
|
11741 ' Special read-only attribute: "__dict__" is the module’s '
|
|
jpayne@68
|
11742 'namespace\n'
|
|
jpayne@68
|
11743 ' as a dictionary object.\n'
|
|
jpayne@68
|
11744 '\n'
|
|
jpayne@68
|
11745 ' **CPython implementation detail:** Because of the way CPython\n'
|
|
jpayne@68
|
11746 ' clears module dictionaries, the module dictionary will be '
|
|
jpayne@68
|
11747 'cleared\n'
|
|
jpayne@68
|
11748 ' when the module falls out of scope even if the dictionary still '
|
|
jpayne@68
|
11749 'has\n'
|
|
jpayne@68
|
11750 ' live references. To avoid this, copy the dictionary or keep '
|
|
jpayne@68
|
11751 'the\n'
|
|
jpayne@68
|
11752 ' module around while using its dictionary directly.\n'
|
|
jpayne@68
|
11753 '\n'
|
|
jpayne@68
|
11754 'Custom classes\n'
|
|
jpayne@68
|
11755 ' Custom class types are typically created by class definitions '
|
|
jpayne@68
|
11756 '(see\n'
|
|
jpayne@68
|
11757 ' section Class definitions). A class has a namespace implemented '
|
|
jpayne@68
|
11758 'by\n'
|
|
jpayne@68
|
11759 ' a dictionary object. Class attribute references are translated '
|
|
jpayne@68
|
11760 'to\n'
|
|
jpayne@68
|
11761 ' lookups in this dictionary, e.g., "C.x" is translated to\n'
|
|
jpayne@68
|
11762 ' "C.__dict__["x"]" (although there are a number of hooks which '
|
|
jpayne@68
|
11763 'allow\n'
|
|
jpayne@68
|
11764 ' for other means of locating attributes). When the attribute name '
|
|
jpayne@68
|
11765 'is\n'
|
|
jpayne@68
|
11766 ' not found there, the attribute search continues in the base\n'
|
|
jpayne@68
|
11767 ' classes. This search of the base classes uses the C3 method\n'
|
|
jpayne@68
|
11768 ' resolution order which behaves correctly even in the presence '
|
|
jpayne@68
|
11769 'of\n'
|
|
jpayne@68
|
11770 ' ‘diamond’ inheritance structures where there are multiple\n'
|
|
jpayne@68
|
11771 ' inheritance paths leading back to a common ancestor. Additional\n'
|
|
jpayne@68
|
11772 ' details on the C3 MRO used by Python can be found in the\n'
|
|
jpayne@68
|
11773 ' documentation accompanying the 2.3 release at\n'
|
|
jpayne@68
|
11774 ' https://www.python.org/download/releases/2.3/mro/.\n'
|
|
jpayne@68
|
11775 '\n'
|
|
jpayne@68
|
11776 ' When a class attribute reference (for class "C", say) would '
|
|
jpayne@68
|
11777 'yield a\n'
|
|
jpayne@68
|
11778 ' class method object, it is transformed into an instance method\n'
|
|
jpayne@68
|
11779 ' object whose "__self__" attribute is "C". When it would yield '
|
|
jpayne@68
|
11780 'a\n'
|
|
jpayne@68
|
11781 ' static method object, it is transformed into the object wrapped '
|
|
jpayne@68
|
11782 'by\n'
|
|
jpayne@68
|
11783 ' the static method object. See section Implementing Descriptors '
|
|
jpayne@68
|
11784 'for\n'
|
|
jpayne@68
|
11785 ' another way in which attributes retrieved from a class may '
|
|
jpayne@68
|
11786 'differ\n'
|
|
jpayne@68
|
11787 ' from those actually contained in its "__dict__".\n'
|
|
jpayne@68
|
11788 '\n'
|
|
jpayne@68
|
11789 ' Class attribute assignments update the class’s dictionary, '
|
|
jpayne@68
|
11790 'never\n'
|
|
jpayne@68
|
11791 ' the dictionary of a base class.\n'
|
|
jpayne@68
|
11792 '\n'
|
|
jpayne@68
|
11793 ' A class object can be called (see above) to yield a class '
|
|
jpayne@68
|
11794 'instance\n'
|
|
jpayne@68
|
11795 ' (see below).\n'
|
|
jpayne@68
|
11796 '\n'
|
|
jpayne@68
|
11797 ' Special attributes: "__name__" is the class name; "__module__" '
|
|
jpayne@68
|
11798 'is\n'
|
|
jpayne@68
|
11799 ' the module name in which the class was defined; "__dict__" is '
|
|
jpayne@68
|
11800 'the\n'
|
|
jpayne@68
|
11801 ' dictionary containing the class’s namespace; "__bases__" is a '
|
|
jpayne@68
|
11802 'tuple\n'
|
|
jpayne@68
|
11803 ' containing the base classes, in the order of their occurrence '
|
|
jpayne@68
|
11804 'in\n'
|
|
jpayne@68
|
11805 ' the base class list; "__doc__" is the class’s documentation '
|
|
jpayne@68
|
11806 'string,\n'
|
|
jpayne@68
|
11807 ' or "None" if undefined; "__annotations__" (optional) is a\n'
|
|
jpayne@68
|
11808 ' dictionary containing *variable annotations* collected during '
|
|
jpayne@68
|
11809 'class\n'
|
|
jpayne@68
|
11810 ' body execution.\n'
|
|
jpayne@68
|
11811 '\n'
|
|
jpayne@68
|
11812 'Class instances\n'
|
|
jpayne@68
|
11813 ' A class instance is created by calling a class object (see '
|
|
jpayne@68
|
11814 'above).\n'
|
|
jpayne@68
|
11815 ' A class instance has a namespace implemented as a dictionary '
|
|
jpayne@68
|
11816 'which\n'
|
|
jpayne@68
|
11817 ' is the first place in which attribute references are searched.\n'
|
|
jpayne@68
|
11818 ' When an attribute is not found there, and the instance’s class '
|
|
jpayne@68
|
11819 'has\n'
|
|
jpayne@68
|
11820 ' an attribute by that name, the search continues with the class\n'
|
|
jpayne@68
|
11821 ' attributes. If a class attribute is found that is a '
|
|
jpayne@68
|
11822 'user-defined\n'
|
|
jpayne@68
|
11823 ' function object, it is transformed into an instance method '
|
|
jpayne@68
|
11824 'object\n'
|
|
jpayne@68
|
11825 ' whose "__self__" attribute is the instance. Static method and\n'
|
|
jpayne@68
|
11826 ' class method objects are also transformed; see above under\n'
|
|
jpayne@68
|
11827 ' “Classes”. See section Implementing Descriptors for another way '
|
|
jpayne@68
|
11828 'in\n'
|
|
jpayne@68
|
11829 ' which attributes of a class retrieved via its instances may '
|
|
jpayne@68
|
11830 'differ\n'
|
|
jpayne@68
|
11831 ' from the objects actually stored in the class’s "__dict__". If '
|
|
jpayne@68
|
11832 'no\n'
|
|
jpayne@68
|
11833 ' class attribute is found, and the object’s class has a\n'
|
|
jpayne@68
|
11834 ' "__getattr__()" method, that is called to satisfy the lookup.\n'
|
|
jpayne@68
|
11835 '\n'
|
|
jpayne@68
|
11836 ' Attribute assignments and deletions update the instance’s\n'
|
|
jpayne@68
|
11837 ' dictionary, never a class’s dictionary. If the class has a\n'
|
|
jpayne@68
|
11838 ' "__setattr__()" or "__delattr__()" method, this is called '
|
|
jpayne@68
|
11839 'instead\n'
|
|
jpayne@68
|
11840 ' of updating the instance dictionary directly.\n'
|
|
jpayne@68
|
11841 '\n'
|
|
jpayne@68
|
11842 ' Class instances can pretend to be numbers, sequences, or '
|
|
jpayne@68
|
11843 'mappings\n'
|
|
jpayne@68
|
11844 ' if they have methods with certain special names. See section\n'
|
|
jpayne@68
|
11845 ' Special method names.\n'
|
|
jpayne@68
|
11846 '\n'
|
|
jpayne@68
|
11847 ' Special attributes: "__dict__" is the attribute dictionary;\n'
|
|
jpayne@68
|
11848 ' "__class__" is the instance’s class.\n'
|
|
jpayne@68
|
11849 '\n'
|
|
jpayne@68
|
11850 'I/O objects (also known as file objects)\n'
|
|
jpayne@68
|
11851 ' A *file object* represents an open file. Various shortcuts are\n'
|
|
jpayne@68
|
11852 ' available to create file objects: the "open()" built-in '
|
|
jpayne@68
|
11853 'function,\n'
|
|
jpayne@68
|
11854 ' and also "os.popen()", "os.fdopen()", and the "makefile()" '
|
|
jpayne@68
|
11855 'method\n'
|
|
jpayne@68
|
11856 ' of socket objects (and perhaps by other functions or methods\n'
|
|
jpayne@68
|
11857 ' provided by extension modules).\n'
|
|
jpayne@68
|
11858 '\n'
|
|
jpayne@68
|
11859 ' The objects "sys.stdin", "sys.stdout" and "sys.stderr" are\n'
|
|
jpayne@68
|
11860 ' initialized to file objects corresponding to the interpreter’s\n'
|
|
jpayne@68
|
11861 ' standard input, output and error streams; they are all open in '
|
|
jpayne@68
|
11862 'text\n'
|
|
jpayne@68
|
11863 ' mode and therefore follow the interface defined by the\n'
|
|
jpayne@68
|
11864 ' "io.TextIOBase" abstract class.\n'
|
|
jpayne@68
|
11865 '\n'
|
|
jpayne@68
|
11866 'Internal types\n'
|
|
jpayne@68
|
11867 ' A few types used internally by the interpreter are exposed to '
|
|
jpayne@68
|
11868 'the\n'
|
|
jpayne@68
|
11869 ' user. Their definitions may change with future versions of the\n'
|
|
jpayne@68
|
11870 ' interpreter, but they are mentioned here for completeness.\n'
|
|
jpayne@68
|
11871 '\n'
|
|
jpayne@68
|
11872 ' Code objects\n'
|
|
jpayne@68
|
11873 ' Code objects represent *byte-compiled* executable Python '
|
|
jpayne@68
|
11874 'code,\n'
|
|
jpayne@68
|
11875 ' or *bytecode*. The difference between a code object and a\n'
|
|
jpayne@68
|
11876 ' function object is that the function object contains an '
|
|
jpayne@68
|
11877 'explicit\n'
|
|
jpayne@68
|
11878 ' reference to the function’s globals (the module in which it '
|
|
jpayne@68
|
11879 'was\n'
|
|
jpayne@68
|
11880 ' defined), while a code object contains no context; also the\n'
|
|
jpayne@68
|
11881 ' default argument values are stored in the function object, '
|
|
jpayne@68
|
11882 'not\n'
|
|
jpayne@68
|
11883 ' in the code object (because they represent values calculated '
|
|
jpayne@68
|
11884 'at\n'
|
|
jpayne@68
|
11885 ' run-time). Unlike function objects, code objects are '
|
|
jpayne@68
|
11886 'immutable\n'
|
|
jpayne@68
|
11887 ' and contain no references (directly or indirectly) to '
|
|
jpayne@68
|
11888 'mutable\n'
|
|
jpayne@68
|
11889 ' objects.\n'
|
|
jpayne@68
|
11890 '\n'
|
|
jpayne@68
|
11891 ' Special read-only attributes: "co_name" gives the function '
|
|
jpayne@68
|
11892 'name;\n'
|
|
jpayne@68
|
11893 ' "co_argcount" is the total number of positional arguments\n'
|
|
jpayne@68
|
11894 ' (including positional-only arguments and arguments with '
|
|
jpayne@68
|
11895 'default\n'
|
|
jpayne@68
|
11896 ' values); "co_posonlyargcount" is the number of '
|
|
jpayne@68
|
11897 'positional-only\n'
|
|
jpayne@68
|
11898 ' arguments (including arguments with default values);\n'
|
|
jpayne@68
|
11899 ' "co_kwonlyargcount" is the number of keyword-only arguments\n'
|
|
jpayne@68
|
11900 ' (including arguments with default values); "co_nlocals" is '
|
|
jpayne@68
|
11901 'the\n'
|
|
jpayne@68
|
11902 ' number of local variables used by the function (including\n'
|
|
jpayne@68
|
11903 ' arguments); "co_varnames" is a tuple containing the names of '
|
|
jpayne@68
|
11904 'the\n'
|
|
jpayne@68
|
11905 ' local variables (starting with the argument names);\n'
|
|
jpayne@68
|
11906 ' "co_cellvars" is a tuple containing the names of local '
|
|
jpayne@68
|
11907 'variables\n'
|
|
jpayne@68
|
11908 ' that are referenced by nested functions; "co_freevars" is a\n'
|
|
jpayne@68
|
11909 ' tuple containing the names of free variables; "co_code" is a\n'
|
|
jpayne@68
|
11910 ' string representing the sequence of bytecode instructions;\n'
|
|
jpayne@68
|
11911 ' "co_consts" is a tuple containing the literals used by the\n'
|
|
jpayne@68
|
11912 ' bytecode; "co_names" is a tuple containing the names used by '
|
|
jpayne@68
|
11913 'the\n'
|
|
jpayne@68
|
11914 ' bytecode; "co_filename" is the filename from which the code '
|
|
jpayne@68
|
11915 'was\n'
|
|
jpayne@68
|
11916 ' compiled; "co_firstlineno" is the first line number of the\n'
|
|
jpayne@68
|
11917 ' function; "co_lnotab" is a string encoding the mapping from\n'
|
|
jpayne@68
|
11918 ' bytecode offsets to line numbers (for details see the source\n'
|
|
jpayne@68
|
11919 ' code of the interpreter); "co_stacksize" is the required '
|
|
jpayne@68
|
11920 'stack\n'
|
|
jpayne@68
|
11921 ' size (including local variables); "co_flags" is an integer\n'
|
|
jpayne@68
|
11922 ' encoding a number of flags for the interpreter.\n'
|
|
jpayne@68
|
11923 '\n'
|
|
jpayne@68
|
11924 ' The following flag bits are defined for "co_flags": bit '
|
|
jpayne@68
|
11925 '"0x04"\n'
|
|
jpayne@68
|
11926 ' is set if the function uses the "*arguments" syntax to accept '
|
|
jpayne@68
|
11927 'an\n'
|
|
jpayne@68
|
11928 ' arbitrary number of positional arguments; bit "0x08" is set '
|
|
jpayne@68
|
11929 'if\n'
|
|
jpayne@68
|
11930 ' the function uses the "**keywords" syntax to accept '
|
|
jpayne@68
|
11931 'arbitrary\n'
|
|
jpayne@68
|
11932 ' keyword arguments; bit "0x20" is set if the function is a\n'
|
|
jpayne@68
|
11933 ' generator.\n'
|
|
jpayne@68
|
11934 '\n'
|
|
jpayne@68
|
11935 ' Future feature declarations ("from __future__ import '
|
|
jpayne@68
|
11936 'division")\n'
|
|
jpayne@68
|
11937 ' also use bits in "co_flags" to indicate whether a code '
|
|
jpayne@68
|
11938 'object\n'
|
|
jpayne@68
|
11939 ' was compiled with a particular feature enabled: bit "0x2000" '
|
|
jpayne@68
|
11940 'is\n'
|
|
jpayne@68
|
11941 ' set if the function was compiled with future division '
|
|
jpayne@68
|
11942 'enabled;\n'
|
|
jpayne@68
|
11943 ' bits "0x10" and "0x1000" were used in earlier versions of\n'
|
|
jpayne@68
|
11944 ' Python.\n'
|
|
jpayne@68
|
11945 '\n'
|
|
jpayne@68
|
11946 ' Other bits in "co_flags" are reserved for internal use.\n'
|
|
jpayne@68
|
11947 '\n'
|
|
jpayne@68
|
11948 ' If a code object represents a function, the first item in\n'
|
|
jpayne@68
|
11949 ' "co_consts" is the documentation string of the function, or\n'
|
|
jpayne@68
|
11950 ' "None" if undefined.\n'
|
|
jpayne@68
|
11951 '\n'
|
|
jpayne@68
|
11952 ' Frame objects\n'
|
|
jpayne@68
|
11953 ' Frame objects represent execution frames. They may occur in\n'
|
|
jpayne@68
|
11954 ' traceback objects (see below), and are also passed to '
|
|
jpayne@68
|
11955 'registered\n'
|
|
jpayne@68
|
11956 ' trace functions.\n'
|
|
jpayne@68
|
11957 '\n'
|
|
jpayne@68
|
11958 ' Special read-only attributes: "f_back" is to the previous '
|
|
jpayne@68
|
11959 'stack\n'
|
|
jpayne@68
|
11960 ' frame (towards the caller), or "None" if this is the bottom\n'
|
|
jpayne@68
|
11961 ' stack frame; "f_code" is the code object being executed in '
|
|
jpayne@68
|
11962 'this\n'
|
|
jpayne@68
|
11963 ' frame; "f_locals" is the dictionary used to look up local\n'
|
|
jpayne@68
|
11964 ' variables; "f_globals" is used for global variables;\n'
|
|
jpayne@68
|
11965 ' "f_builtins" is used for built-in (intrinsic) names; '
|
|
jpayne@68
|
11966 '"f_lasti"\n'
|
|
jpayne@68
|
11967 ' gives the precise instruction (this is an index into the\n'
|
|
jpayne@68
|
11968 ' bytecode string of the code object).\n'
|
|
jpayne@68
|
11969 '\n'
|
|
jpayne@68
|
11970 ' Special writable attributes: "f_trace", if not "None", is a\n'
|
|
jpayne@68
|
11971 ' function called for various events during code execution '
|
|
jpayne@68
|
11972 '(this\n'
|
|
jpayne@68
|
11973 ' is used by the debugger). Normally an event is triggered for\n'
|
|
jpayne@68
|
11974 ' each new source line - this can be disabled by setting\n'
|
|
jpayne@68
|
11975 ' "f_trace_lines" to "False".\n'
|
|
jpayne@68
|
11976 '\n'
|
|
jpayne@68
|
11977 ' Implementations *may* allow per-opcode events to be requested '
|
|
jpayne@68
|
11978 'by\n'
|
|
jpayne@68
|
11979 ' setting "f_trace_opcodes" to "True". Note that this may lead '
|
|
jpayne@68
|
11980 'to\n'
|
|
jpayne@68
|
11981 ' undefined interpreter behaviour if exceptions raised by the\n'
|
|
jpayne@68
|
11982 ' trace function escape to the function being traced.\n'
|
|
jpayne@68
|
11983 '\n'
|
|
jpayne@68
|
11984 ' "f_lineno" is the current line number of the frame — writing '
|
|
jpayne@68
|
11985 'to\n'
|
|
jpayne@68
|
11986 ' this from within a trace function jumps to the given line '
|
|
jpayne@68
|
11987 '(only\n'
|
|
jpayne@68
|
11988 ' for the bottom-most frame). A debugger can implement a Jump\n'
|
|
jpayne@68
|
11989 ' command (aka Set Next Statement) by writing to f_lineno.\n'
|
|
jpayne@68
|
11990 '\n'
|
|
jpayne@68
|
11991 ' Frame objects support one method:\n'
|
|
jpayne@68
|
11992 '\n'
|
|
jpayne@68
|
11993 ' frame.clear()\n'
|
|
jpayne@68
|
11994 '\n'
|
|
jpayne@68
|
11995 ' This method clears all references to local variables held '
|
|
jpayne@68
|
11996 'by\n'
|
|
jpayne@68
|
11997 ' the frame. Also, if the frame belonged to a generator, '
|
|
jpayne@68
|
11998 'the\n'
|
|
jpayne@68
|
11999 ' generator is finalized. This helps break reference '
|
|
jpayne@68
|
12000 'cycles\n'
|
|
jpayne@68
|
12001 ' involving frame objects (for example when catching an\n'
|
|
jpayne@68
|
12002 ' exception and storing its traceback for later use).\n'
|
|
jpayne@68
|
12003 '\n'
|
|
jpayne@68
|
12004 ' "RuntimeError" is raised if the frame is currently '
|
|
jpayne@68
|
12005 'executing.\n'
|
|
jpayne@68
|
12006 '\n'
|
|
jpayne@68
|
12007 ' New in version 3.4.\n'
|
|
jpayne@68
|
12008 '\n'
|
|
jpayne@68
|
12009 ' Traceback objects\n'
|
|
jpayne@68
|
12010 ' Traceback objects represent a stack trace of an exception. '
|
|
jpayne@68
|
12011 'A\n'
|
|
jpayne@68
|
12012 ' traceback object is implicitly created when an exception '
|
|
jpayne@68
|
12013 'occurs,\n'
|
|
jpayne@68
|
12014 ' and may also be explicitly created by calling\n'
|
|
jpayne@68
|
12015 ' "types.TracebackType".\n'
|
|
jpayne@68
|
12016 '\n'
|
|
jpayne@68
|
12017 ' For implicitly created tracebacks, when the search for an\n'
|
|
jpayne@68
|
12018 ' exception handler unwinds the execution stack, at each '
|
|
jpayne@68
|
12019 'unwound\n'
|
|
jpayne@68
|
12020 ' level a traceback object is inserted in front of the current\n'
|
|
jpayne@68
|
12021 ' traceback. When an exception handler is entered, the stack\n'
|
|
jpayne@68
|
12022 ' trace is made available to the program. (See section The try\n'
|
|
jpayne@68
|
12023 ' statement.) It is accessible as the third item of the tuple\n'
|
|
jpayne@68
|
12024 ' returned by "sys.exc_info()", and as the "__traceback__"\n'
|
|
jpayne@68
|
12025 ' attribute of the caught exception.\n'
|
|
jpayne@68
|
12026 '\n'
|
|
jpayne@68
|
12027 ' When the program contains no suitable handler, the stack '
|
|
jpayne@68
|
12028 'trace\n'
|
|
jpayne@68
|
12029 ' is written (nicely formatted) to the standard error stream; '
|
|
jpayne@68
|
12030 'if\n'
|
|
jpayne@68
|
12031 ' the interpreter is interactive, it is also made available to '
|
|
jpayne@68
|
12032 'the\n'
|
|
jpayne@68
|
12033 ' user as "sys.last_traceback".\n'
|
|
jpayne@68
|
12034 '\n'
|
|
jpayne@68
|
12035 ' For explicitly created tracebacks, it is up to the creator '
|
|
jpayne@68
|
12036 'of\n'
|
|
jpayne@68
|
12037 ' the traceback to determine how the "tb_next" attributes '
|
|
jpayne@68
|
12038 'should\n'
|
|
jpayne@68
|
12039 ' be linked to form a full stack trace.\n'
|
|
jpayne@68
|
12040 '\n'
|
|
jpayne@68
|
12041 ' Special read-only attributes: "tb_frame" points to the '
|
|
jpayne@68
|
12042 'execution\n'
|
|
jpayne@68
|
12043 ' frame of the current level; "tb_lineno" gives the line '
|
|
jpayne@68
|
12044 'number\n'
|
|
jpayne@68
|
12045 ' where the exception occurred; "tb_lasti" indicates the '
|
|
jpayne@68
|
12046 'precise\n'
|
|
jpayne@68
|
12047 ' instruction. The line number and last instruction in the\n'
|
|
jpayne@68
|
12048 ' traceback may differ from the line number of its frame object '
|
|
jpayne@68
|
12049 'if\n'
|
|
jpayne@68
|
12050 ' the exception occurred in a "try" statement with no matching\n'
|
|
jpayne@68
|
12051 ' except clause or with a finally clause.\n'
|
|
jpayne@68
|
12052 '\n'
|
|
jpayne@68
|
12053 ' Special writable attribute: "tb_next" is the next level in '
|
|
jpayne@68
|
12054 'the\n'
|
|
jpayne@68
|
12055 ' stack trace (towards the frame where the exception occurred), '
|
|
jpayne@68
|
12056 'or\n'
|
|
jpayne@68
|
12057 ' "None" if there is no next level.\n'
|
|
jpayne@68
|
12058 '\n'
|
|
jpayne@68
|
12059 ' Changed in version 3.7: Traceback objects can now be '
|
|
jpayne@68
|
12060 'explicitly\n'
|
|
jpayne@68
|
12061 ' instantiated from Python code, and the "tb_next" attribute '
|
|
jpayne@68
|
12062 'of\n'
|
|
jpayne@68
|
12063 ' existing instances can be updated.\n'
|
|
jpayne@68
|
12064 '\n'
|
|
jpayne@68
|
12065 ' Slice objects\n'
|
|
jpayne@68
|
12066 ' Slice objects are used to represent slices for '
|
|
jpayne@68
|
12067 '"__getitem__()"\n'
|
|
jpayne@68
|
12068 ' methods. They are also created by the built-in "slice()"\n'
|
|
jpayne@68
|
12069 ' function.\n'
|
|
jpayne@68
|
12070 '\n'
|
|
jpayne@68
|
12071 ' Special read-only attributes: "start" is the lower bound; '
|
|
jpayne@68
|
12072 '"stop"\n'
|
|
jpayne@68
|
12073 ' is the upper bound; "step" is the step value; each is "None" '
|
|
jpayne@68
|
12074 'if\n'
|
|
jpayne@68
|
12075 ' omitted. These attributes can have any type.\n'
|
|
jpayne@68
|
12076 '\n'
|
|
jpayne@68
|
12077 ' Slice objects support one method:\n'
|
|
jpayne@68
|
12078 '\n'
|
|
jpayne@68
|
12079 ' slice.indices(self, length)\n'
|
|
jpayne@68
|
12080 '\n'
|
|
jpayne@68
|
12081 ' This method takes a single integer argument *length* and\n'
|
|
jpayne@68
|
12082 ' computes information about the slice that the slice '
|
|
jpayne@68
|
12083 'object\n'
|
|
jpayne@68
|
12084 ' would describe if applied to a sequence of *length* '
|
|
jpayne@68
|
12085 'items.\n'
|
|
jpayne@68
|
12086 ' It returns a tuple of three integers; respectively these '
|
|
jpayne@68
|
12087 'are\n'
|
|
jpayne@68
|
12088 ' the *start* and *stop* indices and the *step* or stride\n'
|
|
jpayne@68
|
12089 ' length of the slice. Missing or out-of-bounds indices are\n'
|
|
jpayne@68
|
12090 ' handled in a manner consistent with regular slices.\n'
|
|
jpayne@68
|
12091 '\n'
|
|
jpayne@68
|
12092 ' Static method objects\n'
|
|
jpayne@68
|
12093 ' Static method objects provide a way of defeating the\n'
|
|
jpayne@68
|
12094 ' transformation of function objects to method objects '
|
|
jpayne@68
|
12095 'described\n'
|
|
jpayne@68
|
12096 ' above. A static method object is a wrapper around any other\n'
|
|
jpayne@68
|
12097 ' object, usually a user-defined method object. When a static\n'
|
|
jpayne@68
|
12098 ' method object is retrieved from a class or a class instance, '
|
|
jpayne@68
|
12099 'the\n'
|
|
jpayne@68
|
12100 ' object actually returned is the wrapped object, which is not\n'
|
|
jpayne@68
|
12101 ' subject to any further transformation. Static method objects '
|
|
jpayne@68
|
12102 'are\n'
|
|
jpayne@68
|
12103 ' not themselves callable, although the objects they wrap '
|
|
jpayne@68
|
12104 'usually\n'
|
|
jpayne@68
|
12105 ' are. Static method objects are created by the built-in\n'
|
|
jpayne@68
|
12106 ' "staticmethod()" constructor.\n'
|
|
jpayne@68
|
12107 '\n'
|
|
jpayne@68
|
12108 ' Class method objects\n'
|
|
jpayne@68
|
12109 ' A class method object, like a static method object, is a '
|
|
jpayne@68
|
12110 'wrapper\n'
|
|
jpayne@68
|
12111 ' around another object that alters the way in which that '
|
|
jpayne@68
|
12112 'object\n'
|
|
jpayne@68
|
12113 ' is retrieved from classes and class instances. The behaviour '
|
|
jpayne@68
|
12114 'of\n'
|
|
jpayne@68
|
12115 ' class method objects upon such retrieval is described above,\n'
|
|
jpayne@68
|
12116 ' under “User-defined methods”. Class method objects are '
|
|
jpayne@68
|
12117 'created\n'
|
|
jpayne@68
|
12118 ' by the built-in "classmethod()" constructor.\n',
|
|
jpayne@68
|
12119 'typesfunctions': 'Functions\n'
|
|
jpayne@68
|
12120 '*********\n'
|
|
jpayne@68
|
12121 '\n'
|
|
jpayne@68
|
12122 'Function objects are created by function definitions. The '
|
|
jpayne@68
|
12123 'only\n'
|
|
jpayne@68
|
12124 'operation on a function object is to call it: '
|
|
jpayne@68
|
12125 '"func(argument-list)".\n'
|
|
jpayne@68
|
12126 '\n'
|
|
jpayne@68
|
12127 'There are really two flavors of function objects: built-in '
|
|
jpayne@68
|
12128 'functions\n'
|
|
jpayne@68
|
12129 'and user-defined functions. Both support the same '
|
|
jpayne@68
|
12130 'operation (to call\n'
|
|
jpayne@68
|
12131 'the function), but the implementation is different, hence '
|
|
jpayne@68
|
12132 'the\n'
|
|
jpayne@68
|
12133 'different object types.\n'
|
|
jpayne@68
|
12134 '\n'
|
|
jpayne@68
|
12135 'See Function definitions for more information.\n',
|
|
jpayne@68
|
12136 'typesmapping': 'Mapping Types — "dict"\n'
|
|
jpayne@68
|
12137 '**********************\n'
|
|
jpayne@68
|
12138 '\n'
|
|
jpayne@68
|
12139 'A *mapping* object maps *hashable* values to arbitrary '
|
|
jpayne@68
|
12140 'objects.\n'
|
|
jpayne@68
|
12141 'Mappings are mutable objects. There is currently only one '
|
|
jpayne@68
|
12142 'standard\n'
|
|
jpayne@68
|
12143 'mapping type, the *dictionary*. (For other containers see '
|
|
jpayne@68
|
12144 'the built-\n'
|
|
jpayne@68
|
12145 'in "list", "set", and "tuple" classes, and the "collections" '
|
|
jpayne@68
|
12146 'module.)\n'
|
|
jpayne@68
|
12147 '\n'
|
|
jpayne@68
|
12148 'A dictionary’s keys are *almost* arbitrary values. Values '
|
|
jpayne@68
|
12149 'that are\n'
|
|
jpayne@68
|
12150 'not *hashable*, that is, values containing lists, '
|
|
jpayne@68
|
12151 'dictionaries or\n'
|
|
jpayne@68
|
12152 'other mutable types (that are compared by value rather than '
|
|
jpayne@68
|
12153 'by object\n'
|
|
jpayne@68
|
12154 'identity) may not be used as keys. Numeric types used for '
|
|
jpayne@68
|
12155 'keys obey\n'
|
|
jpayne@68
|
12156 'the normal rules for numeric comparison: if two numbers '
|
|
jpayne@68
|
12157 'compare equal\n'
|
|
jpayne@68
|
12158 '(such as "1" and "1.0") then they can be used '
|
|
jpayne@68
|
12159 'interchangeably to index\n'
|
|
jpayne@68
|
12160 'the same dictionary entry. (Note however, that since '
|
|
jpayne@68
|
12161 'computers store\n'
|
|
jpayne@68
|
12162 'floating-point numbers as approximations it is usually '
|
|
jpayne@68
|
12163 'unwise to use\n'
|
|
jpayne@68
|
12164 'them as dictionary keys.)\n'
|
|
jpayne@68
|
12165 '\n'
|
|
jpayne@68
|
12166 'Dictionaries can be created by placing a comma-separated '
|
|
jpayne@68
|
12167 'list of "key:\n'
|
|
jpayne@68
|
12168 'value" pairs within braces, for example: "{\'jack\': 4098, '
|
|
jpayne@68
|
12169 "'sjoerd':\n"
|
|
jpayne@68
|
12170 '4127}" or "{4098: \'jack\', 4127: \'sjoerd\'}", or by the '
|
|
jpayne@68
|
12171 '"dict"\n'
|
|
jpayne@68
|
12172 'constructor.\n'
|
|
jpayne@68
|
12173 '\n'
|
|
jpayne@68
|
12174 'class dict(**kwarg)\n'
|
|
jpayne@68
|
12175 'class dict(mapping, **kwarg)\n'
|
|
jpayne@68
|
12176 'class dict(iterable, **kwarg)\n'
|
|
jpayne@68
|
12177 '\n'
|
|
jpayne@68
|
12178 ' Return a new dictionary initialized from an optional '
|
|
jpayne@68
|
12179 'positional\n'
|
|
jpayne@68
|
12180 ' argument and a possibly empty set of keyword arguments.\n'
|
|
jpayne@68
|
12181 '\n'
|
|
jpayne@68
|
12182 ' If no positional argument is given, an empty dictionary '
|
|
jpayne@68
|
12183 'is created.\n'
|
|
jpayne@68
|
12184 ' If a positional argument is given and it is a mapping '
|
|
jpayne@68
|
12185 'object, a\n'
|
|
jpayne@68
|
12186 ' dictionary is created with the same key-value pairs as '
|
|
jpayne@68
|
12187 'the mapping\n'
|
|
jpayne@68
|
12188 ' object. Otherwise, the positional argument must be an '
|
|
jpayne@68
|
12189 '*iterable*\n'
|
|
jpayne@68
|
12190 ' object. Each item in the iterable must itself be an '
|
|
jpayne@68
|
12191 'iterable with\n'
|
|
jpayne@68
|
12192 ' exactly two objects. The first object of each item '
|
|
jpayne@68
|
12193 'becomes a key\n'
|
|
jpayne@68
|
12194 ' in the new dictionary, and the second object the '
|
|
jpayne@68
|
12195 'corresponding\n'
|
|
jpayne@68
|
12196 ' value. If a key occurs more than once, the last value '
|
|
jpayne@68
|
12197 'for that key\n'
|
|
jpayne@68
|
12198 ' becomes the corresponding value in the new dictionary.\n'
|
|
jpayne@68
|
12199 '\n'
|
|
jpayne@68
|
12200 ' If keyword arguments are given, the keyword arguments and '
|
|
jpayne@68
|
12201 'their\n'
|
|
jpayne@68
|
12202 ' values are added to the dictionary created from the '
|
|
jpayne@68
|
12203 'positional\n'
|
|
jpayne@68
|
12204 ' argument. If a key being added is already present, the '
|
|
jpayne@68
|
12205 'value from\n'
|
|
jpayne@68
|
12206 ' the keyword argument replaces the value from the '
|
|
jpayne@68
|
12207 'positional\n'
|
|
jpayne@68
|
12208 ' argument.\n'
|
|
jpayne@68
|
12209 '\n'
|
|
jpayne@68
|
12210 ' To illustrate, the following examples all return a '
|
|
jpayne@68
|
12211 'dictionary equal\n'
|
|
jpayne@68
|
12212 ' to "{"one": 1, "two": 2, "three": 3}":\n'
|
|
jpayne@68
|
12213 '\n'
|
|
jpayne@68
|
12214 ' >>> a = dict(one=1, two=2, three=3)\n'
|
|
jpayne@68
|
12215 " >>> b = {'one': 1, 'two': 2, 'three': 3}\n"
|
|
jpayne@68
|
12216 " >>> c = dict(zip(['one', 'two', 'three'], [1, 2, 3]))\n"
|
|
jpayne@68
|
12217 " >>> d = dict([('two', 2), ('one', 1), ('three', 3)])\n"
|
|
jpayne@68
|
12218 " >>> e = dict({'three': 3, 'one': 1, 'two': 2})\n"
|
|
jpayne@68
|
12219 ' >>> a == b == c == d == e\n'
|
|
jpayne@68
|
12220 ' True\n'
|
|
jpayne@68
|
12221 '\n'
|
|
jpayne@68
|
12222 ' Providing keyword arguments as in the first example only '
|
|
jpayne@68
|
12223 'works for\n'
|
|
jpayne@68
|
12224 ' keys that are valid Python identifiers. Otherwise, any '
|
|
jpayne@68
|
12225 'valid keys\n'
|
|
jpayne@68
|
12226 ' can be used.\n'
|
|
jpayne@68
|
12227 '\n'
|
|
jpayne@68
|
12228 ' These are the operations that dictionaries support (and '
|
|
jpayne@68
|
12229 'therefore,\n'
|
|
jpayne@68
|
12230 ' custom mapping types should support too):\n'
|
|
jpayne@68
|
12231 '\n'
|
|
jpayne@68
|
12232 ' list(d)\n'
|
|
jpayne@68
|
12233 '\n'
|
|
jpayne@68
|
12234 ' Return a list of all the keys used in the dictionary '
|
|
jpayne@68
|
12235 '*d*.\n'
|
|
jpayne@68
|
12236 '\n'
|
|
jpayne@68
|
12237 ' len(d)\n'
|
|
jpayne@68
|
12238 '\n'
|
|
jpayne@68
|
12239 ' Return the number of items in the dictionary *d*.\n'
|
|
jpayne@68
|
12240 '\n'
|
|
jpayne@68
|
12241 ' d[key]\n'
|
|
jpayne@68
|
12242 '\n'
|
|
jpayne@68
|
12243 ' Return the item of *d* with key *key*. Raises a '
|
|
jpayne@68
|
12244 '"KeyError" if\n'
|
|
jpayne@68
|
12245 ' *key* is not in the map.\n'
|
|
jpayne@68
|
12246 '\n'
|
|
jpayne@68
|
12247 ' If a subclass of dict defines a method "__missing__()" '
|
|
jpayne@68
|
12248 'and *key*\n'
|
|
jpayne@68
|
12249 ' is not present, the "d[key]" operation calls that '
|
|
jpayne@68
|
12250 'method with\n'
|
|
jpayne@68
|
12251 ' the key *key* as argument. The "d[key]" operation '
|
|
jpayne@68
|
12252 'then returns\n'
|
|
jpayne@68
|
12253 ' or raises whatever is returned or raised by the\n'
|
|
jpayne@68
|
12254 ' "__missing__(key)" call. No other operations or '
|
|
jpayne@68
|
12255 'methods invoke\n'
|
|
jpayne@68
|
12256 ' "__missing__()". If "__missing__()" is not defined, '
|
|
jpayne@68
|
12257 '"KeyError"\n'
|
|
jpayne@68
|
12258 ' is raised. "__missing__()" must be a method; it cannot '
|
|
jpayne@68
|
12259 'be an\n'
|
|
jpayne@68
|
12260 ' instance variable:\n'
|
|
jpayne@68
|
12261 '\n'
|
|
jpayne@68
|
12262 ' >>> class Counter(dict):\n'
|
|
jpayne@68
|
12263 ' ... def __missing__(self, key):\n'
|
|
jpayne@68
|
12264 ' ... return 0\n'
|
|
jpayne@68
|
12265 ' >>> c = Counter()\n'
|
|
jpayne@68
|
12266 " >>> c['red']\n"
|
|
jpayne@68
|
12267 ' 0\n'
|
|
jpayne@68
|
12268 " >>> c['red'] += 1\n"
|
|
jpayne@68
|
12269 " >>> c['red']\n"
|
|
jpayne@68
|
12270 ' 1\n'
|
|
jpayne@68
|
12271 '\n'
|
|
jpayne@68
|
12272 ' The example above shows part of the implementation of\n'
|
|
jpayne@68
|
12273 ' "collections.Counter". A different "__missing__" '
|
|
jpayne@68
|
12274 'method is used\n'
|
|
jpayne@68
|
12275 ' by "collections.defaultdict".\n'
|
|
jpayne@68
|
12276 '\n'
|
|
jpayne@68
|
12277 ' d[key] = value\n'
|
|
jpayne@68
|
12278 '\n'
|
|
jpayne@68
|
12279 ' Set "d[key]" to *value*.\n'
|
|
jpayne@68
|
12280 '\n'
|
|
jpayne@68
|
12281 ' del d[key]\n'
|
|
jpayne@68
|
12282 '\n'
|
|
jpayne@68
|
12283 ' Remove "d[key]" from *d*. Raises a "KeyError" if '
|
|
jpayne@68
|
12284 '*key* is not\n'
|
|
jpayne@68
|
12285 ' in the map.\n'
|
|
jpayne@68
|
12286 '\n'
|
|
jpayne@68
|
12287 ' key in d\n'
|
|
jpayne@68
|
12288 '\n'
|
|
jpayne@68
|
12289 ' Return "True" if *d* has a key *key*, else "False".\n'
|
|
jpayne@68
|
12290 '\n'
|
|
jpayne@68
|
12291 ' key not in d\n'
|
|
jpayne@68
|
12292 '\n'
|
|
jpayne@68
|
12293 ' Equivalent to "not key in d".\n'
|
|
jpayne@68
|
12294 '\n'
|
|
jpayne@68
|
12295 ' iter(d)\n'
|
|
jpayne@68
|
12296 '\n'
|
|
jpayne@68
|
12297 ' Return an iterator over the keys of the dictionary. '
|
|
jpayne@68
|
12298 'This is a\n'
|
|
jpayne@68
|
12299 ' shortcut for "iter(d.keys())".\n'
|
|
jpayne@68
|
12300 '\n'
|
|
jpayne@68
|
12301 ' clear()\n'
|
|
jpayne@68
|
12302 '\n'
|
|
jpayne@68
|
12303 ' Remove all items from the dictionary.\n'
|
|
jpayne@68
|
12304 '\n'
|
|
jpayne@68
|
12305 ' copy()\n'
|
|
jpayne@68
|
12306 '\n'
|
|
jpayne@68
|
12307 ' Return a shallow copy of the dictionary.\n'
|
|
jpayne@68
|
12308 '\n'
|
|
jpayne@68
|
12309 ' classmethod fromkeys(iterable[, value])\n'
|
|
jpayne@68
|
12310 '\n'
|
|
jpayne@68
|
12311 ' Create a new dictionary with keys from *iterable* and '
|
|
jpayne@68
|
12312 'values set\n'
|
|
jpayne@68
|
12313 ' to *value*.\n'
|
|
jpayne@68
|
12314 '\n'
|
|
jpayne@68
|
12315 ' "fromkeys()" is a class method that returns a new '
|
|
jpayne@68
|
12316 'dictionary.\n'
|
|
jpayne@68
|
12317 ' *value* defaults to "None". All of the values refer '
|
|
jpayne@68
|
12318 'to just a\n'
|
|
jpayne@68
|
12319 ' single instance, so it generally doesn’t make sense '
|
|
jpayne@68
|
12320 'for *value*\n'
|
|
jpayne@68
|
12321 ' to be a mutable object such as an empty list. To get '
|
|
jpayne@68
|
12322 'distinct\n'
|
|
jpayne@68
|
12323 ' values, use a dict comprehension instead.\n'
|
|
jpayne@68
|
12324 '\n'
|
|
jpayne@68
|
12325 ' get(key[, default])\n'
|
|
jpayne@68
|
12326 '\n'
|
|
jpayne@68
|
12327 ' Return the value for *key* if *key* is in the '
|
|
jpayne@68
|
12328 'dictionary, else\n'
|
|
jpayne@68
|
12329 ' *default*. If *default* is not given, it defaults to '
|
|
jpayne@68
|
12330 '"None", so\n'
|
|
jpayne@68
|
12331 ' that this method never raises a "KeyError".\n'
|
|
jpayne@68
|
12332 '\n'
|
|
jpayne@68
|
12333 ' items()\n'
|
|
jpayne@68
|
12334 '\n'
|
|
jpayne@68
|
12335 ' Return a new view of the dictionary’s items ("(key, '
|
|
jpayne@68
|
12336 'value)"\n'
|
|
jpayne@68
|
12337 ' pairs). See the documentation of view objects.\n'
|
|
jpayne@68
|
12338 '\n'
|
|
jpayne@68
|
12339 ' keys()\n'
|
|
jpayne@68
|
12340 '\n'
|
|
jpayne@68
|
12341 ' Return a new view of the dictionary’s keys. See the\n'
|
|
jpayne@68
|
12342 ' documentation of view objects.\n'
|
|
jpayne@68
|
12343 '\n'
|
|
jpayne@68
|
12344 ' pop(key[, default])\n'
|
|
jpayne@68
|
12345 '\n'
|
|
jpayne@68
|
12346 ' If *key* is in the dictionary, remove it and return '
|
|
jpayne@68
|
12347 'its value,\n'
|
|
jpayne@68
|
12348 ' else return *default*. If *default* is not given and '
|
|
jpayne@68
|
12349 '*key* is\n'
|
|
jpayne@68
|
12350 ' not in the dictionary, a "KeyError" is raised.\n'
|
|
jpayne@68
|
12351 '\n'
|
|
jpayne@68
|
12352 ' popitem()\n'
|
|
jpayne@68
|
12353 '\n'
|
|
jpayne@68
|
12354 ' Remove and return a "(key, value)" pair from the '
|
|
jpayne@68
|
12355 'dictionary.\n'
|
|
jpayne@68
|
12356 ' Pairs are returned in LIFO (last-in, first-out) '
|
|
jpayne@68
|
12357 'order.\n'
|
|
jpayne@68
|
12358 '\n'
|
|
jpayne@68
|
12359 ' "popitem()" is useful to destructively iterate over a\n'
|
|
jpayne@68
|
12360 ' dictionary, as often used in set algorithms. If the '
|
|
jpayne@68
|
12361 'dictionary\n'
|
|
jpayne@68
|
12362 ' is empty, calling "popitem()" raises a "KeyError".\n'
|
|
jpayne@68
|
12363 '\n'
|
|
jpayne@68
|
12364 ' Changed in version 3.7: LIFO order is now guaranteed. '
|
|
jpayne@68
|
12365 'In prior\n'
|
|
jpayne@68
|
12366 ' versions, "popitem()" would return an arbitrary '
|
|
jpayne@68
|
12367 'key/value pair.\n'
|
|
jpayne@68
|
12368 '\n'
|
|
jpayne@68
|
12369 ' reversed(d)\n'
|
|
jpayne@68
|
12370 '\n'
|
|
jpayne@68
|
12371 ' Return a reverse iterator over the keys of the '
|
|
jpayne@68
|
12372 'dictionary. This\n'
|
|
jpayne@68
|
12373 ' is a shortcut for "reversed(d.keys())".\n'
|
|
jpayne@68
|
12374 '\n'
|
|
jpayne@68
|
12375 ' setdefault(key[, default])\n'
|
|
jpayne@68
|
12376 '\n'
|
|
jpayne@68
|
12377 ' If *key* is in the dictionary, return its value. If '
|
|
jpayne@68
|
12378 'not, insert\n'
|
|
jpayne@68
|
12379 ' *key* with a value of *default* and return *default*. '
|
|
jpayne@68
|
12380 '*default*\n'
|
|
jpayne@68
|
12381 ' defaults to "None".\n'
|
|
jpayne@68
|
12382 '\n'
|
|
jpayne@68
|
12383 ' update([other])\n'
|
|
jpayne@68
|
12384 '\n'
|
|
jpayne@68
|
12385 ' Update the dictionary with the key/value pairs from '
|
|
jpayne@68
|
12386 '*other*,\n'
|
|
jpayne@68
|
12387 ' overwriting existing keys. Return "None".\n'
|
|
jpayne@68
|
12388 '\n'
|
|
jpayne@68
|
12389 ' "update()" accepts either another dictionary object or '
|
|
jpayne@68
|
12390 'an\n'
|
|
jpayne@68
|
12391 ' iterable of key/value pairs (as tuples or other '
|
|
jpayne@68
|
12392 'iterables of\n'
|
|
jpayne@68
|
12393 ' length two). If keyword arguments are specified, the '
|
|
jpayne@68
|
12394 'dictionary\n'
|
|
jpayne@68
|
12395 ' is then updated with those key/value pairs: '
|
|
jpayne@68
|
12396 '"d.update(red=1,\n'
|
|
jpayne@68
|
12397 ' blue=2)".\n'
|
|
jpayne@68
|
12398 '\n'
|
|
jpayne@68
|
12399 ' values()\n'
|
|
jpayne@68
|
12400 '\n'
|
|
jpayne@68
|
12401 ' Return a new view of the dictionary’s values. See '
|
|
jpayne@68
|
12402 'the\n'
|
|
jpayne@68
|
12403 ' documentation of view objects.\n'
|
|
jpayne@68
|
12404 '\n'
|
|
jpayne@68
|
12405 ' An equality comparison between one "dict.values()" '
|
|
jpayne@68
|
12406 'view and\n'
|
|
jpayne@68
|
12407 ' another will always return "False". This also applies '
|
|
jpayne@68
|
12408 'when\n'
|
|
jpayne@68
|
12409 ' comparing "dict.values()" to itself:\n'
|
|
jpayne@68
|
12410 '\n'
|
|
jpayne@68
|
12411 " >>> d = {'a': 1}\n"
|
|
jpayne@68
|
12412 ' >>> d.values() == d.values()\n'
|
|
jpayne@68
|
12413 ' False\n'
|
|
jpayne@68
|
12414 '\n'
|
|
jpayne@68
|
12415 ' Dictionaries compare equal if and only if they have the '
|
|
jpayne@68
|
12416 'same "(key,\n'
|
|
jpayne@68
|
12417 ' value)" pairs (regardless of ordering). Order comparisons '
|
|
jpayne@68
|
12418 '(‘<’,\n'
|
|
jpayne@68
|
12419 ' ‘<=’, ‘>=’, ‘>’) raise "TypeError".\n'
|
|
jpayne@68
|
12420 '\n'
|
|
jpayne@68
|
12421 ' Dictionaries preserve insertion order. Note that '
|
|
jpayne@68
|
12422 'updating a key\n'
|
|
jpayne@68
|
12423 ' does not affect the order. Keys added after deletion are '
|
|
jpayne@68
|
12424 'inserted\n'
|
|
jpayne@68
|
12425 ' at the end.\n'
|
|
jpayne@68
|
12426 '\n'
|
|
jpayne@68
|
12427 ' >>> d = {"one": 1, "two": 2, "three": 3, "four": 4}\n'
|
|
jpayne@68
|
12428 ' >>> d\n'
|
|
jpayne@68
|
12429 " {'one': 1, 'two': 2, 'three': 3, 'four': 4}\n"
|
|
jpayne@68
|
12430 ' >>> list(d)\n'
|
|
jpayne@68
|
12431 " ['one', 'two', 'three', 'four']\n"
|
|
jpayne@68
|
12432 ' >>> list(d.values())\n'
|
|
jpayne@68
|
12433 ' [1, 2, 3, 4]\n'
|
|
jpayne@68
|
12434 ' >>> d["one"] = 42\n'
|
|
jpayne@68
|
12435 ' >>> d\n'
|
|
jpayne@68
|
12436 " {'one': 42, 'two': 2, 'three': 3, 'four': 4}\n"
|
|
jpayne@68
|
12437 ' >>> del d["two"]\n'
|
|
jpayne@68
|
12438 ' >>> d["two"] = None\n'
|
|
jpayne@68
|
12439 ' >>> d\n'
|
|
jpayne@68
|
12440 " {'one': 42, 'three': 3, 'four': 4, 'two': None}\n"
|
|
jpayne@68
|
12441 '\n'
|
|
jpayne@68
|
12442 ' Changed in version 3.7: Dictionary order is guaranteed to '
|
|
jpayne@68
|
12443 'be\n'
|
|
jpayne@68
|
12444 ' insertion order. This behavior was an implementation '
|
|
jpayne@68
|
12445 'detail of\n'
|
|
jpayne@68
|
12446 ' CPython from 3.6.\n'
|
|
jpayne@68
|
12447 '\n'
|
|
jpayne@68
|
12448 ' Dictionaries and dictionary views are reversible.\n'
|
|
jpayne@68
|
12449 '\n'
|
|
jpayne@68
|
12450 ' >>> d = {"one": 1, "two": 2, "three": 3, "four": 4}\n'
|
|
jpayne@68
|
12451 ' >>> d\n'
|
|
jpayne@68
|
12452 " {'one': 1, 'two': 2, 'three': 3, 'four': 4}\n"
|
|
jpayne@68
|
12453 ' >>> list(reversed(d))\n'
|
|
jpayne@68
|
12454 " ['four', 'three', 'two', 'one']\n"
|
|
jpayne@68
|
12455 ' >>> list(reversed(d.values()))\n'
|
|
jpayne@68
|
12456 ' [4, 3, 2, 1]\n'
|
|
jpayne@68
|
12457 ' >>> list(reversed(d.items()))\n'
|
|
jpayne@68
|
12458 " [('four', 4), ('three', 3), ('two', 2), ('one', 1)]\n"
|
|
jpayne@68
|
12459 '\n'
|
|
jpayne@68
|
12460 ' Changed in version 3.8: Dictionaries are now reversible.\n'
|
|
jpayne@68
|
12461 '\n'
|
|
jpayne@68
|
12462 'See also: "types.MappingProxyType" can be used to create a '
|
|
jpayne@68
|
12463 'read-only\n'
|
|
jpayne@68
|
12464 ' view of a "dict".\n'
|
|
jpayne@68
|
12465 '\n'
|
|
jpayne@68
|
12466 '\n'
|
|
jpayne@68
|
12467 'Dictionary view objects\n'
|
|
jpayne@68
|
12468 '=======================\n'
|
|
jpayne@68
|
12469 '\n'
|
|
jpayne@68
|
12470 'The objects returned by "dict.keys()", "dict.values()" and\n'
|
|
jpayne@68
|
12471 '"dict.items()" are *view objects*. They provide a dynamic '
|
|
jpayne@68
|
12472 'view on the\n'
|
|
jpayne@68
|
12473 'dictionary’s entries, which means that when the dictionary '
|
|
jpayne@68
|
12474 'changes,\n'
|
|
jpayne@68
|
12475 'the view reflects these changes.\n'
|
|
jpayne@68
|
12476 '\n'
|
|
jpayne@68
|
12477 'Dictionary views can be iterated over to yield their '
|
|
jpayne@68
|
12478 'respective data,\n'
|
|
jpayne@68
|
12479 'and support membership tests:\n'
|
|
jpayne@68
|
12480 '\n'
|
|
jpayne@68
|
12481 'len(dictview)\n'
|
|
jpayne@68
|
12482 '\n'
|
|
jpayne@68
|
12483 ' Return the number of entries in the dictionary.\n'
|
|
jpayne@68
|
12484 '\n'
|
|
jpayne@68
|
12485 'iter(dictview)\n'
|
|
jpayne@68
|
12486 '\n'
|
|
jpayne@68
|
12487 ' Return an iterator over the keys, values or items '
|
|
jpayne@68
|
12488 '(represented as\n'
|
|
jpayne@68
|
12489 ' tuples of "(key, value)") in the dictionary.\n'
|
|
jpayne@68
|
12490 '\n'
|
|
jpayne@68
|
12491 ' Keys and values are iterated over in insertion order. '
|
|
jpayne@68
|
12492 'This allows\n'
|
|
jpayne@68
|
12493 ' the creation of "(value, key)" pairs using "zip()": '
|
|
jpayne@68
|
12494 '"pairs =\n'
|
|
jpayne@68
|
12495 ' zip(d.values(), d.keys())". Another way to create the '
|
|
jpayne@68
|
12496 'same list is\n'
|
|
jpayne@68
|
12497 ' "pairs = [(v, k) for (k, v) in d.items()]".\n'
|
|
jpayne@68
|
12498 '\n'
|
|
jpayne@68
|
12499 ' Iterating views while adding or deleting entries in the '
|
|
jpayne@68
|
12500 'dictionary\n'
|
|
jpayne@68
|
12501 ' may raise a "RuntimeError" or fail to iterate over all '
|
|
jpayne@68
|
12502 'entries.\n'
|
|
jpayne@68
|
12503 '\n'
|
|
jpayne@68
|
12504 ' Changed in version 3.7: Dictionary order is guaranteed to '
|
|
jpayne@68
|
12505 'be\n'
|
|
jpayne@68
|
12506 ' insertion order.\n'
|
|
jpayne@68
|
12507 '\n'
|
|
jpayne@68
|
12508 'x in dictview\n'
|
|
jpayne@68
|
12509 '\n'
|
|
jpayne@68
|
12510 ' Return "True" if *x* is in the underlying dictionary’s '
|
|
jpayne@68
|
12511 'keys, values\n'
|
|
jpayne@68
|
12512 ' or items (in the latter case, *x* should be a "(key, '
|
|
jpayne@68
|
12513 'value)"\n'
|
|
jpayne@68
|
12514 ' tuple).\n'
|
|
jpayne@68
|
12515 '\n'
|
|
jpayne@68
|
12516 'reversed(dictview)\n'
|
|
jpayne@68
|
12517 '\n'
|
|
jpayne@68
|
12518 ' Return a reverse iterator over the keys, values or items '
|
|
jpayne@68
|
12519 'of the\n'
|
|
jpayne@68
|
12520 ' dictionary. The view will be iterated in reverse order of '
|
|
jpayne@68
|
12521 'the\n'
|
|
jpayne@68
|
12522 ' insertion.\n'
|
|
jpayne@68
|
12523 '\n'
|
|
jpayne@68
|
12524 ' Changed in version 3.8: Dictionary views are now '
|
|
jpayne@68
|
12525 'reversible.\n'
|
|
jpayne@68
|
12526 '\n'
|
|
jpayne@68
|
12527 'Keys views are set-like since their entries are unique and '
|
|
jpayne@68
|
12528 'hashable.\n'
|
|
jpayne@68
|
12529 'If all values are hashable, so that "(key, value)" pairs are '
|
|
jpayne@68
|
12530 'unique\n'
|
|
jpayne@68
|
12531 'and hashable, then the items view is also set-like. (Values '
|
|
jpayne@68
|
12532 'views are\n'
|
|
jpayne@68
|
12533 'not treated as set-like since the entries are generally not '
|
|
jpayne@68
|
12534 'unique.)\n'
|
|
jpayne@68
|
12535 'For set-like views, all of the operations defined for the '
|
|
jpayne@68
|
12536 'abstract\n'
|
|
jpayne@68
|
12537 'base class "collections.abc.Set" are available (for example, '
|
|
jpayne@68
|
12538 '"==",\n'
|
|
jpayne@68
|
12539 '"<", or "^").\n'
|
|
jpayne@68
|
12540 '\n'
|
|
jpayne@68
|
12541 'An example of dictionary view usage:\n'
|
|
jpayne@68
|
12542 '\n'
|
|
jpayne@68
|
12543 " >>> dishes = {'eggs': 2, 'sausage': 1, 'bacon': 1, "
|
|
jpayne@68
|
12544 "'spam': 500}\n"
|
|
jpayne@68
|
12545 ' >>> keys = dishes.keys()\n'
|
|
jpayne@68
|
12546 ' >>> values = dishes.values()\n'
|
|
jpayne@68
|
12547 '\n'
|
|
jpayne@68
|
12548 ' >>> # iteration\n'
|
|
jpayne@68
|
12549 ' >>> n = 0\n'
|
|
jpayne@68
|
12550 ' >>> for val in values:\n'
|
|
jpayne@68
|
12551 ' ... n += val\n'
|
|
jpayne@68
|
12552 ' >>> print(n)\n'
|
|
jpayne@68
|
12553 ' 504\n'
|
|
jpayne@68
|
12554 '\n'
|
|
jpayne@68
|
12555 ' >>> # keys and values are iterated over in the same order '
|
|
jpayne@68
|
12556 '(insertion order)\n'
|
|
jpayne@68
|
12557 ' >>> list(keys)\n'
|
|
jpayne@68
|
12558 " ['eggs', 'sausage', 'bacon', 'spam']\n"
|
|
jpayne@68
|
12559 ' >>> list(values)\n'
|
|
jpayne@68
|
12560 ' [2, 1, 1, 500]\n'
|
|
jpayne@68
|
12561 '\n'
|
|
jpayne@68
|
12562 ' >>> # view objects are dynamic and reflect dict changes\n'
|
|
jpayne@68
|
12563 " >>> del dishes['eggs']\n"
|
|
jpayne@68
|
12564 " >>> del dishes['sausage']\n"
|
|
jpayne@68
|
12565 ' >>> list(keys)\n'
|
|
jpayne@68
|
12566 " ['bacon', 'spam']\n"
|
|
jpayne@68
|
12567 '\n'
|
|
jpayne@68
|
12568 ' >>> # set operations\n'
|
|
jpayne@68
|
12569 " >>> keys & {'eggs', 'bacon', 'salad'}\n"
|
|
jpayne@68
|
12570 " {'bacon'}\n"
|
|
jpayne@68
|
12571 " >>> keys ^ {'sausage', 'juice'}\n"
|
|
jpayne@68
|
12572 " {'juice', 'sausage', 'bacon', 'spam'}\n",
|
|
jpayne@68
|
12573 'typesmethods': 'Methods\n'
|
|
jpayne@68
|
12574 '*******\n'
|
|
jpayne@68
|
12575 '\n'
|
|
jpayne@68
|
12576 'Methods are functions that are called using the attribute '
|
|
jpayne@68
|
12577 'notation.\n'
|
|
jpayne@68
|
12578 'There are two flavors: built-in methods (such as "append()" '
|
|
jpayne@68
|
12579 'on lists)\n'
|
|
jpayne@68
|
12580 'and class instance methods. Built-in methods are described '
|
|
jpayne@68
|
12581 'with the\n'
|
|
jpayne@68
|
12582 'types that support them.\n'
|
|
jpayne@68
|
12583 '\n'
|
|
jpayne@68
|
12584 'If you access a method (a function defined in a class '
|
|
jpayne@68
|
12585 'namespace)\n'
|
|
jpayne@68
|
12586 'through an instance, you get a special object: a *bound '
|
|
jpayne@68
|
12587 'method* (also\n'
|
|
jpayne@68
|
12588 'called *instance method*) object. When called, it will add '
|
|
jpayne@68
|
12589 'the "self"\n'
|
|
jpayne@68
|
12590 'argument to the argument list. Bound methods have two '
|
|
jpayne@68
|
12591 'special read-\n'
|
|
jpayne@68
|
12592 'only attributes: "m.__self__" is the object on which the '
|
|
jpayne@68
|
12593 'method\n'
|
|
jpayne@68
|
12594 'operates, and "m.__func__" is the function implementing the '
|
|
jpayne@68
|
12595 'method.\n'
|
|
jpayne@68
|
12596 'Calling "m(arg-1, arg-2, ..., arg-n)" is completely '
|
|
jpayne@68
|
12597 'equivalent to\n'
|
|
jpayne@68
|
12598 'calling "m.__func__(m.__self__, arg-1, arg-2, ..., arg-n)".\n'
|
|
jpayne@68
|
12599 '\n'
|
|
jpayne@68
|
12600 'Like function objects, bound method objects support getting '
|
|
jpayne@68
|
12601 'arbitrary\n'
|
|
jpayne@68
|
12602 'attributes. However, since method attributes are actually '
|
|
jpayne@68
|
12603 'stored on\n'
|
|
jpayne@68
|
12604 'the underlying function object ("meth.__func__"), setting '
|
|
jpayne@68
|
12605 'method\n'
|
|
jpayne@68
|
12606 'attributes on bound methods is disallowed. Attempting to '
|
|
jpayne@68
|
12607 'set an\n'
|
|
jpayne@68
|
12608 'attribute on a method results in an "AttributeError" being '
|
|
jpayne@68
|
12609 'raised. In\n'
|
|
jpayne@68
|
12610 'order to set a method attribute, you need to explicitly set '
|
|
jpayne@68
|
12611 'it on the\n'
|
|
jpayne@68
|
12612 'underlying function object:\n'
|
|
jpayne@68
|
12613 '\n'
|
|
jpayne@68
|
12614 ' >>> class C:\n'
|
|
jpayne@68
|
12615 ' ... def method(self):\n'
|
|
jpayne@68
|
12616 ' ... pass\n'
|
|
jpayne@68
|
12617 ' ...\n'
|
|
jpayne@68
|
12618 ' >>> c = C()\n'
|
|
jpayne@68
|
12619 " >>> c.method.whoami = 'my name is method' # can't set on "
|
|
jpayne@68
|
12620 'the method\n'
|
|
jpayne@68
|
12621 ' Traceback (most recent call last):\n'
|
|
jpayne@68
|
12622 ' File "<stdin>", line 1, in <module>\n'
|
|
jpayne@68
|
12623 " AttributeError: 'method' object has no attribute "
|
|
jpayne@68
|
12624 "'whoami'\n"
|
|
jpayne@68
|
12625 " >>> c.method.__func__.whoami = 'my name is method'\n"
|
|
jpayne@68
|
12626 ' >>> c.method.whoami\n'
|
|
jpayne@68
|
12627 " 'my name is method'\n"
|
|
jpayne@68
|
12628 '\n'
|
|
jpayne@68
|
12629 'See The standard type hierarchy for more information.\n',
|
|
jpayne@68
|
12630 'typesmodules': 'Modules\n'
|
|
jpayne@68
|
12631 '*******\n'
|
|
jpayne@68
|
12632 '\n'
|
|
jpayne@68
|
12633 'The only special operation on a module is attribute access: '
|
|
jpayne@68
|
12634 '"m.name",\n'
|
|
jpayne@68
|
12635 'where *m* is a module and *name* accesses a name defined in '
|
|
jpayne@68
|
12636 '*m*’s\n'
|
|
jpayne@68
|
12637 'symbol table. Module attributes can be assigned to. (Note '
|
|
jpayne@68
|
12638 'that the\n'
|
|
jpayne@68
|
12639 '"import" statement is not, strictly speaking, an operation '
|
|
jpayne@68
|
12640 'on a module\n'
|
|
jpayne@68
|
12641 'object; "import foo" does not require a module object named '
|
|
jpayne@68
|
12642 '*foo* to\n'
|
|
jpayne@68
|
12643 'exist, rather it requires an (external) *definition* for a '
|
|
jpayne@68
|
12644 'module\n'
|
|
jpayne@68
|
12645 'named *foo* somewhere.)\n'
|
|
jpayne@68
|
12646 '\n'
|
|
jpayne@68
|
12647 'A special attribute of every module is "__dict__". This is '
|
|
jpayne@68
|
12648 'the\n'
|
|
jpayne@68
|
12649 'dictionary containing the module’s symbol table. Modifying '
|
|
jpayne@68
|
12650 'this\n'
|
|
jpayne@68
|
12651 'dictionary will actually change the module’s symbol table, '
|
|
jpayne@68
|
12652 'but direct\n'
|
|
jpayne@68
|
12653 'assignment to the "__dict__" attribute is not possible (you '
|
|
jpayne@68
|
12654 'can write\n'
|
|
jpayne@68
|
12655 '"m.__dict__[\'a\'] = 1", which defines "m.a" to be "1", but '
|
|
jpayne@68
|
12656 'you can’t\n'
|
|
jpayne@68
|
12657 'write "m.__dict__ = {}"). Modifying "__dict__" directly is '
|
|
jpayne@68
|
12658 'not\n'
|
|
jpayne@68
|
12659 'recommended.\n'
|
|
jpayne@68
|
12660 '\n'
|
|
jpayne@68
|
12661 'Modules built into the interpreter are written like this: '
|
|
jpayne@68
|
12662 '"<module\n'
|
|
jpayne@68
|
12663 '\'sys\' (built-in)>". If loaded from a file, they are '
|
|
jpayne@68
|
12664 'written as\n'
|
|
jpayne@68
|
12665 '"<module \'os\' from '
|
|
jpayne@68
|
12666 '\'/usr/local/lib/pythonX.Y/os.pyc\'>".\n',
|
|
jpayne@68
|
12667 'typesseq': 'Sequence Types — "list", "tuple", "range"\n'
|
|
jpayne@68
|
12668 '*****************************************\n'
|
|
jpayne@68
|
12669 '\n'
|
|
jpayne@68
|
12670 'There are three basic sequence types: lists, tuples, and range\n'
|
|
jpayne@68
|
12671 'objects. Additional sequence types tailored for processing of '
|
|
jpayne@68
|
12672 'binary\n'
|
|
jpayne@68
|
12673 'data and text strings are described in dedicated sections.\n'
|
|
jpayne@68
|
12674 '\n'
|
|
jpayne@68
|
12675 '\n'
|
|
jpayne@68
|
12676 'Common Sequence Operations\n'
|
|
jpayne@68
|
12677 '==========================\n'
|
|
jpayne@68
|
12678 '\n'
|
|
jpayne@68
|
12679 'The operations in the following table are supported by most '
|
|
jpayne@68
|
12680 'sequence\n'
|
|
jpayne@68
|
12681 'types, both mutable and immutable. The '
|
|
jpayne@68
|
12682 '"collections.abc.Sequence" ABC\n'
|
|
jpayne@68
|
12683 'is provided to make it easier to correctly implement these '
|
|
jpayne@68
|
12684 'operations\n'
|
|
jpayne@68
|
12685 'on custom sequence types.\n'
|
|
jpayne@68
|
12686 '\n'
|
|
jpayne@68
|
12687 'This table lists the sequence operations sorted in ascending '
|
|
jpayne@68
|
12688 'priority.\n'
|
|
jpayne@68
|
12689 'In the table, *s* and *t* are sequences of the same type, *n*, '
|
|
jpayne@68
|
12690 '*i*,\n'
|
|
jpayne@68
|
12691 '*j* and *k* are integers and *x* is an arbitrary object that '
|
|
jpayne@68
|
12692 'meets any\n'
|
|
jpayne@68
|
12693 'type and value restrictions imposed by *s*.\n'
|
|
jpayne@68
|
12694 '\n'
|
|
jpayne@68
|
12695 'The "in" and "not in" operations have the same priorities as '
|
|
jpayne@68
|
12696 'the\n'
|
|
jpayne@68
|
12697 'comparison operations. The "+" (concatenation) and "*" '
|
|
jpayne@68
|
12698 '(repetition)\n'
|
|
jpayne@68
|
12699 'operations have the same priority as the corresponding numeric\n'
|
|
jpayne@68
|
12700 'operations. [3]\n'
|
|
jpayne@68
|
12701 '\n'
|
|
jpayne@68
|
12702 '+----------------------------+----------------------------------+------------+\n'
|
|
jpayne@68
|
12703 '| Operation | Result '
|
|
jpayne@68
|
12704 '| Notes |\n'
|
|
jpayne@68
|
12705 '|============================|==================================|============|\n'
|
|
jpayne@68
|
12706 '| "x in s" | "True" if an item of *s* is '
|
|
jpayne@68
|
12707 '| (1) |\n'
|
|
jpayne@68
|
12708 '| | equal to *x*, else "False" '
|
|
jpayne@68
|
12709 '| |\n'
|
|
jpayne@68
|
12710 '+----------------------------+----------------------------------+------------+\n'
|
|
jpayne@68
|
12711 '| "x not in s" | "False" if an item of *s* is '
|
|
jpayne@68
|
12712 '| (1) |\n'
|
|
jpayne@68
|
12713 '| | equal to *x*, else "True" '
|
|
jpayne@68
|
12714 '| |\n'
|
|
jpayne@68
|
12715 '+----------------------------+----------------------------------+------------+\n'
|
|
jpayne@68
|
12716 '| "s + t" | the concatenation of *s* and *t* '
|
|
jpayne@68
|
12717 '| (6)(7) |\n'
|
|
jpayne@68
|
12718 '+----------------------------+----------------------------------+------------+\n'
|
|
jpayne@68
|
12719 '| "s * n" or "n * s" | equivalent to adding *s* to '
|
|
jpayne@68
|
12720 '| (2)(7) |\n'
|
|
jpayne@68
|
12721 '| | itself *n* times '
|
|
jpayne@68
|
12722 '| |\n'
|
|
jpayne@68
|
12723 '+----------------------------+----------------------------------+------------+\n'
|
|
jpayne@68
|
12724 '| "s[i]" | *i*th item of *s*, origin 0 '
|
|
jpayne@68
|
12725 '| (3) |\n'
|
|
jpayne@68
|
12726 '+----------------------------+----------------------------------+------------+\n'
|
|
jpayne@68
|
12727 '| "s[i:j]" | slice of *s* from *i* to *j* '
|
|
jpayne@68
|
12728 '| (3)(4) |\n'
|
|
jpayne@68
|
12729 '+----------------------------+----------------------------------+------------+\n'
|
|
jpayne@68
|
12730 '| "s[i:j:k]" | slice of *s* from *i* to *j* '
|
|
jpayne@68
|
12731 '| (3)(5) |\n'
|
|
jpayne@68
|
12732 '| | with step *k* '
|
|
jpayne@68
|
12733 '| |\n'
|
|
jpayne@68
|
12734 '+----------------------------+----------------------------------+------------+\n'
|
|
jpayne@68
|
12735 '| "len(s)" | length of *s* '
|
|
jpayne@68
|
12736 '| |\n'
|
|
jpayne@68
|
12737 '+----------------------------+----------------------------------+------------+\n'
|
|
jpayne@68
|
12738 '| "min(s)" | smallest item of *s* '
|
|
jpayne@68
|
12739 '| |\n'
|
|
jpayne@68
|
12740 '+----------------------------+----------------------------------+------------+\n'
|
|
jpayne@68
|
12741 '| "max(s)" | largest item of *s* '
|
|
jpayne@68
|
12742 '| |\n'
|
|
jpayne@68
|
12743 '+----------------------------+----------------------------------+------------+\n'
|
|
jpayne@68
|
12744 '| "s.index(x[, i[, j]])" | index of the first occurrence of '
|
|
jpayne@68
|
12745 '| (8) |\n'
|
|
jpayne@68
|
12746 '| | *x* in *s* (at or after index '
|
|
jpayne@68
|
12747 '| |\n'
|
|
jpayne@68
|
12748 '| | *i* and before index *j*) '
|
|
jpayne@68
|
12749 '| |\n'
|
|
jpayne@68
|
12750 '+----------------------------+----------------------------------+------------+\n'
|
|
jpayne@68
|
12751 '| "s.count(x)" | total number of occurrences of '
|
|
jpayne@68
|
12752 '| |\n'
|
|
jpayne@68
|
12753 '| | *x* in *s* '
|
|
jpayne@68
|
12754 '| |\n'
|
|
jpayne@68
|
12755 '+----------------------------+----------------------------------+------------+\n'
|
|
jpayne@68
|
12756 '\n'
|
|
jpayne@68
|
12757 'Sequences of the same type also support comparisons. In '
|
|
jpayne@68
|
12758 'particular,\n'
|
|
jpayne@68
|
12759 'tuples and lists are compared lexicographically by comparing\n'
|
|
jpayne@68
|
12760 'corresponding elements. This means that to compare equal, every\n'
|
|
jpayne@68
|
12761 'element must compare equal and the two sequences must be of the '
|
|
jpayne@68
|
12762 'same\n'
|
|
jpayne@68
|
12763 'type and have the same length. (For full details see '
|
|
jpayne@68
|
12764 'Comparisons in\n'
|
|
jpayne@68
|
12765 'the language reference.)\n'
|
|
jpayne@68
|
12766 '\n'
|
|
jpayne@68
|
12767 'Notes:\n'
|
|
jpayne@68
|
12768 '\n'
|
|
jpayne@68
|
12769 '1. While the "in" and "not in" operations are used only for '
|
|
jpayne@68
|
12770 'simple\n'
|
|
jpayne@68
|
12771 ' containment testing in the general case, some specialised '
|
|
jpayne@68
|
12772 'sequences\n'
|
|
jpayne@68
|
12773 ' (such as "str", "bytes" and "bytearray") also use them for\n'
|
|
jpayne@68
|
12774 ' subsequence testing:\n'
|
|
jpayne@68
|
12775 '\n'
|
|
jpayne@68
|
12776 ' >>> "gg" in "eggs"\n'
|
|
jpayne@68
|
12777 ' True\n'
|
|
jpayne@68
|
12778 '\n'
|
|
jpayne@68
|
12779 '2. Values of *n* less than "0" are treated as "0" (which yields '
|
|
jpayne@68
|
12780 'an\n'
|
|
jpayne@68
|
12781 ' empty sequence of the same type as *s*). Note that items in '
|
|
jpayne@68
|
12782 'the\n'
|
|
jpayne@68
|
12783 ' sequence *s* are not copied; they are referenced multiple '
|
|
jpayne@68
|
12784 'times.\n'
|
|
jpayne@68
|
12785 ' This often haunts new Python programmers; consider:\n'
|
|
jpayne@68
|
12786 '\n'
|
|
jpayne@68
|
12787 ' >>> lists = [[]] * 3\n'
|
|
jpayne@68
|
12788 ' >>> lists\n'
|
|
jpayne@68
|
12789 ' [[], [], []]\n'
|
|
jpayne@68
|
12790 ' >>> lists[0].append(3)\n'
|
|
jpayne@68
|
12791 ' >>> lists\n'
|
|
jpayne@68
|
12792 ' [[3], [3], [3]]\n'
|
|
jpayne@68
|
12793 '\n'
|
|
jpayne@68
|
12794 ' What has happened is that "[[]]" is a one-element list '
|
|
jpayne@68
|
12795 'containing\n'
|
|
jpayne@68
|
12796 ' an empty list, so all three elements of "[[]] * 3" are '
|
|
jpayne@68
|
12797 'references\n'
|
|
jpayne@68
|
12798 ' to this single empty list. Modifying any of the elements of\n'
|
|
jpayne@68
|
12799 ' "lists" modifies this single list. You can create a list of\n'
|
|
jpayne@68
|
12800 ' different lists this way:\n'
|
|
jpayne@68
|
12801 '\n'
|
|
jpayne@68
|
12802 ' >>> lists = [[] for i in range(3)]\n'
|
|
jpayne@68
|
12803 ' >>> lists[0].append(3)\n'
|
|
jpayne@68
|
12804 ' >>> lists[1].append(5)\n'
|
|
jpayne@68
|
12805 ' >>> lists[2].append(7)\n'
|
|
jpayne@68
|
12806 ' >>> lists\n'
|
|
jpayne@68
|
12807 ' [[3], [5], [7]]\n'
|
|
jpayne@68
|
12808 '\n'
|
|
jpayne@68
|
12809 ' Further explanation is available in the FAQ entry How do I '
|
|
jpayne@68
|
12810 'create a\n'
|
|
jpayne@68
|
12811 ' multidimensional list?.\n'
|
|
jpayne@68
|
12812 '\n'
|
|
jpayne@68
|
12813 '3. If *i* or *j* is negative, the index is relative to the end '
|
|
jpayne@68
|
12814 'of\n'
|
|
jpayne@68
|
12815 ' sequence *s*: "len(s) + i" or "len(s) + j" is substituted. '
|
|
jpayne@68
|
12816 'But\n'
|
|
jpayne@68
|
12817 ' note that "-0" is still "0".\n'
|
|
jpayne@68
|
12818 '\n'
|
|
jpayne@68
|
12819 '4. The slice of *s* from *i* to *j* is defined as the sequence '
|
|
jpayne@68
|
12820 'of\n'
|
|
jpayne@68
|
12821 ' items with index *k* such that "i <= k < j". If *i* or *j* '
|
|
jpayne@68
|
12822 'is\n'
|
|
jpayne@68
|
12823 ' greater than "len(s)", use "len(s)". If *i* is omitted or '
|
|
jpayne@68
|
12824 '"None",\n'
|
|
jpayne@68
|
12825 ' use "0". If *j* is omitted or "None", use "len(s)". If *i* '
|
|
jpayne@68
|
12826 'is\n'
|
|
jpayne@68
|
12827 ' greater than or equal to *j*, the slice is empty.\n'
|
|
jpayne@68
|
12828 '\n'
|
|
jpayne@68
|
12829 '5. The slice of *s* from *i* to *j* with step *k* is defined as '
|
|
jpayne@68
|
12830 'the\n'
|
|
jpayne@68
|
12831 ' sequence of items with index "x = i + n*k" such that "0 <= n '
|
|
jpayne@68
|
12832 '<\n'
|
|
jpayne@68
|
12833 ' (j-i)/k". In other words, the indices are "i", "i+k", '
|
|
jpayne@68
|
12834 '"i+2*k",\n'
|
|
jpayne@68
|
12835 ' "i+3*k" and so on, stopping when *j* is reached (but never\n'
|
|
jpayne@68
|
12836 ' including *j*). When *k* is positive, *i* and *j* are '
|
|
jpayne@68
|
12837 'reduced to\n'
|
|
jpayne@68
|
12838 ' "len(s)" if they are greater. When *k* is negative, *i* and '
|
|
jpayne@68
|
12839 '*j* are\n'
|
|
jpayne@68
|
12840 ' reduced to "len(s) - 1" if they are greater. If *i* or *j* '
|
|
jpayne@68
|
12841 'are\n'
|
|
jpayne@68
|
12842 ' omitted or "None", they become “end” values (which end '
|
|
jpayne@68
|
12843 'depends on\n'
|
|
jpayne@68
|
12844 ' the sign of *k*). Note, *k* cannot be zero. If *k* is '
|
|
jpayne@68
|
12845 '"None", it\n'
|
|
jpayne@68
|
12846 ' is treated like "1".\n'
|
|
jpayne@68
|
12847 '\n'
|
|
jpayne@68
|
12848 '6. Concatenating immutable sequences always results in a new\n'
|
|
jpayne@68
|
12849 ' object. This means that building up a sequence by repeated\n'
|
|
jpayne@68
|
12850 ' concatenation will have a quadratic runtime cost in the '
|
|
jpayne@68
|
12851 'total\n'
|
|
jpayne@68
|
12852 ' sequence length. To get a linear runtime cost, you must '
|
|
jpayne@68
|
12853 'switch to\n'
|
|
jpayne@68
|
12854 ' one of the alternatives below:\n'
|
|
jpayne@68
|
12855 '\n'
|
|
jpayne@68
|
12856 ' * if concatenating "str" objects, you can build a list and '
|
|
jpayne@68
|
12857 'use\n'
|
|
jpayne@68
|
12858 ' "str.join()" at the end or else write to an "io.StringIO"\n'
|
|
jpayne@68
|
12859 ' instance and retrieve its value when complete\n'
|
|
jpayne@68
|
12860 '\n'
|
|
jpayne@68
|
12861 ' * if concatenating "bytes" objects, you can similarly use\n'
|
|
jpayne@68
|
12862 ' "bytes.join()" or "io.BytesIO", or you can do in-place\n'
|
|
jpayne@68
|
12863 ' concatenation with a "bytearray" object. "bytearray" '
|
|
jpayne@68
|
12864 'objects are\n'
|
|
jpayne@68
|
12865 ' mutable and have an efficient overallocation mechanism\n'
|
|
jpayne@68
|
12866 '\n'
|
|
jpayne@68
|
12867 ' * if concatenating "tuple" objects, extend a "list" instead\n'
|
|
jpayne@68
|
12868 '\n'
|
|
jpayne@68
|
12869 ' * for other types, investigate the relevant class '
|
|
jpayne@68
|
12870 'documentation\n'
|
|
jpayne@68
|
12871 '\n'
|
|
jpayne@68
|
12872 '7. Some sequence types (such as "range") only support item\n'
|
|
jpayne@68
|
12873 ' sequences that follow specific patterns, and hence don’t '
|
|
jpayne@68
|
12874 'support\n'
|
|
jpayne@68
|
12875 ' sequence concatenation or repetition.\n'
|
|
jpayne@68
|
12876 '\n'
|
|
jpayne@68
|
12877 '8. "index" raises "ValueError" when *x* is not found in *s*. '
|
|
jpayne@68
|
12878 'Not\n'
|
|
jpayne@68
|
12879 ' all implementations support passing the additional arguments '
|
|
jpayne@68
|
12880 '*i*\n'
|
|
jpayne@68
|
12881 ' and *j*. These arguments allow efficient searching of '
|
|
jpayne@68
|
12882 'subsections\n'
|
|
jpayne@68
|
12883 ' of the sequence. Passing the extra arguments is roughly '
|
|
jpayne@68
|
12884 'equivalent\n'
|
|
jpayne@68
|
12885 ' to using "s[i:j].index(x)", only without copying any data and '
|
|
jpayne@68
|
12886 'with\n'
|
|
jpayne@68
|
12887 ' the returned index being relative to the start of the '
|
|
jpayne@68
|
12888 'sequence\n'
|
|
jpayne@68
|
12889 ' rather than the start of the slice.\n'
|
|
jpayne@68
|
12890 '\n'
|
|
jpayne@68
|
12891 '\n'
|
|
jpayne@68
|
12892 'Immutable Sequence Types\n'
|
|
jpayne@68
|
12893 '========================\n'
|
|
jpayne@68
|
12894 '\n'
|
|
jpayne@68
|
12895 'The only operation that immutable sequence types generally '
|
|
jpayne@68
|
12896 'implement\n'
|
|
jpayne@68
|
12897 'that is not also implemented by mutable sequence types is '
|
|
jpayne@68
|
12898 'support for\n'
|
|
jpayne@68
|
12899 'the "hash()" built-in.\n'
|
|
jpayne@68
|
12900 '\n'
|
|
jpayne@68
|
12901 'This support allows immutable sequences, such as "tuple" '
|
|
jpayne@68
|
12902 'instances, to\n'
|
|
jpayne@68
|
12903 'be used as "dict" keys and stored in "set" and "frozenset" '
|
|
jpayne@68
|
12904 'instances.\n'
|
|
jpayne@68
|
12905 '\n'
|
|
jpayne@68
|
12906 'Attempting to hash an immutable sequence that contains '
|
|
jpayne@68
|
12907 'unhashable\n'
|
|
jpayne@68
|
12908 'values will result in "TypeError".\n'
|
|
jpayne@68
|
12909 '\n'
|
|
jpayne@68
|
12910 '\n'
|
|
jpayne@68
|
12911 'Mutable Sequence Types\n'
|
|
jpayne@68
|
12912 '======================\n'
|
|
jpayne@68
|
12913 '\n'
|
|
jpayne@68
|
12914 'The operations in the following table are defined on mutable '
|
|
jpayne@68
|
12915 'sequence\n'
|
|
jpayne@68
|
12916 'types. The "collections.abc.MutableSequence" ABC is provided to '
|
|
jpayne@68
|
12917 'make\n'
|
|
jpayne@68
|
12918 'it easier to correctly implement these operations on custom '
|
|
jpayne@68
|
12919 'sequence\n'
|
|
jpayne@68
|
12920 'types.\n'
|
|
jpayne@68
|
12921 '\n'
|
|
jpayne@68
|
12922 'In the table *s* is an instance of a mutable sequence type, *t* '
|
|
jpayne@68
|
12923 'is any\n'
|
|
jpayne@68
|
12924 'iterable object and *x* is an arbitrary object that meets any '
|
|
jpayne@68
|
12925 'type and\n'
|
|
jpayne@68
|
12926 'value restrictions imposed by *s* (for example, "bytearray" '
|
|
jpayne@68
|
12927 'only\n'
|
|
jpayne@68
|
12928 'accepts integers that meet the value restriction "0 <= x <= '
|
|
jpayne@68
|
12929 '255").\n'
|
|
jpayne@68
|
12930 '\n'
|
|
jpayne@68
|
12931 '+--------------------------------+----------------------------------+-----------------------+\n'
|
|
jpayne@68
|
12932 '| Operation | '
|
|
jpayne@68
|
12933 'Result | Notes |\n'
|
|
jpayne@68
|
12934 '|================================|==================================|=======================|\n'
|
|
jpayne@68
|
12935 '| "s[i] = x" | item *i* of *s* is replaced '
|
|
jpayne@68
|
12936 'by | |\n'
|
|
jpayne@68
|
12937 '| | '
|
|
jpayne@68
|
12938 '*x* | |\n'
|
|
jpayne@68
|
12939 '+--------------------------------+----------------------------------+-----------------------+\n'
|
|
jpayne@68
|
12940 '| "s[i:j] = t" | slice of *s* from *i* to *j* '
|
|
jpayne@68
|
12941 'is | |\n'
|
|
jpayne@68
|
12942 '| | replaced by the contents of '
|
|
jpayne@68
|
12943 'the | |\n'
|
|
jpayne@68
|
12944 '| | iterable '
|
|
jpayne@68
|
12945 '*t* | |\n'
|
|
jpayne@68
|
12946 '+--------------------------------+----------------------------------+-----------------------+\n'
|
|
jpayne@68
|
12947 '| "del s[i:j]" | same as "s[i:j] = '
|
|
jpayne@68
|
12948 '[]" | |\n'
|
|
jpayne@68
|
12949 '+--------------------------------+----------------------------------+-----------------------+\n'
|
|
jpayne@68
|
12950 '| "s[i:j:k] = t" | the elements of "s[i:j:k]" '
|
|
jpayne@68
|
12951 'are | (1) |\n'
|
|
jpayne@68
|
12952 '| | replaced by those of '
|
|
jpayne@68
|
12953 '*t* | |\n'
|
|
jpayne@68
|
12954 '+--------------------------------+----------------------------------+-----------------------+\n'
|
|
jpayne@68
|
12955 '| "del s[i:j:k]" | removes the elements '
|
|
jpayne@68
|
12956 'of | |\n'
|
|
jpayne@68
|
12957 '| | "s[i:j:k]" from the '
|
|
jpayne@68
|
12958 'list | |\n'
|
|
jpayne@68
|
12959 '+--------------------------------+----------------------------------+-----------------------+\n'
|
|
jpayne@68
|
12960 '| "s.append(x)" | appends *x* to the end of '
|
|
jpayne@68
|
12961 'the | |\n'
|
|
jpayne@68
|
12962 '| | sequence (same '
|
|
jpayne@68
|
12963 'as | |\n'
|
|
jpayne@68
|
12964 '| | "s[len(s):len(s)] = '
|
|
jpayne@68
|
12965 '[x]") | |\n'
|
|
jpayne@68
|
12966 '+--------------------------------+----------------------------------+-----------------------+\n'
|
|
jpayne@68
|
12967 '| "s.clear()" | removes all items from *s* '
|
|
jpayne@68
|
12968 '(same | (5) |\n'
|
|
jpayne@68
|
12969 '| | as "del '
|
|
jpayne@68
|
12970 's[:]") | |\n'
|
|
jpayne@68
|
12971 '+--------------------------------+----------------------------------+-----------------------+\n'
|
|
jpayne@68
|
12972 '| "s.copy()" | creates a shallow copy of '
|
|
jpayne@68
|
12973 '*s* | (5) |\n'
|
|
jpayne@68
|
12974 '| | (same as '
|
|
jpayne@68
|
12975 '"s[:]") | |\n'
|
|
jpayne@68
|
12976 '+--------------------------------+----------------------------------+-----------------------+\n'
|
|
jpayne@68
|
12977 '| "s.extend(t)" or "s += t" | extends *s* with the contents '
|
|
jpayne@68
|
12978 'of | |\n'
|
|
jpayne@68
|
12979 '| | *t* (for the most part the '
|
|
jpayne@68
|
12980 'same | |\n'
|
|
jpayne@68
|
12981 '| | as "s[len(s):len(s)] = '
|
|
jpayne@68
|
12982 't") | |\n'
|
|
jpayne@68
|
12983 '+--------------------------------+----------------------------------+-----------------------+\n'
|
|
jpayne@68
|
12984 '| "s *= n" | updates *s* with its '
|
|
jpayne@68
|
12985 'contents | (6) |\n'
|
|
jpayne@68
|
12986 '| | repeated *n* '
|
|
jpayne@68
|
12987 'times | |\n'
|
|
jpayne@68
|
12988 '+--------------------------------+----------------------------------+-----------------------+\n'
|
|
jpayne@68
|
12989 '| "s.insert(i, x)" | inserts *x* into *s* at '
|
|
jpayne@68
|
12990 'the | |\n'
|
|
jpayne@68
|
12991 '| | index given by *i* (same '
|
|
jpayne@68
|
12992 'as | |\n'
|
|
jpayne@68
|
12993 '| | "s[i:i] = '
|
|
jpayne@68
|
12994 '[x]") | |\n'
|
|
jpayne@68
|
12995 '+--------------------------------+----------------------------------+-----------------------+\n'
|
|
jpayne@68
|
12996 '| "s.pop([i])" | retrieves the item at *i* '
|
|
jpayne@68
|
12997 'and | (2) |\n'
|
|
jpayne@68
|
12998 '| | also removes it from '
|
|
jpayne@68
|
12999 '*s* | |\n'
|
|
jpayne@68
|
13000 '+--------------------------------+----------------------------------+-----------------------+\n'
|
|
jpayne@68
|
13001 '| "s.remove(x)" | remove the first item from '
|
|
jpayne@68
|
13002 '*s* | (3) |\n'
|
|
jpayne@68
|
13003 '| | where "s[i]" is equal to '
|
|
jpayne@68
|
13004 '*x* | |\n'
|
|
jpayne@68
|
13005 '+--------------------------------+----------------------------------+-----------------------+\n'
|
|
jpayne@68
|
13006 '| "s.reverse()" | reverses the items of *s* '
|
|
jpayne@68
|
13007 'in | (4) |\n'
|
|
jpayne@68
|
13008 '| | '
|
|
jpayne@68
|
13009 'place | |\n'
|
|
jpayne@68
|
13010 '+--------------------------------+----------------------------------+-----------------------+\n'
|
|
jpayne@68
|
13011 '\n'
|
|
jpayne@68
|
13012 'Notes:\n'
|
|
jpayne@68
|
13013 '\n'
|
|
jpayne@68
|
13014 '1. *t* must have the same length as the slice it is replacing.\n'
|
|
jpayne@68
|
13015 '\n'
|
|
jpayne@68
|
13016 '2. The optional argument *i* defaults to "-1", so that by '
|
|
jpayne@68
|
13017 'default\n'
|
|
jpayne@68
|
13018 ' the last item is removed and returned.\n'
|
|
jpayne@68
|
13019 '\n'
|
|
jpayne@68
|
13020 '3. "remove()" raises "ValueError" when *x* is not found in *s*.\n'
|
|
jpayne@68
|
13021 '\n'
|
|
jpayne@68
|
13022 '4. The "reverse()" method modifies the sequence in place for\n'
|
|
jpayne@68
|
13023 ' economy of space when reversing a large sequence. To remind '
|
|
jpayne@68
|
13024 'users\n'
|
|
jpayne@68
|
13025 ' that it operates by side effect, it does not return the '
|
|
jpayne@68
|
13026 'reversed\n'
|
|
jpayne@68
|
13027 ' sequence.\n'
|
|
jpayne@68
|
13028 '\n'
|
|
jpayne@68
|
13029 '5. "clear()" and "copy()" are included for consistency with the\n'
|
|
jpayne@68
|
13030 ' interfaces of mutable containers that don’t support slicing\n'
|
|
jpayne@68
|
13031 ' operations (such as "dict" and "set"). "copy()" is not part '
|
|
jpayne@68
|
13032 'of the\n'
|
|
jpayne@68
|
13033 ' "collections.abc.MutableSequence" ABC, but most concrete '
|
|
jpayne@68
|
13034 'mutable\n'
|
|
jpayne@68
|
13035 ' sequence classes provide it.\n'
|
|
jpayne@68
|
13036 '\n'
|
|
jpayne@68
|
13037 ' New in version 3.3: "clear()" and "copy()" methods.\n'
|
|
jpayne@68
|
13038 '\n'
|
|
jpayne@68
|
13039 '6. The value *n* is an integer, or an object implementing\n'
|
|
jpayne@68
|
13040 ' "__index__()". Zero and negative values of *n* clear the '
|
|
jpayne@68
|
13041 'sequence.\n'
|
|
jpayne@68
|
13042 ' Items in the sequence are not copied; they are referenced '
|
|
jpayne@68
|
13043 'multiple\n'
|
|
jpayne@68
|
13044 ' times, as explained for "s * n" under Common Sequence '
|
|
jpayne@68
|
13045 'Operations.\n'
|
|
jpayne@68
|
13046 '\n'
|
|
jpayne@68
|
13047 '\n'
|
|
jpayne@68
|
13048 'Lists\n'
|
|
jpayne@68
|
13049 '=====\n'
|
|
jpayne@68
|
13050 '\n'
|
|
jpayne@68
|
13051 'Lists are mutable sequences, typically used to store collections '
|
|
jpayne@68
|
13052 'of\n'
|
|
jpayne@68
|
13053 'homogeneous items (where the precise degree of similarity will '
|
|
jpayne@68
|
13054 'vary by\n'
|
|
jpayne@68
|
13055 'application).\n'
|
|
jpayne@68
|
13056 '\n'
|
|
jpayne@68
|
13057 'class list([iterable])\n'
|
|
jpayne@68
|
13058 '\n'
|
|
jpayne@68
|
13059 ' Lists may be constructed in several ways:\n'
|
|
jpayne@68
|
13060 '\n'
|
|
jpayne@68
|
13061 ' * Using a pair of square brackets to denote the empty list: '
|
|
jpayne@68
|
13062 '"[]"\n'
|
|
jpayne@68
|
13063 '\n'
|
|
jpayne@68
|
13064 ' * Using square brackets, separating items with commas: '
|
|
jpayne@68
|
13065 '"[a]",\n'
|
|
jpayne@68
|
13066 ' "[a, b, c]"\n'
|
|
jpayne@68
|
13067 '\n'
|
|
jpayne@68
|
13068 ' * Using a list comprehension: "[x for x in iterable]"\n'
|
|
jpayne@68
|
13069 '\n'
|
|
jpayne@68
|
13070 ' * Using the type constructor: "list()" or "list(iterable)"\n'
|
|
jpayne@68
|
13071 '\n'
|
|
jpayne@68
|
13072 ' The constructor builds a list whose items are the same and in '
|
|
jpayne@68
|
13073 'the\n'
|
|
jpayne@68
|
13074 ' same order as *iterable*’s items. *iterable* may be either '
|
|
jpayne@68
|
13075 'a\n'
|
|
jpayne@68
|
13076 ' sequence, a container that supports iteration, or an '
|
|
jpayne@68
|
13077 'iterator\n'
|
|
jpayne@68
|
13078 ' object. If *iterable* is already a list, a copy is made and\n'
|
|
jpayne@68
|
13079 ' returned, similar to "iterable[:]". For example, '
|
|
jpayne@68
|
13080 '"list(\'abc\')"\n'
|
|
jpayne@68
|
13081 ' returns "[\'a\', \'b\', \'c\']" and "list( (1, 2, 3) )" '
|
|
jpayne@68
|
13082 'returns "[1, 2,\n'
|
|
jpayne@68
|
13083 ' 3]". If no argument is given, the constructor creates a new '
|
|
jpayne@68
|
13084 'empty\n'
|
|
jpayne@68
|
13085 ' list, "[]".\n'
|
|
jpayne@68
|
13086 '\n'
|
|
jpayne@68
|
13087 ' Many other operations also produce lists, including the '
|
|
jpayne@68
|
13088 '"sorted()"\n'
|
|
jpayne@68
|
13089 ' built-in.\n'
|
|
jpayne@68
|
13090 '\n'
|
|
jpayne@68
|
13091 ' Lists implement all of the common and mutable sequence '
|
|
jpayne@68
|
13092 'operations.\n'
|
|
jpayne@68
|
13093 ' Lists also provide the following additional method:\n'
|
|
jpayne@68
|
13094 '\n'
|
|
jpayne@68
|
13095 ' sort(*, key=None, reverse=False)\n'
|
|
jpayne@68
|
13096 '\n'
|
|
jpayne@68
|
13097 ' This method sorts the list in place, using only "<" '
|
|
jpayne@68
|
13098 'comparisons\n'
|
|
jpayne@68
|
13099 ' between items. Exceptions are not suppressed - if any '
|
|
jpayne@68
|
13100 'comparison\n'
|
|
jpayne@68
|
13101 ' operations fail, the entire sort operation will fail (and '
|
|
jpayne@68
|
13102 'the\n'
|
|
jpayne@68
|
13103 ' list will likely be left in a partially modified state).\n'
|
|
jpayne@68
|
13104 '\n'
|
|
jpayne@68
|
13105 ' "sort()" accepts two arguments that can only be passed by\n'
|
|
jpayne@68
|
13106 ' keyword (keyword-only arguments):\n'
|
|
jpayne@68
|
13107 '\n'
|
|
jpayne@68
|
13108 ' *key* specifies a function of one argument that is used '
|
|
jpayne@68
|
13109 'to\n'
|
|
jpayne@68
|
13110 ' extract a comparison key from each list element (for '
|
|
jpayne@68
|
13111 'example,\n'
|
|
jpayne@68
|
13112 ' "key=str.lower"). The key corresponding to each item in '
|
|
jpayne@68
|
13113 'the list\n'
|
|
jpayne@68
|
13114 ' is calculated once and then used for the entire sorting '
|
|
jpayne@68
|
13115 'process.\n'
|
|
jpayne@68
|
13116 ' The default value of "None" means that list items are '
|
|
jpayne@68
|
13117 'sorted\n'
|
|
jpayne@68
|
13118 ' directly without calculating a separate key value.\n'
|
|
jpayne@68
|
13119 '\n'
|
|
jpayne@68
|
13120 ' The "functools.cmp_to_key()" utility is available to '
|
|
jpayne@68
|
13121 'convert a\n'
|
|
jpayne@68
|
13122 ' 2.x style *cmp* function to a *key* function.\n'
|
|
jpayne@68
|
13123 '\n'
|
|
jpayne@68
|
13124 ' *reverse* is a boolean value. If set to "True", then the '
|
|
jpayne@68
|
13125 'list\n'
|
|
jpayne@68
|
13126 ' elements are sorted as if each comparison were reversed.\n'
|
|
jpayne@68
|
13127 '\n'
|
|
jpayne@68
|
13128 ' This method modifies the sequence in place for economy of '
|
|
jpayne@68
|
13129 'space\n'
|
|
jpayne@68
|
13130 ' when sorting a large sequence. To remind users that it '
|
|
jpayne@68
|
13131 'operates\n'
|
|
jpayne@68
|
13132 ' by side effect, it does not return the sorted sequence '
|
|
jpayne@68
|
13133 '(use\n'
|
|
jpayne@68
|
13134 ' "sorted()" to explicitly request a new sorted list '
|
|
jpayne@68
|
13135 'instance).\n'
|
|
jpayne@68
|
13136 '\n'
|
|
jpayne@68
|
13137 ' The "sort()" method is guaranteed to be stable. A sort '
|
|
jpayne@68
|
13138 'is\n'
|
|
jpayne@68
|
13139 ' stable if it guarantees not to change the relative order '
|
|
jpayne@68
|
13140 'of\n'
|
|
jpayne@68
|
13141 ' elements that compare equal — this is helpful for sorting '
|
|
jpayne@68
|
13142 'in\n'
|
|
jpayne@68
|
13143 ' multiple passes (for example, sort by department, then by '
|
|
jpayne@68
|
13144 'salary\n'
|
|
jpayne@68
|
13145 ' grade).\n'
|
|
jpayne@68
|
13146 '\n'
|
|
jpayne@68
|
13147 ' For sorting examples and a brief sorting tutorial, see '
|
|
jpayne@68
|
13148 'Sorting\n'
|
|
jpayne@68
|
13149 ' HOW TO.\n'
|
|
jpayne@68
|
13150 '\n'
|
|
jpayne@68
|
13151 ' **CPython implementation detail:** While a list is being '
|
|
jpayne@68
|
13152 'sorted,\n'
|
|
jpayne@68
|
13153 ' the effect of attempting to mutate, or even inspect, the '
|
|
jpayne@68
|
13154 'list is\n'
|
|
jpayne@68
|
13155 ' undefined. The C implementation of Python makes the list '
|
|
jpayne@68
|
13156 'appear\n'
|
|
jpayne@68
|
13157 ' empty for the duration, and raises "ValueError" if it can '
|
|
jpayne@68
|
13158 'detect\n'
|
|
jpayne@68
|
13159 ' that the list has been mutated during a sort.\n'
|
|
jpayne@68
|
13160 '\n'
|
|
jpayne@68
|
13161 '\n'
|
|
jpayne@68
|
13162 'Tuples\n'
|
|
jpayne@68
|
13163 '======\n'
|
|
jpayne@68
|
13164 '\n'
|
|
jpayne@68
|
13165 'Tuples are immutable sequences, typically used to store '
|
|
jpayne@68
|
13166 'collections of\n'
|
|
jpayne@68
|
13167 'heterogeneous data (such as the 2-tuples produced by the '
|
|
jpayne@68
|
13168 '"enumerate()"\n'
|
|
jpayne@68
|
13169 'built-in). Tuples are also used for cases where an immutable '
|
|
jpayne@68
|
13170 'sequence\n'
|
|
jpayne@68
|
13171 'of homogeneous data is needed (such as allowing storage in a '
|
|
jpayne@68
|
13172 '"set" or\n'
|
|
jpayne@68
|
13173 '"dict" instance).\n'
|
|
jpayne@68
|
13174 '\n'
|
|
jpayne@68
|
13175 'class tuple([iterable])\n'
|
|
jpayne@68
|
13176 '\n'
|
|
jpayne@68
|
13177 ' Tuples may be constructed in a number of ways:\n'
|
|
jpayne@68
|
13178 '\n'
|
|
jpayne@68
|
13179 ' * Using a pair of parentheses to denote the empty tuple: '
|
|
jpayne@68
|
13180 '"()"\n'
|
|
jpayne@68
|
13181 '\n'
|
|
jpayne@68
|
13182 ' * Using a trailing comma for a singleton tuple: "a," or '
|
|
jpayne@68
|
13183 '"(a,)"\n'
|
|
jpayne@68
|
13184 '\n'
|
|
jpayne@68
|
13185 ' * Separating items with commas: "a, b, c" or "(a, b, c)"\n'
|
|
jpayne@68
|
13186 '\n'
|
|
jpayne@68
|
13187 ' * Using the "tuple()" built-in: "tuple()" or '
|
|
jpayne@68
|
13188 '"tuple(iterable)"\n'
|
|
jpayne@68
|
13189 '\n'
|
|
jpayne@68
|
13190 ' The constructor builds a tuple whose items are the same and '
|
|
jpayne@68
|
13191 'in the\n'
|
|
jpayne@68
|
13192 ' same order as *iterable*’s items. *iterable* may be either '
|
|
jpayne@68
|
13193 'a\n'
|
|
jpayne@68
|
13194 ' sequence, a container that supports iteration, or an '
|
|
jpayne@68
|
13195 'iterator\n'
|
|
jpayne@68
|
13196 ' object. If *iterable* is already a tuple, it is returned\n'
|
|
jpayne@68
|
13197 ' unchanged. For example, "tuple(\'abc\')" returns "(\'a\', '
|
|
jpayne@68
|
13198 '\'b\', \'c\')"\n'
|
|
jpayne@68
|
13199 ' and "tuple( [1, 2, 3] )" returns "(1, 2, 3)". If no argument '
|
|
jpayne@68
|
13200 'is\n'
|
|
jpayne@68
|
13201 ' given, the constructor creates a new empty tuple, "()".\n'
|
|
jpayne@68
|
13202 '\n'
|
|
jpayne@68
|
13203 ' Note that it is actually the comma which makes a tuple, not '
|
|
jpayne@68
|
13204 'the\n'
|
|
jpayne@68
|
13205 ' parentheses. The parentheses are optional, except in the '
|
|
jpayne@68
|
13206 'empty\n'
|
|
jpayne@68
|
13207 ' tuple case, or when they are needed to avoid syntactic '
|
|
jpayne@68
|
13208 'ambiguity.\n'
|
|
jpayne@68
|
13209 ' For example, "f(a, b, c)" is a function call with three '
|
|
jpayne@68
|
13210 'arguments,\n'
|
|
jpayne@68
|
13211 ' while "f((a, b, c))" is a function call with a 3-tuple as the '
|
|
jpayne@68
|
13212 'sole\n'
|
|
jpayne@68
|
13213 ' argument.\n'
|
|
jpayne@68
|
13214 '\n'
|
|
jpayne@68
|
13215 ' Tuples implement all of the common sequence operations.\n'
|
|
jpayne@68
|
13216 '\n'
|
|
jpayne@68
|
13217 'For heterogeneous collections of data where access by name is '
|
|
jpayne@68
|
13218 'clearer\n'
|
|
jpayne@68
|
13219 'than access by index, "collections.namedtuple()" may be a more\n'
|
|
jpayne@68
|
13220 'appropriate choice than a simple tuple object.\n'
|
|
jpayne@68
|
13221 '\n'
|
|
jpayne@68
|
13222 '\n'
|
|
jpayne@68
|
13223 'Ranges\n'
|
|
jpayne@68
|
13224 '======\n'
|
|
jpayne@68
|
13225 '\n'
|
|
jpayne@68
|
13226 'The "range" type represents an immutable sequence of numbers and '
|
|
jpayne@68
|
13227 'is\n'
|
|
jpayne@68
|
13228 'commonly used for looping a specific number of times in "for" '
|
|
jpayne@68
|
13229 'loops.\n'
|
|
jpayne@68
|
13230 '\n'
|
|
jpayne@68
|
13231 'class range(stop)\n'
|
|
jpayne@68
|
13232 'class range(start, stop[, step])\n'
|
|
jpayne@68
|
13233 '\n'
|
|
jpayne@68
|
13234 ' The arguments to the range constructor must be integers '
|
|
jpayne@68
|
13235 '(either\n'
|
|
jpayne@68
|
13236 ' built-in "int" or any object that implements the "__index__"\n'
|
|
jpayne@68
|
13237 ' special method). If the *step* argument is omitted, it '
|
|
jpayne@68
|
13238 'defaults to\n'
|
|
jpayne@68
|
13239 ' "1". If the *start* argument is omitted, it defaults to "0". '
|
|
jpayne@68
|
13240 'If\n'
|
|
jpayne@68
|
13241 ' *step* is zero, "ValueError" is raised.\n'
|
|
jpayne@68
|
13242 '\n'
|
|
jpayne@68
|
13243 ' For a positive *step*, the contents of a range "r" are '
|
|
jpayne@68
|
13244 'determined\n'
|
|
jpayne@68
|
13245 ' by the formula "r[i] = start + step*i" where "i >= 0" and '
|
|
jpayne@68
|
13246 '"r[i] <\n'
|
|
jpayne@68
|
13247 ' stop".\n'
|
|
jpayne@68
|
13248 '\n'
|
|
jpayne@68
|
13249 ' For a negative *step*, the contents of the range are still\n'
|
|
jpayne@68
|
13250 ' determined by the formula "r[i] = start + step*i", but the\n'
|
|
jpayne@68
|
13251 ' constraints are "i >= 0" and "r[i] > stop".\n'
|
|
jpayne@68
|
13252 '\n'
|
|
jpayne@68
|
13253 ' A range object will be empty if "r[0]" does not meet the '
|
|
jpayne@68
|
13254 'value\n'
|
|
jpayne@68
|
13255 ' constraint. Ranges do support negative indices, but these '
|
|
jpayne@68
|
13256 'are\n'
|
|
jpayne@68
|
13257 ' interpreted as indexing from the end of the sequence '
|
|
jpayne@68
|
13258 'determined by\n'
|
|
jpayne@68
|
13259 ' the positive indices.\n'
|
|
jpayne@68
|
13260 '\n'
|
|
jpayne@68
|
13261 ' Ranges containing absolute values larger than "sys.maxsize" '
|
|
jpayne@68
|
13262 'are\n'
|
|
jpayne@68
|
13263 ' permitted but some features (such as "len()") may raise\n'
|
|
jpayne@68
|
13264 ' "OverflowError".\n'
|
|
jpayne@68
|
13265 '\n'
|
|
jpayne@68
|
13266 ' Range examples:\n'
|
|
jpayne@68
|
13267 '\n'
|
|
jpayne@68
|
13268 ' >>> list(range(10))\n'
|
|
jpayne@68
|
13269 ' [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]\n'
|
|
jpayne@68
|
13270 ' >>> list(range(1, 11))\n'
|
|
jpayne@68
|
13271 ' [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]\n'
|
|
jpayne@68
|
13272 ' >>> list(range(0, 30, 5))\n'
|
|
jpayne@68
|
13273 ' [0, 5, 10, 15, 20, 25]\n'
|
|
jpayne@68
|
13274 ' >>> list(range(0, 10, 3))\n'
|
|
jpayne@68
|
13275 ' [0, 3, 6, 9]\n'
|
|
jpayne@68
|
13276 ' >>> list(range(0, -10, -1))\n'
|
|
jpayne@68
|
13277 ' [0, -1, -2, -3, -4, -5, -6, -7, -8, -9]\n'
|
|
jpayne@68
|
13278 ' >>> list(range(0))\n'
|
|
jpayne@68
|
13279 ' []\n'
|
|
jpayne@68
|
13280 ' >>> list(range(1, 0))\n'
|
|
jpayne@68
|
13281 ' []\n'
|
|
jpayne@68
|
13282 '\n'
|
|
jpayne@68
|
13283 ' Ranges implement all of the common sequence operations '
|
|
jpayne@68
|
13284 'except\n'
|
|
jpayne@68
|
13285 ' concatenation and repetition (due to the fact that range '
|
|
jpayne@68
|
13286 'objects\n'
|
|
jpayne@68
|
13287 ' can only represent sequences that follow a strict pattern '
|
|
jpayne@68
|
13288 'and\n'
|
|
jpayne@68
|
13289 ' repetition and concatenation will usually violate that '
|
|
jpayne@68
|
13290 'pattern).\n'
|
|
jpayne@68
|
13291 '\n'
|
|
jpayne@68
|
13292 ' start\n'
|
|
jpayne@68
|
13293 '\n'
|
|
jpayne@68
|
13294 ' The value of the *start* parameter (or "0" if the '
|
|
jpayne@68
|
13295 'parameter was\n'
|
|
jpayne@68
|
13296 ' not supplied)\n'
|
|
jpayne@68
|
13297 '\n'
|
|
jpayne@68
|
13298 ' stop\n'
|
|
jpayne@68
|
13299 '\n'
|
|
jpayne@68
|
13300 ' The value of the *stop* parameter\n'
|
|
jpayne@68
|
13301 '\n'
|
|
jpayne@68
|
13302 ' step\n'
|
|
jpayne@68
|
13303 '\n'
|
|
jpayne@68
|
13304 ' The value of the *step* parameter (or "1" if the parameter '
|
|
jpayne@68
|
13305 'was\n'
|
|
jpayne@68
|
13306 ' not supplied)\n'
|
|
jpayne@68
|
13307 '\n'
|
|
jpayne@68
|
13308 'The advantage of the "range" type over a regular "list" or '
|
|
jpayne@68
|
13309 '"tuple" is\n'
|
|
jpayne@68
|
13310 'that a "range" object will always take the same (small) amount '
|
|
jpayne@68
|
13311 'of\n'
|
|
jpayne@68
|
13312 'memory, no matter the size of the range it represents (as it '
|
|
jpayne@68
|
13313 'only\n'
|
|
jpayne@68
|
13314 'stores the "start", "stop" and "step" values, calculating '
|
|
jpayne@68
|
13315 'individual\n'
|
|
jpayne@68
|
13316 'items and subranges as needed).\n'
|
|
jpayne@68
|
13317 '\n'
|
|
jpayne@68
|
13318 'Range objects implement the "collections.abc.Sequence" ABC, and\n'
|
|
jpayne@68
|
13319 'provide features such as containment tests, element index '
|
|
jpayne@68
|
13320 'lookup,\n'
|
|
jpayne@68
|
13321 'slicing and support for negative indices (see Sequence Types — '
|
|
jpayne@68
|
13322 'list,\n'
|
|
jpayne@68
|
13323 'tuple, range):\n'
|
|
jpayne@68
|
13324 '\n'
|
|
jpayne@68
|
13325 '>>> r = range(0, 20, 2)\n'
|
|
jpayne@68
|
13326 '>>> r\n'
|
|
jpayne@68
|
13327 'range(0, 20, 2)\n'
|
|
jpayne@68
|
13328 '>>> 11 in r\n'
|
|
jpayne@68
|
13329 'False\n'
|
|
jpayne@68
|
13330 '>>> 10 in r\n'
|
|
jpayne@68
|
13331 'True\n'
|
|
jpayne@68
|
13332 '>>> r.index(10)\n'
|
|
jpayne@68
|
13333 '5\n'
|
|
jpayne@68
|
13334 '>>> r[5]\n'
|
|
jpayne@68
|
13335 '10\n'
|
|
jpayne@68
|
13336 '>>> r[:5]\n'
|
|
jpayne@68
|
13337 'range(0, 10, 2)\n'
|
|
jpayne@68
|
13338 '>>> r[-1]\n'
|
|
jpayne@68
|
13339 '18\n'
|
|
jpayne@68
|
13340 '\n'
|
|
jpayne@68
|
13341 'Testing range objects for equality with "==" and "!=" compares '
|
|
jpayne@68
|
13342 'them as\n'
|
|
jpayne@68
|
13343 'sequences. That is, two range objects are considered equal if '
|
|
jpayne@68
|
13344 'they\n'
|
|
jpayne@68
|
13345 'represent the same sequence of values. (Note that two range '
|
|
jpayne@68
|
13346 'objects\n'
|
|
jpayne@68
|
13347 'that compare equal might have different "start", "stop" and '
|
|
jpayne@68
|
13348 '"step"\n'
|
|
jpayne@68
|
13349 'attributes, for example "range(0) == range(2, 1, 3)" or '
|
|
jpayne@68
|
13350 '"range(0, 3,\n'
|
|
jpayne@68
|
13351 '2) == range(0, 4, 2)".)\n'
|
|
jpayne@68
|
13352 '\n'
|
|
jpayne@68
|
13353 'Changed in version 3.2: Implement the Sequence ABC. Support '
|
|
jpayne@68
|
13354 'slicing\n'
|
|
jpayne@68
|
13355 'and negative indices. Test "int" objects for membership in '
|
|
jpayne@68
|
13356 'constant\n'
|
|
jpayne@68
|
13357 'time instead of iterating through all items.\n'
|
|
jpayne@68
|
13358 '\n'
|
|
jpayne@68
|
13359 'Changed in version 3.3: Define ‘==’ and ‘!=’ to compare range '
|
|
jpayne@68
|
13360 'objects\n'
|
|
jpayne@68
|
13361 'based on the sequence of values they define (instead of '
|
|
jpayne@68
|
13362 'comparing\n'
|
|
jpayne@68
|
13363 'based on object identity).\n'
|
|
jpayne@68
|
13364 '\n'
|
|
jpayne@68
|
13365 'New in version 3.3: The "start", "stop" and "step" attributes.\n'
|
|
jpayne@68
|
13366 '\n'
|
|
jpayne@68
|
13367 'See also:\n'
|
|
jpayne@68
|
13368 '\n'
|
|
jpayne@68
|
13369 ' * The linspace recipe shows how to implement a lazy version '
|
|
jpayne@68
|
13370 'of\n'
|
|
jpayne@68
|
13371 ' range suitable for floating point applications.\n',
|
|
jpayne@68
|
13372 'typesseq-mutable': 'Mutable Sequence Types\n'
|
|
jpayne@68
|
13373 '**********************\n'
|
|
jpayne@68
|
13374 '\n'
|
|
jpayne@68
|
13375 'The operations in the following table are defined on '
|
|
jpayne@68
|
13376 'mutable sequence\n'
|
|
jpayne@68
|
13377 'types. The "collections.abc.MutableSequence" ABC is '
|
|
jpayne@68
|
13378 'provided to make\n'
|
|
jpayne@68
|
13379 'it easier to correctly implement these operations on '
|
|
jpayne@68
|
13380 'custom sequence\n'
|
|
jpayne@68
|
13381 'types.\n'
|
|
jpayne@68
|
13382 '\n'
|
|
jpayne@68
|
13383 'In the table *s* is an instance of a mutable sequence '
|
|
jpayne@68
|
13384 'type, *t* is any\n'
|
|
jpayne@68
|
13385 'iterable object and *x* is an arbitrary object that '
|
|
jpayne@68
|
13386 'meets any type and\n'
|
|
jpayne@68
|
13387 'value restrictions imposed by *s* (for example, '
|
|
jpayne@68
|
13388 '"bytearray" only\n'
|
|
jpayne@68
|
13389 'accepts integers that meet the value restriction "0 <= x '
|
|
jpayne@68
|
13390 '<= 255").\n'
|
|
jpayne@68
|
13391 '\n'
|
|
jpayne@68
|
13392 '+--------------------------------+----------------------------------+-----------------------+\n'
|
|
jpayne@68
|
13393 '| Operation | '
|
|
jpayne@68
|
13394 'Result | Notes '
|
|
jpayne@68
|
13395 '|\n'
|
|
jpayne@68
|
13396 '|================================|==================================|=======================|\n'
|
|
jpayne@68
|
13397 '| "s[i] = x" | item *i* of *s* is '
|
|
jpayne@68
|
13398 'replaced by | |\n'
|
|
jpayne@68
|
13399 '| | '
|
|
jpayne@68
|
13400 '*x* | '
|
|
jpayne@68
|
13401 '|\n'
|
|
jpayne@68
|
13402 '+--------------------------------+----------------------------------+-----------------------+\n'
|
|
jpayne@68
|
13403 '| "s[i:j] = t" | slice of *s* from *i* '
|
|
jpayne@68
|
13404 'to *j* is | |\n'
|
|
jpayne@68
|
13405 '| | replaced by the '
|
|
jpayne@68
|
13406 'contents of the | |\n'
|
|
jpayne@68
|
13407 '| | iterable '
|
|
jpayne@68
|
13408 '*t* | |\n'
|
|
jpayne@68
|
13409 '+--------------------------------+----------------------------------+-----------------------+\n'
|
|
jpayne@68
|
13410 '| "del s[i:j]" | same as "s[i:j] = '
|
|
jpayne@68
|
13411 '[]" | |\n'
|
|
jpayne@68
|
13412 '+--------------------------------+----------------------------------+-----------------------+\n'
|
|
jpayne@68
|
13413 '| "s[i:j:k] = t" | the elements of '
|
|
jpayne@68
|
13414 '"s[i:j:k]" are | (1) |\n'
|
|
jpayne@68
|
13415 '| | replaced by those of '
|
|
jpayne@68
|
13416 '*t* | |\n'
|
|
jpayne@68
|
13417 '+--------------------------------+----------------------------------+-----------------------+\n'
|
|
jpayne@68
|
13418 '| "del s[i:j:k]" | removes the elements '
|
|
jpayne@68
|
13419 'of | |\n'
|
|
jpayne@68
|
13420 '| | "s[i:j:k]" from the '
|
|
jpayne@68
|
13421 'list | |\n'
|
|
jpayne@68
|
13422 '+--------------------------------+----------------------------------+-----------------------+\n'
|
|
jpayne@68
|
13423 '| "s.append(x)" | appends *x* to the '
|
|
jpayne@68
|
13424 'end of the | |\n'
|
|
jpayne@68
|
13425 '| | sequence (same '
|
|
jpayne@68
|
13426 'as | |\n'
|
|
jpayne@68
|
13427 '| | "s[len(s):len(s)] = '
|
|
jpayne@68
|
13428 '[x]") | |\n'
|
|
jpayne@68
|
13429 '+--------------------------------+----------------------------------+-----------------------+\n'
|
|
jpayne@68
|
13430 '| "s.clear()" | removes all items '
|
|
jpayne@68
|
13431 'from *s* (same | (5) |\n'
|
|
jpayne@68
|
13432 '| | as "del '
|
|
jpayne@68
|
13433 's[:]") | |\n'
|
|
jpayne@68
|
13434 '+--------------------------------+----------------------------------+-----------------------+\n'
|
|
jpayne@68
|
13435 '| "s.copy()" | creates a shallow '
|
|
jpayne@68
|
13436 'copy of *s* | (5) |\n'
|
|
jpayne@68
|
13437 '| | (same as '
|
|
jpayne@68
|
13438 '"s[:]") | |\n'
|
|
jpayne@68
|
13439 '+--------------------------------+----------------------------------+-----------------------+\n'
|
|
jpayne@68
|
13440 '| "s.extend(t)" or "s += t" | extends *s* with the '
|
|
jpayne@68
|
13441 'contents of | |\n'
|
|
jpayne@68
|
13442 '| | *t* (for the most '
|
|
jpayne@68
|
13443 'part the same | |\n'
|
|
jpayne@68
|
13444 '| | as "s[len(s):len(s)] '
|
|
jpayne@68
|
13445 '= t") | |\n'
|
|
jpayne@68
|
13446 '+--------------------------------+----------------------------------+-----------------------+\n'
|
|
jpayne@68
|
13447 '| "s *= n" | updates *s* with its '
|
|
jpayne@68
|
13448 'contents | (6) |\n'
|
|
jpayne@68
|
13449 '| | repeated *n* '
|
|
jpayne@68
|
13450 'times | |\n'
|
|
jpayne@68
|
13451 '+--------------------------------+----------------------------------+-----------------------+\n'
|
|
jpayne@68
|
13452 '| "s.insert(i, x)" | inserts *x* into *s* '
|
|
jpayne@68
|
13453 'at the | |\n'
|
|
jpayne@68
|
13454 '| | index given by *i* '
|
|
jpayne@68
|
13455 '(same as | |\n'
|
|
jpayne@68
|
13456 '| | "s[i:i] = '
|
|
jpayne@68
|
13457 '[x]") | |\n'
|
|
jpayne@68
|
13458 '+--------------------------------+----------------------------------+-----------------------+\n'
|
|
jpayne@68
|
13459 '| "s.pop([i])" | retrieves the item at '
|
|
jpayne@68
|
13460 '*i* and | (2) |\n'
|
|
jpayne@68
|
13461 '| | also removes it from '
|
|
jpayne@68
|
13462 '*s* | |\n'
|
|
jpayne@68
|
13463 '+--------------------------------+----------------------------------+-----------------------+\n'
|
|
jpayne@68
|
13464 '| "s.remove(x)" | remove the first item '
|
|
jpayne@68
|
13465 'from *s* | (3) |\n'
|
|
jpayne@68
|
13466 '| | where "s[i]" is equal '
|
|
jpayne@68
|
13467 'to *x* | |\n'
|
|
jpayne@68
|
13468 '+--------------------------------+----------------------------------+-----------------------+\n'
|
|
jpayne@68
|
13469 '| "s.reverse()" | reverses the items of '
|
|
jpayne@68
|
13470 '*s* in | (4) |\n'
|
|
jpayne@68
|
13471 '| | '
|
|
jpayne@68
|
13472 'place | '
|
|
jpayne@68
|
13473 '|\n'
|
|
jpayne@68
|
13474 '+--------------------------------+----------------------------------+-----------------------+\n'
|
|
jpayne@68
|
13475 '\n'
|
|
jpayne@68
|
13476 'Notes:\n'
|
|
jpayne@68
|
13477 '\n'
|
|
jpayne@68
|
13478 '1. *t* must have the same length as the slice it is '
|
|
jpayne@68
|
13479 'replacing.\n'
|
|
jpayne@68
|
13480 '\n'
|
|
jpayne@68
|
13481 '2. The optional argument *i* defaults to "-1", so that '
|
|
jpayne@68
|
13482 'by default\n'
|
|
jpayne@68
|
13483 ' the last item is removed and returned.\n'
|
|
jpayne@68
|
13484 '\n'
|
|
jpayne@68
|
13485 '3. "remove()" raises "ValueError" when *x* is not found '
|
|
jpayne@68
|
13486 'in *s*.\n'
|
|
jpayne@68
|
13487 '\n'
|
|
jpayne@68
|
13488 '4. The "reverse()" method modifies the sequence in place '
|
|
jpayne@68
|
13489 'for\n'
|
|
jpayne@68
|
13490 ' economy of space when reversing a large sequence. To '
|
|
jpayne@68
|
13491 'remind users\n'
|
|
jpayne@68
|
13492 ' that it operates by side effect, it does not return '
|
|
jpayne@68
|
13493 'the reversed\n'
|
|
jpayne@68
|
13494 ' sequence.\n'
|
|
jpayne@68
|
13495 '\n'
|
|
jpayne@68
|
13496 '5. "clear()" and "copy()" are included for consistency '
|
|
jpayne@68
|
13497 'with the\n'
|
|
jpayne@68
|
13498 ' interfaces of mutable containers that don’t support '
|
|
jpayne@68
|
13499 'slicing\n'
|
|
jpayne@68
|
13500 ' operations (such as "dict" and "set"). "copy()" is '
|
|
jpayne@68
|
13501 'not part of the\n'
|
|
jpayne@68
|
13502 ' "collections.abc.MutableSequence" ABC, but most '
|
|
jpayne@68
|
13503 'concrete mutable\n'
|
|
jpayne@68
|
13504 ' sequence classes provide it.\n'
|
|
jpayne@68
|
13505 '\n'
|
|
jpayne@68
|
13506 ' New in version 3.3: "clear()" and "copy()" methods.\n'
|
|
jpayne@68
|
13507 '\n'
|
|
jpayne@68
|
13508 '6. The value *n* is an integer, or an object '
|
|
jpayne@68
|
13509 'implementing\n'
|
|
jpayne@68
|
13510 ' "__index__()". Zero and negative values of *n* clear '
|
|
jpayne@68
|
13511 'the sequence.\n'
|
|
jpayne@68
|
13512 ' Items in the sequence are not copied; they are '
|
|
jpayne@68
|
13513 'referenced multiple\n'
|
|
jpayne@68
|
13514 ' times, as explained for "s * n" under Common Sequence '
|
|
jpayne@68
|
13515 'Operations.\n',
|
|
jpayne@68
|
13516 'unary': 'Unary arithmetic and bitwise operations\n'
|
|
jpayne@68
|
13517 '***************************************\n'
|
|
jpayne@68
|
13518 '\n'
|
|
jpayne@68
|
13519 'All unary arithmetic and bitwise operations have the same '
|
|
jpayne@68
|
13520 'priority:\n'
|
|
jpayne@68
|
13521 '\n'
|
|
jpayne@68
|
13522 ' u_expr ::= power | "-" u_expr | "+" u_expr | "~" u_expr\n'
|
|
jpayne@68
|
13523 '\n'
|
|
jpayne@68
|
13524 'The unary "-" (minus) operator yields the negation of its numeric\n'
|
|
jpayne@68
|
13525 'argument.\n'
|
|
jpayne@68
|
13526 '\n'
|
|
jpayne@68
|
13527 'The unary "+" (plus) operator yields its numeric argument '
|
|
jpayne@68
|
13528 'unchanged.\n'
|
|
jpayne@68
|
13529 '\n'
|
|
jpayne@68
|
13530 'The unary "~" (invert) operator yields the bitwise inversion of '
|
|
jpayne@68
|
13531 'its\n'
|
|
jpayne@68
|
13532 'integer argument. The bitwise inversion of "x" is defined as\n'
|
|
jpayne@68
|
13533 '"-(x+1)". It only applies to integral numbers.\n'
|
|
jpayne@68
|
13534 '\n'
|
|
jpayne@68
|
13535 'In all three cases, if the argument does not have the proper type, '
|
|
jpayne@68
|
13536 'a\n'
|
|
jpayne@68
|
13537 '"TypeError" exception is raised.\n',
|
|
jpayne@68
|
13538 'while': 'The "while" statement\n'
|
|
jpayne@68
|
13539 '*********************\n'
|
|
jpayne@68
|
13540 '\n'
|
|
jpayne@68
|
13541 'The "while" statement is used for repeated execution as long as an\n'
|
|
jpayne@68
|
13542 'expression is true:\n'
|
|
jpayne@68
|
13543 '\n'
|
|
jpayne@68
|
13544 ' while_stmt ::= "while" expression ":" suite\n'
|
|
jpayne@68
|
13545 ' ["else" ":" suite]\n'
|
|
jpayne@68
|
13546 '\n'
|
|
jpayne@68
|
13547 'This repeatedly tests the expression and, if it is true, executes '
|
|
jpayne@68
|
13548 'the\n'
|
|
jpayne@68
|
13549 'first suite; if the expression is false (which may be the first '
|
|
jpayne@68
|
13550 'time\n'
|
|
jpayne@68
|
13551 'it is tested) the suite of the "else" clause, if present, is '
|
|
jpayne@68
|
13552 'executed\n'
|
|
jpayne@68
|
13553 'and the loop terminates.\n'
|
|
jpayne@68
|
13554 '\n'
|
|
jpayne@68
|
13555 'A "break" statement executed in the first suite terminates the '
|
|
jpayne@68
|
13556 'loop\n'
|
|
jpayne@68
|
13557 'without executing the "else" clause’s suite. A "continue" '
|
|
jpayne@68
|
13558 'statement\n'
|
|
jpayne@68
|
13559 'executed in the first suite skips the rest of the suite and goes '
|
|
jpayne@68
|
13560 'back\n'
|
|
jpayne@68
|
13561 'to testing the expression.\n',
|
|
jpayne@68
|
13562 'with': 'The "with" statement\n'
|
|
jpayne@68
|
13563 '********************\n'
|
|
jpayne@68
|
13564 '\n'
|
|
jpayne@68
|
13565 'The "with" statement is used to wrap the execution of a block with\n'
|
|
jpayne@68
|
13566 'methods defined by a context manager (see section With Statement\n'
|
|
jpayne@68
|
13567 'Context Managers). This allows common "try"…"except"…"finally" '
|
|
jpayne@68
|
13568 'usage\n'
|
|
jpayne@68
|
13569 'patterns to be encapsulated for convenient reuse.\n'
|
|
jpayne@68
|
13570 '\n'
|
|
jpayne@68
|
13571 ' with_stmt ::= "with" with_item ("," with_item)* ":" suite\n'
|
|
jpayne@68
|
13572 ' with_item ::= expression ["as" target]\n'
|
|
jpayne@68
|
13573 '\n'
|
|
jpayne@68
|
13574 'The execution of the "with" statement with one “item” proceeds as\n'
|
|
jpayne@68
|
13575 'follows:\n'
|
|
jpayne@68
|
13576 '\n'
|
|
jpayne@68
|
13577 '1. The context expression (the expression given in the "with_item")\n'
|
|
jpayne@68
|
13578 ' is evaluated to obtain a context manager.\n'
|
|
jpayne@68
|
13579 '\n'
|
|
jpayne@68
|
13580 '2. The context manager’s "__exit__()" is loaded for later use.\n'
|
|
jpayne@68
|
13581 '\n'
|
|
jpayne@68
|
13582 '3. The context manager’s "__enter__()" method is invoked.\n'
|
|
jpayne@68
|
13583 '\n'
|
|
jpayne@68
|
13584 '4. If a target was included in the "with" statement, the return\n'
|
|
jpayne@68
|
13585 ' value from "__enter__()" is assigned to it.\n'
|
|
jpayne@68
|
13586 '\n'
|
|
jpayne@68
|
13587 ' Note: The "with" statement guarantees that if the "__enter__()"\n'
|
|
jpayne@68
|
13588 ' method returns without an error, then "__exit__()" will always '
|
|
jpayne@68
|
13589 'be\n'
|
|
jpayne@68
|
13590 ' called. Thus, if an error occurs during the assignment to the\n'
|
|
jpayne@68
|
13591 ' target list, it will be treated the same as an error occurring\n'
|
|
jpayne@68
|
13592 ' within the suite would be. See step 6 below.\n'
|
|
jpayne@68
|
13593 '\n'
|
|
jpayne@68
|
13594 '5. The suite is executed.\n'
|
|
jpayne@68
|
13595 '\n'
|
|
jpayne@68
|
13596 '6. The context manager’s "__exit__()" method is invoked. If an\n'
|
|
jpayne@68
|
13597 ' exception caused the suite to be exited, its type, value, and\n'
|
|
jpayne@68
|
13598 ' traceback are passed as arguments to "__exit__()". Otherwise, '
|
|
jpayne@68
|
13599 'three\n'
|
|
jpayne@68
|
13600 ' "None" arguments are supplied.\n'
|
|
jpayne@68
|
13601 '\n'
|
|
jpayne@68
|
13602 ' If the suite was exited due to an exception, and the return '
|
|
jpayne@68
|
13603 'value\n'
|
|
jpayne@68
|
13604 ' from the "__exit__()" method was false, the exception is '
|
|
jpayne@68
|
13605 'reraised.\n'
|
|
jpayne@68
|
13606 ' If the return value was true, the exception is suppressed, and\n'
|
|
jpayne@68
|
13607 ' execution continues with the statement following the "with"\n'
|
|
jpayne@68
|
13608 ' statement.\n'
|
|
jpayne@68
|
13609 '\n'
|
|
jpayne@68
|
13610 ' If the suite was exited for any reason other than an exception, '
|
|
jpayne@68
|
13611 'the\n'
|
|
jpayne@68
|
13612 ' return value from "__exit__()" is ignored, and execution '
|
|
jpayne@68
|
13613 'proceeds\n'
|
|
jpayne@68
|
13614 ' at the normal location for the kind of exit that was taken.\n'
|
|
jpayne@68
|
13615 '\n'
|
|
jpayne@68
|
13616 'With more than one item, the context managers are processed as if\n'
|
|
jpayne@68
|
13617 'multiple "with" statements were nested:\n'
|
|
jpayne@68
|
13618 '\n'
|
|
jpayne@68
|
13619 ' with A() as a, B() as b:\n'
|
|
jpayne@68
|
13620 ' suite\n'
|
|
jpayne@68
|
13621 '\n'
|
|
jpayne@68
|
13622 'is equivalent to\n'
|
|
jpayne@68
|
13623 '\n'
|
|
jpayne@68
|
13624 ' with A() as a:\n'
|
|
jpayne@68
|
13625 ' with B() as b:\n'
|
|
jpayne@68
|
13626 ' suite\n'
|
|
jpayne@68
|
13627 '\n'
|
|
jpayne@68
|
13628 'Changed in version 3.1: Support for multiple context expressions.\n'
|
|
jpayne@68
|
13629 '\n'
|
|
jpayne@68
|
13630 'See also:\n'
|
|
jpayne@68
|
13631 '\n'
|
|
jpayne@68
|
13632 ' **PEP 343** - The “with” statement\n'
|
|
jpayne@68
|
13633 ' The specification, background, and examples for the Python '
|
|
jpayne@68
|
13634 '"with"\n'
|
|
jpayne@68
|
13635 ' statement.\n',
|
|
jpayne@68
|
13636 'yield': 'The "yield" statement\n'
|
|
jpayne@68
|
13637 '*********************\n'
|
|
jpayne@68
|
13638 '\n'
|
|
jpayne@68
|
13639 ' yield_stmt ::= yield_expression\n'
|
|
jpayne@68
|
13640 '\n'
|
|
jpayne@68
|
13641 'A "yield" statement is semantically equivalent to a yield '
|
|
jpayne@68
|
13642 'expression.\n'
|
|
jpayne@68
|
13643 'The yield statement can be used to omit the parentheses that would\n'
|
|
jpayne@68
|
13644 'otherwise be required in the equivalent yield expression '
|
|
jpayne@68
|
13645 'statement.\n'
|
|
jpayne@68
|
13646 'For example, the yield statements\n'
|
|
jpayne@68
|
13647 '\n'
|
|
jpayne@68
|
13648 ' yield <expr>\n'
|
|
jpayne@68
|
13649 ' yield from <expr>\n'
|
|
jpayne@68
|
13650 '\n'
|
|
jpayne@68
|
13651 'are equivalent to the yield expression statements\n'
|
|
jpayne@68
|
13652 '\n'
|
|
jpayne@68
|
13653 ' (yield <expr>)\n'
|
|
jpayne@68
|
13654 ' (yield from <expr>)\n'
|
|
jpayne@68
|
13655 '\n'
|
|
jpayne@68
|
13656 'Yield expressions and statements are only used when defining a\n'
|
|
jpayne@68
|
13657 '*generator* function, and are only used in the body of the '
|
|
jpayne@68
|
13658 'generator\n'
|
|
jpayne@68
|
13659 'function. Using yield in a function definition is sufficient to '
|
|
jpayne@68
|
13660 'cause\n'
|
|
jpayne@68
|
13661 'that definition to create a generator function instead of a normal\n'
|
|
jpayne@68
|
13662 'function.\n'
|
|
jpayne@68
|
13663 '\n'
|
|
jpayne@68
|
13664 'For full details of "yield" semantics, refer to the Yield '
|
|
jpayne@68
|
13665 'expressions\n'
|
|
jpayne@68
|
13666 'section.\n'}
|
