Python code coverage: Lib/pydoc

#	count	content
1	n/a	# -- coding: utf-8 --
2	n/a	# Autogenerated by Sphinx on Mon Sep 12 10:47:11 2016
3	n/a	topics = {'assert': '\n'
4	n/a	'The "assert" statement\n'
5	n/a	'**********************\n'
6	n/a	'\n'
7	n/a	'Assert statements are a convenient way to insert debugging '
8	n/a	'assertions\n'
9	n/a	'into a program:\n'
10	n/a	'\n'
11	n/a	' assert_stmt ::= "assert" expression ["," expression]\n'
12	n/a	'\n'
13	n/a	'The simple form, "assert expression", is equivalent to\n'
14	n/a	'\n'
15	n/a	' if __debug__:\n'
16	n/a	' if not expression: raise AssertionError\n'
17	n/a	'\n'
18	n/a	'The extended form, "assert expression1, expression2", is '
19	n/a	'equivalent to\n'
20	n/a	'\n'
21	n/a	' if __debug__:\n'
22	n/a	' if not expression1: raise AssertionError(expression2)\n'
23	n/a	'\n'
24	n/a	'These equivalences assume that "__debug__" and "AssertionError" '
25	n/a	'refer\n'
26	n/a	'to the built-in variables with those names. In the current\n'
27	n/a	'implementation, the built-in variable "__debug__" is "True" under\n'
28	n/a	'normal circumstances, "False" when optimization is requested '
29	n/a	'(command\n'
30	n/a	'line option -O). The current code generator emits no code for an\n'
31	n/a	'assert statement when optimization is requested at compile time. '
32	n/a	'Note\n'
33	n/a	'that it is unnecessary to include the source code for the '
34	n/a	'expression\n'
35	n/a	'that failed in the error message; it will be displayed as part of '
36	n/a	'the\n'
37	n/a	'stack trace.\n'
38	n/a	'\n'
39	n/a	'Assignments to "__debug__" are illegal. The value for the '
40	n/a	'built-in\n'
41	n/a	'variable is determined when the interpreter starts.\n',
42	n/a	'assignment': '\n'
43	n/a	'Assignment statements\n'
44	n/a	'*********************\n'
45	n/a	'\n'
46	n/a	'Assignment statements are used to (re)bind names to values and '
47	n/a	'to\n'
48	n/a	'modify attributes or items of mutable objects:\n'
49	n/a	'\n'
50	n/a	' assignment_stmt ::= (target_list "=")+ (starred_expression '
51	n/a	'\| yield_expression)\n'
52	n/a	' target_list ::= target ("," target)* [","]\n'
53	n/a	' target ::= identifier\n'
54	n/a	' \| "(" [target_list] ")"\n'
55	n/a	' \| "[" [target_list] "]"\n'
56	n/a	' \| attributeref\n'
57	n/a	' \| subscription\n'
58	n/a	' \| slicing\n'
59	n/a	' \| "*" target\n'
60	n/a	'\n'
61	n/a	'(See section Primaries for the syntax definitions for '
62	n/a	'attributeref,\n'
63	n/a	'subscription, and slicing.)\n'
64	n/a	'\n'
65	n/a	'An assignment statement evaluates the expression list '
66	n/a	'(remember that\n'
67	n/a	'this can be a single expression or a comma-separated list, the '
68	n/a	'latter\n'
69	n/a	'yielding a tuple) and assigns the single resulting object to '
70	n/a	'each of\n'
71	n/a	'the target lists, from left to right.\n'
72	n/a	'\n'
73	n/a	'Assignment is defined recursively depending on the form of the '
74	n/a	'target\n'
75	n/a	'(list). When a target is part of a mutable object (an '
76	n/a	'attribute\n'
77	n/a	'reference, subscription or slicing), the mutable object must\n'
78	n/a	'ultimately perform the assignment and decide about its '
79	n/a	'validity, and\n'
80	n/a	'may raise an exception if the assignment is unacceptable. The '
81	n/a	'rules\n'
82	n/a	'observed by various types and the exceptions raised are given '
83	n/a	'with the\n'
84	n/a	'definition of the object types (see section The standard type\n'
85	n/a	'hierarchy).\n'
86	n/a	'\n'
87	n/a	'Assignment of an object to a target list, optionally enclosed '
88	n/a	'in\n'
89	n/a	'parentheses or square brackets, is recursively defined as '
90	n/a	'follows.\n'
91	n/a	'\n'
92	n/a	'* If the target list is empty: The object must also be an '
93	n/a	'empty\n'
94	n/a	' iterable.\n'
95	n/a	'\n'
96	n/a	'* If the target list is a single target in parentheses: The '
97	n/a	'object\n'
98	n/a	' is assigned to that target.\n'
99	n/a	'\n'
100	n/a	'* If the target list is a comma-separated list of targets, or '
101	n/a	'a\n'
102	n/a	' single target in square brackets: The object must be an '
103	n/a	'iterable\n'
104	n/a	' with the same number of items as there are targets in the '
105	n/a	'target\n'
106	n/a	' list, and the items are assigned, from left to right, to '
107	n/a	'the\n'
108	n/a	' corresponding targets.\n'
109	n/a	'\n'
110	n/a	' * If the target list contains one target prefixed with an\n'
111	n/a	' asterisk, called a "starred" target: The object must be '
112	n/a	'an\n'
113	n/a	' iterable with at least as many items as there are targets '
114	n/a	'in the\n'
115	n/a	' target list, minus one. The first items of the iterable '
116	n/a	'are\n'
117	n/a	' assigned, from left to right, to the targets before the '
118	n/a	'starred\n'
119	n/a	' target. The final items of the iterable are assigned to '
120	n/a	'the\n'
121	n/a	' targets after the starred target. A list of the remaining '
122	n/a	'items\n'
123	n/a	' in the iterable is then assigned to the starred target '
124	n/a	'(the list\n'
125	n/a	' can be empty).\n'
126	n/a	'\n'
127	n/a	' * Else: The object must be an iterable with the same number '
128	n/a	'of\n'
129	n/a	' items as there are targets in the target list, and the '
130	n/a	'items are\n'
131	n/a	' assigned, from left to right, to the corresponding '
132	n/a	'targets.\n'
133	n/a	'\n'
134	n/a	'Assignment of an object to a single target is recursively '
135	n/a	'defined as\n'
136	n/a	'follows.\n'
137	n/a	'\n'
138	n/a	'* If the target is an identifier (name):\n'
139	n/a	'\n'
140	n/a	' * If the name does not occur in a "global" or "nonlocal" '
141	n/a	'statement\n'
142	n/a	' in the current code block: the name is bound to the object '
143	n/a	'in the\n'
144	n/a	' current local namespace.\n'
145	n/a	'\n'
146	n/a	' * Otherwise: the name is bound to the object in the global\n'
147	n/a	' namespace or the outer namespace determined by '
148	n/a	'"nonlocal",\n'
149	n/a	' respectively.\n'
150	n/a	'\n'
151	n/a	' The name is rebound if it was already bound. This may cause '
152	n/a	'the\n'
153	n/a	' reference count for the object previously bound to the name '
154	n/a	'to reach\n'
155	n/a	' zero, causing the object to be deallocated and its '
156	n/a	'destructor (if it\n'
157	n/a	' has one) to be called.\n'
158	n/a	'\n'
159	n/a	'* If the target is an attribute reference: The primary '
160	n/a	'expression in\n'
161	n/a	' the reference is evaluated. It should yield an object with\n'
162	n/a	' assignable attributes; if this is not the case, "TypeError" '
163	n/a	'is\n'
164	n/a	' raised. That object is then asked to assign the assigned '
165	n/a	'object to\n'
166	n/a	' the given attribute; if it cannot perform the assignment, it '
167	n/a	'raises\n'
168	n/a	' an exception (usually but not necessarily '
169	n/a	'"AttributeError").\n'
170	n/a	'\n'
171	n/a	' Note: If the object is a class instance and the attribute '
172	n/a	'reference\n'
173	n/a	' occurs on both sides of the assignment operator, the RHS '
174	n/a	'expression,\n'
175	n/a	' "a.x" can access either an instance attribute or (if no '
176	n/a	'instance\n'
177	n/a	' attribute exists) a class attribute. The LHS target "a.x" '
178	n/a	'is always\n'
179	n/a	' set as an instance attribute, creating it if necessary. '
180	n/a	'Thus, the\n'
181	n/a	' two occurrences of "a.x" do not necessarily refer to the '
182	n/a	'same\n'
183	n/a	' attribute: if the RHS expression refers to a class '
184	n/a	'attribute, the\n'
185	n/a	' LHS creates a new instance attribute as the target of the\n'
186	n/a	' assignment:\n'
187	n/a	'\n'
188	n/a	' class Cls:\n'
189	n/a	' x = 3 # class variable\n'
190	n/a	' inst = Cls()\n'
191	n/a	' inst.x = inst.x + 1 # writes inst.x as 4 leaving Cls.x '
192	n/a	'as 3\n'
193	n/a	'\n'
194	n/a	' This description does not necessarily apply to descriptor\n'
195	n/a	' attributes, such as properties created with "property()".\n'
196	n/a	'\n'
197	n/a	'* If the target is a subscription: The primary expression in '
198	n/a	'the\n'
199	n/a	' reference is evaluated. It should yield either a mutable '
200	n/a	'sequence\n'
201	n/a	' object (such as a list) or a mapping object (such as a '
202	n/a	'dictionary).\n'
203	n/a	' Next, the subscript expression is evaluated.\n'
204	n/a	'\n'
205	n/a	' If the primary is a mutable sequence object (such as a '
206	n/a	'list), the\n'
207	n/a	' subscript must yield an integer. If it is negative, the '
208	n/a	"sequence's\n"
209	n/a	' length is added to it. The resulting value must be a '
210	n/a	'nonnegative\n'
211	n/a	" integer less than the sequence's length, and the sequence is "
212	n/a	'asked\n'
213	n/a	' to assign the assigned object to its item with that index. '
214	n/a	'If the\n'
215	n/a	' index is out of range, "IndexError" is raised (assignment to '
216	n/a	'a\n'
217	n/a	' subscripted sequence cannot add new items to a list).\n'
218	n/a	'\n'
219	n/a	' If the primary is a mapping object (such as a dictionary), '
220	n/a	'the\n'
221	n/a	" subscript must have a type compatible with the mapping's key "
222	n/a	'type,\n'
223	n/a	' and the mapping is then asked to create a key/datum pair '
224	n/a	'which maps\n'
225	n/a	' the subscript to the assigned object. This can either '
226	n/a	'replace an\n'
227	n/a	' existing key/value pair with the same key value, or insert a '
228	n/a	'new\n'
229	n/a	' key/value pair (if no key with the same value existed).\n'
230	n/a	'\n'
231	n/a	' For user-defined objects, the "__setitem__()" method is '
232	n/a	'called with\n'
233	n/a	' appropriate arguments.\n'
234	n/a	'\n'
235	n/a	'* If the target is a slicing: The primary expression in the\n'
236	n/a	' reference is evaluated. It should yield a mutable sequence '
237	n/a	'object\n'
238	n/a	' (such as a list). The assigned object should be a sequence '
239	n/a	'object\n'
240	n/a	' of the same type. Next, the lower and upper bound '
241	n/a	'expressions are\n'
242	n/a	' evaluated, insofar they are present; defaults are zero and '
243	n/a	'the\n'
244	n/a	" sequence's length. The bounds should evaluate to integers. "
245	n/a	'If\n'
246	n/a	" either bound is negative, the sequence's length is added to "
247	n/a	'it. The\n'
248	n/a	' resulting bounds are clipped to lie between zero and the '
249	n/a	"sequence's\n"
250	n/a	' length, inclusive. Finally, the sequence object is asked to '
251	n/a	'replace\n'
252	n/a	' the slice with the items of the assigned sequence. The '
253	n/a	'length of\n'
254	n/a	' the slice may be different from the length of the assigned '
255	n/a	'sequence,\n'
256	n/a	' thus changing the length of the target sequence, if the '
257	n/a	'target\n'
258	n/a	' sequence allows it.\n'
259	n/a	'\n'
260	n/a	'CPython implementation detail: In the current '
261	n/a	'implementation, the\n'
262	n/a	'syntax for targets is taken to be the same as for expressions, '
263	n/a	'and\n'
264	n/a	'invalid syntax is rejected during the code generation phase, '
265	n/a	'causing\n'
266	n/a	'less detailed error messages.\n'
267	n/a	'\n'
268	n/a	'Although the definition of assignment implies that overlaps '
269	n/a	'between\n'
270	n/a	"the left-hand side and the right-hand side are 'simultaneous' "
271	n/a	'(for\n'
272	n/a	'example "a, b = b, a" swaps two variables), overlaps within '
273	n/a	'the\n'
274	n/a	'collection of assigned-to variables occur left-to-right, '
275	n/a	'sometimes\n'
276	n/a	'resulting in confusion. For instance, the following program '
277	n/a	'prints\n'
278	n/a	'"[0, 2]":\n'
279	n/a	'\n'
280	n/a	' x = [0, 1]\n'
281	n/a	' i = 0\n'
282	n/a	' i, x[i] = 1, 2 # i is updated, then x[i] is '
283	n/a	'updated\n'
284	n/a	' print(x)\n'
285	n/a	'\n'
286	n/a	'See also:\n'
287	n/a	'\n'
288	n/a	' PEP 3132 - Extended Iterable Unpacking\n'
289	n/a	' The specification for the "*target" feature.\n'
290	n/a	'\n'
291	n/a	'\n'
292	n/a	'Augmented assignment statements\n'
293	n/a	'===============================\n'
294	n/a	'\n'
295	n/a	'Augmented assignment is the combination, in a single '
296	n/a	'statement, of a\n'
297	n/a	'binary operation and an assignment statement:\n'
298	n/a	'\n'
299	n/a	' augmented_assignment_stmt ::= augtarget augop '
300	n/a	'(expression_list \| yield_expression)\n'
301	n/a	' augtarget ::= identifier \| attributeref \| '
302	n/a	'subscription \| slicing\n'
303	n/a	' augop ::= "+=" \| "-=" \| "*=" \| "@=" \| '
304	n/a	'"/=" \| "//=" \| "%=" \| "**="\n'
305	n/a	' \| ">>=" \| "<<=" \| "&=" \| "^=" \| "\|="\n'
306	n/a	'\n'
307	n/a	'(See section Primaries for the syntax definitions of the last '
308	n/a	'three\n'
309	n/a	'symbols.)\n'
310	n/a	'\n'
311	n/a	'An augmented assignment evaluates the target (which, unlike '
312	n/a	'normal\n'
313	n/a	'assignment statements, cannot be an unpacking) and the '
314	n/a	'expression\n'
315	n/a	'list, performs the binary operation specific to the type of '
316	n/a	'assignment\n'
317	n/a	'on the two operands, and assigns the result to the original '
318	n/a	'target.\n'
319	n/a	'The target is only evaluated once.\n'
320	n/a	'\n'
321	n/a	'An augmented assignment expression like "x += 1" can be '
322	n/a	'rewritten as\n'
323	n/a	'"x = x + 1" to achieve a similar, but not exactly equal '
324	n/a	'effect. In the\n'
325	n/a	'augmented version, "x" is only evaluated once. Also, when '
326	n/a	'possible,\n'
327	n/a	'the actual operation is performed in-place, meaning that '
328	n/a	'rather than\n'
329	n/a	'creating a new object and assigning that to the target, the '
330	n/a	'old object\n'
331	n/a	'is modified instead.\n'
332	n/a	'\n'
333	n/a	'Unlike normal assignments, augmented assignments evaluate the '
334	n/a	'left-\n'
335	n/a	'hand side before evaluating the right-hand side. For '
336	n/a	'example, "a[i]\n'
337	n/a	'+= f(x)" first looks-up "a[i]", then it evaluates "f(x)" and '
338	n/a	'performs\n'
339	n/a	'the addition, and lastly, it writes the result back to '
340	n/a	'"a[i]".\n'
341	n/a	'\n'
342	n/a	'With the exception of assigning to tuples and multiple targets '
343	n/a	'in a\n'
344	n/a	'single statement, the assignment done by augmented assignment\n'
345	n/a	'statements is handled the same way as normal assignments. '
346	n/a	'Similarly,\n'
347	n/a	'with the exception of the possible in-place behavior, the '
348	n/a	'binary\n'
349	n/a	'operation performed by augmented assignment is the same as the '
350	n/a	'normal\n'
351	n/a	'binary operations.\n'
352	n/a	'\n'
353	n/a	'For targets which are attribute references, the same caveat '
354	n/a	'about\n'
355	n/a	'class and instance attributes applies as for regular '
356	n/a	'assignments.\n'
357	n/a	'\n'
358	n/a	'\n'
359	n/a	'Annotated assignment statements\n'
360	n/a	'===============================\n'
361	n/a	'\n'
362	n/a	'Annotation assignment is the combination, in a single '
363	n/a	'statement, of a\n'
364	n/a	'variable or attribute annotation and an optional assignment '
365	n/a	'statement:\n'
366	n/a	'\n'
367	n/a	' annotated_assignment_stmt ::= augtarget ":" expression ["=" '
368	n/a	'expression]\n'
369	n/a	'\n'
370	n/a	'The difference from normal Assignment statements is that only '
371	n/a	'single\n'
372	n/a	'target and only single right hand side value is allowed.\n'
373	n/a	'\n'
374	n/a	'For simple names as assignment targets, if in class or module '
375	n/a	'scope,\n'
376	n/a	'the annotations are evaluated and stored in a special class or '
377	n/a	'module\n'
378	n/a	'attribute "__annotations__" that is a dictionary mapping from '
379	n/a	'variable\n'
380	n/a	'names (mangled if private) to evaluated annotations. This '
381	n/a	'attribute is\n'
382	n/a	'writable and is automatically created at the start of class or '
383	n/a	'module\n'
384	n/a	'body execution, if annotations are found statically.\n'
385	n/a	'\n'
386	n/a	'For expressions as assignment targets, the annotations are '
387	n/a	'evaluated\n'
388	n/a	'if in class or module scope, but not stored.\n'
389	n/a	'\n'
390	n/a	'If a name is annotated in a function scope, then this name is '
391	n/a	'local\n'
392	n/a	'for that scope. Annotations are never evaluated and stored in '
393	n/a	'function\n'
394	n/a	'scopes.\n'
395	n/a	'\n'
396	n/a	'If the right hand side is present, an annotated assignment '
397	n/a	'performs\n'
398	n/a	'the actual assignment before evaluating annotations (where\n'
399	n/a	'applicable). If the right hand side is not present for an '
400	n/a	'expression\n'
401	n/a	'target, then the interpreter evaluates the target except for '
402	n/a	'the last\n'
403	n/a	'"__setitem__()" or "__setattr__()" call.\n'
404	n/a	'\n'
405	n/a	'See also: PEP 526 - Variable and attribute annotation '
406	n/a	'syntax\n'
407	n/a	' PEP 484 - Type hints\n',
408	n/a	'atom-identifiers': '\n'
409	n/a	'Identifiers (Names)\n'
410	n/a	'*******************\n'
411	n/a	'\n'
412	n/a	'An identifier occurring as an atom is a name. See '
413	n/a	'section Identifiers\n'
414	n/a	'and keywords for lexical definition and section Naming '
415	n/a	'and binding for\n'
416	n/a	'documentation of naming and binding.\n'
417	n/a	'\n'
418	n/a	'When the name is bound to an object, evaluation of the '
419	n/a	'atom yields\n'
420	n/a	'that object. When a name is not bound, an attempt to '
421	n/a	'evaluate it\n'
422	n/a	'raises a "NameError" exception.\n'
423	n/a	'\n'
424	n/a	'Private name mangling: When an identifier that '
425	n/a	'textually occurs in\n'
426	n/a	'a class definition begins with two or more underscore '
427	n/a	'characters and\n'
428	n/a	'does not end in two or more underscores, it is '
429	n/a	'considered a *private\n'
430	n/a	'name* of that class. Private names are transformed to a '
431	n/a	'longer form\n'
432	n/a	'before code is generated for them. The transformation '
433	n/a	'inserts the\n'
434	n/a	'class name, with leading underscores removed and a '
435	n/a	'single underscore\n'
436	n/a	'inserted, in front of the name. For example, the '
437	n/a	'identifier "__spam"\n'
438	n/a	'occurring in a class named "Ham" will be transformed to '
439	n/a	'"_Ham__spam".\n'
440	n/a	'This transformation is independent of the syntactical '
441	n/a	'context in which\n'
442	n/a	'the identifier is used. If the transformed name is '
443	n/a	'extremely long\n'
444	n/a	'(longer than 255 characters), implementation defined '
445	n/a	'truncation may\n'
446	n/a	'happen. If the class name consists only of underscores, '
447	n/a	'no\n'
448	n/a	'transformation is done.\n',
449	n/a	'atom-literals': '\n'
450	n/a	'Literals\n'
451	n/a	'********\n'
452	n/a	'\n'
453	n/a	'Python supports string and bytes literals and various '
454	n/a	'numeric\n'
455	n/a	'literals:\n'
456	n/a	'\n'
457	n/a	' literal ::= stringliteral \| bytesliteral\n'
458	n/a	' \| integer \| floatnumber \| imagnumber\n'
459	n/a	'\n'
460	n/a	'Evaluation of a literal yields an object of the given type '
461	n/a	'(string,\n'
462	n/a	'bytes, integer, floating point number, complex number) with '
463	n/a	'the given\n'
464	n/a	'value. The value may be approximated in the case of '
465	n/a	'floating point\n'
466	n/a	'and imaginary (complex) literals. See section Literals for '
467	n/a	'details.\n'
468	n/a	'\n'
469	n/a	'All literals correspond to immutable data types, and hence '
470	n/a	'the\n'
471	n/a	"object's identity is less important than its value. "
472	n/a	'Multiple\n'
473	n/a	'evaluations of literals with the same value (either the '
474	n/a	'same\n'
475	n/a	'occurrence in the program text or a different occurrence) '
476	n/a	'may obtain\n'
477	n/a	'the same object or a different object with the same '
478	n/a	'value.\n',
479	n/a	'attribute-access': '\n'
480	n/a	'Customizing attribute access\n'
481	n/a	'****************************\n'
482	n/a	'\n'
483	n/a	'The following methods can be defined to customize the '
484	n/a	'meaning of\n'
485	n/a	'attribute access (use of, assignment to, or deletion of '
486	n/a	'"x.name") for\n'
487	n/a	'class instances.\n'
488	n/a	'\n'
489	n/a	'object.__getattr__(self, name)\n'
490	n/a	'\n'
491	n/a	' Called when an attribute lookup has not found the '
492	n/a	'attribute in the\n'
493	n/a	' usual places (i.e. it is not an instance attribute '
494	n/a	'nor is it found\n'
495	n/a	' in the class tree for "self"). "name" is the '
496	n/a	'attribute name. This\n'
497	n/a	' method should return the (computed) attribute value '
498	n/a	'or raise an\n'
499	n/a	' "AttributeError" exception.\n'
500	n/a	'\n'

1

n/a

# -*- coding: utf-8 -*-

2

n/a

# Autogenerated by Sphinx on Mon Sep 12 10:47:11 2016

3

n/a

topics = {'assert': '\n'

4

n/a

'The "assert" statement\n'

5

n/a

'**********************\n'

6

n/a

'\n'

7

n/a

'Assert statements are a convenient way to insert debugging '

8

n/a

'assertions\n'

9

n/a

'into a program:\n'

10

n/a

'\n'

11

n/a

' assert_stmt ::= "assert" expression ["," expression]\n'

12

n/a

'\n'

13

n/a

'The simple form, "assert expression", is equivalent to\n'

14

n/a

'\n'

15

n/a

' if __debug__:\n'

16

n/a

' if not expression: raise AssertionError\n'

17

n/a

'\n'

18

n/a

'The extended form, "assert expression1, expression2", is '

19

n/a

'equivalent to\n'

20

n/a

'\n'

21

n/a

' if __debug__:\n'

22

n/a

' if not expression1: raise AssertionError(expression2)\n'

23

n/a

'\n'

24

n/a

'These equivalences assume that "__debug__" and "AssertionError" '

25

n/a

'refer\n'

26

n/a

'to the built-in variables with those names. In the current\n'

27

n/a

'implementation, the built-in variable "__debug__" is "True" under\n'

28

n/a

'normal circumstances, "False" when optimization is requested '

29

n/a

'(command\n'

30

n/a

'line option -O). The current code generator emits no code for an\n'

31

n/a

'assert statement when optimization is requested at compile time. '

32

n/a

'Note\n'

33

n/a

'that it is unnecessary to include the source code for the '

34

n/a

'expression\n'

35

n/a

'that failed in the error message; it will be displayed as part of '

36

n/a

'the\n'

37

n/a

'stack trace.\n'

38

n/a

'\n'

39

n/a

'Assignments to "__debug__" are illegal. The value for the '

40

n/a

'built-in\n'

41

n/a

'variable is determined when the interpreter starts.\n',

42

n/a

'assignment': '\n'

43

n/a

'Assignment statements\n'

44

n/a

'*********************\n'

45

n/a

'\n'

46

n/a

'Assignment statements are used to (re)bind names to values and '

47

n/a

'to\n'

48

n/a

'modify attributes or items of mutable objects:\n'

49

n/a

'\n'

50

n/a

' assignment_stmt ::= (target_list "=")+ (starred_expression '

51

n/a

'| yield_expression)\n'

52

n/a

' target_list ::= target ("," target)* [","]\n'

53

n/a

' target ::= identifier\n'

54

n/a

' | "(" [target_list] ")"\n'

55

n/a

' | "[" [target_list] "]"\n'

56

n/a

' | attributeref\n'

57

n/a

' | subscription\n'

58

n/a

' | slicing\n'

59

n/a

' | "*" target\n'

60

n/a

'\n'

61

n/a

'(See section Primaries for the syntax definitions for '

62

n/a

'*attributeref*,\n'

63

n/a

'*subscription*, and *slicing*.)\n'

64

n/a

'\n'

65

n/a

'An assignment statement evaluates the expression list '

66

n/a

'(remember that\n'

67

n/a

'this can be a single expression or a comma-separated list, the '

68

n/a

'latter\n'

69

n/a

'yielding a tuple) and assigns the single resulting object to '

70

n/a

'each of\n'

71

n/a

'the target lists, from left to right.\n'

72

n/a

'\n'

73

n/a

'Assignment is defined recursively depending on the form of the '

74

n/a

'target\n'

75

n/a

'(list). When a target is part of a mutable object (an '

76

n/a

'attribute\n'

77

n/a

'reference, subscription or slicing), the mutable object must\n'

78

n/a

'ultimately perform the assignment and decide about its '

79

n/a

'validity, and\n'

80

n/a

'may raise an exception if the assignment is unacceptable. The '

81

n/a

'rules\n'

82

n/a

'observed by various types and the exceptions raised are given '

83

n/a

'with the\n'

84

n/a

'definition of the object types (see section The standard type\n'

85

n/a

'hierarchy).\n'

86

n/a

'\n'

87

n/a

'Assignment of an object to a target list, optionally enclosed '

88

n/a

'in\n'

89

n/a

'parentheses or square brackets, is recursively defined as '

90

n/a

'follows.\n'

91

n/a

'\n'

92

n/a

'* If the target list is empty: The object must also be an '

93

n/a

'empty\n'

94

n/a

' iterable.\n'

95

n/a

'\n'

96

n/a

'* If the target list is a single target in parentheses: The '

97

n/a

'object\n'

98

n/a

' is assigned to that target.\n'

99

n/a

'\n'

100

n/a

'* If the target list is a comma-separated list of targets, or '

101

n/a

'a\n'

102

n/a

' single target in square brackets: The object must be an '

103

n/a

'iterable\n'

104

n/a

' with the same number of items as there are targets in the '

105

n/a

'target\n'

106

n/a

' list, and the items are assigned, from left to right, to '

107

n/a

'the\n'

108

n/a

' corresponding targets.\n'

109

n/a

'\n'

110

n/a

' * If the target list contains one target prefixed with an\n'

111

n/a

' asterisk, called a "starred" target: The object must be '

112

n/a

'an\n'

113

n/a

' iterable with at least as many items as there are targets '

114

n/a

'in the\n'

115

n/a

' target list, minus one. The first items of the iterable '

116

n/a

'are\n'

117

n/a

' assigned, from left to right, to the targets before the '

118

n/a

'starred\n'

119

n/a

' target. The final items of the iterable are assigned to '

120

n/a

'the\n'

121

n/a

' targets after the starred target. A list of the remaining '

122

n/a

'items\n'

123

n/a

' in the iterable is then assigned to the starred target '

124

n/a

'(the list\n'

125

n/a

' can be empty).\n'

126

n/a

'\n'

127

n/a

' * Else: The object must be an iterable with the same number '

128

n/a

'of\n'

129

n/a

' items as there are targets in the target list, and the '

130

n/a

'items are\n'

131

n/a

' assigned, from left to right, to the corresponding '

132

n/a

'targets.\n'

133

n/a

'\n'

134

n/a

'Assignment of an object to a single target is recursively '

135

n/a

'defined as\n'

136

n/a

'follows.\n'

137

n/a

'\n'

138

n/a

'* If the target is an identifier (name):\n'

139

n/a

'\n'

140

n/a

' * If the name does not occur in a "global" or "nonlocal" '

141

n/a

'statement\n'

142

n/a

' in the current code block: the name is bound to the object '

143

n/a

'in the\n'

144

n/a

' current local namespace.\n'

145

n/a

'\n'

146

n/a

' * Otherwise: the name is bound to the object in the global\n'

147

n/a

' namespace or the outer namespace determined by '

148

n/a

'"nonlocal",\n'

149

n/a

' respectively.\n'

150

n/a

'\n'

151

n/a

' The name is rebound if it was already bound. This may cause '

152

n/a

'the\n'

153

n/a

' reference count for the object previously bound to the name '

154

n/a

'to reach\n'

155

n/a

' zero, causing the object to be deallocated and its '

156

n/a

'destructor (if it\n'

157

n/a

' has one) to be called.\n'

158

n/a

'\n'

159

n/a

'* If the target is an attribute reference: The primary '

160

n/a

'expression in\n'

161

n/a

' the reference is evaluated. It should yield an object with\n'

162

n/a

' assignable attributes; if this is not the case, "TypeError" '

163

n/a

'is\n'

164

n/a

' raised. That object is then asked to assign the assigned '

165

n/a

'object to\n'

166

n/a

' the given attribute; if it cannot perform the assignment, it '

167

n/a

'raises\n'

168

n/a

' an exception (usually but not necessarily '

169

n/a

'"AttributeError").\n'

170

n/a

'\n'

171

n/a

' Note: If the object is a class instance and the attribute '

172

n/a

'reference\n'

173

n/a

' occurs on both sides of the assignment operator, the RHS '

174

n/a

'expression,\n'

175

n/a

' "a.x" can access either an instance attribute or (if no '

176

n/a

'instance\n'

177

n/a

' attribute exists) a class attribute. The LHS target "a.x" '

178

n/a

'is always\n'

179

n/a

' set as an instance attribute, creating it if necessary. '

180

n/a

'Thus, the\n'

181

n/a

' two occurrences of "a.x" do not necessarily refer to the '

182

n/a

'same\n'

183

n/a

' attribute: if the RHS expression refers to a class '

184

n/a

'attribute, the\n'

185

n/a

' LHS creates a new instance attribute as the target of the\n'

186

n/a

' assignment:\n'

187

n/a

'\n'

188

n/a

' class Cls:\n'

189

n/a

' x = 3 # class variable\n'

190

n/a

' inst = Cls()\n'

191

n/a

' inst.x = inst.x + 1 # writes inst.x as 4 leaving Cls.x '

192

n/a

'as 3\n'

193

n/a

'\n'

194

n/a

' This description does not necessarily apply to descriptor\n'

195

n/a

' attributes, such as properties created with "property()".\n'

196

n/a

'\n'

197

n/a

'* If the target is a subscription: The primary expression in '

198

n/a

'the\n'

199

n/a

' reference is evaluated. It should yield either a mutable '

200

n/a

'sequence\n'

201

n/a

' object (such as a list) or a mapping object (such as a '

202

n/a

'dictionary).\n'

203

n/a

' Next, the subscript expression is evaluated.\n'

204

n/a

'\n'

205

n/a

' If the primary is a mutable sequence object (such as a '

206

n/a

'list), the\n'

207

n/a

' subscript must yield an integer. If it is negative, the '

208

n/a

"sequence's\n"

209

n/a

' length is added to it. The resulting value must be a '

210

n/a

'nonnegative\n'

211

n/a

" integer less than the sequence's length, and the sequence is "

212

n/a

'asked\n'

213

n/a

' to assign the assigned object to its item with that index. '

214

n/a

'If the\n'

215

n/a

' index is out of range, "IndexError" is raised (assignment to '

216

n/a

'a\n'

217

n/a

' subscripted sequence cannot add new items to a list).\n'

218

n/a

'\n'

219

n/a

' If the primary is a mapping object (such as a dictionary), '

220

n/a

'the\n'

221

n/a

" subscript must have a type compatible with the mapping's key "

222

n/a

'type,\n'

223

n/a

' and the mapping is then asked to create a key/datum pair '

224

n/a

'which maps\n'

225

n/a

' the subscript to the assigned object. This can either '

226

n/a

'replace an\n'

227

n/a

' existing key/value pair with the same key value, or insert a '

228

n/a

'new\n'

229

n/a

' key/value pair (if no key with the same value existed).\n'

230

n/a

'\n'

231

n/a

' For user-defined objects, the "__setitem__()" method is '

232

n/a

'called with\n'

233

n/a

' appropriate arguments.\n'

234

n/a

'\n'

235

n/a

'* If the target is a slicing: The primary expression in the\n'

236

n/a

' reference is evaluated. It should yield a mutable sequence '

237

n/a

'object\n'

238

n/a

' (such as a list). The assigned object should be a sequence '

239

n/a

'object\n'

240

n/a

' of the same type. Next, the lower and upper bound '

241

n/a

'expressions are\n'

242

n/a

' evaluated, insofar they are present; defaults are zero and '

243

n/a

'the\n'

244

n/a

" sequence's length. The bounds should evaluate to integers. "

245

n/a

'If\n'

246

n/a

" either bound is negative, the sequence's length is added to "

247

n/a

'it. The\n'

248

n/a

' resulting bounds are clipped to lie between zero and the '

249

n/a

"sequence's\n"

250

n/a

' length, inclusive. Finally, the sequence object is asked to '

251

n/a

'replace\n'

252

n/a

' the slice with the items of the assigned sequence. The '

253

n/a

'length of\n'

254

n/a

' the slice may be different from the length of the assigned '

255

n/a

'sequence,\n'

256

n/a

' thus changing the length of the target sequence, if the '

257

n/a

'target\n'

258

n/a

' sequence allows it.\n'

259

n/a

'\n'

260

n/a

'**CPython implementation detail:** In the current '

261

n/a

'implementation, the\n'

262

n/a

'syntax for targets is taken to be the same as for expressions, '

263

n/a

'and\n'

264

n/a

'invalid syntax is rejected during the code generation phase, '

265

n/a

'causing\n'

266

n/a

'less detailed error messages.\n'

267

n/a

'\n'

268

n/a

'Although the definition of assignment implies that overlaps '

269

n/a

'between\n'

270

n/a

"the left-hand side and the right-hand side are 'simultaneous' "

271

n/a

'(for\n'

272

n/a

'example "a, b = b, a" swaps two variables), overlaps *within* '

273

n/a

'the\n'

274

n/a

'collection of assigned-to variables occur left-to-right, '

275

n/a

'sometimes\n'

276

n/a

'resulting in confusion. For instance, the following program '

277

n/a

'prints\n'

278

n/a

'"[0, 2]":\n'

279

n/a

'\n'

280

n/a

' x = [0, 1]\n'

281

n/a

' i = 0\n'

282

n/a

' i, x[i] = 1, 2 # i is updated, then x[i] is '

283

n/a

'updated\n'

284

n/a

' print(x)\n'

285

n/a

'\n'

286

n/a

'See also:\n'

287

n/a

'\n'

288

n/a

' **PEP 3132** - Extended Iterable Unpacking\n'

289

n/a

' The specification for the "*target" feature.\n'

290

n/a

'\n'

291

n/a

'\n'

292

n/a

'Augmented assignment statements\n'

293

n/a

'===============================\n'

294

n/a

'\n'

295

n/a

'Augmented assignment is the combination, in a single '

296

n/a

'statement, of a\n'

297

n/a

'binary operation and an assignment statement:\n'

298

n/a

'\n'

299

n/a

' augmented_assignment_stmt ::= augtarget augop '

300

n/a

'(expression_list | yield_expression)\n'

301

n/a

' augtarget ::= identifier | attributeref | '

302

n/a

'subscription | slicing\n'

303

n/a

' augop ::= "+=" | "-=" | "*=" | "@=" | '

304

n/a

'"/=" | "//=" | "%=" | "**="\n'

305

n/a

' | ">>=" | "<<=" | "&=" | "^=" | "|="\n'

306

n/a

'\n'

307

n/a

'(See section Primaries for the syntax definitions of the last '

308

n/a

'three\n'

309

n/a

'symbols.)\n'

310

n/a

'\n'

311

n/a

'An augmented assignment evaluates the target (which, unlike '

312

n/a

'normal\n'

313

n/a

'assignment statements, cannot be an unpacking) and the '

314

n/a

'expression\n'

315

n/a

'list, performs the binary operation specific to the type of '

316

n/a

'assignment\n'

317

n/a

'on the two operands, and assigns the result to the original '

318

n/a

'target.\n'

319

n/a

'The target is only evaluated once.\n'

320

n/a

'\n'

321

n/a

'An augmented assignment expression like "x += 1" can be '

322

n/a

'rewritten as\n'

323

n/a

'"x = x + 1" to achieve a similar, but not exactly equal '

324

n/a

'effect. In the\n'

325

n/a

'augmented version, "x" is only evaluated once. Also, when '

326

n/a

'possible,\n'

327

n/a

'the actual operation is performed *in-place*, meaning that '

328

n/a

'rather than\n'

329

n/a

'creating a new object and assigning that to the target, the '

330

n/a

'old object\n'

331

n/a

'is modified instead.\n'

332

n/a

'\n'

333

n/a

'Unlike normal assignments, augmented assignments evaluate the '

334

n/a

'left-\n'

335

n/a

'hand side *before* evaluating the right-hand side. For '

336

n/a

'example, "a[i]\n'

337

n/a

'+= f(x)" first looks-up "a[i]", then it evaluates "f(x)" and '

338

n/a

'performs\n'

339

n/a

'the addition, and lastly, it writes the result back to '

340

n/a

'"a[i]".\n'

341

n/a

'\n'

342

n/a

'With the exception of assigning to tuples and multiple targets '

343

n/a

'in a\n'

344

n/a

'single statement, the assignment done by augmented assignment\n'

345

n/a

'statements is handled the same way as normal assignments. '

346

n/a

'Similarly,\n'

347

n/a

'with the exception of the possible *in-place* behavior, the '

348

n/a

'binary\n'

349

n/a

'operation performed by augmented assignment is the same as the '

350

n/a

'normal\n'

351

n/a

'binary operations.\n'

352

n/a

'\n'

353

n/a

'For targets which are attribute references, the same caveat '

354

n/a

'about\n'

355

n/a

'class and instance attributes applies as for regular '

356

n/a

'assignments.\n'

357

n/a

'\n'

358

n/a

'\n'

359

n/a

'Annotated assignment statements\n'

360

n/a

'===============================\n'

361

n/a

'\n'

362

n/a

'Annotation assignment is the combination, in a single '

363

n/a

'statement, of a\n'

364

n/a

'variable or attribute annotation and an optional assignment '

365

n/a

'statement:\n'

366

n/a

'\n'

367

n/a

' annotated_assignment_stmt ::= augtarget ":" expression ["=" '

368

n/a

'expression]\n'

369

n/a

'\n'

370

n/a

'The difference from normal Assignment statements is that only '

371

n/a

'single\n'

372

n/a

'target and only single right hand side value is allowed.\n'

373

n/a

'\n'

374

n/a

'For simple names as assignment targets, if in class or module '

375

n/a

'scope,\n'

376

n/a

'the annotations are evaluated and stored in a special class or '

377

n/a

'module\n'

378

n/a

'attribute "__annotations__" that is a dictionary mapping from '

379

n/a

'variable\n'

380

n/a

'names (mangled if private) to evaluated annotations. This '

381

n/a

'attribute is\n'

382

n/a

'writable and is automatically created at the start of class or '

383

n/a

'module\n'

384

n/a

'body execution, if annotations are found statically.\n'

385

n/a

'\n'

386

n/a

'For expressions as assignment targets, the annotations are '

387

n/a

'evaluated\n'

388

n/a

'if in class or module scope, but not stored.\n'

389

n/a

'\n'

390

n/a

'If a name is annotated in a function scope, then this name is '

391

n/a

'local\n'

392

n/a

'for that scope. Annotations are never evaluated and stored in '

393

n/a

'function\n'

394

n/a

'scopes.\n'

395

n/a

'\n'

396

n/a

'If the right hand side is present, an annotated assignment '

397

n/a

'performs\n'

398

n/a

'the actual assignment before evaluating annotations (where\n'

399

n/a

'applicable). If the right hand side is not present for an '

400

n/a

'expression\n'

401

n/a

'target, then the interpreter evaluates the target except for '

402

n/a

'the last\n'

403

n/a

'"__setitem__()" or "__setattr__()" call.\n'

404

n/a

'\n'

405

n/a

'See also: **PEP 526** - Variable and attribute annotation '

406

n/a

'syntax\n'

407

n/a

' **PEP 484** - Type hints\n',

408

n/a

'atom-identifiers': '\n'

409

n/a

'Identifiers (Names)\n'

410

n/a

'*******************\n'

411

n/a

'\n'

412

n/a

'An identifier occurring as an atom is a name. See '

413

n/a

'section Identifiers\n'

414

n/a

'and keywords for lexical definition and section Naming '

415

n/a

'and binding for\n'

416

n/a

'documentation of naming and binding.\n'

417

n/a

'\n'

418

n/a

'When the name is bound to an object, evaluation of the '

419

n/a

'atom yields\n'

420

n/a

'that object. When a name is not bound, an attempt to '

421

n/a

'evaluate it\n'

422

n/a

'raises a "NameError" exception.\n'

423

n/a

'\n'

424

n/a

'**Private name mangling:** When an identifier that '

425

n/a

'textually occurs in\n'

426

n/a

'a class definition begins with two or more underscore '

427

n/a

'characters and\n'

428

n/a

'does not end in two or more underscores, it is '

429

n/a

'considered a *private\n'

430

n/a

'name* of that class. Private names are transformed to a '

431

n/a

'longer form\n'

432

n/a

'before code is generated for them. The transformation '

433

n/a

'inserts the\n'

434

n/a

'class name, with leading underscores removed and a '

435

n/a

'single underscore\n'

436

n/a

'inserted, in front of the name. For example, the '

437

n/a

'identifier "__spam"\n'

438

n/a

'occurring in a class named "Ham" will be transformed to '

439

n/a

'"_Ham__spam".\n'

440

n/a

'This transformation is independent of the syntactical '

441

n/a

'context in which\n'

442

n/a

'the identifier is used. If the transformed name is '

443

n/a

'extremely long\n'

444

n/a

'(longer than 255 characters), implementation defined '

445

n/a

'truncation may\n'

446

n/a

'happen. If the class name consists only of underscores, '

447

n/a

'no\n'

448

n/a

'transformation is done.\n',

449

n/a

'atom-literals': '\n'

450

n/a

'Literals\n'

451

n/a

'********\n'

452

n/a

'\n'

453

n/a

'Python supports string and bytes literals and various '

454

n/a

'numeric\n'

455

n/a

'literals:\n'

456

n/a

'\n'

457

n/a

' literal ::= stringliteral | bytesliteral\n'

458

n/a

' | integer | floatnumber | imagnumber\n'

459

n/a

'\n'

460

n/a

'Evaluation of a literal yields an object of the given type '

461

n/a

'(string,\n'

462

n/a

'bytes, integer, floating point number, complex number) with '

463

n/a

'the given\n'

464

n/a

'value. The value may be approximated in the case of '

465

n/a

'floating point\n'

466

n/a

'and imaginary (complex) literals. See section Literals for '

467

n/a

'details.\n'

468

n/a

'\n'

469

n/a

'All literals correspond to immutable data types, and hence '

470

n/a

'the\n'

471

n/a

"object's identity is less important than its value. "

472

n/a

'Multiple\n'

473

n/a

'evaluations of literals with the same value (either the '

474

n/a

'same\n'

475

n/a

'occurrence in the program text or a different occurrence) '

476

n/a

'may obtain\n'

477

n/a

'the same object or a different object with the same '

478

n/a

'value.\n',

479

n/a

'attribute-access': '\n'

480

n/a

'Customizing attribute access\n'

481

n/a

'****************************\n'

482

n/a

'\n'

483

n/a

'The following methods can be defined to customize the '

484

n/a

'meaning of\n'

485

n/a

'attribute access (use of, assignment to, or deletion of '

486

n/a

'"x.name") for\n'

487

n/a

'class instances.\n'

488

n/a

'\n'

489

n/a

'object.__getattr__(self, name)\n'

490

n/a

'\n'

491

n/a

' Called when an attribute lookup has not found the '

492

n/a

'attribute in the\n'

493

n/a

' usual places (i.e. it is not an instance attribute '

494

n/a

'nor is it found\n'

495

n/a

' in the class tree for "self"). "name" is the '

496

n/a

'attribute name. This\n'

497

n/a

' method should return the (computed) attribute value '

498

n/a

'or raise an\n'

499

n/a

' "AttributeError" exception.\n'

500

n/a

'\n'

501

n/a

' Note that if the attribute is found through the '

502

n/a

'normal mechanism,\n'

503

n/a

' "__getattr__()" is not called. (This is an '

504

n/a

'intentional asymmetry\n'

505

n/a

' between "__getattr__()" and "__setattr__()".) This is '

506

n/a

'done both for\n'

507

n/a

' efficiency reasons and because otherwise '

508

n/a

'"__getattr__()" would have\n'

509

n/a

' no way to access other attributes of the instance. '

510

n/a

'Note that at\n'

511

n/a

' least for instance variables, you can fake total '

512

n/a

'control by not\n'

513

n/a

' inserting any values in the instance attribute '

514

n/a

'dictionary (but\n'

515

n/a

' instead inserting them in another object). See the\n'

516

n/a

' "__getattribute__()" method below for a way to '

517

n/a

'actually get total\n'

518

n/a

' control over attribute access.\n'

519

n/a

'\n'

520

n/a

'object.__getattribute__(self, name)\n'

521

n/a

'\n'

522

n/a

' Called unconditionally to implement attribute '

523

n/a

'accesses for\n'

524

n/a

' instances of the class. If the class also defines '

525

n/a

'"__getattr__()",\n'

526

n/a

' the latter will not be called unless '

527

n/a

'"__getattribute__()" either\n'

528

n/a

' calls it explicitly or raises an "AttributeError". '

529

n/a

'This method\n'

530

n/a

' should return the (computed) attribute value or raise '

531

n/a

'an\n'

532

n/a

' "AttributeError" exception. In order to avoid '

533

n/a

'infinite recursion in\n'

534

n/a

' this method, its implementation should always call '

535

n/a

'the base class\n'

536

n/a

' method with the same name to access any attributes it '

537

n/a

'needs, for\n'

538

n/a

' example, "object.__getattribute__(self, name)".\n'

539

n/a

'\n'

540

n/a

' Note: This method may still be bypassed when looking '

541

n/a

'up special\n'

542

n/a

' methods as the result of implicit invocation via '

543

n/a

'language syntax\n'

544

n/a

' or built-in functions. See Special method lookup.\n'

545

n/a

'\n'

546

n/a

'object.__setattr__(self, name, value)\n'

547

n/a

'\n'

548

n/a

' Called when an attribute assignment is attempted. '

549

n/a

'This is called\n'

550

n/a

' instead of the normal mechanism (i.e. store the value '

551

n/a

'in the\n'

552

n/a

' instance dictionary). *name* is the attribute name, '

553

n/a

'*value* is the\n'

554

n/a

' value to be assigned to it.\n'

555

n/a

'\n'

556

n/a

' If "__setattr__()" wants to assign to an instance '

557

n/a

'attribute, it\n'

558

n/a

' should call the base class method with the same name, '

559

n/a

'for example,\n'

560

n/a

' "object.__setattr__(self, name, value)".\n'

561

n/a

'\n'

562

n/a

'object.__delattr__(self, name)\n'

563

n/a

'\n'

564

n/a

' Like "__setattr__()" but for attribute deletion '

565

n/a

'instead of\n'

566

n/a

' assignment. This should only be implemented if "del '

567

n/a

'obj.name" is\n'

568

n/a

' meaningful for the object.\n'

569

n/a

'\n'

570

n/a

'object.__dir__(self)\n'

571

n/a

'\n'

572

n/a

' Called when "dir()" is called on the object. A '

573

n/a

'sequence must be\n'

574

n/a

' returned. "dir()" converts the returned sequence to a '

575

n/a

'list and\n'

576

n/a

' sorts it.\n'

577

n/a

'\n'

578

n/a

'\n'

579

n/a

'Implementing Descriptors\n'

580

n/a

'========================\n'

581

n/a

'\n'

582

n/a

'The following methods only apply when an instance of the '

583

n/a

'class\n'

584

n/a

'containing the method (a so-called *descriptor* class) '

585

n/a

'appears in an\n'

586

n/a

'*owner* class (the descriptor must be in either the '

587

n/a

"owner's class\n"

588

n/a

'dictionary or in the class dictionary for one of its '

589

n/a

'parents). In the\n'

590

n/a

'examples below, "the attribute" refers to the attribute '

591

n/a

'whose name is\n'

592

n/a

"the key of the property in the owner class' "

593

n/a

'"__dict__".\n'

594

n/a

'\n'

595

n/a

'object.__get__(self, instance, owner)\n'

596

n/a

'\n'

597

n/a

' Called to get the attribute of the owner class (class '

598

n/a

'attribute\n'

599

n/a

' access) or of an instance of that class (instance '

600

n/a

'attribute\n'

601

n/a

' access). *owner* is always the owner class, while '

602

n/a

'*instance* is the\n'

603

n/a

' instance that the attribute was accessed through, or '

604

n/a

'"None" when\n'

605

n/a

' the attribute is accessed through the *owner*. This '

606

n/a

'method should\n'

607

n/a

' return the (computed) attribute value or raise an '

608

n/a

'"AttributeError"\n'

609

n/a

' exception.\n'

610

n/a

'\n'

611

n/a

'object.__set__(self, instance, value)\n'

612

n/a

'\n'

613

n/a

' Called to set the attribute on an instance *instance* '

614

n/a

'of the owner\n'

615

n/a

' class to a new value, *value*.\n'

616

n/a

'\n'

617

n/a

'object.__delete__(self, instance)\n'

618

n/a

'\n'

619

n/a

' Called to delete the attribute on an instance '

620

n/a

'*instance* of the\n'

621

n/a

' owner class.\n'

622

n/a

'\n'

623

n/a

'object.__set_name__(self, owner, name)\n'

624

n/a

'\n'

625

n/a

' Called at the time the owning class *owner* is '

626

n/a

'created. The\n'

627

n/a

' descriptor has been assigned to *name*.\n'

628

n/a

'\n'

629

n/a

' New in version 3.6.\n'

630

n/a

'\n'

631

n/a

'The attribute "__objclass__" is interpreted by the '

632

n/a

'"inspect" module as\n'

633

n/a

'specifying the class where this object was defined '

634

n/a

'(setting this\n'

635

n/a

'appropriately can assist in runtime introspection of '

636

n/a

'dynamic class\n'

637

n/a

'attributes). For callables, it may indicate that an '

638

n/a

'instance of the\n'

639

n/a

'given type (or a subclass) is expected or required as '

640

n/a

'the first\n'

641

n/a

'positional argument (for example, CPython sets this '

642

n/a

'attribute for\n'

643

n/a

'unbound methods that are implemented in C).\n'

644

n/a

'\n'

645

n/a

'\n'

646

n/a

'Invoking Descriptors\n'

647

n/a

'====================\n'

648

n/a

'\n'

649

n/a

'In general, a descriptor is an object attribute with '

650

n/a

'"binding\n'

651

n/a

'behavior", one whose attribute access has been '

652

n/a

'overridden by methods\n'

653

n/a

'in the descriptor protocol: "__get__()", "__set__()", '

654

n/a

'and\n'

655

n/a

'"__delete__()". If any of those methods are defined for '

656

n/a

'an object, it\n'

657

n/a

'is said to be a descriptor.\n'

658

n/a

'\n'

659

n/a

'The default behavior for attribute access is to get, '

660

n/a

'set, or delete\n'

661

n/a

"the attribute from an object's dictionary. For instance, "

662

n/a

'"a.x" has a\n'

663

n/a

'lookup chain starting with "a.__dict__[\'x\']", then\n'

664

n/a

'"type(a).__dict__[\'x\']", and continuing through the '

665

n/a

'base classes of\n'

666

n/a

'"type(a)" excluding metaclasses.\n'

667

n/a

'\n'

668

n/a

'However, if the looked-up value is an object defining '

669

n/a

'one of the\n'

670

n/a

'descriptor methods, then Python may override the default '

671

n/a

'behavior and\n'

672

n/a

'invoke the descriptor method instead. Where this occurs '

673

n/a

'in the\n'

674

n/a

'precedence chain depends on which descriptor methods '

675

n/a

'were defined and\n'

676

n/a

'how they were called.\n'

677

n/a

'\n'

678

n/a

'The starting point for descriptor invocation is a '

679

n/a

'binding, "a.x". How\n'

680

n/a

'the arguments are assembled depends on "a":\n'

681

n/a

'\n'

682

n/a

'Direct Call\n'

683

n/a

' The simplest and least common call is when user code '

684

n/a

'directly\n'

685

n/a

' invokes a descriptor method: "x.__get__(a)".\n'

686

n/a

'\n'

687

n/a

'Instance Binding\n'

688

n/a

' If binding to an object instance, "a.x" is '

689

n/a

'transformed into the\n'

690

n/a

' call: "type(a).__dict__[\'x\'].__get__(a, type(a))".\n'

691

n/a

'\n'

692

n/a

'Class Binding\n'

693

n/a

' If binding to a class, "A.x" is transformed into the '

694

n/a

'call:\n'

695

n/a

' "A.__dict__[\'x\'].__get__(None, A)".\n'

696

n/a

'\n'

697

n/a

'Super Binding\n'

698

n/a

' If "a" is an instance of "super", then the binding '

699

n/a

'"super(B,\n'

700

n/a

' obj).m()" searches "obj.__class__.__mro__" for the '

701

n/a

'base class "A"\n'

702

n/a

' immediately preceding "B" and then invokes the '

703

n/a

'descriptor with the\n'

704

n/a

' call: "A.__dict__[\'m\'].__get__(obj, '

705

n/a

'obj.__class__)".\n'

706

n/a

'\n'

707

n/a

'For instance bindings, the precedence of descriptor '

708

n/a

'invocation depends\n'

709

n/a

'on the which descriptor methods are defined. A '

710

n/a

'descriptor can define\n'

711

n/a

'any combination of "__get__()", "__set__()" and '

712

n/a

'"__delete__()". If it\n'

713

n/a

'does not define "__get__()", then accessing the '

714

n/a

'attribute will return\n'

715

n/a

'the descriptor object itself unless there is a value in '

716

n/a

"the object's\n"

717

n/a

'instance dictionary. If the descriptor defines '

718

n/a

'"__set__()" and/or\n'

719

n/a

'"__delete__()", it is a data descriptor; if it defines '

720

n/a

'neither, it is\n'

721

n/a

'a non-data descriptor. Normally, data descriptors '

722

n/a

'define both\n'

723

n/a

'"__get__()" and "__set__()", while non-data descriptors '

724

n/a

'have just the\n'

725

n/a

'"__get__()" method. Data descriptors with "__set__()" '

726

n/a

'and "__get__()"\n'

727

n/a

'defined always override a redefinition in an instance '

728

n/a

'dictionary. In\n'

729

n/a

'contrast, non-data descriptors can be overridden by '

730

n/a

'instances.\n'

731

n/a

'\n'

732

n/a

'Python methods (including "staticmethod()" and '

733

n/a

'"classmethod()") are\n'

734

n/a

'implemented as non-data descriptors. Accordingly, '

735

n/a

'instances can\n'

736

n/a

'redefine and override methods. This allows individual '

737

n/a

'instances to\n'

738

n/a

'acquire behaviors that differ from other instances of '

739

n/a

'the same class.\n'

740

n/a

'\n'

741

n/a

'The "property()" function is implemented as a data '

742

n/a

'descriptor.\n'

743

n/a

'Accordingly, instances cannot override the behavior of a '

744

n/a

'property.\n'

745

n/a

'\n'

746

n/a

'\n'

747

n/a

'__slots__\n'

748

n/a

'=========\n'

749

n/a

'\n'

750

n/a

'By default, instances of classes have a dictionary for '

751

n/a

'attribute\n'

752

n/a

'storage. This wastes space for objects having very few '

753

n/a

'instance\n'

754

n/a

'variables. The space consumption can become acute when '

755

n/a

'creating large\n'

756

n/a

'numbers of instances.\n'

757

n/a

'\n'

758

n/a

'The default can be overridden by defining *__slots__* in '

759

n/a

'a class\n'

760

n/a

'definition. The *__slots__* declaration takes a sequence '

761

n/a

'of instance\n'

762

n/a

'variables and reserves just enough space in each '

763

n/a

'instance to hold a\n'

764

n/a

'value for each variable. Space is saved because '

765

n/a

'*__dict__* is not\n'

766

n/a

'created for each instance.\n'

767

n/a

'\n'

768

n/a

'object.__slots__\n'

769

n/a

'\n'

770

n/a

' This class variable can be assigned a string, '

771

n/a

'iterable, or sequence\n'

772

n/a

' of strings with variable names used by instances. '

773

n/a

'*__slots__*\n'

774

n/a

' reserves space for the declared variables and '

775

n/a

'prevents the\n'

776

n/a

' automatic creation of *__dict__* and *__weakref__* '

777

n/a

'for each\n'

778

n/a

' instance.\n'

779

n/a

'\n'

780

n/a

'\n'

781

n/a

'Notes on using *__slots__*\n'

782

n/a

'--------------------------\n'

783

n/a

'\n'

784

n/a

'* When inheriting from a class without *__slots__*, the '

785

n/a

'*__dict__*\n'

786

n/a

' attribute of that class will always be accessible, so '

787

n/a

'a *__slots__*\n'

788

n/a

' definition in the subclass is meaningless.\n'

789

n/a

'\n'

790

n/a

'* Without a *__dict__* variable, instances cannot be '

791

n/a

'assigned new\n'

792

n/a

' variables not listed in the *__slots__* definition. '

793

n/a

'Attempts to\n'

794

n/a

' assign to an unlisted variable name raises '

795

n/a

'"AttributeError". If\n'

796

n/a

' dynamic assignment of new variables is desired, then '

797

n/a

'add\n'

798

n/a

' "\'__dict__\'" to the sequence of strings in the '

799

n/a

'*__slots__*\n'

800

n/a

' declaration.\n'

801

n/a

'\n'

802

n/a

'* Without a *__weakref__* variable for each instance, '

803

n/a

'classes\n'

804

n/a

' defining *__slots__* do not support weak references to '

805

n/a

'its\n'

806

n/a

' instances. If weak reference support is needed, then '

807

n/a

'add\n'

808

n/a

' "\'__weakref__\'" to the sequence of strings in the '

809

n/a

'*__slots__*\n'

810

n/a

' declaration.\n'

811

n/a

'\n'

812

n/a

'* *__slots__* are implemented at the class level by '

813

n/a

'creating\n'

814

n/a

' descriptors (Implementing Descriptors) for each '

815

n/a

'variable name. As a\n'

816

n/a

' result, class attributes cannot be used to set default '

817

n/a

'values for\n'

818

n/a

' instance variables defined by *__slots__*; otherwise, '

819

n/a

'the class\n'

820

n/a

' attribute would overwrite the descriptor assignment.\n'

821

n/a

'\n'

822

n/a

'* The action of a *__slots__* declaration is limited to '

823

n/a

'the class\n'

824

n/a

' where it is defined. As a result, subclasses will '

825

n/a

'have a *__dict__*\n'

826

n/a

' unless they also define *__slots__* (which must only '

827

n/a

'contain names\n'

828

n/a

' of any *additional* slots).\n'

829

n/a

'\n'

830

n/a

'* If a class defines a slot also defined in a base '

831

n/a

'class, the\n'

832

n/a

' instance variable defined by the base class slot is '

833

n/a

'inaccessible\n'

834

n/a

' (except by retrieving its descriptor directly from the '

835

n/a

'base class).\n'

836

n/a

' This renders the meaning of the program undefined. In '

837

n/a

'the future, a\n'

838

n/a

' check may be added to prevent this.\n'

839

n/a

'\n'

840

n/a

'* Nonempty *__slots__* does not work for classes derived '

841

n/a

'from\n'

842

n/a

' "variable-length" built-in types such as "int", '

843

n/a

'"bytes" and "tuple".\n'

844

n/a

'\n'

845

n/a

'* Any non-string iterable may be assigned to '

846

n/a

'*__slots__*. Mappings\n'

847

n/a

' may also be used; however, in the future, special '

848

n/a

'meaning may be\n'

849

n/a

' assigned to the values corresponding to each key.\n'

850

n/a

'\n'

851

n/a

'* *__class__* assignment works only if both classes have '

852

n/a

'the same\n'

853

n/a

' *__slots__*.\n',

854

n/a

'attribute-references': '\n'

855

n/a

'Attribute references\n'

856

n/a

'********************\n'

857

n/a

'\n'

858

n/a

'An attribute reference is a primary followed by a '

859

n/a

'period and a name:\n'

860

n/a

'\n'

861

n/a

' attributeref ::= primary "." identifier\n'

862

n/a

'\n'

863

n/a

'The primary must evaluate to an object of a type '

864

n/a

'that supports\n'

865

n/a

'attribute references, which most objects do. This '

866

n/a

'object is then\n'

867

n/a

'asked to produce the attribute whose name is the '

868

n/a

'identifier. This\n'

869

n/a

'production can be customized by overriding the '

870

n/a

'"__getattr__()" method.\n'

871

n/a

'If this attribute is not available, the exception '

872

n/a

'"AttributeError" is\n'

873

n/a

'raised. Otherwise, the type and value of the object '

874

n/a

'produced is\n'

875

n/a

'determined by the object. Multiple evaluations of '

876

n/a

'the same attribute\n'

877

n/a

'reference may yield different objects.\n',

878

n/a

'augassign': '\n'

879

n/a

'Augmented assignment statements\n'

880

n/a

'*******************************\n'

881

n/a

'\n'

882

n/a

'Augmented assignment is the combination, in a single statement, '

883

n/a

'of a\n'

884

n/a

'binary operation and an assignment statement:\n'

885

n/a

'\n'

886

n/a

' augmented_assignment_stmt ::= augtarget augop '

887

n/a

'(expression_list | yield_expression)\n'

888

n/a

' augtarget ::= identifier | attributeref | '

889

n/a

'subscription | slicing\n'

890

n/a

' augop ::= "+=" | "-=" | "*=" | "@=" | '

891

n/a

'"/=" | "//=" | "%=" | "**="\n'

892

n/a

' | ">>=" | "<<=" | "&=" | "^=" | "|="\n'

893

n/a

'\n'

894

n/a

'(See section Primaries for the syntax definitions of the last '

895

n/a

'three\n'

896

n/a

'symbols.)\n'

897

n/a

'\n'

898

n/a

'An augmented assignment evaluates the target (which, unlike '

899

n/a

'normal\n'

900

n/a

'assignment statements, cannot be an unpacking) and the '

901

n/a

'expression\n'

902

n/a

'list, performs the binary operation specific to the type of '

903

n/a

'assignment\n'

904

n/a

'on the two operands, and assigns the result to the original '

905

n/a

'target.\n'

906

n/a

'The target is only evaluated once.\n'

907

n/a

'\n'

908

n/a

'An augmented assignment expression like "x += 1" can be '

909

n/a

'rewritten as\n'

910

n/a

'"x = x + 1" to achieve a similar, but not exactly equal effect. '

911

n/a

'In the\n'

912

n/a

'augmented version, "x" is only evaluated once. Also, when '

913

n/a

'possible,\n'

914

n/a

'the actual operation is performed *in-place*, meaning that '

915

n/a

'rather than\n'

916

n/a

'creating a new object and assigning that to the target, the old '

917

n/a

'object\n'

918

n/a

'is modified instead.\n'

919

n/a

'\n'

920

n/a

'Unlike normal assignments, augmented assignments evaluate the '

921

n/a

'left-\n'

922

n/a

'hand side *before* evaluating the right-hand side. For '

923

n/a

'example, "a[i]\n'

924

n/a

'+= f(x)" first looks-up "a[i]", then it evaluates "f(x)" and '

925

n/a

'performs\n'

926

n/a

'the addition, and lastly, it writes the result back to "a[i]".\n'

927

n/a

'\n'

928

n/a

'With the exception of assigning to tuples and multiple targets '

929

n/a

'in a\n'

930

n/a

'single statement, the assignment done by augmented assignment\n'

931

n/a

'statements is handled the same way as normal assignments. '

932

n/a

'Similarly,\n'

933

n/a

'with the exception of the possible *in-place* behavior, the '

934

n/a

'binary\n'

935

n/a

'operation performed by augmented assignment is the same as the '

936

n/a

'normal\n'

937

n/a

'binary operations.\n'

938

n/a

'\n'

939

n/a

'For targets which are attribute references, the same caveat '

940

n/a

'about\n'

941

n/a

'class and instance attributes applies as for regular '

942

n/a

'assignments.\n',

943

n/a

'binary': '\n'

944

n/a

'Binary arithmetic operations\n'

945

n/a

'****************************\n'

946

n/a

'\n'

947

n/a

'The binary arithmetic operations have the conventional priority\n'

948

n/a

'levels. Note that some of these operations also apply to certain '

949

n/a

'non-\n'

950

n/a

'numeric types. Apart from the power operator, there are only two\n'

951

n/a

'levels, one for multiplicative operators and one for additive\n'

952

n/a

'operators:\n'

953

n/a

'\n'

954

n/a

' m_expr ::= u_expr | m_expr "*" u_expr | m_expr "@" m_expr |\n'

955

n/a

' m_expr "//" u_expr| m_expr "/" u_expr |\n'

956

n/a

' m_expr "%" u_expr\n'

957

n/a

' a_expr ::= m_expr | a_expr "+" m_expr | a_expr "-" m_expr\n'

958

n/a

'\n'

959

n/a

'The "*" (multiplication) operator yields the product of its '

960

n/a

'arguments.\n'

961

n/a

'The arguments must either both be numbers, or one argument must be '

962

n/a

'an\n'

963

n/a

'integer and the other must be a sequence. In the former case, the\n'

964

n/a

'numbers are converted to a common type and then multiplied '

965

n/a

'together.\n'

966

n/a

'In the latter case, sequence repetition is performed; a negative\n'

967

n/a

'repetition factor yields an empty sequence.\n'

968

n/a

'\n'

969

n/a

'The "@" (at) operator is intended to be used for matrix\n'

970

n/a

'multiplication. No builtin Python types implement this operator.\n'

971

n/a

'\n'

972

n/a

'New in version 3.5.\n'

973

n/a

'\n'

974

n/a

'The "/" (division) and "//" (floor division) operators yield the\n'

975

n/a

'quotient of their arguments. The numeric arguments are first\n'

976

n/a

'converted to a common type. Division of integers yields a float, '

977

n/a

'while\n'

978

n/a

'floor division of integers results in an integer; the result is '

979

n/a

'that\n'

980

n/a

"of mathematical division with the 'floor' function applied to the\n"

981

n/a

'result. Division by zero raises the "ZeroDivisionError" '

982

n/a

'exception.\n'

983

n/a

'\n'

984

n/a

'The "%" (modulo) operator yields the remainder from the division '

985

n/a

'of\n'

986

n/a

'the first argument by the second. The numeric arguments are '

987

n/a

'first\n'

988

n/a

'converted to a common type. A zero right argument raises the\n'

989

n/a

'"ZeroDivisionError" exception. The arguments may be floating '

990

n/a

'point\n'

991

n/a

'numbers, e.g., "3.14%0.7" equals "0.34" (since "3.14" equals '

992

n/a

'"4*0.7 +\n'

993

n/a

'0.34".) The modulo operator always yields a result with the same '

994

n/a

'sign\n'

995

n/a

'as its second operand (or zero); the absolute value of the result '

996

n/a

'is\n'

997

n/a

'strictly smaller than the absolute value of the second operand '

998

n/a

'[1].\n'

999

n/a

'\n'

1000

n/a

'The floor division and modulo operators are connected by the '

1001

n/a

'following\n'

1002

n/a

'identity: "x == (x//y)*y + (x%y)". Floor division and modulo are '

1003

n/a

'also\n'

1004

n/a

'connected with the built-in function "divmod()": "divmod(x, y) ==\n'

1005

n/a

'(x//y, x%y)". [2].\n'

1006

n/a

'\n'

1007

n/a

'In addition to performing the modulo operation on numbers, the '

1008

n/a

'"%"\n'

1009

n/a

'operator is also overloaded by string objects to perform '

1010

n/a

'old-style\n'

1011

n/a

'string formatting (also known as interpolation). The syntax for\n'

1012

n/a

'string formatting is described in the Python Library Reference,\n'

1013

n/a

'section printf-style String Formatting.\n'

1014

n/a

'\n'

1015

n/a

'The floor division operator, the modulo operator, and the '

1016

n/a

'"divmod()"\n'

1017

n/a

'function are not defined for complex numbers. Instead, convert to '

1018

n/a

'a\n'

1019

n/a

'floating point number using the "abs()" function if appropriate.\n'

1020

n/a

'\n'

1021

n/a

'The "+" (addition) operator yields the sum of its arguments. The\n'

1022

n/a

'arguments must either both be numbers or both be sequences of the '

1023

n/a

'same\n'

1024

n/a

'type. In the former case, the numbers are converted to a common '

1025

n/a

'type\n'

1026

n/a

'and then added together. In the latter case, the sequences are\n'

1027

n/a

'concatenated.\n'

1028

n/a

'\n'

1029

n/a

'The "-" (subtraction) operator yields the difference of its '

1030

n/a

'arguments.\n'

1031

n/a

'The numeric arguments are first converted to a common type.\n',

1032

n/a

'bitwise': '\n'

1033

n/a

'Binary bitwise operations\n'

1034

n/a

'*************************\n'

1035

n/a

'\n'

1036

n/a

'Each of the three bitwise operations has a different priority '

1037

n/a

'level:\n'

1038

n/a

'\n'

1039

n/a

' and_expr ::= shift_expr | and_expr "&" shift_expr\n'

1040

n/a

' xor_expr ::= and_expr | xor_expr "^" and_expr\n'

1041

n/a

' or_expr ::= xor_expr | or_expr "|" xor_expr\n'

1042

n/a

'\n'

1043

n/a

'The "&" operator yields the bitwise AND of its arguments, which '

1044

n/a

'must\n'

1045

n/a

'be integers.\n'

1046

n/a

'\n'

1047

n/a

'The "^" operator yields the bitwise XOR (exclusive OR) of its\n'

1048

n/a

'arguments, which must be integers.\n'

1049

n/a

'\n'

1050

n/a

'The "|" operator yields the bitwise (inclusive) OR of its '

1051

n/a

'arguments,\n'

1052

n/a

'which must be integers.\n',

1053

n/a

'bltin-code-objects': '\n'

1054

n/a

'Code Objects\n'

1055

n/a

'************\n'

1056

n/a

'\n'

1057

n/a

'Code objects are used by the implementation to '

1058

n/a

'represent "pseudo-\n'

1059

n/a

'compiled" executable Python code such as a function '

1060

n/a

'body. They differ\n'

1061

n/a

"from function objects because they don't contain a "

1062

n/a

'reference to their\n'

1063

n/a

'global execution environment. Code objects are '

1064

n/a

'returned by the built-\n'

1065

n/a

'in "compile()" function and can be extracted from '

1066

n/a

'function objects\n'

1067

n/a

'through their "__code__" attribute. See also the '

1068

n/a

'"code" module.\n'

1069

n/a

'\n'

1070

n/a

'A code object can be executed or evaluated by passing '

1071

n/a

'it (instead of a\n'

1072

n/a

'source string) to the "exec()" or "eval()" built-in '

1073

n/a

'functions.\n'

1074

n/a

'\n'

1075

n/a

'See The standard type hierarchy for more '

1076

n/a

'information.\n',

1077

n/a

'bltin-ellipsis-object': '\n'

1078

n/a

'The Ellipsis Object\n'

1079

n/a

'*******************\n'

1080

n/a

'\n'

1081

n/a

'This object is commonly used by slicing (see '

1082

n/a

'Slicings). It supports\n'

1083

n/a

'no special operations. There is exactly one '

1084

n/a

'ellipsis object, named\n'

1085

n/a

'"Ellipsis" (a built-in name). "type(Ellipsis)()" '

1086

n/a

'produces the\n'

1087

n/a

'"Ellipsis" singleton.\n'

1088

n/a

'\n'

1089

n/a

'It is written as "Ellipsis" or "...".\n',

1090

n/a

'bltin-null-object': '\n'

1091

n/a

'The Null Object\n'

1092

n/a

'***************\n'

1093

n/a

'\n'

1094

n/a

"This object is returned by functions that don't "

1095

n/a

'explicitly return a\n'

1096

n/a

'value. It supports no special operations. There is '

1097

n/a

'exactly one null\n'

1098

n/a

'object, named "None" (a built-in name). "type(None)()" '

1099

n/a

'produces the\n'

1100

n/a

'same singleton.\n'

1101

n/a

'\n'

1102

n/a

'It is written as "None".\n',

1103

n/a

'bltin-type-objects': '\n'

1104

n/a

'Type Objects\n'

1105

n/a

'************\n'

1106

n/a

'\n'

1107

n/a

'Type objects represent the various object types. An '

1108

n/a

"object's type is\n"

1109

n/a

'accessed by the built-in function "type()". There are '

1110

n/a

'no special\n'

1111

n/a

'operations on types. The standard module "types" '

1112

n/a

'defines names for\n'

1113

n/a

'all standard built-in types.\n'

1114

n/a

'\n'

1115

n/a

'Types are written like this: "<class \'int\'>".\n',

1116

n/a

'booleans': '\n'

1117

n/a

'Boolean operations\n'

1118

n/a

'******************\n'

1119

n/a

'\n'

1120

n/a

' or_test ::= and_test | or_test "or" and_test\n'

1121

n/a

' and_test ::= not_test | and_test "and" not_test\n'

1122

n/a

' not_test ::= comparison | "not" not_test\n'

1123

n/a

'\n'

1124

n/a

'In the context of Boolean operations, and also when expressions '

1125

n/a

'are\n'

1126

n/a

'used by control flow statements, the following values are '

1127

n/a

'interpreted\n'

1128

n/a

'as false: "False", "None", numeric zero of all types, and empty\n'

1129

n/a

'strings and containers (including strings, tuples, lists,\n'

1130

n/a

'dictionaries, sets and frozensets). All other values are '

1131

n/a

'interpreted\n'

1132

n/a

'as true. User-defined objects can customize their truth value '

1133

n/a

'by\n'

1134

n/a

'providing a "__bool__()" method.\n'

1135

n/a

'\n'

1136

n/a

'The operator "not" yields "True" if its argument is false, '

1137

n/a

'"False"\n'

1138

n/a

'otherwise.\n'

1139

n/a

'\n'

1140

n/a

'The expression "x and y" first evaluates *x*; if *x* is false, '

1141

n/a

'its\n'

1142

n/a

'value is returned; otherwise, *y* is evaluated and the resulting '

1143

n/a

'value\n'

1144

n/a

'is returned.\n'

1145

n/a

'\n'

1146

n/a

'The expression "x or y" first evaluates *x*; if *x* is true, its '

1147

n/a

'value\n'

1148

n/a

'is returned; otherwise, *y* is evaluated and the resulting value '

1149

n/a

'is\n'

1150

n/a

'returned.\n'

1151

n/a

'\n'

1152

n/a

'(Note that neither "and" nor "or" restrict the value and type '

1153

n/a

'they\n'

1154

n/a

'return to "False" and "True", but rather return the last '

1155

n/a

'evaluated\n'

1156

n/a

'argument. This is sometimes useful, e.g., if "s" is a string '

1157

n/a

'that\n'

1158

n/a

'should be replaced by a default value if it is empty, the '

1159

n/a

'expression\n'

1160

n/a

'"s or \'foo\'" yields the desired value. Because "not" has to '

1161

n/a

'create a\n'

1162

n/a

'new value, it returns a boolean value regardless of the type of '

1163

n/a

'its\n'

1164

n/a

'argument (for example, "not \'foo\'" produces "False" rather '

1165

n/a

'than "\'\'".)\n',

1166

n/a

'break': '\n'

1167

n/a

'The "break" statement\n'

1168

n/a

'*********************\n'

1169

n/a

'\n'

1170

n/a

' break_stmt ::= "break"\n'

1171

n/a

'\n'

1172

n/a

'"break" may only occur syntactically nested in a "for" or "while"\n'

1173

n/a

'loop, but not nested in a function or class definition within that\n'

1174

n/a

'loop.\n'

1175

n/a

'\n'

1176

n/a

'It terminates the nearest enclosing loop, skipping the optional '

1177

n/a

'"else"\n'

1178

n/a

'clause if the loop has one.\n'

1179

n/a

'\n'

1180

n/a

'If a "for" loop is terminated by "break", the loop control target\n'

1181

n/a

'keeps its current value.\n'

1182

n/a

'\n'

1183

n/a

'When "break" passes control out of a "try" statement with a '

1184

n/a

'"finally"\n'

1185

n/a

'clause, that "finally" clause is executed before really leaving '

1186

n/a

'the\n'

1187

n/a

'loop.\n',

1188

n/a

'callable-types': '\n'

1189

n/a

'Emulating callable objects\n'

1190

n/a

'**************************\n'

1191

n/a

'\n'

1192

n/a

'object.__call__(self[, args...])\n'

1193

n/a

'\n'

1194

n/a

' Called when the instance is "called" as a function; if '

1195

n/a

'this method\n'

1196

n/a

' is defined, "x(arg1, arg2, ...)" is a shorthand for\n'

1197

n/a

' "x.__call__(arg1, arg2, ...)".\n',

1198

n/a

'calls': '\n'

1199

n/a

'Calls\n'

1200

n/a

'*****\n'

1201

n/a

'\n'

1202

n/a

'A call calls a callable object (e.g., a *function*) with a '

1203

n/a

'possibly\n'

1204

n/a

'empty series of *arguments*:\n'

1205

n/a

'\n'

1206

n/a

' call ::= primary "(" [argument_list [","] | '

1207

n/a

'comprehension] ")"\n'

1208

n/a

' argument_list ::= positional_arguments ["," '

1209

n/a

'starred_and_keywords]\n'

1210

n/a

' ["," keywords_arguments]\n'

1211

n/a

' | starred_and_keywords ["," '

1212

n/a

'keywords_arguments]\n'

1213

n/a

' | keywords_arguments\n'

1214

n/a

' positional_arguments ::= ["*"] expression ("," ["*"] '

1215

n/a

'expression)*\n'

1216

n/a

' starred_and_keywords ::= ("*" expression | keyword_item)\n'

1217

n/a

' ("," "*" expression | "," '

1218

n/a

'keyword_item)*\n'

1219

n/a

' keywords_arguments ::= (keyword_item | "**" expression)\n'

1220

n/a

' ("," keyword_item | "**" expression)*\n'

1221

n/a

' keyword_item ::= identifier "=" expression\n'

1222

n/a

'\n'

1223

n/a

'An optional trailing comma may be present after the positional and\n'

1224

n/a

'keyword arguments but does not affect the semantics.\n'

1225

n/a

'\n'

1226

n/a

'The primary must evaluate to a callable object (user-defined\n'

1227

n/a

'functions, built-in functions, methods of built-in objects, class\n'

1228

n/a

'objects, methods of class instances, and all objects having a\n'

1229

n/a

'"__call__()" method are callable). All argument expressions are\n'

1230

n/a

'evaluated before the call is attempted. Please refer to section\n'

1231

n/a

'Function definitions for the syntax of formal *parameter* lists.\n'

1232

n/a

'\n'

1233

n/a

'If keyword arguments are present, they are first converted to\n'

1234

n/a

'positional arguments, as follows. First, a list of unfilled slots '

1235

n/a

'is\n'

1236

n/a

'created for the formal parameters. If there are N positional\n'

1237

n/a

'arguments, they are placed in the first N slots. Next, for each\n'

1238

n/a

'keyword argument, the identifier is used to determine the\n'

1239

n/a

'corresponding slot (if the identifier is the same as the first '

1240

n/a

'formal\n'

1241

n/a

'parameter name, the first slot is used, and so on). If the slot '

1242

n/a

'is\n'

1243

n/a

'already filled, a "TypeError" exception is raised. Otherwise, the\n'

1244

n/a

'value of the argument is placed in the slot, filling it (even if '

1245

n/a

'the\n'

1246

n/a

'expression is "None", it fills the slot). When all arguments have\n'

1247

n/a

'been processed, the slots that are still unfilled are filled with '

1248

n/a

'the\n'

1249

n/a

'corresponding default value from the function definition. '

1250

n/a

'(Default\n'

1251

n/a

'values are calculated, once, when the function is defined; thus, a\n'

1252

n/a

'mutable object such as a list or dictionary used as default value '

1253

n/a

'will\n'

1254

n/a

"be shared by all calls that don't specify an argument value for "

1255

n/a

'the\n'

1256

n/a

'corresponding slot; this should usually be avoided.) If there are '

1257

n/a

'any\n'

1258

n/a

'unfilled slots for which no default value is specified, a '

1259

n/a

'"TypeError"\n'

1260

n/a

'exception is raised. Otherwise, the list of filled slots is used '

1261

n/a

'as\n'

1262

n/a

'the argument list for the call.\n'

1263

n/a

'\n'

1264

n/a

'**CPython implementation detail:** An implementation may provide\n'

1265

n/a

'built-in functions whose positional parameters do not have names, '

1266

n/a

'even\n'

1267

n/a

"if they are 'named' for the purpose of documentation, and which\n"

1268

n/a

'therefore cannot be supplied by keyword. In CPython, this is the '

1269

n/a

'case\n'

1270

n/a

'for functions implemented in C that use "PyArg_ParseTuple()" to '

1271

n/a

'parse\n'

1272

n/a

'their arguments.\n'

1273

n/a

'\n'

1274

n/a

'If there are more positional arguments than there are formal '

1275

n/a

'parameter\n'

1276

n/a

'slots, a "TypeError" exception is raised, unless a formal '

1277

n/a

'parameter\n'

1278

n/a

'using the syntax "*identifier" is present; in this case, that '

1279

n/a

'formal\n'

1280

n/a

'parameter receives a tuple containing the excess positional '

1281

n/a

'arguments\n'

1282

n/a

'(or an empty tuple if there were no excess positional arguments).\n'

1283

n/a

'\n'

1284

n/a

'If any keyword argument does not correspond to a formal parameter\n'

1285

n/a

'name, a "TypeError" exception is raised, unless a formal parameter\n'

1286

n/a

'using the syntax "**identifier" is present; in this case, that '

1287

n/a

'formal\n'

1288

n/a

'parameter receives a dictionary containing the excess keyword\n'

1289

n/a

'arguments (using the keywords as keys and the argument values as\n'

1290

n/a

'corresponding values), or a (new) empty dictionary if there were '

1291

n/a

'no\n'

1292

n/a

'excess keyword arguments.\n'

1293

n/a

'\n'

1294

n/a

'If the syntax "*expression" appears in the function call, '

1295

n/a

'"expression"\n'

1296

n/a

'must evaluate to an *iterable*. Elements from these iterables are\n'

1297

n/a

'treated as if they were additional positional arguments. For the '

1298

n/a

'call\n'

1299

n/a

'"f(x1, x2, *y, x3, x4)", if *y* evaluates to a sequence *y1*, ...,\n'

1300

n/a

'*yM*, this is equivalent to a call with M+4 positional arguments '

1301

n/a

'*x1*,\n'

1302

n/a

'*x2*, *y1*, ..., *yM*, *x3*, *x4*.\n'

1303

n/a

'\n'

1304

n/a

'A consequence of this is that although the "*expression" syntax '

1305

n/a

'may\n'

1306

n/a

'appear *after* explicit keyword arguments, it is processed '

1307

n/a

'*before*\n'

1308

n/a

'the keyword arguments (and any "**expression" arguments -- see '

1309

n/a

'below).\n'

1310

n/a

'So:\n'

1311

n/a

'\n'

1312

n/a

' >>> def f(a, b):\n'

1313

n/a

' ... print(a, b)\n'

1314

n/a

' ...\n'

1315

n/a

' >>> f(b=1, *(2,))\n'

1316

n/a

' 2 1\n'

1317

n/a

' >>> f(a=1, *(2,))\n'

1318

n/a

' Traceback (most recent call last):\n'

1319

n/a

' File "<stdin>", line 1, in ?\n'

1320

n/a

" TypeError: f() got multiple values for keyword argument 'a'\n"

1321

n/a

' >>> f(1, *(2,))\n'

1322

n/a

' 1 2\n'

1323

n/a

'\n'

1324

n/a

'It is unusual for both keyword arguments and the "*expression" '

1325

n/a

'syntax\n'

1326

n/a

'to be used in the same call, so in practice this confusion does '

1327

n/a

'not\n'

1328

n/a

'arise.\n'

1329

n/a

'\n'

1330

n/a

'If the syntax "**expression" appears in the function call,\n'

1331

n/a

'"expression" must evaluate to a *mapping*, the contents of which '

1332

n/a

'are\n'

1333

n/a

'treated as additional keyword arguments. If a keyword is already\n'

1334

n/a

'present (as an explicit keyword argument, or from another '

1335

n/a

'unpacking),\n'

1336

n/a

'a "TypeError" exception is raised.\n'

1337

n/a

'\n'

1338

n/a

'Formal parameters using the syntax "*identifier" or "**identifier"\n'

1339

n/a

'cannot be used as positional argument slots or as keyword argument\n'

1340

n/a

'names.\n'

1341

n/a

'\n'

1342

n/a

'Changed in version 3.5: Function calls accept any number of "*" '

1343

n/a

'and\n'

1344

n/a

'"**" unpackings, positional arguments may follow iterable '

1345

n/a

'unpackings\n'

1346

n/a

'("*"), and keyword arguments may follow dictionary unpackings '

1347

n/a

'("**").\n'

1348

n/a

'Originally proposed by **PEP 448**.\n'

1349

n/a

'\n'

1350

n/a

'A call always returns some value, possibly "None", unless it raises '

1351

n/a

'an\n'

1352

n/a

'exception. How this value is computed depends on the type of the\n'

1353

n/a

'callable object.\n'

1354

n/a

'\n'

1355

n/a

'If it is---\n'

1356

n/a

'\n'

1357

n/a

'a user-defined function:\n'

1358

n/a

' The code block for the function is executed, passing it the\n'

1359

n/a

' argument list. The first thing the code block will do is bind '

1360

n/a

'the\n'

1361

n/a

' formal parameters to the arguments; this is described in '

1362

n/a

'section\n'

1363

n/a

' Function definitions. When the code block executes a "return"\n'

1364

n/a

' statement, this specifies the return value of the function '

1365

n/a

'call.\n'

1366

n/a

'\n'

1367

n/a

'a built-in function or method:\n'

1368

n/a

' The result is up to the interpreter; see Built-in Functions for '

1369

n/a

'the\n'

1370

n/a

' descriptions of built-in functions and methods.\n'

1371

n/a

'\n'

1372

n/a

'a class object:\n'

1373

n/a

' A new instance of that class is returned.\n'

1374

n/a

'\n'

1375

n/a

'a class instance method:\n'

1376

n/a

' The corresponding user-defined function is called, with an '

1377

n/a

'argument\n'

1378

n/a

' list that is one longer than the argument list of the call: the\n'

1379

n/a

' instance becomes the first argument.\n'

1380

n/a

'\n'

1381

n/a

'a class instance:\n'

1382

n/a

' The class must define a "__call__()" method; the effect is then '

1383

n/a

'the\n'

1384

n/a

' same as if that method was called.\n',

1385

n/a

'class': '\n'

1386

n/a

'Class definitions\n'

1387

n/a

'*****************\n'

1388

n/a

'\n'

1389

n/a

'A class definition defines a class object (see section The '

1390

n/a

'standard\n'

1391

n/a

'type hierarchy):\n'

1392

n/a

'\n'

1393

n/a

' classdef ::= [decorators] "class" classname [inheritance] ":" '

1394

n/a

'suite\n'

1395

n/a

' inheritance ::= "(" [argument_list] ")"\n'

1396

n/a

' classname ::= identifier\n'

1397

n/a

'\n'

1398

n/a

'A class definition is an executable statement. The inheritance '

1399

n/a

'list\n'

1400

n/a

'usually gives a list of base classes (see Metaclasses for more\n'

1401

n/a

'advanced uses), so each item in the list should evaluate to a '

1402

n/a

'class\n'

1403

n/a

'object which allows subclassing. Classes without an inheritance '

1404

n/a

'list\n'

1405

n/a

'inherit, by default, from the base class "object"; hence,\n'

1406

n/a

'\n'

1407

n/a

' class Foo:\n'

1408

n/a

' pass\n'

1409

n/a

'\n'

1410

n/a

'is equivalent to\n'

1411

n/a

'\n'

1412

n/a

' class Foo(object):\n'

1413

n/a

' pass\n'

1414

n/a

'\n'

1415

n/a

"The class's suite is then executed in a new execution frame (see\n"

1416

n/a

'Naming and binding), using a newly created local namespace and the\n'

1417

n/a

'original global namespace. (Usually, the suite contains mostly\n'

1418

n/a

"function definitions.) When the class's suite finishes execution, "

1419

n/a

'its\n'

1420

n/a

'execution frame is discarded but its local namespace is saved. [4] '

1421

n/a

'A\n'

1422

n/a

'class object is then created using the inheritance list for the '

1423

n/a

'base\n'

1424

n/a

'classes and the saved local namespace for the attribute '

1425

n/a

'dictionary.\n'

1426

n/a

'The class name is bound to this class object in the original local\n'

1427

n/a

'namespace.\n'

1428

n/a

'\n'

1429

n/a

'The order in which attributes are defined in the class body is\n'

1430

n/a

'preserved in the new class\'s "__dict__". Note that this is '

1431

n/a

'reliable\n'

1432

n/a

'only right after the class is created and only for classes that '

1433

n/a

'were\n'

1434

n/a

'defined using the definition syntax.\n'

1435

n/a

'\n'

1436

n/a

'Class creation can be customized heavily using metaclasses.\n'

1437

n/a

'\n'

1438

n/a

'Classes can also be decorated: just like when decorating '

1439

n/a

'functions,\n'

1440

n/a

'\n'

1441

n/a

' @f1(arg)\n'

1442

n/a

' @f2\n'

1443

n/a

' class Foo: pass\n'

1444

n/a

'\n'

1445

n/a

'is roughly equivalent to\n'

1446

n/a

'\n'

1447

n/a

' class Foo: pass\n'

1448

n/a

' Foo = f1(arg)(f2(Foo))\n'

1449

n/a

'\n'

1450

n/a

'The evaluation rules for the decorator expressions are the same as '

1451

n/a

'for\n'

1452

n/a

'function decorators. The result is then bound to the class name.\n'

1453

n/a

'\n'

1454

n/a

"**Programmer's note:** Variables defined in the class definition "

1455

n/a

'are\n'

1456

n/a

'class attributes; they are shared by instances. Instance '

1457

n/a

'attributes\n'

1458

n/a

'can be set in a method with "self.name = value". Both class and\n'

1459

n/a

'instance attributes are accessible through the notation '

1460

n/a

'""self.name"",\n'

1461

n/a

'and an instance attribute hides a class attribute with the same '

1462

n/a

'name\n'

1463

n/a

'when accessed in this way. Class attributes can be used as '

1464

n/a

'defaults\n'

1465

n/a

'for instance attributes, but using mutable values there can lead '

1466

n/a

'to\n'

1467

n/a

'unexpected results. Descriptors can be used to create instance\n'

1468

n/a

'variables with different implementation details.\n'

1469

n/a

'\n'

1470

n/a

'See also: **PEP 3115** - Metaclasses in Python 3 **PEP 3129** -\n'

1471

n/a

' Class Decorators\n',

1472

n/a

'comparisons': '\n'

1473

n/a

'Comparisons\n'

1474

n/a

'***********\n'

1475

n/a

'\n'

1476

n/a

'Unlike C, all comparison operations in Python have the same '

1477

n/a

'priority,\n'

1478

n/a

'which is lower than that of any arithmetic, shifting or '

1479

n/a

'bitwise\n'

1480

n/a

'operation. Also unlike C, expressions like "a < b < c" have '

1481

n/a

'the\n'

1482

n/a

'interpretation that is conventional in mathematics:\n'

1483

n/a

'\n'

1484

n/a

' comparison ::= or_expr ( comp_operator or_expr )*\n'

1485

n/a

' comp_operator ::= "<" | ">" | "==" | ">=" | "<=" | "!="\n'

1486

n/a

' | "is" ["not"] | ["not"] "in"\n'

1487

n/a

'\n'

1488

n/a

'Comparisons yield boolean values: "True" or "False".\n'

1489

n/a

'\n'

1490

n/a

'Comparisons can be chained arbitrarily, e.g., "x < y <= z" '

1491

n/a

'is\n'

1492

n/a

'equivalent to "x < y and y <= z", except that "y" is '

1493

n/a

'evaluated only\n'

1494

n/a

'once (but in both cases "z" is not evaluated at all when "x < '

1495

n/a

'y" is\n'

1496

n/a

'found to be false).\n'

1497

n/a

'\n'

1498

n/a

'Formally, if *a*, *b*, *c*, ..., *y*, *z* are expressions and '

1499

n/a

'*op1*,\n'

1500

n/a

'*op2*, ..., *opN* are comparison operators, then "a op1 b op2 '

1501

n/a

'c ... y\n'

1502

n/a

'opN z" is equivalent to "a op1 b and b op2 c and ... y opN '

1503

n/a

'z", except\n'

1504

n/a

'that each expression is evaluated at most once.\n'

1505

n/a

'\n'

1506

n/a

'Note that "a op1 b op2 c" doesn\'t imply any kind of '

1507

n/a

'comparison between\n'

1508

n/a

'*a* and *c*, so that, e.g., "x < y > z" is perfectly legal '

1509

n/a

'(though\n'

1510

n/a

'perhaps not pretty).\n'

1511

n/a

'\n'

1512

n/a

'\n'

1513

n/a

'Value comparisons\n'

1514

n/a

'=================\n'

1515

n/a

'\n'

1516

n/a

'The operators "<", ">", "==", ">=", "<=", and "!=" compare '

1517

n/a

'the values\n'

1518

n/a

'of two objects. The objects do not need to have the same '

1519

n/a

'type.\n'

1520

n/a

'\n'

1521

n/a

'Chapter Objects, values and types states that objects have a '

1522

n/a

'value (in\n'

1523

n/a

'addition to type and identity). The value of an object is a '

1524

n/a

'rather\n'

1525

n/a

'abstract notion in Python: For example, there is no canonical '

1526

n/a

'access\n'

1527

n/a

"method for an object's value. Also, there is no requirement "

1528

n/a

'that the\n'

1529

n/a

'value of an object should be constructed in a particular way, '

1530

n/a

'e.g.\n'

1531

n/a

'comprised of all its data attributes. Comparison operators '

1532

n/a

'implement a\n'

1533

n/a

'particular notion of what the value of an object is. One can '

1534

n/a

'think of\n'

1535

n/a

'them as defining the value of an object indirectly, by means '

1536

n/a

'of their\n'

1537

n/a

'comparison implementation.\n'

1538

n/a

'\n'

1539

n/a

'Because all types are (direct or indirect) subtypes of '

1540

n/a

'"object", they\n'

1541

n/a

'inherit the default comparison behavior from "object". Types '

1542

n/a

'can\n'

1543

n/a

'customize their comparison behavior by implementing *rich '

1544

n/a

'comparison\n'

1545

n/a

'methods* like "__lt__()", described in Basic customization.\n'

1546

n/a

'\n'

1547

n/a

'The default behavior for equality comparison ("==" and "!=") '

1548

n/a

'is based\n'

1549

n/a

'on the identity of the objects. Hence, equality comparison '

1550

n/a

'of\n'

1551

n/a

'instances with the same identity results in equality, and '

1552

n/a

'equality\n'

1553

n/a

'comparison of instances with different identities results in\n'

1554

n/a

'inequality. A motivation for this default behavior is the '

1555

n/a

'desire that\n'

1556

n/a

'all objects should be reflexive (i.e. "x is y" implies "x == '

1557

n/a

'y").\n'

1558

n/a

'\n'

1559

n/a

'A default order comparison ("<", ">", "<=", and ">=") is not '

1560

n/a

'provided;\n'

1561

n/a

'an attempt raises "TypeError". A motivation for this default '

1562

n/a

'behavior\n'

1563

n/a

'is the lack of a similar invariant as for equality.\n'

1564

n/a

'\n'

1565

n/a

'The behavior of the default equality comparison, that '

1566

n/a

'instances with\n'

1567

n/a

'different identities are always unequal, may be in contrast '

1568

n/a

'to what\n'

1569

n/a

'types will need that have a sensible definition of object '

1570

n/a

'value and\n'

1571

n/a

'value-based equality. Such types will need to customize '

1572

n/a

'their\n'

1573

n/a

'comparison behavior, and in fact, a number of built-in types '

1574

n/a

'have done\n'

1575

n/a

'that.\n'

1576

n/a

'\n'

1577

n/a

'The following list describes the comparison behavior of the '

1578

n/a

'most\n'

1579

n/a

'important built-in types.\n'

1580

n/a

'\n'

1581

n/a

'* Numbers of built-in numeric types (Numeric Types --- int, '

1582

n/a

'float,\n'

1583

n/a

' complex) and of the standard library types '

1584

n/a

'"fractions.Fraction" and\n'

1585

n/a

' "decimal.Decimal" can be compared within and across their '

1586

n/a

'types,\n'

1587

n/a

' with the restriction that complex numbers do not support '

1588

n/a

'order\n'

1589

n/a

' comparison. Within the limits of the types involved, they '

1590

n/a

'compare\n'

1591

n/a

' mathematically (algorithmically) correct without loss of '

1592

n/a

'precision.\n'

1593

n/a

'\n'

1594

n/a

' The not-a-number values "float(\'NaN\')" and '

1595

n/a

'"Decimal(\'NaN\')" are\n'

1596

n/a

' special. They are identical to themselves ("x is x" is '

1597

n/a

'true) but\n'

1598

n/a

' are not equal to themselves ("x == x" is false). '

1599

n/a

'Additionally,\n'

1600

n/a

' comparing any number to a not-a-number value will return '

1601

n/a

'"False".\n'

1602

n/a

' For example, both "3 < float(\'NaN\')" and "float(\'NaN\') '

1603

n/a

'< 3" will\n'

1604

n/a

' return "False".\n'

1605

n/a

'\n'

1606

n/a

'* Binary sequences (instances of "bytes" or "bytearray") can '

1607

n/a

'be\n'

1608

n/a

' compared within and across their types. They compare\n'

1609

n/a

' lexicographically using the numeric values of their '

1610

n/a

'elements.\n'

1611

n/a

'\n'

1612

n/a

'* Strings (instances of "str") compare lexicographically '

1613

n/a

'using the\n'

1614

n/a

' numerical Unicode code points (the result of the built-in '

1615

n/a

'function\n'

1616

n/a

' "ord()") of their characters. [3]\n'

1617

n/a

'\n'

1618

n/a

' Strings and binary sequences cannot be directly compared.\n'

1619

n/a

'\n'

1620

n/a

'* Sequences (instances of "tuple", "list", or "range") can '

1621

n/a

'be\n'

1622

n/a

' compared only within each of their types, with the '

1623

n/a

'restriction that\n'

1624

n/a

' ranges do not support order comparison. Equality '

1625

n/a

'comparison across\n'

1626

n/a

' these types results in unequality, and ordering comparison '

1627

n/a

'across\n'

1628

n/a

' these types raises "TypeError".\n'

1629

n/a

'\n'

1630

n/a

' Sequences compare lexicographically using comparison of\n'

1631

n/a

' corresponding elements, whereby reflexivity of the elements '

1632

n/a

'is\n'

1633

n/a

' enforced.\n'

1634

n/a

'\n'

1635

n/a

' In enforcing reflexivity of elements, the comparison of '

1636

n/a

'collections\n'

1637

n/a

' assumes that for a collection element "x", "x == x" is '

1638

n/a

'always true.\n'

1639

n/a

' Based on that assumption, element identity is compared '

1640

n/a

'first, and\n'

1641

n/a

' element comparison is performed only for distinct '

1642

n/a

'elements. This\n'

1643

n/a

' approach yields the same result as a strict element '

1644

n/a

'comparison\n'

1645

n/a

' would, if the compared elements are reflexive. For '

1646

n/a

'non-reflexive\n'

1647

n/a

' elements, the result is different than for strict element\n'

1648

n/a

' comparison, and may be surprising: The non-reflexive '

1649

n/a

'not-a-number\n'

1650

n/a

' values for example result in the following comparison '

1651

n/a

'behavior when\n'

1652

n/a

' used in a list:\n'

1653

n/a

'\n'

1654

n/a

" >>> nan = float('NaN')\n"

1655

n/a

' >>> nan is nan\n'

1656

n/a

' True\n'

1657

n/a

' >>> nan == nan\n'

1658

n/a

' False <-- the defined non-reflexive '

1659

n/a

'behavior of NaN\n'

1660

n/a

' >>> [nan] == [nan]\n'

1661

n/a

' True <-- list enforces reflexivity and '

1662

n/a

'tests identity first\n'

1663

n/a

'\n'

1664

n/a

' Lexicographical comparison between built-in collections '

1665

n/a

'works as\n'

1666

n/a

' follows:\n'

1667

n/a

'\n'

1668

n/a

' * For two collections to compare equal, they must be of the '

1669

n/a

'same\n'

1670

n/a

' type, have the same length, and each pair of '

1671

n/a

'corresponding\n'

1672

n/a

' elements must compare equal (for example, "[1,2] == '

1673

n/a

'(1,2)" is\n'

1674

n/a

' false because the type is not the same).\n'

1675

n/a

'\n'

1676

n/a

' * Collections that support order comparison are ordered the '

1677

n/a

'same\n'

1678

n/a

' as their first unequal elements (for example, "[1,2,x] <= '

1679

n/a

'[1,2,y]"\n'

1680

n/a

' has the same value as "x <= y"). If a corresponding '

1681

n/a

'element does\n'

1682

n/a

' not exist, the shorter collection is ordered first (for '

1683

n/a

'example,\n'

1684

n/a

' "[1,2] < [1,2,3]" is true).\n'

1685

n/a

'\n'

1686

n/a

'* Mappings (instances of "dict") compare equal if and only if '

1687

n/a

'they\n'

1688

n/a

' have equal *(key, value)* pairs. Equality comparison of the '

1689

n/a

'keys and\n'

1690

n/a

' elements enforces reflexivity.\n'

1691

n/a

'\n'

1692

n/a

' Order comparisons ("<", ">", "<=", and ">=") raise '

1693

n/a

'"TypeError".\n'

1694

n/a

'\n'

1695

n/a

'* Sets (instances of "set" or "frozenset") can be compared '

1696

n/a

'within\n'

1697

n/a

' and across their types.\n'

1698

n/a

'\n'

1699

n/a

' They define order comparison operators to mean subset and '

1700

n/a

'superset\n'

1701

n/a

' tests. Those relations do not define total orderings (for '

1702

n/a

'example,\n'

1703

n/a

' the two sets "{1,2}" and "{2,3}" are not equal, nor subsets '

1704

n/a

'of one\n'

1705

n/a

' another, nor supersets of one another). Accordingly, sets '

1706

n/a

'are not\n'

1707

n/a

' appropriate arguments for functions which depend on total '

1708

n/a

'ordering\n'

1709

n/a

' (for example, "min()", "max()", and "sorted()" produce '

1710

n/a

'undefined\n'

1711

n/a

' results given a list of sets as inputs).\n'

1712

n/a

'\n'

1713

n/a

' Comparison of sets enforces reflexivity of its elements.\n'

1714

n/a

'\n'

1715

n/a

'* Most other built-in types have no comparison methods '

1716

n/a

'implemented,\n'

1717

n/a

' so they inherit the default comparison behavior.\n'

1718

n/a

'\n'

1719

n/a

'User-defined classes that customize their comparison behavior '

1720

n/a

'should\n'

1721

n/a

'follow some consistency rules, if possible:\n'

1722

n/a

'\n'

1723

n/a

'* Equality comparison should be reflexive. In other words, '

1724

n/a

'identical\n'

1725

n/a

' objects should compare equal:\n'

1726

n/a

'\n'

1727

n/a

' "x is y" implies "x == y"\n'

1728

n/a

'\n'

1729

n/a

'* Comparison should be symmetric. In other words, the '

1730

n/a

'following\n'

1731

n/a

' expressions should have the same result:\n'

1732

n/a

'\n'

1733

n/a

' "x == y" and "y == x"\n'

1734

n/a

'\n'

1735

n/a

' "x != y" and "y != x"\n'

1736

n/a

'\n'

1737

n/a

' "x < y" and "y > x"\n'

1738

n/a

'\n'

1739

n/a

' "x <= y" and "y >= x"\n'

1740

n/a

'\n'

1741

n/a

'* Comparison should be transitive. The following '

1742

n/a

'(non-exhaustive)\n'

1743

n/a

' examples illustrate that:\n'

1744

n/a

'\n'

1745

n/a

' "x > y and y > z" implies "x > z"\n'

1746

n/a

'\n'

1747

n/a

' "x < y and y <= z" implies "x < z"\n'

1748

n/a

'\n'

1749

n/a

'* Inverse comparison should result in the boolean negation. '

1750

n/a

'In other\n'

1751

n/a

' words, the following expressions should have the same '

1752

n/a

'result:\n'

1753

n/a

'\n'

1754

n/a

' "x == y" and "not x != y"\n'

1755

n/a

'\n'

1756

n/a

' "x < y" and "not x >= y" (for total ordering)\n'

1757

n/a

'\n'

1758

n/a

' "x > y" and "not x <= y" (for total ordering)\n'

1759

n/a

'\n'

1760

n/a

' The last two expressions apply to totally ordered '

1761

n/a

'collections (e.g.\n'

1762

n/a

' to sequences, but not to sets or mappings). See also the\n'

1763

n/a

' "total_ordering()" decorator.\n'

1764

n/a

'\n'

1765

n/a

'Python does not enforce these consistency rules. In fact, '

1766

n/a

'the\n'

1767

n/a

'not-a-number values are an example for not following these '

1768

n/a

'rules.\n'

1769

n/a

'\n'

1770

n/a

'\n'

1771

n/a

'Membership test operations\n'

1772

n/a

'==========================\n'

1773

n/a

'\n'

1774

n/a

'The operators "in" and "not in" test for membership. "x in '

1775

n/a

's"\n'

1776

n/a

'evaluates to true if *x* is a member of *s*, and false '

1777

n/a

'otherwise. "x\n'

1778

n/a

'not in s" returns the negation of "x in s". All built-in '

1779

n/a

'sequences\n'

1780

n/a

'and set types support this as well as dictionary, for which '

1781

n/a

'"in" tests\n'

1782

n/a

'whether the dictionary has a given key. For container types '

1783

n/a

'such as\n'

1784

n/a

'list, tuple, set, frozenset, dict, or collections.deque, the\n'

1785

n/a

'expression "x in y" is equivalent to "any(x is e or x == e '

1786

n/a

'for e in\n'

1787

n/a

'y)".\n'

1788

n/a

'\n'

1789

n/a

'For the string and bytes types, "x in y" is true if and only '

1790

n/a

'if *x* is\n'

1791

n/a

'a substring of *y*. An equivalent test is "y.find(x) != '

1792

n/a

'-1". Empty\n'

1793

n/a

'strings are always considered to be a substring of any other '

1794

n/a

'string,\n'

1795

n/a

'so """ in "abc"" will return "True".\n'

1796

n/a

'\n'

1797

n/a

'For user-defined classes which define the "__contains__()" '

1798

n/a

'method, "x\n'

1799

n/a

'in y" is true if and only if "y.__contains__(x)" is true.\n'

1800

n/a

'\n'

1801

n/a

'For user-defined classes which do not define "__contains__()" '

1802

n/a

'but do\n'

1803

n/a

'define "__iter__()", "x in y" is true if some value "z" with '

1804

n/a

'"x == z"\n'

1805

n/a

'is produced while iterating over "y". If an exception is '

1806

n/a

'raised\n'

1807

n/a

'during the iteration, it is as if "in" raised that '

1808

n/a

'exception.\n'

1809

n/a

'\n'

1810

n/a

'Lastly, the old-style iteration protocol is tried: if a class '

1811

n/a

'defines\n'

1812

n/a

'"__getitem__()", "x in y" is true if and only if there is a '

1813

n/a

'non-\n'

1814

n/a

'negative integer index *i* such that "x == y[i]", and all '

1815

n/a

'lower\n'

1816

n/a

'integer indices do not raise "IndexError" exception. (If any '

1817

n/a

'other\n'

1818

n/a

'exception is raised, it is as if "in" raised that '

1819

n/a

'exception).\n'

1820

n/a

'\n'

1821

n/a

'The operator "not in" is defined to have the inverse true '

1822

n/a

'value of\n'

1823

n/a

'"in".\n'

1824

n/a

'\n'

1825

n/a

'\n'

1826

n/a

'Identity comparisons\n'

1827

n/a

'====================\n'

1828

n/a

'\n'

1829

n/a

'The operators "is" and "is not" test for object identity: "x '

1830

n/a

'is y" is\n'

1831

n/a

'true if and only if *x* and *y* are the same object. Object '

1832

n/a

'identity\n'

1833

n/a

'is determined using the "id()" function. "x is not y" yields '

1834

n/a

'the\n'

1835

n/a

'inverse truth value. [4]\n',

1836

n/a

'compound': '\n'

1837

n/a

'Compound statements\n'

1838

n/a

'*******************\n'

1839

n/a

'\n'

1840

n/a

'Compound statements contain (groups of) other statements; they '

1841

n/a

'affect\n'

1842

n/a

'or control the execution of those other statements in some way. '

1843

n/a

'In\n'

1844

n/a

'general, compound statements span multiple lines, although in '

1845

n/a

'simple\n'

1846

n/a

'incarnations a whole compound statement may be contained in one '

1847

n/a

'line.\n'

1848

n/a

'\n'

1849

n/a

'The "if", "while" and "for" statements implement traditional '

1850

n/a

'control\n'

1851

n/a

'flow constructs. "try" specifies exception handlers and/or '

1852

n/a

'cleanup\n'

1853

n/a

'code for a group of statements, while the "with" statement '

1854

n/a

'allows the\n'

1855

n/a

'execution of initialization and finalization code around a block '

1856

n/a

'of\n'

1857

n/a

'code. Function and class definitions are also syntactically '

1858

n/a

'compound\n'

1859

n/a

'statements.\n'

1860

n/a

'\n'

1861

n/a

"A compound statement consists of one or more 'clauses.' A "

1862

n/a

'clause\n'

1863

n/a

"consists of a header and a 'suite.' The clause headers of a\n"

1864

n/a

'particular compound statement are all at the same indentation '

1865

n/a

'level.\n'

1866

n/a

'Each clause header begins with a uniquely identifying keyword '

1867

n/a

'and ends\n'

1868

n/a

'with a colon. A suite is a group of statements controlled by a\n'

1869

n/a

'clause. A suite can be one or more semicolon-separated simple\n'

1870

n/a

'statements on the same line as the header, following the '

1871

n/a

"header's\n"

1872

n/a

'colon, or it can be one or more indented statements on '

1873

n/a

'subsequent\n'

1874

n/a

'lines. Only the latter form of a suite can contain nested '

1875

n/a

'compound\n'

1876

n/a

"statements; the following is illegal, mostly because it wouldn't "

1877

n/a

'be\n'

1878

n/a

'clear to which "if" clause a following "else" clause would '

1879

n/a

'belong:\n'

1880

n/a

'\n'

1881

n/a

' if test1: if test2: print(x)\n'

1882

n/a

'\n'

1883

n/a

'Also note that the semicolon binds tighter than the colon in '

1884

n/a

'this\n'

1885

n/a

'context, so that in the following example, either all or none of '

1886

n/a

'the\n'

1887

n/a

'"print()" calls are executed:\n'

1888

n/a

'\n'

1889

n/a

' if x < y < z: print(x); print(y); print(z)\n'

1890

n/a

'\n'

1891

n/a

'Summarizing:\n'

1892

n/a

'\n'

1893

n/a

' compound_stmt ::= if_stmt\n'

1894

n/a

' | while_stmt\n'

1895

n/a

' | for_stmt\n'

1896

n/a

' | try_stmt\n'

1897

n/a

' | with_stmt\n'

1898

n/a

' | funcdef\n'

1899

n/a

' | classdef\n'

1900

n/a

' | async_with_stmt\n'

1901

n/a

' | async_for_stmt\n'

1902

n/a

' | async_funcdef\n'

1903

n/a

' suite ::= stmt_list NEWLINE | NEWLINE INDENT '

1904

n/a

'statement+ DEDENT\n'

1905

n/a

' statement ::= stmt_list NEWLINE | compound_stmt\n'

1906

n/a

' stmt_list ::= simple_stmt (";" simple_stmt)* [";"]\n'

1907

n/a

'\n'

1908

n/a

'Note that statements always end in a "NEWLINE" possibly followed '

1909

n/a

'by a\n'

1910

n/a

'"DEDENT". Also note that optional continuation clauses always '

1911

n/a

'begin\n'

1912

n/a

'with a keyword that cannot start a statement, thus there are no\n'

1913

n/a

'ambiguities (the \'dangling "else"\' problem is solved in Python '

1914

n/a

'by\n'

1915

n/a

'requiring nested "if" statements to be indented).\n'

1916

n/a

'\n'

1917

n/a

'The formatting of the grammar rules in the following sections '

1918

n/a

'places\n'

1919

n/a

'each clause on a separate line for clarity.\n'

1920

n/a

'\n'

1921

n/a

'\n'

1922

n/a

'The "if" statement\n'

1923

n/a

'==================\n'

1924

n/a

'\n'

1925

n/a

'The "if" statement is used for conditional execution:\n'

1926

n/a

'\n'

1927

n/a

' if_stmt ::= "if" expression ":" suite\n'

1928

n/a

' ( "elif" expression ":" suite )*\n'

1929

n/a

' ["else" ":" suite]\n'

1930

n/a

'\n'

1931

n/a

'It selects exactly one of the suites by evaluating the '

1932

n/a

'expressions one\n'

1933

n/a

'by one until one is found to be true (see section Boolean '

1934

n/a

'operations\n'

1935

n/a

'for the definition of true and false); then that suite is '

1936

n/a

'executed\n'

1937

n/a

'(and no other part of the "if" statement is executed or '

1938

n/a

'evaluated).\n'

1939

n/a

'If all expressions are false, the suite of the "else" clause, '

1940

n/a

'if\n'

1941

n/a

'present, is executed.\n'

1942

n/a

'\n'

1943

n/a

'\n'

1944

n/a

'The "while" statement\n'

1945

n/a

'=====================\n'

1946

n/a

'\n'

1947

n/a

'The "while" statement is used for repeated execution as long as '

1948

n/a

'an\n'

1949

n/a

'expression is true:\n'

1950

n/a

'\n'

1951

n/a

' while_stmt ::= "while" expression ":" suite\n'

1952

n/a

' ["else" ":" suite]\n'

1953

n/a

'\n'

1954

n/a

'This repeatedly tests the expression and, if it is true, '

1955

n/a

'executes the\n'

1956

n/a

'first suite; if the expression is false (which may be the first '

1957

n/a

'time\n'

1958

n/a

'it is tested) the suite of the "else" clause, if present, is '

1959

n/a

'executed\n'

1960

n/a

'and the loop terminates.\n'

1961

n/a

'\n'

1962

n/a

'A "break" statement executed in the first suite terminates the '

1963

n/a

'loop\n'

1964

n/a

'without executing the "else" clause\'s suite. A "continue" '

1965

n/a

'statement\n'

1966

n/a

'executed in the first suite skips the rest of the suite and goes '

1967

n/a

'back\n'

1968

n/a

'to testing the expression.\n'

1969

n/a

'\n'

1970

n/a

'\n'

1971

n/a

'The "for" statement\n'

1972

n/a

'===================\n'

1973

n/a

'\n'

1974

n/a

'The "for" statement is used to iterate over the elements of a '

1975

n/a

'sequence\n'

1976

n/a

'(such as a string, tuple or list) or other iterable object:\n'

1977

n/a

'\n'

1978

n/a

' for_stmt ::= "for" target_list "in" expression_list ":" '

1979

n/a

'suite\n'

1980

n/a

' ["else" ":" suite]\n'

1981

n/a

'\n'

1982

n/a

'The expression list is evaluated once; it should yield an '

1983

n/a

'iterable\n'

1984

n/a

'object. An iterator is created for the result of the\n'

1985

n/a

'"expression_list". The suite is then executed once for each '

1986

n/a

'item\n'

1987

n/a

'provided by the iterator, in the order returned by the '

1988

n/a

'iterator. Each\n'

1989

n/a

'item in turn is assigned to the target list using the standard '

1990

n/a

'rules\n'

1991

n/a

'for assignments (see Assignment statements), and then the suite '

1992

n/a

'is\n'

1993

n/a

'executed. When the items are exhausted (which is immediately '

1994

n/a

'when the\n'

1995

n/a

'sequence is empty or an iterator raises a "StopIteration" '

1996

n/a

'exception),\n'

1997

n/a

'the suite in the "else" clause, if present, is executed, and the '

1998

n/a

'loop\n'

1999

n/a

'terminates.\n'

2000

n/a

'\n'

2001

n/a

'A "break" statement executed in the first suite terminates the '

2002

n/a

'loop\n'

2003

n/a

'without executing the "else" clause\'s suite. A "continue" '

2004

n/a

'statement\n'

2005

n/a

'executed in the first suite skips the rest of the suite and '

2006

n/a

'continues\n'

2007

n/a

'with the next item, or with the "else" clause if there is no '

2008

n/a

'next\n'

2009

n/a

'item.\n'

2010

n/a

'\n'

2011

n/a

'The for-loop makes assignments to the variables(s) in the target '

2012

n/a

'list.\n'

2013

n/a

'This overwrites all previous assignments to those variables '

2014

n/a

'including\n'

2015

n/a

'those made in the suite of the for-loop:\n'

2016

n/a

'\n'

2017

n/a

' for i in range(10):\n'

2018

n/a

' print(i)\n'

2019

n/a

' i = 5 # this will not affect the for-loop\n'

2020

n/a

' # because i will be overwritten with '

2021

n/a

'the next\n'

2022

n/a

' # index in the range\n'

2023

n/a

'\n'

2024

n/a

'Names in the target list are not deleted when the loop is '

2025

n/a

'finished,\n'

2026

n/a

'but if the sequence is empty, they will not have been assigned '

2027

n/a

'to at\n'

2028

n/a

'all by the loop. Hint: the built-in function "range()" returns '

2029

n/a

'an\n'

2030

n/a

"iterator of integers suitable to emulate the effect of Pascal's "

2031

n/a

'"for i\n'

2032

n/a

':= a to b do"; e.g., "list(range(3))" returns the list "[0, 1, '

2033

n/a

'2]".\n'

2034

n/a

'\n'

2035

n/a

'Note: There is a subtlety when the sequence is being modified by '

2036

n/a

'the\n'

2037

n/a

' loop (this can only occur for mutable sequences, i.e. lists). '

2038

n/a

'An\n'

2039

n/a

' internal counter is used to keep track of which item is used '

2040

n/a

'next,\n'

2041

n/a

' and this is incremented on each iteration. When this counter '

2042

n/a

'has\n'

2043

n/a

' reached the length of the sequence the loop terminates. This '

2044

n/a

'means\n'

2045

n/a

' that if the suite deletes the current (or a previous) item '

2046

n/a

'from the\n'

2047

n/a

' sequence, the next item will be skipped (since it gets the '

2048

n/a

'index of\n'

2049

n/a

' the current item which has already been treated). Likewise, '

2050

n/a

'if the\n'

2051

n/a

' suite inserts an item in the sequence before the current item, '

2052

n/a

'the\n'

2053

n/a

' current item will be treated again the next time through the '

2054

n/a

'loop.\n'

2055

n/a

' This can lead to nasty bugs that can be avoided by making a\n'

2056

n/a

' temporary copy using a slice of the whole sequence, e.g.,\n'

2057

n/a

'\n'

2058

n/a

' for x in a[:]:\n'

2059

n/a

' if x < 0: a.remove(x)\n'

2060

n/a

'\n'

2061

n/a

'\n'

2062

n/a

'The "try" statement\n'

2063

n/a

'===================\n'

2064

n/a

'\n'

2065

n/a

'The "try" statement specifies exception handlers and/or cleanup '

2066

n/a

'code\n'

2067

n/a

'for a group of statements:\n'

2068

n/a

'\n'

2069

n/a

' try_stmt ::= try1_stmt | try2_stmt\n'

2070

n/a

' try1_stmt ::= "try" ":" suite\n'

2071

n/a

' ("except" [expression ["as" identifier]] ":" '

2072

n/a

'suite)+\n'

2073

n/a

' ["else" ":" suite]\n'

2074

n/a

' ["finally" ":" suite]\n'

2075

n/a

' try2_stmt ::= "try" ":" suite\n'

2076

n/a

' "finally" ":" suite\n'

2077

n/a

'\n'

2078

n/a

'The "except" clause(s) specify one or more exception handlers. '

2079

n/a

'When no\n'

2080

n/a

'exception occurs in the "try" clause, no exception handler is\n'

2081

n/a

'executed. When an exception occurs in the "try" suite, a search '

2082

n/a

'for an\n'

2083

n/a

'exception handler is started. This search inspects the except '

2084

n/a

'clauses\n'

2085

n/a

'in turn until one is found that matches the exception. An '

2086

n/a

'expression-\n'

2087

n/a

'less except clause, if present, must be last; it matches any\n'

2088

n/a

'exception. For an except clause with an expression, that '

2089

n/a

'expression\n'

2090

n/a

'is evaluated, and the clause matches the exception if the '

2091

n/a

'resulting\n'

2092

n/a

'object is "compatible" with the exception. An object is '

2093

n/a

'compatible\n'

2094

n/a

'with an exception if it is the class or a base class of the '

2095

n/a

'exception\n'

2096

n/a

'object or a tuple containing an item compatible with the '

2097

n/a

'exception.\n'

2098

n/a

'\n'

2099

n/a

'If no except clause matches the exception, the search for an '

2100

n/a

'exception\n'

2101

n/a

'handler continues in the surrounding code and on the invocation '

2102

n/a

'stack.\n'

2103

n/a

'[1]\n'

2104

n/a

'\n'

2105

n/a

'If the evaluation of an expression in the header of an except '

2106

n/a

'clause\n'

2107

n/a

'raises an exception, the original search for a handler is '

2108

n/a

'canceled and\n'

2109

n/a

'a search starts for the new exception in the surrounding code '

2110

n/a

'and on\n'

2111

n/a

'the call stack (it is treated as if the entire "try" statement '

2112

n/a

'raised\n'

2113

n/a

'the exception).\n'

2114

n/a

'\n'

2115

n/a

'When a matching except clause is found, the exception is '

2116

n/a

'assigned to\n'

2117

n/a

'the target specified after the "as" keyword in that except '

2118

n/a

'clause, if\n'

2119

n/a

"present, and the except clause's suite is executed. All except\n"

2120

n/a

'clauses must have an executable block. When the end of this '

2121

n/a

'block is\n'

2122

n/a

'reached, execution continues normally after the entire try '

2123

n/a

'statement.\n'

2124

n/a

'(This means that if two nested handlers exist for the same '

2125

n/a

'exception,\n'

2126

n/a

'and the exception occurs in the try clause of the inner handler, '

2127

n/a

'the\n'

2128

n/a

'outer handler will not handle the exception.)\n'

2129

n/a

'\n'

2130

n/a

'When an exception has been assigned using "as target", it is '

2131

n/a

'cleared\n'

2132

n/a

'at the end of the except clause. This is as if\n'

2133

n/a

'\n'

2134

n/a

' except E as N:\n'

2135

n/a

' foo\n'

2136

n/a

'\n'

2137

n/a

'was translated to\n'

2138

n/a

'\n'

2139

n/a

' except E as N:\n'

2140

n/a

' try:\n'

2141

n/a

' foo\n'

2142

n/a

' finally:\n'

2143

n/a

' del N\n'

2144

n/a

'\n'

2145

n/a

'This means the exception must be assigned to a different name to '

2146

n/a

'be\n'

2147

n/a

'able to refer to it after the except clause. Exceptions are '

2148

n/a

'cleared\n'

2149

n/a

'because with the traceback attached to them, they form a '

2150

n/a

'reference\n'

2151

n/a

'cycle with the stack frame, keeping all locals in that frame '

2152

n/a

'alive\n'

2153

n/a

'until the next garbage collection occurs.\n'

2154

n/a

'\n'

2155

n/a

"Before an except clause's suite is executed, details about the\n"

2156

n/a

'exception are stored in the "sys" module and can be accessed '

2157

n/a

'via\n'

2158

n/a

'"sys.exc_info()". "sys.exc_info()" returns a 3-tuple consisting '

2159

n/a

'of the\n'

2160

n/a

'exception class, the exception instance and a traceback object '

2161

n/a

'(see\n'

2162

n/a

'section The standard type hierarchy) identifying the point in '

2163

n/a

'the\n'

2164

n/a

'program where the exception occurred. "sys.exc_info()" values '

2165

n/a

'are\n'

2166

n/a

'restored to their previous values (before the call) when '

2167

n/a

'returning\n'

2168

n/a

'from a function that handled an exception.\n'

2169

n/a

'\n'

2170

n/a

'The optional "else" clause is executed if and when control flows '

2171

n/a

'off\n'

2172

n/a

'the end of the "try" clause. [2] Exceptions in the "else" clause '

2173

n/a

'are\n'

2174

n/a

'not handled by the preceding "except" clauses.\n'

2175

n/a

'\n'

2176

n/a

'If "finally" is present, it specifies a \'cleanup\' handler. '

2177

n/a

'The "try"\n'

2178

n/a

'clause is executed, including any "except" and "else" clauses. '

2179

n/a

'If an\n'

2180

n/a

'exception occurs in any of the clauses and is not handled, the\n'

2181

n/a

'exception is temporarily saved. The "finally" clause is '

2182

n/a

'executed. If\n'

2183

n/a

'there is a saved exception it is re-raised at the end of the '

2184

n/a

'"finally"\n'

2185

n/a

'clause. If the "finally" clause raises another exception, the '

2186

n/a

'saved\n'

2187

n/a

'exception is set as the context of the new exception. If the '

2188

n/a

'"finally"\n'

2189

n/a

'clause executes a "return" or "break" statement, the saved '

2190

n/a

'exception\n'

2191

n/a

'is discarded:\n'

2192

n/a

'\n'

2193

n/a

' >>> def f():\n'

2194

n/a

' ... try:\n'

2195

n/a

' ... 1/0\n'

2196

n/a

' ... finally:\n'

2197

n/a

' ... return 42\n'

2198

n/a

' ...\n'

2199

n/a

' >>> f()\n'

2200

n/a

' 42\n'

2201

n/a

'\n'

2202

n/a

'The exception information is not available to the program '

2203

n/a

'during\n'

2204

n/a

'execution of the "finally" clause.\n'

2205

n/a

'\n'

2206

n/a

'When a "return", "break" or "continue" statement is executed in '

2207

n/a

'the\n'

2208

n/a

'"try" suite of a "try"..."finally" statement, the "finally" '

2209

n/a

'clause is\n'

2210

n/a

'also executed \'on the way out.\' A "continue" statement is '

2211

n/a

'illegal in\n'

2212

n/a

'the "finally" clause. (The reason is a problem with the current\n'

2213

n/a

'implementation --- this restriction may be lifted in the '

2214

n/a

'future).\n'

2215

n/a

'\n'

2216

n/a

'The return value of a function is determined by the last '

2217

n/a

'"return"\n'

2218

n/a

'statement executed. Since the "finally" clause always executes, '

2219

n/a

'a\n'

2220

n/a

'"return" statement executed in the "finally" clause will always '

2221

n/a

'be the\n'

2222

n/a

'last one executed:\n'

2223

n/a

'\n'

2224

n/a

' >>> def foo():\n'

2225

n/a

' ... try:\n'

2226

n/a

" ... return 'try'\n"

2227

n/a

' ... finally:\n'

2228

n/a

" ... return 'finally'\n"

2229

n/a

' ...\n'

2230

n/a

' >>> foo()\n'

2231

n/a

" 'finally'\n"

2232

n/a

'\n'

2233

n/a

'Additional information on exceptions can be found in section\n'

2234

n/a

'Exceptions, and information on using the "raise" statement to '

2235

n/a

'generate\n'

2236

n/a

'exceptions may be found in section The raise statement.\n'

2237

n/a

'\n'

2238

n/a

'\n'

2239

n/a

'The "with" statement\n'

2240

n/a

'====================\n'

2241

n/a

'\n'

2242

n/a

'The "with" statement is used to wrap the execution of a block '

2243

n/a

'with\n'

2244

n/a

'methods defined by a context manager (see section With '

2245

n/a

'Statement\n'

2246

n/a

'Context Managers). This allows common '

2247

n/a

'"try"..."except"..."finally"\n'

2248

n/a

'usage patterns to be encapsulated for convenient reuse.\n'

2249

n/a

'\n'

2250

n/a

' with_stmt ::= "with" with_item ("," with_item)* ":" suite\n'

2251

n/a

' with_item ::= expression ["as" target]\n'

2252

n/a

'\n'

2253

n/a

'The execution of the "with" statement with one "item" proceeds '

2254

n/a

'as\n'

2255

n/a

'follows:\n'

2256

n/a

'\n'

2257

n/a

'1. The context expression (the expression given in the '

2258

n/a

'"with_item")\n'

2259

n/a

' is evaluated to obtain a context manager.\n'

2260

n/a

'\n'

2261

n/a

'2. The context manager\'s "__exit__()" is loaded for later use.\n'

2262

n/a

'\n'

2263

n/a

'3. The context manager\'s "__enter__()" method is invoked.\n'

2264

n/a

'\n'

2265

n/a

'4. If a target was included in the "with" statement, the return\n'

2266

n/a

' value from "__enter__()" is assigned to it.\n'

2267

n/a

'\n'

2268

n/a

' Note: The "with" statement guarantees that if the '

2269

n/a

'"__enter__()"\n'

2270

n/a

' method returns without an error, then "__exit__()" will '

2271

n/a

'always be\n'

2272

n/a

' called. Thus, if an error occurs during the assignment to '

2273

n/a

'the\n'

2274

n/a

' target list, it will be treated the same as an error '

2275

n/a

'occurring\n'

2276

n/a

' within the suite would be. See step 6 below.\n'

2277

n/a

'\n'

2278

n/a

'5. The suite is executed.\n'

2279

n/a

'\n'

2280

n/a

'6. The context manager\'s "__exit__()" method is invoked. If '

2281

n/a

'an\n'

2282

n/a

' exception caused the suite to be exited, its type, value, '

2283

n/a

'and\n'

2284

n/a

' traceback are passed as arguments to "__exit__()". Otherwise, '

2285

n/a

'three\n'

2286

n/a

' "None" arguments are supplied.\n'

2287

n/a

'\n'

2288

n/a

' If the suite was exited due to an exception, and the return '

2289

n/a

'value\n'

2290

n/a

' from the "__exit__()" method was false, the exception is '

2291

n/a

'reraised.\n'

2292

n/a

' If the return value was true, the exception is suppressed, '

2293

n/a

'and\n'

2294

n/a

' execution continues with the statement following the "with"\n'

2295

n/a

' statement.\n'

2296

n/a

'\n'

2297

n/a

' If the suite was exited for any reason other than an '

2298

n/a

'exception, the\n'

2299

n/a

' return value from "__exit__()" is ignored, and execution '

2300

n/a

'proceeds\n'

2301

n/a

' at the normal location for the kind of exit that was taken.\n'

2302

n/a

'\n'

2303

n/a

'With more than one item, the context managers are processed as '

2304

n/a

'if\n'

2305

n/a

'multiple "with" statements were nested:\n'

2306

n/a

'\n'

2307

n/a

' with A() as a, B() as b:\n'

2308

n/a

' suite\n'

2309

n/a

'\n'

2310

n/a

'is equivalent to\n'

2311

n/a

'\n'

2312

n/a

' with A() as a:\n'

2313

n/a

' with B() as b:\n'

2314

n/a

' suite\n'

2315

n/a

'\n'

2316

n/a

'Changed in version 3.1: Support for multiple context '

2317

n/a

'expressions.\n'

2318

n/a

'\n'

2319

n/a

'See also:\n'

2320

n/a

'\n'

2321

n/a

' **PEP 343** - The "with" statement\n'

2322

n/a

' The specification, background, and examples for the Python '

2323

n/a

'"with"\n'

2324

n/a

' statement.\n'

2325

n/a

'\n'

2326

n/a

'\n'

2327

n/a

'Function definitions\n'

2328

n/a

'====================\n'

2329

n/a

'\n'

2330

n/a

'A function definition defines a user-defined function object '

2331

n/a

'(see\n'

2332

n/a

'section The standard type hierarchy):\n'

2333

n/a

'\n'

2334

n/a

' funcdef ::= [decorators] "def" funcname "(" '

2335

n/a

'[parameter_list] ")" ["->" expression] ":" suite\n'

2336

n/a

' decorators ::= decorator+\n'

2337

n/a

' decorator ::= "@" dotted_name ["(" '

2338

n/a

'[argument_list [","]] ")"] NEWLINE\n'

2339

n/a

' dotted_name ::= identifier ("." identifier)*\n'

2340

n/a

' parameter_list ::= defparameter ("," defparameter)* '

2341

n/a

'["," [parameter_list_starargs]]\n'

2342

n/a

' | parameter_list_starargs\n'

2343

n/a

' parameter_list_starargs ::= "*" [parameter] ("," '

2344

n/a

'defparameter)* ["," ["**" parameter [","]]]\n'

2345

n/a

' | "**" parameter [","]\n'

2346

n/a

' parameter ::= identifier [":" expression]\n'

2347

n/a

' defparameter ::= parameter ["=" expression]\n'

2348

n/a

' funcname ::= identifier\n'

2349

n/a

'\n'

2350

n/a

'A function definition is an executable statement. Its execution '

2351

n/a

'binds\n'

2352

n/a

'the function name in the current local namespace to a function '

2353

n/a

'object\n'

2354

n/a

'(a wrapper around the executable code for the function). This\n'

2355

n/a

'function object contains a reference to the current global '

2356

n/a

'namespace\n'

2357

n/a

'as the global namespace to be used when the function is called.\n'

2358

n/a

'\n'

2359

n/a

'The function definition does not execute the function body; this '

2360

n/a

'gets\n'

2361

n/a

'executed only when the function is called. [3]\n'

2362

n/a

'\n'

2363

n/a

'A function definition may be wrapped by one or more *decorator*\n'

2364

n/a

'expressions. Decorator expressions are evaluated when the '

2365

n/a

'function is\n'

2366

n/a

'defined, in the scope that contains the function definition. '

2367

n/a

'The\n'

2368

n/a

'result must be a callable, which is invoked with the function '

2369

n/a

'object\n'

2370

n/a

'as the only argument. The returned value is bound to the '

2371

n/a

'function name\n'

2372

n/a

'instead of the function object. Multiple decorators are applied '

2373

n/a

'in\n'

2374

n/a

'nested fashion. For example, the following code\n'

2375

n/a

'\n'

2376

n/a

' @f1(arg)\n'

2377

n/a

' @f2\n'

2378

n/a

' def func(): pass\n'

2379

n/a

'\n'

2380

n/a

'is roughly equivalent to\n'

2381

n/a

'\n'

2382

n/a

' def func(): pass\n'

2383

n/a

' func = f1(arg)(f2(func))\n'

2384

n/a

'\n'

2385

n/a

'except that the original function is not temporarily bound to '

2386

n/a

'the name\n'

2387

n/a

'"func".\n'

2388

n/a

'\n'

2389

n/a

'When one or more *parameters* have the form *parameter* "="\n'

2390

n/a

'*expression*, the function is said to have "default parameter '

2391

n/a

'values."\n'

2392

n/a

'For a parameter with a default value, the corresponding '

2393

n/a

'*argument* may\n'

2394

n/a

"be omitted from a call, in which case the parameter's default "

2395

n/a

'value is\n'

2396

n/a

'substituted. If a parameter has a default value, all following\n'

2397

n/a

'parameters up until the ""*"" must also have a default value --- '

2398

n/a

'this\n'

2399

n/a

'is a syntactic restriction that is not expressed by the '

2400

n/a

'grammar.\n'

2401

n/a

'\n'

2402

n/a

'**Default parameter values are evaluated from left to right when '

2403

n/a

'the\n'

2404

n/a

'function definition is executed.** This means that the '

2405

n/a

'expression is\n'

2406

n/a

'evaluated once, when the function is defined, and that the same '

2407

n/a

'"pre-\n'

2408

n/a

'computed" value is used for each call. This is especially '

2409

n/a

'important\n'

2410

n/a

'to understand when a default parameter is a mutable object, such '

2411

n/a

'as a\n'

2412

n/a

'list or a dictionary: if the function modifies the object (e.g. '

2413

n/a

'by\n'

2414

n/a

'appending an item to a list), the default value is in effect '

2415

n/a

'modified.\n'

2416

n/a

'This is generally not what was intended. A way around this is '

2417

n/a

'to use\n'

2418

n/a

'"None" as the default, and explicitly test for it in the body of '

2419

n/a

'the\n'

2420

n/a

'function, e.g.:\n'

2421

n/a

'\n'

2422

n/a

' def whats_on_the_telly(penguin=None):\n'

2423

n/a

' if penguin is None:\n'

2424

n/a

' penguin = []\n'

2425

n/a

' penguin.append("property of the zoo")\n'

2426

n/a

' return penguin\n'

2427

n/a

'\n'

2428

n/a

'Function call semantics are described in more detail in section '

2429

n/a

'Calls.\n'

2430

n/a

'A function call always assigns values to all parameters '

2431

n/a

'mentioned in\n'

2432

n/a

'the parameter list, either from position arguments, from '

2433

n/a

'keyword\n'

2434

n/a

'arguments, or from default values. If the form ""*identifier"" '

2435

n/a

'is\n'

2436

n/a

'present, it is initialized to a tuple receiving any excess '

2437

n/a

'positional\n'

2438

n/a

'parameters, defaulting to the empty tuple. If the form\n'

2439

n/a

'""**identifier"" is present, it is initialized to a new ordered\n'

2440

n/a

'mapping receiving any excess keyword arguments, defaulting to a '

2441

n/a

'new\n'

2442

n/a

'empty mapping of the same type. Parameters after ""*"" or\n'

2443

n/a

'""*identifier"" are keyword-only parameters and may only be '

2444

n/a

'passed\n'

2445

n/a

'used keyword arguments.\n'

2446

n/a

'\n'

2447

n/a

'Parameters may have annotations of the form "": expression"" '

2448

n/a

'following\n'

2449

n/a

'the parameter name. Any parameter may have an annotation even '

2450

n/a

'those\n'

2451

n/a

'of the form "*identifier" or "**identifier". Functions may '

2452

n/a

'have\n'

2453

n/a

'"return" annotation of the form ""-> expression"" after the '

2454

n/a

'parameter\n'

2455

n/a

'list. These annotations can be any valid Python expression and '

2456

n/a

'are\n'

2457

n/a

'evaluated when the function definition is executed. Annotations '

2458

n/a

'may\n'

2459

n/a

'be evaluated in a different order than they appear in the source '

2460

n/a

'code.\n'

2461

n/a

'The presence of annotations does not change the semantics of a\n'

2462

n/a

'function. The annotation values are available as values of a\n'

2463

n/a

"dictionary keyed by the parameters' names in the "

2464

n/a

'"__annotations__"\n'

2465

n/a

'attribute of the function object.\n'

2466

n/a

'\n'

2467

n/a

'It is also possible to create anonymous functions (functions not '

2468

n/a

'bound\n'

2469

n/a

'to a name), for immediate use in expressions. This uses lambda\n'

2470

n/a

'expressions, described in section Lambdas. Note that the '

2471

n/a

'lambda\n'

2472

n/a

'expression is merely a shorthand for a simplified function '

2473

n/a

'definition;\n'

2474

n/a

'a function defined in a ""def"" statement can be passed around '

2475

n/a

'or\n'

2476

n/a

'assigned to another name just like a function defined by a '

2477

n/a

'lambda\n'

2478

n/a

'expression. The ""def"" form is actually more powerful since '

2479

n/a

'it\n'

2480

n/a

'allows the execution of multiple statements and annotations.\n'

2481

n/a

'\n'

2482

n/a

"**Programmer's note:** Functions are first-class objects. A "

2483

n/a

'""def""\n'

2484

n/a

'statement executed inside a function definition defines a local\n'

2485

n/a

'function that can be returned or passed around. Free variables '

2486

n/a

'used\n'

2487

n/a

'in the nested function can access the local variables of the '

2488

n/a

'function\n'

2489

n/a

'containing the def. See section Naming and binding for '

2490

n/a

'details.\n'

2491

n/a

'\n'

2492

n/a

'See also:\n'

2493

n/a

'\n'

2494

n/a

' **PEP 3107** - Function Annotations\n'

2495

n/a

' The original specification for function annotations.\n'

2496

n/a

'\n'

2497

n/a

'\n'

2498

n/a

'Class definitions\n'

2499

n/a

'=================\n'

2500

n/a

'\n'

2501

n/a

'A class definition defines a class object (see section The '

2502

n/a

'standard\n'

2503

n/a

'type hierarchy):\n'

2504

n/a

'\n'

2505

n/a

' classdef ::= [decorators] "class" classname [inheritance] '

2506

n/a

'":" suite\n'

2507

n/a

' inheritance ::= "(" [argument_list] ")"\n'

2508

n/a

' classname ::= identifier\n'

2509

n/a

'\n'

2510

n/a

'A class definition is an executable statement. The inheritance '

2511

n/a

'list\n'

2512

n/a

'usually gives a list of base classes (see Metaclasses for more\n'

2513

n/a

'advanced uses), so each item in the list should evaluate to a '

2514

n/a

'class\n'

2515

n/a

'object which allows subclassing. Classes without an inheritance '

2516

n/a

'list\n'

2517

n/a

'inherit, by default, from the base class "object"; hence,\n'

2518

n/a

'\n'

2519

n/a

' class Foo:\n'

2520

n/a

' pass\n'

2521

n/a

'\n'

2522

n/a

'is equivalent to\n'

2523

n/a

'\n'

2524

n/a

' class Foo(object):\n'

2525

n/a

' pass\n'

2526

n/a

'\n'

2527

n/a

"The class's suite is then executed in a new execution frame "

2528

n/a

'(see\n'

2529

n/a

'Naming and binding), using a newly created local namespace and '

2530

n/a

'the\n'

2531

n/a

'original global namespace. (Usually, the suite contains mostly\n'

2532

n/a

"function definitions.) When the class's suite finishes "

2533

n/a

'execution, its\n'

2534

n/a

'execution frame is discarded but its local namespace is saved. '

2535

n/a

'[4] A\n'

2536

n/a

'class object is then created using the inheritance list for the '

2537

n/a

'base\n'

2538

n/a

'classes and the saved local namespace for the attribute '

2539

n/a

'dictionary.\n'

2540

n/a

'The class name is bound to this class object in the original '

2541

n/a

'local\n'

2542

n/a

'namespace.\n'

2543

n/a

'\n'

2544

n/a

'The order in which attributes are defined in the class body is\n'

2545

n/a

'preserved in the new class\'s "__dict__". Note that this is '

2546

n/a

'reliable\n'

2547

n/a

'only right after the class is created and only for classes that '

2548

n/a

'were\n'

2549

n/a

'defined using the definition syntax.\n'

2550

n/a

'\n'

2551

n/a

'Class creation can be customized heavily using metaclasses.\n'

2552

n/a

'\n'

2553

n/a

'Classes can also be decorated: just like when decorating '

2554

n/a

'functions,\n'

2555

n/a

'\n'

2556

n/a

' @f1(arg)\n'

2557

n/a

' @f2\n'

2558

n/a

' class Foo: pass\n'

2559

n/a

'\n'

2560

n/a

'is roughly equivalent to\n'

2561

n/a

'\n'

2562

n/a

' class Foo: pass\n'

2563

n/a

' Foo = f1(arg)(f2(Foo))\n'

2564

n/a

'\n'

2565

n/a

'The evaluation rules for the decorator expressions are the same '

2566

n/a

'as for\n'

2567

n/a

'function decorators. The result is then bound to the class '

2568

n/a

'name.\n'

2569

n/a

'\n'

2570

n/a

"**Programmer's note:** Variables defined in the class definition "

2571

n/a

'are\n'

2572

n/a

'class attributes; they are shared by instances. Instance '

2573

n/a

'attributes\n'

2574

n/a

'can be set in a method with "self.name = value". Both class '

2575

n/a

'and\n'

2576

n/a

'instance attributes are accessible through the notation '

2577

n/a

'""self.name"",\n'

2578

n/a

'and an instance attribute hides a class attribute with the same '

2579

n/a

'name\n'

2580

n/a

'when accessed in this way. Class attributes can be used as '

2581

n/a

'defaults\n'

2582

n/a

'for instance attributes, but using mutable values there can lead '

2583

n/a

'to\n'

2584

n/a

'unexpected results. Descriptors can be used to create instance\n'

2585

n/a

'variables with different implementation details.\n'

2586

n/a

'\n'

2587

n/a

'See also: **PEP 3115** - Metaclasses in Python 3 **PEP 3129** -\n'

2588

n/a

' Class Decorators\n'

2589

n/a

'\n'

2590

n/a

'\n'

2591

n/a

'Coroutines\n'

2592

n/a

'==========\n'

2593

n/a

'\n'

2594

n/a

'New in version 3.5.\n'

2595

n/a

'\n'

2596

n/a

'\n'

2597

n/a

'Coroutine function definition\n'

2598

n/a

'-----------------------------\n'

2599

n/a

'\n'

2600

n/a

' async_funcdef ::= [decorators] "async" "def" funcname "(" '

2601

n/a

'[parameter_list] ")" ["->" expression] ":" suite\n'

2602

n/a

'\n'

2603

n/a

'Execution of Python coroutines can be suspended and resumed at '

2604

n/a

'many\n'

2605

n/a

'points (see *coroutine*). In the body of a coroutine, any '

2606

n/a

'"await" and\n'

2607

n/a

'"async" identifiers become reserved keywords; "await" '

2608

n/a

'expressions,\n'

2609

n/a

'"async for" and "async with" can only be used in coroutine '

2610

n/a

'bodies.\n'

2611

n/a

'\n'

2612

n/a

'Functions defined with "async def" syntax are always coroutine\n'

2613

n/a

'functions, even if they do not contain "await" or "async" '

2614

n/a

'keywords.\n'

2615

n/a

'\n'

2616

n/a

'It is a "SyntaxError" to use "yield" expressions in "async def"\n'

2617

n/a

'coroutines.\n'

2618

n/a

'\n'

2619

n/a

'An example of a coroutine function:\n'

2620

n/a

'\n'

2621

n/a

' async def func(param1, param2):\n'

2622

n/a

' do_stuff()\n'

2623

n/a

' await some_coroutine()\n'

2624

n/a

'\n'

2625

n/a

'\n'

2626

n/a

'The "async for" statement\n'

2627

n/a

'-------------------------\n'

2628

n/a

'\n'

2629

n/a

' async_for_stmt ::= "async" for_stmt\n'

2630

n/a

'\n'

2631

n/a

'An *asynchronous iterable* is able to call asynchronous code in '

2632

n/a

'its\n'

2633

n/a

'*iter* implementation, and *asynchronous iterator* can call\n'

2634

n/a

'asynchronous code in its *next* method.\n'

2635

n/a

'\n'

2636

n/a

'The "async for" statement allows convenient iteration over\n'

2637

n/a

'asynchronous iterators.\n'

2638

n/a

'\n'

2639

n/a

'The following code:\n'

2640

n/a

'\n'

2641

n/a

' async for TARGET in ITER:\n'

2642

n/a

' BLOCK\n'

2643

n/a

' else:\n'

2644

n/a

' BLOCK2\n'

2645

n/a

'\n'

2646

n/a

'Is semantically equivalent to:\n'

2647

n/a

'\n'

2648

n/a

' iter = (ITER)\n'

2649

n/a

' iter = type(iter).__aiter__(iter)\n'

2650

n/a

' running = True\n'

2651

n/a

' while running:\n'

2652

n/a

' try:\n'

2653

n/a

' TARGET = await type(iter).__anext__(iter)\n'

2654

n/a

' except StopAsyncIteration:\n'

2655

n/a

' running = False\n'

2656

n/a

' else:\n'

2657

n/a

' BLOCK\n'

2658

n/a

' else:\n'

2659

n/a

' BLOCK2\n'

2660

n/a

'\n'

2661

n/a

'See also "__aiter__()" and "__anext__()" for details.\n'

2662

n/a

'\n'

2663

n/a

'It is a "SyntaxError" to use "async for" statement outside of '

2664

n/a

'an\n'

2665

n/a

'"async def" function.\n'

2666

n/a

'\n'

2667

n/a

'\n'

2668

n/a

'The "async with" statement\n'

2669

n/a

'--------------------------\n'

2670

n/a

'\n'

2671

n/a

' async_with_stmt ::= "async" with_stmt\n'

2672

n/a

'\n'

2673

n/a

'An *asynchronous context manager* is a *context manager* that is '

2674

n/a

'able\n'

2675

n/a

'to suspend execution in its *enter* and *exit* methods.\n'

2676

n/a

'\n'

2677

n/a

'The following code:\n'

2678

n/a

'\n'

2679

n/a

' async with EXPR as VAR:\n'

2680

n/a

' BLOCK\n'

2681

n/a

'\n'

2682

n/a

'Is semantically equivalent to:\n'

2683

n/a

'\n'

2684

n/a

' mgr = (EXPR)\n'

2685

n/a

' aexit = type(mgr).__aexit__\n'

2686

n/a

' aenter = type(mgr).__aenter__(mgr)\n'

2687

n/a

' exc = True\n'

2688

n/a

'\n'

2689

n/a

' VAR = await aenter\n'

2690

n/a

' try:\n'

2691

n/a

' BLOCK\n'

2692

n/a

' except:\n'

2693

n/a

' if not await aexit(mgr, *sys.exc_info()):\n'

2694

n/a

' raise\n'

2695

n/a

' else:\n'

2696

n/a

' await aexit(mgr, None, None, None)\n'

2697

n/a

'\n'

2698

n/a

'See also "__aenter__()" and "__aexit__()" for details.\n'

2699

n/a

'\n'

2700

n/a

'It is a "SyntaxError" to use "async with" statement outside of '

2701

n/a

'an\n'

2702

n/a

'"async def" function.\n'

2703

n/a

'\n'

2704

n/a

'See also: **PEP 492** - Coroutines with async and await syntax\n'

2705

n/a

'\n'

2706

n/a

'-[ Footnotes ]-\n'

2707

n/a

'\n'

2708

n/a

'[1] The exception is propagated to the invocation stack unless\n'

2709

n/a

' there is a "finally" clause which happens to raise another\n'

2710

n/a

' exception. That new exception causes the old one to be '

2711

n/a

'lost.\n'

2712

n/a

'\n'

2713

n/a

'[2] Currently, control "flows off the end" except in the case '

2714

n/a

'of\n'

2715

n/a

' an exception or the execution of a "return", "continue", or\n'

2716

n/a

' "break" statement.\n'

2717

n/a

'\n'

2718

n/a

'[3] A string literal appearing as the first statement in the\n'

2719

n/a

' function body is transformed into the function\'s "__doc__"\n'

2720

n/a

" attribute and therefore the function's *docstring*.\n"

2721

n/a

'\n'

2722

n/a

'[4] A string literal appearing as the first statement in the '

2723

n/a

'class\n'

2724

n/a

' body is transformed into the namespace\'s "__doc__" item '

2725

n/a

'and\n'

2726

n/a

" therefore the class's *docstring*.\n",

2727

n/a

'context-managers': '\n'

2728

n/a

'With Statement Context Managers\n'

2729

n/a

'*******************************\n'

2730

n/a

'\n'

2731

n/a

'A *context manager* is an object that defines the '

2732

n/a

'runtime context to\n'

2733

n/a

'be established when executing a "with" statement. The '

2734

n/a

'context manager\n'

2735

n/a

'handles the entry into, and the exit from, the desired '

2736

n/a

'runtime context\n'

2737

n/a

'for the execution of the block of code. Context '

2738

n/a

'managers are normally\n'

2739

n/a

'invoked using the "with" statement (described in section '

2740

n/a

'The with\n'

2741

n/a

'statement), but can also be used by directly invoking '

2742

n/a

'their methods.\n'

2743

n/a

'\n'

2744

n/a

'Typical uses of context managers include saving and '

2745

n/a

'restoring various\n'

2746

n/a

'kinds of global state, locking and unlocking resources, '

2747

n/a

'closing opened\n'

2748

n/a

'files, etc.\n'

2749

n/a

'\n'

2750

n/a

'For more information on context managers, see Context '

2751

n/a

'Manager Types.\n'

2752

n/a

'\n'

2753

n/a

'object.__enter__(self)\n'

2754

n/a

'\n'

2755

n/a

' Enter the runtime context related to this object. The '

2756

n/a

'"with"\n'

2757

n/a

" statement will bind this method's return value to the "

2758

n/a

'target(s)\n'

2759

n/a

' specified in the "as" clause of the statement, if '

2760

n/a

'any.\n'

2761

n/a

'\n'

2762

n/a

'object.__exit__(self, exc_type, exc_value, traceback)\n'

2763

n/a

'\n'

2764

n/a

' Exit the runtime context related to this object. The '

2765

n/a

'parameters\n'

2766

n/a

' describe the exception that caused the context to be '

2767

n/a

'exited. If the\n'

2768

n/a

' context was exited without an exception, all three '

2769

n/a

'arguments will\n'

2770

n/a

' be "None".\n'

2771

n/a

'\n'

2772

n/a

' If an exception is supplied, and the method wishes to '

2773

n/a

'suppress the\n'

2774

n/a

' exception (i.e., prevent it from being propagated), '

2775

n/a

'it should\n'

2776

n/a

' return a true value. Otherwise, the exception will be '

2777

n/a

'processed\n'

2778

n/a

' normally upon exit from this method.\n'

2779

n/a

'\n'

2780

n/a

' Note that "__exit__()" methods should not reraise the '

2781

n/a

'passed-in\n'

2782

n/a

" exception; this is the caller's responsibility.\n"

2783

n/a

'\n'

2784

n/a

'See also:\n'

2785

n/a

'\n'

2786

n/a

' **PEP 343** - The "with" statement\n'

2787

n/a

' The specification, background, and examples for the '

2788

n/a

'Python "with"\n'

2789

n/a

' statement.\n',

2790

n/a

'continue': '\n'

2791

n/a

'The "continue" statement\n'

2792

n/a

'************************\n'

2793

n/a

'\n'

2794

n/a

' continue_stmt ::= "continue"\n'

2795

n/a

'\n'

2796

n/a

'"continue" may only occur syntactically nested in a "for" or '

2797

n/a

'"while"\n'

2798

n/a

'loop, but not nested in a function or class definition or '

2799

n/a

'"finally"\n'

2800

n/a

'clause within that loop. It continues with the next cycle of '

2801

n/a

'the\n'

2802

n/a

'nearest enclosing loop.\n'

2803

n/a

'\n'

2804

n/a

'When "continue" passes control out of a "try" statement with a\n'

2805

n/a

'"finally" clause, that "finally" clause is executed before '

2806

n/a

'really\n'

2807

n/a

'starting the next loop cycle.\n',

2808

n/a

'conversions': '\n'

2809

n/a

'Arithmetic conversions\n'

2810

n/a

'**********************\n'

2811

n/a

'\n'

2812

n/a

'When a description of an arithmetic operator below uses the '

2813

n/a

'phrase\n'

2814

n/a

'"the numeric arguments are converted to a common type," this '

2815

n/a

'means\n'

2816

n/a

'that the operator implementation for built-in types works as '

2817

n/a

'follows:\n'

2818

n/a

'\n'

2819

n/a

'* If either argument is a complex number, the other is '

2820

n/a

'converted to\n'

2821

n/a

' complex;\n'

2822

n/a

'\n'

2823

n/a

'* otherwise, if either argument is a floating point number, '

2824

n/a

'the\n'

2825

n/a

' other is converted to floating point;\n'

2826

n/a

'\n'

2827

n/a

'* otherwise, both must be integers and no conversion is '

2828

n/a

'necessary.\n'

2829

n/a

'\n'

2830

n/a

'Some additional rules apply for certain operators (e.g., a '

2831

n/a

'string as a\n'

2832

n/a

"left argument to the '%' operator). Extensions must define "

2833

n/a

'their own\n'

2834

n/a

'conversion behavior.\n',

2835

n/a

'customization': '\n'

2836

n/a

'Basic customization\n'

2837

n/a

'*******************\n'

2838

n/a

'\n'

2839

n/a

'object.__new__(cls[, ...])\n'

2840

n/a

'\n'

2841

n/a

' Called to create a new instance of class *cls*. '

2842

n/a

'"__new__()" is a\n'

2843

n/a

' static method (special-cased so you need not declare it '

2844

n/a

'as such)\n'

2845

n/a

' that takes the class of which an instance was requested '

2846

n/a

'as its\n'

2847

n/a

' first argument. The remaining arguments are those '

2848

n/a

'passed to the\n'

2849

n/a

' object constructor expression (the call to the class). '

2850

n/a

'The return\n'

2851

n/a

' value of "__new__()" should be the new object instance '

2852

n/a

'(usually an\n'

2853

n/a

' instance of *cls*).\n'

2854

n/a

'\n'

2855

n/a

' Typical implementations create a new instance of the '

2856

n/a

'class by\n'

2857

n/a

' invoking the superclass\'s "__new__()" method using\n'

2858

n/a

' "super(currentclass, cls).__new__(cls[, ...])" with '

2859

n/a

'appropriate\n'

2860

n/a

' arguments and then modifying the newly-created instance '

2861

n/a

'as\n'

2862

n/a

' necessary before returning it.\n'

2863

n/a

'\n'

2864

n/a

' If "__new__()" returns an instance of *cls*, then the '

2865

n/a

'new\n'

2866

n/a

' instance\'s "__init__()" method will be invoked like\n'

2867

n/a

' "__init__(self[, ...])", where *self* is the new '

2868

n/a

'instance and the\n'

2869

n/a

' remaining arguments are the same as were passed to '

2870

n/a

'"__new__()".\n'

2871

n/a

'\n'

2872

n/a

' If "__new__()" does not return an instance of *cls*, '

2873

n/a

'then the new\n'

2874

n/a

' instance\'s "__init__()" method will not be invoked.\n'

2875

n/a

'\n'

2876

n/a

' "__new__()" is intended mainly to allow subclasses of '

2877

n/a

'immutable\n'

2878

n/a

' types (like int, str, or tuple) to customize instance '

2879

n/a

'creation. It\n'

2880

n/a

' is also commonly overridden in custom metaclasses in '

2881

n/a

'order to\n'

2882

n/a

' customize class creation.\n'

2883

n/a

'\n'

2884

n/a

'object.__init__(self[, ...])\n'

2885

n/a

'\n'

2886

n/a

' Called after the instance has been created (by '

2887

n/a

'"__new__()"), but\n'

2888

n/a

' before it is returned to the caller. The arguments are '

2889

n/a

'those\n'

2890

n/a

' passed to the class constructor expression. If a base '

2891

n/a

'class has an\n'

2892

n/a

' "__init__()" method, the derived class\'s "__init__()" '

2893

n/a

'method, if\n'

2894

n/a

' any, must explicitly call it to ensure proper '

2895

n/a

'initialization of the\n'

2896

n/a

' base class part of the instance; for example:\n'

2897

n/a

' "BaseClass.__init__(self, [args...])".\n'

2898

n/a

'\n'

2899

n/a

' Because "__new__()" and "__init__()" work together in '

2900

n/a

'constructing\n'

2901

n/a

' objects ("__new__()" to create it, and "__init__()" to '

2902

n/a

'customize\n'

2903

n/a

' it), no non-"None" value may be returned by '

2904

n/a

'"__init__()"; doing so\n'

2905

n/a

' will cause a "TypeError" to be raised at runtime.\n'

2906

n/a

'\n'

2907

n/a

'object.__del__(self)\n'

2908

n/a

'\n'

2909

n/a

' Called when the instance is about to be destroyed. This '

2910

n/a

'is also\n'

2911

n/a

' called a destructor. If a base class has a "__del__()" '

2912

n/a

'method, the\n'

2913

n/a

' derived class\'s "__del__()" method, if any, must '

2914

n/a

'explicitly call it\n'

2915

n/a

' to ensure proper deletion of the base class part of the '

2916

n/a

'instance.\n'

2917

n/a

' Note that it is possible (though not recommended!) for '

2918

n/a

'the\n'

2919

n/a

' "__del__()" method to postpone destruction of the '

2920

n/a

'instance by\n'

2921

n/a

' creating a new reference to it. It may then be called '

2922

n/a

'at a later\n'

2923

n/a

' time when this new reference is deleted. It is not '

2924

n/a

'guaranteed that\n'

2925

n/a

' "__del__()" methods are called for objects that still '

2926

n/a

'exist when\n'

2927

n/a

' the interpreter exits.\n'

2928

n/a

'\n'

2929

n/a

' Note: "del x" doesn\'t directly call "x.__del__()" --- '

2930

n/a

'the former\n'

2931

n/a

' decrements the reference count for "x" by one, and the '

2932

n/a

'latter is\n'

2933

n/a

' only called when "x"\'s reference count reaches zero. '

2934

n/a

'Some common\n'

2935

n/a

' situations that may prevent the reference count of an '

2936

n/a

'object from\n'

2937

n/a

' going to zero include: circular references between '

2938

n/a

'objects (e.g.,\n'

2939

n/a

' a doubly-linked list or a tree data structure with '

2940

n/a

'parent and\n'

2941

n/a

' child pointers); a reference to the object on the '

2942

n/a

'stack frame of\n'

2943

n/a

' a function that caught an exception (the traceback '

2944

n/a

'stored in\n'

2945

n/a

' "sys.exc_info()[2]" keeps the stack frame alive); or a '

2946

n/a

'reference\n'

2947

n/a

' to the object on the stack frame that raised an '

2948

n/a

'unhandled\n'

2949

n/a

' exception in interactive mode (the traceback stored '

2950

n/a

'in\n'

2951

n/a

' "sys.last_traceback" keeps the stack frame alive). '

2952

n/a

'The first\n'

2953

n/a

' situation can only be remedied by explicitly breaking '

2954

n/a

'the cycles;\n'

2955

n/a

' the second can be resolved by freeing the reference to '

2956

n/a

'the\n'

2957

n/a

' traceback object when it is no longer useful, and the '

2958

n/a

'third can\n'

2959

n/a

' be resolved by storing "None" in "sys.last_traceback". '

2960

n/a

'Circular\n'

2961

n/a

' references which are garbage are detected and cleaned '

2962

n/a

'up when the\n'

2963

n/a

" cyclic garbage collector is enabled (it's on by "

2964

n/a

'default). Refer\n'

2965

n/a

' to the documentation for the "gc" module for more '

2966

n/a

'information\n'

2967

n/a

' about this topic.\n'

2968

n/a

'\n'

2969

n/a

' Warning: Due to the precarious circumstances under '

2970

n/a

'which\n'

2971

n/a

' "__del__()" methods are invoked, exceptions that occur '

2972

n/a

'during\n'

2973

n/a

' their execution are ignored, and a warning is printed '

2974

n/a

'to\n'

2975

n/a

' "sys.stderr" instead. Also, when "__del__()" is '

2976

n/a

'invoked in\n'

2977

n/a

' response to a module being deleted (e.g., when '

2978

n/a

'execution of the\n'

2979

n/a

' program is done), other globals referenced by the '

2980

n/a

'"__del__()"\n'

2981

n/a

' method may already have been deleted or in the process '

2982

n/a

'of being\n'

2983

n/a

' torn down (e.g. the import machinery shutting down). '

2984

n/a

'For this\n'

2985

n/a

' reason, "__del__()" methods should do the absolute '

2986

n/a

'minimum needed\n'

2987

n/a

' to maintain external invariants. Starting with '

2988

n/a

'version 1.5,\n'

2989

n/a

' Python guarantees that globals whose name begins with '

2990

n/a

'a single\n'

2991

n/a

' underscore are deleted from their module before other '

2992

n/a

'globals are\n'

2993

n/a

' deleted; if no other references to such globals exist, '

2994

n/a

'this may\n'

2995

n/a

' help in assuring that imported modules are still '

2996

n/a

'available at the\n'

2997

n/a

' time when the "__del__()" method is called.\n'

2998

n/a

'\n'

2999

n/a

'object.__repr__(self)\n'

3000

n/a

'\n'

3001

n/a

' Called by the "repr()" built-in function to compute the '

3002

n/a

'"official"\n'

3003

n/a

' string representation of an object. If at all possible, '

3004

n/a

'this\n'

3005

n/a

' should look like a valid Python expression that could be '

3006

n/a

'used to\n'

3007

n/a

' recreate an object with the same value (given an '

3008

n/a

'appropriate\n'

3009

n/a

' environment). If this is not possible, a string of the '

3010

n/a

'form\n'

3011

n/a

' "<...some useful description...>" should be returned. '

3012

n/a

'The return\n'

3013

n/a

' value must be a string object. If a class defines '

3014

n/a

'"__repr__()" but\n'

3015

n/a

' not "__str__()", then "__repr__()" is also used when an '

3016

n/a

'"informal"\n'

3017

n/a

' string representation of instances of that class is '

3018

n/a

'required.\n'

3019

n/a

'\n'

3020

n/a

' This is typically used for debugging, so it is important '

3021

n/a

'that the\n'

3022

n/a

' representation is information-rich and unambiguous.\n'

3023

n/a

'\n'

3024

n/a

'object.__str__(self)\n'

3025

n/a

'\n'

3026

n/a

' Called by "str(object)" and the built-in functions '

3027

n/a

'"format()" and\n'

3028

n/a

' "print()" to compute the "informal" or nicely printable '

3029

n/a

'string\n'

3030

n/a

' representation of an object. The return value must be a '

3031

n/a

'string\n'

3032

n/a

' object.\n'

3033

n/a

'\n'

3034

n/a

' This method differs from "object.__repr__()" in that '

3035

n/a

'there is no\n'

3036

n/a

' expectation that "__str__()" return a valid Python '

3037

n/a

'expression: a\n'

3038

n/a

' more convenient or concise representation can be used.\n'

3039

n/a

'\n'

3040

n/a

' The default implementation defined by the built-in type '

3041

n/a

'"object"\n'

3042

n/a

' calls "object.__repr__()".\n'

3043

n/a

'\n'

3044

n/a

'object.__bytes__(self)\n'

3045

n/a

'\n'

3046

n/a

' Called by "bytes()" to compute a byte-string '

3047

n/a

'representation of an\n'

3048

n/a

' object. This should return a "bytes" object.\n'

3049

n/a

'\n'

3050

n/a

'object.__format__(self, format_spec)\n'

3051

n/a

'\n'

3052

n/a

' Called by the "format()" built-in function, and by '

3053

n/a

'extension,\n'

3054

n/a

' evaluation of formatted string literals and the '

3055

n/a

'"str.format()"\n'

3056

n/a

' method, to produce a "formatted" string representation '

3057

n/a

'of an\n'

3058

n/a

' object. The "format_spec" argument is a string that '

3059

n/a

'contains a\n'

3060

n/a

' description of the formatting options desired. The '

3061

n/a

'interpretation\n'

3062

n/a

' of the "format_spec" argument is up to the type '

3063

n/a

'implementing\n'

3064

n/a

' "__format__()", however most classes will either '

3065

n/a

'delegate\n'

3066

n/a

' formatting to one of the built-in types, or use a '

3067

n/a

'similar\n'

3068

n/a

' formatting option syntax.\n'

3069

n/a

'\n'

3070

n/a

' See Format Specification Mini-Language for a description '

3071

n/a

'of the\n'

3072

n/a

' standard formatting syntax.\n'

3073

n/a

'\n'

3074

n/a

' The return value must be a string object.\n'

3075

n/a

'\n'

3076

n/a

' Changed in version 3.4: The __format__ method of '

3077

n/a

'"object" itself\n'

3078

n/a

' raises a "TypeError" if passed any non-empty string.\n'

3079

n/a

'\n'

3080

n/a

'object.__lt__(self, other)\n'

3081

n/a

'object.__le__(self, other)\n'

3082

n/a

'object.__eq__(self, other)\n'

3083

n/a

'object.__ne__(self, other)\n'

3084

n/a

'object.__gt__(self, other)\n'

3085

n/a

'object.__ge__(self, other)\n'

3086

n/a

'\n'

3087

n/a

' These are the so-called "rich comparison" methods. The\n'

3088

n/a

' correspondence between operator symbols and method names '

3089

n/a

'is as\n'

3090

n/a

' follows: "x<y" calls "x.__lt__(y)", "x<=y" calls '

3091

n/a

'"x.__le__(y)",\n'

3092

n/a

' "x==y" calls "x.__eq__(y)", "x!=y" calls "x.__ne__(y)", '

3093

n/a

'"x>y" calls\n'

3094

n/a

' "x.__gt__(y)", and "x>=y" calls "x.__ge__(y)".\n'

3095

n/a

'\n'

3096

n/a

' A rich comparison method may return the singleton '

3097

n/a

'"NotImplemented"\n'

3098

n/a

' if it does not implement the operation for a given pair '

3099

n/a

'of\n'

3100

n/a

' arguments. By convention, "False" and "True" are '

3101

n/a

'returned for a\n'

3102

n/a

' successful comparison. However, these methods can return '

3103

n/a

'any value,\n'

3104

n/a

' so if the comparison operator is used in a Boolean '

3105

n/a

'context (e.g.,\n'

3106

n/a

' in the condition of an "if" statement), Python will call '

3107

n/a

'"bool()"\n'

3108

n/a

' on the value to determine if the result is true or '

3109

n/a

'false.\n'

3110

n/a

'\n'

3111

n/a

' By default, "__ne__()" delegates to "__eq__()" and '

3112

n/a

'inverts the\n'

3113

n/a

' result unless it is "NotImplemented". There are no '

3114

n/a

'other implied\n'

3115

n/a

' relationships among the comparison operators, for '

3116

n/a

'example, the\n'

3117

n/a

' truth of "(x<y or x==y)" does not imply "x<=y". To '

3118

n/a

'automatically\n'

3119

n/a

' generate ordering operations from a single root '

3120

n/a

'operation, see\n'

3121

n/a

' "functools.total_ordering()".\n'

3122

n/a

'\n'

3123

n/a

' See the paragraph on "__hash__()" for some important '

3124

n/a

'notes on\n'

3125

n/a

' creating *hashable* objects which support custom '

3126

n/a

'comparison\n'

3127

n/a

' operations and are usable as dictionary keys.\n'

3128

n/a

'\n'

3129

n/a

' There are no swapped-argument versions of these methods '

3130

n/a

'(to be used\n'

3131

n/a

' when the left argument does not support the operation '

3132

n/a

'but the right\n'

3133

n/a

' argument does); rather, "__lt__()" and "__gt__()" are '

3134

n/a

"each other's\n"

3135

n/a

' reflection, "__le__()" and "__ge__()" are each other\'s '

3136

n/a

'reflection,\n'

3137

n/a

' and "__eq__()" and "__ne__()" are their own reflection. '

3138

n/a

'If the\n'

3139

n/a

" operands are of different types, and right operand's "

3140

n/a

'type is a\n'

3141

n/a

" direct or indirect subclass of the left operand's type, "

3142

n/a

'the\n'

3143

n/a

' reflected method of the right operand has priority, '

3144

n/a

'otherwise the\n'

3145

n/a

" left operand's method has priority. Virtual subclassing "

3146

n/a

'is not\n'

3147

n/a

' considered.\n'

3148

n/a

'\n'

3149

n/a

'object.__hash__(self)\n'

3150

n/a

'\n'

3151

n/a

' Called by built-in function "hash()" and for operations '

3152

n/a

'on members\n'

3153

n/a

' of hashed collections including "set", "frozenset", and '

3154

n/a

'"dict".\n'

3155

n/a

' "__hash__()" should return an integer. The only '

3156

n/a

'required property\n'

3157

n/a

' is that objects which compare equal have the same hash '

3158

n/a

'value; it is\n'

3159

n/a

' advised to somehow mix together (e.g. using exclusive '

3160

n/a

'or) the hash\n'

3161

n/a

' values for the components of the object that also play a '

3162

n/a

'part in\n'

3163

n/a

' comparison of objects.\n'

3164

n/a

'\n'

3165

n/a

' Note: "hash()" truncates the value returned from an '

3166

n/a

"object's\n"

3167

n/a

' custom "__hash__()" method to the size of a '

3168

n/a

'"Py_ssize_t". This\n'

3169

n/a

' is typically 8 bytes on 64-bit builds and 4 bytes on '

3170

n/a

'32-bit\n'

3171

n/a

' builds. If an object\'s "__hash__()" must '

3172

n/a

'interoperate on builds\n'

3173

n/a

' of different bit sizes, be sure to check the width on '

3174

n/a

'all\n'

3175

n/a

' supported builds. An easy way to do this is with '

3176

n/a

'"python -c\n'

3177

n/a

' "import sys; print(sys.hash_info.width)"".\n'

3178

n/a

'\n'

3179

n/a

' If a class does not define an "__eq__()" method it '

3180

n/a

'should not\n'

3181

n/a

' define a "__hash__()" operation either; if it defines '

3182

n/a

'"__eq__()"\n'

3183

n/a

' but not "__hash__()", its instances will not be usable '

3184

n/a

'as items in\n'

3185

n/a

' hashable collections. If a class defines mutable '

3186

n/a

'objects and\n'

3187

n/a

' implements an "__eq__()" method, it should not '

3188

n/a

'implement\n'

3189

n/a

' "__hash__()", since the implementation of hashable '

3190

n/a

'collections\n'

3191

n/a

" requires that a key's hash value is immutable (if the "

3192

n/a

"object's hash\n"

3193

n/a

' value changes, it will be in the wrong hash bucket).\n'

3194

n/a

'\n'

3195

n/a

' User-defined classes have "__eq__()" and "__hash__()" '

3196

n/a

'methods by\n'

3197

n/a

' default; with them, all objects compare unequal (except '

3198

n/a

'with\n'

3199

n/a

' themselves) and "x.__hash__()" returns an appropriate '

3200

n/a

'value such\n'

3201

n/a

' that "x == y" implies both that "x is y" and "hash(x) == '

3202

n/a

'hash(y)".\n'

3203

n/a

'\n'

3204

n/a

' A class that overrides "__eq__()" and does not define '

3205

n/a

'"__hash__()"\n'

3206

n/a

' will have its "__hash__()" implicitly set to "None". '

3207

n/a

'When the\n'

3208

n/a

' "__hash__()" method of a class is "None", instances of '

3209

n/a

'the class\n'

3210

n/a

' will raise an appropriate "TypeError" when a program '

3211

n/a

'attempts to\n'

3212

n/a

' retrieve their hash value, and will also be correctly '

3213

n/a

'identified as\n'

3214

n/a

' unhashable when checking "isinstance(obj, '

3215

n/a

'collections.Hashable)".\n'

3216

n/a

'\n'

3217

n/a

' If a class that overrides "__eq__()" needs to retain '

3218

n/a

'the\n'

3219

n/a

' implementation of "__hash__()" from a parent class, the '

3220

n/a

'interpreter\n'

3221

n/a

' must be told this explicitly by setting "__hash__ =\n'

3222

n/a

' <ParentClass>.__hash__".\n'

3223

n/a

'\n'

3224

n/a

' If a class that does not override "__eq__()" wishes to '

3225

n/a

'suppress\n'

3226

n/a

' hash support, it should include "__hash__ = None" in the '

3227

n/a

'class\n'

3228

n/a

' definition. A class which defines its own "__hash__()" '

3229

n/a

'that\n'

3230

n/a

' explicitly raises a "TypeError" would be incorrectly '

3231

n/a

'identified as\n'

3232

n/a

' hashable by an "isinstance(obj, collections.Hashable)" '

3233

n/a

'call.\n'

3234

n/a

'\n'

3235

n/a

' Note: By default, the "__hash__()" values of str, bytes '

3236

n/a

'and\n'

3237

n/a

' datetime objects are "salted" with an unpredictable '

3238

n/a

'random value.\n'

3239

n/a

' Although they remain constant within an individual '

3240

n/a

'Python\n'

3241

n/a

' process, they are not predictable between repeated '

3242

n/a

'invocations of\n'

3243

n/a

' Python.This is intended to provide protection against '

3244

n/a

'a denial-\n'

3245

n/a

' of-service caused by carefully-chosen inputs that '

3246

n/a

'exploit the\n'

3247

n/a

' worst case performance of a dict insertion, O(n^2) '

3248

n/a

'complexity.\n'

3249

n/a

' See '

3250

n/a

'http://www.ocert.org/advisories/ocert-2011-003.html for\n'

3251

n/a

' details.Changing hash values affects the iteration '

3252

n/a

'order of\n'

3253

n/a

' dicts, sets and other mappings. Python has never made '

3254

n/a

'guarantees\n'

3255

n/a

' about this ordering (and it typically varies between '

3256

n/a

'32-bit and\n'

3257

n/a

' 64-bit builds).See also "PYTHONHASHSEED".\n'

3258

n/a

'\n'

3259

n/a

' Changed in version 3.3: Hash randomization is enabled by '

3260

n/a

'default.\n'

3261

n/a

'\n'

3262

n/a

'object.__bool__(self)\n'

3263

n/a

'\n'

3264

n/a

' Called to implement truth value testing and the built-in '

3265

n/a

'operation\n'

3266

n/a

' "bool()"; should return "False" or "True". When this '

3267

n/a

'method is not\n'

3268

n/a

' defined, "__len__()" is called, if it is defined, and '

3269

n/a

'the object is\n'

3270

n/a

' considered true if its result is nonzero. If a class '

3271

n/a

'defines\n'

3272

n/a

' neither "__len__()" nor "__bool__()", all its instances '

3273

n/a

'are\n'

3274

n/a

' considered true.\n',

3275

n/a

'debugger': '\n'

3276

n/a

'"pdb" --- The Python Debugger\n'

3277

n/a

'*****************************\n'

3278

n/a

'\n'

3279

n/a

'**Source code:** Lib/pdb.py\n'

3280

n/a

'\n'

3281

n/a

'======================================================================\n'

3282

n/a

'\n'

3283

n/a

'The module "pdb" defines an interactive source code debugger '

3284

n/a

'for\n'

3285

n/a

'Python programs. It supports setting (conditional) breakpoints '

3286

n/a

'and\n'

3287

n/a

'single stepping at the source line level, inspection of stack '

3288

n/a

'frames,\n'

3289

n/a

'source code listing, and evaluation of arbitrary Python code in '

3290

n/a

'the\n'

3291

n/a

'context of any stack frame. It also supports post-mortem '

3292

n/a

'debugging\n'

3293

n/a

'and can be called under program control.\n'

3294

n/a

'\n'

3295

n/a

'The debugger is extensible -- it is actually defined as the '

3296

n/a

'class\n'

3297

n/a

'"Pdb". This is currently undocumented but easily understood by '

3298

n/a

'reading\n'

3299

n/a

'the source. The extension interface uses the modules "bdb" and '

3300

n/a

'"cmd".\n'

3301

n/a

'\n'

3302

n/a

'The debugger\'s prompt is "(Pdb)". Typical usage to run a '

3303

n/a

'program under\n'

3304

n/a

'control of the debugger is:\n'

3305

n/a

'\n'

3306

n/a

' >>> import pdb\n'

3307

n/a

' >>> import mymodule\n'

3308

n/a

" >>> pdb.run('mymodule.test()')\n"

3309

n/a

' > <string>(0)?()\n'

3310

n/a

' (Pdb) continue\n'

3311

n/a

' > <string>(1)?()\n'

3312

n/a

' (Pdb) continue\n'

3313

n/a

" NameError: 'spam'\n"

3314

n/a

' > <string>(1)?()\n'

3315

n/a

' (Pdb)\n'

3316

n/a

'\n'

3317

n/a

'Changed in version 3.3: Tab-completion via the "readline" module '

3318

n/a

'is\n'

3319

n/a

'available for commands and command arguments, e.g. the current '

3320

n/a

'global\n'

3321

n/a

'and local names are offered as arguments of the "p" command.\n'

3322

n/a

'\n'

3323

n/a

'"pdb.py" can also be invoked as a script to debug other '

3324

n/a

'scripts. For\n'

3325

n/a

'example:\n'

3326

n/a

'\n'

3327

n/a

' python3 -m pdb myscript.py\n'

3328

n/a

'\n'

3329

n/a

'When invoked as a script, pdb will automatically enter '

3330

n/a

'post-mortem\n'

3331

n/a

'debugging if the program being debugged exits abnormally. After '

3332

n/a

'post-\n'

3333

n/a

'mortem debugging (or after normal exit of the program), pdb '

3334

n/a

'will\n'

3335

n/a

"restart the program. Automatic restarting preserves pdb's state "

3336

n/a

'(such\n'

3337

n/a

'as breakpoints) and in most cases is more useful than quitting '

3338

n/a

'the\n'

3339

n/a

"debugger upon program's exit.\n"

3340

n/a

'\n'

3341

n/a

'New in version 3.2: "pdb.py" now accepts a "-c" option that '

3342

n/a

'executes\n'

3343

n/a

'commands as if given in a ".pdbrc" file, see Debugger Commands.\n'

3344

n/a

'\n'

3345

n/a

'The typical usage to break into the debugger from a running '

3346

n/a

'program is\n'

3347

n/a

'to insert\n'

3348

n/a

'\n'

3349

n/a

' import pdb; pdb.set_trace()\n'

3350

n/a

'\n'

3351

n/a

'at the location you want to break into the debugger. You can '

3352

n/a

'then\n'

3353

n/a

'step through the code following this statement, and continue '

3354

n/a

'running\n'

3355

n/a

'without the debugger using the "continue" command.\n'

3356

n/a

'\n'

3357

n/a

'The typical usage to inspect a crashed program is:\n'

3358

n/a

'\n'

3359

n/a

' >>> import pdb\n'

3360

n/a

' >>> import mymodule\n'

3361

n/a

' >>> mymodule.test()\n'

3362

n/a

' Traceback (most recent call last):\n'

3363

n/a

' File "<stdin>", line 1, in ?\n'

3364

n/a

' File "./mymodule.py", line 4, in test\n'

3365

n/a

' test2()\n'

3366

n/a

' File "./mymodule.py", line 3, in test2\n'

3367

n/a

' print(spam)\n'

3368

n/a

' NameError: spam\n'

3369

n/a

' >>> pdb.pm()\n'

3370

n/a

' > ./mymodule.py(3)test2()\n'

3371

n/a

' -> print(spam)\n'

3372

n/a

' (Pdb)\n'

3373

n/a

'\n'

3374

n/a

'The module defines the following functions; each enters the '

3375

n/a

'debugger\n'

3376

n/a

'in a slightly different way:\n'

3377

n/a

'\n'

3378

n/a

'pdb.run(statement, globals=None, locals=None)\n'

3379

n/a

'\n'

3380

n/a

' Execute the *statement* (given as a string or a code object) '

3381

n/a

'under\n'

3382

n/a

' debugger control. The debugger prompt appears before any '

3383

n/a

'code is\n'

3384

n/a

' executed; you can set breakpoints and type "continue", or you '

3385

n/a

'can\n'

3386

n/a

' step through the statement using "step" or "next" (all these\n'

3387

n/a

' commands are explained below). The optional *globals* and '

3388

n/a

'*locals*\n'

3389

n/a

' arguments specify the environment in which the code is '

3390

n/a

'executed; by\n'

3391

n/a

' default the dictionary of the module "__main__" is used. '

3392

n/a

'(See the\n'

3393

n/a

' explanation of the built-in "exec()" or "eval()" functions.)\n'

3394

n/a

'\n'

3395

n/a

'pdb.runeval(expression, globals=None, locals=None)\n'

3396

n/a

'\n'

3397

n/a

' Evaluate the *expression* (given as a string or a code '

3398

n/a

'object)\n'

3399

n/a

' under debugger control. When "runeval()" returns, it returns '

3400

n/a

'the\n'

3401

n/a

' value of the expression. Otherwise this function is similar '

3402

n/a

'to\n'

3403

n/a

' "run()".\n'

3404

n/a

'\n'

3405

n/a

'pdb.runcall(function, *args, **kwds)\n'

3406

n/a

'\n'

3407

n/a

' Call the *function* (a function or method object, not a '

3408

n/a

'string)\n'

3409

n/a

' with the given arguments. When "runcall()" returns, it '

3410

n/a

'returns\n'

3411

n/a

' whatever the function call returned. The debugger prompt '

3412

n/a

'appears\n'

3413

n/a

' as soon as the function is entered.\n'

3414

n/a

'\n'

3415

n/a

'pdb.set_trace()\n'

3416

n/a

'\n'

3417

n/a

' Enter the debugger at the calling stack frame. This is '

3418

n/a

'useful to\n'

3419

n/a

' hard-code a breakpoint at a given point in a program, even if '

3420

n/a

'the\n'

3421

n/a

' code is not otherwise being debugged (e.g. when an assertion\n'

3422

n/a

' fails).\n'

3423

n/a

'\n'

3424

n/a

'pdb.post_mortem(traceback=None)\n'

3425

n/a

'\n'

3426

n/a

' Enter post-mortem debugging of the given *traceback* object. '

3427

n/a

'If no\n'

3428

n/a

' *traceback* is given, it uses the one of the exception that '

3429

n/a

'is\n'

3430

n/a

' currently being handled (an exception must be being handled '

3431

n/a

'if the\n'

3432

n/a

' default is to be used).\n'

3433

n/a

'\n'

3434

n/a

'pdb.pm()\n'

3435

n/a

'\n'

3436

n/a

' Enter post-mortem debugging of the traceback found in\n'

3437

n/a

' "sys.last_traceback".\n'

3438

n/a

'\n'

3439

n/a

'The "run*" functions and "set_trace()" are aliases for '

3440

n/a

'instantiating\n'

3441

n/a

'the "Pdb" class and calling the method of the same name. If you '

3442

n/a

'want\n'

3443

n/a

'to access further features, you have to do this yourself:\n'

3444

n/a

'\n'

3445

n/a

"class pdb.Pdb(completekey='tab', stdin=None, stdout=None, "

3446

n/a

'skip=None, nosigint=False, readrc=True)\n'

3447

n/a

'\n'

3448

n/a

' "Pdb" is the debugger class.\n'

3449

n/a

'\n'

3450

n/a

' The *completekey*, *stdin* and *stdout* arguments are passed '

3451

n/a

'to the\n'

3452

n/a

' underlying "cmd.Cmd" class; see the description there.\n'

3453

n/a

'\n'

3454

n/a

' The *skip* argument, if given, must be an iterable of '

3455

n/a

'glob-style\n'

3456

n/a

' module name patterns. The debugger will not step into frames '

3457

n/a

'that\n'

3458

n/a

' originate in a module that matches one of these patterns. '

3459

n/a

'[1]\n'

3460

n/a

'\n'

3461

n/a

' By default, Pdb sets a handler for the SIGINT signal (which '

3462

n/a

'is sent\n'

3463

n/a

' when the user presses "Ctrl-C" on the console) when you give '

3464

n/a

'a\n'

3465

n/a

' "continue" command. This allows you to break into the '

3466

n/a

'debugger\n'

3467

n/a

' again by pressing "Ctrl-C". If you want Pdb not to touch '

3468

n/a

'the\n'

3469

n/a

' SIGINT handler, set *nosigint* to true.\n'

3470

n/a

'\n'

3471

n/a

' The *readrc* argument defaults to true and controls whether '

3472

n/a

'Pdb\n'

3473

n/a

' will load .pdbrc files from the filesystem.\n'

3474

n/a

'\n'

3475

n/a

' Example call to enable tracing with *skip*:\n'

3476

n/a

'\n'

3477

n/a

" import pdb; pdb.Pdb(skip=['django.*']).set_trace()\n"

3478

n/a

'\n'

3479

n/a

' New in version 3.1: The *skip* argument.\n'

3480

n/a

'\n'

3481

n/a

' New in version 3.2: The *nosigint* argument. Previously, a '

3482

n/a

'SIGINT\n'

3483

n/a

' handler was never set by Pdb.\n'

3484

n/a

'\n'

3485

n/a

' Changed in version 3.6: The *readrc* argument.\n'

3486

n/a

'\n'

3487

n/a

' run(statement, globals=None, locals=None)\n'

3488

n/a

' runeval(expression, globals=None, locals=None)\n'

3489

n/a

' runcall(function, *args, **kwds)\n'

3490

n/a

' set_trace()\n'

3491

n/a

'\n'

3492

n/a

' See the documentation for the functions explained above.\n'

3493

n/a

'\n'

3494

n/a

'\n'

3495

n/a

'Debugger Commands\n'

3496

n/a

'=================\n'

3497

n/a

'\n'

3498

n/a

'The commands recognized by the debugger are listed below. Most\n'

3499

n/a

'commands can be abbreviated to one or two letters as indicated; '

3500

n/a

'e.g.\n'

3501

n/a

'"h(elp)" means that either "h" or "help" can be used to enter '

3502

n/a

'the help\n'

3503

n/a

'command (but not "he" or "hel", nor "H" or "Help" or "HELP").\n'

3504

n/a

'Arguments to commands must be separated by whitespace (spaces '

3505

n/a

'or\n'

3506

n/a

'tabs). Optional arguments are enclosed in square brackets '

3507

n/a

'("[]") in\n'

3508

n/a

'the command syntax; the square brackets must not be typed.\n'

3509

n/a

'Alternatives in the command syntax are separated by a vertical '

3510

n/a

'bar\n'

3511

n/a

'("|").\n'

3512

n/a

'\n'

3513

n/a

'Entering a blank line repeats the last command entered. '

3514

n/a

'Exception: if\n'

3515

n/a

'the last command was a "list" command, the next 11 lines are '

3516

n/a

'listed.\n'

3517

n/a

'\n'

3518

n/a

"Commands that the debugger doesn't recognize are assumed to be "

3519

n/a

'Python\n'

3520

n/a

'statements and are executed in the context of the program being\n'

3521

n/a

'debugged. Python statements can also be prefixed with an '

3522

n/a

'exclamation\n'

3523

n/a

'point ("!"). This is a powerful way to inspect the program '

3524

n/a

'being\n'

3525

n/a

'debugged; it is even possible to change a variable or call a '

3526

n/a

'function.\n'

3527

n/a

'When an exception occurs in such a statement, the exception name '

3528

n/a

'is\n'

3529

n/a

"printed but the debugger's state is not changed.\n"

3530

n/a

'\n'

3531

n/a

'The debugger supports aliases. Aliases can have parameters '

3532

n/a

'which\n'

3533

n/a

'allows one a certain level of adaptability to the context under\n'

3534

n/a

'examination.\n'

3535

n/a

'\n'

3536

n/a

'Multiple commands may be entered on a single line, separated by '

3537

n/a

'";;".\n'

3538

n/a

'(A single ";" is not used as it is the separator for multiple '

3539

n/a

'commands\n'

3540

n/a

'in a line that is passed to the Python parser.) No intelligence '

3541

n/a

'is\n'

3542

n/a

'applied to separating the commands; the input is split at the '

3543

n/a

'first\n'

3544

n/a

'";;" pair, even if it is in the middle of a quoted string.\n'

3545

n/a

'\n'

3546

n/a

'If a file ".pdbrc" exists in the user\'s home directory or in '

3547

n/a

'the\n'

3548

n/a

'current directory, it is read in and executed as if it had been '

3549

n/a

'typed\n'

3550

n/a

'at the debugger prompt. This is particularly useful for '

3551

n/a

'aliases. If\n'

3552

n/a

'both files exist, the one in the home directory is read first '

3553

n/a

'and\n'

3554

n/a

'aliases defined there can be overridden by the local file.\n'

3555

n/a

'\n'

3556

n/a

'Changed in version 3.2: ".pdbrc" can now contain commands that\n'

3557

n/a

'continue debugging, such as "continue" or "next". Previously, '

3558

n/a

'these\n'

3559

n/a

'commands had no effect.\n'

3560

n/a

'\n'

3561

n/a

'h(elp) [command]\n'

3562

n/a

'\n'

3563

n/a

' Without argument, print the list of available commands. With '

3564

n/a

'a\n'

3565

n/a

' *command* as argument, print help about that command. "help '

3566

n/a

'pdb"\n'

3567

n/a

' displays the full documentation (the docstring of the "pdb"\n'

3568

n/a

' module). Since the *command* argument must be an identifier, '

3569

n/a

'"help\n'

3570

n/a

' exec" must be entered to get help on the "!" command.\n'

3571

n/a

'\n'

3572

n/a

'w(here)\n'

3573

n/a

'\n'

3574

n/a

' Print a stack trace, with the most recent frame at the '

3575

n/a

'bottom. An\n'

3576

n/a

' arrow indicates the current frame, which determines the '

3577

n/a

'context of\n'

3578

n/a

' most commands.\n'

3579

n/a

'\n'

3580

n/a

'd(own) [count]\n'

3581

n/a

'\n'

3582

n/a

' Move the current frame *count* (default one) levels down in '

3583

n/a

'the\n'

3584

n/a

' stack trace (to a newer frame).\n'

3585

n/a

'\n'

3586

n/a

'u(p) [count]\n'

3587

n/a

'\n'

3588

n/a

' Move the current frame *count* (default one) levels up in the '

3589

n/a

'stack\n'

3590

n/a

' trace (to an older frame).\n'

3591

n/a

'\n'

3592

n/a

'b(reak) [([filename:]lineno | function) [, condition]]\n'

3593

n/a

'\n'

3594

n/a

' With a *lineno* argument, set a break there in the current '

3595

n/a

'file.\n'

3596

n/a

' With a *function* argument, set a break at the first '

3597

n/a

'executable\n'

3598

n/a

' statement within that function. The line number may be '

3599

n/a

'prefixed\n'

3600

n/a

' with a filename and a colon, to specify a breakpoint in '

3601

n/a

'another\n'

3602

n/a

" file (probably one that hasn't been loaded yet). The file "

3603

n/a

'is\n'

3604

n/a

' searched on "sys.path". Note that each breakpoint is '

3605

n/a

'assigned a\n'

3606

n/a

' number to which all the other breakpoint commands refer.\n'

3607

n/a

'\n'

3608

n/a

' If a second argument is present, it is an expression which '

3609

n/a

'must\n'

3610

n/a

' evaluate to true before the breakpoint is honored.\n'

3611

n/a

'\n'

3612

n/a

' Without argument, list all breaks, including for each '

3613

n/a

'breakpoint,\n'

3614

n/a

' the number of times that breakpoint has been hit, the '

3615

n/a

'current\n'

3616

n/a

' ignore count, and the associated condition if any.\n'

3617

n/a

'\n'

3618

n/a

'tbreak [([filename:]lineno | function) [, condition]]\n'

3619

n/a

'\n'

3620

n/a

' Temporary breakpoint, which is removed automatically when it '

3621

n/a

'is\n'

3622

n/a

' first hit. The arguments are the same as for "break".\n'

3623

n/a

'\n'

3624

n/a

'cl(ear) [filename:lineno | bpnumber [bpnumber ...]]\n'

3625

n/a

'\n'

3626

n/a

' With a *filename:lineno* argument, clear all the breakpoints '

3627

n/a

'at\n'

3628

n/a

' this line. With a space separated list of breakpoint numbers, '

3629

n/a

'clear\n'

3630

n/a

' those breakpoints. Without argument, clear all breaks (but '

3631

n/a

'first\n'

3632

n/a

' ask confirmation).\n'

3633

n/a

'\n'

3634

n/a

'disable [bpnumber [bpnumber ...]]\n'

3635

n/a

'\n'

3636

n/a

' Disable the breakpoints given as a space separated list of\n'

3637

n/a

' breakpoint numbers. Disabling a breakpoint means it cannot '

3638

n/a

'cause\n'

3639

n/a

' the program to stop execution, but unlike clearing a '

3640

n/a

'breakpoint, it\n'

3641

n/a

' remains in the list of breakpoints and can be (re-)enabled.\n'

3642

n/a

'\n'

3643

n/a

'enable [bpnumber [bpnumber ...]]\n'

3644

n/a

'\n'

3645

n/a

' Enable the breakpoints specified.\n'

3646

n/a

'\n'

3647

n/a

'ignore bpnumber [count]\n'

3648

n/a

'\n'

3649

n/a

' Set the ignore count for the given breakpoint number. If '

3650

n/a

'count is\n'

3651

n/a

' omitted, the ignore count is set to 0. A breakpoint becomes '

3652

n/a

'active\n'

3653

n/a

' when the ignore count is zero. When non-zero, the count is\n'

3654

n/a

' decremented each time the breakpoint is reached and the '

3655

n/a

'breakpoint\n'

3656

n/a

' is not disabled and any associated condition evaluates to '

3657

n/a

'true.\n'

3658

n/a

'\n'

3659

n/a

'condition bpnumber [condition]\n'

3660

n/a

'\n'

3661

n/a

' Set a new *condition* for the breakpoint, an expression which '

3662

n/a

'must\n'

3663

n/a

' evaluate to true before the breakpoint is honored. If '

3664

n/a

'*condition*\n'

3665

n/a

' is absent, any existing condition is removed; i.e., the '

3666

n/a

'breakpoint\n'

3667

n/a

' is made unconditional.\n'

3668

n/a

'\n'

3669

n/a

'commands [bpnumber]\n'

3670

n/a

'\n'

3671

n/a

' Specify a list of commands for breakpoint number *bpnumber*. '

3672

n/a

'The\n'

3673

n/a

' commands themselves appear on the following lines. Type a '

3674

n/a

'line\n'

3675

n/a

' containing just "end" to terminate the commands. An example:\n'

3676

n/a

'\n'

3677

n/a

' (Pdb) commands 1\n'

3678

n/a

' (com) p some_variable\n'

3679

n/a

' (com) end\n'

3680

n/a

' (Pdb)\n'

3681

n/a

'\n'

3682

n/a

' To remove all commands from a breakpoint, type commands and '

3683

n/a

'follow\n'

3684

n/a

' it immediately with "end"; that is, give no commands.\n'

3685

n/a

'\n'

3686

n/a

' With no *bpnumber* argument, commands refers to the last '

3687

n/a

'breakpoint\n'

3688

n/a

' set.\n'

3689

n/a

'\n'

3690

n/a

' You can use breakpoint commands to start your program up '

3691

n/a

'again.\n'

3692

n/a

' Simply use the continue command, or step, or any other '

3693

n/a

'command that\n'

3694

n/a

' resumes execution.\n'

3695

n/a

'\n'

3696

n/a

' Specifying any command resuming execution (currently '

3697

n/a

'continue,\n'

3698

n/a

' step, next, return, jump, quit and their abbreviations) '

3699

n/a

'terminates\n'

3700

n/a

' the command list (as if that command was immediately followed '

3701

n/a

'by\n'

3702

n/a

' end). This is because any time you resume execution (even '

3703

n/a

'with a\n'

3704

n/a

' simple next or step), you may encounter another '

3705

n/a

'breakpoint--which\n'

3706

n/a

' could have its own command list, leading to ambiguities about '

3707

n/a

'which\n'

3708

n/a

' list to execute.\n'

3709

n/a

'\n'

3710

n/a

" If you use the 'silent' command in the command list, the "

3711

n/a

'usual\n'

3712

n/a

' message about stopping at a breakpoint is not printed. This '

3713

n/a

'may be\n'

3714

n/a

' desirable for breakpoints that are to print a specific '

3715

n/a

'message and\n'

3716

n/a

' then continue. If none of the other commands print anything, '

3717

n/a

'you\n'

3718

n/a

' see no sign that the breakpoint was reached.\n'

3719

n/a

'\n'

3720

n/a

's(tep)\n'

3721

n/a

'\n'

3722

n/a

' Execute the current line, stop at the first possible '

3723

n/a

'occasion\n'

3724

n/a

' (either in a function that is called or on the next line in '

3725

n/a

'the\n'

3726

n/a

' current function).\n'

3727

n/a

'\n'

3728

n/a

'n(ext)\n'

3729

n/a

'\n'

3730

n/a

' Continue execution until the next line in the current '

3731

n/a

'function is\n'

3732

n/a

' reached or it returns. (The difference between "next" and '

3733

n/a

'"step"\n'

3734

n/a

' is that "step" stops inside a called function, while "next"\n'

3735

n/a

' executes called functions at (nearly) full speed, only '

3736

n/a

'stopping at\n'

3737

n/a

' the next line in the current function.)\n'

3738

n/a

'\n'

3739

n/a

'unt(il) [lineno]\n'

3740

n/a

'\n'

3741

n/a

' Without argument, continue execution until the line with a '

3742

n/a

'number\n'

3743

n/a

' greater than the current one is reached.\n'

3744

n/a

'\n'

3745

n/a

' With a line number, continue execution until a line with a '

3746

n/a

'number\n'

3747

n/a

' greater or equal to that is reached. In both cases, also '

3748

n/a

'stop when\n'

3749

n/a

' the current frame returns.\n'

3750

n/a

'\n'

3751

n/a

' Changed in version 3.2: Allow giving an explicit line '

3752

n/a

'number.\n'

3753

n/a

'\n'

3754

n/a

'r(eturn)\n'

3755

n/a

'\n'

3756

n/a

' Continue execution until the current function returns.\n'

3757

n/a

'\n'

3758

n/a

'c(ont(inue))\n'

3759

n/a

'\n'

3760

n/a

' Continue execution, only stop when a breakpoint is '

3761

n/a

'encountered.\n'

3762

n/a

'\n'

3763

n/a

'j(ump) lineno\n'

3764

n/a

'\n'

3765

n/a

' Set the next line that will be executed. Only available in '

3766

n/a

'the\n'

3767

n/a

' bottom-most frame. This lets you jump back and execute code '

3768

n/a

'again,\n'

3769

n/a

" or jump forward to skip code that you don't want to run.\n"

3770

n/a

'\n'

3771

n/a

' It should be noted that not all jumps are allowed -- for '

3772

n/a

'instance\n'

3773

n/a

' it is not possible to jump into the middle of a "for" loop or '

3774

n/a

'out\n'

3775

n/a

' of a "finally" clause.\n'

3776

n/a

'\n'

3777

n/a

'l(ist) [first[, last]]\n'

3778

n/a

'\n'

3779

n/a

' List source code for the current file. Without arguments, '

3780

n/a

'list 11\n'

3781

n/a

' lines around the current line or continue the previous '

3782

n/a

'listing.\n'

3783

n/a

' With "." as argument, list 11 lines around the current line. '

3784

n/a

'With\n'

3785

n/a

' one argument, list 11 lines around at that line. With two\n'

3786

n/a

' arguments, list the given range; if the second argument is '

3787

n/a

'less\n'

3788

n/a

' than the first, it is interpreted as a count.\n'

3789

n/a

'\n'

3790

n/a

' The current line in the current frame is indicated by "->". '

3791

n/a

'If an\n'

3792

n/a

' exception is being debugged, the line where the exception '

3793

n/a

'was\n'

3794

n/a

' originally raised or propagated is indicated by ">>", if it '

3795

n/a

'differs\n'

3796

n/a

' from the current line.\n'

3797

n/a

'\n'

3798

n/a

' New in version 3.2: The ">>" marker.\n'

3799

n/a

'\n'

3800

n/a

'll | longlist\n'

3801

n/a

'\n'

3802

n/a

' List all source code for the current function or frame.\n'

3803

n/a

' Interesting lines are marked as for "list".\n'

3804

n/a

'\n'

3805

n/a

' New in version 3.2.\n'

3806

n/a

'\n'

3807

n/a

'a(rgs)\n'

3808

n/a

'\n'

3809

n/a

' Print the argument list of the current function.\n'

3810

n/a

'\n'

3811

n/a

'p expression\n'

3812

n/a

'\n'

3813

n/a

' Evaluate the *expression* in the current context and print '

3814

n/a

'its\n'

3815

n/a

' value.\n'

3816

n/a

'\n'

3817

n/a

' Note: "print()" can also be used, but is not a debugger '

3818

n/a

'command\n'

3819

n/a

' --- this executes the Python "print()" function.\n'

3820

n/a

'\n'

3821

n/a

'pp expression\n'

3822

n/a

'\n'

3823

n/a

' Like the "p" command, except the value of the expression is '

3824

n/a

'pretty-\n'

3825

n/a

' printed using the "pprint" module.\n'

3826

n/a

'\n'

3827

n/a

'whatis expression\n'

3828

n/a

'\n'

3829

n/a

' Print the type of the *expression*.\n'

3830

n/a

'\n'

3831

n/a

'source expression\n'

3832

n/a

'\n'

3833

n/a

' Try to get source code for the given object and display it.\n'

3834

n/a

'\n'

3835

n/a

' New in version 3.2.\n'

3836

n/a

'\n'

3837

n/a

'display [expression]\n'

3838

n/a

'\n'

3839

n/a

' Display the value of the expression if it changed, each time\n'

3840

n/a

' execution stops in the current frame.\n'

3841

n/a

'\n'

3842

n/a

' Without expression, list all display expressions for the '

3843

n/a

'current\n'

3844

n/a

' frame.\n'

3845

n/a

'\n'

3846

n/a

' New in version 3.2.\n'

3847

n/a

'\n'

3848

n/a

'undisplay [expression]\n'

3849

n/a

'\n'

3850

n/a

' Do not display the expression any more in the current frame.\n'

3851

n/a

' Without expression, clear all display expressions for the '

3852

n/a

'current\n'

3853

n/a

' frame.\n'

3854

n/a

'\n'

3855

n/a

' New in version 3.2.\n'

3856

n/a

'\n'

3857

n/a

'interact\n'

3858

n/a

'\n'

3859

n/a

' Start an interactive interpreter (using the "code" module) '

3860

n/a

'whose\n'

3861

n/a

' global namespace contains all the (global and local) names '

3862

n/a

'found in\n'

3863

n/a

' the current scope.\n'

3864

n/a

'\n'

3865

n/a

' New in version 3.2.\n'

3866

n/a

'\n'

3867

n/a

'alias [name [command]]\n'

3868

n/a

'\n'

3869

n/a

' Create an alias called *name* that executes *command*. The '

3870

n/a

'command\n'

3871

n/a

' must *not* be enclosed in quotes. Replaceable parameters can '

3872

n/a

'be\n'

3873

n/a

' indicated by "%1", "%2", and so on, while "%*" is replaced by '

3874

n/a

'all\n'

3875

n/a

' the parameters. If no command is given, the current alias '

3876

n/a

'for\n'

3877

n/a

' *name* is shown. If no arguments are given, all aliases are '

3878

n/a

'listed.\n'

3879

n/a

'\n'

3880

n/a

' Aliases may be nested and can contain anything that can be '

3881

n/a

'legally\n'

3882

n/a

' typed at the pdb prompt. Note that internal pdb commands '

3883

n/a

'*can* be\n'

3884

n/a

' overridden by aliases. Such a command is then hidden until '

3885

n/a

'the\n'

3886

n/a

' alias is removed. Aliasing is recursively applied to the '

3887

n/a

'first\n'

3888

n/a

' word of the command line; all other words in the line are '

3889

n/a

'left\n'

3890

n/a

' alone.\n'

3891

n/a

'\n'

3892

n/a

' As an example, here are two useful aliases (especially when '

3893

n/a

'placed\n'

3894

n/a

' in the ".pdbrc" file):\n'

3895

n/a

'\n'

3896

n/a

' # Print instance variables (usage "pi classInst")\n'

3897

n/a

' alias pi for k in %1.__dict__.keys(): '

3898

n/a

'print("%1.",k,"=",%1.__dict__[k])\n'

3899

n/a

' # Print instance variables in self\n'

3900

n/a

' alias ps pi self\n'

3901

n/a

'\n'

3902

n/a

'unalias name\n'

3903

n/a

'\n'

3904

n/a

' Delete the specified alias.\n'

3905

n/a

'\n'

3906

n/a

'! statement\n'

3907

n/a

'\n'

3908

n/a

' Execute the (one-line) *statement* in the context of the '

3909

n/a

'current\n'

3910

n/a

' stack frame. The exclamation point can be omitted unless the '

3911

n/a

'first\n'

3912

n/a

' word of the statement resembles a debugger command. To set '

3913

n/a

'a\n'

3914

n/a

' global variable, you can prefix the assignment command with '

3915

n/a

'a\n'

3916

n/a

' "global" statement on the same line, e.g.:\n'

3917

n/a

'\n'

3918

n/a

" (Pdb) global list_options; list_options = ['-l']\n"

3919

n/a

' (Pdb)\n'

3920

n/a

'\n'

3921

n/a

'run [args ...]\n'

3922

n/a

'restart [args ...]\n'

3923

n/a

'\n'

3924

n/a

' Restart the debugged Python program. If an argument is '

3925

n/a

'supplied,\n'

3926

n/a

' it is split with "shlex" and the result is used as the new\n'

3927

n/a

' "sys.argv". History, breakpoints, actions and debugger '

3928

n/a

'options are\n'

3929

n/a

' preserved. "restart" is an alias for "run".\n'

3930

n/a

'\n'

3931

n/a

'q(uit)\n'

3932

n/a

'\n'

3933

n/a

' Quit from the debugger. The program being executed is '

3934

n/a

'aborted.\n'

3935

n/a

'\n'

3936

n/a

'-[ Footnotes ]-\n'

3937

n/a

'\n'

3938

n/a

'[1] Whether a frame is considered to originate in a certain '

3939

n/a

'module\n'

3940

n/a

' is determined by the "__name__" in the frame globals.\n',

3941

n/a

'del': '\n'

3942

n/a

'The "del" statement\n'

3943

n/a

'*******************\n'

3944

n/a

'\n'

3945

n/a

' del_stmt ::= "del" target_list\n'

3946

n/a

'\n'

3947

n/a

'Deletion is recursively defined very similar to the way assignment '

3948

n/a

'is\n'

3949

n/a

'defined. Rather than spelling it out in full details, here are some\n'

3950

n/a

'hints.\n'

3951

n/a

'\n'

3952

n/a

'Deletion of a target list recursively deletes each target, from left\n'

3953

n/a

'to right.\n'

3954

n/a

'\n'

3955

n/a

'Deletion of a name removes the binding of that name from the local '

3956

n/a

'or\n'

3957

n/a

'global namespace, depending on whether the name occurs in a "global"\n'

3958

n/a

'statement in the same code block. If the name is unbound, a\n'

3959

n/a

'"NameError" exception will be raised.\n'

3960

n/a

'\n'

3961

n/a

'Deletion of attribute references, subscriptions and slicings is '

3962

n/a

'passed\n'

3963

n/a

'to the primary object involved; deletion of a slicing is in general\n'

3964

n/a

'equivalent to assignment of an empty slice of the right type (but '

3965

n/a

'even\n'

3966

n/a

'this is determined by the sliced object).\n'

3967

n/a

'\n'

3968

n/a

'Changed in version 3.2: Previously it was illegal to delete a name\n'

3969

n/a

'from the local namespace if it occurs as a free variable in a nested\n'

3970

n/a

'block.\n',

3971

n/a

'dict': '\n'

3972

n/a

'Dictionary displays\n'

3973

n/a

'*******************\n'

3974

n/a

'\n'

3975

n/a

'A dictionary display is a possibly empty series of key/datum pairs\n'

3976

n/a

'enclosed in curly braces:\n'

3977

n/a

'\n'

3978

n/a

' dict_display ::= "{" [key_datum_list | dict_comprehension] '

3979

n/a

'"}"\n'

3980

n/a

' key_datum_list ::= key_datum ("," key_datum)* [","]\n'

3981

n/a

' key_datum ::= expression ":" expression | "**" or_expr\n'

3982

n/a

' dict_comprehension ::= expression ":" expression comp_for\n'

3983

n/a

'\n'

3984

n/a

'A dictionary display yields a new dictionary object.\n'

3985

n/a

'\n'

3986

n/a

'If a comma-separated sequence of key/datum pairs is given, they are\n'

3987

n/a

'evaluated from left to right to define the entries of the '

3988

n/a

'dictionary:\n'

3989

n/a

'each key object is used as a key into the dictionary to store the\n'

3990

n/a

'corresponding datum. This means that you can specify the same key\n'

3991

n/a

"multiple times in the key/datum list, and the final dictionary's "

3992

n/a

'value\n'

3993

n/a

'for that key will be the last one given.\n'

3994

n/a

'\n'

3995

n/a

'A double asterisk "**" denotes *dictionary unpacking*. Its operand\n'

3996

n/a

'must be a *mapping*. Each mapping item is added to the new\n'

3997

n/a

'dictionary. Later values replace values already set by earlier\n'

3998

n/a

'key/datum pairs and earlier dictionary unpackings.\n'

3999

n/a

'\n'

4000

n/a

'New in version 3.5: Unpacking into dictionary displays, originally\n'

4001

n/a

'proposed by **PEP 448**.\n'

4002

n/a

'\n'

4003

n/a

'A dict comprehension, in contrast to list and set comprehensions,\n'

4004

n/a

'needs two expressions separated with a colon followed by the usual\n'

4005

n/a

'"for" and "if" clauses. When the comprehension is run, the '

4006

n/a

'resulting\n'

4007

n/a

'key and value elements are inserted in the new dictionary in the '

4008

n/a

'order\n'

4009

n/a

'they are produced.\n'

4010

n/a

'\n'

4011

n/a

'Restrictions on the types of the key values are listed earlier in\n'

4012

n/a

'section The standard type hierarchy. (To summarize, the key type\n'

4013

n/a

'should be *hashable*, which excludes all mutable objects.) Clashes\n'

4014

n/a

'between duplicate keys are not detected; the last datum (textually\n'

4015

n/a

'rightmost in the display) stored for a given key value prevails.\n',

4016

n/a

'dynamic-features': '\n'

4017

n/a

'Interaction with dynamic features\n'

4018

n/a

'*********************************\n'

4019

n/a

'\n'

4020

n/a

'Name resolution of free variables occurs at runtime, not '

4021

n/a

'at compile\n'

4022

n/a

'time. This means that the following code will print 42:\n'

4023

n/a

'\n'

4024

n/a

' i = 10\n'

4025

n/a

' def f():\n'

4026

n/a

' print(i)\n'

4027

n/a

' i = 42\n'

4028

n/a

' f()\n'

4029

n/a

'\n'

4030

n/a

'There are several cases where Python statements are '

4031

n/a

'illegal when used\n'

4032

n/a

'in conjunction with nested scopes that contain free '

4033

n/a

'variables.\n'

4034

n/a

'\n'

4035

n/a

'If a variable is referenced in an enclosing scope, it is '

4036

n/a

'illegal to\n'

4037

n/a

'delete the name. An error will be reported at compile '

4038

n/a

'time.\n'

4039

n/a

'\n'

4040

n/a

'The "eval()" and "exec()" functions do not have access '

4041

n/a

'to the full\n'

4042

n/a

'environment for resolving names. Names may be resolved '

4043

n/a

'in the local\n'

4044

n/a

'and global namespaces of the caller. Free variables are '

4045

n/a

'not resolved\n'

4046

n/a

'in the nearest enclosing namespace, but in the global '

4047

n/a

'namespace. [1]\n'

4048

n/a

'The "exec()" and "eval()" functions have optional '

4049

n/a

'arguments to\n'

4050

n/a

'override the global and local namespace. If only one '

4051

n/a

'namespace is\n'

4052

n/a

'specified, it is used for both.\n',

4053

n/a

'else': '\n'

4054

n/a

'The "if" statement\n'

4055

n/a

'******************\n'

4056

n/a

'\n'

4057

n/a

'The "if" statement is used for conditional execution:\n'

4058

n/a

'\n'

4059

n/a

' if_stmt ::= "if" expression ":" suite\n'

4060

n/a

' ( "elif" expression ":" suite )*\n'

4061

n/a

' ["else" ":" suite]\n'

4062

n/a

'\n'

4063

n/a

'It selects exactly one of the suites by evaluating the expressions '

4064

n/a

'one\n'

4065

n/a

'by one until one is found to be true (see section Boolean '

4066

n/a

'operations\n'

4067

n/a

'for the definition of true and false); then that suite is executed\n'

4068

n/a

'(and no other part of the "if" statement is executed or evaluated).\n'

4069

n/a

'If all expressions are false, the suite of the "else" clause, if\n'

4070

n/a

'present, is executed.\n',

4071

n/a

'exceptions': '\n'

4072

n/a

'Exceptions\n'

4073

n/a

'**********\n'

4074

n/a

'\n'

4075

n/a

'Exceptions are a means of breaking out of the normal flow of '

4076

n/a

'control\n'

4077

n/a

'of a code block in order to handle errors or other '

4078

n/a

'exceptional\n'

4079

n/a

'conditions. An exception is *raised* at the point where the '

4080

n/a

'error is\n'

4081

n/a

'detected; it may be *handled* by the surrounding code block or '

4082

n/a

'by any\n'

4083

n/a

'code block that directly or indirectly invoked the code block '

4084

n/a

'where\n'

4085

n/a

'the error occurred.\n'

4086

n/a

'\n'

4087

n/a

'The Python interpreter raises an exception when it detects a '

4088

n/a

'run-time\n'

4089

n/a

'error (such as division by zero). A Python program can also\n'

4090

n/a

'explicitly raise an exception with the "raise" statement. '

4091

n/a

'Exception\n'

4092

n/a

'handlers are specified with the "try" ... "except" statement. '

4093

n/a

'The\n'

4094

n/a

'"finally" clause of such a statement can be used to specify '

4095

n/a

'cleanup\n'

4096

n/a

'code which does not handle the exception, but is executed '

4097

n/a

'whether an\n'

4098

n/a

'exception occurred or not in the preceding code.\n'

4099

n/a

'\n'

4100

n/a

'Python uses the "termination" model of error handling: an '

4101

n/a

'exception\n'

4102

n/a

'handler can find out what happened and continue execution at '

4103

n/a

'an outer\n'

4104

n/a

'level, but it cannot repair the cause of the error and retry '

4105

n/a

'the\n'

4106

n/a

'failing operation (except by re-entering the offending piece '

4107

n/a

'of code\n'

4108

n/a

'from the top).\n'

4109

n/a

'\n'

4110

n/a

'When an exception is not handled at all, the interpreter '

4111

n/a

'terminates\n'

4112

n/a

'execution of the program, or returns to its interactive main '

4113

n/a

'loop. In\n'

4114

n/a

'either case, it prints a stack backtrace, except when the '

4115

n/a

'exception is\n'

4116

n/a

'"SystemExit".\n'

4117

n/a

'\n'

4118

n/a

'Exceptions are identified by class instances. The "except" '

4119

n/a

'clause is\n'

4120

n/a

'selected depending on the class of the instance: it must '

4121

n/a

'reference the\n'

4122

n/a

'class of the instance or a base class thereof. The instance '

4123

n/a

'can be\n'

4124

n/a

'received by the handler and can carry additional information '

4125

n/a

'about the\n'

4126

n/a

'exceptional condition.\n'

4127

n/a

'\n'

4128

n/a

'Note: Exception messages are not part of the Python API. '

4129

n/a

'Their\n'

4130

n/a

' contents may change from one version of Python to the next '

4131

n/a

'without\n'

4132

n/a

' warning and should not be relied on by code which will run '

4133

n/a

'under\n'

4134

n/a

' multiple versions of the interpreter.\n'

4135

n/a

'\n'

4136

n/a

'See also the description of the "try" statement in section The '

4137

n/a

'try\n'

4138

n/a

'statement and "raise" statement in section The raise '

4139

n/a

'statement.\n'

4140

n/a

'\n'

4141

n/a

'-[ Footnotes ]-\n'

4142

n/a

'\n'

4143

n/a

'[1] This limitation occurs because the code that is executed '

4144

n/a

'by\n'

4145

n/a

' these operations is not available at the time the module '

4146

n/a

'is\n'

4147

n/a

' compiled.\n',

4148

n/a

'execmodel': '\n'

4149

n/a

'Execution model\n'

4150

n/a

'***************\n'

4151

n/a

'\n'

4152

n/a

'\n'

4153

n/a

'Structure of a program\n'

4154

n/a

'======================\n'

4155

n/a

'\n'

4156

n/a

'A Python program is constructed from code blocks. A *block* is '

4157

n/a

'a piece\n'

4158

n/a

'of Python program text that is executed as a unit. The '

4159

n/a

'following are\n'

4160

n/a

'blocks: a module, a function body, and a class definition. '

4161

n/a

'Each\n'

4162

n/a

'command typed interactively is a block. A script file (a file '

4163

n/a

'given\n'

4164

n/a

'as standard input to the interpreter or specified as a command '

4165

n/a

'line\n'

4166

n/a

'argument to the interpreter) is a code block. A script command '

4167

n/a

'(a\n'

4168

n/a

'command specified on the interpreter command line with the '

4169

n/a

"'**-c**'\n"

4170

n/a

'option) is a code block. The string argument passed to the '

4171

n/a

'built-in\n'

4172

n/a

'functions "eval()" and "exec()" is a code block.\n'

4173

n/a

'\n'

4174

n/a

'A code block is executed in an *execution frame*. A frame '

4175

n/a

'contains\n'

4176

n/a

'some administrative information (used for debugging) and '

4177

n/a

'determines\n'

4178

n/a

"where and how execution continues after the code block's "

4179

n/a

'execution has\n'

4180

n/a

'completed.\n'

4181

n/a

'\n'

4182

n/a

'\n'

4183

n/a

'Naming and binding\n'

4184

n/a

'==================\n'

4185

n/a

'\n'

4186

n/a

'\n'

4187

n/a

'Binding of names\n'

4188

n/a

'----------------\n'

4189

n/a

'\n'

4190

n/a

'*Names* refer to objects. Names are introduced by name '

4191

n/a

'binding\n'

4192

n/a

'operations.\n'

4193

n/a

'\n'

4194

n/a

'The following constructs bind names: formal parameters to '

4195

n/a

'functions,\n'

4196

n/a

'"import" statements, class and function definitions (these bind '

4197

n/a

'the\n'

4198

n/a

'class or function name in the defining block), and targets that '

4199

n/a

'are\n'

4200

n/a

'identifiers if occurring in an assignment, "for" loop header, '

4201

n/a

'or after\n'

4202

n/a

'"as" in a "with" statement or "except" clause. The "import" '

4203

n/a

'statement\n'

4204

n/a

'of the form "from ... import *" binds all names defined in the\n'

4205

n/a

'imported module, except those beginning with an underscore. '

4206

n/a

'This form\n'

4207

n/a

'may only be used at the module level.\n'

4208

n/a

'\n'

4209

n/a

'A target occurring in a "del" statement is also considered '

4210

n/a

'bound for\n'

4211

n/a

'this purpose (though the actual semantics are to unbind the '

4212

n/a

'name).\n'

4213

n/a

'\n'

4214

n/a

'Each assignment or import statement occurs within a block '

4215

n/a

'defined by a\n'

4216

n/a

'class or function definition or at the module level (the '

4217

n/a

'top-level\n'

4218

n/a

'code block).\n'

4219

n/a

'\n'

4220

n/a

'If a name is bound in a block, it is a local variable of that '

4221

n/a

'block,\n'

4222

n/a

'unless declared as "nonlocal" or "global". If a name is bound '

4223

n/a

'at the\n'

4224

n/a

'module level, it is a global variable. (The variables of the '

4225

n/a

'module\n'

4226

n/a

'code block are local and global.) If a variable is used in a '

4227

n/a

'code\n'

4228

n/a

'block but not defined there, it is a *free variable*.\n'

4229

n/a

'\n'

4230

n/a

'Each occurrence of a name in the program text refers to the '

4231

n/a

'*binding*\n'

4232

n/a

'of that name established by the following name resolution '

4233

n/a

'rules.\n'

4234

n/a

'\n'

4235

n/a

'\n'

4236

n/a

'Resolution of names\n'

4237

n/a

'-------------------\n'

4238

n/a

'\n'

4239

n/a

'A *scope* defines the visibility of a name within a block. If '

4240

n/a

'a local\n'

4241

n/a

'variable is defined in a block, its scope includes that block. '

4242

n/a

'If the\n'

4243

n/a

'definition occurs in a function block, the scope extends to any '

4244

n/a

'blocks\n'

4245

n/a

'contained within the defining one, unless a contained block '

4246

n/a

'introduces\n'

4247

n/a

'a different binding for the name.\n'

4248

n/a

'\n'

4249

n/a

'When a name is used in a code block, it is resolved using the '

4250

n/a

'nearest\n'

4251

n/a

'enclosing scope. The set of all such scopes visible to a code '

4252

n/a

'block\n'

4253

n/a

"is called the block's *environment*.\n"

4254

n/a

'\n'

4255

n/a

'When a name is not found at all, a "NameError" exception is '

4256

n/a

'raised. If\n'

4257

n/a

'the current scope is a function scope, and the name refers to a '

4258

n/a

'local\n'

4259

n/a

'variable that has not yet been bound to a value at the point '

4260

n/a

'where the\n'

4261

n/a

'name is used, an "UnboundLocalError" exception is raised.\n'

4262

n/a

'"UnboundLocalError" is a subclass of "NameError".\n'

4263

n/a

'\n'

4264

n/a

'If a name binding operation occurs anywhere within a code '

4265

n/a

'block, all\n'

4266

n/a

'uses of the name within the block are treated as references to '

4267

n/a

'the\n'

4268

n/a

'current block. This can lead to errors when a name is used '

4269

n/a

'within a\n'

4270

n/a

'block before it is bound. This rule is subtle. Python lacks\n'

4271

n/a

'declarations and allows name binding operations to occur '

4272

n/a

'anywhere\n'

4273

n/a

'within a code block. The local variables of a code block can '

4274

n/a

'be\n'

4275

n/a

'determined by scanning the entire text of the block for name '

4276

n/a

'binding\n'

4277

n/a

'operations.\n'

4278

n/a

'\n'

4279

n/a

'If the "global" statement occurs within a block, all uses of '

4280

n/a

'the name\n'

4281

n/a

'specified in the statement refer to the binding of that name in '

4282

n/a

'the\n'

4283

n/a

'top-level namespace. Names are resolved in the top-level '

4284

n/a

'namespace by\n'

4285

n/a

'searching the global namespace, i.e. the namespace of the '

4286

n/a

'module\n'

4287

n/a

'containing the code block, and the builtins namespace, the '

4288

n/a

'namespace\n'

4289

n/a

'of the module "builtins". The global namespace is searched '

4290

n/a

'first. If\n'

4291

n/a

'the name is not found there, the builtins namespace is '

4292

n/a

'searched. The\n'

4293

n/a

'"global" statement must precede all uses of the name.\n'

4294

n/a

'\n'

4295

n/a

'The "global" statement has the same scope as a name binding '

4296

n/a

'operation\n'

4297

n/a

'in the same block. If the nearest enclosing scope for a free '

4298

n/a

'variable\n'

4299

n/a

'contains a global statement, the free variable is treated as a '

4300

n/a

'global.\n'

4301

n/a

'\n'

4302

n/a

'The "nonlocal" statement causes corresponding names to refer '

4303

n/a

'to\n'

4304

n/a

'previously bound variables in the nearest enclosing function '

4305

n/a

'scope.\n'

4306

n/a

'"SyntaxError" is raised at compile time if the given name does '

4307

n/a

'not\n'

4308

n/a

'exist in any enclosing function scope.\n'

4309

n/a

'\n'

4310

n/a

'The namespace for a module is automatically created the first '

4311

n/a

'time a\n'

4312

n/a

'module is imported. The main module for a script is always '

4313

n/a

'called\n'

4314

n/a

'"__main__".\n'

4315

n/a

'\n'

4316

n/a

'Class definition blocks and arguments to "exec()" and "eval()" '

4317

n/a

'are\n'

4318

n/a

'special in the context of name resolution. A class definition '

4319

n/a

'is an\n'

4320

n/a

'executable statement that may use and define names. These '

4321

n/a

'references\n'

4322

n/a

'follow the normal rules for name resolution with an exception '

4323

n/a

'that\n'

4324

n/a

'unbound local variables are looked up in the global namespace. '

4325

n/a

'The\n'

4326

n/a

'namespace of the class definition becomes the attribute '

4327

n/a

'dictionary of\n'

4328

n/a

'the class. The scope of names defined in a class block is '

4329

n/a

'limited to\n'

4330

n/a

'the class block; it does not extend to the code blocks of '

4331

n/a

'methods --\n'

4332

n/a

'this includes comprehensions and generator expressions since '

4333

n/a

'they are\n'

4334

n/a

'implemented using a function scope. This means that the '

4335

n/a

'following\n'

4336

n/a

'will fail:\n'

4337

n/a

'\n'

4338

n/a

' class A:\n'

4339

n/a

' a = 42\n'

4340

n/a

' b = list(a + i for i in range(10))\n'

4341

n/a

'\n'

4342

n/a

'\n'

4343

n/a

'Builtins and restricted execution\n'

4344

n/a

'---------------------------------\n'

4345

n/a

'\n'

4346

n/a

'The builtins namespace associated with the execution of a code '

4347

n/a

'block\n'

4348

n/a

'is actually found by looking up the name "__builtins__" in its '

4349

n/a

'global\n'

4350

n/a

'namespace; this should be a dictionary or a module (in the '

4351

n/a

'latter case\n'

4352

n/a

"the module's dictionary is used). By default, when in the "

4353

n/a

'"__main__"\n'

4354

n/a

'module, "__builtins__" is the built-in module "builtins"; when '

4355

n/a

'in any\n'

4356

n/a

'other module, "__builtins__" is an alias for the dictionary of '

4357

n/a

'the\n'

4358

n/a

'"builtins" module itself. "__builtins__" can be set to a '

4359

n/a

'user-created\n'

4360

n/a

'dictionary to create a weak form of restricted execution.\n'

4361

n/a

'\n'

4362

n/a

'**CPython implementation detail:** Users should not touch\n'

4363

n/a

'"__builtins__"; it is strictly an implementation detail. '

4364

n/a

'Users\n'

4365

n/a

'wanting to override values in the builtins namespace should '

4366

n/a

'"import"\n'

4367

n/a

'the "builtins" module and modify its attributes appropriately.\n'

4368

n/a

'\n'

4369

n/a

'\n'

4370

n/a

'Interaction with dynamic features\n'

4371

n/a

'---------------------------------\n'

4372

n/a

'\n'

4373

n/a

'Name resolution of free variables occurs at runtime, not at '

4374

n/a

'compile\n'

4375

n/a

'time. This means that the following code will print 42:\n'

4376

n/a

'\n'

4377

n/a

' i = 10\n'

4378

n/a

' def f():\n'

4379

n/a

' print(i)\n'

4380

n/a

' i = 42\n'

4381

n/a

' f()\n'

4382

n/a

'\n'

4383

n/a

'There are several cases where Python statements are illegal '

4384

n/a

'when used\n'

4385

n/a

'in conjunction with nested scopes that contain free variables.\n'

4386

n/a

'\n'

4387

n/a

'If a variable is referenced in an enclosing scope, it is '

4388

n/a

'illegal to\n'

4389

n/a

'delete the name. An error will be reported at compile time.\n'

4390

n/a

'\n'

4391

n/a

'The "eval()" and "exec()" functions do not have access to the '

4392

n/a

'full\n'

4393

n/a

'environment for resolving names. Names may be resolved in the '

4394

n/a

'local\n'

4395

n/a

'and global namespaces of the caller. Free variables are not '

4396

n/a

'resolved\n'

4397

n/a

'in the nearest enclosing namespace, but in the global '

4398

n/a

'namespace. [1]\n'

4399

n/a

'The "exec()" and "eval()" functions have optional arguments to\n'

4400

n/a

'override the global and local namespace. If only one namespace '

4401

n/a

'is\n'

4402

n/a

'specified, it is used for both.\n'

4403

n/a

'\n'

4404

n/a

'\n'

4405

n/a

'Exceptions\n'

4406

n/a

'==========\n'

4407

n/a

'\n'

4408

n/a

'Exceptions are a means of breaking out of the normal flow of '

4409

n/a

'control\n'

4410

n/a

'of a code block in order to handle errors or other exceptional\n'

4411

n/a

'conditions. An exception is *raised* at the point where the '

4412

n/a

'error is\n'

4413

n/a

'detected; it may be *handled* by the surrounding code block or '

4414

n/a

'by any\n'

4415

n/a

'code block that directly or indirectly invoked the code block '

4416

n/a

'where\n'

4417

n/a

'the error occurred.\n'

4418

n/a

'\n'

4419

n/a

'The Python interpreter raises an exception when it detects a '

4420

n/a

'run-time\n'

4421

n/a

'error (such as division by zero). A Python program can also\n'

4422

n/a

'explicitly raise an exception with the "raise" statement. '

4423

n/a

'Exception\n'

4424

n/a

'handlers are specified with the "try" ... "except" statement. '

4425

n/a

'The\n'

4426

n/a

'"finally" clause of such a statement can be used to specify '

4427

n/a

'cleanup\n'

4428

n/a

'code which does not handle the exception, but is executed '

4429

n/a

'whether an\n'

4430

n/a

'exception occurred or not in the preceding code.\n'

4431

n/a

'\n'

4432

n/a

'Python uses the "termination" model of error handling: an '

4433

n/a

'exception\n'

4434

n/a

'handler can find out what happened and continue execution at an '

4435

n/a

'outer\n'

4436

n/a

'level, but it cannot repair the cause of the error and retry '

4437

n/a

'the\n'

4438

n/a

'failing operation (except by re-entering the offending piece of '

4439

n/a

'code\n'

4440

n/a

'from the top).\n'

4441

n/a

'\n'

4442

n/a

'When an exception is not handled at all, the interpreter '

4443

n/a

'terminates\n'

4444

n/a

'execution of the program, or returns to its interactive main '

4445

n/a

'loop. In\n'

4446

n/a

'either case, it prints a stack backtrace, except when the '

4447

n/a

'exception is\n'

4448

n/a

'"SystemExit".\n'

4449

n/a

'\n'

4450

n/a

'Exceptions are identified by class instances. The "except" '

4451

n/a

'clause is\n'

4452

n/a

'selected depending on the class of the instance: it must '

4453

n/a

'reference the\n'

4454

n/a

'class of the instance or a base class thereof. The instance '

4455

n/a

'can be\n'

4456

n/a

'received by the handler and can carry additional information '

4457

n/a

'about the\n'

4458

n/a

'exceptional condition.\n'

4459

n/a

'\n'

4460

n/a

'Note: Exception messages are not part of the Python API. '

4461

n/a

'Their\n'

4462

n/a

' contents may change from one version of Python to the next '

4463

n/a

'without\n'

4464

n/a

' warning and should not be relied on by code which will run '

4465

n/a

'under\n'

4466

n/a

' multiple versions of the interpreter.\n'

4467

n/a

'\n'

4468

n/a

'See also the description of the "try" statement in section The '

4469

n/a

'try\n'

4470

n/a

'statement and "raise" statement in section The raise '

4471

n/a

'statement.\n'

4472

n/a

'\n'

4473

n/a

'-[ Footnotes ]-\n'

4474

n/a

'\n'

4475

n/a

'[1] This limitation occurs because the code that is executed '

4476

n/a

'by\n'

4477

n/a

' these operations is not available at the time the module '

4478

n/a

'is\n'

4479

n/a

' compiled.\n',

4480

n/a

'exprlists': '\n'

4481

n/a

'Expression lists\n'

4482

n/a

'****************\n'

4483

n/a

'\n'

4484

n/a

' expression_list ::= expression ( "," expression )* [","]\n'

4485

n/a

' starred_list ::= starred_item ( "," starred_item )* '

4486

n/a

'[","]\n'

4487

n/a

' starred_expression ::= expression | ( starred_item "," )* '

4488

n/a

'[starred_item]\n'

4489

n/a

' starred_item ::= expression | "*" or_expr\n'

4490

n/a

'\n'

4491

n/a

'Except when part of a list or set display, an expression list\n'

4492

n/a

'containing at least one comma yields a tuple. The length of '

4493

n/a

'the tuple\n'

4494

n/a

'is the number of expressions in the list. The expressions are\n'

4495

n/a

'evaluated from left to right.\n'

4496

n/a

'\n'

4497

n/a

'An asterisk "*" denotes *iterable unpacking*. Its operand must '

4498

n/a

'be an\n'

4499

n/a

'*iterable*. The iterable is expanded into a sequence of items, '

4500

n/a

'which\n'

4501

n/a

'are included in the new tuple, list, or set, at the site of '

4502

n/a

'the\n'

4503

n/a

'unpacking.\n'

4504

n/a

'\n'

4505

n/a

'New in version 3.5: Iterable unpacking in expression lists, '

4506

n/a

'originally\n'

4507

n/a

'proposed by **PEP 448**.\n'

4508

n/a

'\n'

4509

n/a

'The trailing comma is required only to create a single tuple '

4510

n/a

'(a.k.a. a\n'

4511

n/a

'*singleton*); it is optional in all other cases. A single '

4512

n/a

'expression\n'

4513

n/a

"without a trailing comma doesn't create a tuple, but rather "

4514

n/a

'yields the\n'

4515

n/a

'value of that expression. (To create an empty tuple, use an '

4516

n/a

'empty pair\n'

4517

n/a

'of parentheses: "()".)\n',

4518

n/a

'floating': '\n'

4519

n/a

'Floating point literals\n'

4520

n/a

'***********************\n'

4521

n/a

'\n'

4522

n/a

'Floating point literals are described by the following lexical\n'

4523

n/a

'definitions:\n'

4524

n/a

'\n'

4525

n/a

' floatnumber ::= pointfloat | exponentfloat\n'

4526

n/a

' pointfloat ::= [digitpart] fraction | digitpart "."\n'

4527

n/a

' exponentfloat ::= (digitpart | pointfloat) exponent\n'

4528

n/a

' digitpart ::= digit (["_"] digit)*\n'

4529

n/a

' fraction ::= "." digitpart\n'

4530

n/a

' exponent ::= ("e" | "E") ["+" | "-"] digitpart\n'

4531

n/a

'\n'

4532

n/a

'Note that the integer and exponent parts are always interpreted '

4533

n/a

'using\n'

4534

n/a

'radix 10. For example, "077e010" is legal, and denotes the same '

4535

n/a

'number\n'

4536

n/a

'as "77e10". The allowed range of floating point literals is\n'

4537

n/a

'implementation-dependent. As in integer literals, underscores '

4538

n/a

'are\n'

4539

n/a

'supported for digit grouping.\n'

4540

n/a

'\n'

4541

n/a

'Some examples of floating point literals:\n'

4542

n/a

'\n'

4543

n/a

' 3.14 10. .001 1e100 3.14e-10 0e0 '

4544

n/a

'3.14_15_93\n'

4545

n/a

'\n'

4546

n/a

'Note that numeric literals do not include a sign; a phrase like '

4547

n/a

'"-1"\n'

4548

n/a

'is actually an expression composed of the unary operator "-" and '

4549

n/a

'the\n'

4550

n/a

'literal "1".\n'

4551

n/a

'\n'

4552

n/a

'Changed in version 3.6: Underscores are now allowed for '

4553

n/a

'grouping\n'

4554

n/a

'purposes in literals.\n',

4555

n/a

'for': '\n'

4556

n/a

'The "for" statement\n'

4557

n/a

'*******************\n'

4558

n/a

'\n'

4559

n/a

'The "for" statement is used to iterate over the elements of a '

4560

n/a

'sequence\n'

4561

n/a

'(such as a string, tuple or list) or other iterable object:\n'

4562

n/a

'\n'

4563

n/a

' for_stmt ::= "for" target_list "in" expression_list ":" suite\n'

4564

n/a

' ["else" ":" suite]\n'

4565

n/a

'\n'

4566

n/a

'The expression list is evaluated once; it should yield an iterable\n'

4567

n/a

'object. An iterator is created for the result of the\n'

4568

n/a

'"expression_list". The suite is then executed once for each item\n'

4569

n/a

'provided by the iterator, in the order returned by the iterator. '

4570

n/a

'Each\n'

4571

n/a

'item in turn is assigned to the target list using the standard rules\n'

4572

n/a

'for assignments (see Assignment statements), and then the suite is\n'

4573

n/a

'executed. When the items are exhausted (which is immediately when '

4574

n/a

'the\n'

4575

n/a

'sequence is empty or an iterator raises a "StopIteration" '

4576

n/a

'exception),\n'

4577

n/a

'the suite in the "else" clause, if present, is executed, and the '

4578

n/a

'loop\n'

4579

n/a

'terminates.\n'

4580

n/a

'\n'

4581

n/a

'A "break" statement executed in the first suite terminates the loop\n'

4582

n/a

'without executing the "else" clause\'s suite. A "continue" '

4583

n/a

'statement\n'

4584

n/a

'executed in the first suite skips the rest of the suite and '

4585

n/a

'continues\n'

4586

n/a

'with the next item, or with the "else" clause if there is no next\n'

4587

n/a

'item.\n'

4588

n/a

'\n'

4589

n/a

'The for-loop makes assignments to the variables(s) in the target '

4590

n/a

'list.\n'

4591

n/a

'This overwrites all previous assignments to those variables '

4592

n/a

'including\n'

4593

n/a

'those made in the suite of the for-loop:\n'

4594

n/a

'\n'

4595

n/a

' for i in range(10):\n'

4596

n/a

' print(i)\n'

4597

n/a

' i = 5 # this will not affect the for-loop\n'

4598

n/a

' # because i will be overwritten with the '

4599

n/a

'next\n'

4600

n/a

' # index in the range\n'

4601

n/a

'\n'

4602

n/a

'Names in the target list are not deleted when the loop is finished,\n'

4603

n/a

'but if the sequence is empty, they will not have been assigned to at\n'

4604

n/a

'all by the loop. Hint: the built-in function "range()" returns an\n'

4605

n/a

'iterator of integers suitable to emulate the effect of Pascal\'s "for '

4606

n/a

'i\n'

4607

n/a

':= a to b do"; e.g., "list(range(3))" returns the list "[0, 1, 2]".\n'

4608

n/a

'\n'

4609

n/a

'Note: There is a subtlety when the sequence is being modified by the\n'

4610

n/a

' loop (this can only occur for mutable sequences, i.e. lists). An\n'

4611

n/a

' internal counter is used to keep track of which item is used next,\n'

4612

n/a

' and this is incremented on each iteration. When this counter has\n'

4613

n/a

' reached the length of the sequence the loop terminates. This '

4614

n/a

'means\n'

4615

n/a

' that if the suite deletes the current (or a previous) item from '

4616

n/a

'the\n'

4617

n/a

' sequence, the next item will be skipped (since it gets the index '

4618

n/a

'of\n'

4619

n/a

' the current item which has already been treated). Likewise, if '

4620

n/a

'the\n'

4621

n/a

' suite inserts an item in the sequence before the current item, the\n'

4622

n/a

' current item will be treated again the next time through the loop.\n'

4623

n/a

' This can lead to nasty bugs that can be avoided by making a\n'

4624

n/a

' temporary copy using a slice of the whole sequence, e.g.,\n'

4625

n/a

'\n'

4626

n/a

' for x in a[:]:\n'

4627

n/a

' if x < 0: a.remove(x)\n',

4628

n/a

'formatstrings': '\n'

4629

n/a

'Format String Syntax\n'

4630

n/a

'********************\n'

4631

n/a

'\n'

4632

n/a

'The "str.format()" method and the "Formatter" class share '

4633

n/a

'the same\n'

4634

n/a

'syntax for format strings (although in the case of '

4635

n/a

'"Formatter",\n'

4636

n/a

'subclasses can define their own format string syntax). The '

4637

n/a

'syntax is\n'

4638

n/a

'related to that of formatted string literals, but there '

4639

n/a

'are\n'

4640

n/a

'differences.\n'

4641

n/a

'\n'

4642

n/a

'Format strings contain "replacement fields" surrounded by '

4643

n/a

'curly braces\n'

4644

n/a

'"{}". Anything that is not contained in braces is '

4645

n/a

'considered literal\n'

4646

n/a

'text, which is copied unchanged to the output. If you need '

4647

n/a

'to include\n'

4648

n/a

'a brace character in the literal text, it can be escaped by '

4649

n/a

'doubling:\n'

4650

n/a

'"{{" and "}}".\n'

4651

n/a

'\n'

4652

n/a

'The grammar for a replacement field is as follows:\n'

4653

n/a

'\n'

4654

n/a

' replacement_field ::= "{" [field_name] ["!" '

4655

n/a

'conversion] [":" format_spec] "}"\n'

4656

n/a

' field_name ::= arg_name ("." attribute_name | '

4657

n/a

'"[" element_index "]")*\n'

4658

n/a

' arg_name ::= [identifier | integer]\n'

4659

n/a

' attribute_name ::= identifier\n'

4660

n/a

' element_index ::= integer | index_string\n'

4661

n/a

' index_string ::= <any source character except '

4662

n/a

'"]"> +\n'

4663

n/a

' conversion ::= "r" | "s" | "a"\n'

4664

n/a

' format_spec ::= <described in the next '

4665

n/a

'section>\n'

4666

n/a

'\n'

4667

n/a

'In less formal terms, the replacement field can start with '

4668

n/a

'a\n'

4669

n/a

'*field_name* that specifies the object whose value is to be '

4670

n/a

'formatted\n'

4671

n/a

'and inserted into the output instead of the replacement '

4672

n/a

'field. The\n'

4673

n/a

'*field_name* is optionally followed by a *conversion* '

4674

n/a

'field, which is\n'

4675

n/a

'preceded by an exclamation point "\'!\'", and a '

4676

n/a

'*format_spec*, which is\n'

4677

n/a

'preceded by a colon "\':\'". These specify a non-default '

4678

n/a

'format for the\n'

4679

n/a

'replacement value.\n'

4680

n/a

'\n'

4681

n/a

'See also the Format Specification Mini-Language section.\n'

4682

n/a

'\n'

4683

n/a

'The *field_name* itself begins with an *arg_name* that is '

4684

n/a

'either a\n'

4685

n/a

"number or a keyword. If it's a number, it refers to a "

4686

n/a

'positional\n'

4687

n/a

"argument, and if it's a keyword, it refers to a named "

4688

n/a

'keyword\n'

4689

n/a

'argument. If the numerical arg_names in a format string '

4690

n/a

'are 0, 1, 2,\n'

4691

n/a

'... in sequence, they can all be omitted (not just some) '

4692

n/a

'and the\n'

4693

n/a

'numbers 0, 1, 2, ... will be automatically inserted in that '

4694

n/a

'order.\n'

4695

n/a

'Because *arg_name* is not quote-delimited, it is not '

4696

n/a

'possible to\n'

4697

n/a

'specify arbitrary dictionary keys (e.g., the strings '

4698

n/a

'"\'10\'" or\n'

4699

n/a

'"\':-]\'") within a format string. The *arg_name* can be '

4700

n/a

'followed by any\n'

4701

n/a

'number of index or attribute expressions. An expression of '

4702

n/a

'the form\n'

4703

n/a

'"\'.name\'" selects the named attribute using "getattr()", '

4704

n/a

'while an\n'

4705

n/a

'expression of the form "\'[index]\'" does an index lookup '

4706

n/a

'using\n'

4707

n/a

'"__getitem__()".\n'

4708

n/a

'\n'

4709

n/a

'Changed in version 3.1: The positional argument specifiers '

4710

n/a

'can be\n'

4711

n/a

'omitted, so "\'{} {}\'" is equivalent to "\'{0} {1}\'".\n'

4712

n/a

'\n'

4713

n/a

'Some simple format string examples:\n'

4714

n/a

'\n'

4715

n/a

' "First, thou shalt count to {0}" # References first '

4716

n/a

'positional argument\n'

4717

n/a

' "Bring me a {}" # Implicitly '

4718

n/a

'references the first positional argument\n'

4719

n/a

' "From {} to {}" # Same as "From {0} to '

4720

n/a

'{1}"\n'

4721

n/a

' "My quest is {name}" # References keyword '

4722

n/a

"argument 'name'\n"

4723

n/a

' "Weight in tons {0.weight}" # \'weight\' attribute '

4724

n/a

'of first positional arg\n'

4725

n/a

' "Units destroyed: {players[0]}" # First element of '

4726

n/a

"keyword argument 'players'.\n"

4727

n/a

'\n'

4728

n/a

'The *conversion* field causes a type coercion before '

4729

n/a

'formatting.\n'

4730

n/a

'Normally, the job of formatting a value is done by the '

4731

n/a

'"__format__()"\n'

4732

n/a

'method of the value itself. However, in some cases it is '

4733

n/a

'desirable to\n'

4734

n/a

'force a type to be formatted as a string, overriding its '

4735

n/a

'own\n'

4736

n/a

'definition of formatting. By converting the value to a '

4737

n/a

'string before\n'

4738

n/a

'calling "__format__()", the normal formatting logic is '

4739

n/a

'bypassed.\n'

4740

n/a

'\n'

4741

n/a

'Three conversion flags are currently supported: "\'!s\'" '

4742

n/a

'which calls\n'

4743

n/a

'"str()" on the value, "\'!r\'" which calls "repr()" and '

4744

n/a

'"\'!a\'" which\n'

4745

n/a

'calls "ascii()".\n'

4746

n/a

'\n'

4747

n/a

'Some examples:\n'

4748

n/a

'\n'

4749

n/a

' "Harold\'s a clever {0!s}" # Calls str() on the '

4750

n/a

'argument first\n'

4751

n/a

' "Bring out the holy {name!r}" # Calls repr() on the '

4752

n/a

'argument first\n'

4753

n/a

' "More {!a}" # Calls ascii() on the '

4754

n/a

'argument first\n'

4755

n/a

'\n'

4756

n/a

'The *format_spec* field contains a specification of how the '

4757

n/a

'value\n'

4758

n/a

'should be presented, including such details as field width, '

4759

n/a

'alignment,\n'

4760

n/a

'padding, decimal precision and so on. Each value type can '

4761

n/a

'define its\n'

4762

n/a

'own "formatting mini-language" or interpretation of the '

4763

n/a

'*format_spec*.\n'

4764

n/a

'\n'

4765

n/a

'Most built-in types support a common formatting '

4766

n/a

'mini-language, which\n'

4767

n/a

'is described in the next section.\n'

4768

n/a

'\n'

4769

n/a

'A *format_spec* field can also include nested replacement '

4770

n/a

'fields\n'

4771

n/a

'within it. These nested replacement fields may contain a '

4772

n/a

'field name,\n'

4773

n/a

'conversion flag and format specification, but deeper '

4774

n/a

'nesting is not\n'

4775

n/a

'allowed. The replacement fields within the format_spec '

4776

n/a

'are\n'

4777

n/a

'substituted before the *format_spec* string is interpreted. '

4778

n/a

'This\n'

4779

n/a

'allows the formatting of a value to be dynamically '

4780

n/a

'specified.\n'

4781

n/a

'\n'

4782

n/a

'See the Format examples section for some examples.\n'

4783

n/a

'\n'

4784

n/a

'\n'

4785

n/a

'Format Specification Mini-Language\n'

4786

n/a

'==================================\n'

4787

n/a

'\n'

4788

n/a

'"Format specifications" are used within replacement fields '

4789

n/a

'contained\n'

4790

n/a

'within a format string to define how individual values are '

4791

n/a

'presented\n'

4792

n/a

'(see Format String Syntax and Formatted string literals). '

4793

n/a

'They can\n'

4794

n/a

'also be passed directly to the built-in "format()" '

4795

n/a

'function. Each\n'

4796

n/a

'formattable type may define how the format specification is '

4797

n/a

'to be\n'

4798

n/a

'interpreted.\n'

4799

n/a

'\n'

4800

n/a

'Most built-in types implement the following options for '

4801

n/a

'format\n'

4802

n/a

'specifications, although some of the formatting options are '

4803

n/a

'only\n'

4804

n/a

'supported by the numeric types.\n'

4805

n/a

'\n'

4806

n/a

'A general convention is that an empty format string ("""") '

4807

n/a

'produces\n'

4808

n/a

'the same result as if you had called "str()" on the value. '

4809

n/a

'A non-empty\n'

4810

n/a

'format string typically modifies the result.\n'

4811

n/a

'\n'

4812

n/a

'The general form of a *standard format specifier* is:\n'

4813

n/a

'\n'

4814

n/a

' format_spec ::= '

4815

n/a

'[[fill]align][sign][#][0][width][grouping_option][.precision][type]\n'

4816

n/a

' fill ::= <any character>\n'

4817

n/a

' align ::= "<" | ">" | "=" | "^"\n'

4818

n/a

' sign ::= "+" | "-" | " "\n'

4819

n/a

' width ::= integer\n'

4820

n/a

' grouping_option ::= "_" | ","\n'

4821

n/a

' precision ::= integer\n'

4822

n/a

' type ::= "b" | "c" | "d" | "e" | "E" | "f" | '

4823

n/a

'"F" | "g" | "G" | "n" | "o" | "s" | "x" | "X" | "%"\n'

4824

n/a

'\n'

4825

n/a

'If a valid *align* value is specified, it can be preceded '

4826

n/a

'by a *fill*\n'

4827

n/a

'character that can be any character and defaults to a space '

4828

n/a

'if\n'

4829

n/a

'omitted. It is not possible to use a literal curly brace '

4830

n/a

'(""{"" or\n'

4831

n/a

'""}"") as the *fill* character in a formatted string '

4832

n/a

'literal or when\n'

4833

n/a

'using the "str.format()" method. However, it is possible '

4834

n/a

'to insert a\n'

4835

n/a

'curly brace with a nested replacement field. This '

4836

n/a

"limitation doesn't\n"

4837

n/a

'affect the "format()" function.\n'

4838

n/a

'\n'

4839

n/a

'The meaning of the various alignment options is as '

4840

n/a

'follows:\n'

4841

n/a

'\n'

4842

n/a

' '

4843

n/a

'+-----------+------------------------------------------------------------+\n'

4844

n/a

' | Option | '

4845

n/a

'Meaning '

4846

n/a

'|\n'

4847

n/a

' '

4848

n/a

'+===========+============================================================+\n'

4849

n/a

' | "\'<\'" | Forces the field to be left-aligned '

4850

n/a

'within the available |\n'

4851

n/a

' | | space (this is the default for most '

4852

n/a

'objects). |\n'

4853

n/a

' '

4854

n/a

'+-----------+------------------------------------------------------------+\n'

4855

n/a

' | "\'>\'" | Forces the field to be right-aligned '

4856

n/a

'within the available |\n'

4857

n/a

' | | space (this is the default for '

4858

n/a

'numbers). |\n'

4859

n/a

' '

4860

n/a

'+-----------+------------------------------------------------------------+\n'

4861

n/a

' | "\'=\'" | Forces the padding to be placed after '

4862

n/a

'the sign (if any) |\n'

4863

n/a

' | | but before the digits. This is used for '

4864

n/a

'printing fields |\n'

4865

n/a

" | | in the form '+000000120'. This alignment "

4866

n/a

'option is only |\n'

4867

n/a

' | | valid for numeric types. It becomes the '

4868

n/a

"default when '0' |\n"

4869

n/a

' | | immediately precedes the field '

4870

n/a

'width. |\n'

4871

n/a

' '

4872

n/a

'+-----------+------------------------------------------------------------+\n'

4873

n/a

' | "\'^\'" | Forces the field to be centered within '

4874

n/a

'the available |\n'

4875

n/a

' | | '

4876

n/a

'space. '

4877

n/a

'|\n'

4878

n/a

' '

4879

n/a

'+-----------+------------------------------------------------------------+\n'

4880

n/a

'\n'

4881

n/a

'Note that unless a minimum field width is defined, the '

4882

n/a

'field width\n'

4883

n/a

'will always be the same size as the data to fill it, so '

4884

n/a

'that the\n'

4885

n/a

'alignment option has no meaning in this case.\n'

4886

n/a

'\n'

4887

n/a

'The *sign* option is only valid for number types, and can '

4888

n/a

'be one of\n'

4889

n/a

'the following:\n'

4890

n/a

'\n'

4891

n/a

' '

4892

n/a

'+-----------+------------------------------------------------------------+\n'

4893

n/a

' | Option | '

4894

n/a

'Meaning '

4895

n/a

'|\n'

4896

n/a

' '

4897

n/a

'+===========+============================================================+\n'

4898

n/a

' | "\'+\'" | indicates that a sign should be used for '

4899

n/a

'both positive as |\n'

4900

n/a

' | | well as negative '

4901

n/a

'numbers. |\n'

4902

n/a

' '

4903

n/a

'+-----------+------------------------------------------------------------+\n'

4904

n/a

' | "\'-\'" | indicates that a sign should be used '

4905

n/a

'only for negative |\n'

4906

n/a

' | | numbers (this is the default '

4907

n/a

'behavior). |\n'

4908

n/a

' '

4909

n/a

'+-----------+------------------------------------------------------------+\n'

4910

n/a

' | space | indicates that a leading space should be '

4911

n/a

'used on positive |\n'

4912

n/a

' | | numbers, and a minus sign on negative '

4913

n/a

'numbers. |\n'

4914

n/a

' '

4915

n/a

'+-----------+------------------------------------------------------------+\n'

4916

n/a

'\n'

4917

n/a

'The "\'#\'" option causes the "alternate form" to be used '

4918

n/a

'for the\n'

4919

n/a

'conversion. The alternate form is defined differently for '

4920

n/a

'different\n'

4921

n/a

'types. This option is only valid for integer, float, '

4922

n/a

'complex and\n'

4923

n/a

'Decimal types. For integers, when binary, octal, or '

4924

n/a

'hexadecimal output\n'

4925

n/a

'is used, this option adds the prefix respective "\'0b\'", '

4926

n/a

'"\'0o\'", or\n'

4927

n/a

'"\'0x\'" to the output value. For floats, complex and '

4928

n/a

'Decimal the\n'

4929

n/a

'alternate form causes the result of the conversion to '

4930

n/a

'always contain a\n'

4931

n/a

'decimal-point character, even if no digits follow it. '

4932

n/a

'Normally, a\n'

4933

n/a

'decimal-point character appears in the result of these '

4934

n/a

'conversions\n'

4935

n/a

'only if a digit follows it. In addition, for "\'g\'" and '

4936

n/a

'"\'G\'"\n'

4937

n/a

'conversions, trailing zeros are not removed from the '

4938

n/a

'result.\n'

4939

n/a

'\n'

4940

n/a

'The "\',\'" option signals the use of a comma for a '

4941

n/a

'thousands separator.\n'

4942

n/a

'For a locale aware separator, use the "\'n\'" integer '

4943

n/a

'presentation type\n'

4944

n/a

'instead.\n'

4945

n/a

'\n'

4946

n/a

'Changed in version 3.1: Added the "\',\'" option (see also '

4947

n/a

'**PEP 378**).\n'

4948

n/a

'\n'

4949

n/a

'The "\'_\'" option signals the use of an underscore for a '

4950

n/a

'thousands\n'

4951

n/a

'separator for floating point presentation types and for '

4952

n/a

'integer\n'

4953

n/a

'presentation type "\'d\'". For integer presentation types '

4954

n/a

'"\'b\'", "\'o\'",\n'

4955

n/a

'"\'x\'", and "\'X\'", underscores will be inserted every 4 '

4956

n/a

'digits. For\n'

4957

n/a

'other presentation types, specifying this option is an '

4958

n/a

'error.\n'

4959

n/a

'\n'

4960

n/a

'Changed in version 3.6: Added the "\'_\'" option (see also '

4961

n/a

'**PEP 515**).\n'

4962

n/a

'\n'

4963

n/a

'*width* is a decimal integer defining the minimum field '

4964

n/a

'width. If not\n'

4965

n/a

'specified, then the field width will be determined by the '

4966

n/a

'content.\n'

4967

n/a

'\n'

4968

n/a

'When no explicit alignment is given, preceding the *width* '

4969

n/a

'field by a\n'

4970

n/a

'zero ("\'0\'") character enables sign-aware zero-padding '

4971

n/a

'for numeric\n'

4972

n/a

'types. This is equivalent to a *fill* character of "\'0\'" '

4973

n/a

'with an\n'

4974

n/a

'*alignment* type of "\'=\'".\n'

4975

n/a

'\n'

4976

n/a

'The *precision* is a decimal number indicating how many '

4977

n/a

'digits should\n'

4978

n/a

'be displayed after the decimal point for a floating point '

4979

n/a

'value\n'

4980

n/a

'formatted with "\'f\'" and "\'F\'", or before and after the '

4981

n/a

'decimal point\n'

4982

n/a

'for a floating point value formatted with "\'g\'" or '

4983

n/a

'"\'G\'". For non-\n'

4984

n/a

'number types the field indicates the maximum field size - '

4985

n/a

'in other\n'

4986

n/a

'words, how many characters will be used from the field '

4987

n/a

'content. The\n'

4988

n/a

'*precision* is not allowed for integer values.\n'

4989

n/a

'\n'

4990

n/a

'Finally, the *type* determines how the data should be '

4991

n/a

'presented.\n'

4992

n/a

'\n'

4993

n/a

'The available string presentation types are:\n'

4994

n/a

'\n'

4995

n/a

' '

4996

n/a

'+-----------+------------------------------------------------------------+\n'

4997

n/a

' | Type | '

4998

n/a

'Meaning '

4999

n/a

'|\n'

5000

n/a

' '

5001

n/a

'+===========+============================================================+\n'

5002

n/a

' | "\'s\'" | String format. This is the default type '

5003

n/a

'for strings and |\n'

5004

n/a

' | | may be '

5005

n/a

'omitted. |\n'

5006

n/a

' '

5007

n/a

'+-----------+------------------------------------------------------------+\n'

5008

n/a

' | None | The same as '

5009

n/a

'"\'s\'". |\n'

5010

n/a

' '

5011

n/a

'+-----------+------------------------------------------------------------+\n'

5012

n/a

'\n'

5013

n/a

'The available integer presentation types are:\n'

5014

n/a

'\n'

5015

n/a

' '

5016

n/a

'+-----------+------------------------------------------------------------+\n'

5017

n/a

' | Type | '

5018

n/a

'Meaning '

5019

n/a

'|\n'

5020

n/a

' '

5021

n/a

'+===========+============================================================+\n'

5022

n/a

' | "\'b\'" | Binary format. Outputs the number in '

5023

n/a

'base 2. |\n'

5024

n/a

' '

5025

n/a

'+-----------+------------------------------------------------------------+\n'

5026

n/a

' | "\'c\'" | Character. Converts the integer to the '

5027

n/a

'corresponding |\n'

5028

n/a

' | | unicode character before '

5029

n/a

'printing. |\n'

5030

n/a

' '

5031

n/a

'+-----------+------------------------------------------------------------+\n'

5032

n/a

' | "\'d\'" | Decimal Integer. Outputs the number in '

5033

n/a

'base 10. |\n'

5034

n/a

' '

5035

n/a

'+-----------+------------------------------------------------------------+\n'

5036

n/a

' | "\'o\'" | Octal format. Outputs the number in base '

5037

n/a

'8. |\n'

5038

n/a

' '

5039

n/a

'+-----------+------------------------------------------------------------+\n'

5040

n/a

' | "\'x\'" | Hex format. Outputs the number in base '

5041

n/a

'16, using lower- |\n'

5042

n/a

' | | case letters for the digits above '

5043

n/a

'9. |\n'

5044

n/a

' '

5045

n/a

'+-----------+------------------------------------------------------------+\n'

5046

n/a

' | "\'X\'" | Hex format. Outputs the number in base '

5047

n/a

'16, using upper- |\n'

5048

n/a

' | | case letters for the digits above '

5049

n/a

'9. |\n'

5050

n/a

' '

5051

n/a

'+-----------+------------------------------------------------------------+\n'

5052

n/a

' | "\'n\'" | Number. This is the same as "\'d\'", '

5053

n/a

'except that it uses the |\n'

5054

n/a

' | | current locale setting to insert the '

5055

n/a

'appropriate number |\n'

5056

n/a

' | | separator '

5057

n/a

'characters. |\n'

5058

n/a

' '

5059

n/a

'+-----------+------------------------------------------------------------+\n'

5060

n/a

' | None | The same as '

5061

n/a

'"\'d\'". |\n'

5062

n/a

' '

5063

n/a

'+-----------+------------------------------------------------------------+\n'

5064

n/a

'\n'

5065

n/a

'In addition to the above presentation types, integers can '

5066

n/a

'be formatted\n'

5067

n/a

'with the floating point presentation types listed below '

5068

n/a

'(except "\'n\'"\n'

5069

n/a

'and None). When doing so, "float()" is used to convert the '

5070

n/a

'integer to\n'

5071

n/a

'a floating point number before formatting.\n'

5072

n/a

'\n'

5073

n/a

'The available presentation types for floating point and '

5074

n/a

'decimal values\n'

5075

n/a

'are:\n'

5076

n/a

'\n'

5077

n/a

' '

5078

n/a

'+-----------+------------------------------------------------------------+\n'

5079

n/a

' | Type | '

5080

n/a

'Meaning '

5081

n/a

'|\n'

5082

n/a

' '

5083

n/a

'+===========+============================================================+\n'

5084

n/a

' | "\'e\'" | Exponent notation. Prints the number in '

5085

n/a

'scientific |\n'

5086

n/a

" | | notation using the letter 'e' to indicate "

5087

n/a

'the exponent. |\n'

5088

n/a

' | | The default precision is '

5089

n/a

'"6". |\n'

5090

n/a

' '

5091

n/a

'+-----------+------------------------------------------------------------+\n'

5092

n/a

' | "\'E\'" | Exponent notation. Same as "\'e\'" '

5093

n/a

'except it uses an upper |\n'

5094

n/a

" | | case 'E' as the separator "

5095

n/a

'character. |\n'

5096

n/a

' '

5097

n/a

'+-----------+------------------------------------------------------------+\n'

5098

n/a

' | "\'f\'" | Fixed point. Displays the number as a '

5099

n/a

'fixed-point number. |\n'

5100

n/a

' | | The default precision is '

5101

n/a

'"6". |\n'

5102

n/a

' '

5103

n/a

'+-----------+------------------------------------------------------------+\n'

5104

n/a

' | "\'F\'" | Fixed point. Same as "\'f\'", but '

5105

n/a

'converts "nan" to "NAN" |\n'

5106

n/a

' | | and "inf" to '

5107

n/a

'"INF". |\n'

5108

n/a

' '

5109

n/a

'+-----------+------------------------------------------------------------+\n'

5110

n/a

' | "\'g\'" | General format. For a given precision '

5111

n/a

'"p >= 1", this |\n'

5112

n/a

' | | rounds the number to "p" significant '

5113

n/a

'digits and then |\n'

5114

n/a

' | | formats the result in either fixed-point '

5115

n/a

'format or in |\n'

5116

n/a

' | | scientific notation, depending on its '

5117

n/a

'magnitude. The |\n'

5118

n/a

' | | precise rules are as follows: suppose that '

5119

n/a

'the result |\n'

5120

n/a

' | | formatted with presentation type "\'e\'" '

5121

n/a

'and precision "p-1" |\n'

5122

n/a

' | | would have exponent "exp". Then if "-4 <= '

5123

n/a

'exp < p", the |\n'

5124

n/a

' | | number is formatted with presentation type '

5125

n/a

'"\'f\'" and |\n'

5126

n/a

' | | precision "p-1-exp". Otherwise, the '

5127

n/a

'number is formatted |\n'

5128

n/a

' | | with presentation type "\'e\'" and '

5129

n/a

'precision "p-1". In both |\n'

5130

n/a

' | | cases insignificant trailing zeros are '

5131

n/a

'removed from the |\n'

5132

n/a

' | | significand, and the decimal point is also '

5133

n/a

'removed if |\n'

5134

n/a

' | | there are no remaining digits following '

5135

n/a

'it. Positive and |\n'

5136

n/a

' | | negative infinity, positive and negative '

5137

n/a

'zero, and nans, |\n'

5138

n/a

' | | are formatted as "inf", "-inf", "0", "-0" '

5139

n/a

'and "nan" |\n'

5140

n/a

' | | respectively, regardless of the '

5141

n/a

'precision. A precision of |\n'

5142

n/a

' | | "0" is treated as equivalent to a '

5143

n/a

'precision of "1". The |\n'

5144

n/a

' | | default precision is '

5145

n/a

'"6". |\n'

5146

n/a

' '

5147

n/a

'+-----------+------------------------------------------------------------+\n'

5148

n/a

' | "\'G\'" | General format. Same as "\'g\'" except '

5149

n/a

'switches to "\'E\'" if |\n'

5150

n/a

' | | the number gets too large. The '

5151

n/a

'representations of infinity |\n'

5152

n/a

' | | and NaN are uppercased, '

5153

n/a

'too. |\n'

5154

n/a

' '

5155

n/a

'+-----------+------------------------------------------------------------+\n'

5156

n/a

' | "\'n\'" | Number. This is the same as "\'g\'", '

5157

n/a

'except that it uses the |\n'

5158

n/a

' | | current locale setting to insert the '

5159

n/a

'appropriate number |\n'

5160

n/a

' | | separator '

5161

n/a

'characters. |\n'

5162

n/a

' '

5163

n/a

'+-----------+------------------------------------------------------------+\n'

5164

n/a

' | "\'%\'" | Percentage. Multiplies the number by 100 '

5165

n/a

'and displays in |\n'

5166

n/a

' | | fixed ("\'f\'") format, followed by a '

5167

n/a

'percent sign. |\n'

5168

n/a

' '

5169

n/a

'+-----------+------------------------------------------------------------+\n'

5170

n/a

' | None | Similar to "\'g\'", except that '

5171

n/a

'fixed-point notation, when |\n'

5172

n/a

' | | used, has at least one digit past the '

5173

n/a

'decimal point. The |\n'

5174

n/a

' | | default precision is as high as needed to '

5175

n/a

'represent the |\n'

5176

n/a

' | | particular value. The overall effect is to '

5177

n/a

'match the |\n'

5178

n/a

' | | output of "str()" as altered by the other '

5179

n/a

'format |\n'

5180

n/a

' | | '

5181

n/a

'modifiers. '

5182

n/a

'|\n'

5183

n/a

' '

5184

n/a

'+-----------+------------------------------------------------------------+\n'

5185

n/a

'\n'

5186

n/a

'\n'

5187

n/a

'Format examples\n'

5188

n/a

'===============\n'

5189

n/a

'\n'

5190

n/a

'This section contains examples of the "str.format()" syntax '

5191

n/a

'and\n'

5192

n/a

'comparison with the old "%"-formatting.\n'

5193

n/a

'\n'

5194

n/a

'In most of the cases the syntax is similar to the old '

5195

n/a

'"%"-formatting,\n'

5196

n/a

'with the addition of the "{}" and with ":" used instead of '

5197

n/a

'"%". For\n'

5198

n/a

'example, "\'%03.2f\'" can be translated to "\'{:03.2f}\'".\n'

5199

n/a

'\n'

5200

n/a

'The new format syntax also supports new and different '

5201

n/a

'options, shown\n'

5202

n/a

'in the follow examples.\n'

5203

n/a

'\n'

5204

n/a

'Accessing arguments by position:\n'

5205

n/a

'\n'

5206

n/a

" >>> '{0}, {1}, {2}'.format('a', 'b', 'c')\n"

5207

n/a

" 'a, b, c'\n"

5208

n/a

" >>> '{}, {}, {}'.format('a', 'b', 'c') # 3.1+ only\n"

5209

n/a

" 'a, b, c'\n"

5210

n/a

" >>> '{2}, {1}, {0}'.format('a', 'b', 'c')\n"

5211

n/a

" 'c, b, a'\n"

5212

n/a

" >>> '{2}, {1}, {0}'.format(*'abc') # unpacking "

5213

n/a

'argument sequence\n'

5214

n/a

" 'c, b, a'\n"

5215

n/a

" >>> '{0}{1}{0}'.format('abra', 'cad') # arguments' "

5216

n/a

'indices can be repeated\n'

5217

n/a

" 'abracadabra'\n"

5218

n/a

'\n'

5219

n/a

'Accessing arguments by name:\n'

5220

n/a

'\n'

5221

n/a

" >>> 'Coordinates: {latitude}, "

5222

n/a

"{longitude}'.format(latitude='37.24N', "

5223

n/a

"longitude='-115.81W')\n"

5224

n/a

" 'Coordinates: 37.24N, -115.81W'\n"

5225

n/a

" >>> coord = {'latitude': '37.24N', 'longitude': "

5226

n/a

"'-115.81W'}\n"

5227

n/a

" >>> 'Coordinates: {latitude}, "

5228

n/a

"{longitude}'.format(**coord)\n"

5229

n/a

" 'Coordinates: 37.24N, -115.81W'\n"

5230

n/a

'\n'

5231

n/a

"Accessing arguments' attributes:\n"

5232

n/a

'\n'

5233

n/a

' >>> c = 3-5j\n'

5234

n/a

" >>> ('The complex number {0} is formed from the real "

5235

n/a

"part {0.real} '\n"

5236

n/a

" ... 'and the imaginary part {0.imag}.').format(c)\n"

5237

n/a

" 'The complex number (3-5j) is formed from the real part "

5238

n/a

"3.0 and the imaginary part -5.0.'\n"

5239

n/a

' >>> class Point:\n'

5240

n/a

' ... def __init__(self, x, y):\n'

5241

n/a

' ... self.x, self.y = x, y\n'

5242

n/a

' ... def __str__(self):\n'

5243

n/a

" ... return 'Point({self.x}, "

5244

n/a

"{self.y})'.format(self=self)\n"

5245

n/a

' ...\n'

5246

n/a

' >>> str(Point(4, 2))\n'

5247

n/a

" 'Point(4, 2)'\n"

5248

n/a

'\n'

5249

n/a

"Accessing arguments' items:\n"

5250

n/a

'\n'

5251

n/a

' >>> coord = (3, 5)\n'

5252

n/a

" >>> 'X: {0[0]}; Y: {0[1]}'.format(coord)\n"

5253

n/a

" 'X: 3; Y: 5'\n"

5254

n/a

'\n'

5255

n/a

'Replacing "%s" and "%r":\n'

5256

n/a

'\n'

5257

n/a

' >>> "repr() shows quotes: {!r}; str() doesn\'t: '

5258

n/a

'{!s}".format(\'test1\', \'test2\')\n'

5259

n/a

' "repr() shows quotes: \'test1\'; str() doesn\'t: test2"\n'

5260

n/a

'\n'

5261

n/a

'Aligning the text and specifying a width:\n'

5262

n/a

'\n'

5263

n/a

" >>> '{:<30}'.format('left aligned')\n"

5264

n/a

" 'left aligned '\n"

5265

n/a

" >>> '{:>30}'.format('right aligned')\n"

5266

n/a

" ' right aligned'\n"

5267

n/a

" >>> '{:^30}'.format('centered')\n"

5268

n/a

" ' centered '\n"

5269

n/a

" >>> '{:*^30}'.format('centered') # use '*' as a fill "

5270

n/a

'char\n'

5271

n/a

" '***********centered***********'\n"

5272

n/a

'\n'

5273

n/a

'Replacing "%+f", "%-f", and "% f" and specifying a sign:\n'

5274

n/a

'\n'

5275

n/a

" >>> '{:+f}; {:+f}'.format(3.14, -3.14) # show it "

5276

n/a

'always\n'

5277

n/a

" '+3.140000; -3.140000'\n"

5278

n/a

" >>> '{: f}; {: f}'.format(3.14, -3.14) # show a space "

5279

n/a

'for positive numbers\n'

5280

n/a

" ' 3.140000; -3.140000'\n"

5281

n/a

" >>> '{:-f}; {:-f}'.format(3.14, -3.14) # show only the "

5282

n/a

"minus -- same as '{:f}; {:f}'\n"

5283

n/a

" '3.140000; -3.140000'\n"

5284

n/a

'\n'

5285

n/a

'Replacing "%x" and "%o" and converting the value to '

5286

n/a

'different bases:\n'

5287

n/a

'\n'

5288

n/a

' >>> # format also supports binary numbers\n'

5289

n/a

' >>> "int: {0:d}; hex: {0:x}; oct: {0:o}; bin: '

5290

n/a

'{0:b}".format(42)\n'

5291

n/a

" 'int: 42; hex: 2a; oct: 52; bin: 101010'\n"

5292

n/a

' >>> # with 0x, 0o, or 0b as prefix:\n'

5293

n/a

' >>> "int: {0:d}; hex: {0:#x}; oct: {0:#o}; bin: '

5294

n/a

'{0:#b}".format(42)\n'

5295

n/a

" 'int: 42; hex: 0x2a; oct: 0o52; bin: 0b101010'\n"

5296

n/a

'\n'

5297

n/a

'Using the comma as a thousands separator:\n'

5298

n/a

'\n'

5299

n/a

" >>> '{:,}'.format(1234567890)\n"

5300

n/a

" '1,234,567,890'\n"

5301

n/a

'\n'

5302

n/a

'Expressing a percentage:\n'

5303

n/a

'\n'

5304

n/a

' >>> points = 19\n'

5305

n/a

' >>> total = 22\n'

5306

n/a

" >>> 'Correct answers: {:.2%}'.format(points/total)\n"

5307

n/a

" 'Correct answers: 86.36%'\n"

5308

n/a

'\n'

5309

n/a

'Using type-specific formatting:\n'

5310

n/a

'\n'

5311

n/a

' >>> import datetime\n'

5312

n/a

' >>> d = datetime.datetime(2010, 7, 4, 12, 15, 58)\n'

5313

n/a

" >>> '{:%Y-%m-%d %H:%M:%S}'.format(d)\n"

5314

n/a

" '2010-07-04 12:15:58'\n"

5315

n/a

'\n'

5316

n/a

'Nesting arguments and more complex examples:\n'

5317

n/a

'\n'

5318

n/a

" >>> for align, text in zip('<^>', ['left', 'center', "

5319

n/a

"'right']):\n"

5320

n/a

" ... '{0:{fill}{align}16}'.format(text, fill=align, "

5321

n/a

'align=align)\n'

5322

n/a

' ...\n'

5323

n/a

" 'left<<<<<<<<<<<<'\n"

5324

n/a

" '^^^^^center^^^^^'\n"

5325

n/a

" '>>>>>>>>>>>right'\n"

5326

n/a

' >>>\n'

5327

n/a

' >>> octets = [192, 168, 0, 1]\n'

5328

n/a

" >>> '{:02X}{:02X}{:02X}{:02X}'.format(*octets)\n"

5329

n/a

" 'C0A80001'\n"

5330

n/a

' >>> int(_, 16)\n'

5331

n/a

' 3232235521\n'

5332

n/a

' >>>\n'

5333

n/a

' >>> width = 5\n'

5334

n/a

' >>> for num in range(5,12): #doctest: '

5335

n/a

'+NORMALIZE_WHITESPACE\n'

5336

n/a

" ... for base in 'dXob':\n"

5337

n/a

" ... print('{0:{width}{base}}'.format(num, "

5338

n/a

"base=base, width=width), end=' ')\n"

5339

n/a

' ... print()\n'

5340

n/a

' ...\n'

5341

n/a

' 5 5 5 101\n'

5342

n/a

' 6 6 6 110\n'

5343

n/a

' 7 7 7 111\n'

5344

n/a

' 8 8 10 1000\n'

5345

n/a

' 9 9 11 1001\n'

5346

n/a

' 10 A 12 1010\n'

5347

n/a

' 11 B 13 1011\n',

5348

n/a

'function': '\n'

5349

n/a

'Function definitions\n'

5350

n/a

'********************\n'

5351

n/a

'\n'

5352

n/a

'A function definition defines a user-defined function object '

5353

n/a

'(see\n'

5354

n/a

'section The standard type hierarchy):\n'

5355

n/a

'\n'

5356

n/a

' funcdef ::= [decorators] "def" funcname "(" '

5357

n/a

'[parameter_list] ")" ["->" expression] ":" suite\n'

5358

n/a

' decorators ::= decorator+\n'

5359

n/a

' decorator ::= "@" dotted_name ["(" '

5360

n/a

'[argument_list [","]] ")"] NEWLINE\n'

5361

n/a

' dotted_name ::= identifier ("." identifier)*\n'

5362

n/a

' parameter_list ::= defparameter ("," defparameter)* '

5363

n/a

'["," [parameter_list_starargs]]\n'

5364

n/a

' | parameter_list_starargs\n'

5365

n/a

' parameter_list_starargs ::= "*" [parameter] ("," '

5366

n/a

'defparameter)* ["," ["**" parameter [","]]]\n'

5367

n/a

' | "**" parameter [","]\n'

5368

n/a

' parameter ::= identifier [":" expression]\n'

5369

n/a

' defparameter ::= parameter ["=" expression]\n'

5370

n/a

' funcname ::= identifier\n'

5371

n/a

'\n'

5372

n/a

'A function definition is an executable statement. Its execution '

5373

n/a

'binds\n'

5374

n/a

'the function name in the current local namespace to a function '

5375

n/a

'object\n'

5376

n/a

'(a wrapper around the executable code for the function). This\n'

5377

n/a

'function object contains a reference to the current global '

5378

n/a

'namespace\n'

5379

n/a

'as the global namespace to be used when the function is called.\n'

5380

n/a

'\n'

5381

n/a

'The function definition does not execute the function body; this '

5382

n/a

'gets\n'

5383

n/a

'executed only when the function is called. [3]\n'

5384

n/a

'\n'

5385

n/a

'A function definition may be wrapped by one or more *decorator*\n'

5386

n/a

'expressions. Decorator expressions are evaluated when the '

5387

n/a

'function is\n'

5388

n/a

'defined, in the scope that contains the function definition. '

5389

n/a

'The\n'

5390

n/a

'result must be a callable, which is invoked with the function '

5391

n/a

'object\n'

5392

n/a

'as the only argument. The returned value is bound to the '

5393

n/a

'function name\n'

5394

n/a

'instead of the function object. Multiple decorators are applied '

5395

n/a

'in\n'

5396

n/a

'nested fashion. For example, the following code\n'

5397

n/a

'\n'

5398

n/a

' @f1(arg)\n'

5399

n/a

' @f2\n'

5400

n/a

' def func(): pass\n'

5401

n/a

'\n'

5402

n/a

'is roughly equivalent to\n'

5403

n/a

'\n'

5404

n/a

' def func(): pass\n'

5405

n/a

' func = f1(arg)(f2(func))\n'

5406

n/a

'\n'

5407

n/a

'except that the original function is not temporarily bound to '

5408

n/a

'the name\n'

5409

n/a

'"func".\n'

5410

n/a

'\n'

5411

n/a

'When one or more *parameters* have the form *parameter* "="\n'

5412

n/a

'*expression*, the function is said to have "default parameter '

5413

n/a

'values."\n'

5414

n/a

'For a parameter with a default value, the corresponding '

5415

n/a

'*argument* may\n'

5416

n/a

"be omitted from a call, in which case the parameter's default "

5417

n/a

'value is\n'

5418

n/a

'substituted. If a parameter has a default value, all following\n'

5419

n/a

'parameters up until the ""*"" must also have a default value --- '

5420

n/a

'this\n'

5421

n/a

'is a syntactic restriction that is not expressed by the '

5422

n/a

'grammar.\n'

5423

n/a

'\n'

5424

n/a

'**Default parameter values are evaluated from left to right when '

5425

n/a

'the\n'

5426

n/a

'function definition is executed.** This means that the '

5427

n/a

'expression is\n'

5428

n/a

'evaluated once, when the function is defined, and that the same '

5429

n/a

'"pre-\n'

5430

n/a

'computed" value is used for each call. This is especially '

5431

n/a

'important\n'

5432

n/a

'to understand when a default parameter is a mutable object, such '

5433

n/a

'as a\n'

5434

n/a

'list or a dictionary: if the function modifies the object (e.g. '

5435

n/a

'by\n'

5436

n/a

'appending an item to a list), the default value is in effect '

5437

n/a

'modified.\n'

5438

n/a

'This is generally not what was intended. A way around this is '

5439

n/a

'to use\n'

5440

n/a

'"None" as the default, and explicitly test for it in the body of '

5441

n/a

'the\n'

5442

n/a

'function, e.g.:\n'

5443

n/a

'\n'

5444

n/a

' def whats_on_the_telly(penguin=None):\n'

5445

n/a

' if penguin is None:\n'

5446

n/a

' penguin = []\n'

5447

n/a

' penguin.append("property of the zoo")\n'

5448

n/a

' return penguin\n'

5449

n/a

'\n'

5450

n/a

'Function call semantics are described in more detail in section '

5451

n/a

'Calls.\n'

5452

n/a

'A function call always assigns values to all parameters '

5453

n/a

'mentioned in\n'

5454

n/a

'the parameter list, either from position arguments, from '

5455

n/a

'keyword\n'

5456

n/a

'arguments, or from default values. If the form ""*identifier"" '

5457

n/a

'is\n'

5458

n/a

'present, it is initialized to a tuple receiving any excess '

5459

n/a

'positional\n'

5460

n/a

'parameters, defaulting to the empty tuple. If the form\n'

5461

n/a

'""**identifier"" is present, it is initialized to a new ordered\n'

5462

n/a

'mapping receiving any excess keyword arguments, defaulting to a '

5463

n/a

'new\n'

5464

n/a

'empty mapping of the same type. Parameters after ""*"" or\n'

5465

n/a

'""*identifier"" are keyword-only parameters and may only be '

5466

n/a

'passed\n'

5467

n/a

'used keyword arguments.\n'

5468

n/a

'\n'

5469

n/a

'Parameters may have annotations of the form "": expression"" '

5470

n/a

'following\n'

5471

n/a

'the parameter name. Any parameter may have an annotation even '

5472

n/a

'those\n'

5473

n/a

'of the form "*identifier" or "**identifier". Functions may '

5474

n/a

'have\n'

5475

n/a

'"return" annotation of the form ""-> expression"" after the '

5476

n/a

'parameter\n'

5477

n/a

'list. These annotations can be any valid Python expression and '

5478

n/a

'are\n'

5479

n/a

'evaluated when the function definition is executed. Annotations '

5480

n/a

'may\n'

5481

n/a

'be evaluated in a different order than they appear in the source '

5482

n/a

'code.\n'

5483

n/a

'The presence of annotations does not change the semantics of a\n'

5484

n/a

'function. The annotation values are available as values of a\n'

5485

n/a

"dictionary keyed by the parameters' names in the "

5486

n/a

'"__annotations__"\n'

5487

n/a

'attribute of the function object.\n'

5488

n/a

'\n'

5489

n/a

'It is also possible to create anonymous functions (functions not '

5490

n/a

'bound\n'

5491

n/a

'to a name), for immediate use in expressions. This uses lambda\n'

5492

n/a

'expressions, described in section Lambdas. Note that the '

5493

n/a

'lambda\n'

5494

n/a

'expression is merely a shorthand for a simplified function '

5495

n/a

'definition;\n'

5496

n/a

'a function defined in a ""def"" statement can be passed around '

5497

n/a

'or\n'

5498

n/a

'assigned to another name just like a function defined by a '

5499

n/a

'lambda\n'

5500

n/a

'expression. The ""def"" form is actually more powerful since '

5501

n/a

'it\n'

5502

n/a

'allows the execution of multiple statements and annotations.\n'

5503

n/a

'\n'

5504

n/a

"**Programmer's note:** Functions are first-class objects. A "

5505

n/a

'""def""\n'

5506

n/a

'statement executed inside a function definition defines a local\n'

5507

n/a

'function that can be returned or passed around. Free variables '

5508

n/a

'used\n'

5509

n/a

'in the nested function can access the local variables of the '

5510

n/a

'function\n'

5511

n/a

'containing the def. See section Naming and binding for '

5512

n/a

'details.\n'

5513

n/a

'\n'

5514

n/a

'See also:\n'

5515

n/a

'\n'

5516

n/a

' **PEP 3107** - Function Annotations\n'

5517

n/a

' The original specification for function annotations.\n',

5518

n/a

'global': '\n'

5519

n/a

'The "global" statement\n'

5520

n/a

'**********************\n'

5521

n/a

'\n'

5522

n/a

' global_stmt ::= "global" identifier ("," identifier)*\n'

5523

n/a

'\n'

5524

n/a

'The "global" statement is a declaration which holds for the '

5525

n/a

'entire\n'

5526

n/a

'current code block. It means that the listed identifiers are to '

5527

n/a

'be\n'

5528

n/a

'interpreted as globals. It would be impossible to assign to a '

5529

n/a

'global\n'

5530

n/a

'variable without "global", although free variables may refer to\n'

5531

n/a

'globals without being declared global.\n'

5532

n/a

'\n'

5533

n/a

'Names listed in a "global" statement must not be used in the same '

5534

n/a

'code\n'

5535

n/a

'block textually preceding that "global" statement.\n'

5536

n/a

'\n'

5537

n/a

'Names listed in a "global" statement must not be defined as '

5538

n/a

'formal\n'

5539

n/a

'parameters or in a "for" loop control target, "class" definition,\n'

5540

n/a

'function definition, "import" statement, or variable annotation.\n'

5541

n/a

'\n'

5542

n/a

'**CPython implementation detail:** The current implementation does '

5543

n/a

'not\n'

5544

n/a

'enforce some of these restriction, but programs should not abuse '

5545

n/a

'this\n'

5546

n/a

'freedom, as future implementations may enforce them or silently '

5547

n/a

'change\n'

5548

n/a

'the meaning of the program.\n'

5549

n/a

'\n'

5550

n/a

'**Programmer\'s note:** the "global" is a directive to the '

5551

n/a

'parser. It\n'

5552

n/a

'applies only to code parsed at the same time as the "global"\n'

5553

n/a

'statement. In particular, a "global" statement contained in a '

5554

n/a

'string\n'

5555

n/a

'or code object supplied to the built-in "exec()" function does '

5556

n/a

'not\n'

5557

n/a

'affect the code block *containing* the function call, and code\n'

5558

n/a

'contained in such a string is unaffected by "global" statements in '

5559

n/a

'the\n'

5560

n/a

'code containing the function call. The same applies to the '

5561

n/a

'"eval()"\n'

5562

n/a

'and "compile()" functions.\n',

5563

n/a

'id-classes': '\n'

5564

n/a

'Reserved classes of identifiers\n'

5565

n/a

'*******************************\n'

5566

n/a

'\n'

5567

n/a

'Certain classes of identifiers (besides keywords) have '

5568

n/a

'special\n'

5569

n/a

'meanings. These classes are identified by the patterns of '

5570

n/a

'leading and\n'

5571

n/a

'trailing underscore characters:\n'

5572

n/a

'\n'

5573

n/a

'"_*"\n'

5574

n/a

' Not imported by "from module import *". The special '

5575

n/a

'identifier "_"\n'

5576

n/a

' is used in the interactive interpreter to store the result '

5577

n/a

'of the\n'

5578

n/a

' last evaluation; it is stored in the "builtins" module. '

5579

n/a

'When not\n'

5580

n/a

' in interactive mode, "_" has no special meaning and is not '

5581

n/a

'defined.\n'

5582

n/a

' See section The import statement.\n'

5583

n/a

'\n'

5584

n/a

' Note: The name "_" is often used in conjunction with\n'

5585

n/a

' internationalization; refer to the documentation for the\n'

5586

n/a

' "gettext" module for more information on this '

5587

n/a

'convention.\n'

5588

n/a

'\n'

5589

n/a

'"__*__"\n'

5590

n/a

' System-defined names. These names are defined by the '

5591

n/a

'interpreter\n'

5592

n/a

' and its implementation (including the standard library). '

5593

n/a

'Current\n'

5594

n/a

' system names are discussed in the Special method names '

5595

n/a

'section and\n'

5596

n/a

' elsewhere. More will likely be defined in future versions '

5597

n/a

'of\n'

5598

n/a

' Python. *Any* use of "__*__" names, in any context, that '

5599

n/a

'does not\n'

5600

n/a

' follow explicitly documented use, is subject to breakage '

5601

n/a

'without\n'

5602

n/a

' warning.\n'

5603

n/a

'\n'

5604

n/a

'"__*"\n'

5605

n/a

' Class-private names. Names in this category, when used '

5606

n/a

'within the\n'

5607

n/a

' context of a class definition, are re-written to use a '

5608

n/a

'mangled form\n'

5609

n/a

' to help avoid name clashes between "private" attributes of '

5610

n/a

'base and\n'

5611

n/a

' derived classes. See section Identifiers (Names).\n',

5612

n/a

'identifiers': '\n'

5613

n/a

'Identifiers and keywords\n'

5614

n/a

'************************\n'

5615

n/a

'\n'

5616

n/a

'Identifiers (also referred to as *names*) are described by '

5617

n/a

'the\n'

5618

n/a

'following lexical definitions.\n'

5619

n/a

'\n'

5620

n/a

'The syntax of identifiers in Python is based on the Unicode '

5621

n/a

'standard\n'

5622

n/a

'annex UAX-31, with elaboration and changes as defined below; '

5623

n/a

'see also\n'

5624

n/a

'**PEP 3131** for further details.\n'

5625

n/a

'\n'

5626

n/a

'Within the ASCII range (U+0001..U+007F), the valid characters '

5627

n/a

'for\n'

5628

n/a

'identifiers are the same as in Python 2.x: the uppercase and '

5629

n/a

'lowercase\n'

5630

n/a

'letters "A" through "Z", the underscore "_" and, except for '

5631

n/a

'the first\n'

5632

n/a

'character, the digits "0" through "9".\n'

5633

n/a

'\n'

5634

n/a

'Python 3.0 introduces additional characters from outside the '

5635

n/a

'ASCII\n'

5636

n/a

'range (see **PEP 3131**). For these characters, the '

5637

n/a

'classification\n'

5638

n/a

'uses the version of the Unicode Character Database as '

5639

n/a

'included in the\n'

5640

n/a

'"unicodedata" module.\n'

5641

n/a

'\n'

5642

n/a

'Identifiers are unlimited in length. Case is significant.\n'

5643

n/a

'\n'

5644

n/a

' identifier ::= xid_start xid_continue*\n'

5645

n/a

' id_start ::= <all characters in general categories Lu, '

5646

n/a

'Ll, Lt, Lm, Lo, Nl, the underscore, and characters with the '

5647

n/a

'Other_ID_Start property>\n'

5648

n/a

' id_continue ::= <all characters in id_start, plus '

5649

n/a

'characters in the categories Mn, Mc, Nd, Pc and others with '

5650

n/a

'the Other_ID_Continue property>\n'

5651

n/a

' xid_start ::= <all characters in id_start whose NFKC '

5652

n/a

'normalization is in "id_start xid_continue*">\n'

5653

n/a

' xid_continue ::= <all characters in id_continue whose NFKC '

5654

n/a

'normalization is in "id_continue*">\n'

5655

n/a

'\n'

5656

n/a

'The Unicode category codes mentioned above stand for:\n'

5657

n/a

'\n'

5658

n/a

'* *Lu* - uppercase letters\n'

5659

n/a

'\n'

5660

n/a

'* *Ll* - lowercase letters\n'

5661

n/a

'\n'

5662

n/a

'* *Lt* - titlecase letters\n'

5663

n/a

'\n'

5664

n/a

'* *Lm* - modifier letters\n'

5665

n/a

'\n'

5666

n/a

'* *Lo* - other letters\n'

5667

n/a

'\n'

5668

n/a

'* *Nl* - letter numbers\n'

5669

n/a

'\n'

5670

n/a

'* *Mn* - nonspacing marks\n'

5671

n/a

'\n'

5672

n/a

'* *Mc* - spacing combining marks\n'

5673

n/a

'\n'

5674

n/a

'* *Nd* - decimal numbers\n'

5675

n/a

'\n'

5676

n/a

'* *Pc* - connector punctuations\n'

5677

n/a

'\n'

5678

n/a

'* *Other_ID_Start* - explicit list of characters in '

5679

n/a

'PropList.txt to\n'

5680

n/a

' support backwards compatibility\n'

5681

n/a

'\n'

5682

n/a

'* *Other_ID_Continue* - likewise\n'

5683

n/a

'\n'

5684

n/a

'All identifiers are converted into the normal form NFKC while '

5685

n/a

'parsing;\n'

5686

n/a

'comparison of identifiers is based on NFKC.\n'

5687

n/a

'\n'

5688

n/a

'A non-normative HTML file listing all valid identifier '

5689

n/a

'characters for\n'

5690

n/a

'Unicode 4.1 can be found at https://www.dcl.hpi.uni-\n'

5691

n/a

'potsdam.de/home/loewis/table-3131.html.\n'

5692

n/a

'\n'

5693

n/a

'\n'

5694

n/a

'Keywords\n'

5695

n/a

'========\n'

5696

n/a

'\n'

5697

n/a

'The following identifiers are used as reserved words, or '

5698

n/a

'*keywords* of\n'

5699

n/a

'the language, and cannot be used as ordinary identifiers. '

5700

n/a

'They must\n'

5701

n/a

'be spelled exactly as written here:\n'

5702

n/a

'\n'

5703

n/a

' False class finally is return\n'

5704

n/a

' None continue for lambda try\n'

5705

n/a

' True def from nonlocal while\n'

5706

n/a

' and del global not with\n'

5707

n/a

' as elif if or yield\n'

5708

n/a

' assert else import pass\n'

5709

n/a

' break except in raise\n'

5710

n/a

'\n'

5711

n/a

'\n'

5712

n/a

'Reserved classes of identifiers\n'

5713

n/a

'===============================\n'

5714

n/a

'\n'

5715

n/a

'Certain classes of identifiers (besides keywords) have '

5716

n/a

'special\n'

5717

n/a

'meanings. These classes are identified by the patterns of '

5718

n/a

'leading and\n'

5719

n/a

'trailing underscore characters:\n'

5720

n/a

'\n'

5721

n/a

'"_*"\n'

5722

n/a

' Not imported by "from module import *". The special '

5723

n/a

'identifier "_"\n'

5724

n/a

' is used in the interactive interpreter to store the result '

5725

n/a

'of the\n'

5726

n/a

' last evaluation; it is stored in the "builtins" module. '

5727

n/a

'When not\n'

5728

n/a

' in interactive mode, "_" has no special meaning and is not '

5729

n/a

'defined.\n'

5730

n/a

' See section The import statement.\n'

5731

n/a

'\n'

5732

n/a

' Note: The name "_" is often used in conjunction with\n'

5733

n/a

' internationalization; refer to the documentation for '

5734

n/a

'the\n'

5735

n/a

' "gettext" module for more information on this '

5736

n/a

'convention.\n'

5737

n/a

'\n'

5738

n/a

'"__*__"\n'

5739

n/a

' System-defined names. These names are defined by the '

5740

n/a

'interpreter\n'

5741

n/a

' and its implementation (including the standard library). '

5742

n/a

'Current\n'

5743

n/a

' system names are discussed in the Special method names '

5744

n/a

'section and\n'

5745

n/a

' elsewhere. More will likely be defined in future versions '

5746

n/a

'of\n'

5747

n/a

' Python. *Any* use of "__*__" names, in any context, that '

5748

n/a

'does not\n'

5749

n/a

' follow explicitly documented use, is subject to breakage '

5750

n/a

'without\n'

5751

n/a

' warning.\n'

5752

n/a

'\n'

5753

n/a

'"__*"\n'

5754

n/a

' Class-private names. Names in this category, when used '

5755

n/a

'within the\n'

5756

n/a

' context of a class definition, are re-written to use a '

5757

n/a

'mangled form\n'

5758

n/a

' to help avoid name clashes between "private" attributes of '

5759

n/a

'base and\n'

5760

n/a

' derived classes. See section Identifiers (Names).\n',

5761

n/a

'if': '\n'

5762

n/a

'The "if" statement\n'

5763

n/a

'******************\n'

5764

n/a

'\n'

5765

n/a

'The "if" statement is used for conditional execution:\n'

5766

n/a

'\n'

5767

n/a

' if_stmt ::= "if" expression ":" suite\n'

5768

n/a

' ( "elif" expression ":" suite )*\n'

5769

n/a

' ["else" ":" suite]\n'

5770

n/a

'\n'

5771

n/a

'It selects exactly one of the suites by evaluating the expressions '

5772

n/a

'one\n'

5773

n/a

'by one until one is found to be true (see section Boolean operations\n'

5774

n/a

'for the definition of true and false); then that suite is executed\n'

5775

n/a

'(and no other part of the "if" statement is executed or evaluated).\n'

5776

n/a

'If all expressions are false, the suite of the "else" clause, if\n'

5777

n/a

'present, is executed.\n',

5778

n/a

'imaginary': '\n'

5779

n/a

'Imaginary literals\n'

5780

n/a

'******************\n'

5781

n/a

'\n'

5782

n/a

'Imaginary literals are described by the following lexical '

5783

n/a

'definitions:\n'

5784

n/a

'\n'

5785

n/a

' imagnumber ::= (floatnumber | digitpart) ("j" | "J")\n'

5786

n/a

'\n'

5787

n/a

'An imaginary literal yields a complex number with a real part '

5788

n/a

'of 0.0.\n'

5789

n/a

'Complex numbers are represented as a pair of floating point '

5790

n/a

'numbers\n'

5791

n/a

'and have the same restrictions on their range. To create a '

5792

n/a

'complex\n'

5793

n/a

'number with a nonzero real part, add a floating point number to '

5794

n/a

'it,\n'

5795

n/a

'e.g., "(3+4j)". Some examples of imaginary literals:\n'

5796

n/a

'\n'

5797

n/a

' 3.14j 10.j 10j .001j 1e100j 3.14e-10j '

5798

n/a

'3.14_15_93j\n',

5799

n/a

'import': '\n'

5800

n/a

'The "import" statement\n'

5801

n/a

'**********************\n'

5802

n/a

'\n'

5803

n/a

' import_stmt ::= "import" module ["as" name] ( "," module '

5804

n/a

'["as" name] )*\n'

5805

n/a

' | "from" relative_module "import" identifier '

5806

n/a

'["as" name]\n'

5807

n/a

' ( "," identifier ["as" name] )*\n'

5808

n/a

' | "from" relative_module "import" "(" '

5809

n/a

'identifier ["as" name]\n'

5810

n/a

' ( "," identifier ["as" name] )* [","] ")"\n'

5811

n/a

' | "from" module "import" "*"\n'

5812

n/a

' module ::= (identifier ".")* identifier\n'

5813

n/a

' relative_module ::= "."* module | "."+\n'

5814

n/a

' name ::= identifier\n'

5815

n/a

'\n'

5816

n/a

'The basic import statement (no "from" clause) is executed in two\n'

5817

n/a

'steps:\n'

5818

n/a

'\n'

5819

n/a

'1. find a module, loading and initializing it if necessary\n'

5820

n/a

'\n'

5821

n/a

'2. define a name or names in the local namespace for the scope\n'

5822

n/a

' where the "import" statement occurs.\n'

5823

n/a

'\n'

5824

n/a

'When the statement contains multiple clauses (separated by commas) '

5825

n/a

'the\n'

5826

n/a

'two steps are carried out separately for each clause, just as '

5827

n/a

'though\n'

5828

n/a

'the clauses had been separated out into individual import '

5829

n/a

'statements.\n'

5830

n/a

'\n'

5831

n/a

'The details of the first step, finding and loading modules are\n'

5832

n/a

'described in greater detail in the section on the import system, '

5833

n/a

'which\n'

5834

n/a

'also describes the various types of packages and modules that can '

5835

n/a

'be\n'

5836

n/a

'imported, as well as all the hooks that can be used to customize '

5837

n/a

'the\n'

5838

n/a

'import system. Note that failures in this step may indicate '

5839

n/a

'either\n'

5840

n/a

'that the module could not be located, *or* that an error occurred\n'

5841

n/a

'while initializing the module, which includes execution of the\n'

5842

n/a

"module's code.\n"

5843

n/a

'\n'

5844

n/a

'If the requested module is retrieved successfully, it will be '

5845

n/a

'made\n'

5846

n/a

'available in the local namespace in one of three ways:\n'

5847

n/a

'\n'

5848

n/a

'* If the module name is followed by "as", then the name following\n'

5849

n/a

' "as" is bound directly to the imported module.\n'

5850

n/a

'\n'

5851

n/a

'* If no other name is specified, and the module being imported is '

5852

n/a

'a\n'

5853

n/a

" top level module, the module's name is bound in the local "

5854

n/a

'namespace\n'

5855

n/a

' as a reference to the imported module\n'

5856

n/a

'\n'

5857

n/a

'* If the module being imported is *not* a top level module, then '

5858

n/a

'the\n'

5859

n/a

' name of the top level package that contains the module is bound '

5860

n/a

'in\n'

5861

n/a

' the local namespace as a reference to the top level package. '

5862

n/a

'The\n'

5863

n/a

' imported module must be accessed using its full qualified name\n'

5864

n/a

' rather than directly\n'

5865

n/a

'\n'

5866

n/a

'The "from" form uses a slightly more complex process:\n'

5867

n/a

'\n'

5868

n/a

'1. find the module specified in the "from" clause, loading and\n'

5869

n/a

' initializing it if necessary;\n'

5870

n/a

'\n'

5871

n/a

'2. for each of the identifiers specified in the "import" clauses:\n'

5872

n/a

'\n'

5873

n/a

' 1. check if the imported module has an attribute by that name\n'

5874

n/a

'\n'

5875

n/a

' 2. if not, attempt to import a submodule with that name and '

5876

n/a

'then\n'

5877

n/a

' check the imported module again for that attribute\n'

5878

n/a

'\n'

5879

n/a

' 3. if the attribute is not found, "ImportError" is raised.\n'

5880

n/a

'\n'

5881

n/a

' 4. otherwise, a reference to that value is stored in the local\n'

5882

n/a

' namespace, using the name in the "as" clause if it is '

5883

n/a

'present,\n'

5884

n/a

' otherwise using the attribute name\n'

5885

n/a

'\n'

5886

n/a

'Examples:\n'

5887

n/a

'\n'

5888

n/a

' import foo # foo imported and bound locally\n'

5889

n/a

' import foo.bar.baz # foo.bar.baz imported, foo bound '

5890

n/a

'locally\n'

5891

n/a

' import foo.bar.baz as fbb # foo.bar.baz imported and bound as '

5892

n/a

'fbb\n'

5893

n/a

' from foo.bar import baz # foo.bar.baz imported and bound as '

5894

n/a

'baz\n'

5895

n/a

' from foo import attr # foo imported and foo.attr bound as '

5896

n/a

'attr\n'

5897

n/a

'\n'

5898

n/a

'If the list of identifiers is replaced by a star ("\'*\'"), all '

5899

n/a

'public\n'

5900

n/a

'names defined in the module are bound in the local namespace for '

5901

n/a

'the\n'

5902

n/a

'scope where the "import" statement occurs.\n'

5903

n/a

'\n'

5904

n/a

'The *public names* defined by a module are determined by checking '

5905

n/a

'the\n'

5906

n/a

'module\'s namespace for a variable named "__all__"; if defined, it '

5907

n/a

'must\n'

5908

n/a

'be a sequence of strings which are names defined or imported by '

5909

n/a

'that\n'

5910

n/a

'module. The names given in "__all__" are all considered public '

5911

n/a

'and\n'

5912

n/a

'are required to exist. If "__all__" is not defined, the set of '

5913

n/a

'public\n'

5914

n/a

"names includes all names found in the module's namespace which do "

5915

n/a

'not\n'

5916

n/a

'begin with an underscore character ("\'_\'"). "__all__" should '

5917

n/a

'contain\n'

5918

n/a

'the entire public API. It is intended to avoid accidentally '

5919

n/a

'exporting\n'

5920

n/a

'items that are not part of the API (such as library modules which '

5921

n/a

'were\n'

5922

n/a

'imported and used within the module).\n'

5923

n/a

'\n'

5924

n/a

'The wild card form of import --- "from module import *" --- is '

5925

n/a

'only\n'

5926

n/a

'allowed at the module level. Attempting to use it in class or\n'

5927

n/a

'function definitions will raise a "SyntaxError".\n'

5928

n/a

'\n'

5929

n/a

'When specifying what module to import you do not have to specify '

5930

n/a

'the\n'

5931

n/a

'absolute name of the module. When a module or package is '

5932

n/a

'contained\n'

5933

n/a

'within another package it is possible to make a relative import '

5934

n/a

'within\n'

5935

n/a

'the same top package without having to mention the package name. '

5936

n/a

'By\n'

5937

n/a

'using leading dots in the specified module or package after "from" '

5938

n/a

'you\n'

5939

n/a

'can specify how high to traverse up the current package hierarchy\n'

5940

n/a

'without specifying exact names. One leading dot means the current\n'

5941

n/a

'package where the module making the import exists. Two dots means '

5942

n/a

'up\n'

5943

n/a

'one package level. Three dots is up two levels, etc. So if you '

5944

n/a

'execute\n'

5945

n/a

'"from . import mod" from a module in the "pkg" package then you '

5946

n/a

'will\n'

5947

n/a

'end up importing "pkg.mod". If you execute "from ..subpkg2 import '

5948

n/a

'mod"\n'

5949

n/a

'from within "pkg.subpkg1" you will import "pkg.subpkg2.mod". The\n'

5950

n/a

'specification for relative imports is contained within **PEP '

5951

n/a

'328**.\n'

5952

n/a

'\n'

5953

n/a

'"importlib.import_module()" is provided to support applications '

5954

n/a

'that\n'

5955

n/a

'determine dynamically the modules to be loaded.\n'

5956

n/a

'\n'

5957

n/a

'\n'

5958

n/a

'Future statements\n'

5959

n/a

'=================\n'

5960

n/a

'\n'

5961

n/a

'A *future statement* is a directive to the compiler that a '

5962

n/a

'particular\n'

5963

n/a

'module should be compiled using syntax or semantics that will be\n'

5964

n/a

'available in a specified future release of Python where the '

5965

n/a

'feature\n'

5966

n/a

'becomes standard.\n'

5967

n/a

'\n'

5968

n/a

'The future statement is intended to ease migration to future '

5969

n/a

'versions\n'

5970

n/a

'of Python that introduce incompatible changes to the language. '

5971

n/a

'It\n'

5972

n/a

'allows use of the new features on a per-module basis before the\n'

5973

n/a

'release in which the feature becomes standard.\n'

5974

n/a

'\n'

5975

n/a

' future_statement ::= "from" "__future__" "import" feature ["as" '

5976

n/a

'name]\n'

5977

n/a

' ("," feature ["as" name])*\n'

5978

n/a

' | "from" "__future__" "import" "(" feature '

5979

n/a

'["as" name]\n'

5980

n/a

' ("," feature ["as" name])* [","] ")"\n'

5981

n/a

' feature ::= identifier\n'

5982

n/a

' name ::= identifier\n'

5983

n/a

'\n'

5984

n/a

'A future statement must appear near the top of the module. The '

5985

n/a

'only\n'

5986

n/a

'lines that can appear before a future statement are:\n'

5987

n/a

'\n'

5988

n/a

'* the module docstring (if any),\n'

5989

n/a

'\n'

5990

n/a

'* comments,\n'

5991

n/a

'\n'

5992

n/a

'* blank lines, and\n'

5993

n/a

'\n'

5994

n/a

'* other future statements.\n'

5995

n/a

'\n'

5996

n/a

'The features recognized by Python 3.0 are "absolute_import",\n'

5997

n/a

'"division", "generators", "unicode_literals", "print_function",\n'

5998

n/a

'"nested_scopes" and "with_statement". They are all redundant '

5999

n/a

'because\n'

6000

n/a

'they are always enabled, and only kept for backwards '

6001

n/a

'compatibility.\n'

6002

n/a

'\n'

6003

n/a

'A future statement is recognized and treated specially at compile\n'

6004

n/a

'time: Changes to the semantics of core constructs are often\n'

6005

n/a

'implemented by generating different code. It may even be the '

6006

n/a

'case\n'

6007

n/a

'that a new feature introduces new incompatible syntax (such as a '

6008

n/a

'new\n'

6009

n/a

'reserved word), in which case the compiler may need to parse the\n'

6010

n/a

'module differently. Such decisions cannot be pushed off until\n'

6011

n/a

'runtime.\n'

6012

n/a

'\n'

6013

n/a

'For any given release, the compiler knows which feature names '

6014

n/a

'have\n'

6015

n/a

'been defined, and raises a compile-time error if a future '

6016

n/a

'statement\n'

6017

n/a

'contains a feature not known to it.\n'

6018

n/a

'\n'

6019

n/a

'The direct runtime semantics are the same as for any import '

6020

n/a

'statement:\n'

6021

n/a

'there is a standard module "__future__", described later, and it '

6022

n/a

'will\n'

6023

n/a

'be imported in the usual way at the time the future statement is\n'

6024

n/a

'executed.\n'

6025

n/a

'\n'

6026

n/a

'The interesting runtime semantics depend on the specific feature\n'

6027

n/a

'enabled by the future statement.\n'

6028

n/a

'\n'

6029

n/a

'Note that there is nothing special about the statement:\n'

6030

n/a

'\n'

6031

n/a

' import __future__ [as name]\n'

6032

n/a

'\n'

6033

n/a

"That is not a future statement; it's an ordinary import statement "

6034

n/a

'with\n'

6035

n/a

'no special semantics or syntax restrictions.\n'

6036

n/a

'\n'

6037

n/a

'Code compiled by calls to the built-in functions "exec()" and\n'

6038

n/a

'"compile()" that occur in a module "M" containing a future '

6039

n/a

'statement\n'

6040

n/a

'will, by default, use the new syntax or semantics associated with '

6041

n/a

'the\n'

6042

n/a

'future statement. This can be controlled by optional arguments '

6043

n/a

'to\n'

6044

n/a

'"compile()" --- see the documentation of that function for '

6045

n/a

'details.\n'

6046

n/a

'\n'

6047

n/a

'A future statement typed at an interactive interpreter prompt '

6048

n/a

'will\n'

6049

n/a

'take effect for the rest of the interpreter session. If an\n'

6050

n/a

'interpreter is started with the "-i" option, is passed a script '

6051

n/a

'name\n'

6052

n/a

'to execute, and the script includes a future statement, it will be '

6053

n/a

'in\n'

6054

n/a

'effect in the interactive session started after the script is\n'

6055

n/a

'executed.\n'

6056

n/a

'\n'

6057

n/a

'See also:\n'

6058

n/a

'\n'

6059

n/a

' **PEP 236** - Back to the __future__\n'

6060

n/a

' The original proposal for the __future__ mechanism.\n',

6061

n/a

'in': '\n'

6062

n/a

'Membership test operations\n'

6063

n/a

'**************************\n'

6064

n/a

'\n'

6065

n/a

'The operators "in" and "not in" test for membership. "x in s"\n'

6066

n/a

'evaluates to true if *x* is a member of *s*, and false otherwise. "x\n'

6067

n/a

'not in s" returns the negation of "x in s". All built-in sequences\n'

6068

n/a

'and set types support this as well as dictionary, for which "in" '

6069

n/a

'tests\n'

6070

n/a

'whether the dictionary has a given key. For container types such as\n'

6071

n/a

'list, tuple, set, frozenset, dict, or collections.deque, the\n'

6072

n/a

'expression "x in y" is equivalent to "any(x is e or x == e for e in\n'

6073

n/a

'y)".\n'

6074

n/a

'\n'

6075

n/a

'For the string and bytes types, "x in y" is true if and only if *x* '

6076

n/a

'is\n'

6077

n/a

'a substring of *y*. An equivalent test is "y.find(x) != -1". Empty\n'

6078

n/a

'strings are always considered to be a substring of any other string,\n'

6079

n/a

'so """ in "abc"" will return "True".\n'

6080

n/a

'\n'

6081

n/a

'For user-defined classes which define the "__contains__()" method, "x\n'

6082

n/a

'in y" is true if and only if "y.__contains__(x)" is true.\n'

6083

n/a

'\n'

6084

n/a

'For user-defined classes which do not define "__contains__()" but do\n'

6085

n/a

'define "__iter__()", "x in y" is true if some value "z" with "x == z"\n'

6086

n/a

'is produced while iterating over "y". If an exception is raised\n'

6087

n/a

'during the iteration, it is as if "in" raised that exception.\n'

6088

n/a

'\n'

6089

n/a

'Lastly, the old-style iteration protocol is tried: if a class defines\n'

6090

n/a

'"__getitem__()", "x in y" is true if and only if there is a non-\n'

6091

n/a

'negative integer index *i* such that "x == y[i]", and all lower\n'

6092

n/a

'integer indices do not raise "IndexError" exception. (If any other\n'

6093

n/a

'exception is raised, it is as if "in" raised that exception).\n'

6094

n/a

'\n'

6095

n/a

'The operator "not in" is defined to have the inverse true value of\n'

6096

n/a

'"in".\n',

6097

n/a

'integers': '\n'

6098

n/a

'Integer literals\n'

6099

n/a

'****************\n'

6100

n/a

'\n'

6101

n/a

'Integer literals are described by the following lexical '

6102

n/a

'definitions:\n'

6103

n/a

'\n'

6104

n/a

' integer ::= decinteger | bininteger | octinteger | '

6105

n/a

'hexinteger\n'

6106

n/a

' decinteger ::= nonzerodigit (["_"] digit)* | "0"+ (["_"] '

6107

n/a

'"0")*\n'

6108

n/a

' bininteger ::= "0" ("b" | "B") (["_"] bindigit)+\n'

6109

n/a

' octinteger ::= "0" ("o" | "O") (["_"] octdigit)+\n'

6110

n/a

' hexinteger ::= "0" ("x" | "X") (["_"] hexdigit)+\n'

6111

n/a

' nonzerodigit ::= "1"..."9"\n'

6112

n/a

' digit ::= "0"..."9"\n'

6113

n/a

' bindigit ::= "0" | "1"\n'

6114

n/a

' octdigit ::= "0"..."7"\n'

6115

n/a

' hexdigit ::= digit | "a"..."f" | "A"..."F"\n'

6116

n/a

'\n'

6117

n/a

'There is no limit for the length of integer literals apart from '

6118

n/a

'what\n'

6119

n/a

'can be stored in available memory.\n'

6120

n/a

'\n'

6121

n/a

'Underscores are ignored for determining the numeric value of '

6122

n/a

'the\n'

6123

n/a

'literal. They can be used to group digits for enhanced '

6124

n/a

'readability.\n'

6125

n/a

'One underscore can occur between digits, and after base '

6126

n/a

'specifiers\n'

6127

n/a

'like "0x".\n'

6128

n/a

'\n'

6129

n/a

'Note that leading zeros in a non-zero decimal number are not '

6130

n/a

'allowed.\n'

6131

n/a

'This is for disambiguation with C-style octal literals, which '

6132

n/a

'Python\n'

6133

n/a

'used before version 3.0.\n'

6134

n/a

'\n'

6135

n/a

'Some examples of integer literals:\n'

6136

n/a

'\n'

6137

n/a

' 7 2147483647 0o177 0b100110111\n'

6138

n/a

' 3 79228162514264337593543950336 0o377 0xdeadbeef\n'

6139

n/a

' 100_000_000_000 0b_1110_0101\n'

6140

n/a

'\n'

6141

n/a

'Changed in version 3.6: Underscores are now allowed for '

6142

n/a

'grouping\n'

6143

n/a

'purposes in literals.\n',

6144

n/a

'lambda': '\n'

6145

n/a

'Lambdas\n'

6146

n/a

'*******\n'

6147

n/a

'\n'

6148

n/a

' lambda_expr ::= "lambda" [parameter_list]: expression\n'

6149

n/a

' lambda_expr_nocond ::= "lambda" [parameter_list]: '

6150

n/a

'expression_nocond\n'

6151

n/a

'\n'

6152

n/a

'Lambda expressions (sometimes called lambda forms) are used to '

6153

n/a

'create\n'

6154

n/a

'anonymous functions. The expression "lambda arguments: '

6155

n/a

'expression"\n'

6156

n/a

'yields a function object. The unnamed object behaves like a '

6157

n/a

'function\n'

6158

n/a

'object defined with:\n'

6159

n/a

'\n'

6160

n/a

' def <lambda>(arguments):\n'

6161

n/a

' return expression\n'

6162

n/a

'\n'

6163

n/a

'See section Function definitions for the syntax of parameter '

6164

n/a

'lists.\n'

6165

n/a

'Note that functions created with lambda expressions cannot '

6166

n/a

'contain\n'

6167

n/a

'statements or annotations.\n',

6168

n/a

'lists': '\n'

6169

n/a

'List displays\n'

6170

n/a

'*************\n'

6171

n/a

'\n'

6172

n/a

'A list display is a possibly empty series of expressions enclosed '

6173

n/a

'in\n'

6174

n/a

'square brackets:\n'

6175

n/a

'\n'

6176

n/a

' list_display ::= "[" [starred_list | comprehension] "]"\n'

6177

n/a

'\n'

6178

n/a

'A list display yields a new list object, the contents being '

6179

n/a

'specified\n'

6180

n/a

'by either a list of expressions or a comprehension. When a comma-\n'

6181

n/a

'separated list of expressions is supplied, its elements are '

6182

n/a

'evaluated\n'

6183

n/a

'from left to right and placed into the list object in that order.\n'

6184

n/a

'When a comprehension is supplied, the list is constructed from the\n'

6185

n/a

'elements resulting from the comprehension.\n',

6186

n/a

'naming': '\n'

6187

n/a

'Naming and binding\n'

6188

n/a

'******************\n'

6189

n/a

'\n'

6190

n/a

'\n'

6191

n/a

'Binding of names\n'

6192

n/a

'================\n'

6193

n/a

'\n'

6194

n/a

'*Names* refer to objects. Names are introduced by name binding\n'

6195

n/a

'operations.\n'

6196

n/a

'\n'

6197

n/a

'The following constructs bind names: formal parameters to '

6198

n/a

'functions,\n'

6199

n/a

'"import" statements, class and function definitions (these bind '

6200

n/a

'the\n'

6201

n/a

'class or function name in the defining block), and targets that '

6202

n/a

'are\n'

6203

n/a

'identifiers if occurring in an assignment, "for" loop header, or '

6204

n/a

'after\n'

6205

n/a

'"as" in a "with" statement or "except" clause. The "import" '

6206

n/a

'statement\n'

6207

n/a

'of the form "from ... import *" binds all names defined in the\n'

6208

n/a

'imported module, except those beginning with an underscore. This '

6209

n/a

'form\n'

6210

n/a

'may only be used at the module level.\n'

6211

n/a

'\n'

6212

n/a

'A target occurring in a "del" statement is also considered bound '

6213

n/a

'for\n'

6214

n/a

'this purpose (though the actual semantics are to unbind the '

6215

n/a

'name).\n'

6216

n/a

'\n'

6217

n/a

'Each assignment or import statement occurs within a block defined '

6218

n/a

'by a\n'

6219

n/a

'class or function definition or at the module level (the '

6220

n/a

'top-level\n'

6221

n/a

'code block).\n'

6222

n/a

'\n'

6223

n/a

'If a name is bound in a block, it is a local variable of that '

6224

n/a

'block,\n'

6225

n/a

'unless declared as "nonlocal" or "global". If a name is bound at '

6226

n/a

'the\n'

6227

n/a

'module level, it is a global variable. (The variables of the '

6228

n/a

'module\n'

6229

n/a

'code block are local and global.) If a variable is used in a '

6230

n/a

'code\n'

6231

n/a

'block but not defined there, it is a *free variable*.\n'

6232

n/a

'\n'

6233

n/a

'Each occurrence of a name in the program text refers to the '

6234

n/a

'*binding*\n'

6235

n/a

'of that name established by the following name resolution rules.\n'

6236

n/a

'\n'

6237

n/a

'\n'

6238

n/a

'Resolution of names\n'

6239

n/a

'===================\n'

6240

n/a

'\n'

6241

n/a

'A *scope* defines the visibility of a name within a block. If a '

6242

n/a

'local\n'

6243

n/a

'variable is defined in a block, its scope includes that block. If '

6244

n/a

'the\n'

6245

n/a

'definition occurs in a function block, the scope extends to any '

6246

n/a

'blocks\n'

6247

n/a

'contained within the defining one, unless a contained block '

6248

n/a

'introduces\n'

6249

n/a

'a different binding for the name.\n'

6250

n/a

'\n'

6251

n/a

'When a name is used in a code block, it is resolved using the '

6252

n/a

'nearest\n'

6253

n/a

'enclosing scope. The set of all such scopes visible to a code '

6254

n/a

'block\n'

6255

n/a

"is called the block's *environment*.\n"

6256

n/a

'\n'

6257

n/a

'When a name is not found at all, a "NameError" exception is '

6258

n/a

'raised. If\n'

6259

n/a

'the current scope is a function scope, and the name refers to a '

6260

n/a

'local\n'

6261

n/a

'variable that has not yet been bound to a value at the point where '

6262

n/a

'the\n'

6263

n/a

'name is used, an "UnboundLocalError" exception is raised.\n'

6264

n/a

'"UnboundLocalError" is a subclass of "NameError".\n'

6265

n/a

'\n'

6266

n/a

'If a name binding operation occurs anywhere within a code block, '

6267

n/a

'all\n'

6268

n/a

'uses of the name within the block are treated as references to '

6269

n/a

'the\n'

6270

n/a

'current block. This can lead to errors when a name is used within '

6271

n/a

'a\n'

6272

n/a

'block before it is bound. This rule is subtle. Python lacks\n'

6273

n/a

'declarations and allows name binding operations to occur anywhere\n'

6274

n/a

'within a code block. The local variables of a code block can be\n'

6275

n/a

'determined by scanning the entire text of the block for name '

6276

n/a

'binding\n'

6277

n/a

'operations.\n'

6278

n/a

'\n'

6279

n/a

'If the "global" statement occurs within a block, all uses of the '

6280

n/a

'name\n'

6281

n/a

'specified in the statement refer to the binding of that name in '

6282

n/a

'the\n'

6283

n/a

'top-level namespace. Names are resolved in the top-level '

6284

n/a

'namespace by\n'

6285

n/a

'searching the global namespace, i.e. the namespace of the module\n'

6286

n/a

'containing the code block, and the builtins namespace, the '

6287

n/a

'namespace\n'

6288

n/a

'of the module "builtins". The global namespace is searched '

6289

n/a

'first. If\n'

6290

n/a

'the name is not found there, the builtins namespace is searched. '

6291

n/a

'The\n'

6292

n/a

'"global" statement must precede all uses of the name.\n'

6293

n/a

'\n'

6294

n/a

'The "global" statement has the same scope as a name binding '

6295

n/a

'operation\n'

6296

n/a

'in the same block. If the nearest enclosing scope for a free '

6297

n/a

'variable\n'

6298

n/a

'contains a global statement, the free variable is treated as a '

6299

n/a

'global.\n'

6300

n/a

'\n'

6301

n/a

'The "nonlocal" statement causes corresponding names to refer to\n'

6302

n/a

'previously bound variables in the nearest enclosing function '

6303

n/a

'scope.\n'

6304

n/a

'"SyntaxError" is raised at compile time if the given name does '

6305

n/a

'not\n'

6306

n/a

'exist in any enclosing function scope.\n'

6307

n/a

'\n'

6308

n/a

'The namespace for a module is automatically created the first time '

6309

n/a

'a\n'

6310

n/a

'module is imported. The main module for a script is always '

6311

n/a

'called\n'

6312

n/a

'"__main__".\n'

6313

n/a

'\n'

6314

n/a

'Class definition blocks and arguments to "exec()" and "eval()" '

6315

n/a

'are\n'

6316

n/a

'special in the context of name resolution. A class definition is '

6317

n/a

'an\n'

6318

n/a

'executable statement that may use and define names. These '

6319

n/a

'references\n'

6320

n/a

'follow the normal rules for name resolution with an exception '

6321

n/a

'that\n'

6322

n/a

'unbound local variables are looked up in the global namespace. '

6323

n/a

'The\n'

6324

n/a

'namespace of the class definition becomes the attribute dictionary '

6325

n/a

'of\n'

6326

n/a

'the class. The scope of names defined in a class block is limited '

6327

n/a

'to\n'

6328

n/a

'the class block; it does not extend to the code blocks of methods '

6329

n/a

'--\n'

6330

n/a

'this includes comprehensions and generator expressions since they '

6331

n/a

'are\n'

6332

n/a

'implemented using a function scope. This means that the '

6333

n/a

'following\n'

6334

n/a

'will fail:\n'

6335

n/a

'\n'

6336

n/a

' class A:\n'

6337

n/a

' a = 42\n'

6338

n/a

' b = list(a + i for i in range(10))\n'

6339

n/a

'\n'

6340

n/a

'\n'

6341

n/a

'Builtins and restricted execution\n'

6342

n/a

'=================================\n'

6343

n/a

'\n'

6344

n/a

'The builtins namespace associated with the execution of a code '

6345

n/a

'block\n'

6346

n/a

'is actually found by looking up the name "__builtins__" in its '

6347

n/a

'global\n'

6348

n/a

'namespace; this should be a dictionary or a module (in the latter '

6349

n/a

'case\n'

6350

n/a

"the module's dictionary is used). By default, when in the "

6351

n/a

'"__main__"\n'

6352

n/a

'module, "__builtins__" is the built-in module "builtins"; when in '

6353

n/a

'any\n'

6354

n/a

'other module, "__builtins__" is an alias for the dictionary of '

6355

n/a

'the\n'

6356

n/a

'"builtins" module itself. "__builtins__" can be set to a '

6357

n/a

'user-created\n'

6358

n/a

'dictionary to create a weak form of restricted execution.\n'

6359

n/a

'\n'

6360

n/a

'**CPython implementation detail:** Users should not touch\n'

6361

n/a

'"__builtins__"; it is strictly an implementation detail. Users\n'

6362

n/a

'wanting to override values in the builtins namespace should '

6363

n/a

'"import"\n'

6364

n/a

'the "builtins" module and modify its attributes appropriately.\n'

6365

n/a

'\n'

6366

n/a

'\n'

6367

n/a

'Interaction with dynamic features\n'

6368

n/a

'=================================\n'

6369

n/a

'\n'

6370

n/a

'Name resolution of free variables occurs at runtime, not at '

6371

n/a

'compile\n'

6372

n/a

'time. This means that the following code will print 42:\n'

6373

n/a

'\n'

6374

n/a

' i = 10\n'

6375

n/a

' def f():\n'

6376

n/a

' print(i)\n'

6377

n/a

' i = 42\n'

6378

n/a

' f()\n'

6379

n/a

'\n'

6380

n/a

'There are several cases where Python statements are illegal when '

6381

n/a

'used\n'

6382

n/a

'in conjunction with nested scopes that contain free variables.\n'

6383

n/a

'\n'

6384

n/a

'If a variable is referenced in an enclosing scope, it is illegal '

6385

n/a

'to\n'

6386

n/a

'delete the name. An error will be reported at compile time.\n'

6387

n/a

'\n'

6388

n/a

'The "eval()" and "exec()" functions do not have access to the '

6389

n/a

'full\n'

6390

n/a

'environment for resolving names. Names may be resolved in the '

6391

n/a

'local\n'

6392

n/a

'and global namespaces of the caller. Free variables are not '

6393

n/a

'resolved\n'

6394

n/a

'in the nearest enclosing namespace, but in the global namespace. '

6395

n/a

'[1]\n'

6396

n/a

'The "exec()" and "eval()" functions have optional arguments to\n'

6397

n/a

'override the global and local namespace. If only one namespace '

6398

n/a

'is\n'

6399

n/a

'specified, it is used for both.\n',

6400

n/a

'nonlocal': '\n'

6401

n/a

'The "nonlocal" statement\n'

6402

n/a

'************************\n'

6403

n/a

'\n'

6404

n/a

' nonlocal_stmt ::= "nonlocal" identifier ("," identifier)*\n'

6405

n/a

'\n'

6406

n/a

'The "nonlocal" statement causes the listed identifiers to refer '

6407

n/a

'to\n'

6408

n/a

'previously bound variables in the nearest enclosing scope '

6409

n/a

'excluding\n'

6410

n/a

'globals. This is important because the default behavior for '

6411

n/a

'binding is\n'

6412

n/a

'to search the local namespace first. The statement allows\n'

6413

n/a

'encapsulated code to rebind variables outside of the local '

6414

n/a

'scope\n'

6415

n/a

'besides the global (module) scope.\n'

6416

n/a

'\n'

6417

n/a

'Names listed in a "nonlocal" statement, unlike those listed in '

6418

n/a

'a\n'

6419

n/a

'"global" statement, must refer to pre-existing bindings in an\n'

6420

n/a

'enclosing scope (the scope in which a new binding should be '

6421

n/a

'created\n'

6422

n/a

'cannot be determined unambiguously).\n'

6423

n/a

'\n'

6424

n/a

'Names listed in a "nonlocal" statement must not collide with '

6425

n/a

'pre-\n'

6426

n/a

'existing bindings in the local scope.\n'

6427

n/a

'\n'

6428

n/a

'See also:\n'

6429

n/a

'\n'

6430

n/a

' **PEP 3104** - Access to Names in Outer Scopes\n'

6431

n/a

' The specification for the "nonlocal" statement.\n',

6432

n/a

'numbers': '\n'

6433

n/a

'Numeric literals\n'

6434

n/a

'****************\n'

6435

n/a

'\n'

6436

n/a

'There are three types of numeric literals: integers, floating '

6437

n/a

'point\n'

6438

n/a

'numbers, and imaginary numbers. There are no complex literals\n'

6439

n/a

'(complex numbers can be formed by adding a real number and an\n'

6440

n/a

'imaginary number).\n'

6441

n/a

'\n'

6442

n/a

'Note that numeric literals do not include a sign; a phrase like '

6443

n/a

'"-1"\n'

6444

n/a

'is actually an expression composed of the unary operator \'"-"\' '

6445

n/a

'and the\n'

6446

n/a

'literal "1".\n',

6447

n/a

'numeric-types': '\n'

6448

n/a

'Emulating numeric types\n'

6449

n/a

'***********************\n'

6450

n/a

'\n'

6451

n/a

'The following methods can be defined to emulate numeric '

6452

n/a

'objects.\n'

6453

n/a

'Methods corresponding to operations that are not supported '

6454

n/a

'by the\n'

6455

n/a

'particular kind of number implemented (e.g., bitwise '

6456

n/a

'operations for\n'

6457

n/a

'non-integral numbers) should be left undefined.\n'

6458

n/a

'\n'

6459

n/a

'object.__add__(self, other)\n'

6460

n/a

'object.__sub__(self, other)\n'

6461

n/a

'object.__mul__(self, other)\n'

6462

n/a

'object.__matmul__(self, other)\n'

6463

n/a

'object.__truediv__(self, other)\n'

6464

n/a

'object.__floordiv__(self, other)\n'

6465

n/a

'object.__mod__(self, other)\n'

6466

n/a

'object.__divmod__(self, other)\n'

6467

n/a

'object.__pow__(self, other[, modulo])\n'

6468

n/a

'object.__lshift__(self, other)\n'

6469

n/a

'object.__rshift__(self, other)\n'

6470

n/a

'object.__and__(self, other)\n'

6471

n/a

'object.__xor__(self, other)\n'

6472

n/a

'object.__or__(self, other)\n'

6473

n/a

'\n'

6474

n/a

' These methods are called to implement the binary '

6475

n/a

'arithmetic\n'

6476

n/a

' operations ("+", "-", "*", "@", "/", "//", "%", '

6477

n/a

'"divmod()",\n'

6478

n/a

' "pow()", "**", "<<", ">>", "&", "^", "|"). For '

6479

n/a

'instance, to\n'

6480

n/a

' evaluate the expression "x + y", where *x* is an '

6481

n/a

'instance of a\n'

6482

n/a

' class that has an "__add__()" method, "x.__add__(y)" is '

6483

n/a

'called.\n'

6484

n/a

' The "__divmod__()" method should be the equivalent to '

6485

n/a

'using\n'

6486

n/a

' "__floordiv__()" and "__mod__()"; it should not be '

6487

n/a

'related to\n'

6488

n/a

' "__truediv__()". Note that "__pow__()" should be '

6489

n/a

'defined to accept\n'

6490

n/a

' an optional third argument if the ternary version of the '

6491

n/a

'built-in\n'

6492

n/a

' "pow()" function is to be supported.\n'

6493

n/a

'\n'

6494

n/a

' If one of those methods does not support the operation '

6495

n/a

'with the\n'

6496

n/a

' supplied arguments, it should return "NotImplemented".\n'

6497

n/a

'\n'

6498

n/a

'object.__radd__(self, other)\n'

6499

n/a

'object.__rsub__(self, other)\n'

6500

n/a

'object.__rmul__(self, other)\n'

6501

n/a

'object.__rmatmul__(self, other)\n'

6502

n/a

'object.__rtruediv__(self, other)\n'

6503

n/a

'object.__rfloordiv__(self, other)\n'

6504

n/a

'object.__rmod__(self, other)\n'

6505

n/a

'object.__rdivmod__(self, other)\n'

6506

n/a

'object.__rpow__(self, other)\n'

6507

n/a

'object.__rlshift__(self, other)\n'

6508

n/a

'object.__rrshift__(self, other)\n'

6509

n/a

'object.__rand__(self, other)\n'

6510

n/a

'object.__rxor__(self, other)\n'

6511

n/a

'object.__ror__(self, other)\n'

6512

n/a

'\n'

6513

n/a

' These methods are called to implement the binary '

6514

n/a

'arithmetic\n'

6515

n/a

' operations ("+", "-", "*", "@", "/", "//", "%", '

6516

n/a

'"divmod()",\n'

6517

n/a

' "pow()", "**", "<<", ">>", "&", "^", "|") with reflected '

6518

n/a

'(swapped)\n'

6519

n/a

' operands. These functions are only called if the left '

6520

n/a

'operand does\n'

6521

n/a

' not support the corresponding operation [3] and the '

6522

n/a

'operands are of\n'

6523

n/a

' different types. [4] For instance, to evaluate the '

6524

n/a

'expression "x -\n'

6525

n/a

' y", where *y* is an instance of a class that has an '

6526

n/a

'"__rsub__()"\n'

6527

n/a

' method, "y.__rsub__(x)" is called if "x.__sub__(y)" '

6528

n/a

'returns\n'

6529

n/a

' *NotImplemented*.\n'

6530

n/a

'\n'

6531

n/a

' Note that ternary "pow()" will not try calling '

6532

n/a

'"__rpow__()" (the\n'

6533

n/a

' coercion rules would become too complicated).\n'

6534

n/a

'\n'

6535

n/a

" Note: If the right operand's type is a subclass of the "

6536

n/a

'left\n'

6537

n/a

" operand's type and that subclass provides the "

6538

n/a

'reflected method\n'

6539

n/a

' for the operation, this method will be called before '

6540

n/a

'the left\n'

6541

n/a

" operand's non-reflected method. This behavior allows "

6542

n/a

'subclasses\n'

6543

n/a

" to override their ancestors' operations.\n"

6544

n/a

'\n'

6545

n/a

'object.__iadd__(self, other)\n'

6546

n/a

'object.__isub__(self, other)\n'

6547

n/a

'object.__imul__(self, other)\n'

6548

n/a

'object.__imatmul__(self, other)\n'

6549

n/a

'object.__itruediv__(self, other)\n'

6550

n/a

'object.__ifloordiv__(self, other)\n'

6551

n/a

'object.__imod__(self, other)\n'

6552

n/a

'object.__ipow__(self, other[, modulo])\n'

6553

n/a

'object.__ilshift__(self, other)\n'

6554

n/a

'object.__irshift__(self, other)\n'

6555

n/a

'object.__iand__(self, other)\n'

6556

n/a

'object.__ixor__(self, other)\n'

6557

n/a

'object.__ior__(self, other)\n'

6558

n/a

'\n'

6559

n/a

' These methods are called to implement the augmented '

6560

n/a

'arithmetic\n'

6561

n/a

' assignments ("+=", "-=", "*=", "@=", "/=", "//=", "%=", '

6562

n/a

'"**=",\n'

6563

n/a

' "<<=", ">>=", "&=", "^=", "|="). These methods should '

6564

n/a

'attempt to\n'

6565

n/a

' do the operation in-place (modifying *self*) and return '

6566

n/a

'the result\n'

6567

n/a

' (which could be, but does not have to be, *self*). If a '

6568

n/a

'specific\n'

6569

n/a

' method is not defined, the augmented assignment falls '

6570

n/a

'back to the\n'

6571

n/a

' normal methods. For instance, if *x* is an instance of '

6572

n/a

'a class\n'

6573

n/a

' with an "__iadd__()" method, "x += y" is equivalent to '

6574

n/a

'"x =\n'

6575

n/a

' x.__iadd__(y)" . Otherwise, "x.__add__(y)" and '

6576

n/a

'"y.__radd__(x)" are\n'

6577

n/a

' considered, as with the evaluation of "x + y". In '

6578

n/a

'certain\n'

6579

n/a

' situations, augmented assignment can result in '

6580

n/a

'unexpected errors\n'

6581

n/a

" (see Why does a_tuple[i] += ['item'] raise an exception "

6582

n/a

'when the\n'

6583

n/a

' addition works?), but this behavior is in fact part of '

6584

n/a

'the data\n'

6585

n/a

' model.\n'

6586

n/a

'\n'

6587

n/a

'object.__neg__(self)\n'

6588

n/a

'object.__pos__(self)\n'

6589

n/a

'object.__abs__(self)\n'

6590

n/a

'object.__invert__(self)\n'

6591

n/a

'\n'

6592

n/a

' Called to implement the unary arithmetic operations '

6593

n/a

'("-", "+",\n'

6594

n/a

' "abs()" and "~").\n'

6595

n/a

'\n'

6596

n/a

'object.__complex__(self)\n'

6597

n/a

'object.__int__(self)\n'

6598

n/a

'object.__float__(self)\n'

6599

n/a

'object.__round__(self[, n])\n'

6600

n/a

'\n'

6601

n/a

' Called to implement the built-in functions "complex()", '

6602

n/a

'"int()",\n'

6603

n/a

' "float()" and "round()". Should return a value of the '

6604

n/a

'appropriate\n'

6605

n/a

' type.\n'

6606

n/a

'\n'

6607

n/a

'object.__index__(self)\n'

6608

n/a

'\n'

6609

n/a

' Called to implement "operator.index()", and whenever '

6610

n/a

'Python needs\n'

6611

n/a

' to losslessly convert the numeric object to an integer '

6612

n/a

'object (such\n'

6613

n/a

' as in slicing, or in the built-in "bin()", "hex()" and '

6614

n/a

'"oct()"\n'

6615

n/a

' functions). Presence of this method indicates that the '

6616

n/a

'numeric\n'

6617

n/a

' object is an integer type. Must return an integer.\n'

6618

n/a

'\n'

6619

n/a

' Note: In order to have a coherent integer type class, '

6620

n/a

'when\n'

6621

n/a

' "__index__()" is defined "__int__()" should also be '

6622

n/a

'defined, and\n'

6623

n/a

' both should return the same value.\n',

6624

n/a

'objects': '\n'

6625

n/a

'Objects, values and types\n'

6626

n/a

'*************************\n'

6627

n/a

'\n'

6628

n/a

"*Objects* are Python's abstraction for data. All data in a "

6629

n/a

'Python\n'

6630

n/a

'program is represented by objects or by relations between '

6631

n/a

'objects. (In\n'

6632

n/a

'a sense, and in conformance to Von Neumann\'s model of a "stored\n'

6633

n/a

'program computer," code is also represented by objects.)\n'

6634

n/a

'\n'

6635

n/a

"Every object has an identity, a type and a value. An object's\n"

6636

n/a

'*identity* never changes once it has been created; you may think '

6637

n/a

'of it\n'

6638

n/a

'as the object\'s address in memory. The \'"is"\' operator '

6639

n/a

'compares the\n'

6640

n/a

'identity of two objects; the "id()" function returns an integer\n'

6641

n/a

'representing its identity.\n'

6642

n/a

'\n'

6643

n/a

'**CPython implementation detail:** For CPython, "id(x)" is the '

6644

n/a

'memory\n'

6645

n/a

'address where "x" is stored.\n'

6646

n/a

'\n'

6647

n/a

"An object's type determines the operations that the object "

6648

n/a

'supports\n'

6649

n/a

'(e.g., "does it have a length?") and also defines the possible '

6650

n/a

'values\n'

6651

n/a

'for objects of that type. The "type()" function returns an '

6652

n/a

"object's\n"

6653

n/a

'type (which is an object itself). Like its identity, an '

6654

n/a

"object's\n"

6655

n/a

'*type* is also unchangeable. [1]\n'

6656

n/a

'\n'

6657

n/a

'The *value* of some objects can change. Objects whose value can\n'

6658

n/a

'change are said to be *mutable*; objects whose value is '

6659

n/a

'unchangeable\n'

6660

n/a

'once they are created are called *immutable*. (The value of an\n'

6661

n/a

'immutable container object that contains a reference to a '

6662

n/a

'mutable\n'

6663

n/a

"object can change when the latter's value is changed; however "

6664

n/a

'the\n'

6665

n/a

'container is still considered immutable, because the collection '

6666

n/a

'of\n'

6667

n/a

'objects it contains cannot be changed. So, immutability is not\n'

6668

n/a

'strictly the same as having an unchangeable value, it is more '

6669

n/a

'subtle.)\n'

6670

n/a

"An object's mutability is determined by its type; for instance,\n"

6671

n/a

'numbers, strings and tuples are immutable, while dictionaries '

6672

n/a

'and\n'

6673

n/a

'lists are mutable.\n'

6674

n/a

'\n'

6675

n/a

'Objects are never explicitly destroyed; however, when they '

6676

n/a

'become\n'

6677

n/a

'unreachable they may be garbage-collected. An implementation is\n'

6678

n/a

'allowed to postpone garbage collection or omit it altogether --- '

6679

n/a

'it is\n'

6680

n/a

'a matter of implementation quality how garbage collection is\n'

6681

n/a

'implemented, as long as no objects are collected that are still\n'

6682

n/a

'reachable.\n'

6683

n/a

'\n'

6684

n/a

'**CPython implementation detail:** CPython currently uses a '

6685

n/a

'reference-\n'

6686

n/a

'counting scheme with (optional) delayed detection of cyclically '

6687

n/a

'linked\n'

6688

n/a

'garbage, which collects most objects as soon as they become\n'

6689

n/a

'unreachable, but is not guaranteed to collect garbage containing\n'

6690

n/a

'circular references. See the documentation of the "gc" module '

6691

n/a

'for\n'

6692

n/a

'information on controlling the collection of cyclic garbage. '

6693

n/a

'Other\n'

6694

n/a

'implementations act differently and CPython may change. Do not '

6695

n/a

'depend\n'

6696

n/a

'on immediate finalization of objects when they become unreachable '

6697

n/a

'(so\n'

6698

n/a

'you should always close files explicitly).\n'

6699

n/a

'\n'

6700

n/a

"Note that the use of the implementation's tracing or debugging\n"

6701

n/a

'facilities may keep objects alive that would normally be '

6702

n/a

'collectable.\n'

6703

n/a

'Also note that catching an exception with a \'"try"..."except"\'\n'

6704

n/a

'statement may keep objects alive.\n'

6705

n/a

'\n'

6706

n/a

'Some objects contain references to "external" resources such as '

6707

n/a

'open\n'

6708

n/a

'files or windows. It is understood that these resources are '

6709

n/a

'freed\n'

6710

n/a

'when the object is garbage-collected, but since garbage '

6711

n/a

'collection is\n'

6712

n/a

'not guaranteed to happen, such objects also provide an explicit '

6713

n/a

'way to\n'

6714

n/a

'release the external resource, usually a "close()" method. '

6715

n/a

'Programs\n'

6716

n/a

'are strongly recommended to explicitly close such objects. The\n'

6717

n/a

'\'"try"..."finally"\' statement and the \'"with"\' statement '

6718

n/a

'provide\n'

6719

n/a

'convenient ways to do this.\n'

6720

n/a

'\n'

6721

n/a

'Some objects contain references to other objects; these are '

6722

n/a

'called\n'

6723

n/a

'*containers*. Examples of containers are tuples, lists and\n'

6724

n/a

"dictionaries. The references are part of a container's value. "

6725

n/a

'In\n'

6726

n/a

'most cases, when we talk about the value of a container, we imply '

6727

n/a

'the\n'

6728

n/a

'values, not the identities of the contained objects; however, '

6729

n/a

'when we\n'

6730

n/a

'talk about the mutability of a container, only the identities of '

6731

n/a

'the\n'

6732

n/a

'immediately contained objects are implied. So, if an immutable\n'

6733

n/a

'container (like a tuple) contains a reference to a mutable '

6734

n/a

'object, its\n'

6735

n/a

'value changes if that mutable object is changed.\n'

6736

n/a

'\n'

6737

n/a

'Types affect almost all aspects of object behavior. Even the\n'

6738

n/a

'importance of object identity is affected in some sense: for '

6739

n/a

'immutable\n'

6740

n/a

'types, operations that compute new values may actually return a\n'

6741

n/a

'reference to any existing object with the same type and value, '

6742

n/a

'while\n'

6743

n/a

'for mutable objects this is not allowed. E.g., after "a = 1; b = '

6744

n/a

'1",\n'

6745

n/a

'"a" and "b" may or may not refer to the same object with the '

6746

n/a

'value\n'

6747

n/a

'one, depending on the implementation, but after "c = []; d = []", '

6748

n/a

'"c"\n'

6749

n/a

'and "d" are guaranteed to refer to two different, unique, newly\n'

6750

n/a

'created empty lists. (Note that "c = d = []" assigns the same '

6751

n/a

'object\n'

6752

n/a

'to both "c" and "d".)\n',

6753

n/a

'operator-summary': '\n'

6754

n/a

'Operator precedence\n'

6755

n/a

'*******************\n'

6756

n/a

'\n'

6757

n/a

'The following table summarizes the operator precedence '

6758

n/a

'in Python, from\n'

6759

n/a

'lowest precedence (least binding) to highest precedence '

6760

n/a

'(most\n'

6761

n/a

'binding). Operators in the same box have the same '

6762

n/a

'precedence. Unless\n'

6763

n/a

'the syntax is explicitly given, operators are binary. '

6764

n/a

'Operators in\n'

6765

n/a

'the same box group left to right (except for '

6766

n/a

'exponentiation, which\n'

6767

n/a

'groups from right to left).\n'

6768

n/a

'\n'

6769

n/a

'Note that comparisons, membership tests, and identity '

6770

n/a

'tests, all have\n'

6771

n/a

'the same precedence and have a left-to-right chaining '

6772

n/a

'feature as\n'

6773

n/a

'described in the Comparisons section.\n'

6774

n/a

'\n'

6775

n/a

'+-------------------------------------------------+---------------------------------------+\n'

6776

n/a

'| Operator | '

6777

n/a

'Description |\n'

6778

n/a

'+=================================================+=======================================+\n'

6779

n/a

'| "lambda" | '

6780

n/a

'Lambda expression |\n'

6781

n/a

'+-------------------------------------------------+---------------------------------------+\n'

6782

n/a

'| "if" -- "else" | '

6783

n/a

'Conditional expression |\n'

6784

n/a

'+-------------------------------------------------+---------------------------------------+\n'

6785

n/a

'| "or" | '

6786

n/a

'Boolean OR |\n'

6787

n/a

'+-------------------------------------------------+---------------------------------------+\n'

6788

n/a

'| "and" | '

6789

n/a

'Boolean AND |\n'

6790

n/a

'+-------------------------------------------------+---------------------------------------+\n'

6791

n/a

'| "not" "x" | '

6792

n/a

'Boolean NOT |\n'

6793

n/a

'+-------------------------------------------------+---------------------------------------+\n'

6794

n/a

'| "in", "not in", "is", "is not", "<", "<=", ">", | '

6795

n/a

'Comparisons, including membership |\n'

6796

n/a

'| ">=", "!=", "==" | '

6797

n/a

'tests and identity tests |\n'

6798

n/a

'+-------------------------------------------------+---------------------------------------+\n'

6799

n/a

'| "|" | '

6800

n/a

'Bitwise OR |\n'

6801

n/a

'+-------------------------------------------------+---------------------------------------+\n'

6802

n/a

'| "^" | '

6803

n/a

'Bitwise XOR |\n'

6804

n/a

'+-------------------------------------------------+---------------------------------------+\n'

6805

n/a

'| "&" | '

6806

n/a

'Bitwise AND |\n'

6807

n/a

'+-------------------------------------------------+---------------------------------------+\n'

6808

n/a

'| "<<", ">>" | '

6809

n/a

'Shifts |\n'

6810

n/a

'+-------------------------------------------------+---------------------------------------+\n'

6811

n/a

'| "+", "-" | '

6812

n/a

'Addition and subtraction |\n'

6813

n/a

'+-------------------------------------------------+---------------------------------------+\n'

6814

n/a

'| "*", "@", "/", "//", "%" | '

6815

n/a

'Multiplication, matrix multiplication |\n'

6816

n/a

'| | '

6817

n/a

'division, remainder [5] |\n'

6818

n/a

'+-------------------------------------------------+---------------------------------------+\n'

6819

n/a

'| "+x", "-x", "~x" | '

6820

n/a

'Positive, negative, bitwise NOT |\n'

6821

n/a

'+-------------------------------------------------+---------------------------------------+\n'

6822

n/a

'| "**" | '

6823

n/a

'Exponentiation [6] |\n'

6824

n/a

'+-------------------------------------------------+---------------------------------------+\n'

6825

n/a

'| "await" "x" | '

6826

n/a

'Await expression |\n'

6827

n/a

'+-------------------------------------------------+---------------------------------------+\n'

6828

n/a

'| "x[index]", "x[index:index]", | '

6829

n/a

'Subscription, slicing, call, |\n'

6830

n/a

'| "x(arguments...)", "x.attribute" | '

6831

n/a

'attribute reference |\n'

6832

n/a

'+-------------------------------------------------+---------------------------------------+\n'

6833

n/a

'| "(expressions...)", "[expressions...]", "{key: | '

6834

n/a

'Binding or tuple display, list |\n'

6835

n/a

'| value...}", "{expressions...}" | '

6836

n/a

'display, dictionary display, set |\n'

6837

n/a

'| | '

6838

n/a

'display |\n'

6839

n/a

'+-------------------------------------------------+---------------------------------------+\n'

6840

n/a

'\n'

6841

n/a

'-[ Footnotes ]-\n'

6842

n/a

'\n'

6843

n/a

'[1] While "abs(x%y) < abs(y)" is true mathematically, '

6844

n/a

'for floats\n'

6845

n/a

' it may not be true numerically due to roundoff. For '

6846

n/a

'example, and\n'

6847

n/a

' assuming a platform on which a Python float is an '

6848

n/a

'IEEE 754 double-\n'

6849

n/a

' precision number, in order that "-1e-100 % 1e100" '

6850

n/a

'have the same\n'

6851

n/a

' sign as "1e100", the computed result is "-1e-100 + '

6852

n/a

'1e100", which\n'

6853

n/a

' is numerically exactly equal to "1e100". The '

6854

n/a

'function\n'

6855

n/a

' "math.fmod()" returns a result whose sign matches '

6856

n/a

'the sign of the\n'

6857

n/a

' first argument instead, and so returns "-1e-100" in '

6858

n/a

'this case.\n'

6859

n/a

' Which approach is more appropriate depends on the '

6860

n/a

'application.\n'

6861

n/a

'\n'

6862

n/a

'[2] If x is very close to an exact integer multiple of '

6863

n/a

"y, it's\n"

6864

n/a

' possible for "x//y" to be one larger than '

6865

n/a

'"(x-x%y)//y" due to\n'

6866

n/a

' rounding. In such cases, Python returns the latter '

6867

n/a

'result, in\n'

6868

n/a

' order to preserve that "divmod(x,y)[0] * y + x % y" '

6869

n/a

'be very close\n'

6870

n/a

' to "x".\n'

6871

n/a

'\n'

6872

n/a

'[3] The Unicode standard distinguishes between *code '

6873

n/a

'points* (e.g.\n'

6874

n/a

' U+0041) and *abstract characters* (e.g. "LATIN '

6875

n/a

'CAPITAL LETTER A").\n'

6876

n/a

' While most abstract characters in Unicode are only '

6877

n/a

'represented\n'

6878

n/a

' using one code point, there is a number of abstract '

6879

n/a

'characters\n'

6880

n/a

' that can in addition be represented using a sequence '

6881

n/a

'of more than\n'

6882

n/a

' one code point. For example, the abstract character '

6883

n/a

'"LATIN\n'

6884

n/a

' CAPITAL LETTER C WITH CEDILLA" can be represented as '

6885

n/a

'a single\n'

6886

n/a

' *precomposed character* at code position U+00C7, or '

6887

n/a

'as a sequence\n'

6888

n/a

' of a *base character* at code position U+0043 (LATIN '

6889

n/a

'CAPITAL\n'

6890

n/a

' LETTER C), followed by a *combining character* at '

6891

n/a

'code position\n'

6892

n/a

' U+0327 (COMBINING CEDILLA).\n'

6893

n/a

'\n'

6894

n/a

' The comparison operators on strings compare at the '

6895

n/a

'level of\n'

6896

n/a

' Unicode code points. This may be counter-intuitive '

6897

n/a

'to humans. For\n'

6898

n/a

' example, ""\\u00C7" == "\\u0043\\u0327"" is "False", '

6899

n/a

'even though both\n'

6900

n/a

' strings represent the same abstract character "LATIN '

6901

n/a

'CAPITAL\n'

6902

n/a

' LETTER C WITH CEDILLA".\n'

6903

n/a

'\n'

6904

n/a

' To compare strings at the level of abstract '

6905

n/a

'characters (that is,\n'

6906

n/a

' in a way intuitive to humans), use '

6907

n/a

'"unicodedata.normalize()".\n'

6908

n/a

'\n'

6909

n/a

'[4] Due to automatic garbage-collection, free lists, and '

6910

n/a

'the\n'

6911

n/a

' dynamic nature of descriptors, you may notice '

6912

n/a

'seemingly unusual\n'

6913

n/a

' behaviour in certain uses of the "is" operator, like '

6914

n/a

'those\n'

6915

n/a

' involving comparisons between instance methods, or '

6916

n/a

'constants.\n'

6917

n/a

' Check their documentation for more info.\n'

6918

n/a

'\n'

6919

n/a

'[5] The "%" operator is also used for string formatting; '

6920

n/a

'the same\n'

6921

n/a

' precedence applies.\n'

6922

n/a

'\n'

6923

n/a

'[6] The power operator "**" binds less tightly than an '

6924

n/a

'arithmetic\n'

6925

n/a

' or bitwise unary operator on its right, that is, '

6926

n/a

'"2**-1" is "0.5".\n',

6927

n/a

'pass': '\n'

6928

n/a

'The "pass" statement\n'

6929

n/a

'********************\n'

6930

n/a

'\n'

6931

n/a

' pass_stmt ::= "pass"\n'

6932

n/a

'\n'

6933

n/a

'"pass" is a null operation --- when it is executed, nothing '

6934

n/a

'happens.\n'

6935

n/a

'It is useful as a placeholder when a statement is required\n'

6936

n/a

'syntactically, but no code needs to be executed, for example:\n'

6937

n/a

'\n'

6938

n/a

' def f(arg): pass # a function that does nothing (yet)\n'

6939

n/a

'\n'

6940

n/a

' class C: pass # a class with no methods (yet)\n',

6941

n/a

'power': '\n'

6942

n/a

'The power operator\n'

6943

n/a

'******************\n'

6944

n/a

'\n'

6945

n/a

'The power operator binds more tightly than unary operators on its\n'

6946

n/a

'left; it binds less tightly than unary operators on its right. '

6947

n/a

'The\n'

6948

n/a

'syntax is:\n'

6949

n/a

'\n'

6950

n/a

' power ::= ( await_expr | primary ) ["**" u_expr]\n'

6951

n/a

'\n'

6952

n/a

'Thus, in an unparenthesized sequence of power and unary operators, '

6953

n/a

'the\n'

6954

n/a

'operators are evaluated from right to left (this does not '

6955

n/a

'constrain\n'

6956

n/a

'the evaluation order for the operands): "-1**2" results in "-1".\n'

6957

n/a

'\n'

6958

n/a

'The power operator has the same semantics as the built-in "pow()"\n'

6959

n/a

'function, when called with two arguments: it yields its left '

6960

n/a

'argument\n'

6961

n/a

'raised to the power of its right argument. The numeric arguments '

6962

n/a

'are\n'

6963

n/a

'first converted to a common type, and the result is of that type.\n'

6964

n/a

'\n'

6965

n/a

'For int operands, the result has the same type as the operands '

6966

n/a

'unless\n'

6967

n/a

'the second argument is negative; in that case, all arguments are\n'

6968

n/a

'converted to float and a float result is delivered. For example,\n'

6969

n/a

'"10**2" returns "100", but "10**-2" returns "0.01".\n'

6970

n/a

'\n'

6971

n/a

'Raising "0.0" to a negative power results in a '

6972

n/a

'"ZeroDivisionError".\n'

6973

n/a

'Raising a negative number to a fractional power results in a '

6974

n/a

'"complex"\n'

6975

n/a

'number. (In earlier versions it raised a "ValueError".)\n',

6976

n/a

'raise': '\n'

6977

n/a

'The "raise" statement\n'

6978

n/a

'*********************\n'

6979

n/a

'\n'

6980

n/a

' raise_stmt ::= "raise" [expression ["from" expression]]\n'

6981

n/a

'\n'

6982

n/a

'If no expressions are present, "raise" re-raises the last '

6983

n/a

'exception\n'

6984

n/a

'that was active in the current scope. If no exception is active '

6985

n/a

'in\n'

6986

n/a

'the current scope, a "RuntimeError" exception is raised indicating\n'

6987

n/a

'that this is an error.\n'

6988

n/a

'\n'

6989

n/a

'Otherwise, "raise" evaluates the first expression as the exception\n'

6990

n/a

'object. It must be either a subclass or an instance of\n'

6991

n/a

'"BaseException". If it is a class, the exception instance will be\n'

6992

n/a

'obtained when needed by instantiating the class with no arguments.\n'

6993

n/a

'\n'

6994

n/a

"The *type* of the exception is the exception instance's class, the\n"

6995

n/a

'*value* is the instance itself.\n'

6996

n/a

'\n'

6997

n/a

'A traceback object is normally created automatically when an '

6998

n/a

'exception\n'

6999

n/a

'is raised and attached to it as the "__traceback__" attribute, '

7000

n/a

'which\n'

7001

n/a

'is writable. You can create an exception and set your own traceback '

7002

n/a

'in\n'

7003

n/a

'one step using the "with_traceback()" exception method (which '

7004

n/a

'returns\n'

7005

n/a

'the same exception instance, with its traceback set to its '

7006

n/a

'argument),\n'

7007

n/a

'like so:\n'

7008

n/a

'\n'

7009

n/a

' raise Exception("foo occurred").with_traceback(tracebackobj)\n'

7010

n/a

'\n'

7011

n/a

'The "from" clause is used for exception chaining: if given, the '

7012

n/a

'second\n'

7013

n/a

'*expression* must be another exception class or instance, which '

7014

n/a

'will\n'

7015

n/a

'then be attached to the raised exception as the "__cause__" '

7016

n/a

'attribute\n'

7017

n/a

'(which is writable). If the raised exception is not handled, both\n'

7018

n/a

'exceptions will be printed:\n'

7019

n/a

'\n'

7020

n/a

' >>> try:\n'

7021

n/a

' ... print(1 / 0)\n'

7022

n/a

' ... except Exception as exc:\n'

7023

n/a

' ... raise RuntimeError("Something bad happened") from exc\n'

7024

n/a

' ...\n'

7025

n/a

' Traceback (most recent call last):\n'

7026

n/a

' File "<stdin>", line 2, in <module>\n'

7027

n/a

' ZeroDivisionError: int division or modulo by zero\n'

7028

n/a

'\n'

7029

n/a

' The above exception was the direct cause of the following '

7030

n/a

'exception:\n'

7031

n/a

'\n'

7032

n/a

' Traceback (most recent call last):\n'

7033

n/a

' File "<stdin>", line 4, in <module>\n'

7034

n/a

' RuntimeError: Something bad happened\n'

7035

n/a

'\n'

7036

n/a

'A similar mechanism works implicitly if an exception is raised '

7037

n/a

'inside\n'

7038

n/a

'an exception handler or a "finally" clause: the previous exception '

7039

n/a

'is\n'

7040

n/a

'then attached as the new exception\'s "__context__" attribute:\n'

7041

n/a

'\n'

7042

n/a

' >>> try:\n'

7043

n/a

' ... print(1 / 0)\n'

7044

n/a

' ... except:\n'

7045

n/a

' ... raise RuntimeError("Something bad happened")\n'

7046

n/a

' ...\n'

7047

n/a

' Traceback (most recent call last):\n'

7048

n/a

' File "<stdin>", line 2, in <module>\n'

7049

n/a

' ZeroDivisionError: int division or modulo by zero\n'

7050

n/a

'\n'

7051

n/a

' During handling of the above exception, another exception '

7052

n/a

'occurred:\n'

7053

n/a

'\n'

7054

n/a

' Traceback (most recent call last):\n'

7055

n/a

' File "<stdin>", line 4, in <module>\n'

7056

n/a

' RuntimeError: Something bad happened\n'

7057

n/a

'\n'

7058

n/a

'Additional information on exceptions can be found in section\n'

7059

n/a

'Exceptions, and information about handling exceptions is in '

7060

n/a

'section\n'

7061

n/a

'The try statement.\n',

7062

n/a

'return': '\n'

7063

n/a

'The "return" statement\n'

7064

n/a

'**********************\n'

7065

n/a

'\n'

7066

n/a

' return_stmt ::= "return" [expression_list]\n'

7067

n/a

'\n'

7068

n/a

'"return" may only occur syntactically nested in a function '

7069

n/a

'definition,\n'

7070

n/a

'not within a nested class definition.\n'

7071

n/a

'\n'

7072

n/a

'If an expression list is present, it is evaluated, else "None" is\n'

7073

n/a

'substituted.\n'

7074

n/a

'\n'

7075

n/a

'"return" leaves the current function call with the expression list '

7076

n/a

'(or\n'

7077

n/a

'"None") as return value.\n'

7078

n/a

'\n'

7079

n/a

'When "return" passes control out of a "try" statement with a '

7080

n/a

'"finally"\n'

7081

n/a

'clause, that "finally" clause is executed before really leaving '

7082

n/a

'the\n'

7083

n/a

'function.\n'

7084

n/a

'\n'

7085

n/a

'In a generator function, the "return" statement indicates that '

7086

n/a

'the\n'

7087

n/a

'generator is done and will cause "StopIteration" to be raised. '

7088

n/a

'The\n'

7089

n/a

'returned value (if any) is used as an argument to construct\n'

7090

n/a

'"StopIteration" and becomes the "StopIteration.value" attribute.\n',

7091

n/a

'sequence-types': '\n'

7092

n/a

'Emulating container types\n'

7093

n/a

'*************************\n'

7094

n/a

'\n'

7095

n/a

'The following methods can be defined to implement '

7096

n/a

'container objects.\n'

7097

n/a

'Containers usually are sequences (such as lists or tuples) '

7098

n/a

'or mappings\n'

7099

n/a

'(like dictionaries), but can represent other containers as '

7100

n/a

'well. The\n'

7101

n/a

'first set of methods is used either to emulate a sequence '

7102

n/a

'or to\n'

7103

n/a

'emulate a mapping; the difference is that for a sequence, '

7104

n/a

'the\n'

7105

n/a

'allowable keys should be the integers *k* for which "0 <= '

7106

n/a

'k < N" where\n'

7107

n/a

'*N* is the length of the sequence, or slice objects, which '

7108

n/a

'define a\n'

7109

n/a

'range of items. It is also recommended that mappings '

7110

n/a

'provide the\n'

7111

n/a

'methods "keys()", "values()", "items()", "get()", '

7112

n/a

'"clear()",\n'

7113

n/a

'"setdefault()", "pop()", "popitem()", "copy()", and '

7114

n/a

'"update()"\n'

7115

n/a

"behaving similar to those for Python's standard dictionary "

7116

n/a

'objects.\n'

7117

n/a

'The "collections" module provides a "MutableMapping" '

7118

n/a

'abstract base\n'

7119

n/a

'class to help create those methods from a base set of '

7120

n/a

'"__getitem__()",\n'

7121

n/a

'"__setitem__()", "__delitem__()", and "keys()". Mutable '

7122

n/a

'sequences\n'

7123

n/a

'should provide methods "append()", "count()", "index()", '

7124

n/a

'"extend()",\n'

7125

n/a

'"insert()", "pop()", "remove()", "reverse()" and "sort()", '

7126

n/a

'like Python\n'

7127

n/a

'standard list objects. Finally, sequence types should '

7128

n/a

'implement\n'

7129

n/a

'addition (meaning concatenation) and multiplication '

7130

n/a

'(meaning\n'

7131

n/a

'repetition) by defining the methods "__add__()", '

7132

n/a

'"__radd__()",\n'

7133

n/a

'"__iadd__()", "__mul__()", "__rmul__()" and "__imul__()" '

7134

n/a

'described\n'

7135

n/a

'below; they should not define other numerical operators. '

7136

n/a

'It is\n'

7137

n/a

'recommended that both mappings and sequences implement '

7138

n/a

'the\n'

7139

n/a

'"__contains__()" method to allow efficient use of the "in" '

7140

n/a

'operator;\n'

7141

n/a

'for mappings, "in" should search the mapping\'s keys; for '

7142

n/a

'sequences, it\n'

7143

n/a

'should search through the values. It is further '

7144

n/a

'recommended that both\n'

7145

n/a

'mappings and sequences implement the "__iter__()" method '

7146

n/a

'to allow\n'

7147

n/a

'efficient iteration through the container; for mappings, '

7148

n/a

'"__iter__()"\n'

7149

n/a

'should be the same as "keys()"; for sequences, it should '

7150

n/a

'iterate\n'

7151

n/a

'through the values.\n'

7152

n/a

'\n'

7153

n/a

'object.__len__(self)\n'

7154

n/a

'\n'

7155

n/a

' Called to implement the built-in function "len()". '

7156

n/a

'Should return\n'

7157

n/a

' the length of the object, an integer ">=" 0. Also, an '

7158

n/a

'object that\n'

7159

n/a

' doesn\'t define a "__bool__()" method and whose '

7160

n/a

'"__len__()" method\n'

7161

n/a

' returns zero is considered to be false in a Boolean '

7162

n/a

'context.\n'

7163

n/a

'\n'

7164

n/a

'object.__length_hint__(self)\n'

7165

n/a

'\n'

7166

n/a

' Called to implement "operator.length_hint()". Should '

7167

n/a

'return an\n'

7168

n/a

' estimated length for the object (which may be greater '

7169

n/a

'or less than\n'

7170

n/a

' the actual length). The length must be an integer ">=" '

7171

n/a

'0. This\n'

7172

n/a

' method is purely an optimization and is never required '

7173

n/a

'for\n'

7174

n/a

' correctness.\n'

7175

n/a

'\n'

7176

n/a

' New in version 3.4.\n'

7177

n/a

'\n'

7178

n/a

'Note: Slicing is done exclusively with the following three '

7179

n/a

'methods.\n'

7180

n/a

' A call like\n'

7181

n/a

'\n'

7182

n/a

' a[1:2] = b\n'

7183

n/a

'\n'

7184

n/a

' is translated to\n'

7185

n/a

'\n'

7186

n/a

' a[slice(1, 2, None)] = b\n'

7187

n/a

'\n'

7188

n/a

' and so forth. Missing slice items are always filled in '

7189

n/a

'with "None".\n'

7190

n/a

'\n'

7191

n/a

'object.__getitem__(self, key)\n'

7192

n/a

'\n'

7193

n/a

' Called to implement evaluation of "self[key]". For '

7194

n/a

'sequence types,\n'

7195

n/a

' the accepted keys should be integers and slice '

7196

n/a

'objects. Note that\n'

7197

n/a

' the special interpretation of negative indexes (if the '

7198

n/a

'class wishes\n'

7199

n/a

' to emulate a sequence type) is up to the '

7200

n/a

'"__getitem__()" method. If\n'

7201

n/a

' *key* is of an inappropriate type, "TypeError" may be '

7202

n/a

'raised; if of\n'

7203

n/a

' a value outside the set of indexes for the sequence '

7204

n/a

'(after any\n'

7205

n/a

' special interpretation of negative values), '

7206

n/a

'"IndexError" should be\n'

7207

n/a

' raised. For mapping types, if *key* is missing (not in '

7208

n/a

'the\n'

7209

n/a

' container), "KeyError" should be raised.\n'

7210

n/a

'\n'

7211

n/a

' Note: "for" loops expect that an "IndexError" will be '

7212

n/a

'raised for\n'

7213

n/a

' illegal indexes to allow proper detection of the end '

7214

n/a

'of the\n'

7215

n/a

' sequence.\n'

7216

n/a

'\n'

7217

n/a

'object.__missing__(self, key)\n'

7218

n/a

'\n'

7219

n/a

' Called by "dict"."__getitem__()" to implement '

7220

n/a

'"self[key]" for dict\n'

7221

n/a

' subclasses when key is not in the dictionary.\n'

7222

n/a

'\n'

7223

n/a

'object.__setitem__(self, key, value)\n'

7224

n/a

'\n'

7225

n/a

' Called to implement assignment to "self[key]". Same '

7226

n/a

'note as for\n'

7227

n/a

' "__getitem__()". This should only be implemented for '

7228

n/a

'mappings if\n'

7229

n/a

' the objects support changes to the values for keys, or '

7230

n/a

'if new keys\n'

7231

n/a

' can be added, or for sequences if elements can be '

7232

n/a

'replaced. The\n'

7233

n/a

' same exceptions should be raised for improper *key* '

7234

n/a

'values as for\n'

7235

n/a

' the "__getitem__()" method.\n'

7236

n/a

'\n'

7237

n/a

'object.__delitem__(self, key)\n'

7238

n/a

'\n'

7239

n/a

' Called to implement deletion of "self[key]". Same note '

7240

n/a

'as for\n'

7241

n/a

' "__getitem__()". This should only be implemented for '

7242

n/a

'mappings if\n'

7243

n/a

' the objects support removal of keys, or for sequences '

7244

n/a

'if elements\n'

7245

n/a

' can be removed from the sequence. The same exceptions '

7246

n/a

'should be\n'

7247

n/a

' raised for improper *key* values as for the '

7248

n/a

'"__getitem__()" method.\n'

7249

n/a

'\n'

7250

n/a

'object.__iter__(self)\n'

7251

n/a

'\n'

7252

n/a

' This method is called when an iterator is required for '

7253

n/a

'a container.\n'

7254

n/a

' This method should return a new iterator object that '

7255

n/a

'can iterate\n'

7256

n/a

' over all the objects in the container. For mappings, '

7257

n/a

'it should\n'

7258

n/a

' iterate over the keys of the container.\n'

7259

n/a

'\n'

7260

n/a

' Iterator objects also need to implement this method; '

7261

n/a

'they are\n'

7262

n/a

' required to return themselves. For more information on '

7263

n/a

'iterator\n'

7264

n/a

' objects, see Iterator Types.\n'

7265

n/a

'\n'

7266

n/a

'object.__reversed__(self)\n'

7267

n/a

'\n'

7268

n/a

' Called (if present) by the "reversed()" built-in to '

7269

n/a

'implement\n'

7270

n/a

' reverse iteration. It should return a new iterator '

7271

n/a

'object that\n'

7272

n/a

' iterates over all the objects in the container in '

7273

n/a

'reverse order.\n'

7274

n/a

'\n'

7275

n/a

' If the "__reversed__()" method is not provided, the '

7276

n/a

'"reversed()"\n'

7277

n/a

' built-in will fall back to using the sequence protocol '

7278

n/a

'("__len__()"\n'

7279

n/a

' and "__getitem__()"). Objects that support the '

7280

n/a

'sequence protocol\n'

7281

n/a

' should only provide "__reversed__()" if they can '

7282

n/a

'provide an\n'

7283

n/a

' implementation that is more efficient than the one '

7284

n/a

'provided by\n'

7285

n/a

' "reversed()".\n'

7286

n/a

'\n'

7287

n/a

'The membership test operators ("in" and "not in") are '

7288

n/a

'normally\n'

7289

n/a

'implemented as an iteration through a sequence. However, '

7290

n/a

'container\n'

7291

n/a

'objects can supply the following special method with a '

7292

n/a

'more efficient\n'

7293

n/a

'implementation, which also does not require the object be '

7294

n/a

'a sequence.\n'

7295

n/a

'\n'

7296

n/a

'object.__contains__(self, item)\n'

7297

n/a

'\n'

7298

n/a

' Called to implement membership test operators. Should '

7299

n/a

'return true\n'

7300

n/a

' if *item* is in *self*, false otherwise. For mapping '

7301

n/a

'objects, this\n'

7302

n/a

' should consider the keys of the mapping rather than the '

7303

n/a

'values or\n'

7304

n/a

' the key-item pairs.\n'

7305

n/a

'\n'

7306

n/a

' For objects that don\'t define "__contains__()", the '

7307

n/a

'membership test\n'

7308

n/a

' first tries iteration via "__iter__()", then the old '

7309

n/a

'sequence\n'

7310

n/a

' iteration protocol via "__getitem__()", see this '

7311

n/a

'section in the\n'

7312

n/a

' language reference.\n',

7313

n/a

'shifting': '\n'

7314

n/a

'Shifting operations\n'

7315

n/a

'*******************\n'

7316

n/a

'\n'

7317

n/a

'The shifting operations have lower priority than the arithmetic\n'

7318

n/a

'operations:\n'

7319

n/a

'\n'

7320

n/a

' shift_expr ::= a_expr | shift_expr ( "<<" | ">>" ) a_expr\n'

7321

n/a

'\n'

7322

n/a

'These operators accept integers as arguments. They shift the '

7323

n/a

'first\n'

7324

n/a

'argument to the left or right by the number of bits given by '

7325

n/a

'the\n'

7326

n/a

'second argument.\n'

7327

n/a

'\n'

7328

n/a

'A right shift by *n* bits is defined as floor division by '

7329

n/a

'"pow(2,n)".\n'

7330

n/a

'A left shift by *n* bits is defined as multiplication with '

7331

n/a

'"pow(2,n)".\n'

7332

n/a

'\n'

7333

n/a

'Note: In the current implementation, the right-hand operand is\n'

7334

n/a

' required to be at most "sys.maxsize". If the right-hand '

7335

n/a

'operand is\n'

7336

n/a

' larger than "sys.maxsize" an "OverflowError" exception is '

7337

n/a

'raised.\n',

7338

n/a

'slicings': '\n'

7339

n/a

'Slicings\n'

7340

n/a

'********\n'

7341

n/a

'\n'

7342

n/a

'A slicing selects a range of items in a sequence object (e.g., '

7343

n/a

'a\n'

7344

n/a

'string, tuple or list). Slicings may be used as expressions or '

7345

n/a

'as\n'

7346

n/a

'targets in assignment or "del" statements. The syntax for a '

7347

n/a

'slicing:\n'

7348

n/a

'\n'

7349

n/a

' slicing ::= primary "[" slice_list "]"\n'

7350

n/a

' slice_list ::= slice_item ("," slice_item)* [","]\n'

7351

n/a

' slice_item ::= expression | proper_slice\n'

7352

n/a

' proper_slice ::= [lower_bound] ":" [upper_bound] [ ":" '

7353

n/a

'[stride] ]\n'

7354

n/a

' lower_bound ::= expression\n'

7355

n/a

' upper_bound ::= expression\n'

7356

n/a

' stride ::= expression\n'

7357

n/a

'\n'

7358

n/a

'There is ambiguity in the formal syntax here: anything that '

7359

n/a

'looks like\n'

7360

n/a

'an expression list also looks like a slice list, so any '

7361

n/a

'subscription\n'

7362

n/a

'can be interpreted as a slicing. Rather than further '

7363

n/a

'complicating the\n'

7364

n/a

'syntax, this is disambiguated by defining that in this case the\n'

7365

n/a

'interpretation as a subscription takes priority over the\n'

7366

n/a

'interpretation as a slicing (this is the case if the slice list\n'

7367

n/a

'contains no proper slice).\n'

7368

n/a

'\n'

7369

n/a

'The semantics for a slicing are as follows. The primary is '

7370

n/a

'indexed\n'

7371

n/a

'(using the same "__getitem__()" method as normal subscription) '

7372

n/a

'with a\n'

7373

n/a

'key that is constructed from the slice list, as follows. If the '

7374

n/a

'slice\n'

7375

n/a

'list contains at least one comma, the key is a tuple containing '

7376

n/a

'the\n'

7377

n/a

'conversion of the slice items; otherwise, the conversion of the '

7378

n/a

'lone\n'

7379

n/a

'slice item is the key. The conversion of a slice item that is '

7380

n/a

'an\n'

7381

n/a

'expression is that expression. The conversion of a proper slice '

7382

n/a

'is a\n'

7383

n/a

'slice object (see section The standard type hierarchy) whose '

7384

n/a

'"start",\n'

7385

n/a

'"stop" and "step" attributes are the values of the expressions '

7386

n/a

'given\n'

7387

n/a

'as lower bound, upper bound and stride, respectively, '

7388

n/a

'substituting\n'

7389

n/a

'"None" for missing expressions.\n',

7390

n/a

'specialattrs': '\n'

7391

n/a

'Special Attributes\n'

7392

n/a

'******************\n'

7393

n/a

'\n'

7394

n/a

'The implementation adds a few special read-only attributes '

7395

n/a

'to several\n'

7396

n/a

'object types, where they are relevant. Some of these are '

7397

n/a

'not reported\n'

7398

n/a

'by the "dir()" built-in function.\n'

7399

n/a

'\n'

7400

n/a

'object.__dict__\n'

7401

n/a

'\n'

7402

n/a

' A dictionary or other mapping object used to store an '

7403

n/a

"object's\n"

7404

n/a

' (writable) attributes.\n'

7405

n/a

'\n'

7406

n/a

'instance.__class__\n'

7407

n/a

'\n'

7408

n/a

' The class to which a class instance belongs.\n'

7409

n/a

'\n'

7410

n/a

'class.__bases__\n'

7411

n/a

'\n'

7412

n/a

' The tuple of base classes of a class object.\n'

7413

n/a

'\n'

7414

n/a

'definition.__name__\n'

7415

n/a

'\n'

7416

n/a

' The name of the class, function, method, descriptor, or '

7417

n/a

'generator\n'

7418

n/a

' instance.\n'

7419

n/a

'\n'

7420

n/a

'definition.__qualname__\n'

7421

n/a

'\n'

7422

n/a

' The *qualified name* of the class, function, method, '

7423

n/a

'descriptor, or\n'

7424

n/a

' generator instance.\n'

7425

n/a

'\n'

7426

n/a

' New in version 3.3.\n'

7427

n/a

'\n'

7428

n/a

'class.__mro__\n'

7429

n/a

'\n'

7430

n/a

' This attribute is a tuple of classes that are considered '

7431

n/a

'when\n'

7432

n/a

' looking for base classes during method resolution.\n'

7433

n/a

'\n'

7434

n/a

'class.mro()\n'

7435

n/a

'\n'

7436

n/a

' This method can be overridden by a metaclass to customize '

7437

n/a

'the\n'

7438

n/a

' method resolution order for its instances. It is called '

7439

n/a

'at class\n'

7440

n/a

' instantiation, and its result is stored in "__mro__".\n'

7441

n/a

'\n'

7442

n/a

'class.__subclasses__()\n'

7443

n/a

'\n'

7444

n/a

' Each class keeps a list of weak references to its '

7445

n/a

'immediate\n'

7446

n/a

' subclasses. This method returns a list of all those '

7447

n/a

'references\n'

7448

n/a

' still alive. Example:\n'

7449

n/a

'\n'

7450

n/a

' >>> int.__subclasses__()\n'

7451

n/a

" [<class 'bool'>]\n"

7452

n/a

'\n'

7453

n/a

'-[ Footnotes ]-\n'

7454

n/a

'\n'

7455

n/a

'[1] Additional information on these special methods may be '

7456

n/a

'found\n'

7457

n/a

' in the Python Reference Manual (Basic customization).\n'

7458

n/a

'\n'

7459

n/a

'[2] As a consequence, the list "[1, 2]" is considered equal '

7460

n/a

'to\n'

7461

n/a

' "[1.0, 2.0]", and similarly for tuples.\n'

7462

n/a

'\n'

7463

n/a

"[3] They must have since the parser can't tell the type of "

7464

n/a

'the\n'

7465

n/a

' operands.\n'

7466

n/a

'\n'

7467

n/a

'[4] Cased characters are those with general category '

7468

n/a

'property\n'

7469

n/a

' being one of "Lu" (Letter, uppercase), "Ll" (Letter, '

7470

n/a

'lowercase),\n'

7471

n/a

' or "Lt" (Letter, titlecase).\n'

7472

n/a

'\n'

7473

n/a

'[5] To format only a tuple you should therefore provide a\n'

7474

n/a

' singleton tuple whose only element is the tuple to be '

7475

n/a

'formatted.\n',

7476

n/a

'specialnames': '\n'

7477

n/a

'Special method names\n'

7478

n/a

'********************\n'

7479

n/a

'\n'

7480

n/a

'A class can implement certain operations that are invoked by '

7481

n/a

'special\n'

7482

n/a

'syntax (such as arithmetic operations or subscripting and '

7483

n/a

'slicing) by\n'

7484

n/a

"defining methods with special names. This is Python's "

7485

n/a

'approach to\n'

7486

n/a

'*operator overloading*, allowing classes to define their own '

7487

n/a

'behavior\n'

7488

n/a

'with respect to language operators. For instance, if a '

7489

n/a

'class defines\n'

7490

n/a

'a method named "__getitem__()", and "x" is an instance of '

7491

n/a

'this class,\n'

7492

n/a

'then "x[i]" is roughly equivalent to "type(x).__getitem__(x, '

7493

n/a

'i)".\n'

7494

n/a

'Except where mentioned, attempts to execute an operation '

7495

n/a

'raise an\n'

7496

n/a

'exception when no appropriate method is defined (typically\n'

7497

n/a

'"AttributeError" or "TypeError").\n'

7498

n/a

'\n'

7499

n/a

'Setting a special method to "None" indicates that the '

7500

n/a

'corresponding\n'

7501

n/a

'operation is not available. For example, if a class sets '

7502

n/a

'"__iter__()"\n'

7503

n/a

'to "None", the class is not iterable, so calling "iter()" on '

7504

n/a

'its\n'

7505

n/a

'instances will raise a "TypeError" (without falling back to\n'

7506

n/a

'"__getitem__()"). [2]\n'

7507

n/a

'\n'

7508

n/a

'When implementing a class that emulates any built-in type, '

7509

n/a

'it is\n'

7510

n/a

'important that the emulation only be implemented to the '

7511

n/a

'degree that it\n'

7512

n/a

'makes sense for the object being modelled. For example, '

7513

n/a

'some\n'

7514

n/a

'sequences may work well with retrieval of individual '

7515

n/a

'elements, but\n'

7516

n/a

'extracting a slice may not make sense. (One example of this '

7517

n/a

'is the\n'

7518

n/a

'"NodeList" interface in the W3C\'s Document Object Model.)\n'

7519

n/a

'\n'

7520

n/a

'\n'

7521

n/a

'Basic customization\n'

7522

n/a

'===================\n'

7523

n/a

'\n'

7524

n/a

'object.__new__(cls[, ...])\n'

7525

n/a

'\n'

7526

n/a

' Called to create a new instance of class *cls*. '

7527

n/a

'"__new__()" is a\n'

7528

n/a

' static method (special-cased so you need not declare it '

7529

n/a

'as such)\n'

7530

n/a

' that takes the class of which an instance was requested '

7531

n/a

'as its\n'

7532

n/a

' first argument. The remaining arguments are those passed '

7533

n/a

'to the\n'

7534

n/a

' object constructor expression (the call to the class). '

7535

n/a

'The return\n'

7536

n/a

' value of "__new__()" should be the new object instance '

7537

n/a

'(usually an\n'

7538

n/a

' instance of *cls*).\n'

7539

n/a

'\n'

7540

n/a

' Typical implementations create a new instance of the '

7541

n/a

'class by\n'

7542

n/a

' invoking the superclass\'s "__new__()" method using\n'

7543

n/a

' "super(currentclass, cls).__new__(cls[, ...])" with '

7544

n/a

'appropriate\n'

7545

n/a

' arguments and then modifying the newly-created instance '

7546

n/a

'as\n'

7547

n/a

' necessary before returning it.\n'

7548

n/a

'\n'

7549

n/a

' If "__new__()" returns an instance of *cls*, then the '

7550

n/a

'new\n'

7551

n/a

' instance\'s "__init__()" method will be invoked like\n'

7552

n/a

' "__init__(self[, ...])", where *self* is the new instance '

7553

n/a

'and the\n'

7554

n/a

' remaining arguments are the same as were passed to '

7555

n/a

'"__new__()".\n'

7556

n/a

'\n'

7557

n/a

' If "__new__()" does not return an instance of *cls*, then '

7558

n/a

'the new\n'

7559

n/a

' instance\'s "__init__()" method will not be invoked.\n'

7560

n/a

'\n'

7561

n/a

' "__new__()" is intended mainly to allow subclasses of '

7562

n/a

'immutable\n'

7563

n/a

' types (like int, str, or tuple) to customize instance '

7564

n/a

'creation. It\n'

7565

n/a

' is also commonly overridden in custom metaclasses in '

7566

n/a

'order to\n'

7567

n/a

' customize class creation.\n'

7568

n/a

'\n'

7569

n/a

'object.__init__(self[, ...])\n'

7570

n/a

'\n'

7571

n/a

' Called after the instance has been created (by '

7572

n/a

'"__new__()"), but\n'

7573

n/a

' before it is returned to the caller. The arguments are '

7574

n/a

'those\n'

7575

n/a

' passed to the class constructor expression. If a base '

7576

n/a

'class has an\n'

7577

n/a

' "__init__()" method, the derived class\'s "__init__()" '

7578

n/a

'method, if\n'

7579

n/a

' any, must explicitly call it to ensure proper '

7580

n/a

'initialization of the\n'

7581

n/a

' base class part of the instance; for example:\n'

7582

n/a

' "BaseClass.__init__(self, [args...])".\n'

7583

n/a

'\n'

7584

n/a

' Because "__new__()" and "__init__()" work together in '

7585

n/a

'constructing\n'

7586

n/a

' objects ("__new__()" to create it, and "__init__()" to '

7587

n/a

'customize\n'

7588

n/a

' it), no non-"None" value may be returned by "__init__()"; '

7589

n/a

'doing so\n'

7590

n/a

' will cause a "TypeError" to be raised at runtime.\n'

7591

n/a

'\n'

7592

n/a

'object.__del__(self)\n'

7593

n/a

'\n'

7594

n/a

' Called when the instance is about to be destroyed. This '

7595

n/a

'is also\n'

7596

n/a

' called a destructor. If a base class has a "__del__()" '

7597

n/a

'method, the\n'

7598

n/a

' derived class\'s "__del__()" method, if any, must '

7599

n/a

'explicitly call it\n'

7600

n/a

' to ensure proper deletion of the base class part of the '

7601

n/a

'instance.\n'

7602

n/a

' Note that it is possible (though not recommended!) for '

7603

n/a

'the\n'

7604

n/a

' "__del__()" method to postpone destruction of the '

7605

n/a

'instance by\n'

7606

n/a

' creating a new reference to it. It may then be called at '

7607

n/a

'a later\n'

7608

n/a

' time when this new reference is deleted. It is not '

7609

n/a

'guaranteed that\n'

7610

n/a

' "__del__()" methods are called for objects that still '

7611

n/a

'exist when\n'

7612

n/a

' the interpreter exits.\n'

7613

n/a

'\n'

7614

n/a

' Note: "del x" doesn\'t directly call "x.__del__()" --- '

7615

n/a

'the former\n'

7616

n/a

' decrements the reference count for "x" by one, and the '

7617

n/a

'latter is\n'

7618

n/a

' only called when "x"\'s reference count reaches zero. '

7619

n/a

'Some common\n'

7620

n/a

' situations that may prevent the reference count of an '

7621

n/a

'object from\n'

7622

n/a

' going to zero include: circular references between '

7623

n/a

'objects (e.g.,\n'

7624

n/a

' a doubly-linked list or a tree data structure with '

7625

n/a

'parent and\n'

7626

n/a

' child pointers); a reference to the object on the stack '

7627

n/a

'frame of\n'

7628

n/a

' a function that caught an exception (the traceback '

7629

n/a

'stored in\n'

7630

n/a

' "sys.exc_info()[2]" keeps the stack frame alive); or a '

7631

n/a

'reference\n'

7632

n/a

' to the object on the stack frame that raised an '

7633

n/a

'unhandled\n'

7634

n/a

' exception in interactive mode (the traceback stored in\n'

7635

n/a

' "sys.last_traceback" keeps the stack frame alive). The '

7636

n/a

'first\n'

7637

n/a

' situation can only be remedied by explicitly breaking '

7638

n/a

'the cycles;\n'

7639

n/a

' the second can be resolved by freeing the reference to '

7640

n/a

'the\n'

7641

n/a

' traceback object when it is no longer useful, and the '

7642

n/a

'third can\n'

7643

n/a

' be resolved by storing "None" in "sys.last_traceback". '

7644

n/a

'Circular\n'

7645

n/a

' references which are garbage are detected and cleaned '

7646

n/a

'up when the\n'

7647

n/a

" cyclic garbage collector is enabled (it's on by "

7648

n/a

'default). Refer\n'

7649

n/a

' to the documentation for the "gc" module for more '

7650

n/a

'information\n'

7651

n/a

' about this topic.\n'

7652

n/a

'\n'

7653

n/a

' Warning: Due to the precarious circumstances under which\n'

7654

n/a

' "__del__()" methods are invoked, exceptions that occur '

7655

n/a

'during\n'

7656

n/a

' their execution are ignored, and a warning is printed '

7657

n/a

'to\n'

7658

n/a

' "sys.stderr" instead. Also, when "__del__()" is invoked '

7659

n/a

'in\n'

7660

n/a

' response to a module being deleted (e.g., when '

7661

n/a

'execution of the\n'

7662

n/a

' program is done), other globals referenced by the '

7663

n/a

'"__del__()"\n'

7664

n/a

' method may already have been deleted or in the process '

7665

n/a

'of being\n'

7666

n/a

' torn down (e.g. the import machinery shutting down). '

7667

n/a

'For this\n'

7668

n/a

' reason, "__del__()" methods should do the absolute '

7669

n/a

'minimum needed\n'

7670

n/a

' to maintain external invariants. Starting with version '

7671

n/a

'1.5,\n'

7672

n/a

' Python guarantees that globals whose name begins with a '

7673

n/a

'single\n'

7674

n/a

' underscore are deleted from their module before other '

7675

n/a

'globals are\n'

7676

n/a

' deleted; if no other references to such globals exist, '

7677

n/a

'this may\n'

7678

n/a

' help in assuring that imported modules are still '

7679

n/a

'available at the\n'

7680

n/a

' time when the "__del__()" method is called.\n'

7681

n/a

'\n'

7682

n/a

'object.__repr__(self)\n'

7683

n/a

'\n'

7684

n/a

' Called by the "repr()" built-in function to compute the '

7685

n/a

'"official"\n'

7686

n/a

' string representation of an object. If at all possible, '

7687

n/a

'this\n'

7688

n/a

' should look like a valid Python expression that could be '

7689

n/a

'used to\n'

7690

n/a

' recreate an object with the same value (given an '

7691

n/a

'appropriate\n'

7692

n/a

' environment). If this is not possible, a string of the '

7693

n/a

'form\n'

7694

n/a

' "<...some useful description...>" should be returned. The '

7695

n/a

'return\n'

7696

n/a

' value must be a string object. If a class defines '

7697

n/a

'"__repr__()" but\n'

7698

n/a

' not "__str__()", then "__repr__()" is also used when an '

7699

n/a

'"informal"\n'

7700

n/a

' string representation of instances of that class is '

7701

n/a

'required.\n'

7702

n/a

'\n'

7703

n/a

' This is typically used for debugging, so it is important '

7704

n/a

'that the\n'

7705

n/a

' representation is information-rich and unambiguous.\n'

7706

n/a

'\n'

7707

n/a

'object.__str__(self)\n'

7708

n/a

'\n'

7709

n/a

' Called by "str(object)" and the built-in functions '

7710

n/a

'"format()" and\n'

7711

n/a

' "print()" to compute the "informal" or nicely printable '

7712

n/a

'string\n'

7713

n/a

' representation of an object. The return value must be a '

7714

n/a

'string\n'

7715

n/a

' object.\n'

7716

n/a

'\n'

7717

n/a

' This method differs from "object.__repr__()" in that '

7718

n/a

'there is no\n'

7719

n/a

' expectation that "__str__()" return a valid Python '

7720

n/a

'expression: a\n'

7721

n/a

' more convenient or concise representation can be used.\n'

7722

n/a

'\n'

7723

n/a

' The default implementation defined by the built-in type '

7724

n/a

'"object"\n'

7725

n/a

' calls "object.__repr__()".\n'

7726

n/a

'\n'

7727

n/a

'object.__bytes__(self)\n'

7728

n/a

'\n'

7729

n/a

' Called by "bytes()" to compute a byte-string '

7730

n/a

'representation of an\n'

7731

n/a

' object. This should return a "bytes" object.\n'

7732

n/a

'\n'

7733

n/a

'object.__format__(self, format_spec)\n'

7734

n/a

'\n'

7735

n/a

' Called by the "format()" built-in function, and by '

7736

n/a

'extension,\n'

7737

n/a

' evaluation of formatted string literals and the '

7738

n/a

'"str.format()"\n'

7739

n/a

' method, to produce a "formatted" string representation of '

7740

n/a

'an\n'

7741

n/a

' object. The "format_spec" argument is a string that '

7742

n/a

'contains a\n'

7743

n/a

' description of the formatting options desired. The '

7744

n/a

'interpretation\n'

7745

n/a

' of the "format_spec" argument is up to the type '

7746

n/a

'implementing\n'

7747

n/a

' "__format__()", however most classes will either '

7748

n/a

'delegate\n'

7749

n/a

' formatting to one of the built-in types, or use a '

7750

n/a

'similar\n'

7751

n/a

' formatting option syntax.\n'

7752

n/a

'\n'

7753

n/a

' See Format Specification Mini-Language for a description '

7754

n/a

'of the\n'

7755

n/a

' standard formatting syntax.\n'

7756

n/a

'\n'

7757

n/a

' The return value must be a string object.\n'

7758

n/a

'\n'

7759

n/a

' Changed in version 3.4: The __format__ method of "object" '

7760

n/a

'itself\n'

7761

n/a

' raises a "TypeError" if passed any non-empty string.\n'

7762

n/a

'\n'

7763

n/a

'object.__lt__(self, other)\n'

7764

n/a

'object.__le__(self, other)\n'

7765

n/a

'object.__eq__(self, other)\n'

7766

n/a

'object.__ne__(self, other)\n'

7767

n/a

'object.__gt__(self, other)\n'

7768

n/a

'object.__ge__(self, other)\n'

7769

n/a

'\n'

7770

n/a

' These are the so-called "rich comparison" methods. The\n'

7771

n/a

' correspondence between operator symbols and method names '

7772

n/a

'is as\n'

7773

n/a

' follows: "x<y" calls "x.__lt__(y)", "x<=y" calls '

7774

n/a

'"x.__le__(y)",\n'

7775

n/a

' "x==y" calls "x.__eq__(y)", "x!=y" calls "x.__ne__(y)", '

7776

n/a

'"x>y" calls\n'

7777

n/a

' "x.__gt__(y)", and "x>=y" calls "x.__ge__(y)".\n'

7778

n/a

'\n'

7779

n/a

' A rich comparison method may return the singleton '

7780

n/a

'"NotImplemented"\n'

7781

n/a

' if it does not implement the operation for a given pair '

7782

n/a

'of\n'

7783

n/a

' arguments. By convention, "False" and "True" are returned '

7784

n/a

'for a\n'

7785

n/a

' successful comparison. However, these methods can return '

7786

n/a

'any value,\n'

7787

n/a

' so if the comparison operator is used in a Boolean '

7788

n/a

'context (e.g.,\n'

7789

n/a

' in the condition of an "if" statement), Python will call '

7790

n/a

'"bool()"\n'

7791

n/a

' on the value to determine if the result is true or '

7792

n/a

'false.\n'

7793

n/a

'\n'

7794

n/a

' By default, "__ne__()" delegates to "__eq__()" and '

7795

n/a

'inverts the\n'

7796

n/a

' result unless it is "NotImplemented". There are no other '

7797

n/a

'implied\n'

7798

n/a

' relationships among the comparison operators, for '

7799

n/a

'example, the\n'

7800

n/a

' truth of "(x<y or x==y)" does not imply "x<=y". To '

7801

n/a

'automatically\n'

7802

n/a

' generate ordering operations from a single root '

7803

n/a

'operation, see\n'

7804

n/a

' "functools.total_ordering()".\n'

7805

n/a

'\n'

7806

n/a

' See the paragraph on "__hash__()" for some important '

7807

n/a

'notes on\n'

7808

n/a

' creating *hashable* objects which support custom '

7809

n/a

'comparison\n'

7810

n/a

' operations and are usable as dictionary keys.\n'

7811

n/a

'\n'

7812

n/a

' There are no swapped-argument versions of these methods '

7813

n/a

'(to be used\n'

7814

n/a

' when the left argument does not support the operation but '

7815

n/a

'the right\n'

7816

n/a

' argument does); rather, "__lt__()" and "__gt__()" are '

7817

n/a

"each other's\n"

7818

n/a

' reflection, "__le__()" and "__ge__()" are each other\'s '

7819

n/a

'reflection,\n'

7820

n/a

' and "__eq__()" and "__ne__()" are their own reflection. '

7821

n/a

'If the\n'

7822

n/a

" operands are of different types, and right operand's type "

7823

n/a

'is a\n'

7824

n/a

" direct or indirect subclass of the left operand's type, "

7825

n/a

'the\n'

7826

n/a

' reflected method of the right operand has priority, '

7827

n/a

'otherwise the\n'

7828

n/a

" left operand's method has priority. Virtual subclassing "

7829

n/a

'is not\n'

7830

n/a

' considered.\n'

7831

n/a

'\n'

7832

n/a

'object.__hash__(self)\n'

7833

n/a

'\n'

7834

n/a

' Called by built-in function "hash()" and for operations '

7835

n/a

'on members\n'

7836

n/a

' of hashed collections including "set", "frozenset", and '

7837

n/a

'"dict".\n'

7838

n/a

' "__hash__()" should return an integer. The only required '

7839

n/a

'property\n'

7840

n/a

' is that objects which compare equal have the same hash '

7841

n/a

'value; it is\n'

7842

n/a

' advised to somehow mix together (e.g. using exclusive or) '

7843

n/a

'the hash\n'

7844

n/a

' values for the components of the object that also play a '

7845

n/a

'part in\n'

7846

n/a

' comparison of objects.\n'

7847

n/a

'\n'

7848

n/a

' Note: "hash()" truncates the value returned from an '

7849

n/a

"object's\n"

7850

n/a

' custom "__hash__()" method to the size of a '

7851

n/a

'"Py_ssize_t". This\n'

7852

n/a

' is typically 8 bytes on 64-bit builds and 4 bytes on '

7853

n/a

'32-bit\n'

7854

n/a

' builds. If an object\'s "__hash__()" must '

7855

n/a

'interoperate on builds\n'

7856

n/a

' of different bit sizes, be sure to check the width on '

7857

n/a

'all\n'

7858

n/a

' supported builds. An easy way to do this is with '

7859

n/a

'"python -c\n'

7860

n/a

' "import sys; print(sys.hash_info.width)"".\n'

7861

n/a

'\n'

7862

n/a

' If a class does not define an "__eq__()" method it should '

7863

n/a

'not\n'

7864

n/a

' define a "__hash__()" operation either; if it defines '

7865

n/a

'"__eq__()"\n'

7866

n/a

' but not "__hash__()", its instances will not be usable as '

7867

n/a

'items in\n'

7868

n/a

' hashable collections. If a class defines mutable objects '

7869

n/a

'and\n'

7870

n/a

' implements an "__eq__()" method, it should not implement\n'

7871

n/a

' "__hash__()", since the implementation of hashable '

7872

n/a

'collections\n'

7873

n/a

" requires that a key's hash value is immutable (if the "

7874

n/a

"object's hash\n"

7875

n/a

' value changes, it will be in the wrong hash bucket).\n'

7876

n/a

'\n'

7877

n/a

' User-defined classes have "__eq__()" and "__hash__()" '

7878

n/a

'methods by\n'

7879

n/a

' default; with them, all objects compare unequal (except '

7880

n/a

'with\n'

7881

n/a

' themselves) and "x.__hash__()" returns an appropriate '

7882

n/a

'value such\n'

7883

n/a

' that "x == y" implies both that "x is y" and "hash(x) == '

7884

n/a

'hash(y)".\n'

7885

n/a

'\n'

7886

n/a

' A class that overrides "__eq__()" and does not define '

7887

n/a

'"__hash__()"\n'

7888

n/a

' will have its "__hash__()" implicitly set to "None". '

7889

n/a

'When the\n'

7890

n/a

' "__hash__()" method of a class is "None", instances of '

7891

n/a

'the class\n'

7892

n/a

' will raise an appropriate "TypeError" when a program '

7893

n/a

'attempts to\n'

7894

n/a

' retrieve their hash value, and will also be correctly '

7895

n/a

'identified as\n'

7896

n/a

' unhashable when checking "isinstance(obj, '

7897

n/a

'collections.Hashable)".\n'

7898

n/a

'\n'

7899

n/a

' If a class that overrides "__eq__()" needs to retain the\n'

7900

n/a

' implementation of "__hash__()" from a parent class, the '

7901

n/a

'interpreter\n'

7902

n/a

' must be told this explicitly by setting "__hash__ =\n'

7903

n/a

' <ParentClass>.__hash__".\n'

7904

n/a

'\n'

7905

n/a

' If a class that does not override "__eq__()" wishes to '

7906

n/a

'suppress\n'

7907

n/a

' hash support, it should include "__hash__ = None" in the '

7908

n/a

'class\n'

7909

n/a

' definition. A class which defines its own "__hash__()" '

7910

n/a

'that\n'

7911

n/a

' explicitly raises a "TypeError" would be incorrectly '

7912

n/a

'identified as\n'

7913

n/a

' hashable by an "isinstance(obj, collections.Hashable)" '

7914

n/a

'call.\n'

7915

n/a

'\n'

7916

n/a

' Note: By default, the "__hash__()" values of str, bytes '

7917

n/a

'and\n'

7918

n/a

' datetime objects are "salted" with an unpredictable '

7919

n/a

'random value.\n'

7920

n/a

' Although they remain constant within an individual '

7921

n/a

'Python\n'

7922

n/a

' process, they are not predictable between repeated '

7923

n/a

'invocations of\n'

7924

n/a

' Python.This is intended to provide protection against a '

7925

n/a

'denial-\n'

7926

n/a

' of-service caused by carefully-chosen inputs that '

7927

n/a

'exploit the\n'

7928

n/a

' worst case performance of a dict insertion, O(n^2) '

7929

n/a

'complexity.\n'

7930

n/a

' See http://www.ocert.org/advisories/ocert-2011-003.html '

7931

n/a

'for\n'

7932

n/a

' details.Changing hash values affects the iteration '

7933

n/a

'order of\n'

7934

n/a

' dicts, sets and other mappings. Python has never made '

7935

n/a

'guarantees\n'

7936

n/a

' about this ordering (and it typically varies between '

7937

n/a

'32-bit and\n'

7938

n/a

' 64-bit builds).See also "PYTHONHASHSEED".\n'

7939

n/a

'\n'

7940

n/a

' Changed in version 3.3: Hash randomization is enabled by '

7941

n/a

'default.\n'

7942

n/a

'\n'

7943

n/a

'object.__bool__(self)\n'

7944

n/a

'\n'

7945

n/a

' Called to implement truth value testing and the built-in '

7946

n/a

'operation\n'

7947

n/a

' "bool()"; should return "False" or "True". When this '

7948

n/a

'method is not\n'

7949

n/a

' defined, "__len__()" is called, if it is defined, and the '

7950

n/a

'object is\n'

7951

n/a

' considered true if its result is nonzero. If a class '

7952

n/a

'defines\n'

7953

n/a

' neither "__len__()" nor "__bool__()", all its instances '

7954

n/a

'are\n'

7955

n/a

' considered true.\n'

7956

n/a

'\n'

7957

n/a

'\n'

7958

n/a

'Customizing attribute access\n'

7959

n/a

'============================\n'

7960

n/a

'\n'

7961

n/a

'The following methods can be defined to customize the '

7962

n/a

'meaning of\n'

7963

n/a

'attribute access (use of, assignment to, or deletion of '

7964

n/a

'"x.name") for\n'

7965

n/a

'class instances.\n'

7966

n/a

'\n'

7967

n/a

'object.__getattr__(self, name)\n'

7968

n/a

'\n'

7969

n/a

' Called when an attribute lookup has not found the '

7970

n/a

'attribute in the\n'

7971

n/a

' usual places (i.e. it is not an instance attribute nor is '

7972

n/a

'it found\n'

7973

n/a

' in the class tree for "self"). "name" is the attribute '

7974

n/a

'name. This\n'

7975

n/a

' method should return the (computed) attribute value or '

7976

n/a

'raise an\n'

7977

n/a

' "AttributeError" exception.\n'

7978

n/a

'\n'

7979

n/a

' Note that if the attribute is found through the normal '

7980

n/a

'mechanism,\n'

7981

n/a

' "__getattr__()" is not called. (This is an intentional '

7982

n/a

'asymmetry\n'

7983

n/a

' between "__getattr__()" and "__setattr__()".) This is '

7984

n/a

'done both for\n'

7985

n/a

' efficiency reasons and because otherwise "__getattr__()" '

7986

n/a

'would have\n'

7987

n/a

' no way to access other attributes of the instance. Note '

7988

n/a

'that at\n'

7989

n/a

' least for instance variables, you can fake total control '

7990

n/a

'by not\n'

7991

n/a

' inserting any values in the instance attribute dictionary '

7992

n/a

'(but\n'

7993

n/a

' instead inserting them in another object). See the\n'

7994

n/a

' "__getattribute__()" method below for a way to actually '

7995

n/a

'get total\n'

7996

n/a

' control over attribute access.\n'

7997

n/a

'\n'

7998

n/a

'object.__getattribute__(self, name)\n'

7999

n/a

'\n'

8000

n/a

' Called unconditionally to implement attribute accesses '

8001

n/a

'for\n'

8002

n/a

' instances of the class. If the class also defines '

8003

n/a

'"__getattr__()",\n'

8004

n/a

' the latter will not be called unless "__getattribute__()" '

8005

n/a

'either\n'

8006

n/a

' calls it explicitly or raises an "AttributeError". This '

8007

n/a

'method\n'

8008

n/a

' should return the (computed) attribute value or raise an\n'

8009

n/a

' "AttributeError" exception. In order to avoid infinite '

8010

n/a

'recursion in\n'

8011

n/a

' this method, its implementation should always call the '

8012

n/a

'base class\n'

8013

n/a

' method with the same name to access any attributes it '

8014

n/a

'needs, for\n'

8015

n/a

' example, "object.__getattribute__(self, name)".\n'

8016

n/a

'\n'

8017

n/a

' Note: This method may still be bypassed when looking up '

8018

n/a

'special\n'

8019

n/a

' methods as the result of implicit invocation via '

8020

n/a

'language syntax\n'

8021

n/a

' or built-in functions. See Special method lookup.\n'

8022

n/a

'\n'

8023

n/a

'object.__setattr__(self, name, value)\n'

8024

n/a

'\n'

8025

n/a

' Called when an attribute assignment is attempted. This '

8026

n/a

'is called\n'

8027

n/a

' instead of the normal mechanism (i.e. store the value in '

8028

n/a

'the\n'

8029

n/a

' instance dictionary). *name* is the attribute name, '

8030

n/a

'*value* is the\n'

8031

n/a

' value to be assigned to it.\n'

8032

n/a

'\n'

8033

n/a

' If "__setattr__()" wants to assign to an instance '

8034

n/a

'attribute, it\n'

8035

n/a

' should call the base class method with the same name, for '

8036

n/a

'example,\n'

8037

n/a

' "object.__setattr__(self, name, value)".\n'

8038

n/a

'\n'

8039

n/a

'object.__delattr__(self, name)\n'

8040

n/a

'\n'

8041

n/a

' Like "__setattr__()" but for attribute deletion instead '

8042

n/a

'of\n'

8043

n/a

' assignment. This should only be implemented if "del '

8044

n/a

'obj.name" is\n'

8045

n/a

' meaningful for the object.\n'

8046

n/a

'\n'

8047

n/a

'object.__dir__(self)\n'

8048

n/a

'\n'

8049

n/a

' Called when "dir()" is called on the object. A sequence '

8050

n/a

'must be\n'

8051

n/a

' returned. "dir()" converts the returned sequence to a '

8052

n/a

'list and\n'

8053

n/a

' sorts it.\n'

8054

n/a

'\n'

8055

n/a

'\n'

8056

n/a

'Implementing Descriptors\n'

8057

n/a

'------------------------\n'

8058

n/a

'\n'

8059

n/a

'The following methods only apply when an instance of the '

8060

n/a

'class\n'

8061

n/a

'containing the method (a so-called *descriptor* class) '

8062

n/a

'appears in an\n'

8063

n/a

"*owner* class (the descriptor must be in either the owner's "

8064

n/a

'class\n'

8065

n/a

'dictionary or in the class dictionary for one of its '

8066

n/a

'parents). In the\n'

8067

n/a

'examples below, "the attribute" refers to the attribute '

8068

n/a

'whose name is\n'

8069

n/a

'the key of the property in the owner class\' "__dict__".\n'

8070

n/a

'\n'

8071

n/a

'object.__get__(self, instance, owner)\n'

8072

n/a

'\n'

8073

n/a

' Called to get the attribute of the owner class (class '

8074

n/a

'attribute\n'

8075

n/a

' access) or of an instance of that class (instance '

8076

n/a

'attribute\n'

8077

n/a

' access). *owner* is always the owner class, while '

8078

n/a

'*instance* is the\n'

8079

n/a

' instance that the attribute was accessed through, or '

8080

n/a

'"None" when\n'

8081

n/a

' the attribute is accessed through the *owner*. This '

8082

n/a

'method should\n'

8083

n/a

' return the (computed) attribute value or raise an '

8084

n/a

'"AttributeError"\n'

8085

n/a

' exception.\n'

8086

n/a

'\n'

8087

n/a

'object.__set__(self, instance, value)\n'

8088

n/a

'\n'

8089

n/a

' Called to set the attribute on an instance *instance* of '

8090

n/a

'the owner\n'

8091

n/a

' class to a new value, *value*.\n'

8092

n/a

'\n'

8093

n/a

'object.__delete__(self, instance)\n'

8094

n/a

'\n'

8095

n/a

' Called to delete the attribute on an instance *instance* '

8096

n/a

'of the\n'

8097

n/a

' owner class.\n'

8098

n/a

'\n'

8099

n/a

'object.__set_name__(self, owner, name)\n'

8100

n/a

'\n'

8101

n/a

' Called at the time the owning class *owner* is created. '

8102

n/a

'The\n'

8103

n/a

' descriptor has been assigned to *name*.\n'

8104

n/a

'\n'

8105

n/a

' New in version 3.6.\n'

8106

n/a

'\n'

8107

n/a

'The attribute "__objclass__" is interpreted by the "inspect" '

8108

n/a

'module as\n'

8109

n/a

'specifying the class where this object was defined (setting '

8110

n/a

'this\n'

8111

n/a

'appropriately can assist in runtime introspection of dynamic '

8112

n/a

'class\n'

8113

n/a

'attributes). For callables, it may indicate that an instance '

8114

n/a

'of the\n'

8115

n/a

'given type (or a subclass) is expected or required as the '

8116

n/a

'first\n'

8117

n/a

'positional argument (for example, CPython sets this '

8118

n/a

'attribute for\n'

8119

n/a

'unbound methods that are implemented in C).\n'

8120

n/a

'\n'

8121

n/a

'\n'

8122

n/a

'Invoking Descriptors\n'

8123

n/a

'--------------------\n'

8124

n/a

'\n'

8125

n/a

'In general, a descriptor is an object attribute with '

8126

n/a

'"binding\n'

8127

n/a

'behavior", one whose attribute access has been overridden by '

8128

n/a

'methods\n'

8129

n/a

'in the descriptor protocol: "__get__()", "__set__()", and\n'

8130

n/a

'"__delete__()". If any of those methods are defined for an '

8131

n/a

'object, it\n'

8132

n/a

'is said to be a descriptor.\n'

8133

n/a

'\n'

8134

n/a

'The default behavior for attribute access is to get, set, or '

8135

n/a

'delete\n'

8136

n/a

"the attribute from an object's dictionary. For instance, "

8137

n/a

'"a.x" has a\n'

8138

n/a

'lookup chain starting with "a.__dict__[\'x\']", then\n'

8139

n/a

'"type(a).__dict__[\'x\']", and continuing through the base '

8140

n/a

'classes of\n'

8141

n/a

'"type(a)" excluding metaclasses.\n'

8142

n/a

'\n'

8143

n/a

'However, if the looked-up value is an object defining one of '

8144

n/a

'the\n'

8145

n/a

'descriptor methods, then Python may override the default '

8146

n/a

'behavior and\n'

8147

n/a

'invoke the descriptor method instead. Where this occurs in '

8148

n/a

'the\n'

8149

n/a

'precedence chain depends on which descriptor methods were '

8150

n/a

'defined and\n'

8151

n/a

'how they were called.\n'

8152

n/a

'\n'

8153

n/a

'The starting point for descriptor invocation is a binding, '

8154

n/a

'"a.x". How\n'

8155

n/a

'the arguments are assembled depends on "a":\n'

8156

n/a

'\n'

8157

n/a

'Direct Call\n'

8158

n/a

' The simplest and least common call is when user code '

8159

n/a

'directly\n'

8160

n/a

' invokes a descriptor method: "x.__get__(a)".\n'

8161

n/a

'\n'

8162

n/a

'Instance Binding\n'

8163

n/a

' If binding to an object instance, "a.x" is transformed '

8164

n/a

'into the\n'

8165

n/a

' call: "type(a).__dict__[\'x\'].__get__(a, type(a))".\n'

8166

n/a

'\n'

8167

n/a

'Class Binding\n'

8168

n/a

' If binding to a class, "A.x" is transformed into the '

8169

n/a

'call:\n'

8170

n/a

' "A.__dict__[\'x\'].__get__(None, A)".\n'

8171

n/a

'\n'

8172

n/a

'Super Binding\n'

8173

n/a

' If "a" is an instance of "super", then the binding '

8174

n/a

'"super(B,\n'

8175

n/a

' obj).m()" searches "obj.__class__.__mro__" for the base '

8176

n/a

'class "A"\n'

8177

n/a

' immediately preceding "B" and then invokes the descriptor '

8178

n/a

'with the\n'

8179

n/a

' call: "A.__dict__[\'m\'].__get__(obj, obj.__class__)".\n'

8180

n/a

'\n'

8181

n/a

'For instance bindings, the precedence of descriptor '

8182

n/a

'invocation depends\n'

8183

n/a

'on the which descriptor methods are defined. A descriptor '

8184

n/a

'can define\n'

8185

n/a

'any combination of "__get__()", "__set__()" and '

8186

n/a

'"__delete__()". If it\n'

8187

n/a

'does not define "__get__()", then accessing the attribute '

8188

n/a

'will return\n'

8189

n/a

'the descriptor object itself unless there is a value in the '

8190

n/a

"object's\n"

8191

n/a

'instance dictionary. If the descriptor defines "__set__()" '

8192

n/a

'and/or\n'

8193

n/a

'"__delete__()", it is a data descriptor; if it defines '

8194

n/a

'neither, it is\n'

8195

n/a

'a non-data descriptor. Normally, data descriptors define '

8196

n/a

'both\n'

8197

n/a

'"__get__()" and "__set__()", while non-data descriptors have '

8198

n/a

'just the\n'

8199

n/a

'"__get__()" method. Data descriptors with "__set__()" and '

8200

n/a

'"__get__()"\n'

8201

n/a

'defined always override a redefinition in an instance '

8202

n/a

'dictionary. In\n'

8203

n/a

'contrast, non-data descriptors can be overridden by '

8204

n/a

'instances.\n'

8205

n/a

'\n'

8206

n/a

'Python methods (including "staticmethod()" and '

8207

n/a

'"classmethod()") are\n'

8208

n/a

'implemented as non-data descriptors. Accordingly, instances '

8209

n/a

'can\n'

8210

n/a

'redefine and override methods. This allows individual '

8211

n/a

'instances to\n'

8212

n/a

'acquire behaviors that differ from other instances of the '

8213

n/a

'same class.\n'

8214

n/a

'\n'

8215

n/a

'The "property()" function is implemented as a data '

8216

n/a

'descriptor.\n'

8217

n/a

'Accordingly, instances cannot override the behavior of a '

8218

n/a

'property.\n'

8219

n/a

'\n'

8220

n/a

'\n'

8221

n/a

'__slots__\n'

8222

n/a

'---------\n'

8223

n/a

'\n'

8224

n/a

'By default, instances of classes have a dictionary for '

8225

n/a

'attribute\n'

8226

n/a

'storage. This wastes space for objects having very few '

8227

n/a

'instance\n'

8228

n/a

'variables. The space consumption can become acute when '

8229

n/a

'creating large\n'

8230

n/a

'numbers of instances.\n'

8231

n/a

'\n'

8232

n/a

'The default can be overridden by defining *__slots__* in a '

8233

n/a

'class\n'

8234

n/a

'definition. The *__slots__* declaration takes a sequence of '

8235

n/a

'instance\n'

8236

n/a

'variables and reserves just enough space in each instance to '

8237

n/a

'hold a\n'

8238

n/a

'value for each variable. Space is saved because *__dict__* '

8239

n/a

'is not\n'

8240

n/a

'created for each instance.\n'

8241

n/a

'\n'

8242

n/a

'object.__slots__\n'

8243

n/a

'\n'

8244

n/a

' This class variable can be assigned a string, iterable, '

8245

n/a

'or sequence\n'

8246

n/a

' of strings with variable names used by instances. '

8247

n/a

'*__slots__*\n'

8248

n/a

' reserves space for the declared variables and prevents '

8249

n/a

'the\n'

8250

n/a

' automatic creation of *__dict__* and *__weakref__* for '

8251

n/a

'each\n'

8252

n/a

' instance.\n'

8253

n/a

'\n'

8254

n/a

'\n'

8255

n/a

'Notes on using *__slots__*\n'

8256

n/a

'~~~~~~~~~~~~~~~~~~~~~~~~~~\n'

8257

n/a

'\n'

8258

n/a

'* When inheriting from a class without *__slots__*, the '

8259

n/a

'*__dict__*\n'

8260

n/a

' attribute of that class will always be accessible, so a '

8261

n/a

'*__slots__*\n'

8262

n/a

' definition in the subclass is meaningless.\n'

8263

n/a

'\n'

8264

n/a

'* Without a *__dict__* variable, instances cannot be '

8265

n/a

'assigned new\n'

8266

n/a

' variables not listed in the *__slots__* definition. '

8267

n/a

'Attempts to\n'

8268

n/a

' assign to an unlisted variable name raises '

8269

n/a

'"AttributeError". If\n'

8270

n/a

' dynamic assignment of new variables is desired, then add\n'

8271

n/a

' "\'__dict__\'" to the sequence of strings in the '

8272

n/a

'*__slots__*\n'

8273

n/a

' declaration.\n'

8274

n/a

'\n'

8275

n/a

'* Without a *__weakref__* variable for each instance, '

8276

n/a

'classes\n'

8277

n/a

' defining *__slots__* do not support weak references to '

8278

n/a

'its\n'

8279

n/a

' instances. If weak reference support is needed, then add\n'

8280

n/a

' "\'__weakref__\'" to the sequence of strings in the '

8281

n/a

'*__slots__*\n'

8282

n/a

' declaration.\n'

8283

n/a

'\n'

8284

n/a

'* *__slots__* are implemented at the class level by '

8285

n/a

'creating\n'

8286

n/a

' descriptors (Implementing Descriptors) for each variable '

8287

n/a

'name. As a\n'

8288

n/a

' result, class attributes cannot be used to set default '

8289

n/a

'values for\n'

8290

n/a

' instance variables defined by *__slots__*; otherwise, the '

8291

n/a

'class\n'

8292

n/a

' attribute would overwrite the descriptor assignment.\n'

8293

n/a

'\n'

8294

n/a

'* The action of a *__slots__* declaration is limited to the '

8295

n/a

'class\n'

8296

n/a

' where it is defined. As a result, subclasses will have a '

8297

n/a

'*__dict__*\n'

8298

n/a

' unless they also define *__slots__* (which must only '

8299

n/a

'contain names\n'

8300

n/a

' of any *additional* slots).\n'

8301

n/a

'\n'

8302

n/a

'* If a class defines a slot also defined in a base class, '

8303

n/a

'the\n'

8304

n/a

' instance variable defined by the base class slot is '

8305

n/a

'inaccessible\n'

8306

n/a

' (except by retrieving its descriptor directly from the '

8307

n/a

'base class).\n'

8308

n/a

' This renders the meaning of the program undefined. In the '

8309

n/a

'future, a\n'

8310

n/a

' check may be added to prevent this.\n'

8311

n/a

'\n'

8312

n/a

'* Nonempty *__slots__* does not work for classes derived '

8313

n/a

'from\n'

8314

n/a

' "variable-length" built-in types such as "int", "bytes" '

8315

n/a

'and "tuple".\n'

8316

n/a

'\n'

8317

n/a

'* Any non-string iterable may be assigned to *__slots__*. '

8318

n/a

'Mappings\n'

8319

n/a

' may also be used; however, in the future, special meaning '

8320

n/a

'may be\n'

8321

n/a

' assigned to the values corresponding to each key.\n'

8322

n/a

'\n'

8323

n/a

'* *__class__* assignment works only if both classes have the '

8324

n/a

'same\n'

8325

n/a

' *__slots__*.\n'

8326

n/a

'\n'

8327

n/a

'\n'

8328

n/a

'Customizing class creation\n'

8329

n/a

'==========================\n'

8330

n/a

'\n'

8331

n/a

'Whenever a class inherits from another class, '

8332

n/a

'*__init_subclass__* is\n'

8333

n/a

'called on that class. This way, it is possible to write '

8334

n/a

'classes which\n'

8335

n/a

'change the behavior of subclasses. This is closely related '

8336

n/a

'to class\n'

8337

n/a

'decorators, but where class decorators only affect the '

8338

n/a

'specific class\n'

8339

n/a

'they\'re applied to, "__init_subclass__" solely applies to '

8340

n/a

'future\n'

8341

n/a

'subclasses of the class defining the method.\n'

8342

n/a

'\n'

8343

n/a

'classmethod object.__init_subclass__(cls)\n'

8344

n/a

'\n'

8345

n/a

' This method is called whenever the containing class is '

8346

n/a

'subclassed.\n'

8347

n/a

' *cls* is then the new subclass. If defined as a normal '

8348

n/a

'instance\n'

8349

n/a

' method, this method is implicitly converted to a class '

8350

n/a

'method.\n'

8351

n/a

'\n'

8352

n/a

' Keyword arguments which are given to a new class are '

8353

n/a

'passed to the\n'

8354

n/a

' parent\'s class "__init_subclass__". For compatibility '

8355

n/a

'with other\n'

8356

n/a

' classes using "__init_subclass__", one should take out '

8357

n/a

'the needed\n'

8358

n/a

' keyword arguments and pass the others over to the base '

8359

n/a

'class, as\n'

8360

n/a

' in:\n'

8361

n/a

'\n'

8362

n/a

' class Philosopher:\n'

8363

n/a

' def __init_subclass__(cls, default_name, '

8364

n/a

'**kwargs):\n'

8365

n/a

' super().__init_subclass__(**kwargs)\n'

8366

n/a

' cls.default_name = default_name\n'

8367

n/a

'\n'

8368

n/a

' class AustralianPhilosopher(Philosopher, '

8369

n/a

'default_name="Bruce"):\n'

8370

n/a

' pass\n'

8371

n/a

'\n'

8372

n/a

' The default implementation "object.__init_subclass__" '

8373

n/a

'does nothing,\n'

8374

n/a

' but raises an error if it is called with any arguments.\n'

8375

n/a

'\n'

8376

n/a

' Note: The metaclass hint "metaclass" is consumed by the '

8377

n/a

'rest of\n'

8378

n/a

' the type machinery, and is never passed to '

8379

n/a

'"__init_subclass__"\n'

8380

n/a

' implementations. The actual metaclass (rather than the '

8381

n/a

'explicit\n'

8382

n/a

' hint) can be accessed as "type(cls)".\n'

8383

n/a

'\n'

8384

n/a

' New in version 3.6.\n'

8385

n/a

'\n'

8386

n/a

'\n'

8387

n/a

'Metaclasses\n'

8388

n/a

'-----------\n'

8389

n/a

'\n'

8390

n/a

'By default, classes are constructed using "type()". The '

8391

n/a

'class body is\n'

8392

n/a

'executed in a new namespace and the class name is bound '

8393

n/a

'locally to the\n'

8394

n/a

'result of "type(name, bases, namespace)".\n'

8395

n/a

'\n'

8396

n/a

'The class creation process can be customized by passing the\n'

8397

n/a

'"metaclass" keyword argument in the class definition line, '

8398

n/a

'or by\n'

8399

n/a

'inheriting from an existing class that included such an '

8400

n/a

'argument. In\n'

8401

n/a

'the following example, both "MyClass" and "MySubclass" are '

8402

n/a

'instances\n'

8403

n/a

'of "Meta":\n'

8404

n/a

'\n'

8405

n/a

' class Meta(type):\n'

8406

n/a

' pass\n'

8407

n/a

'\n'

8408

n/a

' class MyClass(metaclass=Meta):\n'

8409

n/a

' pass\n'

8410

n/a

'\n'

8411

n/a

' class MySubclass(MyClass):\n'

8412

n/a

' pass\n'

8413

n/a

'\n'

8414

n/a

'Any other keyword arguments that are specified in the class '

8415

n/a

'definition\n'

8416

n/a

'are passed through to all metaclass operations described '

8417

n/a

'below.\n'

8418

n/a

'\n'

8419

n/a

'When a class definition is executed, the following steps '

8420

n/a

'occur:\n'

8421

n/a

'\n'

8422

n/a

'* the appropriate metaclass is determined\n'

8423

n/a

'\n'

8424

n/a

'* the class namespace is prepared\n'

8425

n/a

'\n'

8426

n/a

'* the class body is executed\n'

8427

n/a

'\n'

8428

n/a

'* the class object is created\n'

8429

n/a

'\n'

8430

n/a

'\n'

8431

n/a

'Determining the appropriate metaclass\n'

8432

n/a

'-------------------------------------\n'

8433

n/a

'\n'

8434

n/a

'The appropriate metaclass for a class definition is '

8435

n/a

'determined as\n'

8436

n/a

'follows:\n'

8437

n/a

'\n'

8438

n/a

'* if no bases and no explicit metaclass are given, then '

8439

n/a

'"type()" is\n'

8440

n/a

' used\n'

8441

n/a

'\n'

8442

n/a

'* if an explicit metaclass is given and it is *not* an '

8443

n/a

'instance of\n'

8444

n/a

' "type()", then it is used directly as the metaclass\n'

8445

n/a

'\n'

8446

n/a

'* if an instance of "type()" is given as the explicit '

8447

n/a

'metaclass, or\n'

8448

n/a

' bases are defined, then the most derived metaclass is '

8449

n/a

'used\n'

8450

n/a

'\n'

8451

n/a

'The most derived metaclass is selected from the explicitly '

8452

n/a

'specified\n'

8453

n/a

'metaclass (if any) and the metaclasses (i.e. "type(cls)") of '

8454

n/a

'all\n'

8455

n/a

'specified base classes. The most derived metaclass is one '

8456

n/a

'which is a\n'

8457

n/a

'subtype of *all* of these candidate metaclasses. If none of '

8458

n/a

'the\n'

8459

n/a

'candidate metaclasses meets that criterion, then the class '

8460

n/a

'definition\n'

8461

n/a

'will fail with "TypeError".\n'

8462

n/a

'\n'

8463

n/a

'\n'

8464

n/a

'Preparing the class namespace\n'

8465

n/a

'-----------------------------\n'

8466

n/a

'\n'

8467

n/a

'Once the appropriate metaclass has been identified, then the '

8468

n/a

'class\n'

8469

n/a

'namespace is prepared. If the metaclass has a "__prepare__" '

8470

n/a

'attribute,\n'

8471

n/a

'it is called as "namespace = metaclass.__prepare__(name, '

8472

n/a

'bases,\n'

8473

n/a

'**kwds)" (where the additional keyword arguments, if any, '

8474

n/a

'come from\n'

8475

n/a

'the class definition).\n'

8476

n/a

'\n'

8477

n/a

'If the metaclass has no "__prepare__" attribute, then the '

8478

n/a

'class\n'

8479

n/a

'namespace is initialised as an empty ordered mapping.\n'

8480

n/a

'\n'

8481

n/a

'See also:\n'

8482

n/a

'\n'

8483

n/a

' **PEP 3115** - Metaclasses in Python 3000\n'

8484

n/a

' Introduced the "__prepare__" namespace hook\n'

8485

n/a

'\n'

8486

n/a

'\n'

8487

n/a

'Executing the class body\n'

8488

n/a

'------------------------\n'

8489

n/a

'\n'

8490

n/a

'The class body is executed (approximately) as "exec(body, '

8491

n/a

'globals(),\n'

8492

n/a

'namespace)". The key difference from a normal call to '

8493

n/a

'"exec()" is that\n'

8494

n/a

'lexical scoping allows the class body (including any '

8495

n/a

'methods) to\n'

8496

n/a

'reference names from the current and outer scopes when the '

8497

n/a

'class\n'

8498

n/a

'definition occurs inside a function.\n'

8499

n/a

'\n'

8500

n/a

'However, even when the class definition occurs inside the '

8501

n/a

'function,\n'

8502

n/a

'methods defined inside the class still cannot see names '

8503

n/a

'defined at the\n'

8504

n/a

'class scope. Class variables must be accessed through the '

8505

n/a

'first\n'

8506

n/a

'parameter of instance or class methods, and cannot be '

8507

n/a

'accessed at all\n'

8508

n/a

'from static methods.\n'

8509

n/a

'\n'

8510

n/a

'\n'

8511

n/a

'Creating the class object\n'

8512

n/a

'-------------------------\n'

8513

n/a

'\n'

8514

n/a

'Once the class namespace has been populated by executing the '

8515

n/a

'class\n'

8516

n/a

'body, the class object is created by calling '

8517

n/a

'"metaclass(name, bases,\n'

8518

n/a

'namespace, **kwds)" (the additional keywords passed here are '

8519

n/a

'the same\n'

8520

n/a

'as those passed to "__prepare__").\n'

8521

n/a

'\n'

8522

n/a

'This class object is the one that will be referenced by the '

8523

n/a

'zero-\n'

8524

n/a

'argument form of "super()". "__class__" is an implicit '

8525

n/a

'closure\n'

8526

n/a

'reference created by the compiler if any methods in a class '

8527

n/a

'body refer\n'

8528

n/a

'to either "__class__" or "super". This allows the zero '

8529

n/a

'argument form\n'

8530

n/a

'of "super()" to correctly identify the class being defined '

8531

n/a

'based on\n'

8532

n/a

'lexical scoping, while the class or instance that was used '

8533

n/a

'to make the\n'

8534

n/a

'current call is identified based on the first argument '

8535

n/a

'passed to the\n'

8536

n/a

'method.\n'

8537

n/a

'\n'

8538

n/a

'After the class object is created, it is passed to the '

8539

n/a

'class\n'

8540

n/a

'decorators included in the class definition (if any) and the '

8541

n/a

'resulting\n'

8542

n/a

'object is bound in the local namespace as the defined '

8543

n/a

'class.\n'

8544

n/a

'\n'

8545

n/a

'When a new class is created by "type.__new__", the object '

8546

n/a

'provided as\n'

8547

n/a

'the namespace parameter is copied to a new ordered mapping '

8548

n/a

'and the\n'

8549

n/a

'original object is discarded. The new copy is wrapped in a '

8550

n/a

'read-only\n'

8551

n/a

'proxy, which becomes the "__dict__" attribute of the class '

8552

n/a

'object.\n'

8553

n/a

'\n'

8554

n/a

'See also:\n'

8555

n/a

'\n'

8556

n/a

' **PEP 3135** - New super\n'

8557

n/a

' Describes the implicit "__class__" closure reference\n'

8558

n/a

'\n'

8559

n/a

'\n'

8560

n/a

'Metaclass example\n'

8561

n/a

'-----------------\n'

8562

n/a

'\n'

8563

n/a

'The potential uses for metaclasses are boundless. Some ideas '

8564

n/a

'that have\n'

8565

n/a

'been explored include logging, interface checking, '

8566

n/a

'automatic\n'

8567

n/a

'delegation, automatic property creation, proxies, '

8568

n/a

'frameworks, and\n'

8569

n/a

'automatic resource locking/synchronization.\n'

8570

n/a

'\n'

8571

n/a

'Here is an example of a metaclass that uses an\n'

8572

n/a

'"collections.OrderedDict" to remember the order that class '

8573

n/a

'variables\n'

8574

n/a

'are defined:\n'

8575

n/a

'\n'

8576

n/a

' class OrderedClass(type):\n'

8577

n/a

'\n'

8578

n/a

' @classmethod\n'

8579

n/a

' def __prepare__(metacls, name, bases, **kwds):\n'

8580

n/a

' return collections.OrderedDict()\n'

8581

n/a

'\n'

8582

n/a

' def __new__(cls, name, bases, namespace, **kwds):\n'

8583

n/a

' result = type.__new__(cls, name, bases, '

8584

n/a

'dict(namespace))\n'

8585

n/a

' result.members = tuple(namespace)\n'

8586

n/a

' return result\n'

8587

n/a

'\n'

8588

n/a

' class A(metaclass=OrderedClass):\n'

8589

n/a

' def one(self): pass\n'

8590

n/a

' def two(self): pass\n'

8591

n/a

' def three(self): pass\n'

8592

n/a

' def four(self): pass\n'

8593

n/a

'\n'

8594

n/a

' >>> A.members\n'

8595

n/a

" ('__module__', 'one', 'two', 'three', 'four')\n"

8596

n/a

'\n'

8597

n/a

'When the class definition for *A* gets executed, the process '

8598

n/a

'begins\n'

8599

n/a

'with calling the metaclass\'s "__prepare__()" method which '

8600

n/a

'returns an\n'

8601

n/a

'empty "collections.OrderedDict". That mapping records the '

8602

n/a

'methods and\n'

8603

n/a

'attributes of *A* as they are defined within the body of the '

8604

n/a

'class\n'

8605

n/a

'statement. Once those definitions are executed, the ordered '

8606

n/a

'dictionary\n'

8607

n/a

'is fully populated and the metaclass\'s "__new__()" method '

8608

n/a

'gets\n'

8609

n/a

'invoked. That method builds the new type and it saves the '

8610

n/a

'ordered\n'

8611

n/a

'dictionary keys in an attribute called "members".\n'

8612

n/a

'\n'

8613

n/a

'\n'

8614

n/a

'Customizing instance and subclass checks\n'

8615

n/a

'========================================\n'

8616

n/a

'\n'

8617

n/a

'The following methods are used to override the default '

8618

n/a

'behavior of the\n'

8619

n/a

'"isinstance()" and "issubclass()" built-in functions.\n'

8620

n/a

'\n'

8621

n/a

'In particular, the metaclass "abc.ABCMeta" implements these '

8622

n/a

'methods in\n'

8623

n/a

'order to allow the addition of Abstract Base Classes (ABCs) '

8624

n/a

'as\n'

8625

n/a

'"virtual base classes" to any class or type (including '

8626

n/a

'built-in\n'

8627

n/a

'types), including other ABCs.\n'

8628

n/a

'\n'

8629

n/a

'class.__instancecheck__(self, instance)\n'

8630

n/a

'\n'

8631

n/a

' Return true if *instance* should be considered a (direct '

8632

n/a

'or\n'

8633

n/a

' indirect) instance of *class*. If defined, called to '

8634

n/a

'implement\n'

8635

n/a

' "isinstance(instance, class)".\n'

8636

n/a

'\n'

8637

n/a

'class.__subclasscheck__(self, subclass)\n'

8638

n/a

'\n'

8639

n/a

' Return true if *subclass* should be considered a (direct '

8640

n/a

'or\n'

8641

n/a

' indirect) subclass of *class*. If defined, called to '

8642

n/a

'implement\n'

8643

n/a

' "issubclass(subclass, class)".\n'

8644

n/a

'\n'

8645

n/a

'Note that these methods are looked up on the type '

8646

n/a

'(metaclass) of a\n'

8647

n/a

'class. They cannot be defined as class methods in the '

8648

n/a

'actual class.\n'

8649

n/a

'This is consistent with the lookup of special methods that '

8650

n/a

'are called\n'

8651

n/a

'on instances, only in this case the instance is itself a '

8652

n/a

'class.\n'

8653

n/a

'\n'

8654

n/a

'See also:\n'

8655

n/a

'\n'

8656

n/a

' **PEP 3119** - Introducing Abstract Base Classes\n'

8657

n/a

' Includes the specification for customizing '

8658

n/a

'"isinstance()" and\n'

8659

n/a

' "issubclass()" behavior through "__instancecheck__()" '

8660

n/a

'and\n'

8661

n/a

' "__subclasscheck__()", with motivation for this '

8662

n/a

'functionality in\n'

8663

n/a

' the context of adding Abstract Base Classes (see the '

8664

n/a

'"abc"\n'

8665

n/a

' module) to the language.\n'

8666

n/a

'\n'

8667

n/a

'\n'

8668

n/a

'Emulating callable objects\n'

8669

n/a

'==========================\n'

8670

n/a

'\n'

8671

n/a

'object.__call__(self[, args...])\n'

8672

n/a

'\n'

8673

n/a

' Called when the instance is "called" as a function; if '

8674

n/a

'this method\n'

8675

n/a

' is defined, "x(arg1, arg2, ...)" is a shorthand for\n'

8676

n/a

' "x.__call__(arg1, arg2, ...)".\n'

8677

n/a

'\n'

8678

n/a

'\n'

8679

n/a

'Emulating container types\n'

8680

n/a

'=========================\n'

8681

n/a

'\n'

8682

n/a

'The following methods can be defined to implement container '

8683

n/a

'objects.\n'

8684

n/a

'Containers usually are sequences (such as lists or tuples) '

8685

n/a

'or mappings\n'

8686

n/a

'(like dictionaries), but can represent other containers as '

8687

n/a

'well. The\n'

8688

n/a

'first set of methods is used either to emulate a sequence or '

8689

n/a

'to\n'

8690

n/a

'emulate a mapping; the difference is that for a sequence, '

8691

n/a

'the\n'

8692

n/a

'allowable keys should be the integers *k* for which "0 <= k '

8693

n/a

'< N" where\n'

8694

n/a

'*N* is the length of the sequence, or slice objects, which '

8695

n/a

'define a\n'

8696

n/a

'range of items. It is also recommended that mappings '

8697

n/a

'provide the\n'

8698

n/a

'methods "keys()", "values()", "items()", "get()", '

8699

n/a

'"clear()",\n'

8700

n/a

'"setdefault()", "pop()", "popitem()", "copy()", and '

8701

n/a

'"update()"\n'

8702

n/a

"behaving similar to those for Python's standard dictionary "

8703

n/a

'objects.\n'

8704

n/a

'The "collections" module provides a "MutableMapping" '

8705

n/a

'abstract base\n'

8706

n/a

'class to help create those methods from a base set of '

8707

n/a

'"__getitem__()",\n'

8708

n/a

'"__setitem__()", "__delitem__()", and "keys()". Mutable '

8709

n/a

'sequences\n'

8710

n/a

'should provide methods "append()", "count()", "index()", '

8711

n/a

'"extend()",\n'

8712

n/a

'"insert()", "pop()", "remove()", "reverse()" and "sort()", '

8713

n/a

'like Python\n'

8714

n/a

'standard list objects. Finally, sequence types should '

8715

n/a

'implement\n'

8716

n/a

'addition (meaning concatenation) and multiplication '

8717

n/a

'(meaning\n'

8718

n/a

'repetition) by defining the methods "__add__()", '

8719

n/a

'"__radd__()",\n'

8720

n/a

'"__iadd__()", "__mul__()", "__rmul__()" and "__imul__()" '

8721

n/a

'described\n'

8722

n/a

'below; they should not define other numerical operators. It '

8723

n/a

'is\n'

8724

n/a

'recommended that both mappings and sequences implement the\n'

8725

n/a

'"__contains__()" method to allow efficient use of the "in" '

8726

n/a

'operator;\n'

8727

n/a

'for mappings, "in" should search the mapping\'s keys; for '

8728

n/a

'sequences, it\n'

8729

n/a

'should search through the values. It is further recommended '

8730

n/a

'that both\n'

8731

n/a

'mappings and sequences implement the "__iter__()" method to '

8732

n/a

'allow\n'

8733

n/a

'efficient iteration through the container; for mappings, '

8734

n/a

'"__iter__()"\n'

8735

n/a

'should be the same as "keys()"; for sequences, it should '

8736

n/a

'iterate\n'

8737

n/a

'through the values.\n'

8738

n/a

'\n'

8739

n/a

'object.__len__(self)\n'

8740

n/a

'\n'

8741

n/a

' Called to implement the built-in function "len()". '

8742

n/a

'Should return\n'

8743

n/a

' the length of the object, an integer ">=" 0. Also, an '

8744

n/a

'object that\n'

8745

n/a

' doesn\'t define a "__bool__()" method and whose '

8746

n/a

'"__len__()" method\n'

8747

n/a

' returns zero is considered to be false in a Boolean '

8748

n/a

'context.\n'

8749

n/a

'\n'

8750

n/a

'object.__length_hint__(self)\n'

8751

n/a

'\n'

8752

n/a

' Called to implement "operator.length_hint()". Should '

8753

n/a

'return an\n'

8754

n/a

' estimated length for the object (which may be greater or '

8755

n/a

'less than\n'

8756

n/a

' the actual length). The length must be an integer ">=" 0. '

8757

n/a

'This\n'

8758

n/a

' method is purely an optimization and is never required '

8759

n/a

'for\n'

8760

n/a

' correctness.\n'

8761

n/a

'\n'

8762

n/a

' New in version 3.4.\n'

8763

n/a

'\n'

8764

n/a

'Note: Slicing is done exclusively with the following three '

8765

n/a

'methods.\n'

8766

n/a

' A call like\n'

8767

n/a

'\n'

8768

n/a

' a[1:2] = b\n'

8769

n/a

'\n'

8770

n/a

' is translated to\n'

8771

n/a

'\n'

8772

n/a

' a[slice(1, 2, None)] = b\n'

8773

n/a

'\n'

8774

n/a

' and so forth. Missing slice items are always filled in '

8775

n/a

'with "None".\n'

8776

n/a

'\n'

8777

n/a

'object.__getitem__(self, key)\n'

8778

n/a

'\n'

8779

n/a

' Called to implement evaluation of "self[key]". For '

8780

n/a

'sequence types,\n'

8781

n/a

' the accepted keys should be integers and slice objects. '

8782

n/a

'Note that\n'

8783

n/a

' the special interpretation of negative indexes (if the '

8784

n/a

'class wishes\n'

8785

n/a

' to emulate a sequence type) is up to the "__getitem__()" '

8786

n/a

'method. If\n'

8787

n/a

' *key* is of an inappropriate type, "TypeError" may be '

8788

n/a

'raised; if of\n'

8789

n/a

' a value outside the set of indexes for the sequence '

8790

n/a

'(after any\n'

8791

n/a

' special interpretation of negative values), "IndexError" '

8792

n/a

'should be\n'

8793

n/a

' raised. For mapping types, if *key* is missing (not in '

8794

n/a

'the\n'

8795

n/a

' container), "KeyError" should be raised.\n'

8796

n/a

'\n'

8797

n/a

' Note: "for" loops expect that an "IndexError" will be '

8798

n/a

'raised for\n'

8799

n/a

' illegal indexes to allow proper detection of the end of '

8800

n/a

'the\n'

8801

n/a

' sequence.\n'

8802

n/a

'\n'

8803

n/a

'object.__missing__(self, key)\n'

8804

n/a

'\n'

8805

n/a

' Called by "dict"."__getitem__()" to implement "self[key]" '

8806

n/a

'for dict\n'

8807

n/a

' subclasses when key is not in the dictionary.\n'

8808

n/a

'\n'

8809

n/a

'object.__setitem__(self, key, value)\n'

8810

n/a

'\n'

8811

n/a

' Called to implement assignment to "self[key]". Same note '

8812

n/a

'as for\n'

8813

n/a

' "__getitem__()". This should only be implemented for '

8814

n/a

'mappings if\n'

8815

n/a

' the objects support changes to the values for keys, or if '

8816

n/a

'new keys\n'

8817

n/a

' can be added, or for sequences if elements can be '

8818

n/a

'replaced. The\n'

8819

n/a

' same exceptions should be raised for improper *key* '

8820

n/a

'values as for\n'

8821

n/a

' the "__getitem__()" method.\n'

8822

n/a

'\n'

8823

n/a

'object.__delitem__(self, key)\n'

8824

n/a

'\n'

8825

n/a

' Called to implement deletion of "self[key]". Same note '

8826

n/a

'as for\n'

8827

n/a

' "__getitem__()". This should only be implemented for '

8828

n/a

'mappings if\n'

8829

n/a

' the objects support removal of keys, or for sequences if '

8830

n/a

'elements\n'

8831

n/a

' can be removed from the sequence. The same exceptions '

8832

n/a

'should be\n'

8833

n/a

' raised for improper *key* values as for the '

8834

n/a

'"__getitem__()" method.\n'

8835

n/a

'\n'

8836

n/a

'object.__iter__(self)\n'

8837

n/a

'\n'

8838

n/a

' This method is called when an iterator is required for a '

8839

n/a

'container.\n'

8840

n/a

' This method should return a new iterator object that can '

8841

n/a

'iterate\n'

8842

n/a

' over all the objects in the container. For mappings, it '

8843

n/a

'should\n'

8844

n/a

' iterate over the keys of the container.\n'

8845

n/a

'\n'

8846

n/a

' Iterator objects also need to implement this method; they '

8847

n/a

'are\n'

8848

n/a

' required to return themselves. For more information on '

8849

n/a

'iterator\n'

8850

n/a

' objects, see Iterator Types.\n'

8851

n/a

'\n'

8852

n/a

'object.__reversed__(self)\n'

8853

n/a

'\n'

8854

n/a

' Called (if present) by the "reversed()" built-in to '

8855

n/a

'implement\n'

8856

n/a

' reverse iteration. It should return a new iterator '

8857

n/a

'object that\n'

8858

n/a

' iterates over all the objects in the container in reverse '

8859

n/a

'order.\n'

8860

n/a

'\n'

8861

n/a

' If the "__reversed__()" method is not provided, the '

8862

n/a

'"reversed()"\n'

8863

n/a

' built-in will fall back to using the sequence protocol '

8864

n/a

'("__len__()"\n'

8865

n/a

' and "__getitem__()"). Objects that support the sequence '

8866

n/a

'protocol\n'

8867

n/a

' should only provide "__reversed__()" if they can provide '

8868

n/a

'an\n'

8869

n/a

' implementation that is more efficient than the one '

8870

n/a

'provided by\n'

8871

n/a

' "reversed()".\n'

8872

n/a

'\n'

8873

n/a

'The membership test operators ("in" and "not in") are '

8874

n/a

'normally\n'

8875

n/a

'implemented as an iteration through a sequence. However, '

8876

n/a

'container\n'

8877

n/a

'objects can supply the following special method with a more '

8878

n/a

'efficient\n'

8879

n/a

'implementation, which also does not require the object be a '

8880

n/a

'sequence.\n'

8881

n/a

'\n'

8882

n/a

'object.__contains__(self, item)\n'

8883

n/a

'\n'

8884

n/a

' Called to implement membership test operators. Should '

8885

n/a

'return true\n'

8886

n/a

' if *item* is in *self*, false otherwise. For mapping '

8887

n/a

'objects, this\n'

8888

n/a

' should consider the keys of the mapping rather than the '

8889

n/a

'values or\n'

8890

n/a

' the key-item pairs.\n'

8891

n/a

'\n'

8892

n/a

' For objects that don\'t define "__contains__()", the '

8893

n/a

'membership test\n'

8894

n/a

' first tries iteration via "__iter__()", then the old '

8895

n/a

'sequence\n'

8896

n/a

' iteration protocol via "__getitem__()", see this section '

8897

n/a

'in the\n'

8898

n/a

' language reference.\n'

8899

n/a

'\n'

8900

n/a

'\n'

8901

n/a

'Emulating numeric types\n'

8902

n/a

'=======================\n'

8903

n/a

'\n'

8904

n/a

'The following methods can be defined to emulate numeric '

8905

n/a

'objects.\n'

8906

n/a

'Methods corresponding to operations that are not supported '

8907

n/a

'by the\n'

8908

n/a

'particular kind of number implemented (e.g., bitwise '

8909

n/a

'operations for\n'

8910

n/a

'non-integral numbers) should be left undefined.\n'

8911

n/a

'\n'

8912

n/a

'object.__add__(self, other)\n'

8913

n/a

'object.__sub__(self, other)\n'

8914

n/a

'object.__mul__(self, other)\n'

8915

n/a

'object.__matmul__(self, other)\n'

8916

n/a

'object.__truediv__(self, other)\n'

8917

n/a

'object.__floordiv__(self, other)\n'

8918

n/a

'object.__mod__(self, other)\n'

8919

n/a

'object.__divmod__(self, other)\n'

8920

n/a

'object.__pow__(self, other[, modulo])\n'

8921

n/a

'object.__lshift__(self, other)\n'

8922

n/a

'object.__rshift__(self, other)\n'

8923

n/a

'object.__and__(self, other)\n'

8924

n/a

'object.__xor__(self, other)\n'

8925

n/a

'object.__or__(self, other)\n'

8926

n/a

'\n'

8927

n/a

' These methods are called to implement the binary '

8928

n/a

'arithmetic\n'

8929

n/a

' operations ("+", "-", "*", "@", "/", "//", "%", '

8930

n/a

'"divmod()",\n'

8931

n/a

' "pow()", "**", "<<", ">>", "&", "^", "|"). For instance, '

8932

n/a

'to\n'

8933

n/a

' evaluate the expression "x + y", where *x* is an instance '

8934

n/a

'of a\n'

8935

n/a

' class that has an "__add__()" method, "x.__add__(y)" is '

8936

n/a

'called.\n'

8937

n/a

' The "__divmod__()" method should be the equivalent to '

8938

n/a

'using\n'

8939

n/a

' "__floordiv__()" and "__mod__()"; it should not be '

8940

n/a

'related to\n'

8941

n/a

' "__truediv__()". Note that "__pow__()" should be defined '

8942

n/a

'to accept\n'

8943

n/a

' an optional third argument if the ternary version of the '

8944

n/a

'built-in\n'

8945

n/a

' "pow()" function is to be supported.\n'

8946

n/a

'\n'

8947

n/a

' If one of those methods does not support the operation '

8948

n/a

'with the\n'

8949

n/a

' supplied arguments, it should return "NotImplemented".\n'

8950

n/a

'\n'

8951

n/a

'object.__radd__(self, other)\n'

8952

n/a

'object.__rsub__(self, other)\n'

8953

n/a

'object.__rmul__(self, other)\n'

8954

n/a

'object.__rmatmul__(self, other)\n'

8955

n/a

'object.__rtruediv__(self, other)\n'

8956

n/a

'object.__rfloordiv__(self, other)\n'

8957

n/a

'object.__rmod__(self, other)\n'

8958

n/a

'object.__rdivmod__(self, other)\n'

8959

n/a

'object.__rpow__(self, other)\n'

8960

n/a

'object.__rlshift__(self, other)\n'

8961

n/a

'object.__rrshift__(self, other)\n'

8962

n/a

'object.__rand__(self, other)\n'

8963

n/a

'object.__rxor__(self, other)\n'

8964

n/a

'object.__ror__(self, other)\n'

8965

n/a

'\n'

8966

n/a

' These methods are called to implement the binary '

8967

n/a

'arithmetic\n'

8968

n/a

' operations ("+", "-", "*", "@", "/", "//", "%", '

8969

n/a

'"divmod()",\n'

8970

n/a

' "pow()", "**", "<<", ">>", "&", "^", "|") with reflected '

8971

n/a

'(swapped)\n'

8972

n/a

' operands. These functions are only called if the left '

8973

n/a

'operand does\n'

8974

n/a

' not support the corresponding operation [3] and the '

8975

n/a

'operands are of\n'

8976

n/a

' different types. [4] For instance, to evaluate the '

8977

n/a

'expression "x -\n'

8978

n/a

' y", where *y* is an instance of a class that has an '

8979

n/a

'"__rsub__()"\n'

8980

n/a

' method, "y.__rsub__(x)" is called if "x.__sub__(y)" '

8981

n/a

'returns\n'

8982

n/a

' *NotImplemented*.\n'

8983

n/a

'\n'

8984

n/a

' Note that ternary "pow()" will not try calling '

8985

n/a

'"__rpow__()" (the\n'

8986

n/a

' coercion rules would become too complicated).\n'

8987

n/a

'\n'

8988

n/a

" Note: If the right operand's type is a subclass of the "

8989

n/a

'left\n'

8990

n/a

" operand's type and that subclass provides the reflected "

8991

n/a

'method\n'

8992

n/a

' for the operation, this method will be called before '

8993

n/a

'the left\n'

8994

n/a

" operand's non-reflected method. This behavior allows "

8995

n/a

'subclasses\n'

8996

n/a

" to override their ancestors' operations.\n"

8997

n/a

'\n'

8998

n/a

'object.__iadd__(self, other)\n'

8999

n/a

'object.__isub__(self, other)\n'

9000

n/a

'object.__imul__(self, other)\n'

9001

n/a

'object.__imatmul__(self, other)\n'

9002

n/a

'object.__itruediv__(self, other)\n'

9003

n/a

'object.__ifloordiv__(self, other)\n'

9004

n/a

'object.__imod__(self, other)\n'

9005

n/a

'object.__ipow__(self, other[, modulo])\n'

9006

n/a

'object.__ilshift__(self, other)\n'

9007

n/a

'object.__irshift__(self, other)\n'

9008

n/a

'object.__iand__(self, other)\n'

9009

n/a

'object.__ixor__(self, other)\n'

9010

n/a

'object.__ior__(self, other)\n'

9011

n/a

'\n'

9012

n/a

' These methods are called to implement the augmented '

9013

n/a

'arithmetic\n'

9014

n/a

' assignments ("+=", "-=", "*=", "@=", "/=", "//=", "%=", '

9015

n/a

'"**=",\n'

9016

n/a

' "<<=", ">>=", "&=", "^=", "|="). These methods should '

9017

n/a

'attempt to\n'

9018

n/a

' do the operation in-place (modifying *self*) and return '

9019

n/a

'the result\n'

9020

n/a

' (which could be, but does not have to be, *self*). If a '

9021

n/a

'specific\n'

9022

n/a

' method is not defined, the augmented assignment falls '

9023

n/a

'back to the\n'

9024

n/a

' normal methods. For instance, if *x* is an instance of a '

9025

n/a

'class\n'

9026

n/a

' with an "__iadd__()" method, "x += y" is equivalent to "x '

9027

n/a

'=\n'

9028

n/a

' x.__iadd__(y)" . Otherwise, "x.__add__(y)" and '

9029

n/a

'"y.__radd__(x)" are\n'

9030

n/a

' considered, as with the evaluation of "x + y". In '

9031

n/a

'certain\n'

9032

n/a

' situations, augmented assignment can result in unexpected '

9033

n/a

'errors\n'

9034

n/a

" (see Why does a_tuple[i] += ['item'] raise an exception "

9035

n/a

'when the\n'

9036

n/a

' addition works?), but this behavior is in fact part of '

9037

n/a

'the data\n'

9038

n/a

' model.\n'

9039

n/a

'\n'

9040

n/a

'object.__neg__(self)\n'

9041

n/a

'object.__pos__(self)\n'

9042

n/a

'object.__abs__(self)\n'

9043

n/a

'object.__invert__(self)\n'

9044

n/a

'\n'

9045

n/a

' Called to implement the unary arithmetic operations ("-", '

9046

n/a

'"+",\n'

9047

n/a

' "abs()" and "~").\n'

9048

n/a

'\n'

9049

n/a

'object.__complex__(self)\n'

9050

n/a

'object.__int__(self)\n'

9051

n/a

'object.__float__(self)\n'

9052

n/a

'object.__round__(self[, n])\n'

9053

n/a

'\n'

9054

n/a

' Called to implement the built-in functions "complex()", '

9055

n/a

'"int()",\n'

9056

n/a

' "float()" and "round()". Should return a value of the '

9057

n/a

'appropriate\n'

9058

n/a

' type.\n'

9059

n/a

'\n'

9060

n/a

'object.__index__(self)\n'

9061

n/a

'\n'

9062

n/a

' Called to implement "operator.index()", and whenever '

9063

n/a

'Python needs\n'

9064

n/a

' to losslessly convert the numeric object to an integer '

9065

n/a

'object (such\n'

9066

n/a

' as in slicing, or in the built-in "bin()", "hex()" and '

9067

n/a

'"oct()"\n'

9068

n/a

' functions). Presence of this method indicates that the '

9069

n/a

'numeric\n'

9070

n/a

' object is an integer type. Must return an integer.\n'

9071

n/a

'\n'

9072

n/a

' Note: In order to have a coherent integer type class, '

9073

n/a

'when\n'

9074

n/a

' "__index__()" is defined "__int__()" should also be '

9075

n/a

'defined, and\n'

9076

n/a

' both should return the same value.\n'

9077

n/a

'\n'

9078

n/a

'\n'

9079

n/a

'With Statement Context Managers\n'

9080

n/a

'===============================\n'

9081

n/a

'\n'

9082

n/a

'A *context manager* is an object that defines the runtime '

9083

n/a

'context to\n'

9084

n/a

'be established when executing a "with" statement. The '

9085

n/a

'context manager\n'

9086

n/a

'handles the entry into, and the exit from, the desired '

9087

n/a

'runtime context\n'

9088

n/a

'for the execution of the block of code. Context managers '

9089

n/a

'are normally\n'

9090

n/a

'invoked using the "with" statement (described in section The '

9091

n/a

'with\n'

9092

n/a

'statement), but can also be used by directly invoking their '

9093

n/a

'methods.\n'

9094

n/a

'\n'

9095

n/a

'Typical uses of context managers include saving and '

9096

n/a

'restoring various\n'

9097

n/a

'kinds of global state, locking and unlocking resources, '

9098

n/a

'closing opened\n'

9099

n/a

'files, etc.\n'

9100

n/a

'\n'

9101

n/a

'For more information on context managers, see Context '

9102

n/a

'Manager Types.\n'

9103

n/a

'\n'

9104

n/a

'object.__enter__(self)\n'

9105

n/a

'\n'

9106

n/a

' Enter the runtime context related to this object. The '

9107

n/a

'"with"\n'

9108

n/a

" statement will bind this method's return value to the "

9109

n/a

'target(s)\n'

9110

n/a

' specified in the "as" clause of the statement, if any.\n'

9111

n/a

'\n'

9112

n/a

'object.__exit__(self, exc_type, exc_value, traceback)\n'

9113

n/a

'\n'

9114

n/a

' Exit the runtime context related to this object. The '

9115

n/a

'parameters\n'

9116

n/a

' describe the exception that caused the context to be '

9117

n/a

'exited. If the\n'

9118

n/a

' context was exited without an exception, all three '

9119

n/a

'arguments will\n'

9120

n/a

' be "None".\n'

9121

n/a

'\n'

9122

n/a

' If an exception is supplied, and the method wishes to '

9123

n/a

'suppress the\n'

9124

n/a

' exception (i.e., prevent it from being propagated), it '

9125

n/a

'should\n'

9126

n/a

' return a true value. Otherwise, the exception will be '

9127

n/a

'processed\n'

9128

n/a

' normally upon exit from this method.\n'

9129

n/a

'\n'

9130

n/a

' Note that "__exit__()" methods should not reraise the '

9131

n/a

'passed-in\n'

9132

n/a

" exception; this is the caller's responsibility.\n"

9133

n/a

'\n'

9134

n/a

'See also:\n'

9135

n/a

'\n'

9136

n/a

' **PEP 343** - The "with" statement\n'

9137

n/a

' The specification, background, and examples for the '

9138

n/a

'Python "with"\n'

9139

n/a

' statement.\n'

9140

n/a

'\n'

9141

n/a

'\n'

9142

n/a

'Special method lookup\n'

9143

n/a

'=====================\n'

9144

n/a

'\n'

9145

n/a

'For custom classes, implicit invocations of special methods '

9146

n/a

'are only\n'

9147

n/a

"guaranteed to work correctly if defined on an object's type, "

9148

n/a

'not in\n'

9149

n/a

"the object's instance dictionary. That behaviour is the "

9150

n/a

'reason why\n'

9151

n/a

'the following code raises an exception:\n'

9152

n/a

'\n'

9153

n/a

' >>> class C:\n'

9154

n/a

' ... pass\n'

9155

n/a

' ...\n'

9156

n/a

' >>> c = C()\n'

9157

n/a

' >>> c.__len__ = lambda: 5\n'

9158

n/a

' >>> len(c)\n'

9159

n/a

' Traceback (most recent call last):\n'

9160

n/a

' File "<stdin>", line 1, in <module>\n'

9161

n/a

" TypeError: object of type 'C' has no len()\n"

9162

n/a

'\n'

9163

n/a

'The rationale behind this behaviour lies with a number of '

9164

n/a

'special\n'

9165

n/a

'methods such as "__hash__()" and "__repr__()" that are '

9166

n/a

'implemented by\n'

9167

n/a

'all objects, including type objects. If the implicit lookup '

9168

n/a

'of these\n'

9169

n/a

'methods used the conventional lookup process, they would '

9170

n/a

'fail when\n'

9171

n/a

'invoked on the type object itself:\n'

9172

n/a

'\n'

9173

n/a

' >>> 1 .__hash__() == hash(1)\n'

9174

n/a

' True\n'

9175

n/a

' >>> int.__hash__() == hash(int)\n'

9176

n/a

' Traceback (most recent call last):\n'

9177

n/a

' File "<stdin>", line 1, in <module>\n'

9178

n/a

" TypeError: descriptor '__hash__' of 'int' object needs an "

9179

n/a

'argument\n'

9180

n/a

'\n'

9181

n/a

'Incorrectly attempting to invoke an unbound method of a '

9182

n/a

'class in this\n'

9183

n/a

"way is sometimes referred to as 'metaclass confusion', and "

9184

n/a

'is avoided\n'

9185

n/a

'by bypassing the instance when looking up special methods:\n'

9186

n/a

'\n'

9187

n/a

' >>> type(1).__hash__(1) == hash(1)\n'

9188

n/a

' True\n'

9189

n/a

' >>> type(int).__hash__(int) == hash(int)\n'

9190

n/a

' True\n'

9191

n/a

'\n'

9192

n/a

'In addition to bypassing any instance attributes in the '

9193

n/a

'interest of\n'

9194

n/a

'correctness, implicit special method lookup generally also '

9195

n/a

'bypasses\n'

9196

n/a

'the "__getattribute__()" method even of the object\'s '

9197

n/a

'metaclass:\n'

9198

n/a

'\n'

9199

n/a

' >>> class Meta(type):\n'

9200

n/a

' ... def __getattribute__(*args):\n'

9201

n/a

' ... print("Metaclass getattribute invoked")\n'

9202

n/a

' ... return type.__getattribute__(*args)\n'

9203

n/a

' ...\n'

9204

n/a

' >>> class C(object, metaclass=Meta):\n'

9205

n/a

' ... def __len__(self):\n'

9206

n/a

' ... return 10\n'

9207

n/a

' ... def __getattribute__(*args):\n'

9208

n/a

' ... print("Class getattribute invoked")\n'

9209

n/a

' ... return object.__getattribute__(*args)\n'

9210

n/a

' ...\n'

9211

n/a

' >>> c = C()\n'

9212

n/a

' >>> c.__len__() # Explicit lookup via '

9213

n/a

'instance\n'

9214

n/a

' Class getattribute invoked\n'

9215

n/a

' 10\n'

9216

n/a

' >>> type(c).__len__(c) # Explicit lookup via '

9217

n/a

'type\n'

9218

n/a

' Metaclass getattribute invoked\n'

9219

n/a

' 10\n'

9220

n/a

' >>> len(c) # Implicit lookup\n'

9221

n/a

' 10\n'

9222

n/a

'\n'

9223

n/a

'Bypassing the "__getattribute__()" machinery in this fashion '

9224

n/a

'provides\n'

9225

n/a

'significant scope for speed optimisations within the '

9226

n/a

'interpreter, at\n'

9227

n/a

'the cost of some flexibility in the handling of special '

9228

n/a

'methods (the\n'

9229

n/a

'special method *must* be set on the class object itself in '

9230

n/a

'order to be\n'

9231

n/a

'consistently invoked by the interpreter).\n',

9232

n/a

'string-methods': '\n'

9233

n/a

'String Methods\n'

9234

n/a

'**************\n'

9235

n/a

'\n'

9236

n/a

'Strings implement all of the common sequence operations, '

9237

n/a

'along with\n'

9238

n/a

'the additional methods described below.\n'

9239

n/a

'\n'

9240

n/a

'Strings also support two styles of string formatting, one '

9241

n/a

'providing a\n'

9242

n/a

'large degree of flexibility and customization (see '

9243

n/a

'"str.format()",\n'

9244

n/a

'Format String Syntax and Custom String Formatting) and the '

9245

n/a

'other based\n'

9246

n/a

'on C "printf" style formatting that handles a narrower '

9247

n/a

'range of types\n'

9248

n/a

'and is slightly harder to use correctly, but is often '

9249

n/a

'faster for the\n'

9250

n/a

'cases it can handle (printf-style String Formatting).\n'

9251

n/a

'\n'

9252

n/a

'The Text Processing Services section of the standard '

9253

n/a

'library covers a\n'

9254

n/a

'number of other modules that provide various text related '

9255

n/a

'utilities\n'

9256

n/a

'(including regular expression support in the "re" '

9257

n/a

'module).\n'

9258

n/a

'\n'

9259

n/a

'str.capitalize()\n'

9260

n/a

'\n'

9261

n/a

' Return a copy of the string with its first character '

9262

n/a

'capitalized\n'

9263

n/a

' and the rest lowercased.\n'

9264

n/a

'\n'

9265

n/a

'str.casefold()\n'

9266

n/a

'\n'

9267

n/a

' Return a casefolded copy of the string. Casefolded '

9268

n/a

'strings may be\n'

9269

n/a

' used for caseless matching.\n'

9270

n/a

'\n'

9271

n/a

' Casefolding is similar to lowercasing but more '

9272

n/a

'aggressive because\n'

9273

n/a

' it is intended to remove all case distinctions in a '

9274

n/a

'string. For\n'

9275

n/a

' example, the German lowercase letter "\'ÃŸ\'" is '

9276

n/a

'equivalent to ""ss"".\n'

9277

n/a

' Since it is already lowercase, "lower()" would do '

9278

n/a

'nothing to "\'ÃŸ\'";\n'

9279

n/a

' "casefold()" converts it to ""ss"".\n'

9280

n/a

'\n'

9281

n/a

' The casefolding algorithm is described in section 3.13 '

9282

n/a

'of the\n'

9283

n/a

' Unicode Standard.\n'

9284

n/a

'\n'

9285

n/a

' New in version 3.3.\n'

9286

n/a

'\n'

9287

n/a

'str.center(width[, fillchar])\n'

9288

n/a

'\n'

9289

n/a

' Return centered in a string of length *width*. Padding '

9290

n/a

'is done\n'

9291

n/a

' using the specified *fillchar* (default is an ASCII '

9292

n/a

'space). The\n'

9293

n/a

' original string is returned if *width* is less than or '

9294

n/a

'equal to\n'

9295

n/a

' "len(s)".\n'

9296

n/a

'\n'

9297

n/a

'str.count(sub[, start[, end]])\n'

9298

n/a

'\n'

9299

n/a

' Return the number of non-overlapping occurrences of '

9300

n/a

'substring *sub*\n'

9301

n/a

' in the range [*start*, *end*]. Optional arguments '

9302

n/a

'*start* and\n'

9303

n/a

' *end* are interpreted as in slice notation.\n'

9304

n/a

'\n'

9305

n/a

'str.encode(encoding="utf-8", errors="strict")\n'

9306

n/a

'\n'

9307

n/a

' Return an encoded version of the string as a bytes '

9308

n/a

'object. Default\n'

9309

n/a

' encoding is "\'utf-8\'". *errors* may be given to set a '

9310

n/a

'different\n'

9311

n/a

' error handling scheme. The default for *errors* is '

9312

n/a

'"\'strict\'",\n'

9313

n/a

' meaning that encoding errors raise a "UnicodeError". '

9314

n/a

'Other possible\n'

9315

n/a

' values are "\'ignore\'", "\'replace\'", '

9316

n/a

'"\'xmlcharrefreplace\'",\n'

9317

n/a

' "\'backslashreplace\'" and any other name registered '

9318

n/a

'via\n'

9319

n/a

' "codecs.register_error()", see section Error Handlers. '

9320

n/a

'For a list\n'

9321

n/a

' of possible encodings, see section Standard Encodings.\n'

9322

n/a

'\n'

9323

n/a

' Changed in version 3.1: Support for keyword arguments '

9324

n/a

'added.\n'

9325

n/a

'\n'

9326

n/a

'str.endswith(suffix[, start[, end]])\n'

9327

n/a

'\n'

9328

n/a

' Return "True" if the string ends with the specified '

9329

n/a

'*suffix*,\n'

9330

n/a

' otherwise return "False". *suffix* can also be a tuple '

9331

n/a

'of suffixes\n'

9332

n/a

' to look for. With optional *start*, test beginning at '

9333

n/a

'that\n'

9334

n/a

' position. With optional *end*, stop comparing at that '

9335

n/a

'position.\n'

9336

n/a

'\n'

9337

n/a

'str.expandtabs(tabsize=8)\n'

9338

n/a

'\n'

9339

n/a

' Return a copy of the string where all tab characters '

9340

n/a

'are replaced\n'

9341

n/a

' by one or more spaces, depending on the current column '

9342

n/a

'and the\n'

9343

n/a

' given tab size. Tab positions occur every *tabsize* '

9344

n/a

'characters\n'

9345

n/a

' (default is 8, giving tab positions at columns 0, 8, 16 '

9346

n/a

'and so on).\n'

9347

n/a

' To expand the string, the current column is set to zero '

9348

n/a

'and the\n'

9349

n/a

' string is examined character by character. If the '

9350

n/a

'character is a\n'

9351

n/a

' tab ("\\t"), one or more space characters are inserted '

9352

n/a

'in the result\n'

9353

n/a

' until the current column is equal to the next tab '

9354

n/a

'position. (The\n'

9355

n/a

' tab character itself is not copied.) If the character '

9356

n/a

'is a newline\n'

9357

n/a

' ("\\n") or return ("\\r"), it is copied and the current '

9358

n/a

'column is\n'

9359

n/a

' reset to zero. Any other character is copied unchanged '

9360

n/a

'and the\n'

9361

n/a

' current column is incremented by one regardless of how '

9362

n/a

'the\n'

9363

n/a

' character is represented when printed.\n'

9364

n/a

'\n'

9365

n/a

" >>> '01\\t012\\t0123\\t01234'.expandtabs()\n"

9366

n/a

" '01 012 0123 01234'\n"

9367

n/a

" >>> '01\\t012\\t0123\\t01234'.expandtabs(4)\n"

9368

n/a

" '01 012 0123 01234'\n"

9369

n/a

'\n'

9370

n/a

'str.find(sub[, start[, end]])\n'

9371

n/a

'\n'

9372

n/a

' Return the lowest index in the string where substring '

9373

n/a

'*sub* is\n'

9374

n/a

' found within the slice "s[start:end]". Optional '

9375

n/a

'arguments *start*\n'

9376

n/a

' and *end* are interpreted as in slice notation. Return '

9377

n/a

'"-1" if\n'

9378

n/a

' *sub* is not found.\n'

9379

n/a

'\n'

9380

n/a

' Note: The "find()" method should be used only if you '

9381

n/a

'need to know\n'

9382

n/a

' the position of *sub*. To check if *sub* is a '

9383

n/a

'substring or not,\n'

9384

n/a

' use the "in" operator:\n'

9385

n/a

'\n'

9386

n/a

" >>> 'Py' in 'Python'\n"

9387

n/a

' True\n'

9388

n/a

'\n'

9389

n/a

'str.format(*args, **kwargs)\n'

9390

n/a

'\n'

9391

n/a

' Perform a string formatting operation. The string on '

9392

n/a

'which this\n'

9393

n/a

' method is called can contain literal text or '

9394

n/a

'replacement fields\n'

9395

n/a

' delimited by braces "{}". Each replacement field '

9396

n/a

'contains either\n'

9397

n/a

' the numeric index of a positional argument, or the name '

9398

n/a

'of a\n'

9399

n/a

' keyword argument. Returns a copy of the string where '

9400

n/a

'each\n'

9401

n/a

' replacement field is replaced with the string value of '

9402

n/a

'the\n'

9403

n/a

' corresponding argument.\n'

9404

n/a

'\n'

9405

n/a

' >>> "The sum of 1 + 2 is {0}".format(1+2)\n'

9406

n/a

" 'The sum of 1 + 2 is 3'\n"

9407

n/a

'\n'

9408

n/a

' See Format String Syntax for a description of the '

9409

n/a

'various\n'

9410

n/a

' formatting options that can be specified in format '

9411

n/a

'strings.\n'

9412

n/a

'\n'

9413

n/a

'str.format_map(mapping)\n'

9414

n/a

'\n'

9415

n/a

' Similar to "str.format(**mapping)", except that '

9416

n/a

'"mapping" is used\n'

9417

n/a

' directly and not copied to a "dict". This is useful if '

9418

n/a

'for example\n'

9419

n/a

' "mapping" is a dict subclass:\n'

9420

n/a

'\n'

9421

n/a

' >>> class Default(dict):\n'

9422

n/a

' ... def __missing__(self, key):\n'

9423

n/a

' ... return key\n'

9424

n/a

' ...\n'

9425

n/a

" >>> '{name} was born in "

9426

n/a

"{country}'.format_map(Default(name='Guido'))\n"

9427

n/a

" 'Guido was born in country'\n"

9428

n/a

'\n'

9429

n/a

' New in version 3.2.\n'

9430

n/a

'\n'

9431

n/a

'str.index(sub[, start[, end]])\n'

9432

n/a

'\n'

9433

n/a

' Like "find()", but raise "ValueError" when the '

9434

n/a

'substring is not\n'

9435

n/a

' found.\n'

9436

n/a

'\n'

9437

n/a

'str.isalnum()\n'

9438

n/a

'\n'

9439

n/a

' Return true if all characters in the string are '

9440

n/a

'alphanumeric and\n'

9441

n/a

' there is at least one character, false otherwise. A '

9442

n/a

'character "c"\n'

9443

n/a

' is alphanumeric if one of the following returns '

9444

n/a

'"True":\n'

9445

n/a

' "c.isalpha()", "c.isdecimal()", "c.isdigit()", or '

9446

n/a

'"c.isnumeric()".\n'

9447

n/a

'\n'

9448

n/a

'str.isalpha()\n'

9449

n/a

'\n'

9450

n/a

' Return true if all characters in the string are '

9451

n/a

'alphabetic and\n'

9452

n/a

' there is at least one character, false otherwise. '

9453

n/a

'Alphabetic\n'

9454

n/a

' characters are those characters defined in the Unicode '

9455

n/a

'character\n'

9456

n/a

' database as "Letter", i.e., those with general category '

9457

n/a

'property\n'

9458

n/a

' being one of "Lm", "Lt", "Lu", "Ll", or "Lo". Note '

9459

n/a

'that this is\n'

9460

n/a

' different from the "Alphabetic" property defined in the '

9461

n/a

'Unicode\n'

9462

n/a

' Standard.\n'

9463

n/a

'\n'

9464

n/a

'str.isdecimal()\n'

9465

n/a

'\n'

9466

n/a

' Return true if all characters in the string are decimal '

9467

n/a

'characters\n'

9468

n/a

' and there is at least one character, false otherwise. '

9469

n/a

'Decimal\n'

9470

n/a

' characters are those from general category "Nd". This '

9471

n/a

'category\n'

9472

n/a

' includes digit characters, and all characters that can '

9473

n/a

'be used to\n'

9474

n/a

' form decimal-radix numbers, e.g. U+0660, ARABIC-INDIC '

9475

n/a

'DIGIT ZERO.\n'

9476

n/a

'\n'

9477

n/a

'str.isdigit()\n'

9478

n/a

'\n'

9479

n/a

' Return true if all characters in the string are digits '

9480

n/a

'and there is\n'

9481

n/a

' at least one character, false otherwise. Digits '

9482

n/a

'include decimal\n'

9483

n/a

' characters and digits that need special handling, such '

9484

n/a

'as the\n'

9485

n/a

' compatibility superscript digits. Formally, a digit is '

9486

n/a

'a character\n'

9487

n/a

' that has the property value Numeric_Type=Digit or\n'

9488

n/a

' Numeric_Type=Decimal.\n'

9489

n/a

'\n'

9490

n/a

'str.isidentifier()\n'

9491

n/a

'\n'

9492

n/a

' Return true if the string is a valid identifier '

9493

n/a

'according to the\n'

9494

n/a

' language definition, section Identifiers and keywords.\n'

9495

n/a

'\n'

9496

n/a

' Use "keyword.iskeyword()" to test for reserved '

9497

n/a

'identifiers such as\n'

9498

n/a

' "def" and "class".\n'

9499

n/a

'\n'

9500

n/a

'str.islower()\n'

9501

n/a

'\n'

9502

n/a

' Return true if all cased characters [4] in the string '

9503

n/a

'are lowercase\n'

9504

n/a

' and there is at least one cased character, false '

9505

n/a

'otherwise.\n'

9506

n/a

'\n'

9507

n/a

'str.isnumeric()\n'

9508

n/a

'\n'

9509

n/a

' Return true if all characters in the string are numeric '

9510

n/a

'characters,\n'

9511

n/a

' and there is at least one character, false otherwise. '

9512

n/a

'Numeric\n'

9513

n/a

' characters include digit characters, and all characters '

9514

n/a

'that have\n'

9515

n/a

' the Unicode numeric value property, e.g. U+2155, VULGAR '

9516

n/a

'FRACTION\n'

9517

n/a

' ONE FIFTH. Formally, numeric characters are those with '

9518

n/a

'the\n'

9519

n/a

' property value Numeric_Type=Digit, Numeric_Type=Decimal '

9520

n/a

'or\n'

9521

n/a

' Numeric_Type=Numeric.\n'

9522

n/a

'\n'

9523

n/a

'str.isprintable()\n'

9524

n/a

'\n'

9525

n/a

' Return true if all characters in the string are '

9526

n/a

'printable or the\n'

9527

n/a

' string is empty, false otherwise. Nonprintable '

9528

n/a

'characters are\n'

9529

n/a

' those characters defined in the Unicode character '

9530

n/a

'database as\n'

9531

n/a

' "Other" or "Separator", excepting the ASCII space '

9532

n/a

'(0x20) which is\n'

9533

n/a

' considered printable. (Note that printable characters '

9534

n/a

'in this\n'

9535

n/a

' context are those which should not be escaped when '

9536

n/a

'"repr()" is\n'

9537

n/a

' invoked on a string. It has no bearing on the handling '

9538

n/a

'of strings\n'

9539

n/a

' written to "sys.stdout" or "sys.stderr".)\n'

9540

n/a

'\n'

9541

n/a

'str.isspace()\n'

9542

n/a

'\n'

9543

n/a

' Return true if there are only whitespace characters in '

9544

n/a

'the string\n'

9545

n/a

' and there is at least one character, false otherwise. '

9546

n/a

'Whitespace\n'

9547

n/a

' characters are those characters defined in the Unicode '

9548

n/a

'character\n'

9549

n/a

' database as "Other" or "Separator" and those with '

9550

n/a

'bidirectional\n'

9551

n/a

' property being one of "WS", "B", or "S".\n'

9552

n/a

'\n'

9553

n/a

'str.istitle()\n'

9554

n/a

'\n'

9555

n/a

' Return true if the string is a titlecased string and '

9556

n/a

'there is at\n'

9557

n/a

' least one character, for example uppercase characters '

9558

n/a

'may only\n'

9559

n/a

' follow uncased characters and lowercase characters only '

9560

n/a

'cased ones.\n'

9561

n/a

' Return false otherwise.\n'

9562

n/a

'\n'

9563

n/a

'str.isupper()\n'

9564

n/a

'\n'

9565

n/a

' Return true if all cased characters [4] in the string '

9566

n/a

'are uppercase\n'

9567

n/a

' and there is at least one cased character, false '

9568

n/a

'otherwise.\n'

9569

n/a

'\n'

9570

n/a

'str.join(iterable)\n'

9571

n/a

'\n'

9572

n/a

' Return a string which is the concatenation of the '

9573

n/a

'strings in the\n'

9574

n/a

' *iterable* *iterable*. A "TypeError" will be raised if '

9575

n/a

'there are\n'

9576

n/a

' any non-string values in *iterable*, including "bytes" '

9577

n/a

'objects.\n'

9578

n/a

' The separator between elements is the string providing '

9579

n/a

'this method.\n'

9580

n/a

'\n'

9581

n/a

'str.ljust(width[, fillchar])\n'

9582

n/a

'\n'

9583

n/a

' Return the string left justified in a string of length '

9584

n/a

'*width*.\n'

9585

n/a

' Padding is done using the specified *fillchar* (default '

9586

n/a

'is an ASCII\n'

9587

n/a

' space). The original string is returned if *width* is '

9588

n/a

'less than or\n'

9589

n/a

' equal to "len(s)".\n'

9590

n/a

'\n'

9591

n/a

'str.lower()\n'

9592

n/a

'\n'

9593

n/a

' Return a copy of the string with all the cased '

9594

n/a

'characters [4]\n'

9595

n/a

' converted to lowercase.\n'

9596

n/a

'\n'

9597

n/a

' The lowercasing algorithm used is described in section '

9598

n/a

'3.13 of the\n'

9599

n/a

' Unicode Standard.\n'

9600

n/a

'\n'

9601

n/a

'str.lstrip([chars])\n'

9602

n/a

'\n'

9603

n/a

' Return a copy of the string with leading characters '

9604

n/a

'removed. The\n'

9605

n/a

' *chars* argument is a string specifying the set of '

9606

n/a

'characters to be\n'

9607

n/a

' removed. If omitted or "None", the *chars* argument '

9608

n/a

'defaults to\n'

9609

n/a

' removing whitespace. The *chars* argument is not a '

9610

n/a

'prefix; rather,\n'

9611

n/a

' all combinations of its values are stripped:\n'

9612

n/a

'\n'

9613

n/a

" >>> ' spacious '.lstrip()\n"

9614

n/a

" 'spacious '\n"

9615

n/a

" >>> 'www.example.com'.lstrip('cmowz.')\n"

9616

n/a

" 'example.com'\n"

9617

n/a

'\n'

9618

n/a

'static str.maketrans(x[, y[, z]])\n'

9619

n/a

'\n'

9620

n/a

' This static method returns a translation table usable '

9621

n/a

'for\n'

9622

n/a

' "str.translate()".\n'

9623

n/a

'\n'

9624

n/a

' If there is only one argument, it must be a dictionary '

9625

n/a

'mapping\n'

9626

n/a

' Unicode ordinals (integers) or characters (strings of '

9627

n/a

'length 1) to\n'

9628

n/a

' Unicode ordinals, strings (of arbitrary lengths) or '

9629

n/a

'None.\n'

9630

n/a

' Character keys will then be converted to ordinals.\n'

9631

n/a

'\n'

9632

n/a

' If there are two arguments, they must be strings of '

9633

n/a

'equal length,\n'

9634

n/a

' and in the resulting dictionary, each character in x '

9635

n/a

'will be mapped\n'

9636

n/a

' to the character at the same position in y. If there '

9637

n/a

'is a third\n'

9638

n/a

' argument, it must be a string, whose characters will be '

9639

n/a

'mapped to\n'

9640

n/a

' None in the result.\n'

9641

n/a

'\n'

9642

n/a

'str.partition(sep)\n'

9643

n/a

'\n'

9644

n/a

' Split the string at the first occurrence of *sep*, and '

9645

n/a

'return a\n'

9646

n/a

' 3-tuple containing the part before the separator, the '

9647

n/a

'separator\n'

9648

n/a

' itself, and the part after the separator. If the '

9649

n/a

'separator is not\n'

9650

n/a

' found, return a 3-tuple containing the string itself, '

9651

n/a

'followed by\n'

9652

n/a

' two empty strings.\n'

9653

n/a

'\n'

9654

n/a

'str.replace(old, new[, count])\n'

9655

n/a

'\n'

9656

n/a

' Return a copy of the string with all occurrences of '

9657

n/a

'substring *old*\n'

9658

n/a

' replaced by *new*. If the optional argument *count* is '

9659

n/a

'given, only\n'

9660

n/a

' the first *count* occurrences are replaced.\n'

9661

n/a

'\n'

9662

n/a

'str.rfind(sub[, start[, end]])\n'

9663

n/a

'\n'

9664

n/a

' Return the highest index in the string where substring '

9665

n/a

'*sub* is\n'

9666

n/a

' found, such that *sub* is contained within '

9667

n/a

'"s[start:end]".\n'

9668

n/a

' Optional arguments *start* and *end* are interpreted as '

9669

n/a

'in slice\n'

9670

n/a

' notation. Return "-1" on failure.\n'

9671

n/a

'\n'

9672

n/a

'str.rindex(sub[, start[, end]])\n'

9673

n/a

'\n'

9674

n/a

' Like "rfind()" but raises "ValueError" when the '

9675

n/a

'substring *sub* is\n'

9676

n/a

' not found.\n'

9677

n/a

'\n'

9678

n/a

'str.rjust(width[, fillchar])\n'

9679

n/a

'\n'

9680

n/a

' Return the string right justified in a string of length '

9681

n/a

'*width*.\n'

9682

n/a

' Padding is done using the specified *fillchar* (default '

9683

n/a

'is an ASCII\n'

9684

n/a

' space). The original string is returned if *width* is '

9685

n/a

'less than or\n'

9686

n/a

' equal to "len(s)".\n'

9687

n/a

'\n'

9688

n/a

'str.rpartition(sep)\n'

9689

n/a

'\n'

9690

n/a

' Split the string at the last occurrence of *sep*, and '

9691

n/a

'return a\n'

9692

n/a

' 3-tuple containing the part before the separator, the '

9693

n/a

'separator\n'

9694

n/a

' itself, and the part after the separator. If the '

9695

n/a

'separator is not\n'

9696

n/a

' found, return a 3-tuple containing two empty strings, '

9697

n/a

'followed by\n'

9698

n/a

' the string itself.\n'

9699

n/a

'\n'

9700

n/a

'str.rsplit(sep=None, maxsplit=-1)\n'

9701

n/a

'\n'

9702

n/a

' Return a list of the words in the string, using *sep* '

9703

n/a

'as the\n'

9704

n/a

' delimiter string. If *maxsplit* is given, at most '

9705

n/a

'*maxsplit* splits\n'

9706

n/a

' are done, the *rightmost* ones. If *sep* is not '

9707

n/a

'specified or\n'

9708

n/a

' "None", any whitespace string is a separator. Except '

9709

n/a

'for splitting\n'

9710

n/a

' from the right, "rsplit()" behaves like "split()" which '

9711

n/a

'is\n'

9712

n/a

' described in detail below.\n'

9713

n/a

'\n'

9714

n/a

'str.rstrip([chars])\n'

9715

n/a

'\n'

9716

n/a

' Return a copy of the string with trailing characters '

9717

n/a

'removed. The\n'

9718

n/a

' *chars* argument is a string specifying the set of '

9719

n/a

'characters to be\n'

9720

n/a

' removed. If omitted or "None", the *chars* argument '

9721

n/a

'defaults to\n'

9722

n/a

' removing whitespace. The *chars* argument is not a '

9723

n/a

'suffix; rather,\n'

9724

n/a

' all combinations of its values are stripped:\n'

9725

n/a

'\n'

9726

n/a

" >>> ' spacious '.rstrip()\n"

9727

n/a

" ' spacious'\n"

9728

n/a

" >>> 'mississippi'.rstrip('ipz')\n"

9729

n/a

" 'mississ'\n"

9730

n/a

'\n'

9731

n/a

'str.split(sep=None, maxsplit=-1)\n'

9732

n/a

'\n'

9733

n/a

' Return a list of the words in the string, using *sep* '

9734

n/a

'as the\n'

9735

n/a

' delimiter string. If *maxsplit* is given, at most '

9736

n/a

'*maxsplit*\n'

9737

n/a

' splits are done (thus, the list will have at most '

9738

n/a

'"maxsplit+1"\n'

9739

n/a

' elements). If *maxsplit* is not specified or "-1", '

9740

n/a

'then there is\n'

9741

n/a

' no limit on the number of splits (all possible splits '

9742

n/a

'are made).\n'

9743

n/a

'\n'

9744

n/a

' If *sep* is given, consecutive delimiters are not '

9745

n/a

'grouped together\n'

9746

n/a

' and are deemed to delimit empty strings (for example,\n'

9747

n/a

' "\'1,,2\'.split(\',\')" returns "[\'1\', \'\', '

9748

n/a

'\'2\']"). The *sep* argument\n'

9749

n/a

' may consist of multiple characters (for example,\n'

9750

n/a

' "\'1<>2<>3\'.split(\'<>\')" returns "[\'1\', \'2\', '

9751

n/a

'\'3\']"). Splitting an\n'

9752

n/a

' empty string with a specified separator returns '

9753

n/a

'"[\'\']".\n'

9754

n/a

'\n'

9755

n/a

' For example:\n'

9756

n/a

'\n'

9757

n/a

" >>> '1,2,3'.split(',')\n"

9758

n/a

" ['1', '2', '3']\n"

9759

n/a

" >>> '1,2,3'.split(',', maxsplit=1)\n"

9760

n/a

" ['1', '2,3']\n"

9761

n/a

" >>> '1,2,,3,'.split(',')\n"

9762

n/a

" ['1', '2', '', '3', '']\n"

9763

n/a

'\n'

9764

n/a

' If *sep* is not specified or is "None", a different '

9765

n/a

'splitting\n'

9766

n/a

' algorithm is applied: runs of consecutive whitespace '

9767

n/a

'are regarded\n'

9768

n/a

' as a single separator, and the result will contain no '

9769

n/a

'empty strings\n'

9770

n/a

' at the start or end if the string has leading or '

9771

n/a

'trailing\n'

9772

n/a

' whitespace. Consequently, splitting an empty string or '

9773

n/a

'a string\n'

9774

n/a

' consisting of just whitespace with a "None" separator '

9775

n/a

'returns "[]".\n'

9776

n/a

'\n'

9777

n/a

' For example:\n'

9778

n/a

'\n'

9779

n/a

" >>> '1 2 3'.split()\n"

9780

n/a

" ['1', '2', '3']\n"

9781

n/a

" >>> '1 2 3'.split(maxsplit=1)\n"

9782

n/a

" ['1', '2 3']\n"

9783

n/a

" >>> ' 1 2 3 '.split()\n"

9784

n/a

" ['1', '2', '3']\n"

9785

n/a

'\n'

9786

n/a

'str.splitlines([keepends])\n'

9787

n/a

'\n'

9788

n/a

' Return a list of the lines in the string, breaking at '

9789

n/a

'line\n'

9790

n/a

' boundaries. Line breaks are not included in the '

9791

n/a

'resulting list\n'

9792

n/a

' unless *keepends* is given and true.\n'

9793

n/a

'\n'

9794

n/a

' This method splits on the following line boundaries. '

9795

n/a

'In\n'

9796

n/a

' particular, the boundaries are a superset of *universal '

9797

n/a

'newlines*.\n'

9798

n/a

'\n'

9799

n/a

' '

9800

n/a

'+-------------------------+-------------------------------+\n'

9801

n/a

' | Representation | '

9802

n/a

'Description |\n'

9803

n/a

' '

9804

n/a

'+=========================+===============================+\n'

9805

n/a

' | "\\n" | Line '

9806

n/a

'Feed |\n'

9807

n/a

' '

9808

n/a

'+-------------------------+-------------------------------+\n'

9809

n/a

' | "\\r" | Carriage '

9810

n/a

'Return |\n'

9811

n/a

' '

9812

n/a

'+-------------------------+-------------------------------+\n'

9813

n/a

' | "\\r\\n" | Carriage Return + Line '

9814

n/a

'Feed |\n'

9815

n/a

' '

9816

n/a

'+-------------------------+-------------------------------+\n'

9817

n/a

' | "\\v" or "\\x0b" | Line '

9818

n/a

'Tabulation |\n'

9819

n/a

' '

9820

n/a

'+-------------------------+-------------------------------+\n'

9821

n/a

' | "\\f" or "\\x0c" | Form '

9822

n/a

'Feed |\n'

9823

n/a

' '

9824

n/a

'+-------------------------+-------------------------------+\n'

9825

n/a

' | "\\x1c" | File '

9826

n/a

'Separator |\n'

9827

n/a

' '

9828

n/a

'+-------------------------+-------------------------------+\n'

9829

n/a

' | "\\x1d" | Group '

9830

n/a

'Separator |\n'

9831

n/a

' '

9832

n/a

'+-------------------------+-------------------------------+\n'

9833

n/a

' | "\\x1e" | Record '

9834

n/a

'Separator |\n'

9835

n/a

' '

9836

n/a

'+-------------------------+-------------------------------+\n'

9837

n/a

' | "\\x85" | Next Line (C1 Control '

9838

n/a

'Code) |\n'

9839

n/a

' '

9840

n/a

'+-------------------------+-------------------------------+\n'

9841

n/a

' | "\\u2028" | Line '

9842

n/a

'Separator |\n'

9843

n/a

' '

9844

n/a

'+-------------------------+-------------------------------+\n'

9845

n/a

' | "\\u2029" | Paragraph '

9846

n/a

'Separator |\n'

9847

n/a

' '

9848

n/a

'+-------------------------+-------------------------------+\n'

9849

n/a

'\n'

9850

n/a

' Changed in version 3.2: "\\v" and "\\f" added to list '

9851

n/a

'of line\n'

9852

n/a

' boundaries.\n'

9853

n/a

'\n'

9854

n/a

' For example:\n'

9855

n/a

'\n'

9856

n/a

" >>> 'ab c\\n\\nde fg\\rkl\\r\\n'.splitlines()\n"

9857

n/a

" ['ab c', '', 'de fg', 'kl']\n"

9858

n/a

" >>> 'ab c\\n\\nde "

9859

n/a

"fg\\rkl\\r\\n'.splitlines(keepends=True)\n"

9860

n/a

" ['ab c\\n', '\\n', 'de fg\\r', 'kl\\r\\n']\n"

9861

n/a

'\n'

9862

n/a

' Unlike "split()" when a delimiter string *sep* is '

9863

n/a

'given, this\n'

9864

n/a

' method returns an empty list for the empty string, and '

9865

n/a

'a terminal\n'

9866

n/a

' line break does not result in an extra line:\n'

9867

n/a

'\n'

9868

n/a

' >>> "".splitlines()\n'

9869

n/a

' []\n'

9870

n/a

' >>> "One line\\n".splitlines()\n'

9871

n/a

" ['One line']\n"

9872

n/a

'\n'

9873

n/a

' For comparison, "split(\'\\n\')" gives:\n'

9874

n/a

'\n'

9875

n/a

" >>> ''.split('\\n')\n"

9876

n/a

" ['']\n"

9877

n/a

" >>> 'Two lines\\n'.split('\\n')\n"

9878

n/a

" ['Two lines', '']\n"

9879

n/a

'\n'

9880

n/a

'str.startswith(prefix[, start[, end]])\n'

9881

n/a

'\n'

9882

n/a

' Return "True" if string starts with the *prefix*, '

9883

n/a

'otherwise return\n'

9884

n/a

' "False". *prefix* can also be a tuple of prefixes to '

9885

n/a

'look for.\n'

9886

n/a

' With optional *start*, test string beginning at that '

9887

n/a

'position.\n'

9888

n/a

' With optional *end*, stop comparing string at that '

9889

n/a

'position.\n'

9890

n/a

'\n'

9891

n/a

'str.strip([chars])\n'

9892

n/a

'\n'

9893

n/a

' Return a copy of the string with the leading and '

9894

n/a

'trailing\n'

9895

n/a

' characters removed. The *chars* argument is a string '

9896

n/a

'specifying the\n'

9897

n/a

' set of characters to be removed. If omitted or "None", '

9898

n/a

'the *chars*\n'

9899

n/a

' argument defaults to removing whitespace. The *chars* '

9900

n/a

'argument is\n'

9901

n/a

' not a prefix or suffix; rather, all combinations of its '

9902

n/a

'values are\n'

9903

n/a

' stripped:\n'

9904

n/a

'\n'

9905

n/a

" >>> ' spacious '.strip()\n"

9906

n/a

" 'spacious'\n"

9907

n/a

" >>> 'www.example.com'.strip('cmowz.')\n"

9908

n/a

" 'example'\n"

9909

n/a

'\n'

9910

n/a

' The outermost leading and trailing *chars* argument '

9911

n/a

'values are\n'

9912

n/a

' stripped from the string. Characters are removed from '

9913

n/a

'the leading\n'

9914

n/a

' end until reaching a string character that is not '

9915

n/a

'contained in the\n'

9916

n/a

' set of characters in *chars*. A similar action takes '

9917

n/a

'place on the\n'

9918

n/a

' trailing end. For example:\n'

9919

n/a

'\n'

9920

n/a

" >>> comment_string = '#....... Section 3.2.1 Issue "

9921

n/a

"#32 .......'\n"

9922

n/a

" >>> comment_string.strip('.#! ')\n"

9923

n/a

" 'Section 3.2.1 Issue #32'\n"

9924

n/a

'\n'

9925

n/a

'str.swapcase()\n'

9926

n/a

'\n'

9927

n/a

' Return a copy of the string with uppercase characters '

9928

n/a

'converted to\n'

9929

n/a

' lowercase and vice versa. Note that it is not '

9930

n/a

'necessarily true that\n'

9931

n/a

' "s.swapcase().swapcase() == s".\n'

9932

n/a

'\n'

9933

n/a

'str.title()\n'

9934

n/a

'\n'

9935

n/a

' Return a titlecased version of the string where words '

9936

n/a

'start with an\n'

9937

n/a

' uppercase character and the remaining characters are '

9938

n/a

'lowercase.\n'

9939

n/a

'\n'

9940

n/a

' For example:\n'

9941

n/a

'\n'

9942

n/a

" >>> 'Hello world'.title()\n"

9943

n/a

" 'Hello World'\n"

9944

n/a

'\n'

9945

n/a

' The algorithm uses a simple language-independent '

9946

n/a

'definition of a\n'

9947

n/a

' word as groups of consecutive letters. The definition '

9948

n/a

'works in\n'

9949

n/a

' many contexts but it means that apostrophes in '

9950

n/a

'contractions and\n'

9951

n/a

' possessives form word boundaries, which may not be the '

9952

n/a

'desired\n'

9953

n/a

' result:\n'

9954

n/a

'\n'

9955

n/a

' >>> "they\'re bill\'s friends from the UK".title()\n'

9956

n/a

' "They\'Re Bill\'S Friends From The Uk"\n'

9957

n/a

'\n'

9958

n/a

' A workaround for apostrophes can be constructed using '

9959

n/a

'regular\n'

9960

n/a

' expressions:\n'

9961

n/a

'\n'

9962

n/a

' >>> import re\n'

9963

n/a

' >>> def titlecase(s):\n'

9964

n/a

' ... return re.sub(r"[A-Za-z]+(\'[A-Za-z]+)?",\n'

9965

n/a

' ... lambda mo: '

9966

n/a

'mo.group(0)[0].upper() +\n'

9967

n/a

' ... '

9968

n/a

'mo.group(0)[1:].lower(),\n'

9969

n/a

' ... s)\n'

9970

n/a

' ...\n'

9971

n/a

' >>> titlecase("they\'re bill\'s friends.")\n'

9972

n/a

' "They\'re Bill\'s Friends."\n'

9973

n/a

'\n'

9974

n/a

'str.translate(table)\n'

9975

n/a

'\n'

9976

n/a

' Return a copy of the string in which each character has '

9977

n/a

'been mapped\n'

9978

n/a

' through the given translation table. The table must be '

9979

n/a

'an object\n'

9980

n/a

' that implements indexing via "__getitem__()", typically '

9981

n/a

'a *mapping*\n'

9982

n/a

' or *sequence*. When indexed by a Unicode ordinal (an '

9983

n/a

'integer), the\n'

9984

n/a

' table object can do any of the following: return a '

9985

n/a

'Unicode ordinal\n'

9986

n/a

' or a string, to map the character to one or more other '

9987

n/a

'characters;\n'

9988

n/a

' return "None", to delete the character from the return '

9989

n/a

'string; or\n'

9990

n/a

' raise a "LookupError" exception, to map the character '

9991

n/a

'to itself.\n'

9992

n/a

'\n'

9993

n/a

' You can use "str.maketrans()" to create a translation '

9994

n/a

'map from\n'

9995

n/a

' character-to-character mappings in different formats.\n'

9996

n/a

'\n'

9997

n/a

' See also the "codecs" module for a more flexible '

9998

n/a

'approach to custom\n'

9999

n/a

' character mappings.\n'

10000

n/a

'\n'

10001

n/a

'str.upper()\n'

10002

n/a

'\n'

10003

n/a

' Return a copy of the string with all the cased '

10004

n/a

'characters [4]\n'

10005

n/a

' converted to uppercase. Note that '

10006

n/a

'"str.upper().isupper()" might be\n'

10007

n/a

' "False" if "s" contains uncased characters or if the '

10008

n/a

'Unicode\n'

10009

n/a

' category of the resulting character(s) is not "Lu" '

10010

n/a

'(Letter,\n'

10011

n/a

' uppercase), but e.g. "Lt" (Letter, titlecase).\n'

10012

n/a

'\n'

10013

n/a

' The uppercasing algorithm used is described in section '

10014

n/a

'3.13 of the\n'

10015

n/a

' Unicode Standard.\n'

10016

n/a

'\n'

10017

n/a

'str.zfill(width)\n'

10018

n/a

'\n'

10019

n/a

' Return a copy of the string left filled with ASCII '

10020

n/a

'"\'0\'" digits to\n'

10021

n/a

' make a string of length *width*. A leading sign prefix\n'

10022

n/a

' ("\'+\'"/"\'-\'") is handled by inserting the padding '

10023

n/a

'*after* the sign\n'

10024

n/a

' character rather than before. The original string is '

10025

n/a

'returned if\n'

10026

n/a

' *width* is less than or equal to "len(s)".\n'

10027

n/a

'\n'

10028

n/a

' For example:\n'

10029

n/a

'\n'

10030

n/a

' >>> "42".zfill(5)\n'

10031

n/a

" '00042'\n"

10032

n/a

' >>> "-42".zfill(5)\n'

10033

n/a

" '-0042'\n",

10034

n/a

'strings': '\n'

10035

n/a

'String and Bytes literals\n'

10036

n/a

'*************************\n'

10037

n/a

'\n'

10038

n/a

'String literals are described by the following lexical '

10039

n/a

'definitions:\n'

10040

n/a

'\n'

10041

n/a

' stringliteral ::= [stringprefix](shortstring | longstring)\n'

10042

n/a

' stringprefix ::= "r" | "u" | "R" | "U" | "f" | "F"\n'

10043

n/a

' | "fr" | "Fr" | "fR" | "FR" | "rf" | "rF" | '

10044

n/a

'"Rf" | "RF"\n'

10045

n/a

' shortstring ::= "\'" shortstringitem* "\'" | \'"\' '

10046

n/a

'shortstringitem* \'"\'\n'

10047

n/a

' longstring ::= "\'\'\'" longstringitem* "\'\'\'" | '

10048

n/a

'\'"""\' longstringitem* \'"""\'\n'

10049

n/a

' shortstringitem ::= shortstringchar | stringescapeseq\n'

10050

n/a

' longstringitem ::= longstringchar | stringescapeseq\n'

10051

n/a

' shortstringchar ::= <any source character except "\\" or '

10052

n/a

'newline or the quote>\n'

10053

n/a

' longstringchar ::= <any source character except "\\">\n'

10054

n/a

' stringescapeseq ::= "\\" <any source character>\n'

10055

n/a

'\n'

10056

n/a

' bytesliteral ::= bytesprefix(shortbytes | longbytes)\n'

10057

n/a

' bytesprefix ::= "b" | "B" | "br" | "Br" | "bR" | "BR" | '

10058

n/a

'"rb" | "rB" | "Rb" | "RB"\n'

10059

n/a

' shortbytes ::= "\'" shortbytesitem* "\'" | \'"\' '

10060

n/a

'shortbytesitem* \'"\'\n'

10061

n/a

' longbytes ::= "\'\'\'" longbytesitem* "\'\'\'" | \'"""\' '

10062

n/a

'longbytesitem* \'"""\'\n'

10063

n/a

' shortbytesitem ::= shortbyteschar | bytesescapeseq\n'

10064

n/a

' longbytesitem ::= longbyteschar | bytesescapeseq\n'

10065

n/a

' shortbyteschar ::= <any ASCII character except "\\" or newline '

10066

n/a

'or the quote>\n'

10067

n/a

' longbyteschar ::= <any ASCII character except "\\">\n'

10068

n/a

' bytesescapeseq ::= "\\" <any ASCII character>\n'

10069

n/a

'\n'

10070

n/a

'One syntactic restriction not indicated by these productions is '

10071

n/a

'that\n'

10072

n/a

'whitespace is not allowed between the "stringprefix" or '

10073

n/a

'"bytesprefix"\n'

10074

n/a

'and the rest of the literal. The source character set is defined '

10075

n/a

'by\n'

10076

n/a

'the encoding declaration; it is UTF-8 if no encoding declaration '

10077

n/a

'is\n'

10078

n/a

'given in the source file; see section Encoding declarations.\n'

10079

n/a

'\n'

10080

n/a

'In plain English: Both types of literals can be enclosed in '

10081

n/a

'matching\n'

10082

n/a

'single quotes ("\'") or double quotes ("""). They can also be '

10083

n/a

'enclosed\n'

10084

n/a

'in matching groups of three single or double quotes (these are\n'

10085

n/a

'generally referred to as *triple-quoted strings*). The '

10086

n/a

'backslash\n'

10087

n/a

'("\\") character is used to escape characters that otherwise have '

10088

n/a

'a\n'

10089

n/a

'special meaning, such as newline, backslash itself, or the quote\n'

10090

n/a

'character.\n'

10091

n/a

'\n'

10092

n/a

'Bytes literals are always prefixed with "\'b\'" or "\'B\'"; they '

10093

n/a

'produce\n'

10094

n/a

'an instance of the "bytes" type instead of the "str" type. They '

10095

n/a

'may\n'

10096

n/a

'only contain ASCII characters; bytes with a numeric value of 128 '

10097

n/a

'or\n'

10098

n/a

'greater must be expressed with escapes.\n'

10099

n/a

'\n'

10100

n/a

'As of Python 3.3 it is possible again to prefix string literals '

10101

n/a

'with a\n'

10102

n/a

'"u" prefix to simplify maintenance of dual 2.x and 3.x '

10103

n/a

'codebases.\n'

10104

n/a

'\n'

10105

n/a

'Both string and bytes literals may optionally be prefixed with a\n'

10106

n/a

'letter "\'r\'" or "\'R\'"; such strings are called *raw strings* '

10107

n/a

'and treat\n'

10108

n/a

'backslashes as literal characters. As a result, in string '

10109

n/a

'literals,\n'

10110

n/a

'"\'\\U\'" and "\'\\u\'" escapes in raw strings are not treated '

10111

n/a

'specially.\n'

10112

n/a

"Given that Python 2.x's raw unicode literals behave differently "

10113

n/a

'than\n'

10114

n/a

'Python 3.x\'s the "\'ur\'" syntax is not supported.\n'

10115

n/a

'\n'

10116

n/a

'New in version 3.3: The "\'rb\'" prefix of raw bytes literals has '

10117

n/a

'been\n'

10118

n/a

'added as a synonym of "\'br\'".\n'

10119

n/a

'\n'

10120

n/a

'New in version 3.3: Support for the unicode legacy literal\n'

10121

n/a

'("u\'value\'") was reintroduced to simplify the maintenance of '

10122

n/a

'dual\n'

10123

n/a

'Python 2.x and 3.x codebases. See **PEP 414** for more '

10124

n/a

'information.\n'

10125

n/a

'\n'

10126

n/a

'A string literal with "\'f\'" or "\'F\'" in its prefix is a '

10127

n/a

'*formatted\n'

10128

n/a

'string literal*; see Formatted string literals. The "\'f\'" may '

10129

n/a

'be\n'

10130

n/a

'combined with "\'r\'", but not with "\'b\'" or "\'u\'", therefore '

10131

n/a

'raw\n'

10132

n/a

'formatted strings are possible, but formatted bytes literals are '

10133

n/a

'not.\n'

10134

n/a

'\n'

10135

n/a

'In triple-quoted literals, unescaped newlines and quotes are '

10136

n/a

'allowed\n'

10137

n/a

'(and are retained), except that three unescaped quotes in a row\n'

10138

n/a

'terminate the literal. (A "quote" is the character used to open '

10139

n/a

'the\n'

10140

n/a

'literal, i.e. either "\'" or """.)\n'

10141

n/a

'\n'

10142

n/a

'Unless an "\'r\'" or "\'R\'" prefix is present, escape sequences '

10143

n/a

'in string\n'

10144

n/a

'and bytes literals are interpreted according to rules similar to '

10145

n/a

'those\n'

10146

n/a

'used by Standard C. The recognized escape sequences are:\n'

10147

n/a

'\n'

10148

n/a

'+-------------------+-----------------------------------+---------+\n'

10149

n/a

'| Escape Sequence | Meaning | Notes '

10150

n/a

'|\n'

10151

n/a

'+===================+===================================+=========+\n'

10152

n/a

'| "\\newline" | Backslash and newline ignored '

10153

n/a

'| |\n'

10154

n/a

'+-------------------+-----------------------------------+---------+\n'

10155

n/a

'| "\\\\" | Backslash ("\\") '

10156

n/a

'| |\n'

10157

n/a

'+-------------------+-----------------------------------+---------+\n'

10158

n/a

'| "\\\'" | Single quote ("\'") '

10159

n/a

'| |\n'

10160

n/a

'+-------------------+-----------------------------------+---------+\n'

10161

n/a

'| "\\"" | Double quote (""") '

10162

n/a

'| |\n'

10163

n/a

'+-------------------+-----------------------------------+---------+\n'

10164

n/a

'| "\\a" | ASCII Bell (BEL) '

10165

n/a

'| |\n'

10166

n/a

'+-------------------+-----------------------------------+---------+\n'

10167

n/a

'| "\\b" | ASCII Backspace (BS) '

10168

n/a

'| |\n'

10169

n/a

'+-------------------+-----------------------------------+---------+\n'

10170

n/a

'| "\\f" | ASCII Formfeed (FF) '

10171

n/a

'| |\n'

10172

n/a

'+-------------------+-----------------------------------+---------+\n'

10173

n/a

'| "\\n" | ASCII Linefeed (LF) '

10174

n/a

'| |\n'

10175

n/a

'+-------------------+-----------------------------------+---------+\n'

10176

n/a

'| "\\r" | ASCII Carriage Return (CR) '

10177

n/a

'| |\n'

10178

n/a

'+-------------------+-----------------------------------+---------+\n'

10179

n/a

'| "\\t" | ASCII Horizontal Tab (TAB) '

10180

n/a

'| |\n'

10181

n/a

'+-------------------+-----------------------------------+---------+\n'

10182

n/a

'| "\\v" | ASCII Vertical Tab (VT) '

10183

n/a

'| |\n'

10184

n/a

'+-------------------+-----------------------------------+---------+\n'

10185

n/a

'| "\\ooo" | Character with octal value *ooo* | '

10186

n/a

'(1,3) |\n'

10187

n/a

'+-------------------+-----------------------------------+---------+\n'

10188

n/a

'| "\\xhh" | Character with hex value *hh* | '

10189

n/a

'(2,3) |\n'

10190

n/a

'+-------------------+-----------------------------------+---------+\n'

10191

n/a

'\n'

10192

n/a

'Escape sequences only recognized in string literals are:\n'

10193

n/a

'\n'

10194

n/a

'+-------------------+-----------------------------------+---------+\n'

10195

n/a

'| Escape Sequence | Meaning | Notes '

10196

n/a

'|\n'

10197

n/a

'+===================+===================================+=========+\n'

10198

n/a

'| "\\N{name}" | Character named *name* in the | '

10199

n/a

'(4) |\n'

10200

n/a

'| | Unicode database | '

10201

n/a

'|\n'

10202

n/a

'+-------------------+-----------------------------------+---------+\n'

10203

n/a

'| "\\uxxxx" | Character with 16-bit hex value | '

10204

n/a

'(5) |\n'

10205

n/a

'| | *xxxx* | '

10206

n/a

'|\n'

10207

n/a

'+-------------------+-----------------------------------+---------+\n'

10208

n/a

'| "\\Uxxxxxxxx" | Character with 32-bit hex value | '

10209

n/a

'(6) |\n'

10210

n/a

'| | *xxxxxxxx* | '

10211

n/a

'|\n'

10212

n/a

'+-------------------+-----------------------------------+---------+\n'

10213

n/a

'\n'

10214

n/a

'Notes:\n'

10215

n/a

'\n'

10216

n/a

'1. As in Standard C, up to three octal digits are accepted.\n'

10217

n/a

'\n'

10218

n/a

'2. Unlike in Standard C, exactly two hex digits are required.\n'

10219

n/a

'\n'

10220

n/a

'3. In a bytes literal, hexadecimal and octal escapes denote the\n'

10221

n/a

' byte with the given value. In a string literal, these escapes\n'

10222

n/a

' denote a Unicode character with the given value.\n'

10223

n/a

'\n'

10224

n/a

'4. Changed in version 3.3: Support for name aliases [1] has been\n'

10225

n/a

' added.\n'

10226

n/a

'\n'

10227

n/a

'5. Exactly four hex digits are required.\n'

10228

n/a

'\n'

10229

n/a

'6. Any Unicode character can be encoded this way. Exactly eight\n'

10230

n/a

' hex digits are required.\n'

10231

n/a

'\n'

10232

n/a

'Unlike Standard C, all unrecognized escape sequences are left in '

10233

n/a

'the\n'

10234

n/a

'string unchanged, i.e., *the backslash is left in the result*. '

10235

n/a

'(This\n'

10236

n/a

'behavior is useful when debugging: if an escape sequence is '

10237

n/a

'mistyped,\n'

10238

n/a

'the resulting output is more easily recognized as broken.) It is '

10239

n/a

'also\n'

10240

n/a

'important to note that the escape sequences only recognized in '

10241

n/a

'string\n'

10242

n/a

'literals fall into the category of unrecognized escapes for '

10243

n/a

'bytes\n'

10244

n/a

'literals.\n'

10245

n/a

'\n'

10246

n/a

' Changed in version 3.6: Unrecognized escape sequences produce '

10247

n/a

'a\n'

10248

n/a

' DeprecationWarning. In some future version of Python they '

10249

n/a

'will be\n'

10250

n/a

' a SyntaxError.\n'

10251

n/a

'\n'

10252

n/a

'Even in a raw literal, quotes can be escaped with a backslash, '

10253

n/a

'but the\n'

10254

n/a

'backslash remains in the result; for example, "r"\\""" is a '

10255

n/a

'valid\n'

10256

n/a

'string literal consisting of two characters: a backslash and a '

10257

n/a

'double\n'

10258

n/a

'quote; "r"\\"" is not a valid string literal (even a raw string '

10259

n/a

'cannot\n'

10260

n/a

'end in an odd number of backslashes). Specifically, *a raw '

10261

n/a

'literal\n'

10262

n/a

'cannot end in a single backslash* (since the backslash would '

10263

n/a

'escape\n'

10264

n/a

'the following quote character). Note also that a single '

10265

n/a

'backslash\n'

10266

n/a

'followed by a newline is interpreted as those two characters as '

10267

n/a

'part\n'

10268

n/a

'of the literal, *not* as a line continuation.\n',

10269

n/a

'subscriptions': '\n'

10270

n/a

'Subscriptions\n'

10271

n/a

'*************\n'

10272

n/a

'\n'

10273

n/a

'A subscription selects an item of a sequence (string, tuple '

10274

n/a

'or list)\n'

10275

n/a

'or mapping (dictionary) object:\n'

10276

n/a

'\n'

10277

n/a

' subscription ::= primary "[" expression_list "]"\n'

10278

n/a

'\n'

10279

n/a

'The primary must evaluate to an object that supports '

10280

n/a

'subscription\n'

10281

n/a

'(lists or dictionaries for example). User-defined objects '

10282

n/a

'can support\n'

10283

n/a

'subscription by defining a "__getitem__()" method.\n'

10284

n/a

'\n'

10285

n/a

'For built-in objects, there are two types of objects that '

10286

n/a

'support\n'

10287

n/a

'subscription:\n'

10288

n/a

'\n'

10289

n/a

'If the primary is a mapping, the expression list must '

10290

n/a

'evaluate to an\n'

10291

n/a

'object whose value is one of the keys of the mapping, and '

10292

n/a

'the\n'

10293

n/a

'subscription selects the value in the mapping that '

10294

n/a

'corresponds to that\n'

10295

n/a

'key. (The expression list is a tuple except if it has '

10296

n/a

'exactly one\n'

10297

n/a

'item.)\n'

10298

n/a

'\n'

10299

n/a

'If the primary is a sequence, the expression (list) must '

10300

n/a

'evaluate to\n'

10301

n/a

'an integer or a slice (as discussed in the following '

10302

n/a

'section).\n'

10303

n/a

'\n'

10304

n/a

'The formal syntax makes no special provision for negative '

10305

n/a

'indices in\n'

10306

n/a

'sequences; however, built-in sequences all provide a '

10307

n/a

'"__getitem__()"\n'

10308

n/a

'method that interprets negative indices by adding the '

10309

n/a

'length of the\n'

10310

n/a

'sequence to the index (so that "x[-1]" selects the last '

10311

n/a

'item of "x").\n'

10312

n/a

'The resulting value must be a nonnegative integer less than '

10313

n/a

'the number\n'

10314

n/a

'of items in the sequence, and the subscription selects the '

10315

n/a

'item whose\n'

10316

n/a

'index is that value (counting from zero). Since the support '

10317

n/a

'for\n'

10318

n/a

"negative indices and slicing occurs in the object's "

10319

n/a

'"__getitem__()"\n'

10320

n/a

'method, subclasses overriding this method will need to '

10321

n/a

'explicitly add\n'

10322

n/a

'that support.\n'

10323

n/a

'\n'

10324

n/a

"A string's items are characters. A character is not a "

10325

n/a

'separate data\n'

10326

n/a

'type but a string of exactly one character.\n',

10327

n/a

'truth': '\n'

10328

n/a

'Truth Value Testing\n'

10329

n/a

'*******************\n'

10330

n/a

'\n'

10331

n/a

'Any object can be tested for truth value, for use in an "if" or\n'

10332

n/a

'"while" condition or as operand of the Boolean operations below. '

10333

n/a

'The\n'

10334

n/a

'following values are considered false:\n'

10335

n/a

'\n'

10336

n/a

'* "None"\n'

10337

n/a

'\n'

10338

n/a

'* "False"\n'

10339

n/a

'\n'

10340

n/a

'* zero of any numeric type, for example, "0", "0.0", "0j".\n'

10341

n/a

'\n'

10342

n/a

'* any empty sequence, for example, "\'\'", "()", "[]".\n'

10343

n/a

'\n'

10344

n/a

'* any empty mapping, for example, "{}".\n'

10345

n/a

'\n'

10346

n/a

'* instances of user-defined classes, if the class defines a\n'

10347

n/a

' "__bool__()" or "__len__()" method, when that method returns the\n'

10348

n/a

' integer zero or "bool" value "False". [1]\n'

10349

n/a

'\n'

10350

n/a

'All other values are considered true --- so objects of many types '

10351

n/a

'are\n'

10352

n/a

'always true.\n'

10353

n/a

'\n'

10354

n/a

'Operations and built-in functions that have a Boolean result '

10355

n/a

'always\n'

10356

n/a

'return "0" or "False" for false and "1" or "True" for true, unless\n'

10357

n/a

'otherwise stated. (Important exception: the Boolean operations '

10358

n/a

'"or"\n'

10359

n/a

'and "and" always return one of their operands.)\n',

10360

n/a

'try': '\n'

10361

n/a

'The "try" statement\n'

10362

n/a

'*******************\n'

10363

n/a

'\n'

10364

n/a

'The "try" statement specifies exception handlers and/or cleanup code\n'

10365

n/a

'for a group of statements:\n'

10366

n/a

'\n'

10367

n/a

' try_stmt ::= try1_stmt | try2_stmt\n'

10368

n/a

' try1_stmt ::= "try" ":" suite\n'

10369

n/a

' ("except" [expression ["as" identifier]] ":" '

10370

n/a

'suite)+\n'

10371

n/a

' ["else" ":" suite]\n'

10372

n/a

' ["finally" ":" suite]\n'

10373

n/a

' try2_stmt ::= "try" ":" suite\n'

10374

n/a

' "finally" ":" suite\n'

10375

n/a

'\n'

10376

n/a

'The "except" clause(s) specify one or more exception handlers. When '

10377

n/a

'no\n'

10378

n/a

'exception occurs in the "try" clause, no exception handler is\n'

10379

n/a

'executed. When an exception occurs in the "try" suite, a search for '

10380

n/a

'an\n'

10381

n/a

'exception handler is started. This search inspects the except '

10382

n/a

'clauses\n'

10383

n/a

'in turn until one is found that matches the exception. An '

10384

n/a

'expression-\n'

10385

n/a

'less except clause, if present, must be last; it matches any\n'

10386

n/a

'exception. For an except clause with an expression, that expression\n'

10387

n/a

'is evaluated, and the clause matches the exception if the resulting\n'

10388

n/a

'object is "compatible" with the exception. An object is compatible\n'

10389

n/a

'with an exception if it is the class or a base class of the '

10390

n/a

'exception\n'

10391

n/a

'object or a tuple containing an item compatible with the exception.\n'

10392

n/a

'\n'

10393

n/a

'If no except clause matches the exception, the search for an '

10394

n/a

'exception\n'

10395

n/a

'handler continues in the surrounding code and on the invocation '

10396

n/a

'stack.\n'

10397

n/a

'[1]\n'

10398

n/a

'\n'

10399

n/a

'If the evaluation of an expression in the header of an except clause\n'

10400

n/a

'raises an exception, the original search for a handler is canceled '

10401

n/a

'and\n'

10402

n/a

'a search starts for the new exception in the surrounding code and on\n'

10403

n/a

'the call stack (it is treated as if the entire "try" statement '

10404

n/a

'raised\n'

10405

n/a

'the exception).\n'

10406

n/a

'\n'

10407

n/a

'When a matching except clause is found, the exception is assigned to\n'

10408

n/a

'the target specified after the "as" keyword in that except clause, '

10409

n/a

'if\n'

10410

n/a

"present, and the except clause's suite is executed. All except\n"

10411

n/a

'clauses must have an executable block. When the end of this block '

10412

n/a

'is\n'

10413

n/a

'reached, execution continues normally after the entire try '

10414

n/a

'statement.\n'

10415

n/a

'(This means that if two nested handlers exist for the same '

10416

n/a

'exception,\n'

10417

n/a

'and the exception occurs in the try clause of the inner handler, the\n'

10418

n/a

'outer handler will not handle the exception.)\n'

10419

n/a

'\n'

10420

n/a

'When an exception has been assigned using "as target", it is cleared\n'

10421

n/a

'at the end of the except clause. This is as if\n'

10422

n/a

'\n'

10423

n/a

' except E as N:\n'

10424

n/a

' foo\n'

10425

n/a

'\n'

10426

n/a

'was translated to\n'

10427

n/a

'\n'

10428

n/a

' except E as N:\n'

10429

n/a

' try:\n'

10430

n/a

' foo\n'

10431

n/a

' finally:\n'

10432

n/a

' del N\n'

10433

n/a

'\n'

10434

n/a

'This means the exception must be assigned to a different name to be\n'

10435

n/a

'able to refer to it after the except clause. Exceptions are cleared\n'

10436

n/a

'because with the traceback attached to them, they form a reference\n'

10437

n/a

'cycle with the stack frame, keeping all locals in that frame alive\n'

10438

n/a

'until the next garbage collection occurs.\n'

10439

n/a

'\n'

10440

n/a

"Before an except clause's suite is executed, details about the\n"

10441

n/a

'exception are stored in the "sys" module and can be accessed via\n'

10442

n/a

'"sys.exc_info()". "sys.exc_info()" returns a 3-tuple consisting of '

10443

n/a

'the\n'

10444

n/a

'exception class, the exception instance and a traceback object (see\n'

10445

n/a

'section The standard type hierarchy) identifying the point in the\n'

10446

n/a

'program where the exception occurred. "sys.exc_info()" values are\n'

10447

n/a

'restored to their previous values (before the call) when returning\n'

10448

n/a

'from a function that handled an exception.\n'

10449

n/a

'\n'

10450

n/a

'The optional "else" clause is executed if and when control flows off\n'

10451

n/a

'the end of the "try" clause. [2] Exceptions in the "else" clause are\n'

10452

n/a

'not handled by the preceding "except" clauses.\n'

10453

n/a

'\n'

10454

n/a

'If "finally" is present, it specifies a \'cleanup\' handler. The '

10455

n/a

'"try"\n'

10456

n/a

'clause is executed, including any "except" and "else" clauses. If '

10457

n/a

'an\n'

10458

n/a

'exception occurs in any of the clauses and is not handled, the\n'

10459

n/a

'exception is temporarily saved. The "finally" clause is executed. '

10460

n/a

'If\n'

10461

n/a

'there is a saved exception it is re-raised at the end of the '

10462

n/a

'"finally"\n'

10463

n/a

'clause. If the "finally" clause raises another exception, the saved\n'

10464

n/a

'exception is set as the context of the new exception. If the '

10465

n/a

'"finally"\n'

10466

n/a

'clause executes a "return" or "break" statement, the saved exception\n'

10467

n/a

'is discarded:\n'

10468

n/a

'\n'

10469

n/a

' >>> def f():\n'

10470

n/a

' ... try:\n'

10471

n/a

' ... 1/0\n'

10472

n/a

' ... finally:\n'

10473

n/a

' ... return 42\n'

10474

n/a

' ...\n'

10475

n/a

' >>> f()\n'

10476

n/a

' 42\n'

10477

n/a

'\n'

10478

n/a

'The exception information is not available to the program during\n'

10479

n/a

'execution of the "finally" clause.\n'

10480

n/a

'\n'

10481

n/a

'When a "return", "break" or "continue" statement is executed in the\n'

10482

n/a

'"try" suite of a "try"..."finally" statement, the "finally" clause '

10483

n/a

'is\n'

10484

n/a

'also executed \'on the way out.\' A "continue" statement is illegal '

10485

n/a

'in\n'

10486

n/a

'the "finally" clause. (The reason is a problem with the current\n'

10487

n/a

'implementation --- this restriction may be lifted in the future).\n'

10488

n/a

'\n'

10489

n/a

'The return value of a function is determined by the last "return"\n'

10490

n/a

'statement executed. Since the "finally" clause always executes, a\n'

10491

n/a

'"return" statement executed in the "finally" clause will always be '

10492

n/a

'the\n'

10493

n/a

'last one executed:\n'

10494

n/a

'\n'

10495

n/a

' >>> def foo():\n'

10496

n/a

' ... try:\n'

10497

n/a

" ... return 'try'\n"

10498

n/a

' ... finally:\n'

10499

n/a

" ... return 'finally'\n"

10500

n/a

' ...\n'

10501

n/a

' >>> foo()\n'

10502

n/a

" 'finally'\n"

10503

n/a

'\n'

10504

n/a

'Additional information on exceptions can be found in section\n'

10505

n/a

'Exceptions, and information on using the "raise" statement to '

10506

n/a

'generate\n'

10507

n/a

'exceptions may be found in section The raise statement.\n',

10508

n/a

'types': '\n'

10509

n/a

'The standard type hierarchy\n'

10510

n/a

'***************************\n'

10511

n/a

'\n'

10512

n/a

'Below is a list of the types that are built into Python. '

10513

n/a

'Extension\n'

10514

n/a

'modules (written in C, Java, or other languages, depending on the\n'

10515

n/a

'implementation) can define additional types. Future versions of\n'

10516

n/a

'Python may add types to the type hierarchy (e.g., rational '

10517

n/a

'numbers,\n'

10518

n/a

'efficiently stored arrays of integers, etc.), although such '

10519

n/a

'additions\n'

10520

n/a

'will often be provided via the standard library instead.\n'

10521

n/a

'\n'

10522

n/a

'Some of the type descriptions below contain a paragraph listing\n'

10523

n/a

"'special attributes.' These are attributes that provide access to "

10524

n/a

'the\n'

10525

n/a

'implementation and are not intended for general use. Their '

10526

n/a

'definition\n'

10527

n/a

'may change in the future.\n'

10528

n/a

'\n'

10529

n/a

'None\n'

10530

n/a

' This type has a single value. There is a single object with '

10531

n/a

'this\n'

10532

n/a

' value. This object is accessed through the built-in name "None". '

10533

n/a

'It\n'

10534

n/a

' is used to signify the absence of a value in many situations, '

10535

n/a

'e.g.,\n'

10536

n/a

" it is returned from functions that don't explicitly return\n"

10537

n/a

' anything. Its truth value is false.\n'

10538

n/a

'\n'

10539

n/a

'NotImplemented\n'

10540

n/a

' This type has a single value. There is a single object with '

10541

n/a

'this\n'

10542

n/a

' value. This object is accessed through the built-in name\n'

10543

n/a

' "NotImplemented". Numeric methods and rich comparison methods\n'

10544

n/a

' should return this value if they do not implement the operation '

10545

n/a

'for\n'

10546

n/a

' the operands provided. (The interpreter will then try the\n'

10547

n/a

' reflected operation, or some other fallback, depending on the\n'

10548

n/a

' operator.) Its truth value is true.\n'

10549

n/a

'\n'

10550

n/a

' See Implementing the arithmetic operations for more details.\n'

10551

n/a

'\n'

10552

n/a

'Ellipsis\n'

10553

n/a

' This type has a single value. There is a single object with '

10554

n/a

'this\n'

10555

n/a

' value. This object is accessed through the literal "..." or the\n'

10556

n/a

' built-in name "Ellipsis". Its truth value is true.\n'

10557

n/a

'\n'

10558

n/a

'"numbers.Number"\n'

10559

n/a

' These are created by numeric literals and returned as results '

10560

n/a

'by\n'

10561

n/a

' arithmetic operators and arithmetic built-in functions. '

10562

n/a

'Numeric\n'

10563

n/a

' objects are immutable; once created their value never changes.\n'

10564

n/a

' Python numbers are of course strongly related to mathematical\n'

10565

n/a

' numbers, but subject to the limitations of numerical '

10566

n/a

'representation\n'

10567

n/a

' in computers.\n'

10568

n/a

'\n'

10569

n/a

' Python distinguishes between integers, floating point numbers, '

10570

n/a

'and\n'

10571

n/a

' complex numbers:\n'

10572

n/a

'\n'

10573

n/a

' "numbers.Integral"\n'

10574

n/a

' These represent elements from the mathematical set of '

10575

n/a

'integers\n'

10576

n/a

' (positive and negative).\n'

10577

n/a

'\n'

10578

n/a

' There are two types of integers:\n'

10579

n/a

'\n'

10580

n/a

' Integers ("int")\n'

10581

n/a

'\n'

10582

n/a

' These represent numbers in an unlimited range, subject to\n'

10583

n/a

' available (virtual) memory only. For the purpose of '

10584

n/a

'shift\n'

10585

n/a

' and mask operations, a binary representation is assumed, '

10586

n/a

'and\n'

10587

n/a

" negative numbers are represented in a variant of 2's\n"

10588

n/a

' complement which gives the illusion of an infinite string '

10589

n/a

'of\n'

10590

n/a

' sign bits extending to the left.\n'

10591

n/a

'\n'

10592

n/a

' Booleans ("bool")\n'

10593

n/a

' These represent the truth values False and True. The two\n'

10594

n/a

' objects representing the values "False" and "True" are '

10595

n/a

'the\n'

10596

n/a

' only Boolean objects. The Boolean type is a subtype of '

10597

n/a

'the\n'

10598

n/a

' integer type, and Boolean values behave like the values 0 '

10599

n/a

'and\n'

10600

n/a

' 1, respectively, in almost all contexts, the exception '

10601

n/a

'being\n'

10602

n/a

' that when converted to a string, the strings ""False"" or\n'

10603

n/a

' ""True"" are returned, respectively.\n'

10604

n/a

'\n'

10605

n/a

' The rules for integer representation are intended to give '

10606

n/a

'the\n'

10607

n/a

' most meaningful interpretation of shift and mask operations\n'

10608

n/a

' involving negative integers.\n'

10609

n/a

'\n'

10610

n/a

' "numbers.Real" ("float")\n'

10611

n/a

' These represent machine-level double precision floating '

10612

n/a

'point\n'

10613

n/a

' numbers. You are at the mercy of the underlying machine\n'

10614

n/a

' architecture (and C or Java implementation) for the accepted\n'

10615

n/a

' range and handling of overflow. Python does not support '

10616

n/a

'single-\n'

10617

n/a

' precision floating point numbers; the savings in processor '

10618

n/a

'and\n'

10619

n/a

' memory usage that are usually the reason for using these are\n'

10620

n/a

' dwarfed by the overhead of using objects in Python, so there '

10621

n/a

'is\n'

10622

n/a

' no reason to complicate the language with two kinds of '

10623

n/a

'floating\n'

10624

n/a

' point numbers.\n'

10625

n/a

'\n'

10626

n/a

' "numbers.Complex" ("complex")\n'

10627

n/a

' These represent complex numbers as a pair of machine-level\n'

10628

n/a

' double precision floating point numbers. The same caveats '

10629

n/a

'apply\n'

10630

n/a

' as for floating point numbers. The real and imaginary parts '

10631

n/a

'of a\n'

10632

n/a

' complex number "z" can be retrieved through the read-only\n'

10633

n/a

' attributes "z.real" and "z.imag".\n'

10634

n/a

'\n'

10635

n/a

'Sequences\n'

10636

n/a

' These represent finite ordered sets indexed by non-negative\n'

10637

n/a

' numbers. The built-in function "len()" returns the number of '

10638

n/a

'items\n'

10639

n/a

' of a sequence. When the length of a sequence is *n*, the index '

10640

n/a

'set\n'

10641

n/a

' contains the numbers 0, 1, ..., *n*-1. Item *i* of sequence *a* '

10642

n/a

'is\n'

10643

n/a

' selected by "a[i]".\n'

10644

n/a

'\n'

10645

n/a

' Sequences also support slicing: "a[i:j]" selects all items with\n'

10646

n/a

' index *k* such that *i* "<=" *k* "<" *j*. When used as an\n'

10647

n/a

' expression, a slice is a sequence of the same type. This '

10648

n/a

'implies\n'

10649

n/a

' that the index set is renumbered so that it starts at 0.\n'

10650

n/a

'\n'

10651

n/a

' Some sequences also support "extended slicing" with a third '

10652

n/a

'"step"\n'

10653

n/a

' parameter: "a[i:j:k]" selects all items of *a* with index *x* '

10654

n/a

'where\n'

10655

n/a

' "x = i + n*k", *n* ">=" "0" and *i* "<=" *x* "<" *j*.\n'

10656

n/a

'\n'

10657

n/a

' Sequences are distinguished according to their mutability:\n'

10658

n/a

'\n'

10659

n/a

' Immutable sequences\n'

10660

n/a

' An object of an immutable sequence type cannot change once it '

10661

n/a

'is\n'

10662

n/a

' created. (If the object contains references to other '

10663

n/a

'objects,\n'

10664

n/a

' these other objects may be mutable and may be changed; '

10665

n/a

'however,\n'

10666

n/a

' the collection of objects directly referenced by an '

10667

n/a

'immutable\n'

10668

n/a

' object cannot change.)\n'

10669

n/a

'\n'

10670

n/a

' The following types are immutable sequences:\n'

10671

n/a

'\n'

10672

n/a

' Strings\n'

10673

n/a

' A string is a sequence of values that represent Unicode '

10674

n/a

'code\n'

10675

n/a

' points. All the code points in the range "U+0000 - '

10676

n/a

'U+10FFFF"\n'

10677

n/a

" can be represented in a string. Python doesn't have a "

10678

n/a

'"char"\n'

10679

n/a

' type; instead, every code point in the string is '

10680

n/a

'represented\n'

10681

n/a

' as a string object with length "1". The built-in '

10682

n/a

'function\n'

10683

n/a

' "ord()" converts a code point from its string form to an\n'

10684

n/a

' integer in the range "0 - 10FFFF"; "chr()" converts an\n'

10685

n/a

' integer in the range "0 - 10FFFF" to the corresponding '

10686

n/a

'length\n'

10687

n/a

' "1" string object. "str.encode()" can be used to convert '

10688

n/a

'a\n'

10689

n/a

' "str" to "bytes" using the given text encoding, and\n'

10690

n/a

' "bytes.decode()" can be used to achieve the opposite.\n'

10691

n/a

'\n'

10692

n/a

' Tuples\n'

10693

n/a

' The items of a tuple are arbitrary Python objects. Tuples '

10694

n/a

'of\n'

10695

n/a

' two or more items are formed by comma-separated lists of\n'

10696

n/a

" expressions. A tuple of one item (a 'singleton') can be\n"

10697

n/a

' formed by affixing a comma to an expression (an expression '

10698

n/a

'by\n'

10699

n/a

' itself does not create a tuple, since parentheses must be\n'

10700

n/a

' usable for grouping of expressions). An empty tuple can '

10701

n/a

'be\n'

10702

n/a

' formed by an empty pair of parentheses.\n'

10703

n/a

'\n'

10704

n/a

' Bytes\n'

10705

n/a

' A bytes object is an immutable array. The items are '

10706

n/a

'8-bit\n'

10707

n/a

' bytes, represented by integers in the range 0 <= x < 256.\n'

10708

n/a

' Bytes literals (like "b\'abc\'") and the built-in '

10709

n/a

'function\n'

10710

n/a

' "bytes()" can be used to construct bytes objects. Also,\n'

10711

n/a

' bytes objects can be decoded to strings via the '

10712

n/a

'"decode()"\n'

10713

n/a

' method.\n'

10714

n/a

'\n'

10715

n/a

' Mutable sequences\n'

10716

n/a

' Mutable sequences can be changed after they are created. '

10717

n/a

'The\n'

10718

n/a

' subscription and slicing notations can be used as the target '

10719

n/a

'of\n'

10720

n/a

' assignment and "del" (delete) statements.\n'

10721

n/a

'\n'

10722

n/a

' There are currently two intrinsic mutable sequence types:\n'

10723

n/a

'\n'

10724

n/a

' Lists\n'

10725

n/a

' The items of a list are arbitrary Python objects. Lists '

10726

n/a

'are\n'

10727

n/a

' formed by placing a comma-separated list of expressions '

10728

n/a

'in\n'

10729

n/a

' square brackets. (Note that there are no special cases '

10730

n/a

'needed\n'

10731

n/a

' to form lists of length 0 or 1.)\n'

10732

n/a

'\n'

10733

n/a

' Byte Arrays\n'

10734

n/a

' A bytearray object is a mutable array. They are created '

10735

n/a

'by\n'

10736

n/a

' the built-in "bytearray()" constructor. Aside from being\n'

10737

n/a

' mutable (and hence unhashable), byte arrays otherwise '

10738

n/a

'provide\n'

10739

n/a

' the same interface and functionality as immutable bytes\n'

10740

n/a

' objects.\n'

10741

n/a

'\n'

10742

n/a

' The extension module "array" provides an additional example '

10743

n/a

'of a\n'

10744

n/a

' mutable sequence type, as does the "collections" module.\n'

10745

n/a

'\n'

10746

n/a

'Set types\n'

10747

n/a

' These represent unordered, finite sets of unique, immutable\n'

10748

n/a

' objects. As such, they cannot be indexed by any subscript. '

10749

n/a

'However,\n'

10750

n/a

' they can be iterated over, and the built-in function "len()"\n'

10751

n/a

' returns the number of items in a set. Common uses for sets are '

10752

n/a

'fast\n'

10753

n/a

' membership testing, removing duplicates from a sequence, and\n'

10754

n/a

' computing mathematical operations such as intersection, union,\n'

10755

n/a

' difference, and symmetric difference.\n'

10756

n/a

'\n'

10757

n/a

' For set elements, the same immutability rules apply as for\n'

10758

n/a

' dictionary keys. Note that numeric types obey the normal rules '

10759

n/a

'for\n'

10760

n/a

' numeric comparison: if two numbers compare equal (e.g., "1" and\n'

10761

n/a

' "1.0"), only one of them can be contained in a set.\n'

10762

n/a

'\n'

10763

n/a

' There are currently two intrinsic set types:\n'

10764

n/a

'\n'

10765

n/a

' Sets\n'

10766

n/a

' These represent a mutable set. They are created by the '

10767

n/a

'built-in\n'

10768

n/a

' "set()" constructor and can be modified afterwards by '

10769

n/a

'several\n'

10770

n/a

' methods, such as "add()".\n'

10771

n/a

'\n'

10772

n/a

' Frozen sets\n'

10773

n/a

' These represent an immutable set. They are created by the\n'

10774

n/a

' built-in "frozenset()" constructor. As a frozenset is '

10775

n/a

'immutable\n'

10776

n/a

' and *hashable*, it can be used again as an element of '

10777

n/a

'another\n'

10778

n/a

' set, or as a dictionary key.\n'

10779

n/a

'\n'

10780

n/a

'Mappings\n'

10781

n/a

' These represent finite sets of objects indexed by arbitrary '

10782

n/a

'index\n'

10783

n/a

' sets. The subscript notation "a[k]" selects the item indexed by '

10784

n/a

'"k"\n'

10785

n/a

' from the mapping "a"; this can be used in expressions and as '

10786

n/a

'the\n'

10787

n/a

' target of assignments or "del" statements. The built-in '

10788

n/a

'function\n'

10789

n/a

' "len()" returns the number of items in a mapping.\n'

10790

n/a

'\n'

10791

n/a

' There is currently a single intrinsic mapping type:\n'

10792

n/a

'\n'

10793

n/a

' Dictionaries\n'

10794

n/a

' These represent finite sets of objects indexed by nearly\n'

10795

n/a

' arbitrary values. The only types of values not acceptable '

10796

n/a

'as\n'

10797

n/a

' keys are values containing lists or dictionaries or other\n'

10798

n/a

' mutable types that are compared by value rather than by '

10799

n/a

'object\n'

10800

n/a

' identity, the reason being that the efficient implementation '

10801

n/a

'of\n'

10802

n/a

" dictionaries requires a key's hash value to remain constant.\n"

10803

n/a

' Numeric types used for keys obey the normal rules for '

10804

n/a

'numeric\n'

10805

n/a

' comparison: if two numbers compare equal (e.g., "1" and '

10806

n/a

'"1.0")\n'

10807

n/a

' then they can be used interchangeably to index the same\n'

10808

n/a

' dictionary entry.\n'

10809

n/a

'\n'

10810

n/a

' Dictionaries are mutable; they can be created by the "{...}"\n'

10811

n/a

' notation (see section Dictionary displays).\n'

10812

n/a

'\n'

10813

n/a

' The extension modules "dbm.ndbm" and "dbm.gnu" provide\n'

10814

n/a

' additional examples of mapping types, as does the '

10815

n/a

'"collections"\n'

10816

n/a

' module.\n'

10817

n/a

'\n'

10818

n/a

'Callable types\n'

10819

n/a

' These are the types to which the function call operation (see\n'

10820

n/a

' section Calls) can be applied:\n'

10821

n/a

'\n'

10822

n/a

' User-defined functions\n'

10823

n/a

' A user-defined function object is created by a function\n'

10824

n/a

' definition (see section Function definitions). It should be\n'

10825

n/a

' called with an argument list containing the same number of '

10826

n/a

'items\n'

10827

n/a

" as the function's formal parameter list.\n"

10828

n/a

'\n'

10829

n/a

' Special attributes:\n'

10830

n/a

'\n'

10831

n/a

' '

10832

n/a

'+---------------------------+---------------------------------+-------------+\n'

10833

n/a

' | Attribute | Meaning '

10834

n/a

'| |\n'

10835

n/a

' '

10836

n/a

'+===========================+=================================+=============+\n'

10837

n/a

' | "__doc__" | The function\'s '

10838

n/a

'documentation | Writable |\n'

10839

n/a

' | | string, or "None" if '

10840

n/a

'| |\n'

10841

n/a

' | | unavailable; not inherited by '

10842

n/a

'| |\n'

10843

n/a

' | | subclasses '

10844

n/a

'| |\n'

10845

n/a

' '

10846

n/a

'+---------------------------+---------------------------------+-------------+\n'

10847

n/a

' | "__name__" | The function\'s '

10848

n/a

'name | Writable |\n'

10849

n/a

' '

10850

n/a

'+---------------------------+---------------------------------+-------------+\n'

10851

n/a

' | "__qualname__" | The function\'s *qualified '

10852

n/a

'name* | Writable |\n'

10853

n/a

' | | New in version 3.3. '

10854

n/a

'| |\n'

10855

n/a

' '

10856

n/a

'+---------------------------+---------------------------------+-------------+\n'

10857

n/a

' | "__module__" | The name of the module the '

10858

n/a

'| Writable |\n'

10859

n/a

' | | function was defined in, or '

10860

n/a

'| |\n'

10861

n/a

' | | "None" if unavailable. '

10862

n/a

'| |\n'

10863

n/a

' '

10864

n/a

'+---------------------------+---------------------------------+-------------+\n'

10865

n/a

' | "__defaults__" | A tuple containing default '

10866

n/a

'| Writable |\n'

10867

n/a

' | | argument values for those '

10868

n/a

'| |\n'

10869

n/a

' | | arguments that have defaults, '

10870

n/a

'| |\n'

10871

n/a

' | | or "None" if no arguments have '

10872

n/a

'| |\n'

10873

n/a

' | | a default value '

10874

n/a

'| |\n'

10875

n/a

' '

10876

n/a

'+---------------------------+---------------------------------+-------------+\n'

10877

n/a

' | "__code__" | The code object representing '

10878

n/a

'| Writable |\n'

10879

n/a

' | | the compiled function body. '

10880

n/a

'| |\n'

10881

n/a

' '

10882

n/a

'+---------------------------+---------------------------------+-------------+\n'

10883

n/a

' | "__globals__" | A reference to the dictionary '

10884

n/a

'| Read-only |\n'

10885

n/a

" | | that holds the function's "

10886

n/a

'| |\n'

10887

n/a

' | | global variables --- the global '

10888

n/a

'| |\n'

10889

n/a

' | | namespace of the module in '

10890

n/a

'| |\n'

10891

n/a

' | | which the function was defined. '

10892

n/a

'| |\n'

10893

n/a

' '

10894

n/a

'+---------------------------+---------------------------------+-------------+\n'

10895

n/a

' | "__dict__" | The namespace supporting '

10896

n/a

'| Writable |\n'

10897

n/a

' | | arbitrary function attributes. '

10898

n/a

'| |\n'

10899

n/a

' '

10900

n/a

'+---------------------------+---------------------------------+-------------+\n'

10901

n/a

' | "__closure__" | "None" or a tuple of cells that '

10902

n/a

'| Read-only |\n'

10903

n/a

' | | contain bindings for the '

10904

n/a

'| |\n'

10905

n/a

" | | function's free variables. "

10906

n/a

'| |\n'

10907

n/a

' '

10908

n/a

'+---------------------------+---------------------------------+-------------+\n'

10909

n/a

' | "__annotations__" | A dict containing annotations '

10910

n/a

'| Writable |\n'

10911

n/a

' | | of parameters. The keys of the '

10912

n/a

'| |\n'

10913

n/a

' | | dict are the parameter names, '

10914

n/a

'| |\n'

10915

n/a

' | | and "\'return\'" for the '

10916

n/a

'return | |\n'

10917

n/a

' | | annotation, if provided. '

10918

n/a

'| |\n'

10919

n/a

' '

10920

n/a

'+---------------------------+---------------------------------+-------------+\n'

10921

n/a

' | "__kwdefaults__" | A dict containing defaults for '

10922

n/a

'| Writable |\n'

10923

n/a

' | | keyword-only parameters. '

10924

n/a

'| |\n'

10925

n/a

' '

10926

n/a

'+---------------------------+---------------------------------+-------------+\n'

10927

n/a

'\n'

10928

n/a

' Most of the attributes labelled "Writable" check the type of '

10929

n/a

'the\n'

10930

n/a

' assigned value.\n'

10931

n/a

'\n'

10932

n/a

' Function objects also support getting and setting arbitrary\n'

10933

n/a

' attributes, which can be used, for example, to attach '

10934

n/a

'metadata\n'

10935

n/a

' to functions. Regular attribute dot-notation is used to get '

10936

n/a

'and\n'

10937

n/a

' set such attributes. *Note that the current implementation '

10938

n/a

'only\n'

10939

n/a

' supports function attributes on user-defined functions. '

10940

n/a

'Function\n'

10941

n/a

' attributes on built-in functions may be supported in the\n'

10942

n/a

' future.*\n'

10943

n/a

'\n'

10944

n/a

" Additional information about a function's definition can be\n"

10945

n/a

' retrieved from its code object; see the description of '

10946

n/a

'internal\n'

10947

n/a

' types below.\n'

10948

n/a

'\n'

10949

n/a

' Instance methods\n'

10950

n/a

' An instance method object combines a class, a class instance '

10951

n/a

'and\n'

10952

n/a

' any callable object (normally a user-defined function).\n'

10953

n/a

'\n'

10954

n/a

' Special read-only attributes: "__self__" is the class '

10955

n/a

'instance\n'

10956

n/a

' object, "__func__" is the function object; "__doc__" is the\n'

10957

n/a

' method\'s documentation (same as "__func__.__doc__"); '

10958

n/a

'"__name__"\n'

10959

n/a

' is the method name (same as "__func__.__name__"); '

10960

n/a

'"__module__"\n'

10961

n/a

' is the name of the module the method was defined in, or '

10962

n/a

'"None"\n'

10963

n/a

' if unavailable.\n'

10964

n/a

'\n'

10965

n/a

' Methods also support accessing (but not setting) the '

10966

n/a

'arbitrary\n'

10967

n/a

' function attributes on the underlying function object.\n'

10968

n/a

'\n'

10969

n/a

' User-defined method objects may be created when getting an\n'

10970

n/a

' attribute of a class (perhaps via an instance of that class), '

10971

n/a

'if\n'

10972

n/a

' that attribute is a user-defined function object or a class\n'

10973

n/a

' method object.\n'

10974

n/a

'\n'

10975

n/a

' When an instance method object is created by retrieving a '

10976

n/a

'user-\n'

10977

n/a

' defined function object from a class via one of its '

10978

n/a

'instances,\n'

10979

n/a

' its "__self__" attribute is the instance, and the method '

10980

n/a

'object\n'

10981

n/a

' is said to be bound. The new method\'s "__func__" attribute '

10982

n/a

'is\n'

10983

n/a

' the original function object.\n'

10984

n/a

'\n'

10985

n/a

' When a user-defined method object is created by retrieving\n'

10986

n/a

' another method object from a class or instance, the behaviour '

10987

n/a

'is\n'

10988

n/a

' the same as for a function object, except that the '

10989

n/a

'"__func__"\n'

10990

n/a

' attribute of the new instance is not the original method '

10991

n/a

'object\n'

10992

n/a

' but its "__func__" attribute.\n'

10993

n/a

'\n'

10994

n/a

' When an instance method object is created by retrieving a '

10995

n/a

'class\n'

10996

n/a

' method object from a class or instance, its "__self__" '

10997

n/a

'attribute\n'

10998

n/a

' is the class itself, and its "__func__" attribute is the\n'

10999

n/a

' function object underlying the class method.\n'

11000

n/a

'\n'

11001

n/a

' When an instance method object is called, the underlying\n'

11002

n/a

' function ("__func__") is called, inserting the class '

11003

n/a

'instance\n'

11004

n/a

' ("__self__") in front of the argument list. For instance, '

11005

n/a

'when\n'

11006

n/a

' "C" is a class which contains a definition for a function '

11007

n/a

'"f()",\n'

11008

n/a

' and "x" is an instance of "C", calling "x.f(1)" is equivalent '

11009

n/a

'to\n'

11010

n/a

' calling "C.f(x, 1)".\n'

11011

n/a

'\n'

11012

n/a

' When an instance method object is derived from a class '

11013

n/a

'method\n'

11014

n/a

' object, the "class instance" stored in "__self__" will '

11015

n/a

'actually\n'

11016

n/a

' be the class itself, so that calling either "x.f(1)" or '

11017

n/a

'"C.f(1)"\n'

11018

n/a

' is equivalent to calling "f(C,1)" where "f" is the '

11019

n/a

'underlying\n'

11020

n/a

' function.\n'

11021

n/a

'\n'

11022

n/a

' Note that the transformation from function object to '

11023

n/a

'instance\n'

11024

n/a

' method object happens each time the attribute is retrieved '

11025

n/a

'from\n'

11026

n/a

' the instance. In some cases, a fruitful optimization is to\n'

11027

n/a

' assign the attribute to a local variable and call that local\n'

11028

n/a

' variable. Also notice that this transformation only happens '

11029

n/a

'for\n'

11030

n/a

' user-defined functions; other callable objects (and all non-\n'

11031

n/a

' callable objects) are retrieved without transformation. It '

11032

n/a

'is\n'

11033

n/a

' also important to note that user-defined functions which are\n'

11034

n/a

' attributes of a class instance are not converted to bound\n'

11035

n/a

' methods; this *only* happens when the function is an '

11036

n/a

'attribute\n'

11037

n/a

' of the class.\n'

11038

n/a

'\n'

11039

n/a

' Generator functions\n'

11040

n/a

' A function or method which uses the "yield" statement (see\n'

11041

n/a

' section The yield statement) is called a *generator '

11042

n/a

'function*.\n'

11043

n/a

' Such a function, when called, always returns an iterator '

11044

n/a

'object\n'

11045

n/a

' which can be used to execute the body of the function: '

11046

n/a

'calling\n'

11047

n/a

' the iterator\'s "iterator.__next__()" method will cause the\n'

11048

n/a

' function to execute until it provides a value using the '

11049

n/a

'"yield"\n'

11050

n/a

' statement. When the function executes a "return" statement '

11051

n/a

'or\n'

11052

n/a

' falls off the end, a "StopIteration" exception is raised and '

11053

n/a

'the\n'

11054

n/a

' iterator will have reached the end of the set of values to '

11055

n/a

'be\n'

11056

n/a

' returned.\n'

11057

n/a

'\n'

11058

n/a

' Coroutine functions\n'

11059

n/a

' A function or method which is defined using "async def" is\n'

11060

n/a

' called a *coroutine function*. Such a function, when '

11061

n/a

'called,\n'

11062

n/a

' returns a *coroutine* object. It may contain "await"\n'

11063

n/a

' expressions, as well as "async with" and "async for" '

11064

n/a

'statements.\n'

11065

n/a

' See also the Coroutine Objects section.\n'

11066

n/a

'\n'

11067

n/a

' Built-in functions\n'

11068

n/a

' A built-in function object is a wrapper around a C function.\n'

11069

n/a

' Examples of built-in functions are "len()" and "math.sin()"\n'

11070

n/a

' ("math" is a standard built-in module). The number and type '

11071

n/a

'of\n'

11072

n/a

' the arguments are determined by the C function. Special '

11073

n/a

'read-\n'

11074

n/a

' only attributes: "__doc__" is the function\'s documentation\n'

11075

n/a

' string, or "None" if unavailable; "__name__" is the '

11076

n/a

"function's\n"

11077

n/a

' name; "__self__" is set to "None" (but see the next item);\n'

11078

n/a

' "__module__" is the name of the module the function was '

11079

n/a

'defined\n'

11080

n/a

' in or "None" if unavailable.\n'

11081

n/a

'\n'

11082

n/a

' Built-in methods\n'

11083

n/a

' This is really a different disguise of a built-in function, '

11084

n/a

'this\n'

11085

n/a

' time containing an object passed to the C function as an\n'

11086

n/a

' implicit extra argument. An example of a built-in method is\n'

11087

n/a

' "alist.append()", assuming *alist* is a list object. In this\n'

11088

n/a

' case, the special read-only attribute "__self__" is set to '

11089

n/a

'the\n'

11090

n/a

' object denoted by *alist*.\n'

11091

n/a

'\n'

11092

n/a

' Classes\n'

11093

n/a

' Classes are callable. These objects normally act as '

11094

n/a

'factories\n'

11095

n/a

' for new instances of themselves, but variations are possible '

11096

n/a

'for\n'

11097

n/a

' class types that override "__new__()". The arguments of the\n'

11098

n/a

' call are passed to "__new__()" and, in the typical case, to\n'

11099

n/a

' "__init__()" to initialize the new instance.\n'

11100

n/a

'\n'

11101

n/a

' Class Instances\n'

11102

n/a

' Instances of arbitrary classes can be made callable by '

11103

n/a

'defining\n'

11104

n/a

' a "__call__()" method in their class.\n'

11105

n/a

'\n'

11106

n/a

'Modules\n'

11107

n/a

' Modules are a basic organizational unit of Python code, and are\n'

11108

n/a

' created by the import system as invoked either by the "import"\n'

11109

n/a

' statement (see "import"), or by calling functions such as\n'

11110

n/a

' "importlib.import_module()" and built-in "__import__()". A '

11111

n/a

'module\n'

11112

n/a

' object has a namespace implemented by a dictionary object (this '

11113

n/a

'is\n'

11114

n/a

' the dictionary referenced by the "__globals__" attribute of\n'

11115

n/a

' functions defined in the module). Attribute references are\n'

11116

n/a

' translated to lookups in this dictionary, e.g., "m.x" is '

11117

n/a

'equivalent\n'

11118

n/a

' to "m.__dict__["x"]". A module object does not contain the code\n'

11119

n/a

" object used to initialize the module (since it isn't needed "

11120

n/a

'once\n'

11121

n/a

' the initialization is done).\n'

11122

n/a

'\n'

11123

n/a

" Attribute assignment updates the module's namespace dictionary,\n"

11124

n/a

' e.g., "m.x = 1" is equivalent to "m.__dict__["x"] = 1".\n'

11125

n/a

'\n'

11126

n/a

' Predefined (writable) attributes: "__name__" is the module\'s '

11127

n/a

'name;\n'

11128

n/a

' "__doc__" is the module\'s documentation string, or "None" if\n'

11129

n/a

' unavailable; "__annotations__" (optional) is a dictionary\n'

11130

n/a

' containing *variable annotations* collected during module body\n'

11131

n/a

' execution; "__file__" is the pathname of the file from which '

11132

n/a

'the\n'

11133

n/a

' module was loaded, if it was loaded from a file. The "__file__"\n'

11134

n/a

' attribute may be missing for certain types of modules, such as '

11135

n/a

'C\n'

11136

n/a

' modules that are statically linked into the interpreter; for\n'

11137

n/a

' extension modules loaded dynamically from a shared library, it '

11138

n/a

'is\n'

11139

n/a

' the pathname of the shared library file.\n'

11140

n/a

'\n'

11141

n/a

' Special read-only attribute: "__dict__" is the module\'s '

11142

n/a

'namespace\n'

11143

n/a

' as a dictionary object.\n'

11144

n/a

'\n'

11145

n/a

' **CPython implementation detail:** Because of the way CPython\n'

11146

n/a

' clears module dictionaries, the module dictionary will be '

11147

n/a

'cleared\n'

11148

n/a

' when the module falls out of scope even if the dictionary still '

11149

n/a

'has\n'

11150

n/a

' live references. To avoid this, copy the dictionary or keep '

11151

n/a

'the\n'

11152

n/a

' module around while using its dictionary directly.\n'

11153

n/a

'\n'

11154

n/a

'Custom classes\n'

11155

n/a

' Custom class types are typically created by class definitions '

11156

n/a

'(see\n'

11157

n/a

' section Class definitions). A class has a namespace implemented '

11158

n/a

'by\n'

11159

n/a

' a dictionary object. Class attribute references are translated '

11160

n/a

'to\n'

11161

n/a

' lookups in this dictionary, e.g., "C.x" is translated to\n'

11162

n/a

' "C.__dict__["x"]" (although there are a number of hooks which '

11163

n/a

'allow\n'

11164

n/a

' for other means of locating attributes). When the attribute name '

11165

n/a

'is\n'

11166

n/a

' not found there, the attribute search continues in the base\n'

11167

n/a

' classes. This search of the base classes uses the C3 method\n'

11168

n/a

' resolution order which behaves correctly even in the presence '

11169

n/a

'of\n'

11170

n/a

" 'diamond' inheritance structures where there are multiple\n"

11171

n/a

' inheritance paths leading back to a common ancestor. Additional\n'

11172

n/a

' details on the C3 MRO used by Python can be found in the\n'

11173

n/a

' documentation accompanying the 2.3 release at\n'

11174

n/a

' https://www.python.org/download/releases/2.3/mro/.\n'

11175

n/a

'\n'

11176

n/a

' When a class attribute reference (for class "C", say) would '

11177

n/a

'yield a\n'

11178

n/a

' class method object, it is transformed into an instance method\n'

11179

n/a

' object whose "__self__" attributes is "C". When it would yield '

11180

n/a

'a\n'

11181

n/a

' static method object, it is transformed into the object wrapped '

11182

n/a

'by\n'

11183

n/a

' the static method object. See section Implementing Descriptors '

11184

n/a

'for\n'

11185

n/a

' another way in which attributes retrieved from a class may '

11186

n/a

'differ\n'

11187

n/a

' from those actually contained in its "__dict__".\n'

11188

n/a

'\n'

11189

n/a

" Class attribute assignments update the class's dictionary, "

11190

n/a

'never\n'

11191

n/a

' the dictionary of a base class.\n'

11192

n/a

'\n'

11193

n/a

' A class object can be called (see above) to yield a class '

11194

n/a

'instance\n'

11195

n/a

' (see below).\n'

11196

n/a

'\n'

11197

n/a

' Special attributes: "__name__" is the class name; "__module__" '

11198

n/a

'is\n'

11199

n/a

' the module name in which the class was defined; "__dict__" is '

11200

n/a

'the\n'

11201

n/a

' dictionary containing the class\'s namespace; "__bases__" is a '

11202

n/a

'tuple\n'

11203

n/a

' (possibly empty or a singleton) containing the base classes, in '

11204

n/a

'the\n'

11205

n/a

' order of their occurrence in the base class list; "__doc__" is '

11206

n/a

'the\n'

11207

n/a

" class's documentation string, or None if undefined;\n"

11208

n/a

' "__annotations__" (optional) is a dictionary containing '

11209

n/a

'*variable\n'

11210

n/a

' annotations* collected during class body execution.\n'

11211

n/a

'\n'

11212

n/a

'Class instances\n'

11213

n/a

' A class instance is created by calling a class object (see '

11214

n/a

'above).\n'

11215

n/a

' A class instance has a namespace implemented as a dictionary '

11216

n/a

'which\n'

11217

n/a

' is the first place in which attribute references are searched.\n'

11218

n/a

" When an attribute is not found there, and the instance's class "

11219

n/a

'has\n'

11220

n/a

' an attribute by that name, the search continues with the class\n'

11221

n/a

' attributes. If a class attribute is found that is a '

11222

n/a

'user-defined\n'

11223

n/a

' function object, it is transformed into an instance method '

11224

n/a

'object\n'

11225

n/a

' whose "__self__" attribute is the instance. Static method and\n'

11226

n/a

' class method objects are also transformed; see above under\n'

11227

n/a

' "Classes". See section Implementing Descriptors for another way '

11228

n/a

'in\n'

11229

n/a

' which attributes of a class retrieved via its instances may '

11230

n/a

'differ\n'

11231

n/a

' from the objects actually stored in the class\'s "__dict__". If '

11232

n/a

'no\n'

11233

n/a

" class attribute is found, and the object's class has a\n"

11234

n/a

' "__getattr__()" method, that is called to satisfy the lookup.\n'

11235

n/a

'\n'

11236

n/a

" Attribute assignments and deletions update the instance's\n"

11237

n/a

" dictionary, never a class's dictionary. If the class has a\n"

11238

n/a

' "__setattr__()" or "__delattr__()" method, this is called '

11239

n/a

'instead\n'

11240

n/a

' of updating the instance dictionary directly.\n'

11241

n/a

'\n'

11242

n/a

' Class instances can pretend to be numbers, sequences, or '

11243

n/a

'mappings\n'

11244

n/a

' if they have methods with certain special names. See section\n'

11245

n/a

' Special method names.\n'

11246

n/a

'\n'

11247

n/a

' Special attributes: "__dict__" is the attribute dictionary;\n'

11248

n/a

' "__class__" is the instance\'s class.\n'

11249

n/a

'\n'

11250

n/a

'I/O objects (also known as file objects)\n'

11251

n/a

' A *file object* represents an open file. Various shortcuts are\n'

11252

n/a

' available to create file objects: the "open()" built-in '

11253

n/a

'function,\n'

11254

n/a

' and also "os.popen()", "os.fdopen()", and the "makefile()" '

11255

n/a

'method\n'

11256

n/a

' of socket objects (and perhaps by other functions or methods\n'

11257

n/a

' provided by extension modules).\n'

11258

n/a

'\n'

11259

n/a

' The objects "sys.stdin", "sys.stdout" and "sys.stderr" are\n'

11260

n/a

" initialized to file objects corresponding to the interpreter's\n"

11261

n/a

' standard input, output and error streams; they are all open in '

11262

n/a

'text\n'

11263

n/a

' mode and therefore follow the interface defined by the\n'

11264

n/a

' "io.TextIOBase" abstract class.\n'

11265

n/a

'\n'

11266

n/a

'Internal types\n'

11267

n/a

' A few types used internally by the interpreter are exposed to '

11268

n/a

'the\n'

11269

n/a

' user. Their definitions may change with future versions of the\n'

11270

n/a

' interpreter, but they are mentioned here for completeness.\n'

11271

n/a

'\n'

11272

n/a

' Code objects\n'

11273

n/a

' Code objects represent *byte-compiled* executable Python '

11274

n/a

'code,\n'

11275

n/a

' or *bytecode*. The difference between a code object and a\n'

11276

n/a

' function object is that the function object contains an '

11277

n/a

'explicit\n'

11278

n/a

" reference to the function's globals (the module in which it "

11279

n/a

'was\n'

11280

n/a

' defined), while a code object contains no context; also the\n'

11281

n/a

' default argument values are stored in the function object, '

11282

n/a

'not\n'

11283

n/a

' in the code object (because they represent values calculated '

11284

n/a

'at\n'

11285

n/a

' run-time). Unlike function objects, code objects are '

11286

n/a

'immutable\n'

11287

n/a

' and contain no references (directly or indirectly) to '

11288

n/a

'mutable\n'

11289

n/a

' objects.\n'

11290

n/a

'\n'

11291

n/a

' Special read-only attributes: "co_name" gives the function '

11292

n/a

'name;\n'

11293

n/a

' "co_argcount" is the number of positional arguments '

11294

n/a

'(including\n'

11295

n/a

' arguments with default values); "co_nlocals" is the number '

11296

n/a

'of\n'

11297

n/a

' local variables used by the function (including arguments);\n'

11298

n/a

' "co_varnames" is a tuple containing the names of the local\n'

11299

n/a

' variables (starting with the argument names); "co_cellvars" '

11300

n/a

'is a\n'

11301

n/a

' tuple containing the names of local variables that are\n'

11302

n/a

' referenced by nested functions; "co_freevars" is a tuple\n'

11303

n/a

' containing the names of free variables; "co_code" is a '

11304

n/a

'string\n'

11305

n/a

' representing the sequence of bytecode instructions; '

11306

n/a

'"co_consts"\n'

11307

n/a

' is a tuple containing the literals used by the bytecode;\n'

11308

n/a

' "co_names" is a tuple containing the names used by the '

11309

n/a

'bytecode;\n'

11310

n/a

' "co_filename" is the filename from which the code was '

11311

n/a

'compiled;\n'

11312

n/a

' "co_firstlineno" is the first line number of the function;\n'

11313

n/a

' "co_lnotab" is a string encoding the mapping from bytecode\n'

11314

n/a

' offsets to line numbers (for details see the source code of '

11315

n/a

'the\n'

11316

n/a

' interpreter); "co_stacksize" is the required stack size\n'

11317

n/a

' (including local variables); "co_flags" is an integer '

11318

n/a

'encoding a\n'

11319

n/a

' number of flags for the interpreter.\n'

11320

n/a

'\n'

11321

n/a

' The following flag bits are defined for "co_flags": bit '

11322

n/a

'"0x04"\n'

11323

n/a

' is set if the function uses the "*arguments" syntax to accept '

11324

n/a

'an\n'

11325

n/a

' arbitrary number of positional arguments; bit "0x08" is set '

11326

n/a

'if\n'

11327

n/a

' the function uses the "**keywords" syntax to accept '

11328

n/a

'arbitrary\n'

11329

n/a

' keyword arguments; bit "0x20" is set if the function is a\n'

11330

n/a

' generator.\n'

11331

n/a

'\n'

11332

n/a

' Future feature declarations ("from __future__ import '

11333

n/a

'division")\n'

11334

n/a

' also use bits in "co_flags" to indicate whether a code '

11335

n/a

'object\n'

11336

n/a

' was compiled with a particular feature enabled: bit "0x2000" '

11337

n/a

'is\n'

11338

n/a

' set if the function was compiled with future division '

11339

n/a

'enabled;\n'

11340

n/a

' bits "0x10" and "0x1000" were used in earlier versions of\n'

11341

n/a

' Python.\n'

11342

n/a

'\n'

11343

n/a

' Other bits in "co_flags" are reserved for internal use.\n'

11344

n/a

'\n'

11345

n/a

' If a code object represents a function, the first item in\n'

11346

n/a

' "co_consts" is the documentation string of the function, or\n'

11347

n/a

' "None" if undefined.\n'

11348

n/a

'\n'

11349

n/a

' Frame objects\n'

11350

n/a

' Frame objects represent execution frames. They may occur in\n'

11351

n/a

' traceback objects (see below).\n'

11352

n/a

'\n'

11353

n/a

' Special read-only attributes: "f_back" is to the previous '

11354

n/a

'stack\n'

11355

n/a

' frame (towards the caller), or "None" if this is the bottom\n'

11356

n/a

' stack frame; "f_code" is the code object being executed in '

11357

n/a

'this\n'

11358

n/a

' frame; "f_locals" is the dictionary used to look up local\n'

11359

n/a

' variables; "f_globals" is used for global variables;\n'

11360

n/a

' "f_builtins" is used for built-in (intrinsic) names; '

11361

n/a

'"f_lasti"\n'

11362

n/a

' gives the precise instruction (this is an index into the\n'

11363

n/a

' bytecode string of the code object).\n'

11364

n/a

'\n'

11365

n/a

' Special writable attributes: "f_trace", if not "None", is a\n'

11366

n/a

' function called at the start of each source code line (this '

11367

n/a

'is\n'

11368

n/a

' used by the debugger); "f_lineno" is the current line number '

11369

n/a

'of\n'

11370

n/a

' the frame --- writing to this from within a trace function '

11371

n/a

'jumps\n'

11372

n/a

' to the given line (only for the bottom-most frame). A '

11373

n/a

'debugger\n'

11374

n/a

' can implement a Jump command (aka Set Next Statement) by '

11375

n/a

'writing\n'

11376

n/a

' to f_lineno.\n'

11377

n/a

'\n'

11378

n/a

' Frame objects support one method:\n'

11379

n/a

'\n'

11380

n/a

' frame.clear()\n'

11381

n/a

'\n'

11382

n/a

' This method clears all references to local variables held '

11383

n/a

'by\n'

11384

n/a

' the frame. Also, if the frame belonged to a generator, '

11385

n/a

'the\n'

11386

n/a

' generator is finalized. This helps break reference '

11387

n/a

'cycles\n'

11388

n/a

' involving frame objects (for example when catching an\n'

11389

n/a

' exception and storing its traceback for later use).\n'

11390

n/a

'\n'

11391

n/a

' "RuntimeError" is raised if the frame is currently '

11392

n/a

'executing.\n'

11393

n/a

'\n'

11394

n/a

' New in version 3.4.\n'

11395

n/a

'\n'

11396

n/a

' Traceback objects\n'

11397

n/a

' Traceback objects represent a stack trace of an exception. '

11398

n/a

'A\n'

11399

n/a

' traceback object is created when an exception occurs. When '

11400

n/a

'the\n'

11401

n/a

' search for an exception handler unwinds the execution stack, '

11402

n/a

'at\n'

11403

n/a

' each unwound level a traceback object is inserted in front '

11404

n/a

'of\n'

11405

n/a

' the current traceback. When an exception handler is '

11406

n/a

'entered,\n'

11407

n/a

' the stack trace is made available to the program. (See '

11408

n/a

'section\n'

11409

n/a

' The try statement.) It is accessible as the third item of '

11410

n/a

'the\n'

11411

n/a

' tuple returned by "sys.exc_info()". When the program contains '

11412

n/a

'no\n'

11413

n/a

' suitable handler, the stack trace is written (nicely '

11414

n/a

'formatted)\n'

11415

n/a

' to the standard error stream; if the interpreter is '

11416

n/a

'interactive,\n'

11417

n/a

' it is also made available to the user as '

11418

n/a

'"sys.last_traceback".\n'

11419

n/a

'\n'

11420

n/a

' Special read-only attributes: "tb_next" is the next level in '

11421

n/a

'the\n'

11422

n/a

' stack trace (towards the frame where the exception occurred), '

11423

n/a

'or\n'

11424

n/a

' "None" if there is no next level; "tb_frame" points to the\n'

11425

n/a

' execution frame of the current level; "tb_lineno" gives the '

11426

n/a

'line\n'

11427

n/a

' number where the exception occurred; "tb_lasti" indicates '

11428

n/a

'the\n'

11429

n/a

' precise instruction. The line number and last instruction '

11430

n/a

'in\n'

11431

n/a

' the traceback may differ from the line number of its frame\n'

11432

n/a

' object if the exception occurred in a "try" statement with '

11433

n/a

'no\n'

11434

n/a

' matching except clause or with a finally clause.\n'

11435

n/a

'\n'

11436

n/a

' Slice objects\n'

11437

n/a

' Slice objects are used to represent slices for '

11438

n/a

'"__getitem__()"\n'

11439

n/a

' methods. They are also created by the built-in "slice()"\n'

11440

n/a

' function.\n'

11441

n/a

'\n'

11442

n/a

' Special read-only attributes: "start" is the lower bound; '

11443

n/a

'"stop"\n'

11444

n/a

' is the upper bound; "step" is the step value; each is "None" '

11445

n/a

'if\n'

11446

n/a

' omitted. These attributes can have any type.\n'

11447

n/a

'\n'

11448

n/a

' Slice objects support one method:\n'

11449

n/a

'\n'

11450

n/a

' slice.indices(self, length)\n'

11451

n/a

'\n'

11452

n/a

' This method takes a single integer argument *length* and\n'

11453

n/a

' computes information about the slice that the slice '

11454

n/a

'object\n'

11455

n/a

' would describe if applied to a sequence of *length* '

11456

n/a

'items.\n'

11457

n/a

' It returns a tuple of three integers; respectively these '

11458

n/a

'are\n'

11459

n/a

' the *start* and *stop* indices and the *step* or stride\n'

11460

n/a

' length of the slice. Missing or out-of-bounds indices are\n'

11461

n/a

' handled in a manner consistent with regular slices.\n'

11462

n/a

'\n'

11463

n/a

' Static method objects\n'

11464

n/a

' Static method objects provide a way of defeating the\n'

11465

n/a

' transformation of function objects to method objects '

11466

n/a

'described\n'

11467

n/a

' above. A static method object is a wrapper around any other\n'

11468

n/a

' object, usually a user-defined method object. When a static\n'

11469

n/a

' method object is retrieved from a class or a class instance, '

11470

n/a

'the\n'

11471

n/a

' object actually returned is the wrapped object, which is not\n'

11472

n/a

' subject to any further transformation. Static method objects '

11473

n/a

'are\n'

11474

n/a

' not themselves callable, although the objects they wrap '

11475

n/a

'usually\n'

11476

n/a

' are. Static method objects are created by the built-in\n'

11477

n/a

' "staticmethod()" constructor.\n'

11478

n/a

'\n'

11479

n/a

' Class method objects\n'

11480

n/a

' A class method object, like a static method object, is a '

11481

n/a

'wrapper\n'

11482

n/a

' around another object that alters the way in which that '

11483

n/a

'object\n'

11484

n/a

' is retrieved from classes and class instances. The behaviour '

11485

n/a

'of\n'

11486

n/a

' class method objects upon such retrieval is described above,\n'

11487

n/a

' under "User-defined methods". Class method objects are '

11488

n/a

'created\n'

11489

n/a

' by the built-in "classmethod()" constructor.\n',

11490

n/a

'typesfunctions': '\n'

11491

n/a

'Functions\n'

11492

n/a

'*********\n'

11493

n/a

'\n'

11494

n/a

'Function objects are created by function definitions. The '

11495

n/a

'only\n'

11496

n/a

'operation on a function object is to call it: '

11497

n/a

'"func(argument-list)".\n'

11498

n/a

'\n'

11499

n/a

'There are really two flavors of function objects: built-in '

11500

n/a

'functions\n'

11501

n/a

'and user-defined functions. Both support the same '

11502

n/a

'operation (to call\n'

11503

n/a

'the function), but the implementation is different, hence '

11504

n/a

'the\n'

11505

n/a

'different object types.\n'

11506

n/a

'\n'

11507

n/a

'See Function definitions for more information.\n',

11508

n/a

'typesmapping': '\n'

11509

n/a

'Mapping Types --- "dict"\n'

11510

n/a

'************************\n'

11511

n/a

'\n'

11512

n/a

'A *mapping* object maps *hashable* values to arbitrary '

11513

n/a

'objects.\n'

11514

n/a

'Mappings are mutable objects. There is currently only one '

11515

n/a

'standard\n'

11516

n/a

'mapping type, the *dictionary*. (For other containers see '

11517

n/a

'the built-\n'

11518

n/a

'in "list", "set", and "tuple" classes, and the "collections" '

11519

n/a

'module.)\n'

11520

n/a

'\n'

11521

n/a

"A dictionary's keys are *almost* arbitrary values. Values "

11522

n/a

'that are\n'

11523

n/a

'not *hashable*, that is, values containing lists, '

11524

n/a

'dictionaries or\n'

11525

n/a

'other mutable types (that are compared by value rather than '

11526

n/a

'by object\n'

11527

n/a

'identity) may not be used as keys. Numeric types used for '

11528

n/a

'keys obey\n'

11529

n/a

'the normal rules for numeric comparison: if two numbers '

11530

n/a

'compare equal\n'

11531

n/a

'(such as "1" and "1.0") then they can be used '

11532

n/a

'interchangeably to index\n'

11533

n/a

'the same dictionary entry. (Note however, that since '

11534

n/a

'computers store\n'

11535

n/a

'floating-point numbers as approximations it is usually '

11536

n/a

'unwise to use\n'

11537

n/a

'them as dictionary keys.)\n'

11538

n/a

'\n'

11539

n/a

'Dictionaries can be created by placing a comma-separated '

11540

n/a

'list of "key:\n'

11541

n/a

'value" pairs within braces, for example: "{\'jack\': 4098, '

11542

n/a

"'sjoerd':\n"

11543

n/a

'4127}" or "{4098: \'jack\', 4127: \'sjoerd\'}", or by the '

11544

n/a

'"dict"\n'

11545

n/a

'constructor.\n'

11546

n/a

'\n'

11547

n/a

'class dict(**kwarg)\n'

11548

n/a

'class dict(mapping, **kwarg)\n'

11549

n/a

'class dict(iterable, **kwarg)\n'

11550

n/a

'\n'

11551

n/a

' Return a new dictionary initialized from an optional '

11552

n/a

'positional\n'

11553

n/a

' argument and a possibly empty set of keyword arguments.\n'

11554

n/a

'\n'

11555

n/a

' If no positional argument is given, an empty dictionary '

11556

n/a

'is created.\n'

11557

n/a

' If a positional argument is given and it is a mapping '

11558

n/a

'object, a\n'

11559

n/a

' dictionary is created with the same key-value pairs as '

11560

n/a

'the mapping\n'

11561

n/a

' object. Otherwise, the positional argument must be an '

11562

n/a

'*iterable*\n'

11563

n/a

' object. Each item in the iterable must itself be an '

11564

n/a

'iterable with\n'

11565

n/a

' exactly two objects. The first object of each item '

11566

n/a

'becomes a key\n'

11567

n/a

' in the new dictionary, and the second object the '

11568

n/a

'corresponding\n'

11569

n/a

' value. If a key occurs more than once, the last value '

11570

n/a

'for that key\n'

11571

n/a

' becomes the corresponding value in the new dictionary.\n'

11572

n/a

'\n'

11573

n/a

' If keyword arguments are given, the keyword arguments and '

11574

n/a

'their\n'

11575

n/a

' values are added to the dictionary created from the '

11576

n/a

'positional\n'

11577

n/a

' argument. If a key being added is already present, the '

11578

n/a

'value from\n'

11579

n/a

' the keyword argument replaces the value from the '

11580

n/a

'positional\n'

11581

n/a

' argument.\n'

11582

n/a

'\n'

11583

n/a

' To illustrate, the following examples all return a '

11584

n/a

'dictionary equal\n'

11585

n/a

' to "{"one": 1, "two": 2, "three": 3}":\n'

11586

n/a

'\n'

11587

n/a

' >>> a = dict(one=1, two=2, three=3)\n'

11588

n/a

" >>> b = {'one': 1, 'two': 2, 'three': 3}\n"

11589

n/a

" >>> c = dict(zip(['one', 'two', 'three'], [1, 2, 3]))\n"

11590

n/a

" >>> d = dict([('two', 2), ('one', 1), ('three', 3)])\n"

11591

n/a

" >>> e = dict({'three': 3, 'one': 1, 'two': 2})\n"

11592

n/a

' >>> a == b == c == d == e\n'

11593

n/a

' True\n'

11594

n/a

'\n'

11595

n/a

' Providing keyword arguments as in the first example only '

11596

n/a

'works for\n'

11597

n/a

' keys that are valid Python identifiers. Otherwise, any '

11598

n/a

'valid keys\n'

11599

n/a

' can be used.\n'

11600

n/a

'\n'

11601

n/a

' These are the operations that dictionaries support (and '

11602

n/a

'therefore,\n'

11603

n/a

' custom mapping types should support too):\n'

11604

n/a

'\n'

11605

n/a

' len(d)\n'

11606

n/a

'\n'

11607

n/a

' Return the number of items in the dictionary *d*.\n'

11608

n/a

'\n'

11609

n/a

' d[key]\n'

11610

n/a

'\n'

11611

n/a

' Return the item of *d* with key *key*. Raises a '

11612

n/a

'"KeyError" if\n'

11613

n/a

' *key* is not in the map.\n'

11614

n/a

'\n'

11615

n/a

' If a subclass of dict defines a method "__missing__()" '

11616

n/a

'and *key*\n'

11617

n/a

' is not present, the "d[key]" operation calls that '

11618

n/a

'method with\n'

11619

n/a

' the key *key* as argument. The "d[key]" operation '

11620

n/a

'then returns\n'

11621

n/a

' or raises whatever is returned or raised by the\n'

11622

n/a

' "__missing__(key)" call. No other operations or '

11623

n/a

'methods invoke\n'

11624

n/a

' "__missing__()". If "__missing__()" is not defined, '

11625

n/a

'"KeyError"\n'

11626

n/a

' is raised. "__missing__()" must be a method; it cannot '

11627

n/a

'be an\n'

11628

n/a

' instance variable:\n'

11629

n/a

'\n'

11630

n/a

' >>> class Counter(dict):\n'

11631

n/a

' ... def __missing__(self, key):\n'

11632

n/a

' ... return 0\n'

11633

n/a

' >>> c = Counter()\n'

11634

n/a

" >>> c['red']\n"

11635

n/a

' 0\n'

11636

n/a

" >>> c['red'] += 1\n"

11637

n/a

" >>> c['red']\n"

11638

n/a

' 1\n'

11639

n/a

'\n'

11640

n/a

' The example above shows part of the implementation of\n'

11641

n/a

' "collections.Counter". A different "__missing__" '

11642

n/a

'method is used\n'

11643

n/a

' by "collections.defaultdict".\n'

11644

n/a

'\n'

11645

n/a

' d[key] = value\n'

11646

n/a

'\n'

11647

n/a

' Set "d[key]" to *value*.\n'

11648

n/a

'\n'

11649

n/a

' del d[key]\n'

11650

n/a

'\n'

11651

n/a

' Remove "d[key]" from *d*. Raises a "KeyError" if '

11652

n/a

'*key* is not\n'

11653

n/a

' in the map.\n'

11654

n/a

'\n'

11655

n/a

' key in d\n'

11656

n/a

'\n'

11657

n/a

' Return "True" if *d* has a key *key*, else "False".\n'

11658

n/a

'\n'

11659

n/a

' key not in d\n'

11660

n/a

'\n'

11661

n/a

' Equivalent to "not key in d".\n'

11662

n/a

'\n'

11663

n/a

' iter(d)\n'

11664

n/a

'\n'

11665

n/a

' Return an iterator over the keys of the dictionary. '

11666

n/a

'This is a\n'

11667

n/a

' shortcut for "iter(d.keys())".\n'

11668

n/a

'\n'

11669

n/a

' clear()\n'

11670

n/a

'\n'

11671

n/a

' Remove all items from the dictionary.\n'

11672

n/a

'\n'

11673

n/a

' copy()\n'

11674

n/a

'\n'

11675

n/a

' Return a shallow copy of the dictionary.\n'

11676

n/a

'\n'

11677

n/a

' classmethod fromkeys(seq[, value])\n'

11678

n/a

'\n'

11679

n/a

' Create a new dictionary with keys from *seq* and '

11680

n/a

'values set to\n'

11681

n/a

' *value*.\n'

11682

n/a

'\n'

11683

n/a

' "fromkeys()" is a class method that returns a new '

11684

n/a

'dictionary.\n'

11685

n/a

' *value* defaults to "None".\n'

11686

n/a

'\n'

11687

n/a

' get(key[, default])\n'

11688

n/a

'\n'

11689

n/a

' Return the value for *key* if *key* is in the '

11690

n/a

'dictionary, else\n'

11691

n/a

' *default*. If *default* is not given, it defaults to '

11692

n/a

'"None", so\n'

11693

n/a

' that this method never raises a "KeyError".\n'

11694

n/a

'\n'

11695

n/a

' items()\n'

11696

n/a

'\n'

11697

n/a

' Return a new view of the dictionary\'s items ("(key, '

11698

n/a

'value)"\n'

11699

n/a

' pairs). See the documentation of view objects.\n'

11700

n/a

'\n'

11701

n/a

' keys()\n'

11702

n/a

'\n'

11703

n/a

" Return a new view of the dictionary's keys. See the\n"

11704

n/a

' documentation of view objects.\n'

11705

n/a

'\n'

11706

n/a

' pop(key[, default])\n'

11707

n/a

'\n'

11708

n/a

' If *key* is in the dictionary, remove it and return '

11709

n/a

'its value,\n'

11710

n/a

' else return *default*. If *default* is not given and '

11711

n/a

'*key* is\n'

11712

n/a

' not in the dictionary, a "KeyError" is raised.\n'

11713

n/a

'\n'

11714

n/a

' popitem()\n'

11715

n/a

'\n'

11716

n/a

' Remove and return an arbitrary "(key, value)" pair '

11717

n/a

'from the\n'

11718

n/a

' dictionary.\n'

11719

n/a

'\n'

11720

n/a

' "popitem()" is useful to destructively iterate over a\n'

11721

n/a

' dictionary, as often used in set algorithms. If the '

11722

n/a

'dictionary\n'

11723

n/a

' is empty, calling "popitem()" raises a "KeyError".\n'

11724

n/a

'\n'

11725

n/a

' setdefault(key[, default])\n'

11726

n/a

'\n'

11727

n/a

' If *key* is in the dictionary, return its value. If '

11728

n/a

'not, insert\n'

11729

n/a

' *key* with a value of *default* and return *default*. '

11730

n/a

'*default*\n'

11731

n/a

' defaults to "None".\n'

11732

n/a

'\n'

11733

n/a

' update([other])\n'

11734

n/a

'\n'

11735

n/a

' Update the dictionary with the key/value pairs from '

11736

n/a

'*other*,\n'

11737

n/a

' overwriting existing keys. Return "None".\n'

11738

n/a

'\n'

11739

n/a

' "update()" accepts either another dictionary object or '

11740

n/a

'an\n'

11741

n/a

' iterable of key/value pairs (as tuples or other '

11742

n/a

'iterables of\n'

11743

n/a

' length two). If keyword arguments are specified, the '

11744

n/a

'dictionary\n'

11745

n/a

' is then updated with those key/value pairs: '

11746

n/a

'"d.update(red=1,\n'

11747

n/a

' blue=2)".\n'

11748

n/a

'\n'

11749

n/a

' values()\n'

11750

n/a

'\n'

11751

n/a

" Return a new view of the dictionary's values. See "

11752

n/a

'the\n'

11753

n/a

' documentation of view objects.\n'

11754

n/a

'\n'

11755

n/a

' Dictionaries compare equal if and only if they have the '

11756

n/a

'same "(key,\n'

11757

n/a

' value)" pairs. Order comparisons (\'<\', \'<=\', \'>=\', '

11758

n/a

"'>') raise\n"

11759

n/a

' "TypeError".\n'

11760

n/a

'\n'

11761

n/a

'See also: "types.MappingProxyType" can be used to create a '

11762

n/a

'read-only\n'

11763

n/a

' view of a "dict".\n'

11764

n/a

'\n'

11765

n/a

'\n'

11766

n/a

'Dictionary view objects\n'

11767

n/a

'=======================\n'

11768

n/a

'\n'

11769

n/a

'The objects returned by "dict.keys()", "dict.values()" and\n'

11770

n/a

'"dict.items()" are *view objects*. They provide a dynamic '

11771

n/a

'view on the\n'

11772

n/a

"dictionary's entries, which means that when the dictionary "

11773

n/a

'changes,\n'

11774

n/a

'the view reflects these changes.\n'

11775

n/a

'\n'

11776

n/a

'Dictionary views can be iterated over to yield their '

11777

n/a

'respective data,\n'

11778

n/a

'and support membership tests:\n'

11779

n/a

'\n'

11780

n/a

'len(dictview)\n'

11781

n/a

'\n'

11782

n/a

' Return the number of entries in the dictionary.\n'

11783

n/a

'\n'

11784

n/a

'iter(dictview)\n'

11785

n/a

'\n'

11786

n/a

' Return an iterator over the keys, values or items '

11787

n/a

'(represented as\n'

11788

n/a

' tuples of "(key, value)") in the dictionary.\n'

11789

n/a

'\n'

11790

n/a

' Keys and values are iterated over in an arbitrary order '

11791

n/a

'which is\n'

11792

n/a

' non-random, varies across Python implementations, and '

11793

n/a

'depends on\n'

11794

n/a

" the dictionary's history of insertions and deletions. If "

11795

n/a

'keys,\n'

11796

n/a

' values and items views are iterated over with no '

11797

n/a

'intervening\n'

11798

n/a

' modifications to the dictionary, the order of items will '

11799

n/a

'directly\n'

11800

n/a

' correspond. This allows the creation of "(value, key)" '

11801

n/a

'pairs using\n'

11802

n/a

' "zip()": "pairs = zip(d.values(), d.keys())". Another '

11803

n/a

'way to\n'

11804

n/a

' create the same list is "pairs = [(v, k) for (k, v) in '

11805

n/a

'd.items()]".\n'

11806

n/a

'\n'

11807

n/a

' Iterating views while adding or deleting entries in the '

11808

n/a

'dictionary\n'

11809

n/a

' may raise a "RuntimeError" or fail to iterate over all '

11810

n/a

'entries.\n'

11811

n/a

'\n'

11812

n/a

'x in dictview\n'

11813

n/a

'\n'

11814

n/a

' Return "True" if *x* is in the underlying dictionary\'s '

11815

n/a

'keys, values\n'

11816

n/a

' or items (in the latter case, *x* should be a "(key, '

11817

n/a

'value)"\n'

11818

n/a

' tuple).\n'

11819

n/a

'\n'

11820

n/a

'Keys views are set-like since their entries are unique and '

11821

n/a

'hashable.\n'

11822

n/a

'If all values are hashable, so that "(key, value)" pairs are '

11823

n/a

'unique\n'

11824

n/a

'and hashable, then the items view is also set-like. (Values '

11825

n/a

'views are\n'

11826

n/a

'not treated as set-like since the entries are generally not '

11827

n/a

'unique.)\n'

11828

n/a

'For set-like views, all of the operations defined for the '

11829

n/a

'abstract\n'

11830

n/a

'base class "collections.abc.Set" are available (for example, '

11831

n/a

'"==",\n'

11832

n/a

'"<", or "^").\n'

11833

n/a

'\n'

11834

n/a

'An example of dictionary view usage:\n'

11835

n/a

'\n'

11836

n/a

" >>> dishes = {'eggs': 2, 'sausage': 1, 'bacon': 1, "

11837

n/a

"'spam': 500}\n"

11838

n/a

' >>> keys = dishes.keys()\n'

11839

n/a

' >>> values = dishes.values()\n'

11840

n/a

'\n'

11841

n/a

' >>> # iteration\n'

11842

n/a

' >>> n = 0\n'

11843

n/a

' >>> for val in values:\n'

11844

n/a

' ... n += val\n'

11845

n/a

' >>> print(n)\n'

11846

n/a

' 504\n'

11847

n/a

'\n'

11848

n/a

' >>> # keys and values are iterated over in the same '

11849

n/a

'order\n'

11850

n/a

' >>> list(keys)\n'

11851

n/a

" ['eggs', 'bacon', 'sausage', 'spam']\n"

11852

n/a

' >>> list(values)\n'

11853

n/a

' [2, 1, 1, 500]\n'

11854

n/a

'\n'

11855

n/a

' >>> # view objects are dynamic and reflect dict changes\n'

11856

n/a

" >>> del dishes['eggs']\n"

11857

n/a

" >>> del dishes['sausage']\n"

11858

n/a

' >>> list(keys)\n'

11859

n/a

" ['spam', 'bacon']\n"

11860

n/a

'\n'

11861

n/a

' >>> # set operations\n'

11862

n/a

" >>> keys & {'eggs', 'bacon', 'salad'}\n"

11863

n/a

" {'bacon'}\n"

11864

n/a

" >>> keys ^ {'sausage', 'juice'}\n"

11865

n/a

" {'juice', 'sausage', 'bacon', 'spam'}\n",

11866

n/a

'typesmethods': '\n'

11867

n/a

'Methods\n'

11868

n/a

'*******\n'

11869

n/a

'\n'

11870

n/a

'Methods are functions that are called using the attribute '

11871

n/a

'notation.\n'

11872

n/a

'There are two flavors: built-in methods (such as "append()" '

11873

n/a

'on lists)\n'

11874

n/a

'and class instance methods. Built-in methods are described '

11875

n/a

'with the\n'

11876

n/a

'types that support them.\n'

11877

n/a

'\n'

11878

n/a

'If you access a method (a function defined in a class '

11879

n/a

'namespace)\n'

11880

n/a

'through an instance, you get a special object: a *bound '

11881

n/a

'method* (also\n'

11882

n/a

'called *instance method*) object. When called, it will add '

11883

n/a

'the "self"\n'

11884

n/a

'argument to the argument list. Bound methods have two '

11885

n/a

'special read-\n'

11886

n/a

'only attributes: "m.__self__" is the object on which the '

11887

n/a

'method\n'

11888

n/a

'operates, and "m.__func__" is the function implementing the '

11889

n/a

'method.\n'

11890

n/a

'Calling "m(arg-1, arg-2, ..., arg-n)" is completely '

11891

n/a

'equivalent to\n'

11892

n/a

'calling "m.__func__(m.__self__, arg-1, arg-2, ..., arg-n)".\n'

11893

n/a

'\n'

11894

n/a

'Like function objects, bound method objects support getting '

11895

n/a

'arbitrary\n'

11896

n/a

'attributes. However, since method attributes are actually '

11897

n/a

'stored on\n'

11898

n/a

'the underlying function object ("meth.__func__"), setting '

11899

n/a

'method\n'

11900

n/a

'attributes on bound methods is disallowed. Attempting to '

11901

n/a

'set an\n'

11902

n/a

'attribute on a method results in an "AttributeError" being '

11903

n/a

'raised. In\n'

11904

n/a

'order to set a method attribute, you need to explicitly set '

11905

n/a

'it on the\n'

11906

n/a

'underlying function object:\n'

11907

n/a

'\n'

11908

n/a

' >>> class C:\n'

11909

n/a

' ... def method(self):\n'

11910

n/a

' ... pass\n'

11911

n/a

' ...\n'

11912

n/a

' >>> c = C()\n'

11913

n/a

" >>> c.method.whoami = 'my name is method' # can't set on "

11914

n/a

'the method\n'

11915

n/a

' Traceback (most recent call last):\n'

11916

n/a

' File "<stdin>", line 1, in <module>\n'

11917

n/a

" AttributeError: 'method' object has no attribute "

11918

n/a

"'whoami'\n"

11919

n/a

" >>> c.method.__func__.whoami = 'my name is method'\n"

11920

n/a

' >>> c.method.whoami\n'

11921

n/a

" 'my name is method'\n"

11922

n/a

'\n'

11923

n/a

'See The standard type hierarchy for more information.\n',

11924

n/a

'typesmodules': '\n'

11925

n/a

'Modules\n'

11926

n/a

'*******\n'

11927

n/a

'\n'

11928

n/a

'The only special operation on a module is attribute access: '

11929

n/a

'"m.name",\n'

11930

n/a

'where *m* is a module and *name* accesses a name defined in '

11931

n/a

"*m*'s\n"

11932

n/a

'symbol table. Module attributes can be assigned to. (Note '

11933

n/a

'that the\n'

11934

n/a

'"import" statement is not, strictly speaking, an operation '

11935

n/a

'on a module\n'

11936

n/a

'object; "import foo" does not require a module object named '

11937

n/a

'*foo* to\n'

11938

n/a

'exist, rather it requires an (external) *definition* for a '

11939

n/a

'module\n'

11940

n/a

'named *foo* somewhere.)\n'

11941

n/a

'\n'

11942

n/a

'A special attribute of every module is "__dict__". This is '

11943

n/a

'the\n'

11944

n/a

"dictionary containing the module's symbol table. Modifying "

11945

n/a

'this\n'

11946

n/a

"dictionary will actually change the module's symbol table, "

11947

n/a

'but direct\n'

11948

n/a

'assignment to the "__dict__" attribute is not possible (you '

11949

n/a

'can write\n'

11950

n/a

'"m.__dict__[\'a\'] = 1", which defines "m.a" to be "1", but '

11951

n/a

"you can't\n"

11952

n/a

'write "m.__dict__ = {}"). Modifying "__dict__" directly is '

11953

n/a

'not\n'

11954

n/a

'recommended.\n'

11955

n/a

'\n'

11956

n/a

'Modules built into the interpreter are written like this: '

11957

n/a

'"<module\n'

11958

n/a

'\'sys\' (built-in)>". If loaded from a file, they are '

11959

n/a

'written as\n'

11960

n/a

'"<module \'os\' from '

11961

n/a

'\'/usr/local/lib/pythonX.Y/os.pyc\'>".\n',

11962

n/a

'typesseq': '\n'

11963

n/a

'Sequence Types --- "list", "tuple", "range"\n'

11964

n/a

'*******************************************\n'

11965

n/a

'\n'

11966

n/a

'There are three basic sequence types: lists, tuples, and range\n'

11967

n/a

'objects. Additional sequence types tailored for processing of '

11968

n/a

'binary\n'

11969

n/a

'data and text strings are described in dedicated sections.\n'

11970

n/a

'\n'

11971

n/a

'\n'

11972

n/a

'Common Sequence Operations\n'

11973

n/a

'==========================\n'

11974

n/a

'\n'

11975

n/a

'The operations in the following table are supported by most '

11976

n/a

'sequence\n'

11977

n/a

'types, both mutable and immutable. The '

11978

n/a

'"collections.abc.Sequence" ABC\n'

11979

n/a

'is provided to make it easier to correctly implement these '

11980

n/a

'operations\n'

11981

n/a

'on custom sequence types.\n'

11982

n/a

'\n'

11983

n/a

'This table lists the sequence operations sorted in ascending '

11984

n/a

'priority.\n'

11985

n/a

'In the table, *s* and *t* are sequences of the same type, *n*, '

11986

n/a

'*i*,\n'

11987

n/a

'*j* and *k* are integers and *x* is an arbitrary object that '

11988

n/a

'meets any\n'

11989

n/a

'type and value restrictions imposed by *s*.\n'

11990

n/a

'\n'

11991

n/a

'The "in" and "not in" operations have the same priorities as '

11992

n/a

'the\n'

11993

n/a

'comparison operations. The "+" (concatenation) and "*" '

11994

n/a

'(repetition)\n'

11995

n/a

'operations have the same priority as the corresponding numeric\n'

11996

n/a

'operations.\n'

11997

n/a

'\n'

11998

n/a

'+----------------------------+----------------------------------+------------+\n'

11999

n/a

'| Operation | Result '

12000

n/a

'| Notes |\n'

12001

n/a

'+============================+==================================+============+\n'

12002

n/a

'| "x in s" | "True" if an item of *s* is '

12003

n/a

'| (1) |\n'

12004

n/a

'| | equal to *x*, else "False" '

12005

n/a

'| |\n'

12006

n/a

'+----------------------------+----------------------------------+------------+\n'

12007

n/a

'| "x not in s" | "False" if an item of *s* is '

12008

n/a

'| (1) |\n'

12009

n/a

'| | equal to *x*, else "True" '

12010

n/a

'| |\n'

12011

n/a

'+----------------------------+----------------------------------+------------+\n'

12012

n/a

'| "s + t" | the concatenation of *s* and *t* '

12013

n/a

'| (6)(7) |\n'

12014

n/a

'+----------------------------+----------------------------------+------------+\n'

12015

n/a

'| "s * n" or "n * s" | equivalent to adding *s* to '

12016

n/a

'| (2)(7) |\n'

12017

n/a

'| | itself *n* times '

12018

n/a

'| |\n'

12019

n/a

'+----------------------------+----------------------------------+------------+\n'

12020

n/a

'| "s[i]" | *i*th item of *s*, origin 0 '

12021

n/a

'| (3) |\n'

12022

n/a

'+----------------------------+----------------------------------+------------+\n'

12023

n/a

'| "s[i:j]" | slice of *s* from *i* to *j* '

12024

n/a

'| (3)(4) |\n'

12025

n/a

'+----------------------------+----------------------------------+------------+\n'

12026

n/a

'| "s[i:j:k]" | slice of *s* from *i* to *j* '

12027

n/a

'| (3)(5) |\n'

12028

n/a

'| | with step *k* '

12029

n/a

'| |\n'

12030

n/a

'+----------------------------+----------------------------------+------------+\n'

12031

n/a

'| "len(s)" | length of *s* '

12032

n/a

'| |\n'

12033

n/a

'+----------------------------+----------------------------------+------------+\n'

12034

n/a

'| "min(s)" | smallest item of *s* '

12035

n/a

'| |\n'

12036

n/a

'+----------------------------+----------------------------------+------------+\n'

12037

n/a

'| "max(s)" | largest item of *s* '

12038

n/a

'| |\n'

12039

n/a

'+----------------------------+----------------------------------+------------+\n'

12040

n/a

'| "s.index(x[, i[, j]])" | index of the first occurrence of '

12041

n/a

'| (8) |\n'

12042

n/a

'| | *x* in *s* (at or after index '

12043

n/a

'| |\n'

12044

n/a

'| | *i* and before index *j*) '

12045

n/a

'| |\n'

12046

n/a

'+----------------------------+----------------------------------+------------+\n'

12047

n/a

'| "s.count(x)" | total number of occurrences of '

12048

n/a

'| |\n'

12049

n/a

'| | *x* in *s* '

12050

n/a

'| |\n'

12051

n/a

'+----------------------------+----------------------------------+------------+\n'

12052

n/a

'\n'

12053

n/a

'Sequences of the same type also support comparisons. In '

12054

n/a

'particular,\n'

12055

n/a

'tuples and lists are compared lexicographically by comparing\n'

12056

n/a

'corresponding elements. This means that to compare equal, every\n'

12057

n/a

'element must compare equal and the two sequences must be of the '

12058

n/a

'same\n'

12059

n/a

'type and have the same length. (For full details see '

12060

n/a

'Comparisons in\n'

12061

n/a

'the language reference.)\n'

12062

n/a

'\n'

12063

n/a

'Notes:\n'

12064

n/a

'\n'

12065

n/a

'1. While the "in" and "not in" operations are used only for '

12066

n/a

'simple\n'

12067

n/a

' containment testing in the general case, some specialised '

12068

n/a

'sequences\n'

12069

n/a

' (such as "str", "bytes" and "bytearray") also use them for\n'

12070

n/a

' subsequence testing:\n'

12071

n/a

'\n'

12072

n/a

' >>> "gg" in "eggs"\n'

12073

n/a

' True\n'

12074

n/a

'\n'

12075

n/a

'2. Values of *n* less than "0" are treated as "0" (which yields '

12076

n/a

'an\n'

12077

n/a

' empty sequence of the same type as *s*). Note that items in '

12078

n/a

'the\n'

12079

n/a

' sequence *s* are not copied; they are referenced multiple '

12080

n/a

'times.\n'

12081

n/a

' This often haunts new Python programmers; consider:\n'

12082

n/a

'\n'

12083

n/a

' >>> lists = [[]] * 3\n'

12084

n/a

' >>> lists\n'

12085

n/a

' [[], [], []]\n'

12086

n/a

' >>> lists[0].append(3)\n'

12087

n/a

' >>> lists\n'

12088

n/a

' [[3], [3], [3]]\n'

12089

n/a

'\n'

12090

n/a

' What has happened is that "[[]]" is a one-element list '

12091

n/a

'containing\n'

12092

n/a

' an empty list, so all three elements of "[[]] * 3" are '

12093

n/a

'references\n'

12094

n/a

' to this single empty list. Modifying any of the elements of\n'

12095

n/a

' "lists" modifies this single list. You can create a list of\n'

12096

n/a

' different lists this way:\n'

12097

n/a

'\n'

12098

n/a

' >>> lists = [[] for i in range(3)]\n'

12099

n/a

' >>> lists[0].append(3)\n'

12100

n/a

' >>> lists[1].append(5)\n'

12101

n/a

' >>> lists[2].append(7)\n'

12102

n/a

' >>> lists\n'

12103

n/a

' [[3], [5], [7]]\n'

12104

n/a

'\n'

12105

n/a

' Further explanation is available in the FAQ entry How do I '

12106

n/a

'create a\n'

12107

n/a

' multidimensional list?.\n'

12108

n/a

'\n'

12109

n/a

'3. If *i* or *j* is negative, the index is relative to the end '

12110

n/a

'of\n'

12111

n/a

' the string: "len(s) + i" or "len(s) + j" is substituted. But '

12112

n/a

'note\n'

12113

n/a

' that "-0" is still "0".\n'

12114

n/a

'\n'

12115

n/a

'4. The slice of *s* from *i* to *j* is defined as the sequence '

12116

n/a

'of\n'

12117

n/a

' items with index *k* such that "i <= k < j". If *i* or *j* '

12118

n/a

'is\n'

12119

n/a

' greater than "len(s)", use "len(s)". If *i* is omitted or '

12120

n/a

'"None",\n'

12121

n/a

' use "0". If *j* is omitted or "None", use "len(s)". If *i* '

12122

n/a

'is\n'

12123

n/a

' greater than or equal to *j*, the slice is empty.\n'

12124

n/a

'\n'

12125

n/a

'5. The slice of *s* from *i* to *j* with step *k* is defined as '

12126

n/a

'the\n'

12127

n/a

' sequence of items with index "x = i + n*k" such that "0 <= n '

12128

n/a

'<\n'

12129

n/a

' (j-i)/k". In other words, the indices are "i", "i+k", '

12130

n/a

'"i+2*k",\n'

12131

n/a

' "i+3*k" and so on, stopping when *j* is reached (but never\n'

12132

n/a

' including *j*). If *i* or *j* is greater than "len(s)", use\n'

12133

n/a

' "len(s)". If *i* or *j* are omitted or "None", they become '

12134

n/a

'"end"\n'

12135

n/a

' values (which end depends on the sign of *k*). Note, *k* '

12136

n/a

'cannot be\n'

12137

n/a

' zero. If *k* is "None", it is treated like "1".\n'

12138

n/a

'\n'

12139

n/a

'6. Concatenating immutable sequences always results in a new\n'

12140

n/a

' object. This means that building up a sequence by repeated\n'

12141

n/a

' concatenation will have a quadratic runtime cost in the '

12142

n/a

'total\n'

12143

n/a

' sequence length. To get a linear runtime cost, you must '

12144

n/a

'switch to\n'

12145

n/a

' one of the alternatives below:\n'

12146

n/a

'\n'

12147

n/a

' * if concatenating "str" objects, you can build a list and '

12148

n/a

'use\n'

12149

n/a

' "str.join()" at the end or else write to an "io.StringIO"\n'

12150

n/a

' instance and retrieve its value when complete\n'

12151

n/a

'\n'

12152

n/a

' * if concatenating "bytes" objects, you can similarly use\n'

12153

n/a

' "bytes.join()" or "io.BytesIO", or you can do in-place\n'

12154

n/a

' concatenation with a "bytearray" object. "bytearray" '

12155

n/a

'objects are\n'

12156

n/a

' mutable and have an efficient overallocation mechanism\n'

12157

n/a

'\n'

12158

n/a

' * if concatenating "tuple" objects, extend a "list" instead\n'

12159

n/a

'\n'

12160

n/a

' * for other types, investigate the relevant class '

12161

n/a

'documentation\n'

12162

n/a

'\n'

12163

n/a

'7. Some sequence types (such as "range") only support item\n'

12164

n/a

" sequences that follow specific patterns, and hence don't "

12165

n/a

'support\n'

12166

n/a

' sequence concatenation or repetition.\n'

12167

n/a

'\n'

12168

n/a

'8. "index" raises "ValueError" when *x* is not found in *s*. '

12169

n/a

'When\n'

12170

n/a

' supported, the additional arguments to the index method '

12171

n/a

'allow\n'

12172

n/a

' efficient searching of subsections of the sequence. Passing '

12173

n/a

'the\n'

12174

n/a

' extra arguments is roughly equivalent to using '

12175

n/a

'"s[i:j].index(x)",\n'

12176

n/a

' only without copying any data and with the returned index '

12177

n/a

'being\n'

12178

n/a

' relative to the start of the sequence rather than the start '

12179

n/a

'of the\n'

12180

n/a

' slice.\n'

12181

n/a

'\n'

12182

n/a

'\n'

12183

n/a

'Immutable Sequence Types\n'

12184

n/a

'========================\n'

12185

n/a

'\n'

12186

n/a

'The only operation that immutable sequence types generally '

12187

n/a

'implement\n'

12188

n/a

'that is not also implemented by mutable sequence types is '

12189

n/a

'support for\n'

12190

n/a

'the "hash()" built-in.\n'

12191

n/a

'\n'

12192

n/a

'This support allows immutable sequences, such as "tuple" '

12193

n/a

'instances, to\n'

12194

n/a

'be used as "dict" keys and stored in "set" and "frozenset" '

12195

n/a

'instances.\n'

12196

n/a

'\n'

12197

n/a

'Attempting to hash an immutable sequence that contains '

12198

n/a

'unhashable\n'

12199

n/a

'values will result in "TypeError".\n'

12200

n/a

'\n'

12201

n/a

'\n'

12202

n/a

'Mutable Sequence Types\n'

12203

n/a

'======================\n'

12204

n/a

'\n'

12205

n/a

'The operations in the following table are defined on mutable '

12206

n/a

'sequence\n'

12207

n/a

'types. The "collections.abc.MutableSequence" ABC is provided to '

12208

n/a

'make\n'

12209

n/a

'it easier to correctly implement these operations on custom '

12210

n/a

'sequence\n'

12211

n/a

'types.\n'

12212

n/a

'\n'

12213

n/a

'In the table *s* is an instance of a mutable sequence type, *t* '

12214

n/a

'is any\n'

12215

n/a

'iterable object and *x* is an arbitrary object that meets any '

12216

n/a

'type and\n'

12217

n/a

'value restrictions imposed by *s* (for example, "bytearray" '

12218

n/a

'only\n'

12219

n/a

'accepts integers that meet the value restriction "0 <= x <= '

12220

n/a

'255").\n'

12221

n/a

'\n'

12222

n/a

'+--------------------------------+----------------------------------+-----------------------+\n'

12223

n/a

'| Operation | '

12224

n/a

'Result | Notes |\n'

12225

n/a

'+================================+==================================+=======================+\n'

12226

n/a

'| "s[i] = x" | item *i* of *s* is replaced '

12227

n/a

'by | |\n'

12228

n/a

'| | '

12229

n/a

'*x* | |\n'

12230

n/a

'+--------------------------------+----------------------------------+-----------------------+\n'

12231

n/a

'| "s[i:j] = t" | slice of *s* from *i* to *j* '

12232

n/a

'is | |\n'

12233

n/a

'| | replaced by the contents of '

12234

n/a

'the | |\n'

12235

n/a

'| | iterable '

12236

n/a

'*t* | |\n'

12237

n/a

'+--------------------------------+----------------------------------+-----------------------+\n'

12238

n/a

'| "del s[i:j]" | same as "s[i:j] = '

12239

n/a

'[]" | |\n'

12240

n/a

'+--------------------------------+----------------------------------+-----------------------+\n'

12241

n/a

'| "s[i:j:k] = t" | the elements of "s[i:j:k]" '

12242

n/a

'are | (1) |\n'

12243

n/a

'| | replaced by those of '

12244

n/a

'*t* | |\n'

12245

n/a

'+--------------------------------+----------------------------------+-----------------------+\n'

12246

n/a

'| "del s[i:j:k]" | removes the elements '

12247

n/a

'of | |\n'

12248

n/a

'| | "s[i:j:k]" from the '

12249

n/a

'list | |\n'

12250

n/a

'+--------------------------------+----------------------------------+-----------------------+\n'

12251

n/a

'| "s.append(x)" | appends *x* to the end of '

12252

n/a

'the | |\n'

12253

n/a

'| | sequence (same '

12254

n/a

'as | |\n'

12255

n/a

'| | "s[len(s):len(s)] = '

12256

n/a

'[x]") | |\n'

12257

n/a

'+--------------------------------+----------------------------------+-----------------------+\n'

12258

n/a

'| "s.clear()" | removes all items from "s" '

12259

n/a

'(same | (5) |\n'

12260

n/a

'| | as "del '

12261

n/a

's[:]") | |\n'

12262

n/a

'+--------------------------------+----------------------------------+-----------------------+\n'

12263

n/a

'| "s.copy()" | creates a shallow copy of '

12264

n/a

'"s" | (5) |\n'

12265

n/a

'| | (same as '

12266

n/a

'"s[:]") | |\n'

12267

n/a

'+--------------------------------+----------------------------------+-----------------------+\n'

12268

n/a

'| "s.extend(t)" or "s += t" | extends *s* with the contents '

12269

n/a

'of | |\n'

12270

n/a

'| | *t* (for the most part the '

12271

n/a

'same | |\n'

12272

n/a

'| | as "s[len(s):len(s)] = '

12273

n/a

't") | |\n'

12274

n/a

'+--------------------------------+----------------------------------+-----------------------+\n'

12275

n/a

'| "s *= n" | updates *s* with its '

12276

n/a

'contents | (6) |\n'

12277

n/a

'| | repeated *n* '

12278

n/a

'times | |\n'

12279

n/a

'+--------------------------------+----------------------------------+-----------------------+\n'

12280

n/a

'| "s.insert(i, x)" | inserts *x* into *s* at '

12281

n/a

'the | |\n'

12282

n/a

'| | index given by *i* (same '

12283

n/a

'as | |\n'

12284

n/a

'| | "s[i:i] = '

12285

n/a

'[x]") | |\n'

12286

n/a

'+--------------------------------+----------------------------------+-----------------------+\n'

12287

n/a

'| "s.pop([i])" | retrieves the item at *i* '

12288

n/a

'and | (2) |\n'

12289

n/a

'| | also removes it from '

12290

n/a

'*s* | |\n'

12291

n/a

'+--------------------------------+----------------------------------+-----------------------+\n'

12292

n/a

'| "s.remove(x)" | remove the first item from '

12293

n/a

'*s* | (3) |\n'

12294

n/a

'| | where "s[i] == '

12295

n/a

'x" | |\n'

12296

n/a

'+--------------------------------+----------------------------------+-----------------------+\n'

12297

n/a

'| "s.reverse()" | reverses the items of *s* '

12298

n/a

'in | (4) |\n'

12299

n/a

'| | '

12300

n/a

'place | |\n'

12301

n/a

'+--------------------------------+----------------------------------+-----------------------+\n'

12302

n/a

'\n'

12303

n/a

'Notes:\n'

12304

n/a

'\n'

12305

n/a

'1. *t* must have the same length as the slice it is replacing.\n'

12306

n/a

'\n'

12307

n/a

'2. The optional argument *i* defaults to "-1", so that by '

12308

n/a

'default\n'

12309

n/a

' the last item is removed and returned.\n'

12310

n/a

'\n'

12311

n/a

'3. "remove" raises "ValueError" when *x* is not found in *s*.\n'

12312

n/a

'\n'

12313

n/a

'4. The "reverse()" method modifies the sequence in place for\n'

12314

n/a

' economy of space when reversing a large sequence. To remind '

12315

n/a

'users\n'

12316

n/a

' that it operates by side effect, it does not return the '

12317

n/a

'reversed\n'

12318

n/a

' sequence.\n'

12319

n/a

'\n'

12320

n/a

'5. "clear()" and "copy()" are included for consistency with the\n'

12321

n/a

" interfaces of mutable containers that don't support slicing\n"

12322

n/a

' operations (such as "dict" and "set")\n'

12323

n/a

'\n'

12324

n/a

' New in version 3.3: "clear()" and "copy()" methods.\n'

12325

n/a

'\n'

12326

n/a

'6. The value *n* is an integer, or an object implementing\n'

12327

n/a

' "__index__()". Zero and negative values of *n* clear the '

12328

n/a

'sequence.\n'

12329

n/a

' Items in the sequence are not copied; they are referenced '

12330

n/a

'multiple\n'

12331

n/a

' times, as explained for "s * n" under Common Sequence '

12332

n/a

'Operations.\n'

12333

n/a

'\n'

12334

n/a

'\n'

12335

n/a

'Lists\n'

12336

n/a

'=====\n'

12337

n/a

'\n'

12338

n/a

'Lists are mutable sequences, typically used to store collections '

12339

n/a

'of\n'

12340

n/a

'homogeneous items (where the precise degree of similarity will '

12341

n/a

'vary by\n'

12342

n/a

'application).\n'

12343

n/a

'\n'

12344

n/a

'class list([iterable])\n'

12345

n/a

'\n'

12346

n/a

' Lists may be constructed in several ways:\n'

12347

n/a

'\n'

12348

n/a

' * Using a pair of square brackets to denote the empty list: '

12349

n/a

'"[]"\n'

12350

n/a

'\n'

12351

n/a

' * Using square brackets, separating items with commas: '

12352

n/a

'"[a]",\n'

12353

n/a

' "[a, b, c]"\n'

12354

n/a

'\n'

12355

n/a

' * Using a list comprehension: "[x for x in iterable]"\n'

12356

n/a

'\n'

12357

n/a

' * Using the type constructor: "list()" or "list(iterable)"\n'

12358

n/a

'\n'

12359

n/a

' The constructor builds a list whose items are the same and in '

12360

n/a

'the\n'

12361

n/a

" same order as *iterable*'s items. *iterable* may be either "

12362

n/a

'a\n'

12363

n/a

' sequence, a container that supports iteration, or an '

12364

n/a

'iterator\n'

12365

n/a

' object. If *iterable* is already a list, a copy is made and\n'

12366

n/a

' returned, similar to "iterable[:]". For example, '

12367

n/a

'"list(\'abc\')"\n'

12368

n/a

' returns "[\'a\', \'b\', \'c\']" and "list( (1, 2, 3) )" '

12369

n/a

'returns "[1, 2,\n'

12370

n/a

' 3]". If no argument is given, the constructor creates a new '

12371

n/a

'empty\n'

12372

n/a

' list, "[]".\n'

12373

n/a

'\n'

12374

n/a

' Many other operations also produce lists, including the '

12375

n/a

'"sorted()"\n'

12376

n/a

' built-in.\n'

12377

n/a

'\n'

12378

n/a

' Lists implement all of the common and mutable sequence '

12379

n/a

'operations.\n'

12380

n/a

' Lists also provide the following additional method:\n'

12381

n/a

'\n'

12382

n/a

' sort(*, key=None, reverse=None)\n'

12383

n/a

'\n'

12384

n/a

' This method sorts the list in place, using only "<" '

12385

n/a

'comparisons\n'

12386

n/a

' between items. Exceptions are not suppressed - if any '

12387

n/a

'comparison\n'

12388

n/a

' operations fail, the entire sort operation will fail (and '

12389

n/a

'the\n'

12390

n/a

' list will likely be left in a partially modified state).\n'

12391

n/a

'\n'

12392

n/a

' "sort()" accepts two arguments that can only be passed by\n'

12393

n/a

' keyword (keyword-only arguments):\n'

12394

n/a

'\n'

12395

n/a

' *key* specifies a function of one argument that is used '

12396

n/a

'to\n'

12397

n/a

' extract a comparison key from each list element (for '

12398

n/a

'example,\n'

12399

n/a

' "key=str.lower"). The key corresponding to each item in '

12400

n/a

'the list\n'

12401

n/a

' is calculated once and then used for the entire sorting '

12402

n/a

'process.\n'

12403

n/a

' The default value of "None" means that list items are '

12404

n/a

'sorted\n'

12405

n/a

' directly without calculating a separate key value.\n'

12406

n/a

'\n'

12407

n/a

' The "functools.cmp_to_key()" utility is available to '

12408

n/a

'convert a\n'

12409

n/a

' 2.x style *cmp* function to a *key* function.\n'

12410

n/a

'\n'

12411

n/a

' *reverse* is a boolean value. If set to "True", then the '

12412

n/a

'list\n'

12413

n/a

' elements are sorted as if each comparison were reversed.\n'

12414

n/a

'\n'

12415

n/a

' This method modifies the sequence in place for economy of '

12416

n/a

'space\n'

12417

n/a

' when sorting a large sequence. To remind users that it '

12418

n/a

'operates\n'

12419

n/a

' by side effect, it does not return the sorted sequence '

12420

n/a

'(use\n'

12421

n/a

' "sorted()" to explicitly request a new sorted list '

12422

n/a

'instance).\n'

12423

n/a

'\n'

12424

n/a

' The "sort()" method is guaranteed to be stable. A sort '

12425

n/a

'is\n'

12426

n/a

' stable if it guarantees not to change the relative order '

12427

n/a

'of\n'

12428

n/a

' elements that compare equal --- this is helpful for '

12429

n/a

'sorting in\n'

12430

n/a

' multiple passes (for example, sort by department, then by '

12431

n/a

'salary\n'

12432

n/a

' grade).\n'

12433

n/a

'\n'

12434

n/a

' **CPython implementation detail:** While a list is being '

12435

n/a

'sorted,\n'

12436

n/a

' the effect of attempting to mutate, or even inspect, the '

12437

n/a

'list is\n'

12438

n/a

' undefined. The C implementation of Python makes the list '

12439

n/a

'appear\n'

12440

n/a

' empty for the duration, and raises "ValueError" if it can '

12441

n/a

'detect\n'

12442

n/a

' that the list has been mutated during a sort.\n'

12443

n/a

'\n'

12444

n/a

'\n'

12445

n/a

'Tuples\n'

12446

n/a

'======\n'

12447

n/a

'\n'

12448

n/a

'Tuples are immutable sequences, typically used to store '

12449

n/a

'collections of\n'

12450

n/a

'heterogeneous data (such as the 2-tuples produced by the '

12451

n/a

'"enumerate()"\n'

12452

n/a

'built-in). Tuples are also used for cases where an immutable '

12453

n/a

'sequence\n'

12454

n/a

'of homogeneous data is needed (such as allowing storage in a '

12455

n/a

'"set" or\n'

12456

n/a

'"dict" instance).\n'

12457

n/a

'\n'

12458

n/a

'class tuple([iterable])\n'

12459

n/a

'\n'

12460

n/a

' Tuples may be constructed in a number of ways:\n'

12461

n/a

'\n'

12462

n/a

' * Using a pair of parentheses to denote the empty tuple: '

12463

n/a

'"()"\n'

12464

n/a

'\n'

12465

n/a

' * Using a trailing comma for a singleton tuple: "a," or '

12466

n/a

'"(a,)"\n'

12467

n/a

'\n'

12468

n/a

' * Separating items with commas: "a, b, c" or "(a, b, c)"\n'

12469

n/a

'\n'

12470

n/a

' * Using the "tuple()" built-in: "tuple()" or '

12471

n/a

'"tuple(iterable)"\n'

12472

n/a

'\n'

12473

n/a

' The constructor builds a tuple whose items are the same and '

12474

n/a

'in the\n'

12475

n/a

" same order as *iterable*'s items. *iterable* may be either "

12476

n/a

'a\n'

12477

n/a

' sequence, a container that supports iteration, or an '

12478

n/a

'iterator\n'

12479

n/a

' object. If *iterable* is already a tuple, it is returned\n'

12480

n/a

' unchanged. For example, "tuple(\'abc\')" returns "(\'a\', '

12481

n/a

'\'b\', \'c\')"\n'

12482

n/a

' and "tuple( [1, 2, 3] )" returns "(1, 2, 3)". If no argument '

12483

n/a

'is\n'

12484

n/a

' given, the constructor creates a new empty tuple, "()".\n'

12485

n/a

'\n'

12486

n/a

' Note that it is actually the comma which makes a tuple, not '

12487

n/a

'the\n'

12488

n/a

' parentheses. The parentheses are optional, except in the '

12489

n/a

'empty\n'

12490

n/a

' tuple case, or when they are needed to avoid syntactic '

12491

n/a

'ambiguity.\n'

12492

n/a

' For example, "f(a, b, c)" is a function call with three '

12493

n/a

'arguments,\n'

12494

n/a

' while "f((a, b, c))" is a function call with a 3-tuple as the '

12495

n/a

'sole\n'

12496

n/a

' argument.\n'

12497

n/a

'\n'

12498

n/a

' Tuples implement all of the common sequence operations.\n'

12499

n/a

'\n'

12500

n/a

'For heterogeneous collections of data where access by name is '

12501

n/a

'clearer\n'

12502

n/a

'than access by index, "collections.namedtuple()" may be a more\n'

12503

n/a

'appropriate choice than a simple tuple object.\n'

12504

n/a

'\n'

12505

n/a

'\n'

12506

n/a

'Ranges\n'

12507

n/a

'======\n'

12508

n/a

'\n'

12509

n/a

'The "range" type represents an immutable sequence of numbers and '

12510

n/a

'is\n'

12511

n/a

'commonly used for looping a specific number of times in "for" '

12512

n/a

'loops.\n'

12513

n/a

'\n'

12514

n/a

'class range(stop)\n'

12515

n/a

'class range(start, stop[, step])\n'

12516

n/a

'\n'

12517

n/a

' The arguments to the range constructor must be integers '

12518

n/a

'(either\n'

12519

n/a

' built-in "int" or any object that implements the "__index__"\n'

12520

n/a

' special method). If the *step* argument is omitted, it '

12521

n/a

'defaults to\n'

12522

n/a

' "1". If the *start* argument is omitted, it defaults to "0". '

12523

n/a

'If\n'

12524

n/a

' *step* is zero, "ValueError" is raised.\n'

12525

n/a

'\n'

12526

n/a

' For a positive *step*, the contents of a range "r" are '

12527

n/a

'determined\n'

12528

n/a

' by the formula "r[i] = start + step*i" where "i >= 0" and '

12529

n/a

'"r[i] <\n'

12530

n/a

' stop".\n'

12531

n/a

'\n'

12532

n/a

' For a negative *step*, the contents of the range are still\n'

12533

n/a

' determined by the formula "r[i] = start + step*i", but the\n'

12534

n/a

' constraints are "i >= 0" and "r[i] > stop".\n'

12535

n/a

'\n'

12536

n/a

' A range object will be empty if "r[0]" does not meet the '

12537

n/a

'value\n'

12538

n/a

' constraint. Ranges do support negative indices, but these '

12539

n/a

'are\n'

12540

n/a

' interpreted as indexing from the end of the sequence '

12541

n/a

'determined by\n'

12542

n/a

' the positive indices.\n'

12543

n/a

'\n'

12544

n/a

' Ranges containing absolute values larger than "sys.maxsize" '

12545

n/a

'are\n'

12546

n/a

' permitted but some features (such as "len()") may raise\n'

12547

n/a

' "OverflowError".\n'

12548

n/a

'\n'

12549

n/a

' Range examples:\n'

12550

n/a

'\n'

12551

n/a

' >>> list(range(10))\n'

12552

n/a

' [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]\n'

12553

n/a

' >>> list(range(1, 11))\n'

12554

n/a

' [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]\n'

12555

n/a

' >>> list(range(0, 30, 5))\n'

12556

n/a

' [0, 5, 10, 15, 20, 25]\n'

12557

n/a

' >>> list(range(0, 10, 3))\n'

12558

n/a

' [0, 3, 6, 9]\n'

12559

n/a

' >>> list(range(0, -10, -1))\n'

12560

n/a

' [0, -1, -2, -3, -4, -5, -6, -7, -8, -9]\n'

12561

n/a

' >>> list(range(0))\n'

12562

n/a

' []\n'

12563

n/a

' >>> list(range(1, 0))\n'

12564

n/a

' []\n'

12565

n/a

'\n'

12566

n/a

' Ranges implement all of the common sequence operations '

12567

n/a

'except\n'

12568

n/a

' concatenation and repetition (due to the fact that range '

12569

n/a

'objects\n'

12570

n/a

' can only represent sequences that follow a strict pattern '

12571

n/a

'and\n'

12572

n/a

' repetition and concatenation will usually violate that '

12573

n/a

'pattern).\n'

12574

n/a

'\n'

12575

n/a

' start\n'

12576

n/a

'\n'

12577

n/a

' The value of the *start* parameter (or "0" if the '

12578

n/a

'parameter was\n'

12579

n/a

' not supplied)\n'

12580

n/a

'\n'

12581

n/a

' stop\n'

12582

n/a

'\n'

12583

n/a

' The value of the *stop* parameter\n'

12584

n/a

'\n'

12585

n/a

' step\n'

12586

n/a

'\n'

12587

n/a

' The value of the *step* parameter (or "1" if the parameter '

12588

n/a

'was\n'

12589

n/a

' not supplied)\n'

12590

n/a

'\n'

12591

n/a

'The advantage of the "range" type over a regular "list" or '

12592

n/a

'"tuple" is\n'

12593

n/a

'that a "range" object will always take the same (small) amount '

12594

n/a

'of\n'

12595

n/a

'memory, no matter the size of the range it represents (as it '

12596

n/a

'only\n'

12597

n/a

'stores the "start", "stop" and "step" values, calculating '

12598

n/a

'individual\n'

12599

n/a

'items and subranges as needed).\n'

12600

n/a

'\n'

12601

n/a

'Range objects implement the "collections.abc.Sequence" ABC, and\n'

12602

n/a

'provide features such as containment tests, element index '

12603

n/a

'lookup,\n'

12604

n/a

'slicing and support for negative indices (see Sequence Types --- '

12605

n/a

'list,\n'

12606

n/a

'tuple, range):\n'

12607

n/a

'\n'

12608

n/a

'>>> r = range(0, 20, 2)\n'

12609

n/a

'>>> r\n'

12610

n/a

'range(0, 20, 2)\n'

12611

n/a

'>>> 11 in r\n'

12612

n/a

'False\n'

12613

n/a

'>>> 10 in r\n'

12614

n/a

'True\n'

12615

n/a

'>>> r.index(10)\n'

12616

n/a

'5\n'

12617

n/a

'>>> r[5]\n'

12618

n/a

'10\n'

12619

n/a

'>>> r[:5]\n'

12620

n/a

'range(0, 10, 2)\n'

12621

n/a

'>>> r[-1]\n'

12622

n/a

'18\n'

12623

n/a

'\n'

12624

n/a

'Testing range objects for equality with "==" and "!=" compares '

12625

n/a

'them as\n'

12626

n/a

'sequences. That is, two range objects are considered equal if '

12627

n/a

'they\n'

12628

n/a

'represent the same sequence of values. (Note that two range '

12629

n/a

'objects\n'

12630

n/a

'that compare equal might have different "start", "stop" and '

12631

n/a

'"step"\n'

12632

n/a

'attributes, for example "range(0) == range(2, 1, 3)" or '

12633

n/a

'"range(0, 3,\n'

12634

n/a

'2) == range(0, 4, 2)".)\n'

12635

n/a

'\n'

12636

n/a

'Changed in version 3.2: Implement the Sequence ABC. Support '

12637

n/a

'slicing\n'

12638

n/a

'and negative indices. Test "int" objects for membership in '

12639

n/a

'constant\n'

12640

n/a

'time instead of iterating through all items.\n'

12641

n/a

'\n'

12642

n/a

"Changed in version 3.3: Define '==' and '!=' to compare range "

12643

n/a

'objects\n'

12644

n/a

'based on the sequence of values they define (instead of '

12645

n/a

'comparing\n'

12646

n/a

'based on object identity).\n'

12647

n/a

'\n'

12648

n/a

'New in version 3.3: The "start", "stop" and "step" attributes.\n'

12649

n/a

'\n'

12650

n/a

'See also:\n'

12651

n/a

'\n'

12652

n/a

' * The linspace recipe shows how to implement a lazy version '

12653

n/a

'of\n'

12654

n/a

' range that suitable for floating point applications.\n',

12655

n/a

'typesseq-mutable': '\n'

12656

n/a

'Mutable Sequence Types\n'

12657

n/a

'**********************\n'

12658

n/a

'\n'

12659

n/a

'The operations in the following table are defined on '

12660

n/a

'mutable sequence\n'

12661

n/a

'types. The "collections.abc.MutableSequence" ABC is '

12662

n/a

'provided to make\n'

12663

n/a

'it easier to correctly implement these operations on '

12664

n/a

'custom sequence\n'

12665

n/a

'types.\n'

12666

n/a

'\n'

12667

n/a

'In the table *s* is an instance of a mutable sequence '

12668

n/a

'type, *t* is any\n'

12669

n/a

'iterable object and *x* is an arbitrary object that '

12670

n/a

'meets any type and\n'

12671

n/a

'value restrictions imposed by *s* (for example, '

12672

n/a

'"bytearray" only\n'

12673

n/a

'accepts integers that meet the value restriction "0 <= x '

12674

n/a

'<= 255").\n'

12675

n/a

'\n'

12676

n/a

'+--------------------------------+----------------------------------+-----------------------+\n'

12677

n/a

'| Operation | '

12678

n/a

'Result | Notes '

12679

n/a

'|\n'

12680

n/a

'+================================+==================================+=======================+\n'

12681

n/a

'| "s[i] = x" | item *i* of *s* is '

12682

n/a

'replaced by | |\n'

12683

n/a

'| | '

12684

n/a

'*x* | '

12685

n/a

'|\n'

12686

n/a

'+--------------------------------+----------------------------------+-----------------------+\n'

12687

n/a

'| "s[i:j] = t" | slice of *s* from *i* '

12688

n/a

'to *j* is | |\n'

12689

n/a

'| | replaced by the '

12690

n/a

'contents of the | |\n'

12691

n/a

'| | iterable '

12692

n/a

'*t* | |\n'

12693

n/a

'+--------------------------------+----------------------------------+-----------------------+\n'

12694

n/a

'| "del s[i:j]" | same as "s[i:j] = '

12695

n/a

'[]" | |\n'

12696

n/a

'+--------------------------------+----------------------------------+-----------------------+\n'

12697

n/a

'| "s[i:j:k] = t" | the elements of '

12698

n/a

'"s[i:j:k]" are | (1) |\n'

12699

n/a

'| | replaced by those of '

12700

n/a

'*t* | |\n'

12701

n/a

'+--------------------------------+----------------------------------+-----------------------+\n'

12702

n/a

'| "del s[i:j:k]" | removes the elements '

12703

n/a

'of | |\n'

12704

n/a

'| | "s[i:j:k]" from the '

12705

n/a

'list | |\n'

12706

n/a

'+--------------------------------+----------------------------------+-----------------------+\n'

12707

n/a

'| "s.append(x)" | appends *x* to the '

12708

n/a

'end of the | |\n'

12709

n/a

'| | sequence (same '

12710

n/a

'as | |\n'

12711

n/a

'| | "s[len(s):len(s)] = '

12712

n/a

'[x]") | |\n'

12713

n/a

'+--------------------------------+----------------------------------+-----------------------+\n'

12714

n/a

'| "s.clear()" | removes all items '

12715

n/a

'from "s" (same | (5) |\n'

12716

n/a

'| | as "del '

12717

n/a

's[:]") | |\n'

12718

n/a

'+--------------------------------+----------------------------------+-----------------------+\n'

12719

n/a

'| "s.copy()" | creates a shallow '

12720

n/a

'copy of "s" | (5) |\n'

12721

n/a

'| | (same as '

12722

n/a

'"s[:]") | |\n'

12723

n/a

'+--------------------------------+----------------------------------+-----------------------+\n'

12724

n/a

'| "s.extend(t)" or "s += t" | extends *s* with the '

12725

n/a

'contents of | |\n'

12726

n/a

'| | *t* (for the most '

12727

n/a

'part the same | |\n'

12728

n/a

'| | as "s[len(s):len(s)] '

12729

n/a

'= t") | |\n'

12730

n/a

'+--------------------------------+----------------------------------+-----------------------+\n'

12731

n/a

'| "s *= n" | updates *s* with its '

12732

n/a

'contents | (6) |\n'

12733

n/a

'| | repeated *n* '

12734

n/a

'times | |\n'

12735

n/a

'+--------------------------------+----------------------------------+-----------------------+\n'

12736

n/a

'| "s.insert(i, x)" | inserts *x* into *s* '

12737

n/a

'at the | |\n'

12738

n/a

'| | index given by *i* '

12739

n/a

'(same as | |\n'

12740

n/a

'| | "s[i:i] = '

12741

n/a

'[x]") | |\n'

12742

n/a

'+--------------------------------+----------------------------------+-----------------------+\n'

12743

n/a

'| "s.pop([i])" | retrieves the item at '

12744

n/a

'*i* and | (2) |\n'

12745

n/a

'| | also removes it from '

12746

n/a

'*s* | |\n'

12747

n/a

'+--------------------------------+----------------------------------+-----------------------+\n'

12748

n/a

'| "s.remove(x)" | remove the first item '

12749

n/a

'from *s* | (3) |\n'

12750

n/a

'| | where "s[i] == '

12751

n/a

'x" | |\n'

12752

n/a

'+--------------------------------+----------------------------------+-----------------------+\n'

12753

n/a

'| "s.reverse()" | reverses the items of '

12754

n/a

'*s* in | (4) |\n'

12755

n/a

'| | '

12756

n/a

'place | '

12757

n/a

'|\n'

12758

n/a

'+--------------------------------+----------------------------------+-----------------------+\n'

12759

n/a

'\n'

12760

n/a

'Notes:\n'

12761

n/a

'\n'

12762

n/a

'1. *t* must have the same length as the slice it is '

12763

n/a

'replacing.\n'

12764

n/a

'\n'

12765

n/a

'2. The optional argument *i* defaults to "-1", so that '

12766

n/a

'by default\n'

12767

n/a

' the last item is removed and returned.\n'

12768

n/a

'\n'

12769

n/a

'3. "remove" raises "ValueError" when *x* is not found in '

12770

n/a

'*s*.\n'

12771

n/a

'\n'

12772

n/a

'4. The "reverse()" method modifies the sequence in place '

12773

n/a

'for\n'

12774

n/a

' economy of space when reversing a large sequence. To '

12775

n/a

'remind users\n'

12776

n/a

' that it operates by side effect, it does not return '

12777

n/a

'the reversed\n'

12778

n/a

' sequence.\n'

12779

n/a

'\n'

12780

n/a

'5. "clear()" and "copy()" are included for consistency '

12781

n/a

'with the\n'

12782

n/a

" interfaces of mutable containers that don't support "

12783

n/a

'slicing\n'

12784

n/a

' operations (such as "dict" and "set")\n'

12785

n/a

'\n'

12786

n/a

' New in version 3.3: "clear()" and "copy()" methods.\n'

12787

n/a

'\n'

12788

n/a

'6. The value *n* is an integer, or an object '

12789

n/a

'implementing\n'

12790

n/a

' "__index__()". Zero and negative values of *n* clear '

12791

n/a

'the sequence.\n'

12792

n/a

' Items in the sequence are not copied; they are '

12793

n/a

'referenced multiple\n'

12794

n/a

' times, as explained for "s * n" under Common Sequence '

12795

n/a

'Operations.\n',

12796

n/a

'unary': '\n'

12797

n/a

'Unary arithmetic and bitwise operations\n'

12798

n/a

'***************************************\n'

12799

n/a

'\n'

12800

n/a

'All unary arithmetic and bitwise operations have the same '

12801

n/a

'priority:\n'

12802

n/a

'\n'

12803

n/a

' u_expr ::= power | "-" u_expr | "+" u_expr | "~" u_expr\n'

12804

n/a

'\n'

12805

n/a

'The unary "-" (minus) operator yields the negation of its numeric\n'

12806

n/a

'argument.\n'

12807

n/a

'\n'

12808

n/a

'The unary "+" (plus) operator yields its numeric argument '

12809

n/a

'unchanged.\n'

12810

n/a

'\n'

12811

n/a

'The unary "~" (invert) operator yields the bitwise inversion of '

12812

n/a

'its\n'

12813

n/a

'integer argument. The bitwise inversion of "x" is defined as\n'

12814

n/a

'"-(x+1)". It only applies to integral numbers.\n'

12815

n/a

'\n'

12816

n/a

'In all three cases, if the argument does not have the proper type, '

12817

n/a

'a\n'

12818

n/a

'"TypeError" exception is raised.\n',

12819

n/a

'while': '\n'

12820

n/a

'The "while" statement\n'

12821

n/a

'*********************\n'

12822

n/a

'\n'

12823

n/a

'The "while" statement is used for repeated execution as long as an\n'

12824

n/a

'expression is true:\n'

12825

n/a

'\n'

12826

n/a

' while_stmt ::= "while" expression ":" suite\n'

12827

n/a

' ["else" ":" suite]\n'

12828

n/a

'\n'

12829

n/a

'This repeatedly tests the expression and, if it is true, executes '

12830

n/a

'the\n'

12831

n/a

'first suite; if the expression is false (which may be the first '

12832

n/a

'time\n'

12833

n/a

'it is tested) the suite of the "else" clause, if present, is '

12834

n/a

'executed\n'

12835

n/a

'and the loop terminates.\n'

12836

n/a

'\n'

12837

n/a

'A "break" statement executed in the first suite terminates the '

12838

n/a

'loop\n'

12839

n/a

'without executing the "else" clause\'s suite. A "continue" '

12840

n/a

'statement\n'

12841

n/a

'executed in the first suite skips the rest of the suite and goes '

12842

n/a

'back\n'

12843

n/a

'to testing the expression.\n',

12844

n/a

'with': '\n'

12845

n/a

'The "with" statement\n'

12846

n/a

'********************\n'

12847

n/a

'\n'

12848

n/a

'The "with" statement is used to wrap the execution of a block with\n'

12849

n/a

'methods defined by a context manager (see section With Statement\n'

12850

n/a

'Context Managers). This allows common "try"..."except"..."finally"\n'

12851

n/a

'usage patterns to be encapsulated for convenient reuse.\n'

12852

n/a

'\n'

12853

n/a

' with_stmt ::= "with" with_item ("," with_item)* ":" suite\n'

12854

n/a

' with_item ::= expression ["as" target]\n'

12855

n/a

'\n'

12856

n/a

'The execution of the "with" statement with one "item" proceeds as\n'

12857

n/a

'follows:\n'

12858

n/a

'\n'

12859

n/a

'1. The context expression (the expression given in the "with_item")\n'

12860

n/a

' is evaluated to obtain a context manager.\n'

12861

n/a

'\n'

12862

n/a

'2. The context manager\'s "__exit__()" is loaded for later use.\n'

12863

n/a

'\n'

12864

n/a

'3. The context manager\'s "__enter__()" method is invoked.\n'

12865

n/a

'\n'

12866

n/a

'4. If a target was included in the "with" statement, the return\n'

12867

n/a

' value from "__enter__()" is assigned to it.\n'

12868

n/a

'\n'

12869

n/a

' Note: The "with" statement guarantees that if the "__enter__()"\n'

12870

n/a

' method returns without an error, then "__exit__()" will always '

12871

n/a

'be\n'

12872

n/a

' called. Thus, if an error occurs during the assignment to the\n'

12873

n/a

' target list, it will be treated the same as an error occurring\n'

12874

n/a

' within the suite would be. See step 6 below.\n'

12875

n/a

'\n'

12876

n/a

'5. The suite is executed.\n'

12877

n/a

'\n'

12878

n/a

'6. The context manager\'s "__exit__()" method is invoked. If an\n'

12879

n/a

' exception caused the suite to be exited, its type, value, and\n'

12880

n/a

' traceback are passed as arguments to "__exit__()". Otherwise, '

12881

n/a

'three\n'

12882

n/a

' "None" arguments are supplied.\n'

12883

n/a

'\n'

12884

n/a

' If the suite was exited due to an exception, and the return '

12885

n/a

'value\n'

12886

n/a

' from the "__exit__()" method was false, the exception is '

12887

n/a

'reraised.\n'

12888

n/a

' If the return value was true, the exception is suppressed, and\n'

12889

n/a

' execution continues with the statement following the "with"\n'

12890

n/a

' statement.\n'

12891

n/a

'\n'

12892

n/a

' If the suite was exited for any reason other than an exception, '

12893

n/a

'the\n'

12894

n/a

' return value from "__exit__()" is ignored, and execution '

12895

n/a

'proceeds\n'

12896

n/a

' at the normal location for the kind of exit that was taken.\n'

12897

n/a

'\n'

12898

n/a

'With more than one item, the context managers are processed as if\n'

12899

n/a

'multiple "with" statements were nested:\n'

12900

n/a

'\n'

12901

n/a

' with A() as a, B() as b:\n'

12902

n/a

' suite\n'

12903

n/a

'\n'

12904

n/a

'is equivalent to\n'

12905

n/a

'\n'

12906

n/a

' with A() as a:\n'

12907

n/a

' with B() as b:\n'

12908

n/a

' suite\n'

12909

n/a

'\n'

12910

n/a

'Changed in version 3.1: Support for multiple context expressions.\n'

12911

n/a

'\n'

12912

n/a

'See also:\n'

12913

n/a

'\n'

12914

n/a

' **PEP 343** - The "with" statement\n'

12915

n/a

' The specification, background, and examples for the Python '

12916

n/a

'"with"\n'

12917

n/a

' statement.\n',

12918

n/a

'yield': '\n'

12919

n/a

'The "yield" statement\n'

12920

n/a

'*********************\n'

12921

n/a

'\n'

12922

n/a

' yield_stmt ::= yield_expression\n'

12923

n/a

'\n'

12924

n/a

'A "yield" statement is semantically equivalent to a yield '

12925

n/a

'expression.\n'

12926

n/a

'The yield statement can be used to omit the parentheses that would\n'

12927

n/a

'otherwise be required in the equivalent yield expression '

12928

n/a

'statement.\n'

12929

n/a

'For example, the yield statements\n'

12930

n/a

'\n'

12931

n/a

' yield <expr>\n'

12932

n/a

' yield from <expr>\n'

12933

n/a

'\n'

12934

n/a

'are equivalent to the yield expression statements\n'

12935

n/a

'\n'

12936

n/a

' (yield <expr>)\n'

12937

n/a

' (yield from <expr>)\n'

12938

n/a

'\n'

12939

n/a

'Yield expressions and statements are only used when defining a\n'

12940

n/a

'*generator* function, and are only used in the body of the '

12941

n/a

'generator\n'

12942

n/a

'function. Using yield in a function definition is sufficient to '

12943

n/a

'cause\n'

12944

n/a

'that definition to create a generator function instead of a normal\n'

12945

n/a

'function.\n'

12946

n/a

'\n'

12947

n/a

'For full details of "yield" semantics, refer to the Yield '

12948

n/a

'expressions\n'

12949

n/a

'section.\n'}

Python code coverage for Lib/pydoc_data/topics.py