ยปCore Development>Code coverage>Lib/pydoc_data/topics.py

Python code coverage for Lib/pydoc_data/topics.py

#countcontent
1n/a# -*- coding: utf-8 -*-
2n/a# Autogenerated by Sphinx on Mon Sep 12 10:47:11 2016
3n/atopics = {'assert': '\n'
4n/a 'The "assert" statement\n'
5n/a '**********************\n'
6n/a '\n'
7n/a 'Assert statements are a convenient way to insert debugging '
8n/a 'assertions\n'
9n/a 'into a program:\n'
10n/a '\n'
11n/a ' assert_stmt ::= "assert" expression ["," expression]\n'
12n/a '\n'
13n/a 'The simple form, "assert expression", is equivalent to\n'
14n/a '\n'
15n/a ' if __debug__:\n'
16n/a ' if not expression: raise AssertionError\n'
17n/a '\n'
18n/a 'The extended form, "assert expression1, expression2", is '
19n/a 'equivalent to\n'
20n/a '\n'
21n/a ' if __debug__:\n'
22n/a ' if not expression1: raise AssertionError(expression2)\n'
23n/a '\n'
24n/a 'These equivalences assume that "__debug__" and "AssertionError" '
25n/a 'refer\n'
26n/a 'to the built-in variables with those names. In the current\n'
27n/a 'implementation, the built-in variable "__debug__" is "True" under\n'
28n/a 'normal circumstances, "False" when optimization is requested '
29n/a '(command\n'
30n/a 'line option -O). The current code generator emits no code for an\n'
31n/a 'assert statement when optimization is requested at compile time. '
32n/a 'Note\n'
33n/a 'that it is unnecessary to include the source code for the '
34n/a 'expression\n'
35n/a 'that failed in the error message; it will be displayed as part of '
36n/a 'the\n'
37n/a 'stack trace.\n'
38n/a '\n'
39n/a 'Assignments to "__debug__" are illegal. The value for the '
40n/a 'built-in\n'
41n/a 'variable is determined when the interpreter starts.\n',
42n/a 'assignment': '\n'
43n/a 'Assignment statements\n'
44n/a '*********************\n'
45n/a '\n'
46n/a 'Assignment statements are used to (re)bind names to values and '
47n/a 'to\n'
48n/a 'modify attributes or items of mutable objects:\n'
49n/a '\n'
50n/a ' assignment_stmt ::= (target_list "=")+ (starred_expression '
51n/a '| yield_expression)\n'
52n/a ' target_list ::= target ("," target)* [","]\n'
53n/a ' target ::= identifier\n'
54n/a ' | "(" [target_list] ")"\n'
55n/a ' | "[" [target_list] "]"\n'
56n/a ' | attributeref\n'
57n/a ' | subscription\n'
58n/a ' | slicing\n'
59n/a ' | "*" target\n'
60n/a '\n'
61n/a '(See section Primaries for the syntax definitions for '
62n/a '*attributeref*,\n'
63n/a '*subscription*, and *slicing*.)\n'
64n/a '\n'
65n/a 'An assignment statement evaluates the expression list '
66n/a '(remember that\n'
67n/a 'this can be a single expression or a comma-separated list, the '
68n/a 'latter\n'
69n/a 'yielding a tuple) and assigns the single resulting object to '
70n/a 'each of\n'
71n/a 'the target lists, from left to right.\n'
72n/a '\n'
73n/a 'Assignment is defined recursively depending on the form of the '
74n/a 'target\n'
75n/a '(list). When a target is part of a mutable object (an '
76n/a 'attribute\n'
77n/a 'reference, subscription or slicing), the mutable object must\n'
78n/a 'ultimately perform the assignment and decide about its '
79n/a 'validity, and\n'
80n/a 'may raise an exception if the assignment is unacceptable. The '
81n/a 'rules\n'
82n/a 'observed by various types and the exceptions raised are given '
83n/a 'with the\n'
84n/a 'definition of the object types (see section The standard type\n'
85n/a 'hierarchy).\n'
86n/a '\n'
87n/a 'Assignment of an object to a target list, optionally enclosed '
88n/a 'in\n'
89n/a 'parentheses or square brackets, is recursively defined as '
90n/a 'follows.\n'
91n/a '\n'
92n/a '* If the target list is empty: The object must also be an '
93n/a 'empty\n'
94n/a ' iterable.\n'
95n/a '\n'
96n/a '* If the target list is a single target in parentheses: The '
97n/a 'object\n'
98n/a ' is assigned to that target.\n'
99n/a '\n'
100n/a '* If the target list is a comma-separated list of targets, or '
101n/a 'a\n'
102n/a ' single target in square brackets: The object must be an '
103n/a 'iterable\n'
104n/a ' with the same number of items as there are targets in the '
105n/a 'target\n'
106n/a ' list, and the items are assigned, from left to right, to '
107n/a 'the\n'
108n/a ' corresponding targets.\n'
109n/a '\n'
110n/a ' * If the target list contains one target prefixed with an\n'
111n/a ' asterisk, called a "starred" target: The object must be '
112n/a 'an\n'
113n/a ' iterable with at least as many items as there are targets '
114n/a 'in the\n'
115n/a ' target list, minus one. The first items of the iterable '
116n/a 'are\n'
117n/a ' assigned, from left to right, to the targets before the '
118n/a 'starred\n'
119n/a ' target. The final items of the iterable are assigned to '
120n/a 'the\n'
121n/a ' targets after the starred target. A list of the remaining '
122n/a 'items\n'
123n/a ' in the iterable is then assigned to the starred target '
124n/a '(the list\n'
125n/a ' can be empty).\n'
126n/a '\n'
127n/a ' * Else: The object must be an iterable with the same number '
128n/a 'of\n'
129n/a ' items as there are targets in the target list, and the '
130n/a 'items are\n'
131n/a ' assigned, from left to right, to the corresponding '
132n/a 'targets.\n'
133n/a '\n'
134n/a 'Assignment of an object to a single target is recursively '
135n/a 'defined as\n'
136n/a 'follows.\n'
137n/a '\n'
138n/a '* If the target is an identifier (name):\n'
139n/a '\n'
140n/a ' * If the name does not occur in a "global" or "nonlocal" '
141n/a 'statement\n'
142n/a ' in the current code block: the name is bound to the object '
143n/a 'in the\n'
144n/a ' current local namespace.\n'
145n/a '\n'
146n/a ' * Otherwise: the name is bound to the object in the global\n'
147n/a ' namespace or the outer namespace determined by '
148n/a '"nonlocal",\n'
149n/a ' respectively.\n'
150n/a '\n'
151n/a ' The name is rebound if it was already bound. This may cause '
152n/a 'the\n'
153n/a ' reference count for the object previously bound to the name '
154n/a 'to reach\n'
155n/a ' zero, causing the object to be deallocated and its '
156n/a 'destructor (if it\n'
157n/a ' has one) to be called.\n'
158n/a '\n'
159n/a '* If the target is an attribute reference: The primary '
160n/a 'expression in\n'
161n/a ' the reference is evaluated. It should yield an object with\n'
162n/a ' assignable attributes; if this is not the case, "TypeError" '
163n/a 'is\n'
164n/a ' raised. That object is then asked to assign the assigned '
165n/a 'object to\n'
166n/a ' the given attribute; if it cannot perform the assignment, it '
167n/a 'raises\n'
168n/a ' an exception (usually but not necessarily '
169n/a '"AttributeError").\n'
170n/a '\n'
171n/a ' Note: If the object is a class instance and the attribute '
172n/a 'reference\n'
173n/a ' occurs on both sides of the assignment operator, the RHS '
174n/a 'expression,\n'
175n/a ' "a.x" can access either an instance attribute or (if no '
176n/a 'instance\n'
177n/a ' attribute exists) a class attribute. The LHS target "a.x" '
178n/a 'is always\n'
179n/a ' set as an instance attribute, creating it if necessary. '
180n/a 'Thus, the\n'
181n/a ' two occurrences of "a.x" do not necessarily refer to the '
182n/a 'same\n'
183n/a ' attribute: if the RHS expression refers to a class '
184n/a 'attribute, the\n'
185n/a ' LHS creates a new instance attribute as the target of the\n'
186n/a ' assignment:\n'
187n/a '\n'
188n/a ' class Cls:\n'
189n/a ' x = 3 # class variable\n'
190n/a ' inst = Cls()\n'
191n/a ' inst.x = inst.x + 1 # writes inst.x as 4 leaving Cls.x '
192n/a 'as 3\n'
193n/a '\n'
194n/a ' This description does not necessarily apply to descriptor\n'
195n/a ' attributes, such as properties created with "property()".\n'
196n/a '\n'
197n/a '* If the target is a subscription: The primary expression in '
198n/a 'the\n'
199n/a ' reference is evaluated. It should yield either a mutable '
200n/a 'sequence\n'
201n/a ' object (such as a list) or a mapping object (such as a '
202n/a 'dictionary).\n'
203n/a ' Next, the subscript expression is evaluated.\n'
204n/a '\n'
205n/a ' If the primary is a mutable sequence object (such as a '
206n/a 'list), the\n'
207n/a ' subscript must yield an integer. If it is negative, the '
208n/a "sequence's\n"
209n/a ' length is added to it. The resulting value must be a '
210n/a 'nonnegative\n'
211n/a " integer less than the sequence's length, and the sequence is "
212n/a 'asked\n'
213n/a ' to assign the assigned object to its item with that index. '
214n/a 'If the\n'
215n/a ' index is out of range, "IndexError" is raised (assignment to '
216n/a 'a\n'
217n/a ' subscripted sequence cannot add new items to a list).\n'
218n/a '\n'
219n/a ' If the primary is a mapping object (such as a dictionary), '
220n/a 'the\n'
221n/a " subscript must have a type compatible with the mapping's key "
222n/a 'type,\n'
223n/a ' and the mapping is then asked to create a key/datum pair '
224n/a 'which maps\n'
225n/a ' the subscript to the assigned object. This can either '
226n/a 'replace an\n'
227n/a ' existing key/value pair with the same key value, or insert a '
228n/a 'new\n'
229n/a ' key/value pair (if no key with the same value existed).\n'
230n/a '\n'
231n/a ' For user-defined objects, the "__setitem__()" method is '
232n/a 'called with\n'
233n/a ' appropriate arguments.\n'
234n/a '\n'
235n/a '* If the target is a slicing: The primary expression in the\n'
236n/a ' reference is evaluated. It should yield a mutable sequence '
237n/a 'object\n'
238n/a ' (such as a list). The assigned object should be a sequence '
239n/a 'object\n'
240n/a ' of the same type. Next, the lower and upper bound '
241n/a 'expressions are\n'
242n/a ' evaluated, insofar they are present; defaults are zero and '
243n/a 'the\n'
244n/a " sequence's length. The bounds should evaluate to integers. "
245n/a 'If\n'
246n/a " either bound is negative, the sequence's length is added to "
247n/a 'it. The\n'
248n/a ' resulting bounds are clipped to lie between zero and the '
249n/a "sequence's\n"
250n/a ' length, inclusive. Finally, the sequence object is asked to '
251n/a 'replace\n'
252n/a ' the slice with the items of the assigned sequence. The '
253n/a 'length of\n'
254n/a ' the slice may be different from the length of the assigned '
255n/a 'sequence,\n'
256n/a ' thus changing the length of the target sequence, if the '
257n/a 'target\n'
258n/a ' sequence allows it.\n'
259n/a '\n'
260n/a '**CPython implementation detail:** In the current '
261n/a 'implementation, the\n'
262n/a 'syntax for targets is taken to be the same as for expressions, '
263n/a 'and\n'
264n/a 'invalid syntax is rejected during the code generation phase, '
265n/a 'causing\n'
266n/a 'less detailed error messages.\n'
267n/a '\n'
268n/a 'Although the definition of assignment implies that overlaps '
269n/a 'between\n'
270n/a "the left-hand side and the right-hand side are 'simultaneous' "
271n/a '(for\n'
272n/a 'example "a, b = b, a" swaps two variables), overlaps *within* '
273n/a 'the\n'
274n/a 'collection of assigned-to variables occur left-to-right, '
275n/a 'sometimes\n'
276n/a 'resulting in confusion. For instance, the following program '
277n/a 'prints\n'
278n/a '"[0, 2]":\n'
279n/a '\n'
280n/a ' x = [0, 1]\n'
281n/a ' i = 0\n'
282n/a ' i, x[i] = 1, 2 # i is updated, then x[i] is '
283n/a 'updated\n'
284n/a ' print(x)\n'
285n/a '\n'
286n/a 'See also:\n'
287n/a '\n'
288n/a ' **PEP 3132** - Extended Iterable Unpacking\n'
289n/a ' The specification for the "*target" feature.\n'
290n/a '\n'
291n/a '\n'
292n/a 'Augmented assignment statements\n'
293n/a '===============================\n'
294n/a '\n'
295n/a 'Augmented assignment is the combination, in a single '
296n/a 'statement, of a\n'
297n/a 'binary operation and an assignment statement:\n'
298n/a '\n'
299n/a ' augmented_assignment_stmt ::= augtarget augop '
300n/a '(expression_list | yield_expression)\n'
301n/a ' augtarget ::= identifier | attributeref | '
302n/a 'subscription | slicing\n'
303n/a ' augop ::= "+=" | "-=" | "*=" | "@=" | '
304n/a '"/=" | "//=" | "%=" | "**="\n'
305n/a ' | ">>=" | "<<=" | "&=" | "^=" | "|="\n'
306n/a '\n'
307n/a '(See section Primaries for the syntax definitions of the last '
308n/a 'three\n'
309n/a 'symbols.)\n'
310n/a '\n'
311n/a 'An augmented assignment evaluates the target (which, unlike '
312n/a 'normal\n'
313n/a 'assignment statements, cannot be an unpacking) and the '
314n/a 'expression\n'
315n/a 'list, performs the binary operation specific to the type of '
316n/a 'assignment\n'
317n/a 'on the two operands, and assigns the result to the original '
318n/a 'target.\n'
319n/a 'The target is only evaluated once.\n'
320n/a '\n'
321n/a 'An augmented assignment expression like "x += 1" can be '
322n/a 'rewritten as\n'
323n/a '"x = x + 1" to achieve a similar, but not exactly equal '
324n/a 'effect. In the\n'
325n/a 'augmented version, "x" is only evaluated once. Also, when '
326n/a 'possible,\n'
327n/a 'the actual operation is performed *in-place*, meaning that '
328n/a 'rather than\n'
329n/a 'creating a new object and assigning that to the target, the '
330n/a 'old object\n'
331n/a 'is modified instead.\n'
332n/a '\n'
333n/a 'Unlike normal assignments, augmented assignments evaluate the '
334n/a 'left-\n'
335n/a 'hand side *before* evaluating the right-hand side. For '
336n/a 'example, "a[i]\n'
337n/a '+= f(x)" first looks-up "a[i]", then it evaluates "f(x)" and '
338n/a 'performs\n'
339n/a 'the addition, and lastly, it writes the result back to '
340n/a '"a[i]".\n'
341n/a '\n'
342n/a 'With the exception of assigning to tuples and multiple targets '
343n/a 'in a\n'
344n/a 'single statement, the assignment done by augmented assignment\n'
345n/a 'statements is handled the same way as normal assignments. '
346n/a 'Similarly,\n'
347n/a 'with the exception of the possible *in-place* behavior, the '
348n/a 'binary\n'
349n/a 'operation performed by augmented assignment is the same as the '
350n/a 'normal\n'
351n/a 'binary operations.\n'
352n/a '\n'
353n/a 'For targets which are attribute references, the same caveat '
354n/a 'about\n'
355n/a 'class and instance attributes applies as for regular '
356n/a 'assignments.\n'
357n/a '\n'
358n/a '\n'
359n/a 'Annotated assignment statements\n'
360n/a '===============================\n'
361n/a '\n'
362n/a 'Annotation assignment is the combination, in a single '
363n/a 'statement, of a\n'
364n/a 'variable or attribute annotation and an optional assignment '
365n/a 'statement:\n'
366n/a '\n'
367n/a ' annotated_assignment_stmt ::= augtarget ":" expression ["=" '
368n/a 'expression]\n'
369n/a '\n'
370n/a 'The difference from normal Assignment statements is that only '
371n/a 'single\n'
372n/a 'target and only single right hand side value is allowed.\n'
373n/a '\n'
374n/a 'For simple names as assignment targets, if in class or module '
375n/a 'scope,\n'
376n/a 'the annotations are evaluated and stored in a special class or '
377n/a 'module\n'
378n/a 'attribute "__annotations__" that is a dictionary mapping from '
379n/a 'variable\n'
380n/a 'names (mangled if private) to evaluated annotations. This '
381n/a 'attribute is\n'
382n/a 'writable and is automatically created at the start of class or '
383n/a 'module\n'
384n/a 'body execution, if annotations are found statically.\n'
385n/a '\n'
386n/a 'For expressions as assignment targets, the annotations are '
387n/a 'evaluated\n'
388n/a 'if in class or module scope, but not stored.\n'
389n/a '\n'
390n/a 'If a name is annotated in a function scope, then this name is '
391n/a 'local\n'
392n/a 'for that scope. Annotations are never evaluated and stored in '
393n/a 'function\n'
394n/a 'scopes.\n'
395n/a '\n'
396n/a 'If the right hand side is present, an annotated assignment '
397n/a 'performs\n'
398n/a 'the actual assignment before evaluating annotations (where\n'
399n/a 'applicable). If the right hand side is not present for an '
400n/a 'expression\n'
401n/a 'target, then the interpreter evaluates the target except for '
402n/a 'the last\n'
403n/a '"__setitem__()" or "__setattr__()" call.\n'
404n/a '\n'
405n/a 'See also: **PEP 526** - Variable and attribute annotation '
406n/a 'syntax\n'
407n/a ' **PEP 484** - Type hints\n',
408n/a 'atom-identifiers': '\n'
409n/a 'Identifiers (Names)\n'
410n/a '*******************\n'
411n/a '\n'
412n/a 'An identifier occurring as an atom is a name. See '
413n/a 'section Identifiers\n'
414n/a 'and keywords for lexical definition and section Naming '
415n/a 'and binding for\n'
416n/a 'documentation of naming and binding.\n'
417n/a '\n'
418n/a 'When the name is bound to an object, evaluation of the '
419n/a 'atom yields\n'
420n/a 'that object. When a name is not bound, an attempt to '
421n/a 'evaluate it\n'
422n/a 'raises a "NameError" exception.\n'
423n/a '\n'
424n/a '**Private name mangling:** When an identifier that '
425n/a 'textually occurs in\n'
426n/a 'a class definition begins with two or more underscore '
427n/a 'characters and\n'
428n/a 'does not end in two or more underscores, it is '
429n/a 'considered a *private\n'
430n/a 'name* of that class. Private names are transformed to a '
431n/a 'longer form\n'
432n/a 'before code is generated for them. The transformation '
433n/a 'inserts the\n'
434n/a 'class name, with leading underscores removed and a '
435n/a 'single underscore\n'
436n/a 'inserted, in front of the name. For example, the '
437n/a 'identifier "__spam"\n'
438n/a 'occurring in a class named "Ham" will be transformed to '
439n/a '"_Ham__spam".\n'
440n/a 'This transformation is independent of the syntactical '
441n/a 'context in which\n'
442n/a 'the identifier is used. If the transformed name is '
443n/a 'extremely long\n'
444n/a '(longer than 255 characters), implementation defined '
445n/a 'truncation may\n'
446n/a 'happen. If the class name consists only of underscores, '
447n/a 'no\n'
448n/a 'transformation is done.\n',
449n/a 'atom-literals': '\n'
450n/a 'Literals\n'
451n/a '********\n'
452n/a '\n'
453n/a 'Python supports string and bytes literals and various '
454n/a 'numeric\n'
455n/a 'literals:\n'
456n/a '\n'
457n/a ' literal ::= stringliteral | bytesliteral\n'
458n/a ' | integer | floatnumber | imagnumber\n'
459n/a '\n'
460n/a 'Evaluation of a literal yields an object of the given type '
461n/a '(string,\n'
462n/a 'bytes, integer, floating point number, complex number) with '
463n/a 'the given\n'
464n/a 'value. The value may be approximated in the case of '
465n/a 'floating point\n'
466n/a 'and imaginary (complex) literals. See section Literals for '
467n/a 'details.\n'
468n/a '\n'
469n/a 'All literals correspond to immutable data types, and hence '
470n/a 'the\n'
471n/a "object's identity is less important than its value. "
472n/a 'Multiple\n'
473n/a 'evaluations of literals with the same value (either the '
474n/a 'same\n'
475n/a 'occurrence in the program text or a different occurrence) '
476n/a 'may obtain\n'
477n/a 'the same object or a different object with the same '
478n/a 'value.\n',
479n/a 'attribute-access': '\n'
480n/a 'Customizing attribute access\n'
481n/a '****************************\n'
482n/a '\n'
483n/a 'The following methods can be defined to customize the '
484n/a 'meaning of\n'
485n/a 'attribute access (use of, assignment to, or deletion of '
486n/a '"x.name") for\n'
487n/a 'class instances.\n'
488n/a '\n'
489n/a 'object.__getattr__(self, name)\n'
490n/a '\n'
491n/a ' Called when an attribute lookup has not found the '
492n/a 'attribute in the\n'
493n/a ' usual places (i.e. it is not an instance attribute '
494n/a 'nor is it found\n'
495n/a ' in the class tree for "self"). "name" is the '
496n/a 'attribute name. This\n'
497n/a ' method should return the (computed) attribute value '
498n/a 'or raise an\n'
499n/a ' "AttributeError" exception.\n'
500n/a '\n'
501n/a ' Note that if the attribute is found through the '
502n/a 'normal mechanism,\n'
503n/a ' "__getattr__()" is not called. (This is an '
504n/a 'intentional asymmetry\n'
505n/a ' between "__getattr__()" and "__setattr__()".) This is '
506n/a 'done both for\n'
507n/a ' efficiency reasons and because otherwise '
508n/a '"__getattr__()" would have\n'
509n/a ' no way to access other attributes of the instance. '
510n/a 'Note that at\n'
511n/a ' least for instance variables, you can fake total '
512n/a 'control by not\n'
513n/a ' inserting any values in the instance attribute '
514n/a 'dictionary (but\n'
515n/a ' instead inserting them in another object). See the\n'
516n/a ' "__getattribute__()" method below for a way to '
517n/a 'actually get total\n'
518n/a ' control over attribute access.\n'
519n/a '\n'
520n/a 'object.__getattribute__(self, name)\n'
521n/a '\n'
522n/a ' Called unconditionally to implement attribute '
523n/a 'accesses for\n'
524n/a ' instances of the class. If the class also defines '
525n/a '"__getattr__()",\n'
526n/a ' the latter will not be called unless '
527n/a '"__getattribute__()" either\n'
528n/a ' calls it explicitly or raises an "AttributeError". '
529n/a 'This method\n'
530n/a ' should return the (computed) attribute value or raise '
531n/a 'an\n'
532n/a ' "AttributeError" exception. In order to avoid '
533n/a 'infinite recursion in\n'
534n/a ' this method, its implementation should always call '
535n/a 'the base class\n'
536n/a ' method with the same name to access any attributes it '
537n/a 'needs, for\n'
538n/a ' example, "object.__getattribute__(self, name)".\n'
539n/a '\n'
540n/a ' Note: This method may still be bypassed when looking '
541n/a 'up special\n'
542n/a ' methods as the result of implicit invocation via '
543n/a 'language syntax\n'
544n/a ' or built-in functions. See Special method lookup.\n'
545n/a '\n'
546n/a 'object.__setattr__(self, name, value)\n'
547n/a '\n'
548n/a ' Called when an attribute assignment is attempted. '
549n/a 'This is called\n'
550n/a ' instead of the normal mechanism (i.e. store the value '
551n/a 'in the\n'
552n/a ' instance dictionary). *name* is the attribute name, '
553n/a '*value* is the\n'
554n/a ' value to be assigned to it.\n'
555n/a '\n'
556n/a ' If "__setattr__()" wants to assign to an instance '
557n/a 'attribute, it\n'
558n/a ' should call the base class method with the same name, '
559n/a 'for example,\n'
560n/a ' "object.__setattr__(self, name, value)".\n'
561n/a '\n'
562n/a 'object.__delattr__(self, name)\n'
563n/a '\n'
564n/a ' Like "__setattr__()" but for attribute deletion '
565n/a 'instead of\n'
566n/a ' assignment. This should only be implemented if "del '
567n/a 'obj.name" is\n'
568n/a ' meaningful for the object.\n'
569n/a '\n'
570n/a 'object.__dir__(self)\n'
571n/a '\n'
572n/a ' Called when "dir()" is called on the object. A '
573n/a 'sequence must be\n'
574n/a ' returned. "dir()" converts the returned sequence to a '
575n/a 'list and\n'
576n/a ' sorts it.\n'
577n/a '\n'
578n/a '\n'
579n/a 'Implementing Descriptors\n'
580n/a '========================\n'
581n/a '\n'
582n/a 'The following methods only apply when an instance of the '
583n/a 'class\n'
584n/a 'containing the method (a so-called *descriptor* class) '
585n/a 'appears in an\n'
586n/a '*owner* class (the descriptor must be in either the '
587n/a "owner's class\n"
588n/a 'dictionary or in the class dictionary for one of its '
589n/a 'parents). In the\n'
590n/a 'examples below, "the attribute" refers to the attribute '
591n/a 'whose name is\n'
592n/a "the key of the property in the owner class' "
593n/a '"__dict__".\n'
594n/a '\n'
595n/a 'object.__get__(self, instance, owner)\n'
596n/a '\n'
597n/a ' Called to get the attribute of the owner class (class '
598n/a 'attribute\n'
599n/a ' access) or of an instance of that class (instance '
600n/a 'attribute\n'
601n/a ' access). *owner* is always the owner class, while '
602n/a '*instance* is the\n'
603n/a ' instance that the attribute was accessed through, or '
604n/a '"None" when\n'
605n/a ' the attribute is accessed through the *owner*. This '
606n/a 'method should\n'
607n/a ' return the (computed) attribute value or raise an '
608n/a '"AttributeError"\n'
609n/a ' exception.\n'
610n/a '\n'
611n/a 'object.__set__(self, instance, value)\n'
612n/a '\n'
613n/a ' Called to set the attribute on an instance *instance* '
614n/a 'of the owner\n'
615n/a ' class to a new value, *value*.\n'
616n/a '\n'
617n/a 'object.__delete__(self, instance)\n'
618n/a '\n'
619n/a ' Called to delete the attribute on an instance '
620n/a '*instance* of the\n'
621n/a ' owner class.\n'
622n/a '\n'
623n/a 'object.__set_name__(self, owner, name)\n'
624n/a '\n'
625n/a ' Called at the time the owning class *owner* is '
626n/a 'created. The\n'
627n/a ' descriptor has been assigned to *name*.\n'
628n/a '\n'
629n/a ' New in version 3.6.\n'
630n/a '\n'
631n/a 'The attribute "__objclass__" is interpreted by the '
632n/a '"inspect" module as\n'
633n/a 'specifying the class where this object was defined '
634n/a '(setting this\n'
635n/a 'appropriately can assist in runtime introspection of '
636n/a 'dynamic class\n'
637n/a 'attributes). For callables, it may indicate that an '
638n/a 'instance of the\n'
639n/a 'given type (or a subclass) is expected or required as '
640n/a 'the first\n'
641n/a 'positional argument (for example, CPython sets this '
642n/a 'attribute for\n'
643n/a 'unbound methods that are implemented in C).\n'
644n/a '\n'
645n/a '\n'
646n/a 'Invoking Descriptors\n'
647n/a '====================\n'
648n/a '\n'
649n/a 'In general, a descriptor is an object attribute with '
650n/a '"binding\n'
651n/a 'behavior", one whose attribute access has been '
652n/a 'overridden by methods\n'
653n/a 'in the descriptor protocol: "__get__()", "__set__()", '
654n/a 'and\n'
655n/a '"__delete__()". If any of those methods are defined for '
656n/a 'an object, it\n'
657n/a 'is said to be a descriptor.\n'
658n/a '\n'
659n/a 'The default behavior for attribute access is to get, '
660n/a 'set, or delete\n'
661n/a "the attribute from an object's dictionary. For instance, "
662n/a '"a.x" has a\n'
663n/a 'lookup chain starting with "a.__dict__[\'x\']", then\n'
664n/a '"type(a).__dict__[\'x\']", and continuing through the '
665n/a 'base classes of\n'
666n/a '"type(a)" excluding metaclasses.\n'
667n/a '\n'
668n/a 'However, if the looked-up value is an object defining '
669n/a 'one of the\n'
670n/a 'descriptor methods, then Python may override the default '
671n/a 'behavior and\n'
672n/a 'invoke the descriptor method instead. Where this occurs '
673n/a 'in the\n'
674n/a 'precedence chain depends on which descriptor methods '
675n/a 'were defined and\n'
676n/a 'how they were called.\n'
677n/a '\n'
678n/a 'The starting point for descriptor invocation is a '
679n/a 'binding, "a.x". How\n'
680n/a 'the arguments are assembled depends on "a":\n'
681n/a '\n'
682n/a 'Direct Call\n'
683n/a ' The simplest and least common call is when user code '
684n/a 'directly\n'
685n/a ' invokes a descriptor method: "x.__get__(a)".\n'
686n/a '\n'
687n/a 'Instance Binding\n'
688n/a ' If binding to an object instance, "a.x" is '
689n/a 'transformed into the\n'
690n/a ' call: "type(a).__dict__[\'x\'].__get__(a, type(a))".\n'
691n/a '\n'
692n/a 'Class Binding\n'
693n/a ' If binding to a class, "A.x" is transformed into the '
694n/a 'call:\n'
695n/a ' "A.__dict__[\'x\'].__get__(None, A)".\n'
696n/a '\n'
697n/a 'Super Binding\n'
698n/a ' If "a" is an instance of "super", then the binding '
699n/a '"super(B,\n'
700n/a ' obj).m()" searches "obj.__class__.__mro__" for the '
701n/a 'base class "A"\n'
702n/a ' immediately preceding "B" and then invokes the '
703n/a 'descriptor with the\n'
704n/a ' call: "A.__dict__[\'m\'].__get__(obj, '
705n/a 'obj.__class__)".\n'
706n/a '\n'
707n/a 'For instance bindings, the precedence of descriptor '
708n/a 'invocation depends\n'
709n/a 'on the which descriptor methods are defined. A '
710n/a 'descriptor can define\n'
711n/a 'any combination of "__get__()", "__set__()" and '
712n/a '"__delete__()". If it\n'
713n/a 'does not define "__get__()", then accessing the '
714n/a 'attribute will return\n'
715n/a 'the descriptor object itself unless there is a value in '
716n/a "the object's\n"
717n/a 'instance dictionary. If the descriptor defines '
718n/a '"__set__()" and/or\n'
719n/a '"__delete__()", it is a data descriptor; if it defines '
720n/a 'neither, it is\n'
721n/a 'a non-data descriptor. Normally, data descriptors '
722n/a 'define both\n'
723n/a '"__get__()" and "__set__()", while non-data descriptors '
724n/a 'have just the\n'
725n/a '"__get__()" method. Data descriptors with "__set__()" '
726n/a 'and "__get__()"\n'
727n/a 'defined always override a redefinition in an instance '
728n/a 'dictionary. In\n'
729n/a 'contrast, non-data descriptors can be overridden by '
730n/a 'instances.\n'
731n/a '\n'
732n/a 'Python methods (including "staticmethod()" and '
733n/a '"classmethod()") are\n'
734n/a 'implemented as non-data descriptors. Accordingly, '
735n/a 'instances can\n'
736n/a 'redefine and override methods. This allows individual '
737n/a 'instances to\n'
738n/a 'acquire behaviors that differ from other instances of '
739n/a 'the same class.\n'
740n/a '\n'
741n/a 'The "property()" function is implemented as a data '
742n/a 'descriptor.\n'
743n/a 'Accordingly, instances cannot override the behavior of a '
744n/a 'property.\n'
745n/a '\n'
746n/a '\n'
747n/a '__slots__\n'
748n/a '=========\n'
749n/a '\n'
750n/a 'By default, instances of classes have a dictionary for '
751n/a 'attribute\n'
752n/a 'storage. This wastes space for objects having very few '
753n/a 'instance\n'
754n/a 'variables. The space consumption can become acute when '
755n/a 'creating large\n'
756n/a 'numbers of instances.\n'
757n/a '\n'
758n/a 'The default can be overridden by defining *__slots__* in '
759n/a 'a class\n'
760n/a 'definition. The *__slots__* declaration takes a sequence '
761n/a 'of instance\n'
762n/a 'variables and reserves just enough space in each '
763n/a 'instance to hold a\n'
764n/a 'value for each variable. Space is saved because '
765n/a '*__dict__* is not\n'
766n/a 'created for each instance.\n'
767n/a '\n'
768n/a 'object.__slots__\n'
769n/a '\n'
770n/a ' This class variable can be assigned a string, '
771n/a 'iterable, or sequence\n'
772n/a ' of strings with variable names used by instances. '
773n/a '*__slots__*\n'
774n/a ' reserves space for the declared variables and '
775n/a 'prevents the\n'
776n/a ' automatic creation of *__dict__* and *__weakref__* '
777n/a 'for each\n'
778n/a ' instance.\n'
779n/a '\n'
780n/a '\n'
781n/a 'Notes on using *__slots__*\n'
782n/a '--------------------------\n'
783n/a '\n'
784n/a '* When inheriting from a class without *__slots__*, the '
785n/a '*__dict__*\n'
786n/a ' attribute of that class will always be accessible, so '
787n/a 'a *__slots__*\n'
788n/a ' definition in the subclass is meaningless.\n'
789n/a '\n'
790n/a '* Without a *__dict__* variable, instances cannot be '
791n/a 'assigned new\n'
792n/a ' variables not listed in the *__slots__* definition. '
793n/a 'Attempts to\n'
794n/a ' assign to an unlisted variable name raises '
795n/a '"AttributeError". If\n'
796n/a ' dynamic assignment of new variables is desired, then '
797n/a 'add\n'
798n/a ' "\'__dict__\'" to the sequence of strings in the '
799n/a '*__slots__*\n'
800n/a ' declaration.\n'
801n/a '\n'
802n/a '* Without a *__weakref__* variable for each instance, '
803n/a 'classes\n'
804n/a ' defining *__slots__* do not support weak references to '
805n/a 'its\n'
806n/a ' instances. If weak reference support is needed, then '
807n/a 'add\n'
808n/a ' "\'__weakref__\'" to the sequence of strings in the '
809n/a '*__slots__*\n'
810n/a ' declaration.\n'
811n/a '\n'
812n/a '* *__slots__* are implemented at the class level by '
813n/a 'creating\n'
814n/a ' descriptors (Implementing Descriptors) for each '
815n/a 'variable name. As a\n'
816n/a ' result, class attributes cannot be used to set default '
817n/a 'values for\n'
818n/a ' instance variables defined by *__slots__*; otherwise, '
819n/a 'the class\n'
820n/a ' attribute would overwrite the descriptor assignment.\n'
821n/a '\n'
822n/a '* The action of a *__slots__* declaration is limited to '
823n/a 'the class\n'
824n/a ' where it is defined. As a result, subclasses will '
825n/a 'have a *__dict__*\n'
826n/a ' unless they also define *__slots__* (which must only '
827n/a 'contain names\n'
828n/a ' of any *additional* slots).\n'
829n/a '\n'
830n/a '* If a class defines a slot also defined in a base '
831n/a 'class, the\n'
832n/a ' instance variable defined by the base class slot is '
833n/a 'inaccessible\n'
834n/a ' (except by retrieving its descriptor directly from the '
835n/a 'base class).\n'
836n/a ' This renders the meaning of the program undefined. In '
837n/a 'the future, a\n'
838n/a ' check may be added to prevent this.\n'
839n/a '\n'
840n/a '* Nonempty *__slots__* does not work for classes derived '
841n/a 'from\n'
842n/a ' "variable-length" built-in types such as "int", '
843n/a '"bytes" and "tuple".\n'
844n/a '\n'
845n/a '* Any non-string iterable may be assigned to '
846n/a '*__slots__*. Mappings\n'
847n/a ' may also be used; however, in the future, special '
848n/a 'meaning may be\n'
849n/a ' assigned to the values corresponding to each key.\n'
850n/a '\n'
851n/a '* *__class__* assignment works only if both classes have '
852n/a 'the same\n'
853n/a ' *__slots__*.\n',
854n/a 'attribute-references': '\n'
855n/a 'Attribute references\n'
856n/a '********************\n'
857n/a '\n'
858n/a 'An attribute reference is a primary followed by a '
859n/a 'period and a name:\n'
860n/a '\n'
861n/a ' attributeref ::= primary "." identifier\n'
862n/a '\n'
863n/a 'The primary must evaluate to an object of a type '
864n/a 'that supports\n'
865n/a 'attribute references, which most objects do. This '
866n/a 'object is then\n'
867n/a 'asked to produce the attribute whose name is the '
868n/a 'identifier. This\n'
869n/a 'production can be customized by overriding the '
870n/a '"__getattr__()" method.\n'
871n/a 'If this attribute is not available, the exception '
872n/a '"AttributeError" is\n'
873n/a 'raised. Otherwise, the type and value of the object '
874n/a 'produced is\n'
875n/a 'determined by the object. Multiple evaluations of '
876n/a 'the same attribute\n'
877n/a 'reference may yield different objects.\n',
878n/a 'augassign': '\n'
879n/a 'Augmented assignment statements\n'
880n/a '*******************************\n'
881n/a '\n'
882n/a 'Augmented assignment is the combination, in a single statement, '
883n/a 'of a\n'
884n/a 'binary operation and an assignment statement:\n'
885n/a '\n'
886n/a ' augmented_assignment_stmt ::= augtarget augop '
887n/a '(expression_list | yield_expression)\n'
888n/a ' augtarget ::= identifier | attributeref | '
889n/a 'subscription | slicing\n'
890n/a ' augop ::= "+=" | "-=" | "*=" | "@=" | '
891n/a '"/=" | "//=" | "%=" | "**="\n'
892n/a ' | ">>=" | "<<=" | "&=" | "^=" | "|="\n'
893n/a '\n'
894n/a '(See section Primaries for the syntax definitions of the last '
895n/a 'three\n'
896n/a 'symbols.)\n'
897n/a '\n'
898n/a 'An augmented assignment evaluates the target (which, unlike '
899n/a 'normal\n'
900n/a 'assignment statements, cannot be an unpacking) and the '
901n/a 'expression\n'
902n/a 'list, performs the binary operation specific to the type of '
903n/a 'assignment\n'
904n/a 'on the two operands, and assigns the result to the original '
905n/a 'target.\n'
906n/a 'The target is only evaluated once.\n'
907n/a '\n'
908n/a 'An augmented assignment expression like "x += 1" can be '
909n/a 'rewritten as\n'
910n/a '"x = x + 1" to achieve a similar, but not exactly equal effect. '
911n/a 'In the\n'
912n/a 'augmented version, "x" is only evaluated once. Also, when '
913n/a 'possible,\n'
914n/a 'the actual operation is performed *in-place*, meaning that '
915n/a 'rather than\n'
916n/a 'creating a new object and assigning that to the target, the old '
917n/a 'object\n'
918n/a 'is modified instead.\n'
919n/a '\n'
920n/a 'Unlike normal assignments, augmented assignments evaluate the '
921n/a 'left-\n'
922n/a 'hand side *before* evaluating the right-hand side. For '
923n/a 'example, "a[i]\n'
924n/a '+= f(x)" first looks-up "a[i]", then it evaluates "f(x)" and '
925n/a 'performs\n'
926n/a 'the addition, and lastly, it writes the result back to "a[i]".\n'
927n/a '\n'
928n/a 'With the exception of assigning to tuples and multiple targets '
929n/a 'in a\n'
930n/a 'single statement, the assignment done by augmented assignment\n'
931n/a 'statements is handled the same way as normal assignments. '
932n/a 'Similarly,\n'
933n/a 'with the exception of the possible *in-place* behavior, the '
934n/a 'binary\n'
935n/a 'operation performed by augmented assignment is the same as the '
936n/a 'normal\n'
937n/a 'binary operations.\n'
938n/a '\n'
939n/a 'For targets which are attribute references, the same caveat '
940n/a 'about\n'
941n/a 'class and instance attributes applies as for regular '
942n/a 'assignments.\n',
943n/a 'binary': '\n'
944n/a 'Binary arithmetic operations\n'
945n/a '****************************\n'
946n/a '\n'
947n/a 'The binary arithmetic operations have the conventional priority\n'
948n/a 'levels. Note that some of these operations also apply to certain '
949n/a 'non-\n'
950n/a 'numeric types. Apart from the power operator, there are only two\n'
951n/a 'levels, one for multiplicative operators and one for additive\n'
952n/a 'operators:\n'
953n/a '\n'
954n/a ' m_expr ::= u_expr | m_expr "*" u_expr | m_expr "@" m_expr |\n'
955n/a ' m_expr "//" u_expr| m_expr "/" u_expr |\n'
956n/a ' m_expr "%" u_expr\n'
957n/a ' a_expr ::= m_expr | a_expr "+" m_expr | a_expr "-" m_expr\n'
958n/a '\n'
959n/a 'The "*" (multiplication) operator yields the product of its '
960n/a 'arguments.\n'
961n/a 'The arguments must either both be numbers, or one argument must be '
962n/a 'an\n'
963n/a 'integer and the other must be a sequence. In the former case, the\n'
964n/a 'numbers are converted to a common type and then multiplied '
965n/a 'together.\n'
966n/a 'In the latter case, sequence repetition is performed; a negative\n'
967n/a 'repetition factor yields an empty sequence.\n'
968n/a '\n'
969n/a 'The "@" (at) operator is intended to be used for matrix\n'
970n/a 'multiplication. No builtin Python types implement this operator.\n'
971n/a '\n'
972n/a 'New in version 3.5.\n'
973n/a '\n'
974n/a 'The "/" (division) and "//" (floor division) operators yield the\n'
975n/a 'quotient of their arguments. The numeric arguments are first\n'
976n/a 'converted to a common type. Division of integers yields a float, '
977n/a 'while\n'
978n/a 'floor division of integers results in an integer; the result is '
979n/a 'that\n'
980n/a "of mathematical division with the 'floor' function applied to the\n"
981n/a 'result. Division by zero raises the "ZeroDivisionError" '
982n/a 'exception.\n'
983n/a '\n'
984n/a 'The "%" (modulo) operator yields the remainder from the division '
985n/a 'of\n'
986n/a 'the first argument by the second. The numeric arguments are '
987n/a 'first\n'
988n/a 'converted to a common type. A zero right argument raises the\n'
989n/a '"ZeroDivisionError" exception. The arguments may be floating '
990n/a 'point\n'
991n/a 'numbers, e.g., "3.14%0.7" equals "0.34" (since "3.14" equals '
992n/a '"4*0.7 +\n'
993n/a '0.34".) The modulo operator always yields a result with the same '
994n/a 'sign\n'
995n/a 'as its second operand (or zero); the absolute value of the result '
996n/a 'is\n'
997n/a 'strictly smaller than the absolute value of the second operand '
998n/a '[1].\n'
999n/a '\n'
1000n/a 'The floor division and modulo operators are connected by the '
1001n/a 'following\n'
1002n/a 'identity: "x == (x//y)*y + (x%y)". Floor division and modulo are '
1003n/a 'also\n'
1004n/a 'connected with the built-in function "divmod()": "divmod(x, y) ==\n'
1005n/a '(x//y, x%y)". [2].\n'
1006n/a '\n'
1007n/a 'In addition to performing the modulo operation on numbers, the '
1008n/a '"%"\n'
1009n/a 'operator is also overloaded by string objects to perform '
1010n/a 'old-style\n'
1011n/a 'string formatting (also known as interpolation). The syntax for\n'
1012n/a 'string formatting is described in the Python Library Reference,\n'
1013n/a 'section printf-style String Formatting.\n'
1014n/a '\n'
1015n/a 'The floor division operator, the modulo operator, and the '
1016n/a '"divmod()"\n'
1017n/a 'function are not defined for complex numbers. Instead, convert to '
1018n/a 'a\n'
1019n/a 'floating point number using the "abs()" function if appropriate.\n'
1020n/a '\n'
1021n/a 'The "+" (addition) operator yields the sum of its arguments. The\n'
1022n/a 'arguments must either both be numbers or both be sequences of the '
1023n/a 'same\n'
1024n/a 'type. In the former case, the numbers are converted to a common '
1025n/a 'type\n'
1026n/a 'and then added together. In the latter case, the sequences are\n'
1027n/a 'concatenated.\n'
1028n/a '\n'
1029n/a 'The "-" (subtraction) operator yields the difference of its '
1030n/a 'arguments.\n'
1031n/a 'The numeric arguments are first converted to a common type.\n',
1032n/a 'bitwise': '\n'
1033n/a 'Binary bitwise operations\n'
1034n/a '*************************\n'
1035n/a '\n'
1036n/a 'Each of the three bitwise operations has a different priority '
1037n/a 'level:\n'
1038n/a '\n'
1039n/a ' and_expr ::= shift_expr | and_expr "&" shift_expr\n'
1040n/a ' xor_expr ::= and_expr | xor_expr "^" and_expr\n'
1041n/a ' or_expr ::= xor_expr | or_expr "|" xor_expr\n'
1042n/a '\n'
1043n/a 'The "&" operator yields the bitwise AND of its arguments, which '
1044n/a 'must\n'
1045n/a 'be integers.\n'
1046n/a '\n'
1047n/a 'The "^" operator yields the bitwise XOR (exclusive OR) of its\n'
1048n/a 'arguments, which must be integers.\n'
1049n/a '\n'
1050n/a 'The "|" operator yields the bitwise (inclusive) OR of its '
1051n/a 'arguments,\n'
1052n/a 'which must be integers.\n',
1053n/a 'bltin-code-objects': '\n'
1054n/a 'Code Objects\n'
1055n/a '************\n'
1056n/a '\n'
1057n/a 'Code objects are used by the implementation to '
1058n/a 'represent "pseudo-\n'
1059n/a 'compiled" executable Python code such as a function '
1060n/a 'body. They differ\n'
1061n/a "from function objects because they don't contain a "
1062n/a 'reference to their\n'
1063n/a 'global execution environment. Code objects are '
1064n/a 'returned by the built-\n'
1065n/a 'in "compile()" function and can be extracted from '
1066n/a 'function objects\n'
1067n/a 'through their "__code__" attribute. See also the '
1068n/a '"code" module.\n'
1069n/a '\n'
1070n/a 'A code object can be executed or evaluated by passing '
1071n/a 'it (instead of a\n'
1072n/a 'source string) to the "exec()" or "eval()" built-in '
1073n/a 'functions.\n'
1074n/a '\n'
1075n/a 'See The standard type hierarchy for more '
1076n/a 'information.\n',
1077n/a 'bltin-ellipsis-object': '\n'
1078n/a 'The Ellipsis Object\n'
1079n/a '*******************\n'
1080n/a '\n'
1081n/a 'This object is commonly used by slicing (see '
1082n/a 'Slicings). It supports\n'
1083n/a 'no special operations. There is exactly one '
1084n/a 'ellipsis object, named\n'
1085n/a '"Ellipsis" (a built-in name). "type(Ellipsis)()" '
1086n/a 'produces the\n'
1087n/a '"Ellipsis" singleton.\n'
1088n/a '\n'
1089n/a 'It is written as "Ellipsis" or "...".\n',
1090n/a 'bltin-null-object': '\n'
1091n/a 'The Null Object\n'
1092n/a '***************\n'
1093n/a '\n'
1094n/a "This object is returned by functions that don't "
1095n/a 'explicitly return a\n'
1096n/a 'value. It supports no special operations. There is '
1097n/a 'exactly one null\n'
1098n/a 'object, named "None" (a built-in name). "type(None)()" '
1099n/a 'produces the\n'
1100n/a 'same singleton.\n'
1101n/a '\n'
1102n/a 'It is written as "None".\n',
1103n/a 'bltin-type-objects': '\n'
1104n/a 'Type Objects\n'
1105n/a '************\n'
1106n/a '\n'
1107n/a 'Type objects represent the various object types. An '
1108n/a "object's type is\n"
1109n/a 'accessed by the built-in function "type()". There are '
1110n/a 'no special\n'
1111n/a 'operations on types. The standard module "types" '
1112n/a 'defines names for\n'
1113n/a 'all standard built-in types.\n'
1114n/a '\n'
1115n/a 'Types are written like this: "<class \'int\'>".\n',
1116n/a 'booleans': '\n'
1117n/a 'Boolean operations\n'
1118n/a '******************\n'
1119n/a '\n'
1120n/a ' or_test ::= and_test | or_test "or" and_test\n'
1121n/a ' and_test ::= not_test | and_test "and" not_test\n'
1122n/a ' not_test ::= comparison | "not" not_test\n'
1123n/a '\n'
1124n/a 'In the context of Boolean operations, and also when expressions '
1125n/a 'are\n'
1126n/a 'used by control flow statements, the following values are '
1127n/a 'interpreted\n'
1128n/a 'as false: "False", "None", numeric zero of all types, and empty\n'
1129n/a 'strings and containers (including strings, tuples, lists,\n'
1130n/a 'dictionaries, sets and frozensets). All other values are '
1131n/a 'interpreted\n'
1132n/a 'as true. User-defined objects can customize their truth value '
1133n/a 'by\n'
1134n/a 'providing a "__bool__()" method.\n'
1135n/a '\n'
1136n/a 'The operator "not" yields "True" if its argument is false, '
1137n/a '"False"\n'
1138n/a 'otherwise.\n'
1139n/a '\n'
1140n/a 'The expression "x and y" first evaluates *x*; if *x* is false, '
1141n/a 'its\n'
1142n/a 'value is returned; otherwise, *y* is evaluated and the resulting '
1143n/a 'value\n'
1144n/a 'is returned.\n'
1145n/a '\n'
1146n/a 'The expression "x or y" first evaluates *x*; if *x* is true, its '
1147n/a 'value\n'
1148n/a 'is returned; otherwise, *y* is evaluated and the resulting value '
1149n/a 'is\n'
1150n/a 'returned.\n'
1151n/a '\n'
1152n/a '(Note that neither "and" nor "or" restrict the value and type '
1153n/a 'they\n'
1154n/a 'return to "False" and "True", but rather return the last '
1155n/a 'evaluated\n'
1156n/a 'argument. This is sometimes useful, e.g., if "s" is a string '
1157n/a 'that\n'
1158n/a 'should be replaced by a default value if it is empty, the '
1159n/a 'expression\n'
1160n/a '"s or \'foo\'" yields the desired value. Because "not" has to '
1161n/a 'create a\n'
1162n/a 'new value, it returns a boolean value regardless of the type of '
1163n/a 'its\n'
1164n/a 'argument (for example, "not \'foo\'" produces "False" rather '
1165n/a 'than "\'\'".)\n',
1166n/a 'break': '\n'
1167n/a 'The "break" statement\n'
1168n/a '*********************\n'
1169n/a '\n'
1170n/a ' break_stmt ::= "break"\n'
1171n/a '\n'
1172n/a '"break" may only occur syntactically nested in a "for" or "while"\n'
1173n/a 'loop, but not nested in a function or class definition within that\n'
1174n/a 'loop.\n'
1175n/a '\n'
1176n/a 'It terminates the nearest enclosing loop, skipping the optional '
1177n/a '"else"\n'
1178n/a 'clause if the loop has one.\n'
1179n/a '\n'
1180n/a 'If a "for" loop is terminated by "break", the loop control target\n'
1181n/a 'keeps its current value.\n'
1182n/a '\n'
1183n/a 'When "break" passes control out of a "try" statement with a '
1184n/a '"finally"\n'
1185n/a 'clause, that "finally" clause is executed before really leaving '
1186n/a 'the\n'
1187n/a 'loop.\n',
1188n/a 'callable-types': '\n'
1189n/a 'Emulating callable objects\n'
1190n/a '**************************\n'
1191n/a '\n'
1192n/a 'object.__call__(self[, args...])\n'
1193n/a '\n'
1194n/a ' Called when the instance is "called" as a function; if '
1195n/a 'this method\n'
1196n/a ' is defined, "x(arg1, arg2, ...)" is a shorthand for\n'
1197n/a ' "x.__call__(arg1, arg2, ...)".\n',
1198n/a 'calls': '\n'
1199n/a 'Calls\n'
1200n/a '*****\n'
1201n/a '\n'
1202n/a 'A call calls a callable object (e.g., a *function*) with a '
1203n/a 'possibly\n'
1204n/a 'empty series of *arguments*:\n'
1205n/a '\n'
1206n/a ' call ::= primary "(" [argument_list [","] | '
1207n/a 'comprehension] ")"\n'
1208n/a ' argument_list ::= positional_arguments ["," '
1209n/a 'starred_and_keywords]\n'
1210n/a ' ["," keywords_arguments]\n'
1211n/a ' | starred_and_keywords ["," '
1212n/a 'keywords_arguments]\n'
1213n/a ' | keywords_arguments\n'
1214n/a ' positional_arguments ::= ["*"] expression ("," ["*"] '
1215n/a 'expression)*\n'
1216n/a ' starred_and_keywords ::= ("*" expression | keyword_item)\n'
1217n/a ' ("," "*" expression | "," '
1218n/a 'keyword_item)*\n'
1219n/a ' keywords_arguments ::= (keyword_item | "**" expression)\n'
1220n/a ' ("," keyword_item | "**" expression)*\n'
1221n/a ' keyword_item ::= identifier "=" expression\n'
1222n/a '\n'
1223n/a 'An optional trailing comma may be present after the positional and\n'
1224n/a 'keyword arguments but does not affect the semantics.\n'
1225n/a '\n'
1226n/a 'The primary must evaluate to a callable object (user-defined\n'
1227n/a 'functions, built-in functions, methods of built-in objects, class\n'
1228n/a 'objects, methods of class instances, and all objects having a\n'
1229n/a '"__call__()" method are callable). All argument expressions are\n'
1230n/a 'evaluated before the call is attempted. Please refer to section\n'
1231n/a 'Function definitions for the syntax of formal *parameter* lists.\n'
1232n/a '\n'
1233n/a 'If keyword arguments are present, they are first converted to\n'
1234n/a 'positional arguments, as follows. First, a list of unfilled slots '
1235n/a 'is\n'
1236n/a 'created for the formal parameters. If there are N positional\n'
1237n/a 'arguments, they are placed in the first N slots. Next, for each\n'
1238n/a 'keyword argument, the identifier is used to determine the\n'
1239n/a 'corresponding slot (if the identifier is the same as the first '
1240n/a 'formal\n'
1241n/a 'parameter name, the first slot is used, and so on). If the slot '
1242n/a 'is\n'
1243n/a 'already filled, a "TypeError" exception is raised. Otherwise, the\n'
1244n/a 'value of the argument is placed in the slot, filling it (even if '
1245n/a 'the\n'
1246n/a 'expression is "None", it fills the slot). When all arguments have\n'
1247n/a 'been processed, the slots that are still unfilled are filled with '
1248n/a 'the\n'
1249n/a 'corresponding default value from the function definition. '
1250n/a '(Default\n'
1251n/a 'values are calculated, once, when the function is defined; thus, a\n'
1252n/a 'mutable object such as a list or dictionary used as default value '
1253n/a 'will\n'
1254n/a "be shared by all calls that don't specify an argument value for "
1255n/a 'the\n'
1256n/a 'corresponding slot; this should usually be avoided.) If there are '
1257n/a 'any\n'
1258n/a 'unfilled slots for which no default value is specified, a '
1259n/a '"TypeError"\n'
1260n/a 'exception is raised. Otherwise, the list of filled slots is used '
1261n/a 'as\n'
1262n/a 'the argument list for the call.\n'
1263n/a '\n'
1264n/a '**CPython implementation detail:** An implementation may provide\n'
1265n/a 'built-in functions whose positional parameters do not have names, '
1266n/a 'even\n'
1267n/a "if they are 'named' for the purpose of documentation, and which\n"
1268n/a 'therefore cannot be supplied by keyword. In CPython, this is the '
1269n/a 'case\n'
1270n/a 'for functions implemented in C that use "PyArg_ParseTuple()" to '
1271n/a 'parse\n'
1272n/a 'their arguments.\n'
1273n/a '\n'
1274n/a 'If there are more positional arguments than there are formal '
1275n/a 'parameter\n'
1276n/a 'slots, a "TypeError" exception is raised, unless a formal '
1277n/a 'parameter\n'
1278n/a 'using the syntax "*identifier" is present; in this case, that '
1279n/a 'formal\n'
1280n/a 'parameter receives a tuple containing the excess positional '
1281n/a 'arguments\n'
1282n/a '(or an empty tuple if there were no excess positional arguments).\n'
1283n/a '\n'
1284n/a 'If any keyword argument does not correspond to a formal parameter\n'
1285n/a 'name, a "TypeError" exception is raised, unless a formal parameter\n'
1286n/a 'using the syntax "**identifier" is present; in this case, that '
1287n/a 'formal\n'
1288n/a 'parameter receives a dictionary containing the excess keyword\n'
1289n/a 'arguments (using the keywords as keys and the argument values as\n'
1290n/a 'corresponding values), or a (new) empty dictionary if there were '
1291n/a 'no\n'
1292n/a 'excess keyword arguments.\n'
1293n/a '\n'
1294n/a 'If the syntax "*expression" appears in the function call, '
1295n/a '"expression"\n'
1296n/a 'must evaluate to an *iterable*. Elements from these iterables are\n'
1297n/a 'treated as if they were additional positional arguments. For the '
1298n/a 'call\n'
1299n/a '"f(x1, x2, *y, x3, x4)", if *y* evaluates to a sequence *y1*, ...,\n'
1300n/a '*yM*, this is equivalent to a call with M+4 positional arguments '
1301n/a '*x1*,\n'
1302n/a '*x2*, *y1*, ..., *yM*, *x3*, *x4*.\n'
1303n/a '\n'
1304n/a 'A consequence of this is that although the "*expression" syntax '
1305n/a 'may\n'
1306n/a 'appear *after* explicit keyword arguments, it is processed '
1307n/a '*before*\n'
1308n/a 'the keyword arguments (and any "**expression" arguments -- see '
1309n/a 'below).\n'
1310n/a 'So:\n'
1311n/a '\n'
1312n/a ' >>> def f(a, b):\n'
1313n/a ' ... print(a, b)\n'
1314n/a ' ...\n'
1315n/a ' >>> f(b=1, *(2,))\n'
1316n/a ' 2 1\n'
1317n/a ' >>> f(a=1, *(2,))\n'
1318n/a ' Traceback (most recent call last):\n'
1319n/a ' File "<stdin>", line 1, in ?\n'
1320n/a " TypeError: f() got multiple values for keyword argument 'a'\n"
1321n/a ' >>> f(1, *(2,))\n'
1322n/a ' 1 2\n'
1323n/a '\n'
1324n/a 'It is unusual for both keyword arguments and the "*expression" '
1325n/a 'syntax\n'
1326n/a 'to be used in the same call, so in practice this confusion does '
1327n/a 'not\n'
1328n/a 'arise.\n'
1329n/a '\n'
1330n/a 'If the syntax "**expression" appears in the function call,\n'
1331n/a '"expression" must evaluate to a *mapping*, the contents of which '
1332n/a 'are\n'
1333n/a 'treated as additional keyword arguments. If a keyword is already\n'
1334n/a 'present (as an explicit keyword argument, or from another '
1335n/a 'unpacking),\n'
1336n/a 'a "TypeError" exception is raised.\n'
1337n/a '\n'
1338n/a 'Formal parameters using the syntax "*identifier" or "**identifier"\n'
1339n/a 'cannot be used as positional argument slots or as keyword argument\n'
1340n/a 'names.\n'
1341n/a '\n'
1342n/a 'Changed in version 3.5: Function calls accept any number of "*" '
1343n/a 'and\n'
1344n/a '"**" unpackings, positional arguments may follow iterable '
1345n/a 'unpackings\n'
1346n/a '("*"), and keyword arguments may follow dictionary unpackings '
1347n/a '("**").\n'
1348n/a 'Originally proposed by **PEP 448**.\n'
1349n/a '\n'
1350n/a 'A call always returns some value, possibly "None", unless it raises '
1351n/a 'an\n'
1352n/a 'exception. How this value is computed depends on the type of the\n'
1353n/a 'callable object.\n'
1354n/a '\n'
1355n/a 'If it is---\n'
1356n/a '\n'
1357n/a 'a user-defined function:\n'
1358n/a ' The code block for the function is executed, passing it the\n'
1359n/a ' argument list. The first thing the code block will do is bind '
1360n/a 'the\n'
1361n/a ' formal parameters to the arguments; this is described in '
1362n/a 'section\n'
1363n/a ' Function definitions. When the code block executes a "return"\n'
1364n/a ' statement, this specifies the return value of the function '
1365n/a 'call.\n'
1366n/a '\n'
1367n/a 'a built-in function or method:\n'
1368n/a ' The result is up to the interpreter; see Built-in Functions for '
1369n/a 'the\n'
1370n/a ' descriptions of built-in functions and methods.\n'
1371n/a '\n'
1372n/a 'a class object:\n'
1373n/a ' A new instance of that class is returned.\n'
1374n/a '\n'
1375n/a 'a class instance method:\n'
1376n/a ' The corresponding user-defined function is called, with an '
1377n/a 'argument\n'
1378n/a ' list that is one longer than the argument list of the call: the\n'
1379n/a ' instance becomes the first argument.\n'
1380n/a '\n'
1381n/a 'a class instance:\n'
1382n/a ' The class must define a "__call__()" method; the effect is then '
1383n/a 'the\n'
1384n/a ' same as if that method was called.\n',
1385n/a 'class': '\n'
1386n/a 'Class definitions\n'
1387n/a '*****************\n'
1388n/a '\n'
1389n/a 'A class definition defines a class object (see section The '
1390n/a 'standard\n'
1391n/a 'type hierarchy):\n'
1392n/a '\n'
1393n/a ' classdef ::= [decorators] "class" classname [inheritance] ":" '
1394n/a 'suite\n'
1395n/a ' inheritance ::= "(" [argument_list] ")"\n'
1396n/a ' classname ::= identifier\n'
1397n/a '\n'
1398n/a 'A class definition is an executable statement. The inheritance '
1399n/a 'list\n'
1400n/a 'usually gives a list of base classes (see Metaclasses for more\n'
1401n/a 'advanced uses), so each item in the list should evaluate to a '
1402n/a 'class\n'
1403n/a 'object which allows subclassing. Classes without an inheritance '
1404n/a 'list\n'
1405n/a 'inherit, by default, from the base class "object"; hence,\n'
1406n/a '\n'
1407n/a ' class Foo:\n'
1408n/a ' pass\n'
1409n/a '\n'
1410n/a 'is equivalent to\n'
1411n/a '\n'
1412n/a ' class Foo(object):\n'
1413n/a ' pass\n'
1414n/a '\n'
1415n/a "The class's suite is then executed in a new execution frame (see\n"
1416n/a 'Naming and binding), using a newly created local namespace and the\n'
1417n/a 'original global namespace. (Usually, the suite contains mostly\n'
1418n/a "function definitions.) When the class's suite finishes execution, "
1419n/a 'its\n'
1420n/a 'execution frame is discarded but its local namespace is saved. [4] '
1421n/a 'A\n'
1422n/a 'class object is then created using the inheritance list for the '
1423n/a 'base\n'
1424n/a 'classes and the saved local namespace for the attribute '
1425n/a 'dictionary.\n'
1426n/a 'The class name is bound to this class object in the original local\n'
1427n/a 'namespace.\n'
1428n/a '\n'
1429n/a 'The order in which attributes are defined in the class body is\n'
1430n/a 'preserved in the new class\'s "__dict__". Note that this is '
1431n/a 'reliable\n'
1432n/a 'only right after the class is created and only for classes that '
1433n/a 'were\n'
1434n/a 'defined using the definition syntax.\n'
1435n/a '\n'
1436n/a 'Class creation can be customized heavily using metaclasses.\n'
1437n/a '\n'
1438n/a 'Classes can also be decorated: just like when decorating '
1439n/a 'functions,\n'
1440n/a '\n'
1441n/a ' @f1(arg)\n'
1442n/a ' @f2\n'
1443n/a ' class Foo: pass\n'
1444n/a '\n'
1445n/a 'is roughly equivalent to\n'
1446n/a '\n'
1447n/a ' class Foo: pass\n'
1448n/a ' Foo = f1(arg)(f2(Foo))\n'
1449n/a '\n'
1450n/a 'The evaluation rules for the decorator expressions are the same as '
1451n/a 'for\n'
1452n/a 'function decorators. The result is then bound to the class name.\n'
1453n/a '\n'
1454n/a "**Programmer's note:** Variables defined in the class definition "
1455n/a 'are\n'
1456n/a 'class attributes; they are shared by instances. Instance '
1457n/a 'attributes\n'
1458n/a 'can be set in a method with "self.name = value". Both class and\n'
1459n/a 'instance attributes are accessible through the notation '
1460n/a '""self.name"",\n'
1461n/a 'and an instance attribute hides a class attribute with the same '
1462n/a 'name\n'
1463n/a 'when accessed in this way. Class attributes can be used as '
1464n/a 'defaults\n'
1465n/a 'for instance attributes, but using mutable values there can lead '
1466n/a 'to\n'
1467n/a 'unexpected results. Descriptors can be used to create instance\n'
1468n/a 'variables with different implementation details.\n'
1469n/a '\n'
1470n/a 'See also: **PEP 3115** - Metaclasses in Python 3 **PEP 3129** -\n'
1471n/a ' Class Decorators\n',
1472n/a 'comparisons': '\n'
1473n/a 'Comparisons\n'
1474n/a '***********\n'
1475n/a '\n'
1476n/a 'Unlike C, all comparison operations in Python have the same '
1477n/a 'priority,\n'
1478n/a 'which is lower than that of any arithmetic, shifting or '
1479n/a 'bitwise\n'
1480n/a 'operation. Also unlike C, expressions like "a < b < c" have '
1481n/a 'the\n'
1482n/a 'interpretation that is conventional in mathematics:\n'
1483n/a '\n'
1484n/a ' comparison ::= or_expr ( comp_operator or_expr )*\n'
1485n/a ' comp_operator ::= "<" | ">" | "==" | ">=" | "<=" | "!="\n'
1486n/a ' | "is" ["not"] | ["not"] "in"\n'
1487n/a '\n'
1488n/a 'Comparisons yield boolean values: "True" or "False".\n'
1489n/a '\n'
1490n/a 'Comparisons can be chained arbitrarily, e.g., "x < y <= z" '
1491n/a 'is\n'
1492n/a 'equivalent to "x < y and y <= z", except that "y" is '
1493n/a 'evaluated only\n'
1494n/a 'once (but in both cases "z" is not evaluated at all when "x < '
1495n/a 'y" is\n'
1496n/a 'found to be false).\n'
1497n/a '\n'
1498n/a 'Formally, if *a*, *b*, *c*, ..., *y*, *z* are expressions and '
1499n/a '*op1*,\n'
1500n/a '*op2*, ..., *opN* are comparison operators, then "a op1 b op2 '
1501n/a 'c ... y\n'
1502n/a 'opN z" is equivalent to "a op1 b and b op2 c and ... y opN '
1503n/a 'z", except\n'
1504n/a 'that each expression is evaluated at most once.\n'
1505n/a '\n'
1506n/a 'Note that "a op1 b op2 c" doesn\'t imply any kind of '
1507n/a 'comparison between\n'
1508n/a '*a* and *c*, so that, e.g., "x < y > z" is perfectly legal '
1509n/a '(though\n'
1510n/a 'perhaps not pretty).\n'
1511n/a '\n'
1512n/a '\n'
1513n/a 'Value comparisons\n'
1514n/a '=================\n'
1515n/a '\n'
1516n/a 'The operators "<", ">", "==", ">=", "<=", and "!=" compare '
1517n/a 'the values\n'
1518n/a 'of two objects. The objects do not need to have the same '
1519n/a 'type.\n'
1520n/a '\n'
1521n/a 'Chapter Objects, values and types states that objects have a '
1522n/a 'value (in\n'
1523n/a 'addition to type and identity). The value of an object is a '
1524n/a 'rather\n'
1525n/a 'abstract notion in Python: For example, there is no canonical '
1526n/a 'access\n'
1527n/a "method for an object's value. Also, there is no requirement "
1528n/a 'that the\n'
1529n/a 'value of an object should be constructed in a particular way, '
1530n/a 'e.g.\n'
1531n/a 'comprised of all its data attributes. Comparison operators '
1532n/a 'implement a\n'
1533n/a 'particular notion of what the value of an object is. One can '
1534n/a 'think of\n'
1535n/a 'them as defining the value of an object indirectly, by means '
1536n/a 'of their\n'
1537n/a 'comparison implementation.\n'
1538n/a '\n'
1539n/a 'Because all types are (direct or indirect) subtypes of '
1540n/a '"object", they\n'
1541n/a 'inherit the default comparison behavior from "object". Types '
1542n/a 'can\n'
1543n/a 'customize their comparison behavior by implementing *rich '
1544n/a 'comparison\n'
1545n/a 'methods* like "__lt__()", described in Basic customization.\n'
1546n/a '\n'
1547n/a 'The default behavior for equality comparison ("==" and "!=") '
1548n/a 'is based\n'
1549n/a 'on the identity of the objects. Hence, equality comparison '
1550n/a 'of\n'
1551n/a 'instances with the same identity results in equality, and '
1552n/a 'equality\n'
1553n/a 'comparison of instances with different identities results in\n'
1554n/a 'inequality. A motivation for this default behavior is the '
1555n/a 'desire that\n'
1556n/a 'all objects should be reflexive (i.e. "x is y" implies "x == '
1557n/a 'y").\n'
1558n/a '\n'
1559n/a 'A default order comparison ("<", ">", "<=", and ">=") is not '
1560n/a 'provided;\n'
1561n/a 'an attempt raises "TypeError". A motivation for this default '
1562n/a 'behavior\n'
1563n/a 'is the lack of a similar invariant as for equality.\n'
1564n/a '\n'
1565n/a 'The behavior of the default equality comparison, that '
1566n/a 'instances with\n'
1567n/a 'different identities are always unequal, may be in contrast '
1568n/a 'to what\n'
1569n/a 'types will need that have a sensible definition of object '
1570n/a 'value and\n'
1571n/a 'value-based equality. Such types will need to customize '
1572n/a 'their\n'
1573n/a 'comparison behavior, and in fact, a number of built-in types '
1574n/a 'have done\n'
1575n/a 'that.\n'
1576n/a '\n'
1577n/a 'The following list describes the comparison behavior of the '
1578n/a 'most\n'
1579n/a 'important built-in types.\n'
1580n/a '\n'
1581n/a '* Numbers of built-in numeric types (Numeric Types --- int, '
1582n/a 'float,\n'
1583n/a ' complex) and of the standard library types '
1584n/a '"fractions.Fraction" and\n'
1585n/a ' "decimal.Decimal" can be compared within and across their '
1586n/a 'types,\n'
1587n/a ' with the restriction that complex numbers do not support '
1588n/a 'order\n'
1589n/a ' comparison. Within the limits of the types involved, they '
1590n/a 'compare\n'
1591n/a ' mathematically (algorithmically) correct without loss of '
1592n/a 'precision.\n'
1593n/a '\n'
1594n/a ' The not-a-number values "float(\'NaN\')" and '
1595n/a '"Decimal(\'NaN\')" are\n'
1596n/a ' special. They are identical to themselves ("x is x" is '
1597n/a 'true) but\n'
1598n/a ' are not equal to themselves ("x == x" is false). '
1599n/a 'Additionally,\n'
1600n/a ' comparing any number to a not-a-number value will return '
1601n/a '"False".\n'
1602n/a ' For example, both "3 < float(\'NaN\')" and "float(\'NaN\') '
1603n/a '< 3" will\n'
1604n/a ' return "False".\n'
1605n/a '\n'
1606n/a '* Binary sequences (instances of "bytes" or "bytearray") can '
1607n/a 'be\n'
1608n/a ' compared within and across their types. They compare\n'
1609n/a ' lexicographically using the numeric values of their '
1610n/a 'elements.\n'
1611n/a '\n'
1612n/a '* Strings (instances of "str") compare lexicographically '
1613n/a 'using the\n'
1614n/a ' numerical Unicode code points (the result of the built-in '
1615n/a 'function\n'
1616n/a ' "ord()") of their characters. [3]\n'
1617n/a '\n'
1618n/a ' Strings and binary sequences cannot be directly compared.\n'
1619n/a '\n'
1620n/a '* Sequences (instances of "tuple", "list", or "range") can '
1621n/a 'be\n'
1622n/a ' compared only within each of their types, with the '
1623n/a 'restriction that\n'
1624n/a ' ranges do not support order comparison. Equality '
1625n/a 'comparison across\n'
1626n/a ' these types results in unequality, and ordering comparison '
1627n/a 'across\n'
1628n/a ' these types raises "TypeError".\n'
1629n/a '\n'
1630n/a ' Sequences compare lexicographically using comparison of\n'
1631n/a ' corresponding elements, whereby reflexivity of the elements '
1632n/a 'is\n'
1633n/a ' enforced.\n'
1634n/a '\n'
1635n/a ' In enforcing reflexivity of elements, the comparison of '
1636n/a 'collections\n'
1637n/a ' assumes that for a collection element "x", "x == x" is '
1638n/a 'always true.\n'
1639n/a ' Based on that assumption, element identity is compared '
1640n/a 'first, and\n'
1641n/a ' element comparison is performed only for distinct '
1642n/a 'elements. This\n'
1643n/a ' approach yields the same result as a strict element '
1644n/a 'comparison\n'
1645n/a ' would, if the compared elements are reflexive. For '
1646n/a 'non-reflexive\n'
1647n/a ' elements, the result is different than for strict element\n'
1648n/a ' comparison, and may be surprising: The non-reflexive '
1649n/a 'not-a-number\n'
1650n/a ' values for example result in the following comparison '
1651n/a 'behavior when\n'
1652n/a ' used in a list:\n'
1653n/a '\n'
1654n/a " >>> nan = float('NaN')\n"
1655n/a ' >>> nan is nan\n'
1656n/a ' True\n'
1657n/a ' >>> nan == nan\n'
1658n/a ' False <-- the defined non-reflexive '
1659n/a 'behavior of NaN\n'
1660n/a ' >>> [nan] == [nan]\n'
1661n/a ' True <-- list enforces reflexivity and '
1662n/a 'tests identity first\n'
1663n/a '\n'
1664n/a ' Lexicographical comparison between built-in collections '
1665n/a 'works as\n'
1666n/a ' follows:\n'
1667n/a '\n'
1668n/a ' * For two collections to compare equal, they must be of the '
1669n/a 'same\n'
1670n/a ' type, have the same length, and each pair of '
1671n/a 'corresponding\n'
1672n/a ' elements must compare equal (for example, "[1,2] == '
1673n/a '(1,2)" is\n'
1674n/a ' false because the type is not the same).\n'
1675n/a '\n'
1676n/a ' * Collections that support order comparison are ordered the '
1677n/a 'same\n'
1678n/a ' as their first unequal elements (for example, "[1,2,x] <= '
1679n/a '[1,2,y]"\n'
1680n/a ' has the same value as "x <= y"). If a corresponding '
1681n/a 'element does\n'
1682n/a ' not exist, the shorter collection is ordered first (for '
1683n/a 'example,\n'
1684n/a ' "[1,2] < [1,2,3]" is true).\n'
1685n/a '\n'
1686n/a '* Mappings (instances of "dict") compare equal if and only if '
1687n/a 'they\n'
1688n/a ' have equal *(key, value)* pairs. Equality comparison of the '
1689n/a 'keys and\n'
1690n/a ' elements enforces reflexivity.\n'
1691n/a '\n'
1692n/a ' Order comparisons ("<", ">", "<=", and ">=") raise '
1693n/a '"TypeError".\n'
1694n/a '\n'
1695n/a '* Sets (instances of "set" or "frozenset") can be compared '
1696n/a 'within\n'
1697n/a ' and across their types.\n'
1698n/a '\n'
1699n/a ' They define order comparison operators to mean subset and '
1700n/a 'superset\n'
1701n/a ' tests. Those relations do not define total orderings (for '
1702n/a 'example,\n'
1703n/a ' the two sets "{1,2}" and "{2,3}" are not equal, nor subsets '
1704n/a 'of one\n'
1705n/a ' another, nor supersets of one another). Accordingly, sets '
1706n/a 'are not\n'
1707n/a ' appropriate arguments for functions which depend on total '
1708n/a 'ordering\n'
1709n/a ' (for example, "min()", "max()", and "sorted()" produce '
1710n/a 'undefined\n'
1711n/a ' results given a list of sets as inputs).\n'
1712n/a '\n'
1713n/a ' Comparison of sets enforces reflexivity of its elements.\n'
1714n/a '\n'
1715n/a '* Most other built-in types have no comparison methods '
1716n/a 'implemented,\n'
1717n/a ' so they inherit the default comparison behavior.\n'
1718n/a '\n'
1719n/a 'User-defined classes that customize their comparison behavior '
1720n/a 'should\n'
1721n/a 'follow some consistency rules, if possible:\n'
1722n/a '\n'
1723n/a '* Equality comparison should be reflexive. In other words, '
1724n/a 'identical\n'
1725n/a ' objects should compare equal:\n'
1726n/a '\n'
1727n/a ' "x is y" implies "x == y"\n'
1728n/a '\n'
1729n/a '* Comparison should be symmetric. In other words, the '
1730n/a 'following\n'
1731n/a ' expressions should have the same result:\n'
1732n/a '\n'
1733n/a ' "x == y" and "y == x"\n'
1734n/a '\n'
1735n/a ' "x != y" and "y != x"\n'
1736n/a '\n'
1737n/a ' "x < y" and "y > x"\n'
1738n/a '\n'
1739n/a ' "x <= y" and "y >= x"\n'
1740n/a '\n'
1741n/a '* Comparison should be transitive. The following '
1742n/a '(non-exhaustive)\n'
1743n/a ' examples illustrate that:\n'
1744n/a '\n'
1745n/a ' "x > y and y > z" implies "x > z"\n'
1746n/a '\n'
1747n/a ' "x < y and y <= z" implies "x < z"\n'
1748n/a '\n'
1749n/a '* Inverse comparison should result in the boolean negation. '
1750n/a 'In other\n'
1751n/a ' words, the following expressions should have the same '
1752n/a 'result:\n'
1753n/a '\n'
1754n/a ' "x == y" and "not x != y"\n'
1755n/a '\n'
1756n/a ' "x < y" and "not x >= y" (for total ordering)\n'
1757n/a '\n'
1758n/a ' "x > y" and "not x <= y" (for total ordering)\n'
1759n/a '\n'
1760n/a ' The last two expressions apply to totally ordered '
1761n/a 'collections (e.g.\n'
1762n/a ' to sequences, but not to sets or mappings). See also the\n'
1763n/a ' "total_ordering()" decorator.\n'
1764n/a '\n'
1765n/a 'Python does not enforce these consistency rules. In fact, '
1766n/a 'the\n'
1767n/a 'not-a-number values are an example for not following these '
1768n/a 'rules.\n'
1769n/a '\n'
1770n/a '\n'
1771n/a 'Membership test operations\n'
1772n/a '==========================\n'
1773n/a '\n'
1774n/a 'The operators "in" and "not in" test for membership. "x in '
1775n/a 's"\n'
1776n/a 'evaluates to true if *x* is a member of *s*, and false '
1777n/a 'otherwise. "x\n'
1778n/a 'not in s" returns the negation of "x in s". All built-in '
1779n/a 'sequences\n'
1780n/a 'and set types support this as well as dictionary, for which '
1781n/a '"in" tests\n'
1782n/a 'whether the dictionary has a given key. For container types '
1783n/a 'such as\n'
1784n/a 'list, tuple, set, frozenset, dict, or collections.deque, the\n'
1785n/a 'expression "x in y" is equivalent to "any(x is e or x == e '
1786n/a 'for e in\n'
1787n/a 'y)".\n'
1788n/a '\n'
1789n/a 'For the string and bytes types, "x in y" is true if and only '
1790n/a 'if *x* is\n'
1791n/a 'a substring of *y*. An equivalent test is "y.find(x) != '
1792n/a '-1". Empty\n'
1793n/a 'strings are always considered to be a substring of any other '
1794n/a 'string,\n'
1795n/a 'so """ in "abc"" will return "True".\n'
1796n/a '\n'
1797n/a 'For user-defined classes which define the "__contains__()" '
1798n/a 'method, "x\n'
1799n/a 'in y" is true if and only if "y.__contains__(x)" is true.\n'
1800n/a '\n'
1801n/a 'For user-defined classes which do not define "__contains__()" '
1802n/a 'but do\n'
1803n/a 'define "__iter__()", "x in y" is true if some value "z" with '
1804n/a '"x == z"\n'
1805n/a 'is produced while iterating over "y". If an exception is '
1806n/a 'raised\n'
1807n/a 'during the iteration, it is as if "in" raised that '
1808n/a 'exception.\n'
1809n/a '\n'
1810n/a 'Lastly, the old-style iteration protocol is tried: if a class '
1811n/a 'defines\n'
1812n/a '"__getitem__()", "x in y" is true if and only if there is a '
1813n/a 'non-\n'
1814n/a 'negative integer index *i* such that "x == y[i]", and all '
1815n/a 'lower\n'
1816n/a 'integer indices do not raise "IndexError" exception. (If any '
1817n/a 'other\n'
1818n/a 'exception is raised, it is as if "in" raised that '
1819n/a 'exception).\n'
1820n/a '\n'
1821n/a 'The operator "not in" is defined to have the inverse true '
1822n/a 'value of\n'
1823n/a '"in".\n'
1824n/a '\n'
1825n/a '\n'
1826n/a 'Identity comparisons\n'
1827n/a '====================\n'
1828n/a '\n'
1829n/a 'The operators "is" and "is not" test for object identity: "x '
1830n/a 'is y" is\n'
1831n/a 'true if and only if *x* and *y* are the same object. Object '
1832n/a 'identity\n'
1833n/a 'is determined using the "id()" function. "x is not y" yields '
1834n/a 'the\n'
1835n/a 'inverse truth value. [4]\n',
1836n/a 'compound': '\n'
1837n/a 'Compound statements\n'
1838n/a '*******************\n'
1839n/a '\n'
1840n/a 'Compound statements contain (groups of) other statements; they '
1841n/a 'affect\n'
1842n/a 'or control the execution of those other statements in some way. '
1843n/a 'In\n'
1844n/a 'general, compound statements span multiple lines, although in '
1845n/a 'simple\n'
1846n/a 'incarnations a whole compound statement may be contained in one '
1847n/a 'line.\n'
1848n/a '\n'
1849n/a 'The "if", "while" and "for" statements implement traditional '
1850n/a 'control\n'
1851n/a 'flow constructs. "try" specifies exception handlers and/or '
1852n/a 'cleanup\n'
1853n/a 'code for a group of statements, while the "with" statement '
1854n/a 'allows the\n'
1855n/a 'execution of initialization and finalization code around a block '
1856n/a 'of\n'
1857n/a 'code. Function and class definitions are also syntactically '
1858n/a 'compound\n'
1859n/a 'statements.\n'
1860n/a '\n'
1861n/a "A compound statement consists of one or more 'clauses.' A "
1862n/a 'clause\n'
1863n/a "consists of a header and a 'suite.' The clause headers of a\n"
1864n/a 'particular compound statement are all at the same indentation '
1865n/a 'level.\n'
1866n/a 'Each clause header begins with a uniquely identifying keyword '
1867n/a 'and ends\n'
1868n/a 'with a colon. A suite is a group of statements controlled by a\n'
1869n/a 'clause. A suite can be one or more semicolon-separated simple\n'
1870n/a 'statements on the same line as the header, following the '
1871n/a "header's\n"
1872n/a 'colon, or it can be one or more indented statements on '
1873n/a 'subsequent\n'
1874n/a 'lines. Only the latter form of a suite can contain nested '
1875n/a 'compound\n'
1876n/a "statements; the following is illegal, mostly because it wouldn't "
1877n/a 'be\n'
1878n/a 'clear to which "if" clause a following "else" clause would '
1879n/a 'belong:\n'
1880n/a '\n'
1881n/a ' if test1: if test2: print(x)\n'
1882n/a '\n'
1883n/a 'Also note that the semicolon binds tighter than the colon in '
1884n/a 'this\n'
1885n/a 'context, so that in the following example, either all or none of '
1886n/a 'the\n'
1887n/a '"print()" calls are executed:\n'
1888n/a '\n'
1889n/a ' if x < y < z: print(x); print(y); print(z)\n'
1890n/a '\n'
1891n/a 'Summarizing:\n'
1892n/a '\n'
1893n/a ' compound_stmt ::= if_stmt\n'
1894n/a ' | while_stmt\n'
1895n/a ' | for_stmt\n'
1896n/a ' | try_stmt\n'
1897n/a ' | with_stmt\n'
1898n/a ' | funcdef\n'
1899n/a ' | classdef\n'
1900n/a ' | async_with_stmt\n'
1901n/a ' | async_for_stmt\n'
1902n/a ' | async_funcdef\n'
1903n/a ' suite ::= stmt_list NEWLINE | NEWLINE INDENT '
1904n/a 'statement+ DEDENT\n'
1905n/a ' statement ::= stmt_list NEWLINE | compound_stmt\n'
1906n/a ' stmt_list ::= simple_stmt (";" simple_stmt)* [";"]\n'
1907n/a '\n'
1908n/a 'Note that statements always end in a "NEWLINE" possibly followed '
1909n/a 'by a\n'
1910n/a '"DEDENT". Also note that optional continuation clauses always '
1911n/a 'begin\n'
1912n/a 'with a keyword that cannot start a statement, thus there are no\n'
1913n/a 'ambiguities (the \'dangling "else"\' problem is solved in Python '
1914n/a 'by\n'
1915n/a 'requiring nested "if" statements to be indented).\n'
1916n/a '\n'
1917n/a 'The formatting of the grammar rules in the following sections '
1918n/a 'places\n'
1919n/a 'each clause on a separate line for clarity.\n'
1920n/a '\n'
1921n/a '\n'
1922n/a 'The "if" statement\n'
1923n/a '==================\n'
1924n/a '\n'
1925n/a 'The "if" statement is used for conditional execution:\n'
1926n/a '\n'
1927n/a ' if_stmt ::= "if" expression ":" suite\n'
1928n/a ' ( "elif" expression ":" suite )*\n'
1929n/a ' ["else" ":" suite]\n'
1930n/a '\n'
1931n/a 'It selects exactly one of the suites by evaluating the '
1932n/a 'expressions one\n'
1933n/a 'by one until one is found to be true (see section Boolean '
1934n/a 'operations\n'
1935n/a 'for the definition of true and false); then that suite is '
1936n/a 'executed\n'
1937n/a '(and no other part of the "if" statement is executed or '
1938n/a 'evaluated).\n'
1939n/a 'If all expressions are false, the suite of the "else" clause, '
1940n/a 'if\n'
1941n/a 'present, is executed.\n'
1942n/a '\n'
1943n/a '\n'
1944n/a 'The "while" statement\n'
1945n/a '=====================\n'
1946n/a '\n'
1947n/a 'The "while" statement is used for repeated execution as long as '
1948n/a 'an\n'
1949n/a 'expression is true:\n'
1950n/a '\n'
1951n/a ' while_stmt ::= "while" expression ":" suite\n'
1952n/a ' ["else" ":" suite]\n'
1953n/a '\n'
1954n/a 'This repeatedly tests the expression and, if it is true, '
1955n/a 'executes the\n'
1956n/a 'first suite; if the expression is false (which may be the first '
1957n/a 'time\n'
1958n/a 'it is tested) the suite of the "else" clause, if present, is '
1959n/a 'executed\n'
1960n/a 'and the loop terminates.\n'
1961n/a '\n'
1962n/a 'A "break" statement executed in the first suite terminates the '
1963n/a 'loop\n'
1964n/a 'without executing the "else" clause\'s suite. A "continue" '
1965n/a 'statement\n'
1966n/a 'executed in the first suite skips the rest of the suite and goes '
1967n/a 'back\n'
1968n/a 'to testing the expression.\n'
1969n/a '\n'
1970n/a '\n'
1971n/a 'The "for" statement\n'
1972n/a '===================\n'
1973n/a '\n'
1974n/a 'The "for" statement is used to iterate over the elements of a '
1975n/a 'sequence\n'
1976n/a '(such as a string, tuple or list) or other iterable object:\n'
1977n/a '\n'
1978n/a ' for_stmt ::= "for" target_list "in" expression_list ":" '
1979n/a 'suite\n'
1980n/a ' ["else" ":" suite]\n'
1981n/a '\n'
1982n/a 'The expression list is evaluated once; it should yield an '
1983n/a 'iterable\n'
1984n/a 'object. An iterator is created for the result of the\n'
1985n/a '"expression_list". The suite is then executed once for each '
1986n/a 'item\n'
1987n/a 'provided by the iterator, in the order returned by the '
1988n/a 'iterator. Each\n'
1989n/a 'item in turn is assigned to the target list using the standard '
1990n/a 'rules\n'
1991n/a 'for assignments (see Assignment statements), and then the suite '
1992n/a 'is\n'
1993n/a 'executed. When the items are exhausted (which is immediately '
1994n/a 'when the\n'
1995n/a 'sequence is empty or an iterator raises a "StopIteration" '
1996n/a 'exception),\n'
1997n/a 'the suite in the "else" clause, if present, is executed, and the '
1998n/a 'loop\n'
1999n/a 'terminates.\n'
2000n/a '\n'
2001n/a 'A "break" statement executed in the first suite terminates the '
2002n/a 'loop\n'
2003n/a 'without executing the "else" clause\'s suite. A "continue" '
2004n/a 'statement\n'
2005n/a 'executed in the first suite skips the rest of the suite and '
2006n/a 'continues\n'
2007n/a 'with the next item, or with the "else" clause if there is no '
2008n/a 'next\n'
2009n/a 'item.\n'
2010n/a '\n'
2011n/a 'The for-loop makes assignments to the variables(s) in the target '
2012n/a 'list.\n'
2013n/a 'This overwrites all previous assignments to those variables '
2014n/a 'including\n'
2015n/a 'those made in the suite of the for-loop:\n'
2016n/a '\n'
2017n/a ' for i in range(10):\n'
2018n/a ' print(i)\n'
2019n/a ' i = 5 # this will not affect the for-loop\n'
2020n/a ' # because i will be overwritten with '
2021n/a 'the next\n'
2022n/a ' # index in the range\n'
2023n/a '\n'
2024n/a 'Names in the target list are not deleted when the loop is '
2025n/a 'finished,\n'
2026n/a 'but if the sequence is empty, they will not have been assigned '
2027n/a 'to at\n'
2028n/a 'all by the loop. Hint: the built-in function "range()" returns '
2029n/a 'an\n'
2030n/a "iterator of integers suitable to emulate the effect of Pascal's "
2031n/a '"for i\n'
2032n/a ':= a to b do"; e.g., "list(range(3))" returns the list "[0, 1, '
2033n/a '2]".\n'
2034n/a '\n'
2035n/a 'Note: There is a subtlety when the sequence is being modified by '
2036n/a 'the\n'
2037n/a ' loop (this can only occur for mutable sequences, i.e. lists). '
2038n/a 'An\n'
2039n/a ' internal counter is used to keep track of which item is used '
2040n/a 'next,\n'
2041n/a ' and this is incremented on each iteration. When this counter '
2042n/a 'has\n'
2043n/a ' reached the length of the sequence the loop terminates. This '
2044n/a 'means\n'
2045n/a ' that if the suite deletes the current (or a previous) item '
2046n/a 'from the\n'
2047n/a ' sequence, the next item will be skipped (since it gets the '
2048n/a 'index of\n'
2049n/a ' the current item which has already been treated). Likewise, '
2050n/a 'if the\n'
2051n/a ' suite inserts an item in the sequence before the current item, '
2052n/a 'the\n'
2053n/a ' current item will be treated again the next time through the '
2054n/a 'loop.\n'
2055n/a ' This can lead to nasty bugs that can be avoided by making a\n'
2056n/a ' temporary copy using a slice of the whole sequence, e.g.,\n'
2057n/a '\n'
2058n/a ' for x in a[:]:\n'
2059n/a ' if x < 0: a.remove(x)\n'
2060n/a '\n'
2061n/a '\n'
2062n/a 'The "try" statement\n'
2063n/a '===================\n'
2064n/a '\n'
2065n/a 'The "try" statement specifies exception handlers and/or cleanup '
2066n/a 'code\n'
2067n/a 'for a group of statements:\n'
2068n/a '\n'
2069n/a ' try_stmt ::= try1_stmt | try2_stmt\n'
2070n/a ' try1_stmt ::= "try" ":" suite\n'
2071n/a ' ("except" [expression ["as" identifier]] ":" '
2072n/a 'suite)+\n'
2073n/a ' ["else" ":" suite]\n'
2074n/a ' ["finally" ":" suite]\n'
2075n/a ' try2_stmt ::= "try" ":" suite\n'
2076n/a ' "finally" ":" suite\n'
2077n/a '\n'
2078n/a 'The "except" clause(s) specify one or more exception handlers. '
2079n/a 'When no\n'
2080n/a 'exception occurs in the "try" clause, no exception handler is\n'
2081n/a 'executed. When an exception occurs in the "try" suite, a search '
2082n/a 'for an\n'
2083n/a 'exception handler is started. This search inspects the except '
2084n/a 'clauses\n'
2085n/a 'in turn until one is found that matches the exception. An '
2086n/a 'expression-\n'
2087n/a 'less except clause, if present, must be last; it matches any\n'
2088n/a 'exception. For an except clause with an expression, that '
2089n/a 'expression\n'
2090n/a 'is evaluated, and the clause matches the exception if the '
2091n/a 'resulting\n'
2092n/a 'object is "compatible" with the exception. An object is '
2093n/a 'compatible\n'
2094n/a 'with an exception if it is the class or a base class of the '
2095n/a 'exception\n'
2096n/a 'object or a tuple containing an item compatible with the '
2097n/a 'exception.\n'
2098n/a '\n'
2099n/a 'If no except clause matches the exception, the search for an '
2100n/a 'exception\n'
2101n/a 'handler continues in the surrounding code and on the invocation '
2102n/a 'stack.\n'
2103n/a '[1]\n'
2104n/a '\n'
2105n/a 'If the evaluation of an expression in the header of an except '
2106n/a 'clause\n'
2107n/a 'raises an exception, the original search for a handler is '
2108n/a 'canceled and\n'
2109n/a 'a search starts for the new exception in the surrounding code '
2110n/a 'and on\n'
2111n/a 'the call stack (it is treated as if the entire "try" statement '
2112n/a 'raised\n'
2113n/a 'the exception).\n'
2114n/a '\n'
2115n/a 'When a matching except clause is found, the exception is '
2116n/a 'assigned to\n'
2117n/a 'the target specified after the "as" keyword in that except '
2118n/a 'clause, if\n'
2119n/a "present, and the except clause's suite is executed. All except\n"
2120n/a 'clauses must have an executable block. When the end of this '
2121n/a 'block is\n'
2122n/a 'reached, execution continues normally after the entire try '
2123n/a 'statement.\n'
2124n/a '(This means that if two nested handlers exist for the same '
2125n/a 'exception,\n'
2126n/a 'and the exception occurs in the try clause of the inner handler, '
2127n/a 'the\n'
2128n/a 'outer handler will not handle the exception.)\n'
2129n/a '\n'
2130n/a 'When an exception has been assigned using "as target", it is '
2131n/a 'cleared\n'
2132n/a 'at the end of the except clause. This is as if\n'
2133n/a '\n'
2134n/a ' except E as N:\n'
2135n/a ' foo\n'
2136n/a '\n'
2137n/a 'was translated to\n'
2138n/a '\n'
2139n/a ' except E as N:\n'
2140n/a ' try:\n'
2141n/a ' foo\n'
2142n/a ' finally:\n'
2143n/a ' del N\n'
2144n/a '\n'
2145n/a 'This means the exception must be assigned to a different name to '
2146n/a 'be\n'
2147n/a 'able to refer to it after the except clause. Exceptions are '
2148n/a 'cleared\n'
2149n/a 'because with the traceback attached to them, they form a '
2150n/a 'reference\n'
2151n/a 'cycle with the stack frame, keeping all locals in that frame '
2152n/a 'alive\n'
2153n/a 'until the next garbage collection occurs.\n'
2154n/a '\n'
2155n/a "Before an except clause's suite is executed, details about the\n"
2156n/a 'exception are stored in the "sys" module and can be accessed '
2157n/a 'via\n'
2158n/a '"sys.exc_info()". "sys.exc_info()" returns a 3-tuple consisting '
2159n/a 'of the\n'
2160n/a 'exception class, the exception instance and a traceback object '
2161n/a '(see\n'
2162n/a 'section The standard type hierarchy) identifying the point in '
2163n/a 'the\n'
2164n/a 'program where the exception occurred. "sys.exc_info()" values '
2165n/a 'are\n'
2166n/a 'restored to their previous values (before the call) when '
2167n/a 'returning\n'
2168n/a 'from a function that handled an exception.\n'
2169n/a '\n'
2170n/a 'The optional "else" clause is executed if and when control flows '
2171n/a 'off\n'
2172n/a 'the end of the "try" clause. [2] Exceptions in the "else" clause '
2173n/a 'are\n'
2174n/a 'not handled by the preceding "except" clauses.\n'
2175n/a '\n'
2176n/a 'If "finally" is present, it specifies a \'cleanup\' handler. '
2177n/a 'The "try"\n'
2178n/a 'clause is executed, including any "except" and "else" clauses. '
2179n/a 'If an\n'
2180n/a 'exception occurs in any of the clauses and is not handled, the\n'
2181n/a 'exception is temporarily saved. The "finally" clause is '
2182n/a 'executed. If\n'
2183n/a 'there is a saved exception it is re-raised at the end of the '
2184n/a '"finally"\n'
2185n/a 'clause. If the "finally" clause raises another exception, the '
2186n/a 'saved\n'
2187n/a 'exception is set as the context of the new exception. If the '
2188n/a '"finally"\n'
2189n/a 'clause executes a "return" or "break" statement, the saved '
2190n/a 'exception\n'
2191n/a 'is discarded:\n'
2192n/a '\n'
2193n/a ' >>> def f():\n'
2194n/a ' ... try:\n'
2195n/a ' ... 1/0\n'
2196n/a ' ... finally:\n'
2197n/a ' ... return 42\n'
2198n/a ' ...\n'
2199n/a ' >>> f()\n'
2200n/a ' 42\n'
2201n/a '\n'
2202n/a 'The exception information is not available to the program '
2203n/a 'during\n'
2204n/a 'execution of the "finally" clause.\n'
2205n/a '\n'
2206n/a 'When a "return", "break" or "continue" statement is executed in '
2207n/a 'the\n'
2208n/a '"try" suite of a "try"..."finally" statement, the "finally" '
2209n/a 'clause is\n'
2210n/a 'also executed \'on the way out.\' A "continue" statement is '
2211n/a 'illegal in\n'
2212n/a 'the "finally" clause. (The reason is a problem with the current\n'
2213n/a 'implementation --- this restriction may be lifted in the '
2214n/a 'future).\n'
2215n/a '\n'
2216n/a 'The return value of a function is determined by the last '
2217n/a '"return"\n'
2218n/a 'statement executed. Since the "finally" clause always executes, '
2219n/a 'a\n'
2220n/a '"return" statement executed in the "finally" clause will always '
2221n/a 'be the\n'
2222n/a 'last one executed:\n'
2223n/a '\n'
2224n/a ' >>> def foo():\n'
2225n/a ' ... try:\n'
2226n/a " ... return 'try'\n"
2227n/a ' ... finally:\n'
2228n/a " ... return 'finally'\n"
2229n/a ' ...\n'
2230n/a ' >>> foo()\n'
2231n/a " 'finally'\n"
2232n/a '\n'
2233n/a 'Additional information on exceptions can be found in section\n'
2234n/a 'Exceptions, and information on using the "raise" statement to '
2235n/a 'generate\n'
2236n/a 'exceptions may be found in section The raise statement.\n'
2237n/a '\n'
2238n/a '\n'
2239n/a 'The "with" statement\n'
2240n/a '====================\n'
2241n/a '\n'
2242n/a 'The "with" statement is used to wrap the execution of a block '
2243n/a 'with\n'
2244n/a 'methods defined by a context manager (see section With '
2245n/a 'Statement\n'
2246n/a 'Context Managers). This allows common '
2247n/a '"try"..."except"..."finally"\n'
2248n/a 'usage patterns to be encapsulated for convenient reuse.\n'
2249n/a '\n'
2250n/a ' with_stmt ::= "with" with_item ("," with_item)* ":" suite\n'
2251n/a ' with_item ::= expression ["as" target]\n'
2252n/a '\n'
2253n/a 'The execution of the "with" statement with one "item" proceeds '
2254n/a 'as\n'
2255n/a 'follows:\n'
2256n/a '\n'
2257n/a '1. The context expression (the expression given in the '
2258n/a '"with_item")\n'
2259n/a ' is evaluated to obtain a context manager.\n'
2260n/a '\n'
2261n/a '2. The context manager\'s "__exit__()" is loaded for later use.\n'
2262n/a '\n'
2263n/a '3. The context manager\'s "__enter__()" method is invoked.\n'
2264n/a '\n'
2265n/a '4. If a target was included in the "with" statement, the return\n'
2266n/a ' value from "__enter__()" is assigned to it.\n'
2267n/a '\n'
2268n/a ' Note: The "with" statement guarantees that if the '
2269n/a '"__enter__()"\n'
2270n/a ' method returns without an error, then "__exit__()" will '
2271n/a 'always be\n'
2272n/a ' called. Thus, if an error occurs during the assignment to '
2273n/a 'the\n'
2274n/a ' target list, it will be treated the same as an error '
2275n/a 'occurring\n'
2276n/a ' within the suite would be. See step 6 below.\n'
2277n/a '\n'
2278n/a '5. The suite is executed.\n'
2279n/a '\n'
2280n/a '6. The context manager\'s "__exit__()" method is invoked. If '
2281n/a 'an\n'
2282n/a ' exception caused the suite to be exited, its type, value, '
2283n/a 'and\n'
2284n/a ' traceback are passed as arguments to "__exit__()". Otherwise, '
2285n/a 'three\n'
2286n/a ' "None" arguments are supplied.\n'
2287n/a '\n'
2288n/a ' If the suite was exited due to an exception, and the return '
2289n/a 'value\n'
2290n/a ' from the "__exit__()" method was false, the exception is '
2291n/a 'reraised.\n'
2292n/a ' If the return value was true, the exception is suppressed, '
2293n/a 'and\n'
2294n/a ' execution continues with the statement following the "with"\n'
2295n/a ' statement.\n'
2296n/a '\n'
2297n/a ' If the suite was exited for any reason other than an '
2298n/a 'exception, the\n'
2299n/a ' return value from "__exit__()" is ignored, and execution '
2300n/a 'proceeds\n'
2301n/a ' at the normal location for the kind of exit that was taken.\n'
2302n/a '\n'
2303n/a 'With more than one item, the context managers are processed as '
2304n/a 'if\n'
2305n/a 'multiple "with" statements were nested:\n'
2306n/a '\n'
2307n/a ' with A() as a, B() as b:\n'
2308n/a ' suite\n'
2309n/a '\n'
2310n/a 'is equivalent to\n'
2311n/a '\n'
2312n/a ' with A() as a:\n'
2313n/a ' with B() as b:\n'
2314n/a ' suite\n'
2315n/a '\n'
2316n/a 'Changed in version 3.1: Support for multiple context '
2317n/a 'expressions.\n'
2318n/a '\n'
2319n/a 'See also:\n'
2320n/a '\n'
2321n/a ' **PEP 343** - The "with" statement\n'
2322n/a ' The specification, background, and examples for the Python '
2323n/a '"with"\n'
2324n/a ' statement.\n'
2325n/a '\n'
2326n/a '\n'
2327n/a 'Function definitions\n'
2328n/a '====================\n'
2329n/a '\n'
2330n/a 'A function definition defines a user-defined function object '
2331n/a '(see\n'
2332n/a 'section The standard type hierarchy):\n'
2333n/a '\n'
2334n/a ' funcdef ::= [decorators] "def" funcname "(" '
2335n/a '[parameter_list] ")" ["->" expression] ":" suite\n'
2336n/a ' decorators ::= decorator+\n'
2337n/a ' decorator ::= "@" dotted_name ["(" '
2338n/a '[argument_list [","]] ")"] NEWLINE\n'
2339n/a ' dotted_name ::= identifier ("." identifier)*\n'
2340n/a ' parameter_list ::= defparameter ("," defparameter)* '
2341n/a '["," [parameter_list_starargs]]\n'
2342n/a ' | parameter_list_starargs\n'
2343n/a ' parameter_list_starargs ::= "*" [parameter] ("," '
2344n/a 'defparameter)* ["," ["**" parameter [","]]]\n'
2345n/a ' | "**" parameter [","]\n'
2346n/a ' parameter ::= identifier [":" expression]\n'
2347n/a ' defparameter ::= parameter ["=" expression]\n'
2348n/a ' funcname ::= identifier\n'
2349n/a '\n'
2350n/a 'A function definition is an executable statement. Its execution '
2351n/a 'binds\n'
2352n/a 'the function name in the current local namespace to a function '
2353n/a 'object\n'
2354n/a '(a wrapper around the executable code for the function). This\n'
2355n/a 'function object contains a reference to the current global '
2356n/a 'namespace\n'
2357n/a 'as the global namespace to be used when the function is called.\n'
2358n/a '\n'
2359n/a 'The function definition does not execute the function body; this '
2360n/a 'gets\n'
2361n/a 'executed only when the function is called. [3]\n'
2362n/a '\n'
2363n/a 'A function definition may be wrapped by one or more *decorator*\n'
2364n/a 'expressions. Decorator expressions are evaluated when the '
2365n/a 'function is\n'
2366n/a 'defined, in the scope that contains the function definition. '
2367n/a 'The\n'
2368n/a 'result must be a callable, which is invoked with the function '
2369n/a 'object\n'
2370n/a 'as the only argument. The returned value is bound to the '
2371n/a 'function name\n'
2372n/a 'instead of the function object. Multiple decorators are applied '
2373n/a 'in\n'
2374n/a 'nested fashion. For example, the following code\n'
2375n/a '\n'
2376n/a ' @f1(arg)\n'
2377n/a ' @f2\n'
2378n/a ' def func(): pass\n'
2379n/a '\n'
2380n/a 'is roughly equivalent to\n'
2381n/a '\n'
2382n/a ' def func(): pass\n'
2383n/a ' func = f1(arg)(f2(func))\n'
2384n/a '\n'
2385n/a 'except that the original function is not temporarily bound to '
2386n/a 'the name\n'
2387n/a '"func".\n'
2388n/a '\n'
2389n/a 'When one or more *parameters* have the form *parameter* "="\n'
2390n/a '*expression*, the function is said to have "default parameter '
2391n/a 'values."\n'
2392n/a 'For a parameter with a default value, the corresponding '
2393n/a '*argument* may\n'
2394n/a "be omitted from a call, in which case the parameter's default "
2395n/a 'value is\n'
2396n/a 'substituted. If a parameter has a default value, all following\n'
2397n/a 'parameters up until the ""*"" must also have a default value --- '
2398n/a 'this\n'
2399n/a 'is a syntactic restriction that is not expressed by the '
2400n/a 'grammar.\n'
2401n/a '\n'
2402n/a '**Default parameter values are evaluated from left to right when '
2403n/a 'the\n'
2404n/a 'function definition is executed.** This means that the '
2405n/a 'expression is\n'
2406n/a 'evaluated once, when the function is defined, and that the same '
2407n/a '"pre-\n'
2408n/a 'computed" value is used for each call. This is especially '
2409n/a 'important\n'
2410n/a 'to understand when a default parameter is a mutable object, such '
2411n/a 'as a\n'
2412n/a 'list or a dictionary: if the function modifies the object (e.g. '
2413n/a 'by\n'
2414n/a 'appending an item to a list), the default value is in effect '
2415n/a 'modified.\n'
2416n/a 'This is generally not what was intended. A way around this is '
2417n/a 'to use\n'
2418n/a '"None" as the default, and explicitly test for it in the body of '
2419n/a 'the\n'
2420n/a 'function, e.g.:\n'
2421n/a '\n'
2422n/a ' def whats_on_the_telly(penguin=None):\n'
2423n/a ' if penguin is None:\n'
2424n/a ' penguin = []\n'
2425n/a ' penguin.append("property of the zoo")\n'
2426n/a ' return penguin\n'
2427n/a '\n'
2428n/a 'Function call semantics are described in more detail in section '
2429n/a 'Calls.\n'
2430n/a 'A function call always assigns values to all parameters '
2431n/a 'mentioned in\n'
2432n/a 'the parameter list, either from position arguments, from '
2433n/a 'keyword\n'
2434n/a 'arguments, or from default values. If the form ""*identifier"" '
2435n/a 'is\n'
2436n/a 'present, it is initialized to a tuple receiving any excess '
2437n/a 'positional\n'
2438n/a 'parameters, defaulting to the empty tuple. If the form\n'
2439n/a '""**identifier"" is present, it is initialized to a new ordered\n'
2440n/a 'mapping receiving any excess keyword arguments, defaulting to a '
2441n/a 'new\n'
2442n/a 'empty mapping of the same type. Parameters after ""*"" or\n'
2443n/a '""*identifier"" are keyword-only parameters and may only be '
2444n/a 'passed\n'
2445n/a 'used keyword arguments.\n'
2446n/a '\n'
2447n/a 'Parameters may have annotations of the form "": expression"" '
2448n/a 'following\n'
2449n/a 'the parameter name. Any parameter may have an annotation even '
2450n/a 'those\n'
2451n/a 'of the form "*identifier" or "**identifier". Functions may '
2452n/a 'have\n'
2453n/a '"return" annotation of the form ""-> expression"" after the '
2454n/a 'parameter\n'
2455n/a 'list. These annotations can be any valid Python expression and '
2456n/a 'are\n'
2457n/a 'evaluated when the function definition is executed. Annotations '
2458n/a 'may\n'
2459n/a 'be evaluated in a different order than they appear in the source '
2460n/a 'code.\n'
2461n/a 'The presence of annotations does not change the semantics of a\n'
2462n/a 'function. The annotation values are available as values of a\n'
2463n/a "dictionary keyed by the parameters' names in the "
2464n/a '"__annotations__"\n'
2465n/a 'attribute of the function object.\n'
2466n/a '\n'
2467n/a 'It is also possible to create anonymous functions (functions not '
2468n/a 'bound\n'
2469n/a 'to a name), for immediate use in expressions. This uses lambda\n'
2470n/a 'expressions, described in section Lambdas. Note that the '
2471n/a 'lambda\n'
2472n/a 'expression is merely a shorthand for a simplified function '
2473n/a 'definition;\n'
2474n/a 'a function defined in a ""def"" statement can be passed around '
2475n/a 'or\n'
2476n/a 'assigned to another name just like a function defined by a '
2477n/a 'lambda\n'
2478n/a 'expression. The ""def"" form is actually more powerful since '
2479n/a 'it\n'
2480n/a 'allows the execution of multiple statements and annotations.\n'
2481n/a '\n'
2482n/a "**Programmer's note:** Functions are first-class objects. A "
2483n/a '""def""\n'
2484n/a 'statement executed inside a function definition defines a local\n'
2485n/a 'function that can be returned or passed around. Free variables '
2486n/a 'used\n'
2487n/a 'in the nested function can access the local variables of the '
2488n/a 'function\n'
2489n/a 'containing the def. See section Naming and binding for '
2490n/a 'details.\n'
2491n/a '\n'
2492n/a 'See also:\n'
2493n/a '\n'
2494n/a ' **PEP 3107** - Function Annotations\n'
2495n/a ' The original specification for function annotations.\n'
2496n/a '\n'
2497n/a '\n'
2498n/a 'Class definitions\n'
2499n/a '=================\n'
2500n/a '\n'
2501n/a 'A class definition defines a class object (see section The '
2502n/a 'standard\n'
2503n/a 'type hierarchy):\n'
2504n/a '\n'
2505n/a ' classdef ::= [decorators] "class" classname [inheritance] '
2506n/a '":" suite\n'
2507n/a ' inheritance ::= "(" [argument_list] ")"\n'
2508n/a ' classname ::= identifier\n'
2509n/a '\n'
2510n/a 'A class definition is an executable statement. The inheritance '
2511n/a 'list\n'
2512n/a 'usually gives a list of base classes (see Metaclasses for more\n'
2513n/a 'advanced uses), so each item in the list should evaluate to a '
2514n/a 'class\n'
2515n/a 'object which allows subclassing. Classes without an inheritance '
2516n/a 'list\n'
2517n/a 'inherit, by default, from the base class "object"; hence,\n'
2518n/a '\n'
2519n/a ' class Foo:\n'
2520n/a ' pass\n'
2521n/a '\n'
2522n/a 'is equivalent to\n'
2523n/a '\n'
2524n/a ' class Foo(object):\n'
2525n/a ' pass\n'
2526n/a '\n'
2527n/a "The class's suite is then executed in a new execution frame "
2528n/a '(see\n'
2529n/a 'Naming and binding), using a newly created local namespace and '
2530n/a 'the\n'
2531n/a 'original global namespace. (Usually, the suite contains mostly\n'
2532n/a "function definitions.) When the class's suite finishes "
2533n/a 'execution, its\n'
2534n/a 'execution frame is discarded but its local namespace is saved. '
2535n/a '[4] A\n'
2536n/a 'class object is then created using the inheritance list for the '
2537n/a 'base\n'
2538n/a 'classes and the saved local namespace for the attribute '
2539n/a 'dictionary.\n'
2540n/a 'The class name is bound to this class object in the original '
2541n/a 'local\n'
2542n/a 'namespace.\n'
2543n/a '\n'
2544n/a 'The order in which attributes are defined in the class body is\n'
2545n/a 'preserved in the new class\'s "__dict__". Note that this is '
2546n/a 'reliable\n'
2547n/a 'only right after the class is created and only for classes that '
2548n/a 'were\n'
2549n/a 'defined using the definition syntax.\n'
2550n/a '\n'
2551n/a 'Class creation can be customized heavily using metaclasses.\n'
2552n/a '\n'
2553n/a 'Classes can also be decorated: just like when decorating '
2554n/a 'functions,\n'
2555n/a '\n'
2556n/a ' @f1(arg)\n'
2557n/a ' @f2\n'
2558n/a ' class Foo: pass\n'
2559n/a '\n'
2560n/a 'is roughly equivalent to\n'
2561n/a '\n'
2562n/a ' class Foo: pass\n'
2563n/a ' Foo = f1(arg)(f2(Foo))\n'
2564n/a '\n'
2565n/a 'The evaluation rules for the decorator expressions are the same '
2566n/a 'as for\n'
2567n/a 'function decorators. The result is then bound to the class '
2568n/a 'name.\n'
2569n/a '\n'
2570n/a "**Programmer's note:** Variables defined in the class definition "
2571n/a 'are\n'
2572n/a 'class attributes; they are shared by instances. Instance '
2573n/a 'attributes\n'
2574n/a 'can be set in a method with "self.name = value". Both class '
2575n/a 'and\n'
2576n/a 'instance attributes are accessible through the notation '
2577n/a '""self.name"",\n'
2578n/a 'and an instance attribute hides a class attribute with the same '
2579n/a 'name\n'
2580n/a 'when accessed in this way. Class attributes can be used as '
2581n/a 'defaults\n'
2582n/a 'for instance attributes, but using mutable values there can lead '
2583n/a 'to\n'
2584n/a 'unexpected results. Descriptors can be used to create instance\n'
2585n/a 'variables with different implementation details.\n'
2586n/a '\n'
2587n/a 'See also: **PEP 3115** - Metaclasses in Python 3 **PEP 3129** -\n'
2588n/a ' Class Decorators\n'
2589n/a '\n'
2590n/a '\n'
2591n/a 'Coroutines\n'
2592n/a '==========\n'
2593n/a '\n'
2594n/a 'New in version 3.5.\n'
2595n/a '\n'
2596n/a '\n'
2597n/a 'Coroutine function definition\n'
2598n/a '-----------------------------\n'
2599n/a '\n'
2600n/a ' async_funcdef ::= [decorators] "async" "def" funcname "(" '
2601n/a '[parameter_list] ")" ["->" expression] ":" suite\n'
2602n/a '\n'
2603n/a 'Execution of Python coroutines can be suspended and resumed at '
2604n/a 'many\n'
2605n/a 'points (see *coroutine*). In the body of a coroutine, any '
2606n/a '"await" and\n'
2607n/a '"async" identifiers become reserved keywords; "await" '
2608n/a 'expressions,\n'
2609n/a '"async for" and "async with" can only be used in coroutine '
2610n/a 'bodies.\n'
2611n/a '\n'
2612n/a 'Functions defined with "async def" syntax are always coroutine\n'
2613n/a 'functions, even if they do not contain "await" or "async" '
2614n/a 'keywords.\n'
2615n/a '\n'
2616n/a 'It is a "SyntaxError" to use "yield" expressions in "async def"\n'
2617n/a 'coroutines.\n'
2618n/a '\n'
2619n/a 'An example of a coroutine function:\n'
2620n/a '\n'
2621n/a ' async def func(param1, param2):\n'
2622n/a ' do_stuff()\n'
2623n/a ' await some_coroutine()\n'
2624n/a '\n'
2625n/a '\n'
2626n/a 'The "async for" statement\n'
2627n/a '-------------------------\n'
2628n/a '\n'
2629n/a ' async_for_stmt ::= "async" for_stmt\n'
2630n/a '\n'
2631n/a 'An *asynchronous iterable* is able to call asynchronous code in '
2632n/a 'its\n'
2633n/a '*iter* implementation, and *asynchronous iterator* can call\n'
2634n/a 'asynchronous code in its *next* method.\n'
2635n/a '\n'
2636n/a 'The "async for" statement allows convenient iteration over\n'
2637n/a 'asynchronous iterators.\n'
2638n/a '\n'
2639n/a 'The following code:\n'
2640n/a '\n'
2641n/a ' async for TARGET in ITER:\n'
2642n/a ' BLOCK\n'
2643n/a ' else:\n'
2644n/a ' BLOCK2\n'
2645n/a '\n'
2646n/a 'Is semantically equivalent to:\n'
2647n/a '\n'
2648n/a ' iter = (ITER)\n'
2649n/a ' iter = type(iter).__aiter__(iter)\n'
2650n/a ' running = True\n'
2651n/a ' while running:\n'
2652n/a ' try:\n'
2653n/a ' TARGET = await type(iter).__anext__(iter)\n'
2654n/a ' except StopAsyncIteration:\n'
2655n/a ' running = False\n'
2656n/a ' else:\n'
2657n/a ' BLOCK\n'
2658n/a ' else:\n'
2659n/a ' BLOCK2\n'
2660n/a '\n'
2661n/a 'See also "__aiter__()" and "__anext__()" for details.\n'
2662n/a '\n'
2663n/a 'It is a "SyntaxError" to use "async for" statement outside of '
2664n/a 'an\n'
2665n/a '"async def" function.\n'
2666n/a '\n'
2667n/a '\n'
2668n/a 'The "async with" statement\n'
2669n/a '--------------------------\n'
2670n/a '\n'
2671n/a ' async_with_stmt ::= "async" with_stmt\n'
2672n/a '\n'
2673n/a 'An *asynchronous context manager* is a *context manager* that is '
2674n/a 'able\n'
2675n/a 'to suspend execution in its *enter* and *exit* methods.\n'
2676n/a '\n'
2677n/a 'The following code:\n'
2678n/a '\n'
2679n/a ' async with EXPR as VAR:\n'
2680n/a ' BLOCK\n'
2681n/a '\n'
2682n/a 'Is semantically equivalent to:\n'
2683n/a '\n'
2684n/a ' mgr = (EXPR)\n'
2685n/a ' aexit = type(mgr).__aexit__\n'
2686n/a ' aenter = type(mgr).__aenter__(mgr)\n'
2687n/a ' exc = True\n'
2688n/a '\n'
2689n/a ' VAR = await aenter\n'
2690n/a ' try:\n'
2691n/a ' BLOCK\n'
2692n/a ' except:\n'
2693n/a ' if not await aexit(mgr, *sys.exc_info()):\n'
2694n/a ' raise\n'
2695n/a ' else:\n'
2696n/a ' await aexit(mgr, None, None, None)\n'
2697n/a '\n'
2698n/a 'See also "__aenter__()" and "__aexit__()" for details.\n'
2699n/a '\n'
2700n/a 'It is a "SyntaxError" to use "async with" statement outside of '
2701n/a 'an\n'
2702n/a '"async def" function.\n'
2703n/a '\n'
2704n/a 'See also: **PEP 492** - Coroutines with async and await syntax\n'
2705n/a '\n'
2706n/a '-[ Footnotes ]-\n'
2707n/a '\n'
2708n/a '[1] The exception is propagated to the invocation stack unless\n'
2709n/a ' there is a "finally" clause which happens to raise another\n'
2710n/a ' exception. That new exception causes the old one to be '
2711n/a 'lost.\n'
2712n/a '\n'
2713n/a '[2] Currently, control "flows off the end" except in the case '
2714n/a 'of\n'
2715n/a ' an exception or the execution of a "return", "continue", or\n'
2716n/a ' "break" statement.\n'
2717n/a '\n'
2718n/a '[3] A string literal appearing as the first statement in the\n'
2719n/a ' function body is transformed into the function\'s "__doc__"\n'
2720n/a " attribute and therefore the function's *docstring*.\n"
2721n/a '\n'
2722n/a '[4] A string literal appearing as the first statement in the '
2723n/a 'class\n'
2724n/a ' body is transformed into the namespace\'s "__doc__" item '
2725n/a 'and\n'
2726n/a " therefore the class's *docstring*.\n",
2727n/a 'context-managers': '\n'
2728n/a 'With Statement Context Managers\n'
2729n/a '*******************************\n'
2730n/a '\n'
2731n/a 'A *context manager* is an object that defines the '
2732n/a 'runtime context to\n'
2733n/a 'be established when executing a "with" statement. The '
2734n/a 'context manager\n'
2735n/a 'handles the entry into, and the exit from, the desired '
2736n/a 'runtime context\n'
2737n/a 'for the execution of the block of code. Context '
2738n/a 'managers are normally\n'
2739n/a 'invoked using the "with" statement (described in section '
2740n/a 'The with\n'
2741n/a 'statement), but can also be used by directly invoking '
2742n/a 'their methods.\n'
2743n/a '\n'
2744n/a 'Typical uses of context managers include saving and '
2745n/a 'restoring various\n'
2746n/a 'kinds of global state, locking and unlocking resources, '
2747n/a 'closing opened\n'
2748n/a 'files, etc.\n'
2749n/a '\n'
2750n/a 'For more information on context managers, see Context '
2751n/a 'Manager Types.\n'
2752n/a '\n'
2753n/a 'object.__enter__(self)\n'
2754n/a '\n'
2755n/a ' Enter the runtime context related to this object. The '
2756n/a '"with"\n'
2757n/a " statement will bind this method's return value to the "
2758n/a 'target(s)\n'
2759n/a ' specified in the "as" clause of the statement, if '
2760n/a 'any.\n'
2761n/a '\n'
2762n/a 'object.__exit__(self, exc_type, exc_value, traceback)\n'
2763n/a '\n'
2764n/a ' Exit the runtime context related to this object. The '
2765n/a 'parameters\n'
2766n/a ' describe the exception that caused the context to be '
2767n/a 'exited. If the\n'
2768n/a ' context was exited without an exception, all three '
2769n/a 'arguments will\n'
2770n/a ' be "None".\n'
2771n/a '\n'
2772n/a ' If an exception is supplied, and the method wishes to '
2773n/a 'suppress the\n'
2774n/a ' exception (i.e., prevent it from being propagated), '
2775n/a 'it should\n'
2776n/a ' return a true value. Otherwise, the exception will be '
2777n/a 'processed\n'
2778n/a ' normally upon exit from this method.\n'
2779n/a '\n'
2780n/a ' Note that "__exit__()" methods should not reraise the '
2781n/a 'passed-in\n'
2782n/a " exception; this is the caller's responsibility.\n"
2783n/a '\n'
2784n/a 'See also:\n'
2785n/a '\n'
2786n/a ' **PEP 343** - The "with" statement\n'
2787n/a ' The specification, background, and examples for the '
2788n/a 'Python "with"\n'
2789n/a ' statement.\n',
2790n/a 'continue': '\n'
2791n/a 'The "continue" statement\n'
2792n/a '************************\n'
2793n/a '\n'
2794n/a ' continue_stmt ::= "continue"\n'
2795n/a '\n'
2796n/a '"continue" may only occur syntactically nested in a "for" or '
2797n/a '"while"\n'
2798n/a 'loop, but not nested in a function or class definition or '
2799n/a '"finally"\n'
2800n/a 'clause within that loop. It continues with the next cycle of '
2801n/a 'the\n'
2802n/a 'nearest enclosing loop.\n'
2803n/a '\n'
2804n/a 'When "continue" passes control out of a "try" statement with a\n'
2805n/a '"finally" clause, that "finally" clause is executed before '
2806n/a 'really\n'
2807n/a 'starting the next loop cycle.\n',
2808n/a 'conversions': '\n'
2809n/a 'Arithmetic conversions\n'
2810n/a '**********************\n'
2811n/a '\n'
2812n/a 'When a description of an arithmetic operator below uses the '
2813n/a 'phrase\n'
2814n/a '"the numeric arguments are converted to a common type," this '
2815n/a 'means\n'
2816n/a 'that the operator implementation for built-in types works as '
2817n/a 'follows:\n'
2818n/a '\n'
2819n/a '* If either argument is a complex number, the other is '
2820n/a 'converted to\n'
2821n/a ' complex;\n'
2822n/a '\n'
2823n/a '* otherwise, if either argument is a floating point number, '
2824n/a 'the\n'
2825n/a ' other is converted to floating point;\n'
2826n/a '\n'
2827n/a '* otherwise, both must be integers and no conversion is '
2828n/a 'necessary.\n'
2829n/a '\n'
2830n/a 'Some additional rules apply for certain operators (e.g., a '
2831n/a 'string as a\n'
2832n/a "left argument to the '%' operator). Extensions must define "
2833n/a 'their own\n'
2834n/a 'conversion behavior.\n',
2835n/a 'customization': '\n'
2836n/a 'Basic customization\n'
2837n/a '*******************\n'
2838n/a '\n'
2839n/a 'object.__new__(cls[, ...])\n'
2840n/a '\n'
2841n/a ' Called to create a new instance of class *cls*. '
2842n/a '"__new__()" is a\n'
2843n/a ' static method (special-cased so you need not declare it '
2844n/a 'as such)\n'
2845n/a ' that takes the class of which an instance was requested '
2846n/a 'as its\n'
2847n/a ' first argument. The remaining arguments are those '
2848n/a 'passed to the\n'
2849n/a ' object constructor expression (the call to the class). '
2850n/a 'The return\n'
2851n/a ' value of "__new__()" should be the new object instance '
2852n/a '(usually an\n'
2853n/a ' instance of *cls*).\n'
2854n/a '\n'
2855n/a ' Typical implementations create a new instance of the '
2856n/a 'class by\n'
2857n/a ' invoking the superclass\'s "__new__()" method using\n'
2858n/a ' "super(currentclass, cls).__new__(cls[, ...])" with '
2859n/a 'appropriate\n'
2860n/a ' arguments and then modifying the newly-created instance '
2861n/a 'as\n'
2862n/a ' necessary before returning it.\n'
2863n/a '\n'
2864n/a ' If "__new__()" returns an instance of *cls*, then the '
2865n/a 'new\n'
2866n/a ' instance\'s "__init__()" method will be invoked like\n'
2867n/a ' "__init__(self[, ...])", where *self* is the new '
2868n/a 'instance and the\n'
2869n/a ' remaining arguments are the same as were passed to '
2870n/a '"__new__()".\n'
2871n/a '\n'
2872n/a ' If "__new__()" does not return an instance of *cls*, '
2873n/a 'then the new\n'
2874n/a ' instance\'s "__init__()" method will not be invoked.\n'
2875n/a '\n'
2876n/a ' "__new__()" is intended mainly to allow subclasses of '
2877n/a 'immutable\n'
2878n/a ' types (like int, str, or tuple) to customize instance '
2879n/a 'creation. It\n'
2880n/a ' is also commonly overridden in custom metaclasses in '
2881n/a 'order to\n'
2882n/a ' customize class creation.\n'
2883n/a '\n'
2884n/a 'object.__init__(self[, ...])\n'
2885n/a '\n'
2886n/a ' Called after the instance has been created (by '
2887n/a '"__new__()"), but\n'
2888n/a ' before it is returned to the caller. The arguments are '
2889n/a 'those\n'
2890n/a ' passed to the class constructor expression. If a base '
2891n/a 'class has an\n'
2892n/a ' "__init__()" method, the derived class\'s "__init__()" '
2893n/a 'method, if\n'
2894n/a ' any, must explicitly call it to ensure proper '
2895n/a 'initialization of the\n'
2896n/a ' base class part of the instance; for example:\n'
2897n/a ' "BaseClass.__init__(self, [args...])".\n'
2898n/a '\n'
2899n/a ' Because "__new__()" and "__init__()" work together in '
2900n/a 'constructing\n'
2901n/a ' objects ("__new__()" to create it, and "__init__()" to '
2902n/a 'customize\n'
2903n/a ' it), no non-"None" value may be returned by '
2904n/a '"__init__()"; doing so\n'
2905n/a ' will cause a "TypeError" to be raised at runtime.\n'
2906n/a '\n'
2907n/a 'object.__del__(self)\n'
2908n/a '\n'
2909n/a ' Called when the instance is about to be destroyed. This '
2910n/a 'is also\n'
2911n/a ' called a destructor. If a base class has a "__del__()" '
2912n/a 'method, the\n'
2913n/a ' derived class\'s "__del__()" method, if any, must '
2914n/a 'explicitly call it\n'
2915n/a ' to ensure proper deletion of the base class part of the '
2916n/a 'instance.\n'
2917n/a ' Note that it is possible (though not recommended!) for '
2918n/a 'the\n'
2919n/a ' "__del__()" method to postpone destruction of the '
2920n/a 'instance by\n'
2921n/a ' creating a new reference to it. It may then be called '
2922n/a 'at a later\n'
2923n/a ' time when this new reference is deleted. It is not '
2924n/a 'guaranteed that\n'
2925n/a ' "__del__()" methods are called for objects that still '
2926n/a 'exist when\n'
2927n/a ' the interpreter exits.\n'
2928n/a '\n'
2929n/a ' Note: "del x" doesn\'t directly call "x.__del__()" --- '
2930n/a 'the former\n'
2931n/a ' decrements the reference count for "x" by one, and the '
2932n/a 'latter is\n'
2933n/a ' only called when "x"\'s reference count reaches zero. '
2934n/a 'Some common\n'
2935n/a ' situations that may prevent the reference count of an '
2936n/a 'object from\n'
2937n/a ' going to zero include: circular references between '
2938n/a 'objects (e.g.,\n'
2939n/a ' a doubly-linked list or a tree data structure with '
2940n/a 'parent and\n'
2941n/a ' child pointers); a reference to the object on the '
2942n/a 'stack frame of\n'
2943n/a ' a function that caught an exception (the traceback '
2944n/a 'stored in\n'
2945n/a ' "sys.exc_info()[2]" keeps the stack frame alive); or a '
2946n/a 'reference\n'
2947n/a ' to the object on the stack frame that raised an '
2948n/a 'unhandled\n'
2949n/a ' exception in interactive mode (the traceback stored '
2950n/a 'in\n'
2951n/a ' "sys.last_traceback" keeps the stack frame alive). '
2952n/a 'The first\n'
2953n/a ' situation can only be remedied by explicitly breaking '
2954n/a 'the cycles;\n'
2955n/a ' the second can be resolved by freeing the reference to '
2956n/a 'the\n'
2957n/a ' traceback object when it is no longer useful, and the '
2958n/a 'third can\n'
2959n/a ' be resolved by storing "None" in "sys.last_traceback". '
2960n/a 'Circular\n'
2961n/a ' references which are garbage are detected and cleaned '
2962n/a 'up when the\n'
2963n/a " cyclic garbage collector is enabled (it's on by "
2964n/a 'default). Refer\n'
2965n/a ' to the documentation for the "gc" module for more '
2966n/a 'information\n'
2967n/a ' about this topic.\n'
2968n/a '\n'
2969n/a ' Warning: Due to the precarious circumstances under '
2970n/a 'which\n'
2971n/a ' "__del__()" methods are invoked, exceptions that occur '
2972n/a 'during\n'
2973n/a ' their execution are ignored, and a warning is printed '
2974n/a 'to\n'
2975n/a ' "sys.stderr" instead. Also, when "__del__()" is '
2976n/a 'invoked in\n'
2977n/a ' response to a module being deleted (e.g., when '
2978n/a 'execution of the\n'
2979n/a ' program is done), other globals referenced by the '
2980n/a '"__del__()"\n'
2981n/a ' method may already have been deleted or in the process '
2982n/a 'of being\n'
2983n/a ' torn down (e.g. the import machinery shutting down). '
2984n/a 'For this\n'
2985n/a ' reason, "__del__()" methods should do the absolute '
2986n/a 'minimum needed\n'
2987n/a ' to maintain external invariants. Starting with '
2988n/a 'version 1.5,\n'
2989n/a ' Python guarantees that globals whose name begins with '
2990n/a 'a single\n'
2991n/a ' underscore are deleted from their module before other '
2992n/a 'globals are\n'
2993n/a ' deleted; if no other references to such globals exist, '
2994n/a 'this may\n'
2995n/a ' help in assuring that imported modules are still '
2996n/a 'available at the\n'
2997n/a ' time when the "__del__()" method is called.\n'
2998n/a '\n'
2999n/a 'object.__repr__(self)\n'
3000n/a '\n'
3001n/a ' Called by the "repr()" built-in function to compute the '
3002n/a '"official"\n'
3003n/a ' string representation of an object. If at all possible, '
3004n/a 'this\n'
3005n/a ' should look like a valid Python expression that could be '
3006n/a 'used to\n'
3007n/a ' recreate an object with the same value (given an '
3008n/a 'appropriate\n'
3009n/a ' environment). If this is not possible, a string of the '
3010n/a 'form\n'
3011n/a ' "<...some useful description...>" should be returned. '
3012n/a 'The return\n'
3013n/a ' value must be a string object. If a class defines '
3014n/a '"__repr__()" but\n'
3015n/a ' not "__str__()", then "__repr__()" is also used when an '
3016n/a '"informal"\n'
3017n/a ' string representation of instances of that class is '
3018n/a 'required.\n'
3019n/a '\n'
3020n/a ' This is typically used for debugging, so it is important '
3021n/a 'that the\n'
3022n/a ' representation is information-rich and unambiguous.\n'
3023n/a '\n'
3024n/a 'object.__str__(self)\n'
3025n/a '\n'
3026n/a ' Called by "str(object)" and the built-in functions '
3027n/a '"format()" and\n'
3028n/a ' "print()" to compute the "informal" or nicely printable '
3029n/a 'string\n'
3030n/a ' representation of an object. The return value must be a '
3031n/a 'string\n'
3032n/a ' object.\n'
3033n/a '\n'
3034n/a ' This method differs from "object.__repr__()" in that '
3035n/a 'there is no\n'
3036n/a ' expectation that "__str__()" return a valid Python '
3037n/a 'expression: a\n'
3038n/a ' more convenient or concise representation can be used.\n'
3039n/a '\n'
3040n/a ' The default implementation defined by the built-in type '
3041n/a '"object"\n'
3042n/a ' calls "object.__repr__()".\n'
3043n/a '\n'
3044n/a 'object.__bytes__(self)\n'
3045n/a '\n'
3046n/a ' Called by "bytes()" to compute a byte-string '
3047n/a 'representation of an\n'
3048n/a ' object. This should return a "bytes" object.\n'
3049n/a '\n'
3050n/a 'object.__format__(self, format_spec)\n'
3051n/a '\n'
3052n/a ' Called by the "format()" built-in function, and by '
3053n/a 'extension,\n'
3054n/a ' evaluation of formatted string literals and the '
3055n/a '"str.format()"\n'
3056n/a ' method, to produce a "formatted" string representation '
3057n/a 'of an\n'
3058n/a ' object. The "format_spec" argument is a string that '
3059n/a 'contains a\n'
3060n/a ' description of the formatting options desired. The '
3061n/a 'interpretation\n'
3062n/a ' of the "format_spec" argument is up to the type '
3063n/a 'implementing\n'
3064n/a ' "__format__()", however most classes will either '
3065n/a 'delegate\n'
3066n/a ' formatting to one of the built-in types, or use a '
3067n/a 'similar\n'
3068n/a ' formatting option syntax.\n'
3069n/a '\n'
3070n/a ' See Format Specification Mini-Language for a description '
3071n/a 'of the\n'
3072n/a ' standard formatting syntax.\n'
3073n/a '\n'
3074n/a ' The return value must be a string object.\n'
3075n/a '\n'
3076n/a ' Changed in version 3.4: The __format__ method of '
3077n/a '"object" itself\n'
3078n/a ' raises a "TypeError" if passed any non-empty string.\n'
3079n/a '\n'
3080n/a 'object.__lt__(self, other)\n'
3081n/a 'object.__le__(self, other)\n'
3082n/a 'object.__eq__(self, other)\n'
3083n/a 'object.__ne__(self, other)\n'
3084n/a 'object.__gt__(self, other)\n'
3085n/a 'object.__ge__(self, other)\n'
3086n/a '\n'
3087n/a ' These are the so-called "rich comparison" methods. The\n'
3088n/a ' correspondence between operator symbols and method names '
3089n/a 'is as\n'
3090n/a ' follows: "x<y" calls "x.__lt__(y)", "x<=y" calls '
3091n/a '"x.__le__(y)",\n'
3092n/a ' "x==y" calls "x.__eq__(y)", "x!=y" calls "x.__ne__(y)", '
3093n/a '"x>y" calls\n'
3094n/a ' "x.__gt__(y)", and "x>=y" calls "x.__ge__(y)".\n'
3095n/a '\n'
3096n/a ' A rich comparison method may return the singleton '
3097n/a '"NotImplemented"\n'
3098n/a ' if it does not implement the operation for a given pair '
3099n/a 'of\n'
3100n/a ' arguments. By convention, "False" and "True" are '
3101n/a 'returned for a\n'
3102n/a ' successful comparison. However, these methods can return '
3103n/a 'any value,\n'
3104n/a ' so if the comparison operator is used in a Boolean '
3105n/a 'context (e.g.,\n'
3106n/a ' in the condition of an "if" statement), Python will call '
3107n/a '"bool()"\n'
3108n/a ' on the value to determine if the result is true or '
3109n/a 'false.\n'
3110n/a '\n'
3111n/a ' By default, "__ne__()" delegates to "__eq__()" and '
3112n/a 'inverts the\n'
3113n/a ' result unless it is "NotImplemented". There are no '
3114n/a 'other implied\n'
3115n/a ' relationships among the comparison operators, for '
3116n/a 'example, the\n'
3117n/a ' truth of "(x<y or x==y)" does not imply "x<=y". To '
3118n/a 'automatically\n'
3119n/a ' generate ordering operations from a single root '
3120n/a 'operation, see\n'
3121n/a ' "functools.total_ordering()".\n'
3122n/a '\n'
3123n/a ' See the paragraph on "__hash__()" for some important '
3124n/a 'notes on\n'
3125n/a ' creating *hashable* objects which support custom '
3126n/a 'comparison\n'
3127n/a ' operations and are usable as dictionary keys.\n'
3128n/a '\n'
3129n/a ' There are no swapped-argument versions of these methods '
3130n/a '(to be used\n'
3131n/a ' when the left argument does not support the operation '
3132n/a 'but the right\n'
3133n/a ' argument does); rather, "__lt__()" and "__gt__()" are '
3134n/a "each other's\n"
3135n/a ' reflection, "__le__()" and "__ge__()" are each other\'s '
3136n/a 'reflection,\n'
3137n/a ' and "__eq__()" and "__ne__()" are their own reflection. '
3138n/a 'If the\n'
3139n/a " operands are of different types, and right operand's "
3140n/a 'type is a\n'
3141n/a " direct or indirect subclass of the left operand's type, "
3142n/a 'the\n'
3143n/a ' reflected method of the right operand has priority, '
3144n/a 'otherwise the\n'
3145n/a " left operand's method has priority. Virtual subclassing "
3146n/a 'is not\n'
3147n/a ' considered.\n'
3148n/a '\n'
3149n/a 'object.__hash__(self)\n'
3150n/a '\n'
3151n/a ' Called by built-in function "hash()" and for operations '
3152n/a 'on members\n'
3153n/a ' of hashed collections including "set", "frozenset", and '
3154n/a '"dict".\n'
3155n/a ' "__hash__()" should return an integer. The only '
3156n/a 'required property\n'
3157n/a ' is that objects which compare equal have the same hash '
3158n/a 'value; it is\n'
3159n/a ' advised to somehow mix together (e.g. using exclusive '
3160n/a 'or) the hash\n'
3161n/a ' values for the components of the object that also play a '
3162n/a 'part in\n'
3163n/a ' comparison of objects.\n'
3164n/a '\n'
3165n/a ' Note: "hash()" truncates the value returned from an '
3166n/a "object's\n"
3167n/a ' custom "__hash__()" method to the size of a '
3168n/a '"Py_ssize_t". This\n'
3169n/a ' is typically 8 bytes on 64-bit builds and 4 bytes on '
3170n/a '32-bit\n'
3171n/a ' builds. If an object\'s "__hash__()" must '
3172n/a 'interoperate on builds\n'
3173n/a ' of different bit sizes, be sure to check the width on '
3174n/a 'all\n'
3175n/a ' supported builds. An easy way to do this is with '
3176n/a '"python -c\n'
3177n/a ' "import sys; print(sys.hash_info.width)"".\n'
3178n/a '\n'
3179n/a ' If a class does not define an "__eq__()" method it '
3180n/a 'should not\n'
3181n/a ' define a "__hash__()" operation either; if it defines '
3182n/a '"__eq__()"\n'
3183n/a ' but not "__hash__()", its instances will not be usable '
3184n/a 'as items in\n'
3185n/a ' hashable collections. If a class defines mutable '
3186n/a 'objects and\n'
3187n/a ' implements an "__eq__()" method, it should not '
3188n/a 'implement\n'
3189n/a ' "__hash__()", since the implementation of hashable '
3190n/a 'collections\n'
3191n/a " requires that a key's hash value is immutable (if the "
3192n/a "object's hash\n"
3193n/a ' value changes, it will be in the wrong hash bucket).\n'
3194n/a '\n'
3195n/a ' User-defined classes have "__eq__()" and "__hash__()" '
3196n/a 'methods by\n'
3197n/a ' default; with them, all objects compare unequal (except '
3198n/a 'with\n'
3199n/a ' themselves) and "x.__hash__()" returns an appropriate '
3200n/a 'value such\n'
3201n/a ' that "x == y" implies both that "x is y" and "hash(x) == '
3202n/a 'hash(y)".\n'
3203n/a '\n'
3204n/a ' A class that overrides "__eq__()" and does not define '
3205n/a '"__hash__()"\n'
3206n/a ' will have its "__hash__()" implicitly set to "None". '
3207n/a 'When the\n'
3208n/a ' "__hash__()" method of a class is "None", instances of '
3209n/a 'the class\n'
3210n/a ' will raise an appropriate "TypeError" when a program '
3211n/a 'attempts to\n'
3212n/a ' retrieve their hash value, and will also be correctly '
3213n/a 'identified as\n'
3214n/a ' unhashable when checking "isinstance(obj, '
3215n/a 'collections.Hashable)".\n'
3216n/a '\n'
3217n/a ' If a class that overrides "__eq__()" needs to retain '
3218n/a 'the\n'
3219n/a ' implementation of "__hash__()" from a parent class, the '
3220n/a 'interpreter\n'
3221n/a ' must be told this explicitly by setting "__hash__ =\n'
3222n/a ' <ParentClass>.__hash__".\n'
3223n/a '\n'
3224n/a ' If a class that does not override "__eq__()" wishes to '
3225n/a 'suppress\n'
3226n/a ' hash support, it should include "__hash__ = None" in the '
3227n/a 'class\n'
3228n/a ' definition. A class which defines its own "__hash__()" '
3229n/a 'that\n'
3230n/a ' explicitly raises a "TypeError" would be incorrectly '
3231n/a 'identified as\n'
3232n/a ' hashable by an "isinstance(obj, collections.Hashable)" '
3233n/a 'call.\n'
3234n/a '\n'
3235n/a ' Note: By default, the "__hash__()" values of str, bytes '
3236n/a 'and\n'
3237n/a ' datetime objects are "salted" with an unpredictable '
3238n/a 'random value.\n'
3239n/a ' Although they remain constant within an individual '
3240n/a 'Python\n'
3241n/a ' process, they are not predictable between repeated '
3242n/a 'invocations of\n'
3243n/a ' Python.This is intended to provide protection against '
3244n/a 'a denial-\n'
3245n/a ' of-service caused by carefully-chosen inputs that '
3246n/a 'exploit the\n'
3247n/a ' worst case performance of a dict insertion, O(n^2) '
3248n/a 'complexity.\n'
3249n/a ' See '
3250n/a 'http://www.ocert.org/advisories/ocert-2011-003.html for\n'
3251n/a ' details.Changing hash values affects the iteration '
3252n/a 'order of\n'
3253n/a ' dicts, sets and other mappings. Python has never made '
3254n/a 'guarantees\n'
3255n/a ' about this ordering (and it typically varies between '
3256n/a '32-bit and\n'
3257n/a ' 64-bit builds).See also "PYTHONHASHSEED".\n'
3258n/a '\n'
3259n/a ' Changed in version 3.3: Hash randomization is enabled by '
3260n/a 'default.\n'
3261n/a '\n'
3262n/a 'object.__bool__(self)\n'
3263n/a '\n'
3264n/a ' Called to implement truth value testing and the built-in '
3265n/a 'operation\n'
3266n/a ' "bool()"; should return "False" or "True". When this '
3267n/a 'method is not\n'
3268n/a ' defined, "__len__()" is called, if it is defined, and '
3269n/a 'the object is\n'
3270n/a ' considered true if its result is nonzero. If a class '
3271n/a 'defines\n'
3272n/a ' neither "__len__()" nor "__bool__()", all its instances '
3273n/a 'are\n'
3274n/a ' considered true.\n',
3275n/a 'debugger': '\n'
3276n/a '"pdb" --- The Python Debugger\n'
3277n/a '*****************************\n'
3278n/a '\n'
3279n/a '**Source code:** Lib/pdb.py\n'
3280n/a '\n'
3281n/a '======================================================================\n'
3282n/a '\n'
3283n/a 'The module "pdb" defines an interactive source code debugger '
3284n/a 'for\n'
3285n/a 'Python programs. It supports setting (conditional) breakpoints '
3286n/a 'and\n'
3287n/a 'single stepping at the source line level, inspection of stack '
3288n/a 'frames,\n'
3289n/a 'source code listing, and evaluation of arbitrary Python code in '
3290n/a 'the\n'
3291n/a 'context of any stack frame. It also supports post-mortem '
3292n/a 'debugging\n'
3293n/a 'and can be called under program control.\n'
3294n/a '\n'
3295n/a 'The debugger is extensible -- it is actually defined as the '
3296n/a 'class\n'
3297n/a '"Pdb". This is currently undocumented but easily understood by '
3298n/a 'reading\n'
3299n/a 'the source. The extension interface uses the modules "bdb" and '
3300n/a '"cmd".\n'
3301n/a '\n'
3302n/a 'The debugger\'s prompt is "(Pdb)". Typical usage to run a '
3303n/a 'program under\n'
3304n/a 'control of the debugger is:\n'
3305n/a '\n'
3306n/a ' >>> import pdb\n'
3307n/a ' >>> import mymodule\n'
3308n/a " >>> pdb.run('mymodule.test()')\n"
3309n/a ' > <string>(0)?()\n'
3310n/a ' (Pdb) continue\n'
3311n/a ' > <string>(1)?()\n'
3312n/a ' (Pdb) continue\n'
3313n/a " NameError: 'spam'\n"
3314n/a ' > <string>(1)?()\n'
3315n/a ' (Pdb)\n'
3316n/a '\n'
3317n/a 'Changed in version 3.3: Tab-completion via the "readline" module '
3318n/a 'is\n'
3319n/a 'available for commands and command arguments, e.g. the current '
3320n/a 'global\n'
3321n/a 'and local names are offered as arguments of the "p" command.\n'
3322n/a '\n'
3323n/a '"pdb.py" can also be invoked as a script to debug other '
3324n/a 'scripts. For\n'
3325n/a 'example:\n'
3326n/a '\n'
3327n/a ' python3 -m pdb myscript.py\n'
3328n/a '\n'
3329n/a 'When invoked as a script, pdb will automatically enter '
3330n/a 'post-mortem\n'
3331n/a 'debugging if the program being debugged exits abnormally. After '
3332n/a 'post-\n'
3333n/a 'mortem debugging (or after normal exit of the program), pdb '
3334n/a 'will\n'
3335n/a "restart the program. Automatic restarting preserves pdb's state "
3336n/a '(such\n'
3337n/a 'as breakpoints) and in most cases is more useful than quitting '
3338n/a 'the\n'
3339n/a "debugger upon program's exit.\n"
3340n/a '\n'
3341n/a 'New in version 3.2: "pdb.py" now accepts a "-c" option that '
3342n/a 'executes\n'
3343n/a 'commands as if given in a ".pdbrc" file, see Debugger Commands.\n'
3344n/a '\n'
3345n/a 'The typical usage to break into the debugger from a running '
3346n/a 'program is\n'
3347n/a 'to insert\n'
3348n/a '\n'
3349n/a ' import pdb; pdb.set_trace()\n'
3350n/a '\n'
3351n/a 'at the location you want to break into the debugger. You can '
3352n/a 'then\n'
3353n/a 'step through the code following this statement, and continue '
3354n/a 'running\n'
3355n/a 'without the debugger using the "continue" command.\n'
3356n/a '\n'
3357n/a 'The typical usage to inspect a crashed program is:\n'
3358n/a '\n'
3359n/a ' >>> import pdb\n'
3360n/a ' >>> import mymodule\n'
3361n/a ' >>> mymodule.test()\n'
3362n/a ' Traceback (most recent call last):\n'
3363n/a ' File "<stdin>", line 1, in ?\n'
3364n/a ' File "./mymodule.py", line 4, in test\n'
3365n/a ' test2()\n'
3366n/a ' File "./mymodule.py", line 3, in test2\n'
3367n/a ' print(spam)\n'
3368n/a ' NameError: spam\n'
3369n/a ' >>> pdb.pm()\n'
3370n/a ' > ./mymodule.py(3)test2()\n'
3371n/a ' -> print(spam)\n'
3372n/a ' (Pdb)\n'
3373n/a '\n'
3374n/a 'The module defines the following functions; each enters the '
3375n/a 'debugger\n'
3376n/a 'in a slightly different way:\n'
3377n/a '\n'
3378n/a 'pdb.run(statement, globals=None, locals=None)\n'
3379n/a '\n'
3380n/a ' Execute the *statement* (given as a string or a code object) '
3381n/a 'under\n'
3382n/a ' debugger control. The debugger prompt appears before any '
3383n/a 'code is\n'
3384n/a ' executed; you can set breakpoints and type "continue", or you '
3385n/a 'can\n'
3386n/a ' step through the statement using "step" or "next" (all these\n'
3387n/a ' commands are explained below). The optional *globals* and '
3388n/a '*locals*\n'
3389n/a ' arguments specify the environment in which the code is '
3390n/a 'executed; by\n'
3391n/a ' default the dictionary of the module "__main__" is used. '
3392n/a '(See the\n'
3393n/a ' explanation of the built-in "exec()" or "eval()" functions.)\n'
3394n/a '\n'
3395n/a 'pdb.runeval(expression, globals=None, locals=None)\n'
3396n/a '\n'
3397n/a ' Evaluate the *expression* (given as a string or a code '
3398n/a 'object)\n'
3399n/a ' under debugger control. When "runeval()" returns, it returns '
3400n/a 'the\n'
3401n/a ' value of the expression. Otherwise this function is similar '
3402n/a 'to\n'
3403n/a ' "run()".\n'
3404n/a '\n'
3405n/a 'pdb.runcall(function, *args, **kwds)\n'
3406n/a '\n'
3407n/a ' Call the *function* (a function or method object, not a '
3408n/a 'string)\n'
3409n/a ' with the given arguments. When "runcall()" returns, it '
3410n/a 'returns\n'
3411n/a ' whatever the function call returned. The debugger prompt '
3412n/a 'appears\n'
3413n/a ' as soon as the function is entered.\n'
3414n/a '\n'
3415n/a 'pdb.set_trace()\n'
3416n/a '\n'
3417n/a ' Enter the debugger at the calling stack frame. This is '
3418n/a 'useful to\n'
3419n/a ' hard-code a breakpoint at a given point in a program, even if '
3420n/a 'the\n'
3421n/a ' code is not otherwise being debugged (e.g. when an assertion\n'
3422n/a ' fails).\n'
3423n/a '\n'
3424n/a 'pdb.post_mortem(traceback=None)\n'
3425n/a '\n'
3426n/a ' Enter post-mortem debugging of the given *traceback* object. '
3427n/a 'If no\n'
3428n/a ' *traceback* is given, it uses the one of the exception that '
3429n/a 'is\n'
3430n/a ' currently being handled (an exception must be being handled '
3431n/a 'if the\n'
3432n/a ' default is to be used).\n'
3433n/a '\n'
3434n/a 'pdb.pm()\n'
3435n/a '\n'
3436n/a ' Enter post-mortem debugging of the traceback found in\n'
3437n/a ' "sys.last_traceback".\n'
3438n/a '\n'
3439n/a 'The "run*" functions and "set_trace()" are aliases for '
3440n/a 'instantiating\n'
3441n/a 'the "Pdb" class and calling the method of the same name. If you '
3442n/a 'want\n'
3443n/a 'to access further features, you have to do this yourself:\n'
3444n/a '\n'
3445n/a "class pdb.Pdb(completekey='tab', stdin=None, stdout=None, "
3446n/a 'skip=None, nosigint=False, readrc=True)\n'
3447n/a '\n'
3448n/a ' "Pdb" is the debugger class.\n'
3449n/a '\n'
3450n/a ' The *completekey*, *stdin* and *stdout* arguments are passed '
3451n/a 'to the\n'
3452n/a ' underlying "cmd.Cmd" class; see the description there.\n'
3453n/a '\n'
3454n/a ' The *skip* argument, if given, must be an iterable of '
3455n/a 'glob-style\n'
3456n/a ' module name patterns. The debugger will not step into frames '
3457n/a 'that\n'
3458n/a ' originate in a module that matches one of these patterns. '
3459n/a '[1]\n'
3460n/a '\n'
3461n/a ' By default, Pdb sets a handler for the SIGINT signal (which '
3462n/a 'is sent\n'
3463n/a ' when the user presses "Ctrl-C" on the console) when you give '
3464n/a 'a\n'
3465n/a ' "continue" command. This allows you to break into the '
3466n/a 'debugger\n'
3467n/a ' again by pressing "Ctrl-C". If you want Pdb not to touch '
3468n/a 'the\n'
3469n/a ' SIGINT handler, set *nosigint* to true.\n'
3470n/a '\n'
3471n/a ' The *readrc* argument defaults to true and controls whether '
3472n/a 'Pdb\n'
3473n/a ' will load .pdbrc files from the filesystem.\n'
3474n/a '\n'
3475n/a ' Example call to enable tracing with *skip*:\n'
3476n/a '\n'
3477n/a " import pdb; pdb.Pdb(skip=['django.*']).set_trace()\n"
3478n/a '\n'
3479n/a ' New in version 3.1: The *skip* argument.\n'
3480n/a '\n'
3481n/a ' New in version 3.2: The *nosigint* argument. Previously, a '
3482n/a 'SIGINT\n'
3483n/a ' handler was never set by Pdb.\n'
3484n/a '\n'
3485n/a ' Changed in version 3.6: The *readrc* argument.\n'
3486n/a '\n'
3487n/a ' run(statement, globals=None, locals=None)\n'
3488n/a ' runeval(expression, globals=None, locals=None)\n'
3489n/a ' runcall(function, *args, **kwds)\n'
3490n/a ' set_trace()\n'
3491n/a '\n'
3492n/a ' See the documentation for the functions explained above.\n'
3493n/a '\n'
3494n/a '\n'
3495n/a 'Debugger Commands\n'
3496n/a '=================\n'
3497n/a '\n'
3498n/a 'The commands recognized by the debugger are listed below. Most\n'
3499n/a 'commands can be abbreviated to one or two letters as indicated; '
3500n/a 'e.g.\n'
3501n/a '"h(elp)" means that either "h" or "help" can be used to enter '
3502n/a 'the help\n'
3503n/a 'command (but not "he" or "hel", nor "H" or "Help" or "HELP").\n'
3504n/a 'Arguments to commands must be separated by whitespace (spaces '
3505n/a 'or\n'
3506n/a 'tabs). Optional arguments are enclosed in square brackets '
3507n/a '("[]") in\n'
3508n/a 'the command syntax; the square brackets must not be typed.\n'
3509n/a 'Alternatives in the command syntax are separated by a vertical '
3510n/a 'bar\n'
3511n/a '("|").\n'
3512n/a '\n'
3513n/a 'Entering a blank line repeats the last command entered. '
3514n/a 'Exception: if\n'
3515n/a 'the last command was a "list" command, the next 11 lines are '
3516n/a 'listed.\n'
3517n/a '\n'
3518n/a "Commands that the debugger doesn't recognize are assumed to be "
3519n/a 'Python\n'
3520n/a 'statements and are executed in the context of the program being\n'
3521n/a 'debugged. Python statements can also be prefixed with an '
3522n/a 'exclamation\n'
3523n/a 'point ("!"). This is a powerful way to inspect the program '
3524n/a 'being\n'
3525n/a 'debugged; it is even possible to change a variable or call a '
3526n/a 'function.\n'
3527n/a 'When an exception occurs in such a statement, the exception name '
3528n/a 'is\n'
3529n/a "printed but the debugger's state is not changed.\n"
3530n/a '\n'
3531n/a 'The debugger supports aliases. Aliases can have parameters '
3532n/a 'which\n'
3533n/a 'allows one a certain level of adaptability to the context under\n'
3534n/a 'examination.\n'
3535n/a '\n'
3536n/a 'Multiple commands may be entered on a single line, separated by '
3537n/a '";;".\n'
3538n/a '(A single ";" is not used as it is the separator for multiple '
3539n/a 'commands\n'
3540n/a 'in a line that is passed to the Python parser.) No intelligence '
3541n/a 'is\n'
3542n/a 'applied to separating the commands; the input is split at the '
3543n/a 'first\n'
3544n/a '";;" pair, even if it is in the middle of a quoted string.\n'
3545n/a '\n'
3546n/a 'If a file ".pdbrc" exists in the user\'s home directory or in '
3547n/a 'the\n'
3548n/a 'current directory, it is read in and executed as if it had been '
3549n/a 'typed\n'
3550n/a 'at the debugger prompt. This is particularly useful for '
3551n/a 'aliases. If\n'
3552n/a 'both files exist, the one in the home directory is read first '
3553n/a 'and\n'
3554n/a 'aliases defined there can be overridden by the local file.\n'
3555n/a '\n'
3556n/a 'Changed in version 3.2: ".pdbrc" can now contain commands that\n'
3557n/a 'continue debugging, such as "continue" or "next". Previously, '
3558n/a 'these\n'
3559n/a 'commands had no effect.\n'
3560n/a '\n'
3561n/a 'h(elp) [command]\n'
3562n/a '\n'
3563n/a ' Without argument, print the list of available commands. With '
3564n/a 'a\n'
3565n/a ' *command* as argument, print help about that command. "help '
3566n/a 'pdb"\n'
3567n/a ' displays the full documentation (the docstring of the "pdb"\n'
3568n/a ' module). Since the *command* argument must be an identifier, '
3569n/a '"help\n'
3570n/a ' exec" must be entered to get help on the "!" command.\n'
3571n/a '\n'
3572n/a 'w(here)\n'
3573n/a '\n'
3574n/a ' Print a stack trace, with the most recent frame at the '
3575n/a 'bottom. An\n'
3576n/a ' arrow indicates the current frame, which determines the '
3577n/a 'context of\n'
3578n/a ' most commands.\n'
3579n/a '\n'
3580n/a 'd(own) [count]\n'
3581n/a '\n'
3582n/a ' Move the current frame *count* (default one) levels down in '
3583n/a 'the\n'
3584n/a ' stack trace (to a newer frame).\n'
3585n/a '\n'
3586n/a 'u(p) [count]\n'
3587n/a '\n'
3588n/a ' Move the current frame *count* (default one) levels up in the '
3589n/a 'stack\n'
3590n/a ' trace (to an older frame).\n'
3591n/a '\n'
3592n/a 'b(reak) [([filename:]lineno | function) [, condition]]\n'
3593n/a '\n'
3594n/a ' With a *lineno* argument, set a break there in the current '
3595n/a 'file.\n'
3596n/a ' With a *function* argument, set a break at the first '
3597n/a 'executable\n'
3598n/a ' statement within that function. The line number may be '
3599n/a 'prefixed\n'
3600n/a ' with a filename and a colon, to specify a breakpoint in '
3601n/a 'another\n'
3602n/a " file (probably one that hasn't been loaded yet). The file "
3603n/a 'is\n'
3604n/a ' searched on "sys.path". Note that each breakpoint is '
3605n/a 'assigned a\n'
3606n/a ' number to which all the other breakpoint commands refer.\n'
3607n/a '\n'
3608n/a ' If a second argument is present, it is an expression which '
3609n/a 'must\n'
3610n/a ' evaluate to true before the breakpoint is honored.\n'
3611n/a '\n'
3612n/a ' Without argument, list all breaks, including for each '
3613n/a 'breakpoint,\n'
3614n/a ' the number of times that breakpoint has been hit, the '
3615n/a 'current\n'
3616n/a ' ignore count, and the associated condition if any.\n'
3617n/a '\n'
3618n/a 'tbreak [([filename:]lineno | function) [, condition]]\n'
3619n/a '\n'
3620n/a ' Temporary breakpoint, which is removed automatically when it '
3621n/a 'is\n'
3622n/a ' first hit. The arguments are the same as for "break".\n'
3623n/a '\n'
3624n/a 'cl(ear) [filename:lineno | bpnumber [bpnumber ...]]\n'
3625n/a '\n'
3626n/a ' With a *filename:lineno* argument, clear all the breakpoints '
3627n/a 'at\n'
3628n/a ' this line. With a space separated list of breakpoint numbers, '
3629n/a 'clear\n'
3630n/a ' those breakpoints. Without argument, clear all breaks (but '
3631n/a 'first\n'
3632n/a ' ask confirmation).\n'
3633n/a '\n'
3634n/a 'disable [bpnumber [bpnumber ...]]\n'
3635n/a '\n'
3636n/a ' Disable the breakpoints given as a space separated list of\n'
3637n/a ' breakpoint numbers. Disabling a breakpoint means it cannot '
3638n/a 'cause\n'
3639n/a ' the program to stop execution, but unlike clearing a '
3640n/a 'breakpoint, it\n'
3641n/a ' remains in the list of breakpoints and can be (re-)enabled.\n'
3642n/a '\n'
3643n/a 'enable [bpnumber [bpnumber ...]]\n'
3644n/a '\n'
3645n/a ' Enable the breakpoints specified.\n'
3646n/a '\n'
3647n/a 'ignore bpnumber [count]\n'
3648n/a '\n'
3649n/a ' Set the ignore count for the given breakpoint number. If '
3650n/a 'count is\n'
3651n/a ' omitted, the ignore count is set to 0. A breakpoint becomes '
3652n/a 'active\n'
3653n/a ' when the ignore count is zero. When non-zero, the count is\n'
3654n/a ' decremented each time the breakpoint is reached and the '
3655n/a 'breakpoint\n'
3656n/a ' is not disabled and any associated condition evaluates to '
3657n/a 'true.\n'
3658n/a '\n'
3659n/a 'condition bpnumber [condition]\n'
3660n/a '\n'
3661n/a ' Set a new *condition* for the breakpoint, an expression which '
3662n/a 'must\n'
3663n/a ' evaluate to true before the breakpoint is honored. If '
3664n/a '*condition*\n'
3665n/a ' is absent, any existing condition is removed; i.e., the '
3666n/a 'breakpoint\n'
3667n/a ' is made unconditional.\n'
3668n/a '\n'
3669n/a 'commands [bpnumber]\n'
3670n/a '\n'
3671n/a ' Specify a list of commands for breakpoint number *bpnumber*. '
3672n/a 'The\n'
3673n/a ' commands themselves appear on the following lines. Type a '
3674n/a 'line\n'
3675n/a ' containing just "end" to terminate the commands. An example:\n'
3676n/a '\n'
3677n/a ' (Pdb) commands 1\n'
3678n/a ' (com) p some_variable\n'
3679n/a ' (com) end\n'
3680n/a ' (Pdb)\n'
3681n/a '\n'
3682n/a ' To remove all commands from a breakpoint, type commands and '
3683n/a 'follow\n'
3684n/a ' it immediately with "end"; that is, give no commands.\n'
3685n/a '\n'
3686n/a ' With no *bpnumber* argument, commands refers to the last '
3687n/a 'breakpoint\n'
3688n/a ' set.\n'
3689n/a '\n'
3690n/a ' You can use breakpoint commands to start your program up '
3691n/a 'again.\n'
3692n/a ' Simply use the continue command, or step, or any other '
3693n/a 'command that\n'
3694n/a ' resumes execution.\n'
3695n/a '\n'
3696n/a ' Specifying any command resuming execution (currently '
3697n/a 'continue,\n'
3698n/a ' step, next, return, jump, quit and their abbreviations) '
3699n/a 'terminates\n'
3700n/a ' the command list (as if that command was immediately followed '
3701n/a 'by\n'
3702n/a ' end). This is because any time you resume execution (even '
3703n/a 'with a\n'
3704n/a ' simple next or step), you may encounter another '
3705n/a 'breakpoint--which\n'
3706n/a ' could have its own command list, leading to ambiguities about '
3707n/a 'which\n'
3708n/a ' list to execute.\n'
3709n/a '\n'
3710n/a " If you use the 'silent' command in the command list, the "
3711n/a 'usual\n'
3712n/a ' message about stopping at a breakpoint is not printed. This '
3713n/a 'may be\n'
3714n/a ' desirable for breakpoints that are to print a specific '
3715n/a 'message and\n'
3716n/a ' then continue. If none of the other commands print anything, '
3717n/a 'you\n'
3718n/a ' see no sign that the breakpoint was reached.\n'
3719n/a '\n'
3720n/a 's(tep)\n'
3721n/a '\n'
3722n/a ' Execute the current line, stop at the first possible '
3723n/a 'occasion\n'
3724n/a ' (either in a function that is called or on the next line in '
3725n/a 'the\n'
3726n/a ' current function).\n'
3727n/a '\n'
3728n/a 'n(ext)\n'
3729n/a '\n'
3730n/a ' Continue execution until the next line in the current '
3731n/a 'function is\n'
3732n/a ' reached or it returns. (The difference between "next" and '
3733n/a '"step"\n'
3734n/a ' is that "step" stops inside a called function, while "next"\n'
3735n/a ' executes called functions at (nearly) full speed, only '
3736n/a 'stopping at\n'
3737n/a ' the next line in the current function.)\n'
3738n/a '\n'
3739n/a 'unt(il) [lineno]\n'
3740n/a '\n'
3741n/a ' Without argument, continue execution until the line with a '
3742n/a 'number\n'
3743n/a ' greater than the current one is reached.\n'
3744n/a '\n'
3745n/a ' With a line number, continue execution until a line with a '
3746n/a 'number\n'
3747n/a ' greater or equal to that is reached. In both cases, also '
3748n/a 'stop when\n'
3749n/a ' the current frame returns.\n'
3750n/a '\n'
3751n/a ' Changed in version 3.2: Allow giving an explicit line '
3752n/a 'number.\n'
3753n/a '\n'
3754n/a 'r(eturn)\n'
3755n/a '\n'
3756n/a ' Continue execution until the current function returns.\n'
3757n/a '\n'
3758n/a 'c(ont(inue))\n'
3759n/a '\n'
3760n/a ' Continue execution, only stop when a breakpoint is '
3761n/a 'encountered.\n'
3762n/a '\n'
3763n/a 'j(ump) lineno\n'
3764n/a '\n'
3765n/a ' Set the next line that will be executed. Only available in '
3766n/a 'the\n'
3767n/a ' bottom-most frame. This lets you jump back and execute code '
3768n/a 'again,\n'
3769n/a " or jump forward to skip code that you don't want to run.\n"
3770n/a '\n'
3771n/a ' It should be noted that not all jumps are allowed -- for '
3772n/a 'instance\n'
3773n/a ' it is not possible to jump into the middle of a "for" loop or '
3774n/a 'out\n'
3775n/a ' of a "finally" clause.\n'
3776n/a '\n'
3777n/a 'l(ist) [first[, last]]\n'
3778n/a '\n'
3779n/a ' List source code for the current file. Without arguments, '
3780n/a 'list 11\n'
3781n/a ' lines around the current line or continue the previous '
3782n/a 'listing.\n'
3783n/a ' With "." as argument, list 11 lines around the current line. '
3784n/a 'With\n'
3785n/a ' one argument, list 11 lines around at that line. With two\n'
3786n/a ' arguments, list the given range; if the second argument is '
3787n/a 'less\n'
3788n/a ' than the first, it is interpreted as a count.\n'
3789n/a '\n'
3790n/a ' The current line in the current frame is indicated by "->". '
3791n/a 'If an\n'
3792n/a ' exception is being debugged, the line where the exception '
3793n/a 'was\n'
3794n/a ' originally raised or propagated is indicated by ">>", if it '
3795n/a 'differs\n'
3796n/a ' from the current line.\n'
3797n/a '\n'
3798n/a ' New in version 3.2: The ">>" marker.\n'
3799n/a '\n'
3800n/a 'll | longlist\n'
3801n/a '\n'
3802n/a ' List all source code for the current function or frame.\n'
3803n/a ' Interesting lines are marked as for "list".\n'
3804n/a '\n'
3805n/a ' New in version 3.2.\n'
3806n/a '\n'
3807n/a 'a(rgs)\n'
3808n/a '\n'
3809n/a ' Print the argument list of the current function.\n'
3810n/a '\n'
3811n/a 'p expression\n'
3812n/a '\n'
3813n/a ' Evaluate the *expression* in the current context and print '
3814n/a 'its\n'
3815n/a ' value.\n'
3816n/a '\n'
3817n/a ' Note: "print()" can also be used, but is not a debugger '
3818n/a 'command\n'
3819n/a ' --- this executes the Python "print()" function.\n'
3820n/a '\n'
3821n/a 'pp expression\n'
3822n/a '\n'
3823n/a ' Like the "p" command, except the value of the expression is '
3824n/a 'pretty-\n'
3825n/a ' printed using the "pprint" module.\n'
3826n/a '\n'
3827n/a 'whatis expression\n'
3828n/a '\n'
3829n/a ' Print the type of the *expression*.\n'
3830n/a '\n'
3831n/a 'source expression\n'
3832n/a '\n'
3833n/a ' Try to get source code for the given object and display it.\n'
3834n/a '\n'
3835n/a ' New in version 3.2.\n'
3836n/a '\n'
3837n/a 'display [expression]\n'
3838n/a '\n'
3839n/a ' Display the value of the expression if it changed, each time\n'
3840n/a ' execution stops in the current frame.\n'
3841n/a '\n'
3842n/a ' Without expression, list all display expressions for the '
3843n/a 'current\n'
3844n/a ' frame.\n'
3845n/a '\n'
3846n/a ' New in version 3.2.\n'
3847n/a '\n'
3848n/a 'undisplay [expression]\n'
3849n/a '\n'
3850n/a ' Do not display the expression any more in the current frame.\n'
3851n/a ' Without expression, clear all display expressions for the '
3852n/a 'current\n'
3853n/a ' frame.\n'
3854n/a '\n'
3855n/a ' New in version 3.2.\n'
3856n/a '\n'
3857n/a 'interact\n'
3858n/a '\n'
3859n/a ' Start an interactive interpreter (using the "code" module) '
3860n/a 'whose\n'
3861n/a ' global namespace contains all the (global and local) names '
3862n/a 'found in\n'
3863n/a ' the current scope.\n'
3864n/a '\n'
3865n/a ' New in version 3.2.\n'
3866n/a '\n'
3867n/a 'alias [name [command]]\n'
3868n/a '\n'
3869n/a ' Create an alias called *name* that executes *command*. The '
3870n/a 'command\n'
3871n/a ' must *not* be enclosed in quotes. Replaceable parameters can '
3872n/a 'be\n'
3873n/a ' indicated by "%1", "%2", and so on, while "%*" is replaced by '
3874n/a 'all\n'
3875n/a ' the parameters. If no command is given, the current alias '
3876n/a 'for\n'
3877n/a ' *name* is shown. If no arguments are given, all aliases are '
3878n/a 'listed.\n'
3879n/a '\n'
3880n/a ' Aliases may be nested and can contain anything that can be '
3881n/a 'legally\n'
3882n/a ' typed at the pdb prompt. Note that internal pdb commands '
3883n/a '*can* be\n'
3884n/a ' overridden by aliases. Such a command is then hidden until '
3885n/a 'the\n'
3886n/a ' alias is removed. Aliasing is recursively applied to the '
3887n/a 'first\n'
3888n/a ' word of the command line; all other words in the line are '
3889n/a 'left\n'
3890n/a ' alone.\n'
3891n/a '\n'
3892n/a ' As an example, here are two useful aliases (especially when '
3893n/a 'placed\n'
3894n/a ' in the ".pdbrc" file):\n'
3895n/a '\n'
3896n/a ' # Print instance variables (usage "pi classInst")\n'
3897n/a ' alias pi for k in %1.__dict__.keys(): '
3898n/a 'print("%1.",k,"=",%1.__dict__[k])\n'
3899n/a ' # Print instance variables in self\n'
3900n/a ' alias ps pi self\n'
3901n/a '\n'
3902n/a 'unalias name\n'
3903n/a '\n'
3904n/a ' Delete the specified alias.\n'
3905n/a '\n'
3906n/a '! statement\n'
3907n/a '\n'
3908n/a ' Execute the (one-line) *statement* in the context of the '
3909n/a 'current\n'
3910n/a ' stack frame. The exclamation point can be omitted unless the '
3911n/a 'first\n'
3912n/a ' word of the statement resembles a debugger command. To set '
3913n/a 'a\n'
3914n/a ' global variable, you can prefix the assignment command with '
3915n/a 'a\n'
3916n/a ' "global" statement on the same line, e.g.:\n'
3917n/a '\n'
3918n/a " (Pdb) global list_options; list_options = ['-l']\n"
3919n/a ' (Pdb)\n'
3920n/a '\n'
3921n/a 'run [args ...]\n'
3922n/a 'restart [args ...]\n'
3923n/a '\n'
3924n/a ' Restart the debugged Python program. If an argument is '
3925n/a 'supplied,\n'
3926n/a ' it is split with "shlex" and the result is used as the new\n'
3927n/a ' "sys.argv". History, breakpoints, actions and debugger '
3928n/a 'options are\n'
3929n/a ' preserved. "restart" is an alias for "run".\n'
3930n/a '\n'
3931n/a 'q(uit)\n'
3932n/a '\n'
3933n/a ' Quit from the debugger. The program being executed is '
3934n/a 'aborted.\n'
3935n/a '\n'
3936n/a '-[ Footnotes ]-\n'
3937n/a '\n'
3938n/a '[1] Whether a frame is considered to originate in a certain '
3939n/a 'module\n'
3940n/a ' is determined by the "__name__" in the frame globals.\n',
3941n/a 'del': '\n'
3942n/a 'The "del" statement\n'
3943n/a '*******************\n'
3944n/a '\n'
3945n/a ' del_stmt ::= "del" target_list\n'
3946n/a '\n'
3947n/a 'Deletion is recursively defined very similar to the way assignment '
3948n/a 'is\n'
3949n/a 'defined. Rather than spelling it out in full details, here are some\n'
3950n/a 'hints.\n'
3951n/a '\n'
3952n/a 'Deletion of a target list recursively deletes each target, from left\n'
3953n/a 'to right.\n'
3954n/a '\n'
3955n/a 'Deletion of a name removes the binding of that name from the local '
3956n/a 'or\n'
3957n/a 'global namespace, depending on whether the name occurs in a "global"\n'
3958n/a 'statement in the same code block. If the name is unbound, a\n'
3959n/a '"NameError" exception will be raised.\n'
3960n/a '\n'
3961n/a 'Deletion of attribute references, subscriptions and slicings is '
3962n/a 'passed\n'
3963n/a 'to the primary object involved; deletion of a slicing is in general\n'
3964n/a 'equivalent to assignment of an empty slice of the right type (but '
3965n/a 'even\n'
3966n/a 'this is determined by the sliced object).\n'
3967n/a '\n'
3968n/a 'Changed in version 3.2: Previously it was illegal to delete a name\n'
3969n/a 'from the local namespace if it occurs as a free variable in a nested\n'
3970n/a 'block.\n',
3971n/a 'dict': '\n'
3972n/a 'Dictionary displays\n'
3973n/a '*******************\n'
3974n/a '\n'
3975n/a 'A dictionary display is a possibly empty series of key/datum pairs\n'
3976n/a 'enclosed in curly braces:\n'
3977n/a '\n'
3978n/a ' dict_display ::= "{" [key_datum_list | dict_comprehension] '
3979n/a '"}"\n'
3980n/a ' key_datum_list ::= key_datum ("," key_datum)* [","]\n'
3981n/a ' key_datum ::= expression ":" expression | "**" or_expr\n'
3982n/a ' dict_comprehension ::= expression ":" expression comp_for\n'
3983n/a '\n'
3984n/a 'A dictionary display yields a new dictionary object.\n'
3985n/a '\n'
3986n/a 'If a comma-separated sequence of key/datum pairs is given, they are\n'
3987n/a 'evaluated from left to right to define the entries of the '
3988n/a 'dictionary:\n'
3989n/a 'each key object is used as a key into the dictionary to store the\n'
3990n/a 'corresponding datum. This means that you can specify the same key\n'
3991n/a "multiple times in the key/datum list, and the final dictionary's "
3992n/a 'value\n'
3993n/a 'for that key will be the last one given.\n'
3994n/a '\n'
3995n/a 'A double asterisk "**" denotes *dictionary unpacking*. Its operand\n'
3996n/a 'must be a *mapping*. Each mapping item is added to the new\n'
3997n/a 'dictionary. Later values replace values already set by earlier\n'
3998n/a 'key/datum pairs and earlier dictionary unpackings.\n'
3999n/a '\n'
4000n/a 'New in version 3.5: Unpacking into dictionary displays, originally\n'
4001n/a 'proposed by **PEP 448**.\n'
4002n/a '\n'
4003n/a 'A dict comprehension, in contrast to list and set comprehensions,\n'
4004n/a 'needs two expressions separated with a colon followed by the usual\n'
4005n/a '"for" and "if" clauses. When the comprehension is run, the '
4006n/a 'resulting\n'
4007n/a 'key and value elements are inserted in the new dictionary in the '
4008n/a 'order\n'
4009n/a 'they are produced.\n'
4010n/a '\n'
4011n/a 'Restrictions on the types of the key values are listed earlier in\n'
4012n/a 'section The standard type hierarchy. (To summarize, the key type\n'
4013n/a 'should be *hashable*, which excludes all mutable objects.) Clashes\n'
4014n/a 'between duplicate keys are not detected; the last datum (textually\n'
4015n/a 'rightmost in the display) stored for a given key value prevails.\n',
4016n/a 'dynamic-features': '\n'
4017n/a 'Interaction with dynamic features\n'
4018n/a '*********************************\n'
4019n/a '\n'
4020n/a 'Name resolution of free variables occurs at runtime, not '
4021n/a 'at compile\n'
4022n/a 'time. This means that the following code will print 42:\n'
4023n/a '\n'
4024n/a ' i = 10\n'
4025n/a ' def f():\n'
4026n/a ' print(i)\n'
4027n/a ' i = 42\n'
4028n/a ' f()\n'
4029n/a '\n'
4030n/a 'There are several cases where Python statements are '
4031n/a 'illegal when used\n'
4032n/a 'in conjunction with nested scopes that contain free '
4033n/a 'variables.\n'
4034n/a '\n'
4035n/a 'If a variable is referenced in an enclosing scope, it is '
4036n/a 'illegal to\n'
4037n/a 'delete the name. An error will be reported at compile '
4038n/a 'time.\n'
4039n/a '\n'
4040n/a 'The "eval()" and "exec()" functions do not have access '
4041n/a 'to the full\n'
4042n/a 'environment for resolving names. Names may be resolved '
4043n/a 'in the local\n'
4044n/a 'and global namespaces of the caller. Free variables are '
4045n/a 'not resolved\n'
4046n/a 'in the nearest enclosing namespace, but in the global '
4047n/a 'namespace. [1]\n'
4048n/a 'The "exec()" and "eval()" functions have optional '
4049n/a 'arguments to\n'
4050n/a 'override the global and local namespace. If only one '
4051n/a 'namespace is\n'
4052n/a 'specified, it is used for both.\n',
4053n/a 'else': '\n'
4054n/a 'The "if" statement\n'
4055n/a '******************\n'
4056n/a '\n'
4057n/a 'The "if" statement is used for conditional execution:\n'
4058n/a '\n'
4059n/a ' if_stmt ::= "if" expression ":" suite\n'
4060n/a ' ( "elif" expression ":" suite )*\n'
4061n/a ' ["else" ":" suite]\n'
4062n/a '\n'
4063n/a 'It selects exactly one of the suites by evaluating the expressions '
4064n/a 'one\n'
4065n/a 'by one until one is found to be true (see section Boolean '
4066n/a 'operations\n'
4067n/a 'for the definition of true and false); then that suite is executed\n'
4068n/a '(and no other part of the "if" statement is executed or evaluated).\n'
4069n/a 'If all expressions are false, the suite of the "else" clause, if\n'
4070n/a 'present, is executed.\n',
4071n/a 'exceptions': '\n'
4072n/a 'Exceptions\n'
4073n/a '**********\n'
4074n/a '\n'
4075n/a 'Exceptions are a means of breaking out of the normal flow of '
4076n/a 'control\n'
4077n/a 'of a code block in order to handle errors or other '
4078n/a 'exceptional\n'
4079n/a 'conditions. An exception is *raised* at the point where the '
4080n/a 'error is\n'
4081n/a 'detected; it may be *handled* by the surrounding code block or '
4082n/a 'by any\n'
4083n/a 'code block that directly or indirectly invoked the code block '
4084n/a 'where\n'
4085n/a 'the error occurred.\n'
4086n/a '\n'
4087n/a 'The Python interpreter raises an exception when it detects a '
4088n/a 'run-time\n'
4089n/a 'error (such as division by zero). A Python program can also\n'
4090n/a 'explicitly raise an exception with the "raise" statement. '
4091n/a 'Exception\n'
4092n/a 'handlers are specified with the "try" ... "except" statement. '
4093n/a 'The\n'
4094n/a '"finally" clause of such a statement can be used to specify '
4095n/a 'cleanup\n'
4096n/a 'code which does not handle the exception, but is executed '
4097n/a 'whether an\n'
4098n/a 'exception occurred or not in the preceding code.\n'
4099n/a '\n'
4100n/a 'Python uses the "termination" model of error handling: an '
4101n/a 'exception\n'
4102n/a 'handler can find out what happened and continue execution at '
4103n/a 'an outer\n'
4104n/a 'level, but it cannot repair the cause of the error and retry '
4105n/a 'the\n'
4106n/a 'failing operation (except by re-entering the offending piece '
4107n/a 'of code\n'
4108n/a 'from the top).\n'
4109n/a '\n'
4110n/a 'When an exception is not handled at all, the interpreter '
4111n/a 'terminates\n'
4112n/a 'execution of the program, or returns to its interactive main '
4113n/a 'loop. In\n'
4114n/a 'either case, it prints a stack backtrace, except when the '
4115n/a 'exception is\n'
4116n/a '"SystemExit".\n'
4117n/a '\n'
4118n/a 'Exceptions are identified by class instances. The "except" '
4119n/a 'clause is\n'
4120n/a 'selected depending on the class of the instance: it must '
4121n/a 'reference the\n'
4122n/a 'class of the instance or a base class thereof. The instance '
4123n/a 'can be\n'
4124n/a 'received by the handler and can carry additional information '
4125n/a 'about the\n'
4126n/a 'exceptional condition.\n'
4127n/a '\n'
4128n/a 'Note: Exception messages are not part of the Python API. '
4129n/a 'Their\n'
4130n/a ' contents may change from one version of Python to the next '
4131n/a 'without\n'
4132n/a ' warning and should not be relied on by code which will run '
4133n/a 'under\n'
4134n/a ' multiple versions of the interpreter.\n'
4135n/a '\n'
4136n/a 'See also the description of the "try" statement in section The '
4137n/a 'try\n'
4138n/a 'statement and "raise" statement in section The raise '
4139n/a 'statement.\n'
4140n/a '\n'
4141n/a '-[ Footnotes ]-\n'
4142n/a '\n'
4143n/a '[1] This limitation occurs because the code that is executed '
4144n/a 'by\n'
4145n/a ' these operations is not available at the time the module '
4146n/a 'is\n'
4147n/a ' compiled.\n',
4148n/a 'execmodel': '\n'
4149n/a 'Execution model\n'
4150n/a '***************\n'
4151n/a '\n'
4152n/a '\n'
4153n/a 'Structure of a program\n'
4154n/a '======================\n'
4155n/a '\n'
4156n/a 'A Python program is constructed from code blocks. A *block* is '
4157n/a 'a piece\n'
4158n/a 'of Python program text that is executed as a unit. The '
4159n/a 'following are\n'
4160n/a 'blocks: a module, a function body, and a class definition. '
4161n/a 'Each\n'
4162n/a 'command typed interactively is a block. A script file (a file '
4163n/a 'given\n'
4164n/a 'as standard input to the interpreter or specified as a command '
4165n/a 'line\n'
4166n/a 'argument to the interpreter) is a code block. A script command '
4167n/a '(a\n'
4168n/a 'command specified on the interpreter command line with the '
4169n/a "'**-c**'\n"
4170n/a 'option) is a code block. The string argument passed to the '
4171n/a 'built-in\n'
4172n/a 'functions "eval()" and "exec()" is a code block.\n'
4173n/a '\n'
4174n/a 'A code block is executed in an *execution frame*. A frame '
4175n/a 'contains\n'
4176n/a 'some administrative information (used for debugging) and '
4177n/a 'determines\n'
4178n/a "where and how execution continues after the code block's "
4179n/a 'execution has\n'
4180n/a 'completed.\n'
4181n/a '\n'
4182n/a '\n'
4183n/a 'Naming and binding\n'
4184n/a '==================\n'
4185n/a '\n'
4186n/a '\n'
4187n/a 'Binding of names\n'
4188n/a '----------------\n'
4189n/a '\n'
4190n/a '*Names* refer to objects. Names are introduced by name '
4191n/a 'binding\n'
4192n/a 'operations.\n'
4193n/a '\n'
4194n/a 'The following constructs bind names: formal parameters to '
4195n/a 'functions,\n'
4196n/a '"import" statements, class and function definitions (these bind '
4197n/a 'the\n'
4198n/a 'class or function name in the defining block), and targets that '
4199n/a 'are\n'
4200n/a 'identifiers if occurring in an assignment, "for" loop header, '
4201n/a 'or after\n'
4202n/a '"as" in a "with" statement or "except" clause. The "import" '
4203n/a 'statement\n'
4204n/a 'of the form "from ... import *" binds all names defined in the\n'
4205n/a 'imported module, except those beginning with an underscore. '
4206n/a 'This form\n'
4207n/a 'may only be used at the module level.\n'
4208n/a '\n'
4209n/a 'A target occurring in a "del" statement is also considered '
4210n/a 'bound for\n'
4211n/a 'this purpose (though the actual semantics are to unbind the '
4212n/a 'name).\n'
4213n/a '\n'
4214n/a 'Each assignment or import statement occurs within a block '
4215n/a 'defined by a\n'
4216n/a 'class or function definition or at the module level (the '
4217n/a 'top-level\n'
4218n/a 'code block).\n'
4219n/a '\n'
4220n/a 'If a name is bound in a block, it is a local variable of that '
4221n/a 'block,\n'
4222n/a 'unless declared as "nonlocal" or "global". If a name is bound '
4223n/a 'at the\n'
4224n/a 'module level, it is a global variable. (The variables of the '
4225n/a 'module\n'
4226n/a 'code block are local and global.) If a variable is used in a '
4227n/a 'code\n'
4228n/a 'block but not defined there, it is a *free variable*.\n'
4229n/a '\n'
4230n/a 'Each occurrence of a name in the program text refers to the '
4231n/a '*binding*\n'
4232n/a 'of that name established by the following name resolution '
4233n/a 'rules.\n'
4234n/a '\n'
4235n/a '\n'
4236n/a 'Resolution of names\n'
4237n/a '-------------------\n'
4238n/a '\n'
4239n/a 'A *scope* defines the visibility of a name within a block. If '
4240n/a 'a local\n'
4241n/a 'variable is defined in a block, its scope includes that block. '
4242n/a 'If the\n'
4243n/a 'definition occurs in a function block, the scope extends to any '
4244n/a 'blocks\n'
4245n/a 'contained within the defining one, unless a contained block '
4246n/a 'introduces\n'
4247n/a 'a different binding for the name.\n'
4248n/a '\n'
4249n/a 'When a name is used in a code block, it is resolved using the '
4250n/a 'nearest\n'
4251n/a 'enclosing scope. The set of all such scopes visible to a code '
4252n/a 'block\n'
4253n/a "is called the block's *environment*.\n"
4254n/a '\n'
4255n/a 'When a name is not found at all, a "NameError" exception is '
4256n/a 'raised. If\n'
4257n/a 'the current scope is a function scope, and the name refers to a '
4258n/a 'local\n'
4259n/a 'variable that has not yet been bound to a value at the point '
4260n/a 'where the\n'
4261n/a 'name is used, an "UnboundLocalError" exception is raised.\n'
4262n/a '"UnboundLocalError" is a subclass of "NameError".\n'
4263n/a '\n'
4264n/a 'If a name binding operation occurs anywhere within a code '
4265n/a 'block, all\n'
4266n/a 'uses of the name within the block are treated as references to '
4267n/a 'the\n'
4268n/a 'current block. This can lead to errors when a name is used '
4269n/a 'within a\n'
4270n/a 'block before it is bound. This rule is subtle. Python lacks\n'
4271n/a 'declarations and allows name binding operations to occur '
4272n/a 'anywhere\n'
4273n/a 'within a code block. The local variables of a code block can '
4274n/a 'be\n'
4275n/a 'determined by scanning the entire text of the block for name '
4276n/a 'binding\n'
4277n/a 'operations.\n'
4278n/a '\n'
4279n/a 'If the "global" statement occurs within a block, all uses of '
4280n/a 'the name\n'
4281n/a 'specified in the statement refer to the binding of that name in '
4282n/a 'the\n'
4283n/a 'top-level namespace. Names are resolved in the top-level '
4284n/a 'namespace by\n'
4285n/a 'searching the global namespace, i.e. the namespace of the '
4286n/a 'module\n'
4287n/a 'containing the code block, and the builtins namespace, the '
4288n/a 'namespace\n'
4289n/a 'of the module "builtins". The global namespace is searched '
4290n/a 'first. If\n'
4291n/a 'the name is not found there, the builtins namespace is '
4292n/a 'searched. The\n'
4293n/a '"global" statement must precede all uses of the name.\n'
4294n/a '\n'
4295n/a 'The "global" statement has the same scope as a name binding '
4296n/a 'operation\n'
4297n/a 'in the same block. If the nearest enclosing scope for a free '
4298n/a 'variable\n'
4299n/a 'contains a global statement, the free variable is treated as a '
4300n/a 'global.\n'
4301n/a '\n'
4302n/a 'The "nonlocal" statement causes corresponding names to refer '
4303n/a 'to\n'
4304n/a 'previously bound variables in the nearest enclosing function '
4305n/a 'scope.\n'
4306n/a '"SyntaxError" is raised at compile time if the given name does '
4307n/a 'not\n'
4308n/a 'exist in any enclosing function scope.\n'
4309n/a '\n'
4310n/a 'The namespace for a module is automatically created the first '
4311n/a 'time a\n'
4312n/a 'module is imported. The main module for a script is always '
4313n/a 'called\n'
4314n/a '"__main__".\n'
4315n/a '\n'
4316n/a 'Class definition blocks and arguments to "exec()" and "eval()" '
4317n/a 'are\n'
4318n/a 'special in the context of name resolution. A class definition '
4319n/a 'is an\n'
4320n/a 'executable statement that may use and define names. These '
4321n/a 'references\n'
4322n/a 'follow the normal rules for name resolution with an exception '
4323n/a 'that\n'
4324n/a 'unbound local variables are looked up in the global namespace. '
4325n/a 'The\n'
4326n/a 'namespace of the class definition becomes the attribute '
4327n/a 'dictionary of\n'
4328n/a 'the class. The scope of names defined in a class block is '
4329n/a 'limited to\n'
4330n/a 'the class block; it does not extend to the code blocks of '
4331n/a 'methods --\n'
4332n/a 'this includes comprehensions and generator expressions since '
4333n/a 'they are\n'
4334n/a 'implemented using a function scope. This means that the '
4335n/a 'following\n'
4336n/a 'will fail:\n'
4337n/a '\n'
4338n/a ' class A:\n'
4339n/a ' a = 42\n'
4340n/a ' b = list(a + i for i in range(10))\n'
4341n/a '\n'
4342n/a '\n'
4343n/a 'Builtins and restricted execution\n'
4344n/a '---------------------------------\n'
4345n/a '\n'
4346n/a 'The builtins namespace associated with the execution of a code '
4347n/a 'block\n'
4348n/a 'is actually found by looking up the name "__builtins__" in its '
4349n/a 'global\n'
4350n/a 'namespace; this should be a dictionary or a module (in the '
4351n/a 'latter case\n'
4352n/a "the module's dictionary is used). By default, when in the "
4353n/a '"__main__"\n'
4354n/a 'module, "__builtins__" is the built-in module "builtins"; when '
4355n/a 'in any\n'
4356n/a 'other module, "__builtins__" is an alias for the dictionary of '
4357n/a 'the\n'
4358n/a '"builtins" module itself. "__builtins__" can be set to a '
4359n/a 'user-created\n'
4360n/a 'dictionary to create a weak form of restricted execution.\n'
4361n/a '\n'
4362n/a '**CPython implementation detail:** Users should not touch\n'
4363n/a '"__builtins__"; it is strictly an implementation detail. '
4364n/a 'Users\n'
4365n/a 'wanting to override values in the builtins namespace should '
4366n/a '"import"\n'
4367n/a 'the "builtins" module and modify its attributes appropriately.\n'
4368n/a '\n'
4369n/a '\n'
4370n/a 'Interaction with dynamic features\n'
4371n/a '---------------------------------\n'
4372n/a '\n'
4373n/a 'Name resolution of free variables occurs at runtime, not at '
4374n/a 'compile\n'
4375n/a 'time. This means that the following code will print 42:\n'
4376n/a '\n'
4377n/a ' i = 10\n'
4378n/a ' def f():\n'
4379n/a ' print(i)\n'
4380n/a ' i = 42\n'
4381n/a ' f()\n'
4382n/a '\n'
4383n/a 'There are several cases where Python statements are illegal '
4384n/a 'when used\n'
4385n/a 'in conjunction with nested scopes that contain free variables.\n'
4386n/a '\n'
4387n/a 'If a variable is referenced in an enclosing scope, it is '
4388n/a 'illegal to\n'
4389n/a 'delete the name. An error will be reported at compile time.\n'
4390n/a '\n'
4391n/a 'The "eval()" and "exec()" functions do not have access to the '
4392n/a 'full\n'
4393n/a 'environment for resolving names. Names may be resolved in the '
4394n/a 'local\n'
4395n/a 'and global namespaces of the caller. Free variables are not '
4396n/a 'resolved\n'
4397n/a 'in the nearest enclosing namespace, but in the global '
4398n/a 'namespace. [1]\n'
4399n/a 'The "exec()" and "eval()" functions have optional arguments to\n'
4400n/a 'override the global and local namespace. If only one namespace '
4401n/a 'is\n'
4402n/a 'specified, it is used for both.\n'
4403n/a '\n'
4404n/a '\n'
4405n/a 'Exceptions\n'
4406n/a '==========\n'
4407n/a '\n'
4408n/a 'Exceptions are a means of breaking out of the normal flow of '
4409n/a 'control\n'
4410n/a 'of a code block in order to handle errors or other exceptional\n'
4411n/a 'conditions. An exception is *raised* at the point where the '
4412n/a 'error is\n'
4413n/a 'detected; it may be *handled* by the surrounding code block or '
4414n/a 'by any\n'
4415n/a 'code block that directly or indirectly invoked the code block '
4416n/a 'where\n'
4417n/a 'the error occurred.\n'
4418n/a '\n'
4419n/a 'The Python interpreter raises an exception when it detects a '
4420n/a 'run-time\n'
4421n/a 'error (such as division by zero). A Python program can also\n'
4422n/a 'explicitly raise an exception with the "raise" statement. '
4423n/a 'Exception\n'
4424n/a 'handlers are specified with the "try" ... "except" statement. '
4425n/a 'The\n'
4426n/a '"finally" clause of such a statement can be used to specify '
4427n/a 'cleanup\n'
4428n/a 'code which does not handle the exception, but is executed '
4429n/a 'whether an\n'
4430n/a 'exception occurred or not in the preceding code.\n'
4431n/a '\n'
4432n/a 'Python uses the "termination" model of error handling: an '
4433n/a 'exception\n'
4434n/a 'handler can find out what happened and continue execution at an '
4435n/a 'outer\n'
4436n/a 'level, but it cannot repair the cause of the error and retry '
4437n/a 'the\n'
4438n/a 'failing operation (except by re-entering the offending piece of '
4439n/a 'code\n'
4440n/a 'from the top).\n'
4441n/a '\n'
4442n/a 'When an exception is not handled at all, the interpreter '
4443n/a 'terminates\n'
4444n/a 'execution of the program, or returns to its interactive main '
4445n/a 'loop. In\n'
4446n/a 'either case, it prints a stack backtrace, except when the '
4447n/a 'exception is\n'
4448n/a '"SystemExit".\n'
4449n/a '\n'
4450n/a 'Exceptions are identified by class instances. The "except" '
4451n/a 'clause is\n'
4452n/a 'selected depending on the class of the instance: it must '
4453n/a 'reference the\n'
4454n/a 'class of the instance or a base class thereof. The instance '
4455n/a 'can be\n'
4456n/a 'received by the handler and can carry additional information '
4457n/a 'about the\n'
4458n/a 'exceptional condition.\n'
4459n/a '\n'
4460n/a 'Note: Exception messages are not part of the Python API. '
4461n/a 'Their\n'
4462n/a ' contents may change from one version of Python to the next '
4463n/a 'without\n'
4464n/a ' warning and should not be relied on by code which will run '
4465n/a 'under\n'
4466n/a ' multiple versions of the interpreter.\n'
4467n/a '\n'
4468n/a 'See also the description of the "try" statement in section The '
4469n/a 'try\n'
4470n/a 'statement and "raise" statement in section The raise '
4471n/a 'statement.\n'
4472n/a '\n'
4473n/a '-[ Footnotes ]-\n'
4474n/a '\n'
4475n/a '[1] This limitation occurs because the code that is executed '
4476n/a 'by\n'
4477n/a ' these operations is not available at the time the module '
4478n/a 'is\n'
4479n/a ' compiled.\n',
4480n/a 'exprlists': '\n'
4481n/a 'Expression lists\n'
4482n/a '****************\n'
4483n/a '\n'
4484n/a ' expression_list ::= expression ( "," expression )* [","]\n'
4485n/a ' starred_list ::= starred_item ( "," starred_item )* '
4486n/a '[","]\n'
4487n/a ' starred_expression ::= expression | ( starred_item "," )* '
4488n/a '[starred_item]\n'
4489n/a ' starred_item ::= expression | "*" or_expr\n'
4490n/a '\n'
4491n/a 'Except when part of a list or set display, an expression list\n'
4492n/a 'containing at least one comma yields a tuple. The length of '
4493n/a 'the tuple\n'
4494n/a 'is the number of expressions in the list. The expressions are\n'
4495n/a 'evaluated from left to right.\n'
4496n/a '\n'
4497n/a 'An asterisk "*" denotes *iterable unpacking*. Its operand must '
4498n/a 'be an\n'
4499n/a '*iterable*. The iterable is expanded into a sequence of items, '
4500n/a 'which\n'
4501n/a 'are included in the new tuple, list, or set, at the site of '
4502n/a 'the\n'
4503n/a 'unpacking.\n'
4504n/a '\n'
4505n/a 'New in version 3.5: Iterable unpacking in expression lists, '
4506n/a 'originally\n'
4507n/a 'proposed by **PEP 448**.\n'
4508n/a '\n'
4509n/a 'The trailing comma is required only to create a single tuple '
4510n/a '(a.k.a. a\n'
4511n/a '*singleton*); it is optional in all other cases. A single '
4512n/a 'expression\n'
4513n/a "without a trailing comma doesn't create a tuple, but rather "
4514n/a 'yields the\n'
4515n/a 'value of that expression. (To create an empty tuple, use an '
4516n/a 'empty pair\n'
4517n/a 'of parentheses: "()".)\n',
4518n/a 'floating': '\n'
4519n/a 'Floating point literals\n'
4520n/a '***********************\n'
4521n/a '\n'
4522n/a 'Floating point literals are described by the following lexical\n'
4523n/a 'definitions:\n'
4524n/a '\n'
4525n/a ' floatnumber ::= pointfloat | exponentfloat\n'
4526n/a ' pointfloat ::= [digitpart] fraction | digitpart "."\n'
4527n/a ' exponentfloat ::= (digitpart | pointfloat) exponent\n'
4528n/a ' digitpart ::= digit (["_"] digit)*\n'
4529n/a ' fraction ::= "." digitpart\n'
4530n/a ' exponent ::= ("e" | "E") ["+" | "-"] digitpart\n'
4531n/a '\n'
4532n/a 'Note that the integer and exponent parts are always interpreted '
4533n/a 'using\n'
4534n/a 'radix 10. For example, "077e010" is legal, and denotes the same '
4535n/a 'number\n'
4536n/a 'as "77e10". The allowed range of floating point literals is\n'
4537n/a 'implementation-dependent. As in integer literals, underscores '
4538n/a 'are\n'
4539n/a 'supported for digit grouping.\n'
4540n/a '\n'
4541n/a 'Some examples of floating point literals:\n'
4542n/a '\n'
4543n/a ' 3.14 10. .001 1e100 3.14e-10 0e0 '
4544n/a '3.14_15_93\n'
4545n/a '\n'
4546n/a 'Note that numeric literals do not include a sign; a phrase like '
4547n/a '"-1"\n'
4548n/a 'is actually an expression composed of the unary operator "-" and '
4549n/a 'the\n'
4550n/a 'literal "1".\n'
4551n/a '\n'
4552n/a 'Changed in version 3.6: Underscores are now allowed for '
4553n/a 'grouping\n'
4554n/a 'purposes in literals.\n',
4555n/a 'for': '\n'
4556n/a 'The "for" statement\n'
4557n/a '*******************\n'
4558n/a '\n'
4559n/a 'The "for" statement is used to iterate over the elements of a '
4560n/a 'sequence\n'
4561n/a '(such as a string, tuple or list) or other iterable object:\n'
4562n/a '\n'
4563n/a ' for_stmt ::= "for" target_list "in" expression_list ":" suite\n'
4564n/a ' ["else" ":" suite]\n'
4565n/a '\n'
4566n/a 'The expression list is evaluated once; it should yield an iterable\n'
4567n/a 'object. An iterator is created for the result of the\n'
4568n/a '"expression_list". The suite is then executed once for each item\n'
4569n/a 'provided by the iterator, in the order returned by the iterator. '
4570n/a 'Each\n'
4571n/a 'item in turn is assigned to the target list using the standard rules\n'
4572n/a 'for assignments (see Assignment statements), and then the suite is\n'
4573n/a 'executed. When the items are exhausted (which is immediately when '
4574n/a 'the\n'
4575n/a 'sequence is empty or an iterator raises a "StopIteration" '
4576n/a 'exception),\n'
4577n/a 'the suite in the "else" clause, if present, is executed, and the '
4578n/a 'loop\n'
4579n/a 'terminates.\n'
4580n/a '\n'
4581n/a 'A "break" statement executed in the first suite terminates the loop\n'
4582n/a 'without executing the "else" clause\'s suite. A "continue" '
4583n/a 'statement\n'
4584n/a 'executed in the first suite skips the rest of the suite and '
4585n/a 'continues\n'
4586n/a 'with the next item, or with the "else" clause if there is no next\n'
4587n/a 'item.\n'
4588n/a '\n'
4589n/a 'The for-loop makes assignments to the variables(s) in the target '
4590n/a 'list.\n'
4591n/a 'This overwrites all previous assignments to those variables '
4592n/a 'including\n'
4593n/a 'those made in the suite of the for-loop:\n'
4594n/a '\n'
4595n/a ' for i in range(10):\n'
4596n/a ' print(i)\n'
4597n/a ' i = 5 # this will not affect the for-loop\n'
4598n/a ' # because i will be overwritten with the '
4599n/a 'next\n'
4600n/a ' # index in the range\n'
4601n/a '\n'
4602n/a 'Names in the target list are not deleted when the loop is finished,\n'
4603n/a 'but if the sequence is empty, they will not have been assigned to at\n'
4604n/a 'all by the loop. Hint: the built-in function "range()" returns an\n'
4605n/a 'iterator of integers suitable to emulate the effect of Pascal\'s "for '
4606n/a 'i\n'
4607n/a ':= a to b do"; e.g., "list(range(3))" returns the list "[0, 1, 2]".\n'
4608n/a '\n'
4609n/a 'Note: There is a subtlety when the sequence is being modified by the\n'
4610n/a ' loop (this can only occur for mutable sequences, i.e. lists). An\n'
4611n/a ' internal counter is used to keep track of which item is used next,\n'
4612n/a ' and this is incremented on each iteration. When this counter has\n'
4613n/a ' reached the length of the sequence the loop terminates. This '
4614n/a 'means\n'
4615n/a ' that if the suite deletes the current (or a previous) item from '
4616n/a 'the\n'
4617n/a ' sequence, the next item will be skipped (since it gets the index '
4618n/a 'of\n'
4619n/a ' the current item which has already been treated). Likewise, if '
4620n/a 'the\n'
4621n/a ' suite inserts an item in the sequence before the current item, the\n'
4622n/a ' current item will be treated again the next time through the loop.\n'
4623n/a ' This can lead to nasty bugs that can be avoided by making a\n'
4624n/a ' temporary copy using a slice of the whole sequence, e.g.,\n'
4625n/a '\n'
4626n/a ' for x in a[:]:\n'
4627n/a ' if x < 0: a.remove(x)\n',
4628n/a 'formatstrings': '\n'
4629n/a 'Format String Syntax\n'
4630n/a '********************\n'
4631n/a '\n'
4632n/a 'The "str.format()" method and the "Formatter" class share '
4633n/a 'the same\n'
4634n/a 'syntax for format strings (although in the case of '
4635n/a '"Formatter",\n'
4636n/a 'subclasses can define their own format string syntax). The '
4637n/a 'syntax is\n'
4638n/a 'related to that of formatted string literals, but there '
4639n/a 'are\n'
4640n/a 'differences.\n'
4641n/a '\n'
4642n/a 'Format strings contain "replacement fields" surrounded by '
4643n/a 'curly braces\n'
4644n/a '"{}". Anything that is not contained in braces is '
4645n/a 'considered literal\n'
4646n/a 'text, which is copied unchanged to the output. If you need '
4647n/a 'to include\n'
4648n/a 'a brace character in the literal text, it can be escaped by '
4649n/a 'doubling:\n'
4650n/a '"{{" and "}}".\n'
4651n/a '\n'
4652n/a 'The grammar for a replacement field is as follows:\n'
4653n/a '\n'
4654n/a ' replacement_field ::= "{" [field_name] ["!" '
4655n/a 'conversion] [":" format_spec] "}"\n'
4656n/a ' field_name ::= arg_name ("." attribute_name | '
4657n/a '"[" element_index "]")*\n'
4658n/a ' arg_name ::= [identifier | integer]\n'
4659n/a ' attribute_name ::= identifier\n'
4660n/a ' element_index ::= integer | index_string\n'
4661n/a ' index_string ::= <any source character except '
4662n/a '"]"> +\n'
4663n/a ' conversion ::= "r" | "s" | "a"\n'
4664n/a ' format_spec ::= <described in the next '
4665n/a 'section>\n'
4666n/a '\n'
4667n/a 'In less formal terms, the replacement field can start with '
4668n/a 'a\n'
4669n/a '*field_name* that specifies the object whose value is to be '
4670n/a 'formatted\n'
4671n/a 'and inserted into the output instead of the replacement '
4672n/a 'field. The\n'
4673n/a '*field_name* is optionally followed by a *conversion* '
4674n/a 'field, which is\n'
4675n/a 'preceded by an exclamation point "\'!\'", and a '
4676n/a '*format_spec*, which is\n'
4677n/a 'preceded by a colon "\':\'". These specify a non-default '
4678n/a 'format for the\n'
4679n/a 'replacement value.\n'
4680n/a '\n'
4681n/a 'See also the Format Specification Mini-Language section.\n'
4682n/a '\n'
4683n/a 'The *field_name* itself begins with an *arg_name* that is '
4684n/a 'either a\n'
4685n/a "number or a keyword. If it's a number, it refers to a "
4686n/a 'positional\n'
4687n/a "argument, and if it's a keyword, it refers to a named "
4688n/a 'keyword\n'
4689n/a 'argument. If the numerical arg_names in a format string '
4690n/a 'are 0, 1, 2,\n'
4691n/a '... in sequence, they can all be omitted (not just some) '
4692n/a 'and the\n'
4693n/a 'numbers 0, 1, 2, ... will be automatically inserted in that '
4694n/a 'order.\n'
4695n/a 'Because *arg_name* is not quote-delimited, it is not '
4696n/a 'possible to\n'
4697n/a 'specify arbitrary dictionary keys (e.g., the strings '
4698n/a '"\'10\'" or\n'
4699n/a '"\':-]\'") within a format string. The *arg_name* can be '
4700n/a 'followed by any\n'
4701n/a 'number of index or attribute expressions. An expression of '
4702n/a 'the form\n'
4703n/a '"\'.name\'" selects the named attribute using "getattr()", '
4704n/a 'while an\n'
4705n/a 'expression of the form "\'[index]\'" does an index lookup '
4706n/a 'using\n'
4707n/a '"__getitem__()".\n'
4708n/a '\n'
4709n/a 'Changed in version 3.1: The positional argument specifiers '
4710n/a 'can be\n'
4711n/a 'omitted, so "\'{} {}\'" is equivalent to "\'{0} {1}\'".\n'
4712n/a '\n'
4713n/a 'Some simple format string examples:\n'
4714n/a '\n'
4715n/a ' "First, thou shalt count to {0}" # References first '
4716n/a 'positional argument\n'
4717n/a ' "Bring me a {}" # Implicitly '
4718n/a 'references the first positional argument\n'
4719n/a ' "From {} to {}" # Same as "From {0} to '
4720n/a '{1}"\n'
4721n/a ' "My quest is {name}" # References keyword '
4722n/a "argument 'name'\n"
4723n/a ' "Weight in tons {0.weight}" # \'weight\' attribute '
4724n/a 'of first positional arg\n'
4725n/a ' "Units destroyed: {players[0]}" # First element of '
4726n/a "keyword argument 'players'.\n"
4727n/a '\n'
4728n/a 'The *conversion* field causes a type coercion before '
4729n/a 'formatting.\n'
4730n/a 'Normally, the job of formatting a value is done by the '
4731n/a '"__format__()"\n'
4732n/a 'method of the value itself. However, in some cases it is '
4733n/a 'desirable to\n'
4734n/a 'force a type to be formatted as a string, overriding its '
4735n/a 'own\n'
4736n/a 'definition of formatting. By converting the value to a '
4737n/a 'string before\n'
4738n/a 'calling "__format__()", the normal formatting logic is '
4739n/a 'bypassed.\n'
4740n/a '\n'
4741n/a 'Three conversion flags are currently supported: "\'!s\'" '
4742n/a 'which calls\n'
4743n/a '"str()" on the value, "\'!r\'" which calls "repr()" and '
4744n/a '"\'!a\'" which\n'
4745n/a 'calls "ascii()".\n'
4746n/a '\n'
4747n/a 'Some examples:\n'
4748n/a '\n'
4749n/a ' "Harold\'s a clever {0!s}" # Calls str() on the '
4750n/a 'argument first\n'
4751n/a ' "Bring out the holy {name!r}" # Calls repr() on the '
4752n/a 'argument first\n'
4753n/a ' "More {!a}" # Calls ascii() on the '
4754n/a 'argument first\n'
4755n/a '\n'
4756n/a 'The *format_spec* field contains a specification of how the '
4757n/a 'value\n'
4758n/a 'should be presented, including such details as field width, '
4759n/a 'alignment,\n'
4760n/a 'padding, decimal precision and so on. Each value type can '
4761n/a 'define its\n'
4762n/a 'own "formatting mini-language" or interpretation of the '
4763n/a '*format_spec*.\n'
4764n/a '\n'
4765n/a 'Most built-in types support a common formatting '
4766n/a 'mini-language, which\n'
4767n/a 'is described in the next section.\n'
4768n/a '\n'
4769n/a 'A *format_spec* field can also include nested replacement '
4770n/a 'fields\n'
4771n/a 'within it. These nested replacement fields may contain a '
4772n/a 'field name,\n'
4773n/a 'conversion flag and format specification, but deeper '
4774n/a 'nesting is not\n'
4775n/a 'allowed. The replacement fields within the format_spec '
4776n/a 'are\n'
4777n/a 'substituted before the *format_spec* string is interpreted. '
4778n/a 'This\n'
4779n/a 'allows the formatting of a value to be dynamically '
4780n/a 'specified.\n'
4781n/a '\n'
4782n/a 'See the Format examples section for some examples.\n'
4783n/a '\n'
4784n/a '\n'
4785n/a 'Format Specification Mini-Language\n'
4786n/a '==================================\n'
4787n/a '\n'
4788n/a '"Format specifications" are used within replacement fields '
4789n/a 'contained\n'
4790n/a 'within a format string to define how individual values are '
4791n/a 'presented\n'
4792n/a '(see Format String Syntax and Formatted string literals). '
4793n/a 'They can\n'
4794n/a 'also be passed directly to the built-in "format()" '
4795n/a 'function. Each\n'
4796n/a 'formattable type may define how the format specification is '
4797n/a 'to be\n'
4798n/a 'interpreted.\n'
4799n/a '\n'
4800n/a 'Most built-in types implement the following options for '
4801n/a 'format\n'
4802n/a 'specifications, although some of the formatting options are '
4803n/a 'only\n'
4804n/a 'supported by the numeric types.\n'
4805n/a '\n'
4806n/a 'A general convention is that an empty format string ("""") '
4807n/a 'produces\n'
4808n/a 'the same result as if you had called "str()" on the value. '
4809n/a 'A non-empty\n'
4810n/a 'format string typically modifies the result.\n'
4811n/a '\n'
4812n/a 'The general form of a *standard format specifier* is:\n'
4813n/a '\n'
4814n/a ' format_spec ::= '
4815n/a '[[fill]align][sign][#][0][width][grouping_option][.precision][type]\n'
4816n/a ' fill ::= <any character>\n'
4817n/a ' align ::= "<" | ">" | "=" | "^"\n'
4818n/a ' sign ::= "+" | "-" | " "\n'
4819n/a ' width ::= integer\n'
4820n/a ' grouping_option ::= "_" | ","\n'
4821n/a ' precision ::= integer\n'
4822n/a ' type ::= "b" | "c" | "d" | "e" | "E" | "f" | '
4823n/a '"F" | "g" | "G" | "n" | "o" | "s" | "x" | "X" | "%"\n'
4824n/a '\n'
4825n/a 'If a valid *align* value is specified, it can be preceded '
4826n/a 'by a *fill*\n'
4827n/a 'character that can be any character and defaults to a space '
4828n/a 'if\n'
4829n/a 'omitted. It is not possible to use a literal curly brace '
4830n/a '(""{"" or\n'
4831n/a '""}"") as the *fill* character in a formatted string '
4832n/a 'literal or when\n'
4833n/a 'using the "str.format()" method. However, it is possible '
4834n/a 'to insert a\n'
4835n/a 'curly brace with a nested replacement field. This '
4836n/a "limitation doesn't\n"
4837n/a 'affect the "format()" function.\n'
4838n/a '\n'
4839n/a 'The meaning of the various alignment options is as '
4840n/a 'follows:\n'
4841n/a '\n'
4842n/a ' '
4843n/a '+-----------+------------------------------------------------------------+\n'
4844n/a ' | Option | '
4845n/a 'Meaning '
4846n/a '|\n'
4847n/a ' '
4848n/a '+===========+============================================================+\n'
4849n/a ' | "\'<\'" | Forces the field to be left-aligned '
4850n/a 'within the available |\n'
4851n/a ' | | space (this is the default for most '
4852n/a 'objects). |\n'
4853n/a ' '
4854n/a '+-----------+------------------------------------------------------------+\n'
4855n/a ' | "\'>\'" | Forces the field to be right-aligned '
4856n/a 'within the available |\n'
4857n/a ' | | space (this is the default for '
4858n/a 'numbers). |\n'
4859n/a ' '
4860n/a '+-----------+------------------------------------------------------------+\n'
4861n/a ' | "\'=\'" | Forces the padding to be placed after '
4862n/a 'the sign (if any) |\n'
4863n/a ' | | but before the digits. This is used for '
4864n/a 'printing fields |\n'
4865n/a " | | in the form '+000000120'. This alignment "
4866n/a 'option is only |\n'
4867n/a ' | | valid for numeric types. It becomes the '
4868n/a "default when '0' |\n"
4869n/a ' | | immediately precedes the field '
4870n/a 'width. |\n'
4871n/a ' '
4872n/a '+-----------+------------------------------------------------------------+\n'
4873n/a ' | "\'^\'" | Forces the field to be centered within '
4874n/a 'the available |\n'
4875n/a ' | | '
4876n/a 'space. '
4877n/a '|\n'
4878n/a ' '
4879n/a '+-----------+------------------------------------------------------------+\n'
4880n/a '\n'
4881n/a 'Note that unless a minimum field width is defined, the '
4882n/a 'field width\n'
4883n/a 'will always be the same size as the data to fill it, so '
4884n/a 'that the\n'
4885n/a 'alignment option has no meaning in this case.\n'
4886n/a '\n'
4887n/a 'The *sign* option is only valid for number types, and can '
4888n/a 'be one of\n'
4889n/a 'the following:\n'
4890n/a '\n'
4891n/a ' '
4892n/a '+-----------+------------------------------------------------------------+\n'
4893n/a ' | Option | '
4894n/a 'Meaning '
4895n/a '|\n'
4896n/a ' '
4897n/a '+===========+============================================================+\n'
4898n/a ' | "\'+\'" | indicates that a sign should be used for '
4899n/a 'both positive as |\n'
4900n/a ' | | well as negative '
4901n/a 'numbers. |\n'
4902n/a ' '
4903n/a '+-----------+------------------------------------------------------------+\n'
4904n/a ' | "\'-\'" | indicates that a sign should be used '
4905n/a 'only for negative |\n'
4906n/a ' | | numbers (this is the default '
4907n/a 'behavior). |\n'
4908n/a ' '
4909n/a '+-----------+------------------------------------------------------------+\n'
4910n/a ' | space | indicates that a leading space should be '
4911n/a 'used on positive |\n'
4912n/a ' | | numbers, and a minus sign on negative '
4913n/a 'numbers. |\n'
4914n/a ' '
4915n/a '+-----------+------------------------------------------------------------+\n'
4916n/a '\n'
4917n/a 'The "\'#\'" option causes the "alternate form" to be used '
4918n/a 'for the\n'
4919n/a 'conversion. The alternate form is defined differently for '
4920n/a 'different\n'
4921n/a 'types. This option is only valid for integer, float, '
4922n/a 'complex and\n'
4923n/a 'Decimal types. For integers, when binary, octal, or '
4924n/a 'hexadecimal output\n'
4925n/a 'is used, this option adds the prefix respective "\'0b\'", '
4926n/a '"\'0o\'", or\n'
4927n/a '"\'0x\'" to the output value. For floats, complex and '
4928n/a 'Decimal the\n'
4929n/a 'alternate form causes the result of the conversion to '
4930n/a 'always contain a\n'
4931n/a 'decimal-point character, even if no digits follow it. '
4932n/a 'Normally, a\n'
4933n/a 'decimal-point character appears in the result of these '
4934n/a 'conversions\n'
4935n/a 'only if a digit follows it. In addition, for "\'g\'" and '
4936n/a '"\'G\'"\n'
4937n/a 'conversions, trailing zeros are not removed from the '
4938n/a 'result.\n'
4939n/a '\n'
4940n/a 'The "\',\'" option signals the use of a comma for a '
4941n/a 'thousands separator.\n'
4942n/a 'For a locale aware separator, use the "\'n\'" integer '
4943n/a 'presentation type\n'
4944n/a 'instead.\n'
4945n/a '\n'
4946n/a 'Changed in version 3.1: Added the "\',\'" option (see also '
4947n/a '**PEP 378**).\n'
4948n/a '\n'
4949n/a 'The "\'_\'" option signals the use of an underscore for a '
4950n/a 'thousands\n'
4951n/a 'separator for floating point presentation types and for '
4952n/a 'integer\n'
4953n/a 'presentation type "\'d\'". For integer presentation types '
4954n/a '"\'b\'", "\'o\'",\n'
4955n/a '"\'x\'", and "\'X\'", underscores will be inserted every 4 '
4956n/a 'digits. For\n'
4957n/a 'other presentation types, specifying this option is an '
4958n/a 'error.\n'
4959n/a '\n'
4960n/a 'Changed in version 3.6: Added the "\'_\'" option (see also '
4961n/a '**PEP 515**).\n'
4962n/a '\n'
4963n/a '*width* is a decimal integer defining the minimum field '
4964n/a 'width. If not\n'
4965n/a 'specified, then the field width will be determined by the '
4966n/a 'content.\n'
4967n/a '\n'
4968n/a 'When no explicit alignment is given, preceding the *width* '
4969n/a 'field by a\n'
4970n/a 'zero ("\'0\'") character enables sign-aware zero-padding '
4971n/a 'for numeric\n'
4972n/a 'types. This is equivalent to a *fill* character of "\'0\'" '
4973n/a 'with an\n'
4974n/a '*alignment* type of "\'=\'".\n'
4975n/a '\n'
4976n/a 'The *precision* is a decimal number indicating how many '
4977n/a 'digits should\n'
4978n/a 'be displayed after the decimal point for a floating point '
4979n/a 'value\n'
4980n/a 'formatted with "\'f\'" and "\'F\'", or before and after the '
4981n/a 'decimal point\n'
4982n/a 'for a floating point value formatted with "\'g\'" or '
4983n/a '"\'G\'". For non-\n'
4984n/a 'number types the field indicates the maximum field size - '
4985n/a 'in other\n'
4986n/a 'words, how many characters will be used from the field '
4987n/a 'content. The\n'
4988n/a '*precision* is not allowed for integer values.\n'
4989n/a '\n'
4990n/a 'Finally, the *type* determines how the data should be '
4991n/a 'presented.\n'
4992n/a '\n'
4993n/a 'The available string presentation types are:\n'
4994n/a '\n'
4995n/a ' '
4996n/a '+-----------+------------------------------------------------------------+\n'
4997n/a ' | Type | '
4998n/a 'Meaning '
4999n/a '|\n'
5000n/a ' '
5001n/a '+===========+============================================================+\n'
5002n/a ' | "\'s\'" | String format. This is the default type '
5003n/a 'for strings and |\n'
5004n/a ' | | may be '
5005n/a 'omitted. |\n'
5006n/a ' '
5007n/a '+-----------+------------------------------------------------------------+\n'
5008n/a ' | None | The same as '
5009n/a '"\'s\'". |\n'
5010n/a ' '
5011n/a '+-----------+------------------------------------------------------------+\n'
5012n/a '\n'
5013n/a 'The available integer presentation types are:\n'
5014n/a '\n'
5015n/a ' '
5016n/a '+-----------+------------------------------------------------------------+\n'
5017n/a ' | Type | '
5018n/a 'Meaning '
5019n/a '|\n'
5020n/a ' '
5021n/a '+===========+============================================================+\n'
5022n/a ' | "\'b\'" | Binary format. Outputs the number in '
5023n/a 'base 2. |\n'
5024n/a ' '
5025n/a '+-----------+------------------------------------------------------------+\n'
5026n/a ' | "\'c\'" | Character. Converts the integer to the '
5027n/a 'corresponding |\n'
5028n/a ' | | unicode character before '
5029n/a 'printing. |\n'
5030n/a ' '
5031n/a '+-----------+------------------------------------------------------------+\n'
5032n/a ' | "\'d\'" | Decimal Integer. Outputs the number in '
5033n/a 'base 10. |\n'
5034n/a ' '
5035n/a '+-----------+------------------------------------------------------------+\n'
5036n/a ' | "\'o\'" | Octal format. Outputs the number in base '
5037n/a '8. |\n'
5038n/a ' '
5039n/a '+-----------+------------------------------------------------------------+\n'
5040n/a ' | "\'x\'" | Hex format. Outputs the number in base '
5041n/a '16, using lower- |\n'
5042n/a ' | | case letters for the digits above '
5043n/a '9. |\n'
5044n/a ' '
5045n/a '+-----------+------------------------------------------------------------+\n'
5046n/a ' | "\'X\'" | Hex format. Outputs the number in base '
5047n/a '16, using upper- |\n'
5048n/a ' | | case letters for the digits above '
5049n/a '9. |\n'
5050n/a ' '
5051n/a '+-----------+------------------------------------------------------------+\n'
5052n/a ' | "\'n\'" | Number. This is the same as "\'d\'", '
5053n/a 'except that it uses the |\n'
5054n/a ' | | current locale setting to insert the '
5055n/a 'appropriate number |\n'
5056n/a ' | | separator '
5057n/a 'characters. |\n'
5058n/a ' '
5059n/a '+-----------+------------------------------------------------------------+\n'
5060n/a ' | None | The same as '
5061n/a '"\'d\'". |\n'
5062n/a ' '
5063n/a '+-----------+------------------------------------------------------------+\n'
5064n/a '\n'
5065n/a 'In addition to the above presentation types, integers can '
5066n/a 'be formatted\n'
5067n/a 'with the floating point presentation types listed below '
5068n/a '(except "\'n\'"\n'
5069n/a 'and None). When doing so, "float()" is used to convert the '
5070n/a 'integer to\n'
5071n/a 'a floating point number before formatting.\n'
5072n/a '\n'
5073n/a 'The available presentation types for floating point and '
5074n/a 'decimal values\n'
5075n/a 'are:\n'
5076n/a '\n'
5077n/a ' '
5078n/a '+-----------+------------------------------------------------------------+\n'
5079n/a ' | Type | '
5080n/a 'Meaning '
5081n/a '|\n'
5082n/a ' '
5083n/a '+===========+============================================================+\n'
5084n/a ' | "\'e\'" | Exponent notation. Prints the number in '
5085n/a 'scientific |\n'
5086n/a " | | notation using the letter 'e' to indicate "
5087n/a 'the exponent. |\n'
5088n/a ' | | The default precision is '
5089n/a '"6". |\n'
5090n/a ' '
5091n/a '+-----------+------------------------------------------------------------+\n'
5092n/a ' | "\'E\'" | Exponent notation. Same as "\'e\'" '
5093n/a 'except it uses an upper |\n'
5094n/a " | | case 'E' as the separator "
5095n/a 'character. |\n'
5096n/a ' '
5097n/a '+-----------+------------------------------------------------------------+\n'
5098n/a ' | "\'f\'" | Fixed point. Displays the number as a '
5099n/a 'fixed-point number. |\n'
5100n/a ' | | The default precision is '
5101n/a '"6". |\n'
5102n/a ' '
5103n/a '+-----------+------------------------------------------------------------+\n'
5104n/a ' | "\'F\'" | Fixed point. Same as "\'f\'", but '
5105n/a 'converts "nan" to "NAN" |\n'
5106n/a ' | | and "inf" to '
5107n/a '"INF". |\n'
5108n/a ' '
5109n/a '+-----------+------------------------------------------------------------+\n'
5110n/a ' | "\'g\'" | General format. For a given precision '
5111n/a '"p >= 1", this |\n'
5112n/a ' | | rounds the number to "p" significant '
5113n/a 'digits and then |\n'
5114n/a ' | | formats the result in either fixed-point '
5115n/a 'format or in |\n'
5116n/a ' | | scientific notation, depending on its '
5117n/a 'magnitude. The |\n'
5118n/a ' | | precise rules are as follows: suppose that '
5119n/a 'the result |\n'
5120n/a ' | | formatted with presentation type "\'e\'" '
5121n/a 'and precision "p-1" |\n'
5122n/a ' | | would have exponent "exp". Then if "-4 <= '
5123n/a 'exp < p", the |\n'
5124n/a ' | | number is formatted with presentation type '
5125n/a '"\'f\'" and |\n'
5126n/a ' | | precision "p-1-exp". Otherwise, the '
5127n/a 'number is formatted |\n'
5128n/a ' | | with presentation type "\'e\'" and '
5129n/a 'precision "p-1". In both |\n'
5130n/a ' | | cases insignificant trailing zeros are '
5131n/a 'removed from the |\n'
5132n/a ' | | significand, and the decimal point is also '
5133n/a 'removed if |\n'
5134n/a ' | | there are no remaining digits following '
5135n/a 'it. Positive and |\n'
5136n/a ' | | negative infinity, positive and negative '
5137n/a 'zero, and nans, |\n'
5138n/a ' | | are formatted as "inf", "-inf", "0", "-0" '
5139n/a 'and "nan" |\n'
5140n/a ' | | respectively, regardless of the '
5141n/a 'precision. A precision of |\n'
5142n/a ' | | "0" is treated as equivalent to a '
5143n/a 'precision of "1". The |\n'
5144n/a ' | | default precision is '
5145n/a '"6". |\n'
5146n/a ' '
5147n/a '+-----------+------------------------------------------------------------+\n'
5148n/a ' | "\'G\'" | General format. Same as "\'g\'" except '
5149n/a 'switches to "\'E\'" if |\n'
5150n/a ' | | the number gets too large. The '
5151n/a 'representations of infinity |\n'
5152n/a ' | | and NaN are uppercased, '
5153n/a 'too. |\n'
5154n/a ' '
5155n/a '+-----------+------------------------------------------------------------+\n'
5156n/a ' | "\'n\'" | Number. This is the same as "\'g\'", '
5157n/a 'except that it uses the |\n'
5158n/a ' | | current locale setting to insert the '
5159n/a 'appropriate number |\n'
5160n/a ' | | separator '
5161n/a 'characters. |\n'
5162n/a ' '
5163n/a '+-----------+------------------------------------------------------------+\n'
5164n/a ' | "\'%\'" | Percentage. Multiplies the number by 100 '
5165n/a 'and displays in |\n'
5166n/a ' | | fixed ("\'f\'") format, followed by a '
5167n/a 'percent sign. |\n'
5168n/a ' '
5169n/a '+-----------+------------------------------------------------------------+\n'
5170n/a ' | None | Similar to "\'g\'", except that '
5171n/a 'fixed-point notation, when |\n'
5172n/a ' | | used, has at least one digit past the '
5173n/a 'decimal point. The |\n'
5174n/a ' | | default precision is as high as needed to '
5175n/a 'represent the |\n'
5176n/a ' | | particular value. The overall effect is to '
5177n/a 'match the |\n'
5178n/a ' | | output of "str()" as altered by the other '
5179n/a 'format |\n'
5180n/a ' | | '
5181n/a 'modifiers. '
5182n/a '|\n'
5183n/a ' '
5184n/a '+-----------+------------------------------------------------------------+\n'
5185n/a '\n'
5186n/a '\n'
5187n/a 'Format examples\n'
5188n/a '===============\n'
5189n/a '\n'
5190n/a 'This section contains examples of the "str.format()" syntax '
5191n/a 'and\n'
5192n/a 'comparison with the old "%"-formatting.\n'
5193n/a '\n'
5194n/a 'In most of the cases the syntax is similar to the old '
5195n/a '"%"-formatting,\n'
5196n/a 'with the addition of the "{}" and with ":" used instead of '
5197n/a '"%". For\n'
5198n/a 'example, "\'%03.2f\'" can be translated to "\'{:03.2f}\'".\n'
5199n/a '\n'
5200n/a 'The new format syntax also supports new and different '
5201n/a 'options, shown\n'
5202n/a 'in the follow examples.\n'
5203n/a '\n'
5204n/a 'Accessing arguments by position:\n'
5205n/a '\n'
5206n/a " >>> '{0}, {1}, {2}'.format('a', 'b', 'c')\n"
5207n/a " 'a, b, c'\n"
5208n/a " >>> '{}, {}, {}'.format('a', 'b', 'c') # 3.1+ only\n"
5209n/a " 'a, b, c'\n"
5210n/a " >>> '{2}, {1}, {0}'.format('a', 'b', 'c')\n"
5211n/a " 'c, b, a'\n"
5212n/a " >>> '{2}, {1}, {0}'.format(*'abc') # unpacking "
5213n/a 'argument sequence\n'
5214n/a " 'c, b, a'\n"
5215n/a " >>> '{0}{1}{0}'.format('abra', 'cad') # arguments' "
5216n/a 'indices can be repeated\n'
5217n/a " 'abracadabra'\n"
5218n/a '\n'
5219n/a 'Accessing arguments by name:\n'
5220n/a '\n'
5221n/a " >>> 'Coordinates: {latitude}, "
5222n/a "{longitude}'.format(latitude='37.24N', "
5223n/a "longitude='-115.81W')\n"
5224n/a " 'Coordinates: 37.24N, -115.81W'\n"
5225n/a " >>> coord = {'latitude': '37.24N', 'longitude': "
5226n/a "'-115.81W'}\n"
5227n/a " >>> 'Coordinates: {latitude}, "
5228n/a "{longitude}'.format(**coord)\n"
5229n/a " 'Coordinates: 37.24N, -115.81W'\n"
5230n/a '\n'
5231n/a "Accessing arguments' attributes:\n"
5232n/a '\n'
5233n/a ' >>> c = 3-5j\n'
5234n/a " >>> ('The complex number {0} is formed from the real "
5235n/a "part {0.real} '\n"
5236n/a " ... 'and the imaginary part {0.imag}.').format(c)\n"
5237n/a " 'The complex number (3-5j) is formed from the real part "
5238n/a "3.0 and the imaginary part -5.0.'\n"
5239n/a ' >>> class Point:\n'
5240n/a ' ... def __init__(self, x, y):\n'
5241n/a ' ... self.x, self.y = x, y\n'
5242n/a ' ... def __str__(self):\n'
5243n/a " ... return 'Point({self.x}, "
5244n/a "{self.y})'.format(self=self)\n"
5245n/a ' ...\n'
5246n/a ' >>> str(Point(4, 2))\n'
5247n/a " 'Point(4, 2)'\n"
5248n/a '\n'
5249n/a "Accessing arguments' items:\n"
5250n/a '\n'
5251n/a ' >>> coord = (3, 5)\n'
5252n/a " >>> 'X: {0[0]}; Y: {0[1]}'.format(coord)\n"
5253n/a " 'X: 3; Y: 5'\n"
5254n/a '\n'
5255n/a 'Replacing "%s" and "%r":\n'
5256n/a '\n'
5257n/a ' >>> "repr() shows quotes: {!r}; str() doesn\'t: '
5258n/a '{!s}".format(\'test1\', \'test2\')\n'
5259n/a ' "repr() shows quotes: \'test1\'; str() doesn\'t: test2"\n'
5260n/a '\n'
5261n/a 'Aligning the text and specifying a width:\n'
5262n/a '\n'
5263n/a " >>> '{:<30}'.format('left aligned')\n"
5264n/a " 'left aligned '\n"
5265n/a " >>> '{:>30}'.format('right aligned')\n"
5266n/a " ' right aligned'\n"
5267n/a " >>> '{:^30}'.format('centered')\n"
5268n/a " ' centered '\n"
5269n/a " >>> '{:*^30}'.format('centered') # use '*' as a fill "
5270n/a 'char\n'
5271n/a " '***********centered***********'\n"
5272n/a '\n'
5273n/a 'Replacing "%+f", "%-f", and "% f" and specifying a sign:\n'
5274n/a '\n'
5275n/a " >>> '{:+f}; {:+f}'.format(3.14, -3.14) # show it "
5276n/a 'always\n'
5277n/a " '+3.140000; -3.140000'\n"
5278n/a " >>> '{: f}; {: f}'.format(3.14, -3.14) # show a space "
5279n/a 'for positive numbers\n'
5280n/a " ' 3.140000; -3.140000'\n"
5281n/a " >>> '{:-f}; {:-f}'.format(3.14, -3.14) # show only the "
5282n/a "minus -- same as '{:f}; {:f}'\n"
5283n/a " '3.140000; -3.140000'\n"
5284n/a '\n'
5285n/a 'Replacing "%x" and "%o" and converting the value to '
5286n/a 'different bases:\n'
5287n/a '\n'
5288n/a ' >>> # format also supports binary numbers\n'
5289n/a ' >>> "int: {0:d}; hex: {0:x}; oct: {0:o}; bin: '
5290n/a '{0:b}".format(42)\n'
5291n/a " 'int: 42; hex: 2a; oct: 52; bin: 101010'\n"
5292n/a ' >>> # with 0x, 0o, or 0b as prefix:\n'
5293n/a ' >>> "int: {0:d}; hex: {0:#x}; oct: {0:#o}; bin: '
5294n/a '{0:#b}".format(42)\n'
5295n/a " 'int: 42; hex: 0x2a; oct: 0o52; bin: 0b101010'\n"
5296n/a '\n'
5297n/a 'Using the comma as a thousands separator:\n'
5298n/a '\n'
5299n/a " >>> '{:,}'.format(1234567890)\n"
5300n/a " '1,234,567,890'\n"
5301n/a '\n'
5302n/a 'Expressing a percentage:\n'
5303n/a '\n'
5304n/a ' >>> points = 19\n'
5305n/a ' >>> total = 22\n'
5306n/a " >>> 'Correct answers: {:.2%}'.format(points/total)\n"
5307n/a " 'Correct answers: 86.36%'\n"
5308n/a '\n'
5309n/a 'Using type-specific formatting:\n'
5310n/a '\n'
5311n/a ' >>> import datetime\n'
5312n/a ' >>> d = datetime.datetime(2010, 7, 4, 12, 15, 58)\n'
5313n/a " >>> '{:%Y-%m-%d %H:%M:%S}'.format(d)\n"
5314n/a " '2010-07-04 12:15:58'\n"
5315n/a '\n'
5316n/a 'Nesting arguments and more complex examples:\n'
5317n/a '\n'
5318n/a " >>> for align, text in zip('<^>', ['left', 'center', "
5319n/a "'right']):\n"
5320n/a " ... '{0:{fill}{align}16}'.format(text, fill=align, "
5321n/a 'align=align)\n'
5322n/a ' ...\n'
5323n/a " 'left<<<<<<<<<<<<'\n"
5324n/a " '^^^^^center^^^^^'\n"
5325n/a " '>>>>>>>>>>>right'\n"
5326n/a ' >>>\n'
5327n/a ' >>> octets = [192, 168, 0, 1]\n'
5328n/a " >>> '{:02X}{:02X}{:02X}{:02X}'.format(*octets)\n"
5329n/a " 'C0A80001'\n"
5330n/a ' >>> int(_, 16)\n'
5331n/a ' 3232235521\n'
5332n/a ' >>>\n'
5333n/a ' >>> width = 5\n'
5334n/a ' >>> for num in range(5,12): #doctest: '
5335n/a '+NORMALIZE_WHITESPACE\n'
5336n/a " ... for base in 'dXob':\n"
5337n/a " ... print('{0:{width}{base}}'.format(num, "
5338n/a "base=base, width=width), end=' ')\n"
5339n/a ' ... print()\n'
5340n/a ' ...\n'
5341n/a ' 5 5 5 101\n'
5342n/a ' 6 6 6 110\n'
5343n/a ' 7 7 7 111\n'
5344n/a ' 8 8 10 1000\n'
5345n/a ' 9 9 11 1001\n'
5346n/a ' 10 A 12 1010\n'
5347n/a ' 11 B 13 1011\n',
5348n/a 'function': '\n'
5349n/a 'Function definitions\n'
5350n/a '********************\n'
5351n/a '\n'
5352n/a 'A function definition defines a user-defined function object '
5353n/a '(see\n'
5354n/a 'section The standard type hierarchy):\n'
5355n/a '\n'
5356n/a ' funcdef ::= [decorators] "def" funcname "(" '
5357n/a '[parameter_list] ")" ["->" expression] ":" suite\n'
5358n/a ' decorators ::= decorator+\n'
5359n/a ' decorator ::= "@" dotted_name ["(" '
5360n/a '[argument_list [","]] ")"] NEWLINE\n'
5361n/a ' dotted_name ::= identifier ("." identifier)*\n'
5362n/a ' parameter_list ::= defparameter ("," defparameter)* '
5363n/a '["," [parameter_list_starargs]]\n'
5364n/a ' | parameter_list_starargs\n'
5365n/a ' parameter_list_starargs ::= "*" [parameter] ("," '
5366n/a 'defparameter)* ["," ["**" parameter [","]]]\n'
5367n/a ' | "**" parameter [","]\n'
5368n/a ' parameter ::= identifier [":" expression]\n'
5369n/a ' defparameter ::= parameter ["=" expression]\n'
5370n/a ' funcname ::= identifier\n'
5371n/a '\n'
5372n/a 'A function definition is an executable statement. Its execution '
5373n/a 'binds\n'
5374n/a 'the function name in the current local namespace to a function '
5375n/a 'object\n'
5376n/a '(a wrapper around the executable code for the function). This\n'
5377n/a 'function object contains a reference to the current global '
5378n/a 'namespace\n'
5379n/a 'as the global namespace to be used when the function is called.\n'
5380n/a '\n'
5381n/a 'The function definition does not execute the function body; this '
5382n/a 'gets\n'
5383n/a 'executed only when the function is called. [3]\n'
5384n/a '\n'
5385n/a 'A function definition may be wrapped by one or more *decorator*\n'
5386n/a 'expressions. Decorator expressions are evaluated when the '
5387n/a 'function is\n'
5388n/a 'defined, in the scope that contains the function definition. '
5389n/a 'The\n'
5390n/a 'result must be a callable, which is invoked with the function '
5391n/a 'object\n'
5392n/a 'as the only argument. The returned value is bound to the '
5393n/a 'function name\n'
5394n/a 'instead of the function object. Multiple decorators are applied '
5395n/a 'in\n'
5396n/a 'nested fashion. For example, the following code\n'
5397n/a '\n'
5398n/a ' @f1(arg)\n'
5399n/a ' @f2\n'
5400n/a ' def func(): pass\n'
5401n/a '\n'
5402n/a 'is roughly equivalent to\n'
5403n/a '\n'
5404n/a ' def func(): pass\n'
5405n/a ' func = f1(arg)(f2(func))\n'
5406n/a '\n'
5407n/a 'except that the original function is not temporarily bound to '
5408n/a 'the name\n'
5409n/a '"func".\n'
5410n/a '\n'
5411n/a 'When one or more *parameters* have the form *parameter* "="\n'
5412n/a '*expression*, the function is said to have "default parameter '
5413n/a 'values."\n'
5414n/a 'For a parameter with a default value, the corresponding '
5415n/a '*argument* may\n'
5416n/a "be omitted from a call, in which case the parameter's default "
5417n/a 'value is\n'
5418n/a 'substituted. If a parameter has a default value, all following\n'
5419n/a 'parameters up until the ""*"" must also have a default value --- '
5420n/a 'this\n'
5421n/a 'is a syntactic restriction that is not expressed by the '
5422n/a 'grammar.\n'
5423n/a '\n'
5424n/a '**Default parameter values are evaluated from left to right when '
5425n/a 'the\n'
5426n/a 'function definition is executed.** This means that the '
5427n/a 'expression is\n'
5428n/a 'evaluated once, when the function is defined, and that the same '
5429n/a '"pre-\n'
5430n/a 'computed" value is used for each call. This is especially '
5431n/a 'important\n'
5432n/a 'to understand when a default parameter is a mutable object, such '
5433n/a 'as a\n'
5434n/a 'list or a dictionary: if the function modifies the object (e.g. '
5435n/a 'by\n'
5436n/a 'appending an item to a list), the default value is in effect '
5437n/a 'modified.\n'
5438n/a 'This is generally not what was intended. A way around this is '
5439n/a 'to use\n'
5440n/a '"None" as the default, and explicitly test for it in the body of '
5441n/a 'the\n'
5442n/a 'function, e.g.:\n'
5443n/a '\n'
5444n/a ' def whats_on_the_telly(penguin=None):\n'
5445n/a ' if penguin is None:\n'
5446n/a ' penguin = []\n'
5447n/a ' penguin.append("property of the zoo")\n'
5448n/a ' return penguin\n'
5449n/a '\n'
5450n/a 'Function call semantics are described in more detail in section '
5451n/a 'Calls.\n'
5452n/a 'A function call always assigns values to all parameters '
5453n/a 'mentioned in\n'
5454n/a 'the parameter list, either from position arguments, from '
5455n/a 'keyword\n'
5456n/a 'arguments, or from default values. If the form ""*identifier"" '
5457n/a 'is\n'
5458n/a 'present, it is initialized to a tuple receiving any excess '
5459n/a 'positional\n'
5460n/a 'parameters, defaulting to the empty tuple. If the form\n'
5461n/a '""**identifier"" is present, it is initialized to a new ordered\n'
5462n/a 'mapping receiving any excess keyword arguments, defaulting to a '
5463n/a 'new\n'
5464n/a 'empty mapping of the same type. Parameters after ""*"" or\n'
5465n/a '""*identifier"" are keyword-only parameters and may only be '
5466n/a 'passed\n'
5467n/a 'used keyword arguments.\n'
5468n/a '\n'
5469n/a 'Parameters may have annotations of the form "": expression"" '
5470n/a 'following\n'
5471n/a 'the parameter name. Any parameter may have an annotation even '
5472n/a 'those\n'
5473n/a 'of the form "*identifier" or "**identifier". Functions may '
5474n/a 'have\n'
5475n/a '"return" annotation of the form ""-> expression"" after the '
5476n/a 'parameter\n'
5477n/a 'list. These annotations can be any valid Python expression and '
5478n/a 'are\n'
5479n/a 'evaluated when the function definition is executed. Annotations '
5480n/a 'may\n'
5481n/a 'be evaluated in a different order than they appear in the source '
5482n/a 'code.\n'
5483n/a 'The presence of annotations does not change the semantics of a\n'
5484n/a 'function. The annotation values are available as values of a\n'
5485n/a "dictionary keyed by the parameters' names in the "
5486n/a '"__annotations__"\n'
5487n/a 'attribute of the function object.\n'
5488n/a '\n'
5489n/a 'It is also possible to create anonymous functions (functions not '
5490n/a 'bound\n'
5491n/a 'to a name), for immediate use in expressions. This uses lambda\n'
5492n/a 'expressions, described in section Lambdas. Note that the '
5493n/a 'lambda\n'
5494n/a 'expression is merely a shorthand for a simplified function '
5495n/a 'definition;\n'
5496n/a 'a function defined in a ""def"" statement can be passed around '
5497n/a 'or\n'
5498n/a 'assigned to another name just like a function defined by a '
5499n/a 'lambda\n'
5500n/a 'expression. The ""def"" form is actually more powerful since '
5501n/a 'it\n'
5502n/a 'allows the execution of multiple statements and annotations.\n'
5503n/a '\n'
5504n/a "**Programmer's note:** Functions are first-class objects. A "
5505n/a '""def""\n'
5506n/a 'statement executed inside a function definition defines a local\n'
5507n/a 'function that can be returned or passed around. Free variables '
5508n/a 'used\n'
5509n/a 'in the nested function can access the local variables of the '
5510n/a 'function\n'
5511n/a 'containing the def. See section Naming and binding for '
5512n/a 'details.\n'
5513n/a '\n'
5514n/a 'See also:\n'
5515n/a '\n'
5516n/a ' **PEP 3107** - Function Annotations\n'
5517n/a ' The original specification for function annotations.\n',
5518n/a 'global': '\n'
5519n/a 'The "global" statement\n'
5520n/a '**********************\n'
5521n/a '\n'
5522n/a ' global_stmt ::= "global" identifier ("," identifier)*\n'
5523n/a '\n'
5524n/a 'The "global" statement is a declaration which holds for the '
5525n/a 'entire\n'
5526n/a 'current code block. It means that the listed identifiers are to '
5527n/a 'be\n'
5528n/a 'interpreted as globals. It would be impossible to assign to a '
5529n/a 'global\n'
5530n/a 'variable without "global", although free variables may refer to\n'
5531n/a 'globals without being declared global.\n'
5532n/a '\n'
5533n/a 'Names listed in a "global" statement must not be used in the same '
5534n/a 'code\n'
5535n/a 'block textually preceding that "global" statement.\n'
5536n/a '\n'
5537n/a 'Names listed in a "global" statement must not be defined as '
5538n/a 'formal\n'
5539n/a 'parameters or in a "for" loop control target, "class" definition,\n'
5540n/a 'function definition, "import" statement, or variable annotation.\n'
5541n/a '\n'
5542n/a '**CPython implementation detail:** The current implementation does '
5543n/a 'not\n'
5544n/a 'enforce some of these restriction, but programs should not abuse '
5545n/a 'this\n'
5546n/a 'freedom, as future implementations may enforce them or silently '
5547n/a 'change\n'
5548n/a 'the meaning of the program.\n'
5549n/a '\n'
5550n/a '**Programmer\'s note:** the "global" is a directive to the '
5551n/a 'parser. It\n'
5552n/a 'applies only to code parsed at the same time as the "global"\n'
5553n/a 'statement. In particular, a "global" statement contained in a '
5554n/a 'string\n'
5555n/a 'or code object supplied to the built-in "exec()" function does '
5556n/a 'not\n'
5557n/a 'affect the code block *containing* the function call, and code\n'
5558n/a 'contained in such a string is unaffected by "global" statements in '
5559n/a 'the\n'
5560n/a 'code containing the function call. The same applies to the '
5561n/a '"eval()"\n'
5562n/a 'and "compile()" functions.\n',
5563n/a 'id-classes': '\n'
5564n/a 'Reserved classes of identifiers\n'
5565n/a '*******************************\n'
5566n/a '\n'
5567n/a 'Certain classes of identifiers (besides keywords) have '
5568n/a 'special\n'
5569n/a 'meanings. These classes are identified by the patterns of '
5570n/a 'leading and\n'
5571n/a 'trailing underscore characters:\n'
5572n/a '\n'
5573n/a '"_*"\n'
5574n/a ' Not imported by "from module import *". The special '
5575n/a 'identifier "_"\n'
5576n/a ' is used in the interactive interpreter to store the result '
5577n/a 'of the\n'
5578n/a ' last evaluation; it is stored in the "builtins" module. '
5579n/a 'When not\n'
5580n/a ' in interactive mode, "_" has no special meaning and is not '
5581n/a 'defined.\n'
5582n/a ' See section The import statement.\n'
5583n/a '\n'
5584n/a ' Note: The name "_" is often used in conjunction with\n'
5585n/a ' internationalization; refer to the documentation for the\n'
5586n/a ' "gettext" module for more information on this '
5587n/a 'convention.\n'
5588n/a '\n'
5589n/a '"__*__"\n'
5590n/a ' System-defined names. These names are defined by the '
5591n/a 'interpreter\n'
5592n/a ' and its implementation (including the standard library). '
5593n/a 'Current\n'
5594n/a ' system names are discussed in the Special method names '
5595n/a 'section and\n'
5596n/a ' elsewhere. More will likely be defined in future versions '
5597n/a 'of\n'
5598n/a ' Python. *Any* use of "__*__" names, in any context, that '
5599n/a 'does not\n'
5600n/a ' follow explicitly documented use, is subject to breakage '
5601n/a 'without\n'
5602n/a ' warning.\n'
5603n/a '\n'
5604n/a '"__*"\n'
5605n/a ' Class-private names. Names in this category, when used '
5606n/a 'within the\n'
5607n/a ' context of a class definition, are re-written to use a '
5608n/a 'mangled form\n'
5609n/a ' to help avoid name clashes between "private" attributes of '
5610n/a 'base and\n'
5611n/a ' derived classes. See section Identifiers (Names).\n',
5612n/a 'identifiers': '\n'
5613n/a 'Identifiers and keywords\n'
5614n/a '************************\n'
5615n/a '\n'
5616n/a 'Identifiers (also referred to as *names*) are described by '
5617n/a 'the\n'
5618n/a 'following lexical definitions.\n'
5619n/a '\n'
5620n/a 'The syntax of identifiers in Python is based on the Unicode '
5621n/a 'standard\n'
5622n/a 'annex UAX-31, with elaboration and changes as defined below; '
5623n/a 'see also\n'
5624n/a '**PEP 3131** for further details.\n'
5625n/a '\n'
5626n/a 'Within the ASCII range (U+0001..U+007F), the valid characters '
5627n/a 'for\n'
5628n/a 'identifiers are the same as in Python 2.x: the uppercase and '
5629n/a 'lowercase\n'
5630n/a 'letters "A" through "Z", the underscore "_" and, except for '
5631n/a 'the first\n'
5632n/a 'character, the digits "0" through "9".\n'
5633n/a '\n'
5634n/a 'Python 3.0 introduces additional characters from outside the '
5635n/a 'ASCII\n'
5636n/a 'range (see **PEP 3131**). For these characters, the '
5637n/a 'classification\n'
5638n/a 'uses the version of the Unicode Character Database as '
5639n/a 'included in the\n'
5640n/a '"unicodedata" module.\n'
5641n/a '\n'
5642n/a 'Identifiers are unlimited in length. Case is significant.\n'
5643n/a '\n'
5644n/a ' identifier ::= xid_start xid_continue*\n'
5645n/a ' id_start ::= <all characters in general categories Lu, '
5646n/a 'Ll, Lt, Lm, Lo, Nl, the underscore, and characters with the '
5647n/a 'Other_ID_Start property>\n'
5648n/a ' id_continue ::= <all characters in id_start, plus '
5649n/a 'characters in the categories Mn, Mc, Nd, Pc and others with '
5650n/a 'the Other_ID_Continue property>\n'
5651n/a ' xid_start ::= <all characters in id_start whose NFKC '
5652n/a 'normalization is in "id_start xid_continue*">\n'
5653n/a ' xid_continue ::= <all characters in id_continue whose NFKC '
5654n/a 'normalization is in "id_continue*">\n'
5655n/a '\n'
5656n/a 'The Unicode category codes mentioned above stand for:\n'
5657n/a '\n'
5658n/a '* *Lu* - uppercase letters\n'
5659n/a '\n'
5660n/a '* *Ll* - lowercase letters\n'
5661n/a '\n'
5662n/a '* *Lt* - titlecase letters\n'
5663n/a '\n'
5664n/a '* *Lm* - modifier letters\n'
5665n/a '\n'
5666n/a '* *Lo* - other letters\n'
5667n/a '\n'
5668n/a '* *Nl* - letter numbers\n'
5669n/a '\n'
5670n/a '* *Mn* - nonspacing marks\n'
5671n/a '\n'
5672n/a '* *Mc* - spacing combining marks\n'
5673n/a '\n'
5674n/a '* *Nd* - decimal numbers\n'
5675n/a '\n'
5676n/a '* *Pc* - connector punctuations\n'
5677n/a '\n'
5678n/a '* *Other_ID_Start* - explicit list of characters in '
5679n/a 'PropList.txt to\n'
5680n/a ' support backwards compatibility\n'
5681n/a '\n'
5682n/a '* *Other_ID_Continue* - likewise\n'
5683n/a '\n'
5684n/a 'All identifiers are converted into the normal form NFKC while '
5685n/a 'parsing;\n'
5686n/a 'comparison of identifiers is based on NFKC.\n'
5687n/a '\n'
5688n/a 'A non-normative HTML file listing all valid identifier '
5689n/a 'characters for\n'
5690n/a 'Unicode 4.1 can be found at https://www.dcl.hpi.uni-\n'
5691n/a 'potsdam.de/home/loewis/table-3131.html.\n'
5692n/a '\n'
5693n/a '\n'
5694n/a 'Keywords\n'
5695n/a '========\n'
5696n/a '\n'
5697n/a 'The following identifiers are used as reserved words, or '
5698n/a '*keywords* of\n'
5699n/a 'the language, and cannot be used as ordinary identifiers. '
5700n/a 'They must\n'
5701n/a 'be spelled exactly as written here:\n'
5702n/a '\n'
5703n/a ' False class finally is return\n'
5704n/a ' None continue for lambda try\n'
5705n/a ' True def from nonlocal while\n'
5706n/a ' and del global not with\n'
5707n/a ' as elif if or yield\n'
5708n/a ' assert else import pass\n'
5709n/a ' break except in raise\n'
5710n/a '\n'
5711n/a '\n'
5712n/a 'Reserved classes of identifiers\n'
5713n/a '===============================\n'
5714n/a '\n'
5715n/a 'Certain classes of identifiers (besides keywords) have '
5716n/a 'special\n'
5717n/a 'meanings. These classes are identified by the patterns of '
5718n/a 'leading and\n'
5719n/a 'trailing underscore characters:\n'
5720n/a '\n'
5721n/a '"_*"\n'
5722n/a ' Not imported by "from module import *". The special '
5723n/a 'identifier "_"\n'
5724n/a ' is used in the interactive interpreter to store the result '
5725n/a 'of the\n'
5726n/a ' last evaluation; it is stored in the "builtins" module. '
5727n/a 'When not\n'
5728n/a ' in interactive mode, "_" has no special meaning and is not '
5729n/a 'defined.\n'
5730n/a ' See section The import statement.\n'
5731n/a '\n'
5732n/a ' Note: The name "_" is often used in conjunction with\n'
5733n/a ' internationalization; refer to the documentation for '
5734n/a 'the\n'
5735n/a ' "gettext" module for more information on this '
5736n/a 'convention.\n'
5737n/a '\n'
5738n/a '"__*__"\n'
5739n/a ' System-defined names. These names are defined by the '
5740n/a 'interpreter\n'
5741n/a ' and its implementation (including the standard library). '
5742n/a 'Current\n'
5743n/a ' system names are discussed in the Special method names '
5744n/a 'section and\n'
5745n/a ' elsewhere. More will likely be defined in future versions '
5746n/a 'of\n'
5747n/a ' Python. *Any* use of "__*__" names, in any context, that '
5748n/a 'does not\n'
5749n/a ' follow explicitly documented use, is subject to breakage '
5750n/a 'without\n'
5751n/a ' warning.\n'
5752n/a '\n'
5753n/a '"__*"\n'
5754n/a ' Class-private names. Names in this category, when used '
5755n/a 'within the\n'
5756n/a ' context of a class definition, are re-written to use a '
5757n/a 'mangled form\n'
5758n/a ' to help avoid name clashes between "private" attributes of '
5759n/a 'base and\n'
5760n/a ' derived classes. See section Identifiers (Names).\n',
5761n/a 'if': '\n'
5762n/a 'The "if" statement\n'
5763n/a '******************\n'
5764n/a '\n'
5765n/a 'The "if" statement is used for conditional execution:\n'
5766n/a '\n'
5767n/a ' if_stmt ::= "if" expression ":" suite\n'
5768n/a ' ( "elif" expression ":" suite )*\n'
5769n/a ' ["else" ":" suite]\n'
5770n/a '\n'
5771n/a 'It selects exactly one of the suites by evaluating the expressions '
5772n/a 'one\n'
5773n/a 'by one until one is found to be true (see section Boolean operations\n'
5774n/a 'for the definition of true and false); then that suite is executed\n'
5775n/a '(and no other part of the "if" statement is executed or evaluated).\n'
5776n/a 'If all expressions are false, the suite of the "else" clause, if\n'
5777n/a 'present, is executed.\n',
5778n/a 'imaginary': '\n'
5779n/a 'Imaginary literals\n'
5780n/a '******************\n'
5781n/a '\n'
5782n/a 'Imaginary literals are described by the following lexical '
5783n/a 'definitions:\n'
5784n/a '\n'
5785n/a ' imagnumber ::= (floatnumber | digitpart) ("j" | "J")\n'
5786n/a '\n'
5787n/a 'An imaginary literal yields a complex number with a real part '
5788n/a 'of 0.0.\n'
5789n/a 'Complex numbers are represented as a pair of floating point '
5790n/a 'numbers\n'
5791n/a 'and have the same restrictions on their range. To create a '
5792n/a 'complex\n'
5793n/a 'number with a nonzero real part, add a floating point number to '
5794n/a 'it,\n'
5795n/a 'e.g., "(3+4j)". Some examples of imaginary literals:\n'
5796n/a '\n'
5797n/a ' 3.14j 10.j 10j .001j 1e100j 3.14e-10j '
5798n/a '3.14_15_93j\n',
5799n/a 'import': '\n'
5800n/a 'The "import" statement\n'
5801n/a '**********************\n'
5802n/a '\n'
5803n/a ' import_stmt ::= "import" module ["as" name] ( "," module '
5804n/a '["as" name] )*\n'
5805n/a ' | "from" relative_module "import" identifier '
5806n/a '["as" name]\n'
5807n/a ' ( "," identifier ["as" name] )*\n'
5808n/a ' | "from" relative_module "import" "(" '
5809n/a 'identifier ["as" name]\n'
5810n/a ' ( "," identifier ["as" name] )* [","] ")"\n'
5811n/a ' | "from" module "import" "*"\n'
5812n/a ' module ::= (identifier ".")* identifier\n'
5813n/a ' relative_module ::= "."* module | "."+\n'
5814n/a ' name ::= identifier\n'
5815n/a '\n'
5816n/a 'The basic import statement (no "from" clause) is executed in two\n'
5817n/a 'steps:\n'
5818n/a '\n'
5819n/a '1. find a module, loading and initializing it if necessary\n'
5820n/a '\n'
5821n/a '2. define a name or names in the local namespace for the scope\n'
5822n/a ' where the "import" statement occurs.\n'
5823n/a '\n'
5824n/a 'When the statement contains multiple clauses (separated by commas) '
5825n/a 'the\n'
5826n/a 'two steps are carried out separately for each clause, just as '
5827n/a 'though\n'
5828n/a 'the clauses had been separated out into individual import '
5829n/a 'statements.\n'
5830n/a '\n'
5831n/a 'The details of the first step, finding and loading modules are\n'
5832n/a 'described in greater detail in the section on the import system, '
5833n/a 'which\n'
5834n/a 'also describes the various types of packages and modules that can '
5835n/a 'be\n'
5836n/a 'imported, as well as all the hooks that can be used to customize '
5837n/a 'the\n'
5838n/a 'import system. Note that failures in this step may indicate '
5839n/a 'either\n'
5840n/a 'that the module could not be located, *or* that an error occurred\n'
5841n/a 'while initializing the module, which includes execution of the\n'
5842n/a "module's code.\n"
5843n/a '\n'
5844n/a 'If the requested module is retrieved successfully, it will be '
5845n/a 'made\n'
5846n/a 'available in the local namespace in one of three ways:\n'
5847n/a '\n'
5848n/a '* If the module name is followed by "as", then the name following\n'
5849n/a ' "as" is bound directly to the imported module.\n'
5850n/a '\n'
5851n/a '* If no other name is specified, and the module being imported is '
5852n/a 'a\n'
5853n/a " top level module, the module's name is bound in the local "
5854n/a 'namespace\n'
5855n/a ' as a reference to the imported module\n'
5856n/a '\n'
5857n/a '* If the module being imported is *not* a top level module, then '
5858n/a 'the\n'
5859n/a ' name of the top level package that contains the module is bound '
5860n/a 'in\n'
5861n/a ' the local namespace as a reference to the top level package. '
5862n/a 'The\n'
5863n/a ' imported module must be accessed using its full qualified name\n'
5864n/a ' rather than directly\n'
5865n/a '\n'
5866n/a 'The "from" form uses a slightly more complex process:\n'
5867n/a '\n'
5868n/a '1. find the module specified in the "from" clause, loading and\n'
5869n/a ' initializing it if necessary;\n'
5870n/a '\n'
5871n/a '2. for each of the identifiers specified in the "import" clauses:\n'
5872n/a '\n'
5873n/a ' 1. check if the imported module has an attribute by that name\n'
5874n/a '\n'
5875n/a ' 2. if not, attempt to import a submodule with that name and '
5876n/a 'then\n'
5877n/a ' check the imported module again for that attribute\n'
5878n/a '\n'
5879n/a ' 3. if the attribute is not found, "ImportError" is raised.\n'
5880n/a '\n'
5881n/a ' 4. otherwise, a reference to that value is stored in the local\n'
5882n/a ' namespace, using the name in the "as" clause if it is '
5883n/a 'present,\n'
5884n/a ' otherwise using the attribute name\n'
5885n/a '\n'
5886n/a 'Examples:\n'
5887n/a '\n'
5888n/a ' import foo # foo imported and bound locally\n'
5889n/a ' import foo.bar.baz # foo.bar.baz imported, foo bound '
5890n/a 'locally\n'
5891n/a ' import foo.bar.baz as fbb # foo.bar.baz imported and bound as '
5892n/a 'fbb\n'
5893n/a ' from foo.bar import baz # foo.bar.baz imported and bound as '
5894n/a 'baz\n'
5895n/a ' from foo import attr # foo imported and foo.attr bound as '
5896n/a 'attr\n'
5897n/a '\n'
5898n/a 'If the list of identifiers is replaced by a star ("\'*\'"), all '
5899n/a 'public\n'
5900n/a 'names defined in the module are bound in the local namespace for '
5901n/a 'the\n'
5902n/a 'scope where the "import" statement occurs.\n'
5903n/a '\n'
5904n/a 'The *public names* defined by a module are determined by checking '
5905n/a 'the\n'
5906n/a 'module\'s namespace for a variable named "__all__"; if defined, it '
5907n/a 'must\n'
5908n/a 'be a sequence of strings which are names defined or imported by '
5909n/a 'that\n'
5910n/a 'module. The names given in "__all__" are all considered public '
5911n/a 'and\n'
5912n/a 'are required to exist. If "__all__" is not defined, the set of '
5913n/a 'public\n'
5914n/a "names includes all names found in the module's namespace which do "
5915n/a 'not\n'
5916n/a 'begin with an underscore character ("\'_\'"). "__all__" should '
5917n/a 'contain\n'
5918n/a 'the entire public API. It is intended to avoid accidentally '
5919n/a 'exporting\n'
5920n/a 'items that are not part of the API (such as library modules which '
5921n/a 'were\n'
5922n/a 'imported and used within the module).\n'
5923n/a '\n'
5924n/a 'The wild card form of import --- "from module import *" --- is '
5925n/a 'only\n'
5926n/a 'allowed at the module level. Attempting to use it in class or\n'
5927n/a 'function definitions will raise a "SyntaxError".\n'
5928n/a '\n'
5929n/a 'When specifying what module to import you do not have to specify '
5930n/a 'the\n'
5931n/a 'absolute name of the module. When a module or package is '
5932n/a 'contained\n'
5933n/a 'within another package it is possible to make a relative import '
5934n/a 'within\n'
5935n/a 'the same top package without having to mention the package name. '
5936n/a 'By\n'
5937n/a 'using leading dots in the specified module or package after "from" '
5938n/a 'you\n'
5939n/a 'can specify how high to traverse up the current package hierarchy\n'
5940n/a 'without specifying exact names. One leading dot means the current\n'
5941n/a 'package where the module making the import exists. Two dots means '
5942n/a 'up\n'
5943n/a 'one package level. Three dots is up two levels, etc. So if you '
5944n/a 'execute\n'
5945n/a '"from . import mod" from a module in the "pkg" package then you '
5946n/a 'will\n'
5947n/a 'end up importing "pkg.mod". If you execute "from ..subpkg2 import '
5948n/a 'mod"\n'
5949n/a 'from within "pkg.subpkg1" you will import "pkg.subpkg2.mod". The\n'
5950n/a 'specification for relative imports is contained within **PEP '
5951n/a '328**.\n'
5952n/a '\n'
5953n/a '"importlib.import_module()" is provided to support applications '
5954n/a 'that\n'
5955n/a 'determine dynamically the modules to be loaded.\n'
5956n/a '\n'
5957n/a '\n'
5958n/a 'Future statements\n'
5959n/a '=================\n'
5960n/a '\n'
5961n/a 'A *future statement* is a directive to the compiler that a '
5962n/a 'particular\n'
5963n/a 'module should be compiled using syntax or semantics that will be\n'
5964n/a 'available in a specified future release of Python where the '
5965n/a 'feature\n'
5966n/a 'becomes standard.\n'
5967n/a '\n'
5968n/a 'The future statement is intended to ease migration to future '
5969n/a 'versions\n'
5970n/a 'of Python that introduce incompatible changes to the language. '
5971n/a 'It\n'
5972n/a 'allows use of the new features on a per-module basis before the\n'
5973n/a 'release in which the feature becomes standard.\n'
5974n/a '\n'
5975n/a ' future_statement ::= "from" "__future__" "import" feature ["as" '
5976n/a 'name]\n'
5977n/a ' ("," feature ["as" name])*\n'
5978n/a ' | "from" "__future__" "import" "(" feature '
5979n/a '["as" name]\n'
5980n/a ' ("," feature ["as" name])* [","] ")"\n'
5981n/a ' feature ::= identifier\n'
5982n/a ' name ::= identifier\n'
5983n/a '\n'
5984n/a 'A future statement must appear near the top of the module. The '
5985n/a 'only\n'
5986n/a 'lines that can appear before a future statement are:\n'
5987n/a '\n'
5988n/a '* the module docstring (if any),\n'
5989n/a '\n'
5990n/a '* comments,\n'
5991n/a '\n'
5992n/a '* blank lines, and\n'
5993n/a '\n'
5994n/a '* other future statements.\n'
5995n/a '\n'
5996n/a 'The features recognized by Python 3.0 are "absolute_import",\n'
5997n/a '"division", "generators", "unicode_literals", "print_function",\n'
5998n/a '"nested_scopes" and "with_statement". They are all redundant '
5999n/a 'because\n'
6000n/a 'they are always enabled, and only kept for backwards '
6001n/a 'compatibility.\n'
6002n/a '\n'
6003n/a 'A future statement is recognized and treated specially at compile\n'
6004n/a 'time: Changes to the semantics of core constructs are often\n'
6005n/a 'implemented by generating different code. It may even be the '
6006n/a 'case\n'
6007n/a 'that a new feature introduces new incompatible syntax (such as a '
6008n/a 'new\n'
6009n/a 'reserved word), in which case the compiler may need to parse the\n'
6010n/a 'module differently. Such decisions cannot be pushed off until\n'
6011n/a 'runtime.\n'
6012n/a '\n'
6013n/a 'For any given release, the compiler knows which feature names '
6014n/a 'have\n'
6015n/a 'been defined, and raises a compile-time error if a future '
6016n/a 'statement\n'
6017n/a 'contains a feature not known to it.\n'
6018n/a '\n'
6019n/a 'The direct runtime semantics are the same as for any import '
6020n/a 'statement:\n'
6021n/a 'there is a standard module "__future__", described later, and it '
6022n/a 'will\n'
6023n/a 'be imported in the usual way at the time the future statement is\n'
6024n/a 'executed.\n'
6025n/a '\n'
6026n/a 'The interesting runtime semantics depend on the specific feature\n'
6027n/a 'enabled by the future statement.\n'
6028n/a '\n'
6029n/a 'Note that there is nothing special about the statement:\n'
6030n/a '\n'
6031n/a ' import __future__ [as name]\n'
6032n/a '\n'
6033n/a "That is not a future statement; it's an ordinary import statement "
6034n/a 'with\n'
6035n/a 'no special semantics or syntax restrictions.\n'
6036n/a '\n'
6037n/a 'Code compiled by calls to the built-in functions "exec()" and\n'
6038n/a '"compile()" that occur in a module "M" containing a future '
6039n/a 'statement\n'
6040n/a 'will, by default, use the new syntax or semantics associated with '
6041n/a 'the\n'
6042n/a 'future statement. This can be controlled by optional arguments '
6043n/a 'to\n'
6044n/a '"compile()" --- see the documentation of that function for '
6045n/a 'details.\n'
6046n/a '\n'
6047n/a 'A future statement typed at an interactive interpreter prompt '
6048n/a 'will\n'
6049n/a 'take effect for the rest of the interpreter session. If an\n'
6050n/a 'interpreter is started with the "-i" option, is passed a script '
6051n/a 'name\n'
6052n/a 'to execute, and the script includes a future statement, it will be '
6053n/a 'in\n'
6054n/a 'effect in the interactive session started after the script is\n'
6055n/a 'executed.\n'
6056n/a '\n'
6057n/a 'See also:\n'
6058n/a '\n'
6059n/a ' **PEP 236** - Back to the __future__\n'
6060n/a ' The original proposal for the __future__ mechanism.\n',
6061n/a 'in': '\n'
6062n/a 'Membership test operations\n'
6063n/a '**************************\n'
6064n/a '\n'
6065n/a 'The operators "in" and "not in" test for membership. "x in s"\n'
6066n/a 'evaluates to true if *x* is a member of *s*, and false otherwise. "x\n'
6067n/a 'not in s" returns the negation of "x in s". All built-in sequences\n'
6068n/a 'and set types support this as well as dictionary, for which "in" '
6069n/a 'tests\n'
6070n/a 'whether the dictionary has a given key. For container types such as\n'
6071n/a 'list, tuple, set, frozenset, dict, or collections.deque, the\n'
6072n/a 'expression "x in y" is equivalent to "any(x is e or x == e for e in\n'
6073n/a 'y)".\n'
6074n/a '\n'
6075n/a 'For the string and bytes types, "x in y" is true if and only if *x* '
6076n/a 'is\n'
6077n/a 'a substring of *y*. An equivalent test is "y.find(x) != -1". Empty\n'
6078n/a 'strings are always considered to be a substring of any other string,\n'
6079n/a 'so """ in "abc"" will return "True".\n'
6080n/a '\n'
6081n/a 'For user-defined classes which define the "__contains__()" method, "x\n'
6082n/a 'in y" is true if and only if "y.__contains__(x)" is true.\n'
6083n/a '\n'
6084n/a 'For user-defined classes which do not define "__contains__()" but do\n'
6085n/a 'define "__iter__()", "x in y" is true if some value "z" with "x == z"\n'
6086n/a 'is produced while iterating over "y". If an exception is raised\n'
6087n/a 'during the iteration, it is as if "in" raised that exception.\n'
6088n/a '\n'
6089n/a 'Lastly, the old-style iteration protocol is tried: if a class defines\n'
6090n/a '"__getitem__()", "x in y" is true if and only if there is a non-\n'
6091n/a 'negative integer index *i* such that "x == y[i]", and all lower\n'
6092n/a 'integer indices do not raise "IndexError" exception. (If any other\n'
6093n/a 'exception is raised, it is as if "in" raised that exception).\n'
6094n/a '\n'
6095n/a 'The operator "not in" is defined to have the inverse true value of\n'
6096n/a '"in".\n',
6097n/a 'integers': '\n'
6098n/a 'Integer literals\n'
6099n/a '****************\n'
6100n/a '\n'
6101n/a 'Integer literals are described by the following lexical '
6102n/a 'definitions:\n'
6103n/a '\n'
6104n/a ' integer ::= decinteger | bininteger | octinteger | '
6105n/a 'hexinteger\n'
6106n/a ' decinteger ::= nonzerodigit (["_"] digit)* | "0"+ (["_"] '
6107n/a '"0")*\n'
6108n/a ' bininteger ::= "0" ("b" | "B") (["_"] bindigit)+\n'
6109n/a ' octinteger ::= "0" ("o" | "O") (["_"] octdigit)+\n'
6110n/a ' hexinteger ::= "0" ("x" | "X") (["_"] hexdigit)+\n'
6111n/a ' nonzerodigit ::= "1"..."9"\n'
6112n/a ' digit ::= "0"..."9"\n'
6113n/a ' bindigit ::= "0" | "1"\n'
6114n/a ' octdigit ::= "0"..."7"\n'
6115n/a ' hexdigit ::= digit | "a"..."f" | "A"..."F"\n'
6116n/a '\n'
6117n/a 'There is no limit for the length of integer literals apart from '
6118n/a 'what\n'
6119n/a 'can be stored in available memory.\n'
6120n/a '\n'
6121n/a 'Underscores are ignored for determining the numeric value of '
6122n/a 'the\n'
6123n/a 'literal. They can be used to group digits for enhanced '
6124n/a 'readability.\n'
6125n/a 'One underscore can occur between digits, and after base '
6126n/a 'specifiers\n'
6127n/a 'like "0x".\n'
6128n/a '\n'
6129n/a 'Note that leading zeros in a non-zero decimal number are not '
6130n/a 'allowed.\n'
6131n/a 'This is for disambiguation with C-style octal literals, which '
6132n/a 'Python\n'
6133n/a 'used before version 3.0.\n'
6134n/a '\n'
6135n/a 'Some examples of integer literals:\n'
6136n/a '\n'
6137n/a ' 7 2147483647 0o177 0b100110111\n'
6138n/a ' 3 79228162514264337593543950336 0o377 0xdeadbeef\n'
6139n/a ' 100_000_000_000 0b_1110_0101\n'
6140n/a '\n'
6141n/a 'Changed in version 3.6: Underscores are now allowed for '
6142n/a 'grouping\n'
6143n/a 'purposes in literals.\n',
6144n/a 'lambda': '\n'
6145n/a 'Lambdas\n'
6146n/a '*******\n'
6147n/a '\n'
6148n/a ' lambda_expr ::= "lambda" [parameter_list]: expression\n'
6149n/a ' lambda_expr_nocond ::= "lambda" [parameter_list]: '
6150n/a 'expression_nocond\n'
6151n/a '\n'
6152n/a 'Lambda expressions (sometimes called lambda forms) are used to '
6153n/a 'create\n'
6154n/a 'anonymous functions. The expression "lambda arguments: '
6155n/a 'expression"\n'
6156n/a 'yields a function object. The unnamed object behaves like a '
6157n/a 'function\n'
6158n/a 'object defined with:\n'
6159n/a '\n'
6160n/a ' def <lambda>(arguments):\n'
6161n/a ' return expression\n'
6162n/a '\n'
6163n/a 'See section Function definitions for the syntax of parameter '
6164n/a 'lists.\n'
6165n/a 'Note that functions created with lambda expressions cannot '
6166n/a 'contain\n'
6167n/a 'statements or annotations.\n',
6168n/a 'lists': '\n'
6169n/a 'List displays\n'
6170n/a '*************\n'
6171n/a '\n'
6172n/a 'A list display is a possibly empty series of expressions enclosed '
6173n/a 'in\n'
6174n/a 'square brackets:\n'
6175n/a '\n'
6176n/a ' list_display ::= "[" [starred_list | comprehension] "]"\n'
6177n/a '\n'
6178n/a 'A list display yields a new list object, the contents being '
6179n/a 'specified\n'
6180n/a 'by either a list of expressions or a comprehension. When a comma-\n'
6181n/a 'separated list of expressions is supplied, its elements are '
6182n/a 'evaluated\n'
6183n/a 'from left to right and placed into the list object in that order.\n'
6184n/a 'When a comprehension is supplied, the list is constructed from the\n'
6185n/a 'elements resulting from the comprehension.\n',
6186n/a 'naming': '\n'
6187n/a 'Naming and binding\n'
6188n/a '******************\n'
6189n/a '\n'
6190n/a '\n'
6191n/a 'Binding of names\n'
6192n/a '================\n'
6193n/a '\n'
6194n/a '*Names* refer to objects. Names are introduced by name binding\n'
6195n/a 'operations.\n'
6196n/a '\n'
6197n/a 'The following constructs bind names: formal parameters to '
6198n/a 'functions,\n'
6199n/a '"import" statements, class and function definitions (these bind '
6200n/a 'the\n'
6201n/a 'class or function name in the defining block), and targets that '
6202n/a 'are\n'
6203n/a 'identifiers if occurring in an assignment, "for" loop header, or '
6204n/a 'after\n'
6205n/a '"as" in a "with" statement or "except" clause. The "import" '
6206n/a 'statement\n'
6207n/a 'of the form "from ... import *" binds all names defined in the\n'
6208n/a 'imported module, except those beginning with an underscore. This '
6209n/a 'form\n'
6210n/a 'may only be used at the module level.\n'
6211n/a '\n'
6212n/a 'A target occurring in a "del" statement is also considered bound '
6213n/a 'for\n'
6214n/a 'this purpose (though the actual semantics are to unbind the '
6215n/a 'name).\n'
6216n/a '\n'
6217n/a 'Each assignment or import statement occurs within a block defined '
6218n/a 'by a\n'
6219n/a 'class or function definition or at the module level (the '
6220n/a 'top-level\n'
6221n/a 'code block).\n'
6222n/a '\n'
6223n/a 'If a name is bound in a block, it is a local variable of that '
6224n/a 'block,\n'
6225n/a 'unless declared as "nonlocal" or "global". If a name is bound at '
6226n/a 'the\n'
6227n/a 'module level, it is a global variable. (The variables of the '
6228n/a 'module\n'
6229n/a 'code block are local and global.) If a variable is used in a '
6230n/a 'code\n'
6231n/a 'block but not defined there, it is a *free variable*.\n'
6232n/a '\n'
6233n/a 'Each occurrence of a name in the program text refers to the '
6234n/a '*binding*\n'
6235n/a 'of that name established by the following name resolution rules.\n'
6236n/a '\n'
6237n/a '\n'
6238n/a 'Resolution of names\n'
6239n/a '===================\n'
6240n/a '\n'
6241n/a 'A *scope* defines the visibility of a name within a block. If a '
6242n/a 'local\n'
6243n/a 'variable is defined in a block, its scope includes that block. If '
6244n/a 'the\n'
6245n/a 'definition occurs in a function block, the scope extends to any '
6246n/a 'blocks\n'
6247n/a 'contained within the defining one, unless a contained block '
6248n/a 'introduces\n'
6249n/a 'a different binding for the name.\n'
6250n/a '\n'
6251n/a 'When a name is used in a code block, it is resolved using the '
6252n/a 'nearest\n'
6253n/a 'enclosing scope. The set of all such scopes visible to a code '
6254n/a 'block\n'
6255n/a "is called the block's *environment*.\n"
6256n/a '\n'
6257n/a 'When a name is not found at all, a "NameError" exception is '
6258n/a 'raised. If\n'
6259n/a 'the current scope is a function scope, and the name refers to a '
6260n/a 'local\n'
6261n/a 'variable that has not yet been bound to a value at the point where '
6262n/a 'the\n'
6263n/a 'name is used, an "UnboundLocalError" exception is raised.\n'
6264n/a '"UnboundLocalError" is a subclass of "NameError".\n'
6265n/a '\n'
6266n/a 'If a name binding operation occurs anywhere within a code block, '
6267n/a 'all\n'
6268n/a 'uses of the name within the block are treated as references to '
6269n/a 'the\n'
6270n/a 'current block. This can lead to errors when a name is used within '
6271n/a 'a\n'
6272n/a 'block before it is bound. This rule is subtle. Python lacks\n'
6273n/a 'declarations and allows name binding operations to occur anywhere\n'
6274n/a 'within a code block. The local variables of a code block can be\n'
6275n/a 'determined by scanning the entire text of the block for name '
6276n/a 'binding\n'
6277n/a 'operations.\n'
6278n/a '\n'
6279n/a 'If the "global" statement occurs within a block, all uses of the '
6280n/a 'name\n'
6281n/a 'specified in the statement refer to the binding of that name in '
6282n/a 'the\n'
6283n/a 'top-level namespace. Names are resolved in the top-level '
6284n/a 'namespace by\n'
6285n/a 'searching the global namespace, i.e. the namespace of the module\n'
6286n/a 'containing the code block, and the builtins namespace, the '
6287n/a 'namespace\n'
6288n/a 'of the module "builtins". The global namespace is searched '
6289n/a 'first. If\n'
6290n/a 'the name is not found there, the builtins namespace is searched. '
6291n/a 'The\n'
6292n/a '"global" statement must precede all uses of the name.\n'
6293n/a '\n'
6294n/a 'The "global" statement has the same scope as a name binding '
6295n/a 'operation\n'
6296n/a 'in the same block. If the nearest enclosing scope for a free '
6297n/a 'variable\n'
6298n/a 'contains a global statement, the free variable is treated as a '
6299n/a 'global.\n'
6300n/a '\n'
6301n/a 'The "nonlocal" statement causes corresponding names to refer to\n'
6302n/a 'previously bound variables in the nearest enclosing function '
6303n/a 'scope.\n'
6304n/a '"SyntaxError" is raised at compile time if the given name does '
6305n/a 'not\n'
6306n/a 'exist in any enclosing function scope.\n'
6307n/a '\n'
6308n/a 'The namespace for a module is automatically created the first time '
6309n/a 'a\n'
6310n/a 'module is imported. The main module for a script is always '
6311n/a 'called\n'
6312n/a '"__main__".\n'
6313n/a '\n'
6314n/a 'Class definition blocks and arguments to "exec()" and "eval()" '
6315n/a 'are\n'
6316n/a 'special in the context of name resolution. A class definition is '
6317n/a 'an\n'
6318n/a 'executable statement that may use and define names. These '
6319n/a 'references\n'
6320n/a 'follow the normal rules for name resolution with an exception '
6321n/a 'that\n'
6322n/a 'unbound local variables are looked up in the global namespace. '
6323n/a 'The\n'
6324n/a 'namespace of the class definition becomes the attribute dictionary '
6325n/a 'of\n'
6326n/a 'the class. The scope of names defined in a class block is limited '
6327n/a 'to\n'
6328n/a 'the class block; it does not extend to the code blocks of methods '
6329n/a '--\n'
6330n/a 'this includes comprehensions and generator expressions since they '
6331n/a 'are\n'
6332n/a 'implemented using a function scope. This means that the '
6333n/a 'following\n'
6334n/a 'will fail:\n'
6335n/a '\n'
6336n/a ' class A:\n'
6337n/a ' a = 42\n'
6338n/a ' b = list(a + i for i in range(10))\n'
6339n/a '\n'
6340n/a '\n'
6341n/a 'Builtins and restricted execution\n'
6342n/a '=================================\n'
6343n/a '\n'
6344n/a 'The builtins namespace associated with the execution of a code '
6345n/a 'block\n'
6346n/a 'is actually found by looking up the name "__builtins__" in its '
6347n/a 'global\n'
6348n/a 'namespace; this should be a dictionary or a module (in the latter '
6349n/a 'case\n'
6350n/a "the module's dictionary is used). By default, when in the "
6351n/a '"__main__"\n'
6352n/a 'module, "__builtins__" is the built-in module "builtins"; when in '
6353n/a 'any\n'
6354n/a 'other module, "__builtins__" is an alias for the dictionary of '
6355n/a 'the\n'
6356n/a '"builtins" module itself. "__builtins__" can be set to a '
6357n/a 'user-created\n'
6358n/a 'dictionary to create a weak form of restricted execution.\n'
6359n/a '\n'
6360n/a '**CPython implementation detail:** Users should not touch\n'
6361n/a '"__builtins__"; it is strictly an implementation detail. Users\n'
6362n/a 'wanting to override values in the builtins namespace should '
6363n/a '"import"\n'
6364n/a 'the "builtins" module and modify its attributes appropriately.\n'
6365n/a '\n'
6366n/a '\n'
6367n/a 'Interaction with dynamic features\n'
6368n/a '=================================\n'
6369n/a '\n'
6370n/a 'Name resolution of free variables occurs at runtime, not at '
6371n/a 'compile\n'
6372n/a 'time. This means that the following code will print 42:\n'
6373n/a '\n'
6374n/a ' i = 10\n'
6375n/a ' def f():\n'
6376n/a ' print(i)\n'
6377n/a ' i = 42\n'
6378n/a ' f()\n'
6379n/a '\n'
6380n/a 'There are several cases where Python statements are illegal when '
6381n/a 'used\n'
6382n/a 'in conjunction with nested scopes that contain free variables.\n'
6383n/a '\n'
6384n/a 'If a variable is referenced in an enclosing scope, it is illegal '
6385n/a 'to\n'
6386n/a 'delete the name. An error will be reported at compile time.\n'
6387n/a '\n'
6388n/a 'The "eval()" and "exec()" functions do not have access to the '
6389n/a 'full\n'
6390n/a 'environment for resolving names. Names may be resolved in the '
6391n/a 'local\n'
6392n/a 'and global namespaces of the caller. Free variables are not '
6393n/a 'resolved\n'
6394n/a 'in the nearest enclosing namespace, but in the global namespace. '
6395n/a '[1]\n'
6396n/a 'The "exec()" and "eval()" functions have optional arguments to\n'
6397n/a 'override the global and local namespace. If only one namespace '
6398n/a 'is\n'
6399n/a 'specified, it is used for both.\n',
6400n/a 'nonlocal': '\n'
6401n/a 'The "nonlocal" statement\n'
6402n/a '************************\n'
6403n/a '\n'
6404n/a ' nonlocal_stmt ::= "nonlocal" identifier ("," identifier)*\n'
6405n/a '\n'
6406n/a 'The "nonlocal" statement causes the listed identifiers to refer '
6407n/a 'to\n'
6408n/a 'previously bound variables in the nearest enclosing scope '
6409n/a 'excluding\n'
6410n/a 'globals. This is important because the default behavior for '
6411n/a 'binding is\n'
6412n/a 'to search the local namespace first. The statement allows\n'
6413n/a 'encapsulated code to rebind variables outside of the local '
6414n/a 'scope\n'
6415n/a 'besides the global (module) scope.\n'
6416n/a '\n'
6417n/a 'Names listed in a "nonlocal" statement, unlike those listed in '
6418n/a 'a\n'
6419n/a '"global" statement, must refer to pre-existing bindings in an\n'
6420n/a 'enclosing scope (the scope in which a new binding should be '
6421n/a 'created\n'
6422n/a 'cannot be determined unambiguously).\n'
6423n/a '\n'
6424n/a 'Names listed in a "nonlocal" statement must not collide with '
6425n/a 'pre-\n'
6426n/a 'existing bindings in the local scope.\n'
6427n/a '\n'
6428n/a 'See also:\n'
6429n/a '\n'
6430n/a ' **PEP 3104** - Access to Names in Outer Scopes\n'
6431n/a ' The specification for the "nonlocal" statement.\n',
6432n/a 'numbers': '\n'
6433n/a 'Numeric literals\n'
6434n/a '****************\n'
6435n/a '\n'
6436n/a 'There are three types of numeric literals: integers, floating '
6437n/a 'point\n'
6438n/a 'numbers, and imaginary numbers. There are no complex literals\n'
6439n/a '(complex numbers can be formed by adding a real number and an\n'
6440n/a 'imaginary number).\n'
6441n/a '\n'
6442n/a 'Note that numeric literals do not include a sign; a phrase like '
6443n/a '"-1"\n'
6444n/a 'is actually an expression composed of the unary operator \'"-"\' '
6445n/a 'and the\n'
6446n/a 'literal "1".\n',
6447n/a 'numeric-types': '\n'
6448n/a 'Emulating numeric types\n'
6449n/a '***********************\n'
6450n/a '\n'
6451n/a 'The following methods can be defined to emulate numeric '
6452n/a 'objects.\n'
6453n/a 'Methods corresponding to operations that are not supported '
6454n/a 'by the\n'
6455n/a 'particular kind of number implemented (e.g., bitwise '
6456n/a 'operations for\n'
6457n/a 'non-integral numbers) should be left undefined.\n'
6458n/a '\n'
6459n/a 'object.__add__(self, other)\n'
6460n/a 'object.__sub__(self, other)\n'
6461n/a 'object.__mul__(self, other)\n'
6462n/a 'object.__matmul__(self, other)\n'
6463n/a 'object.__truediv__(self, other)\n'
6464n/a 'object.__floordiv__(self, other)\n'
6465n/a 'object.__mod__(self, other)\n'
6466n/a 'object.__divmod__(self, other)\n'
6467n/a 'object.__pow__(self, other[, modulo])\n'
6468n/a 'object.__lshift__(self, other)\n'
6469n/a 'object.__rshift__(self, other)\n'
6470n/a 'object.__and__(self, other)\n'
6471n/a 'object.__xor__(self, other)\n'
6472n/a 'object.__or__(self, other)\n'
6473n/a '\n'
6474n/a ' These methods are called to implement the binary '
6475n/a 'arithmetic\n'
6476n/a ' operations ("+", "-", "*", "@", "/", "//", "%", '
6477n/a '"divmod()",\n'
6478n/a ' "pow()", "**", "<<", ">>", "&", "^", "|"). For '
6479n/a 'instance, to\n'
6480n/a ' evaluate the expression "x + y", where *x* is an '
6481n/a 'instance of a\n'
6482n/a ' class that has an "__add__()" method, "x.__add__(y)" is '
6483n/a 'called.\n'
6484n/a ' The "__divmod__()" method should be the equivalent to '
6485n/a 'using\n'
6486n/a ' "__floordiv__()" and "__mod__()"; it should not be '
6487n/a 'related to\n'
6488n/a ' "__truediv__()". Note that "__pow__()" should be '
6489n/a 'defined to accept\n'
6490n/a ' an optional third argument if the ternary version of the '
6491n/a 'built-in\n'
6492n/a ' "pow()" function is to be supported.\n'
6493n/a '\n'
6494n/a ' If one of those methods does not support the operation '
6495n/a 'with the\n'
6496n/a ' supplied arguments, it should return "NotImplemented".\n'
6497n/a '\n'
6498n/a 'object.__radd__(self, other)\n'
6499n/a 'object.__rsub__(self, other)\n'
6500n/a 'object.__rmul__(self, other)\n'
6501n/a 'object.__rmatmul__(self, other)\n'
6502n/a 'object.__rtruediv__(self, other)\n'
6503n/a 'object.__rfloordiv__(self, other)\n'
6504n/a 'object.__rmod__(self, other)\n'
6505n/a 'object.__rdivmod__(self, other)\n'
6506n/a 'object.__rpow__(self, other)\n'
6507n/a 'object.__rlshift__(self, other)\n'
6508n/a 'object.__rrshift__(self, other)\n'
6509n/a 'object.__rand__(self, other)\n'
6510n/a 'object.__rxor__(self, other)\n'
6511n/a 'object.__ror__(self, other)\n'
6512n/a '\n'
6513n/a ' These methods are called to implement the binary '
6514n/a 'arithmetic\n'
6515n/a ' operations ("+", "-", "*", "@", "/", "//", "%", '
6516n/a '"divmod()",\n'
6517n/a ' "pow()", "**", "<<", ">>", "&", "^", "|") with reflected '
6518n/a '(swapped)\n'
6519n/a ' operands. These functions are only called if the left '
6520n/a 'operand does\n'
6521n/a ' not support the corresponding operation [3] and the '
6522n/a 'operands are of\n'
6523n/a ' different types. [4] For instance, to evaluate the '
6524n/a 'expression "x -\n'
6525n/a ' y", where *y* is an instance of a class that has an '
6526n/a '"__rsub__()"\n'
6527n/a ' method, "y.__rsub__(x)" is called if "x.__sub__(y)" '
6528n/a 'returns\n'
6529n/a ' *NotImplemented*.\n'
6530n/a '\n'
6531n/a ' Note that ternary "pow()" will not try calling '
6532n/a '"__rpow__()" (the\n'
6533n/a ' coercion rules would become too complicated).\n'
6534n/a '\n'
6535n/a " Note: If the right operand's type is a subclass of the "
6536n/a 'left\n'
6537n/a " operand's type and that subclass provides the "
6538n/a 'reflected method\n'
6539n/a ' for the operation, this method will be called before '
6540n/a 'the left\n'
6541n/a " operand's non-reflected method. This behavior allows "
6542n/a 'subclasses\n'
6543n/a " to override their ancestors' operations.\n"
6544n/a '\n'
6545n/a 'object.__iadd__(self, other)\n'
6546n/a 'object.__isub__(self, other)\n'
6547n/a 'object.__imul__(self, other)\n'
6548n/a 'object.__imatmul__(self, other)\n'
6549n/a 'object.__itruediv__(self, other)\n'
6550n/a 'object.__ifloordiv__(self, other)\n'
6551n/a 'object.__imod__(self, other)\n'
6552n/a 'object.__ipow__(self, other[, modulo])\n'
6553n/a 'object.__ilshift__(self, other)\n'
6554n/a 'object.__irshift__(self, other)\n'
6555n/a 'object.__iand__(self, other)\n'
6556n/a 'object.__ixor__(self, other)\n'
6557n/a 'object.__ior__(self, other)\n'
6558n/a '\n'
6559n/a ' These methods are called to implement the augmented '
6560n/a 'arithmetic\n'
6561n/a ' assignments ("+=", "-=", "*=", "@=", "/=", "//=", "%=", '
6562n/a '"**=",\n'
6563n/a ' "<<=", ">>=", "&=", "^=", "|="). These methods should '
6564n/a 'attempt to\n'
6565n/a ' do the operation in-place (modifying *self*) and return '
6566n/a 'the result\n'
6567n/a ' (which could be, but does not have to be, *self*). If a '
6568n/a 'specific\n'
6569n/a ' method is not defined, the augmented assignment falls '
6570n/a 'back to the\n'
6571n/a ' normal methods. For instance, if *x* is an instance of '
6572n/a 'a class\n'
6573n/a ' with an "__iadd__()" method, "x += y" is equivalent to '
6574n/a '"x =\n'
6575n/a ' x.__iadd__(y)" . Otherwise, "x.__add__(y)" and '
6576n/a '"y.__radd__(x)" are\n'
6577n/a ' considered, as with the evaluation of "x + y". In '
6578n/a 'certain\n'
6579n/a ' situations, augmented assignment can result in '
6580n/a 'unexpected errors\n'
6581n/a " (see Why does a_tuple[i] += ['item'] raise an exception "
6582n/a 'when the\n'
6583n/a ' addition works?), but this behavior is in fact part of '
6584n/a 'the data\n'
6585n/a ' model.\n'
6586n/a '\n'
6587n/a 'object.__neg__(self)\n'
6588n/a 'object.__pos__(self)\n'
6589n/a 'object.__abs__(self)\n'
6590n/a 'object.__invert__(self)\n'
6591n/a '\n'
6592n/a ' Called to implement the unary arithmetic operations '
6593n/a '("-", "+",\n'
6594n/a ' "abs()" and "~").\n'
6595n/a '\n'
6596n/a 'object.__complex__(self)\n'
6597n/a 'object.__int__(self)\n'
6598n/a 'object.__float__(self)\n'
6599n/a 'object.__round__(self[, n])\n'
6600n/a '\n'
6601n/a ' Called to implement the built-in functions "complex()", '
6602n/a '"int()",\n'
6603n/a ' "float()" and "round()". Should return a value of the '
6604n/a 'appropriate\n'
6605n/a ' type.\n'
6606n/a '\n'
6607n/a 'object.__index__(self)\n'
6608n/a '\n'
6609n/a ' Called to implement "operator.index()", and whenever '
6610n/a 'Python needs\n'
6611n/a ' to losslessly convert the numeric object to an integer '
6612n/a 'object (such\n'
6613n/a ' as in slicing, or in the built-in "bin()", "hex()" and '
6614n/a '"oct()"\n'
6615n/a ' functions). Presence of this method indicates that the '
6616n/a 'numeric\n'
6617n/a ' object is an integer type. Must return an integer.\n'
6618n/a '\n'
6619n/a ' Note: In order to have a coherent integer type class, '
6620n/a 'when\n'
6621n/a ' "__index__()" is defined "__int__()" should also be '
6622n/a 'defined, and\n'
6623n/a ' both should return the same value.\n',
6624n/a 'objects': '\n'
6625n/a 'Objects, values and types\n'
6626n/a '*************************\n'
6627n/a '\n'
6628n/a "*Objects* are Python's abstraction for data. All data in a "
6629n/a 'Python\n'
6630n/a 'program is represented by objects or by relations between '
6631n/a 'objects. (In\n'
6632n/a 'a sense, and in conformance to Von Neumann\'s model of a "stored\n'
6633n/a 'program computer," code is also represented by objects.)\n'
6634n/a '\n'
6635n/a "Every object has an identity, a type and a value. An object's\n"
6636n/a '*identity* never changes once it has been created; you may think '
6637n/a 'of it\n'
6638n/a 'as the object\'s address in memory. The \'"is"\' operator '
6639n/a 'compares the\n'
6640n/a 'identity of two objects; the "id()" function returns an integer\n'
6641n/a 'representing its identity.\n'
6642n/a '\n'
6643n/a '**CPython implementation detail:** For CPython, "id(x)" is the '
6644n/a 'memory\n'
6645n/a 'address where "x" is stored.\n'
6646n/a '\n'
6647n/a "An object's type determines the operations that the object "
6648n/a 'supports\n'
6649n/a '(e.g., "does it have a length?") and also defines the possible '
6650n/a 'values\n'
6651n/a 'for objects of that type. The "type()" function returns an '
6652n/a "object's\n"
6653n/a 'type (which is an object itself). Like its identity, an '
6654n/a "object's\n"
6655n/a '*type* is also unchangeable. [1]\n'
6656n/a '\n'
6657n/a 'The *value* of some objects can change. Objects whose value can\n'
6658n/a 'change are said to be *mutable*; objects whose value is '
6659n/a 'unchangeable\n'
6660n/a 'once they are created are called *immutable*. (The value of an\n'
6661n/a 'immutable container object that contains a reference to a '
6662n/a 'mutable\n'
6663n/a "object can change when the latter's value is changed; however "
6664n/a 'the\n'
6665n/a 'container is still considered immutable, because the collection '
6666n/a 'of\n'
6667n/a 'objects it contains cannot be changed. So, immutability is not\n'
6668n/a 'strictly the same as having an unchangeable value, it is more '
6669n/a 'subtle.)\n'
6670n/a "An object's mutability is determined by its type; for instance,\n"
6671n/a 'numbers, strings and tuples are immutable, while dictionaries '
6672n/a 'and\n'
6673n/a 'lists are mutable.\n'
6674n/a '\n'
6675n/a 'Objects are never explicitly destroyed; however, when they '
6676n/a 'become\n'
6677n/a 'unreachable they may be garbage-collected. An implementation is\n'
6678n/a 'allowed to postpone garbage collection or omit it altogether --- '
6679n/a 'it is\n'
6680n/a 'a matter of implementation quality how garbage collection is\n'
6681n/a 'implemented, as long as no objects are collected that are still\n'
6682n/a 'reachable.\n'
6683n/a '\n'
6684n/a '**CPython implementation detail:** CPython currently uses a '
6685n/a 'reference-\n'
6686n/a 'counting scheme with (optional) delayed detection of cyclically '
6687n/a 'linked\n'
6688n/a 'garbage, which collects most objects as soon as they become\n'
6689n/a 'unreachable, but is not guaranteed to collect garbage containing\n'
6690n/a 'circular references. See the documentation of the "gc" module '
6691n/a 'for\n'
6692n/a 'information on controlling the collection of cyclic garbage. '
6693n/a 'Other\n'
6694n/a 'implementations act differently and CPython may change. Do not '
6695n/a 'depend\n'
6696n/a 'on immediate finalization of objects when they become unreachable '
6697n/a '(so\n'
6698n/a 'you should always close files explicitly).\n'
6699n/a '\n'
6700n/a "Note that the use of the implementation's tracing or debugging\n"
6701n/a 'facilities may keep objects alive that would normally be '
6702n/a 'collectable.\n'
6703n/a 'Also note that catching an exception with a \'"try"..."except"\'\n'
6704n/a 'statement may keep objects alive.\n'
6705n/a '\n'
6706n/a 'Some objects contain references to "external" resources such as '
6707n/a 'open\n'
6708n/a 'files or windows. It is understood that these resources are '
6709n/a 'freed\n'
6710n/a 'when the object is garbage-collected, but since garbage '
6711n/a 'collection is\n'
6712n/a 'not guaranteed to happen, such objects also provide an explicit '
6713n/a 'way to\n'
6714n/a 'release the external resource, usually a "close()" method. '
6715n/a 'Programs\n'
6716n/a 'are strongly recommended to explicitly close such objects. The\n'
6717n/a '\'"try"..."finally"\' statement and the \'"with"\' statement '
6718n/a 'provide\n'
6719n/a 'convenient ways to do this.\n'
6720n/a '\n'
6721n/a 'Some objects contain references to other objects; these are '
6722n/a 'called\n'
6723n/a '*containers*. Examples of containers are tuples, lists and\n'
6724n/a "dictionaries. The references are part of a container's value. "
6725n/a 'In\n'
6726n/a 'most cases, when we talk about the value of a container, we imply '
6727n/a 'the\n'
6728n/a 'values, not the identities of the contained objects; however, '
6729n/a 'when we\n'
6730n/a 'talk about the mutability of a container, only the identities of '
6731n/a 'the\n'
6732n/a 'immediately contained objects are implied. So, if an immutable\n'
6733n/a 'container (like a tuple) contains a reference to a mutable '
6734n/a 'object, its\n'
6735n/a 'value changes if that mutable object is changed.\n'
6736n/a '\n'
6737n/a 'Types affect almost all aspects of object behavior. Even the\n'
6738n/a 'importance of object identity is affected in some sense: for '
6739n/a 'immutable\n'
6740n/a 'types, operations that compute new values may actually return a\n'
6741n/a 'reference to any existing object with the same type and value, '
6742n/a 'while\n'
6743n/a 'for mutable objects this is not allowed. E.g., after "a = 1; b = '
6744n/a '1",\n'
6745n/a '"a" and "b" may or may not refer to the same object with the '
6746n/a 'value\n'
6747n/a 'one, depending on the implementation, but after "c = []; d = []", '
6748n/a '"c"\n'
6749n/a 'and "d" are guaranteed to refer to two different, unique, newly\n'
6750n/a 'created empty lists. (Note that "c = d = []" assigns the same '
6751n/a 'object\n'
6752n/a 'to both "c" and "d".)\n',
6753n/a 'operator-summary': '\n'
6754n/a 'Operator precedence\n'
6755n/a '*******************\n'
6756n/a '\n'
6757n/a 'The following table summarizes the operator precedence '
6758n/a 'in Python, from\n'
6759n/a 'lowest precedence (least binding) to highest precedence '
6760n/a '(most\n'
6761n/a 'binding). Operators in the same box have the same '
6762n/a 'precedence. Unless\n'
6763n/a 'the syntax is explicitly given, operators are binary. '
6764n/a 'Operators in\n'
6765n/a 'the same box group left to right (except for '
6766n/a 'exponentiation, which\n'
6767n/a 'groups from right to left).\n'
6768n/a '\n'
6769n/a 'Note that comparisons, membership tests, and identity '
6770n/a 'tests, all have\n'
6771n/a 'the same precedence and have a left-to-right chaining '
6772n/a 'feature as\n'
6773n/a 'described in the Comparisons section.\n'
6774n/a '\n'
6775n/a '+-------------------------------------------------+---------------------------------------+\n'
6776n/a '| Operator | '
6777n/a 'Description |\n'
6778n/a '+=================================================+=======================================+\n'
6779n/a '| "lambda" | '
6780n/a 'Lambda expression |\n'
6781n/a '+-------------------------------------------------+---------------------------------------+\n'
6782n/a '| "if" -- "else" | '
6783n/a 'Conditional expression |\n'
6784n/a '+-------------------------------------------------+---------------------------------------+\n'
6785n/a '| "or" | '
6786n/a 'Boolean OR |\n'
6787n/a '+-------------------------------------------------+---------------------------------------+\n'
6788n/a '| "and" | '
6789n/a 'Boolean AND |\n'
6790n/a '+-------------------------------------------------+---------------------------------------+\n'
6791n/a '| "not" "x" | '
6792n/a 'Boolean NOT |\n'
6793n/a '+-------------------------------------------------+---------------------------------------+\n'
6794n/a '| "in", "not in", "is", "is not", "<", "<=", ">", | '
6795n/a 'Comparisons, including membership |\n'
6796n/a '| ">=", "!=", "==" | '
6797n/a 'tests and identity tests |\n'
6798n/a '+-------------------------------------------------+---------------------------------------+\n'
6799n/a '| "|" | '
6800n/a 'Bitwise OR |\n'
6801n/a '+-------------------------------------------------+---------------------------------------+\n'
6802n/a '| "^" | '
6803n/a 'Bitwise XOR |\n'
6804n/a '+-------------------------------------------------+---------------------------------------+\n'
6805n/a '| "&" | '
6806n/a 'Bitwise AND |\n'
6807n/a '+-------------------------------------------------+---------------------------------------+\n'
6808n/a '| "<<", ">>" | '
6809n/a 'Shifts |\n'
6810n/a '+-------------------------------------------------+---------------------------------------+\n'
6811n/a '| "+", "-" | '
6812n/a 'Addition and subtraction |\n'
6813n/a '+-------------------------------------------------+---------------------------------------+\n'
6814n/a '| "*", "@", "/", "//", "%" | '
6815n/a 'Multiplication, matrix multiplication |\n'
6816n/a '| | '
6817n/a 'division, remainder [5] |\n'
6818n/a '+-------------------------------------------------+---------------------------------------+\n'
6819n/a '| "+x", "-x", "~x" | '
6820n/a 'Positive, negative, bitwise NOT |\n'
6821n/a '+-------------------------------------------------+---------------------------------------+\n'
6822n/a '| "**" | '
6823n/a 'Exponentiation [6] |\n'
6824n/a '+-------------------------------------------------+---------------------------------------+\n'
6825n/a '| "await" "x" | '
6826n/a 'Await expression |\n'
6827n/a '+-------------------------------------------------+---------------------------------------+\n'
6828n/a '| "x[index]", "x[index:index]", | '
6829n/a 'Subscription, slicing, call, |\n'
6830n/a '| "x(arguments...)", "x.attribute" | '
6831n/a 'attribute reference |\n'
6832n/a '+-------------------------------------------------+---------------------------------------+\n'
6833n/a '| "(expressions...)", "[expressions...]", "{key: | '
6834n/a 'Binding or tuple display, list |\n'
6835n/a '| value...}", "{expressions...}" | '
6836n/a 'display, dictionary display, set |\n'
6837n/a '| | '
6838n/a 'display |\n'
6839n/a '+-------------------------------------------------+---------------------------------------+\n'
6840n/a '\n'
6841n/a '-[ Footnotes ]-\n'
6842n/a '\n'
6843n/a '[1] While "abs(x%y) < abs(y)" is true mathematically, '
6844n/a 'for floats\n'
6845n/a ' it may not be true numerically due to roundoff. For '
6846n/a 'example, and\n'
6847n/a ' assuming a platform on which a Python float is an '
6848n/a 'IEEE 754 double-\n'
6849n/a ' precision number, in order that "-1e-100 % 1e100" '
6850n/a 'have the same\n'
6851n/a ' sign as "1e100", the computed result is "-1e-100 + '
6852n/a '1e100", which\n'
6853n/a ' is numerically exactly equal to "1e100". The '
6854n/a 'function\n'
6855n/a ' "math.fmod()" returns a result whose sign matches '
6856n/a 'the sign of the\n'
6857n/a ' first argument instead, and so returns "-1e-100" in '
6858n/a 'this case.\n'
6859n/a ' Which approach is more appropriate depends on the '
6860n/a 'application.\n'
6861n/a '\n'
6862n/a '[2] If x is very close to an exact integer multiple of '
6863n/a "y, it's\n"
6864n/a ' possible for "x//y" to be one larger than '
6865n/a '"(x-x%y)//y" due to\n'
6866n/a ' rounding. In such cases, Python returns the latter '
6867n/a 'result, in\n'
6868n/a ' order to preserve that "divmod(x,y)[0] * y + x % y" '
6869n/a 'be very close\n'
6870n/a ' to "x".\n'
6871n/a '\n'
6872n/a '[3] The Unicode standard distinguishes between *code '
6873n/a 'points* (e.g.\n'
6874n/a ' U+0041) and *abstract characters* (e.g. "LATIN '
6875n/a 'CAPITAL LETTER A").\n'
6876n/a ' While most abstract characters in Unicode are only '
6877n/a 'represented\n'
6878n/a ' using one code point, there is a number of abstract '
6879n/a 'characters\n'
6880n/a ' that can in addition be represented using a sequence '
6881n/a 'of more than\n'
6882n/a ' one code point. For example, the abstract character '
6883n/a '"LATIN\n'
6884n/a ' CAPITAL LETTER C WITH CEDILLA" can be represented as '
6885n/a 'a single\n'
6886n/a ' *precomposed character* at code position U+00C7, or '
6887n/a 'as a sequence\n'
6888n/a ' of a *base character* at code position U+0043 (LATIN '
6889n/a 'CAPITAL\n'
6890n/a ' LETTER C), followed by a *combining character* at '
6891n/a 'code position\n'
6892n/a ' U+0327 (COMBINING CEDILLA).\n'
6893n/a '\n'
6894n/a ' The comparison operators on strings compare at the '
6895n/a 'level of\n'
6896n/a ' Unicode code points. This may be counter-intuitive '
6897n/a 'to humans. For\n'
6898n/a ' example, ""\\u00C7" == "\\u0043\\u0327"" is "False", '
6899n/a 'even though both\n'
6900n/a ' strings represent the same abstract character "LATIN '
6901n/a 'CAPITAL\n'
6902n/a ' LETTER C WITH CEDILLA".\n'
6903n/a '\n'
6904n/a ' To compare strings at the level of abstract '
6905n/a 'characters (that is,\n'
6906n/a ' in a way intuitive to humans), use '
6907n/a '"unicodedata.normalize()".\n'
6908n/a '\n'
6909n/a '[4] Due to automatic garbage-collection, free lists, and '
6910n/a 'the\n'
6911n/a ' dynamic nature of descriptors, you may notice '
6912n/a 'seemingly unusual\n'
6913n/a ' behaviour in certain uses of the "is" operator, like '
6914n/a 'those\n'
6915n/a ' involving comparisons between instance methods, or '
6916n/a 'constants.\n'
6917n/a ' Check their documentation for more info.\n'
6918n/a '\n'
6919n/a '[5] The "%" operator is also used for string formatting; '
6920n/a 'the same\n'
6921n/a ' precedence applies.\n'
6922n/a '\n'
6923n/a '[6] The power operator "**" binds less tightly than an '
6924n/a 'arithmetic\n'
6925n/a ' or bitwise unary operator on its right, that is, '
6926n/a '"2**-1" is "0.5".\n',
6927n/a 'pass': '\n'
6928n/a 'The "pass" statement\n'
6929n/a '********************\n'
6930n/a '\n'
6931n/a ' pass_stmt ::= "pass"\n'
6932n/a '\n'
6933n/a '"pass" is a null operation --- when it is executed, nothing '
6934n/a 'happens.\n'
6935n/a 'It is useful as a placeholder when a statement is required\n'
6936n/a 'syntactically, but no code needs to be executed, for example:\n'
6937n/a '\n'
6938n/a ' def f(arg): pass # a function that does nothing (yet)\n'
6939n/a '\n'
6940n/a ' class C: pass # a class with no methods (yet)\n',
6941n/a 'power': '\n'
6942n/a 'The power operator\n'
6943n/a '******************\n'
6944n/a '\n'
6945n/a 'The power operator binds more tightly than unary operators on its\n'
6946n/a 'left; it binds less tightly than unary operators on its right. '
6947n/a 'The\n'
6948n/a 'syntax is:\n'
6949n/a '\n'
6950n/a ' power ::= ( await_expr | primary ) ["**" u_expr]\n'
6951n/a '\n'
6952n/a 'Thus, in an unparenthesized sequence of power and unary operators, '
6953n/a 'the\n'
6954n/a 'operators are evaluated from right to left (this does not '
6955n/a 'constrain\n'
6956n/a 'the evaluation order for the operands): "-1**2" results in "-1".\n'
6957n/a '\n'
6958n/a 'The power operator has the same semantics as the built-in "pow()"\n'
6959n/a 'function, when called with two arguments: it yields its left '
6960n/a 'argument\n'
6961n/a 'raised to the power of its right argument. The numeric arguments '
6962n/a 'are\n'
6963n/a 'first converted to a common type, and the result is of that type.\n'
6964n/a '\n'
6965n/a 'For int operands, the result has the same type as the operands '
6966n/a 'unless\n'
6967n/a 'the second argument is negative; in that case, all arguments are\n'
6968n/a 'converted to float and a float result is delivered. For example,\n'
6969n/a '"10**2" returns "100", but "10**-2" returns "0.01".\n'
6970n/a '\n'
6971n/a 'Raising "0.0" to a negative power results in a '
6972n/a '"ZeroDivisionError".\n'
6973n/a 'Raising a negative number to a fractional power results in a '
6974n/a '"complex"\n'
6975n/a 'number. (In earlier versions it raised a "ValueError".)\n',
6976n/a 'raise': '\n'
6977n/a 'The "raise" statement\n'
6978n/a '*********************\n'
6979n/a '\n'
6980n/a ' raise_stmt ::= "raise" [expression ["from" expression]]\n'
6981n/a '\n'
6982n/a 'If no expressions are present, "raise" re-raises the last '
6983n/a 'exception\n'
6984n/a 'that was active in the current scope. If no exception is active '
6985n/a 'in\n'
6986n/a 'the current scope, a "RuntimeError" exception is raised indicating\n'
6987n/a 'that this is an error.\n'
6988n/a '\n'
6989n/a 'Otherwise, "raise" evaluates the first expression as the exception\n'
6990n/a 'object. It must be either a subclass or an instance of\n'
6991n/a '"BaseException". If it is a class, the exception instance will be\n'
6992n/a 'obtained when needed by instantiating the class with no arguments.\n'
6993n/a '\n'
6994n/a "The *type* of the exception is the exception instance's class, the\n"
6995n/a '*value* is the instance itself.\n'
6996n/a '\n'
6997n/a 'A traceback object is normally created automatically when an '
6998n/a 'exception\n'
6999n/a 'is raised and attached to it as the "__traceback__" attribute, '
7000n/a 'which\n'
7001n/a 'is writable. You can create an exception and set your own traceback '
7002n/a 'in\n'
7003n/a 'one step using the "with_traceback()" exception method (which '
7004n/a 'returns\n'
7005n/a 'the same exception instance, with its traceback set to its '
7006n/a 'argument),\n'
7007n/a 'like so:\n'
7008n/a '\n'
7009n/a ' raise Exception("foo occurred").with_traceback(tracebackobj)\n'
7010n/a '\n'
7011n/a 'The "from" clause is used for exception chaining: if given, the '
7012n/a 'second\n'
7013n/a '*expression* must be another exception class or instance, which '
7014n/a 'will\n'
7015n/a 'then be attached to the raised exception as the "__cause__" '
7016n/a 'attribute\n'
7017n/a '(which is writable). If the raised exception is not handled, both\n'
7018n/a 'exceptions will be printed:\n'
7019n/a '\n'
7020n/a ' >>> try:\n'
7021n/a ' ... print(1 / 0)\n'
7022n/a ' ... except Exception as exc:\n'
7023n/a ' ... raise RuntimeError("Something bad happened") from exc\n'
7024n/a ' ...\n'
7025n/a ' Traceback (most recent call last):\n'
7026n/a ' File "<stdin>", line 2, in <module>\n'
7027n/a ' ZeroDivisionError: int division or modulo by zero\n'
7028n/a '\n'
7029n/a ' The above exception was the direct cause of the following '
7030n/a 'exception:\n'
7031n/a '\n'
7032n/a ' Traceback (most recent call last):\n'
7033n/a ' File "<stdin>", line 4, in <module>\n'
7034n/a ' RuntimeError: Something bad happened\n'
7035n/a '\n'
7036n/a 'A similar mechanism works implicitly if an exception is raised '
7037n/a 'inside\n'
7038n/a 'an exception handler or a "finally" clause: the previous exception '
7039n/a 'is\n'
7040n/a 'then attached as the new exception\'s "__context__" attribute:\n'
7041n/a '\n'
7042n/a ' >>> try:\n'
7043n/a ' ... print(1 / 0)\n'
7044n/a ' ... except:\n'
7045n/a ' ... raise RuntimeError("Something bad happened")\n'
7046n/a ' ...\n'
7047n/a ' Traceback (most recent call last):\n'
7048n/a ' File "<stdin>", line 2, in <module>\n'
7049n/a ' ZeroDivisionError: int division or modulo by zero\n'
7050n/a '\n'
7051n/a ' During handling of the above exception, another exception '
7052n/a 'occurred:\n'
7053n/a '\n'
7054n/a ' Traceback (most recent call last):\n'
7055n/a ' File "<stdin>", line 4, in <module>\n'
7056n/a ' RuntimeError: Something bad happened\n'
7057n/a '\n'
7058n/a 'Additional information on exceptions can be found in section\n'
7059n/a 'Exceptions, and information about handling exceptions is in '
7060n/a 'section\n'
7061n/a 'The try statement.\n',
7062n/a 'return': '\n'
7063n/a 'The "return" statement\n'
7064n/a '**********************\n'
7065n/a '\n'
7066n/a ' return_stmt ::= "return" [expression_list]\n'
7067n/a '\n'
7068n/a '"return" may only occur syntactically nested in a function '
7069n/a 'definition,\n'
7070n/a 'not within a nested class definition.\n'
7071n/a '\n'
7072n/a 'If an expression list is present, it is evaluated, else "None" is\n'
7073n/a 'substituted.\n'
7074n/a '\n'
7075n/a '"return" leaves the current function call with the expression list '
7076n/a '(or\n'
7077n/a '"None") as return value.\n'
7078n/a '\n'
7079n/a 'When "return" passes control out of a "try" statement with a '
7080n/a '"finally"\n'
7081n/a 'clause, that "finally" clause is executed before really leaving '
7082n/a 'the\n'
7083n/a 'function.\n'
7084n/a '\n'
7085n/a 'In a generator function, the "return" statement indicates that '
7086n/a 'the\n'
7087n/a 'generator is done and will cause "StopIteration" to be raised. '
7088n/a 'The\n'
7089n/a 'returned value (if any) is used as an argument to construct\n'
7090n/a '"StopIteration" and becomes the "StopIteration.value" attribute.\n',
7091n/a 'sequence-types': '\n'
7092n/a 'Emulating container types\n'
7093n/a '*************************\n'
7094n/a '\n'
7095n/a 'The following methods can be defined to implement '
7096n/a 'container objects.\n'
7097n/a 'Containers usually are sequences (such as lists or tuples) '
7098n/a 'or mappings\n'
7099n/a '(like dictionaries), but can represent other containers as '
7100n/a 'well. The\n'
7101n/a 'first set of methods is used either to emulate a sequence '
7102n/a 'or to\n'
7103n/a 'emulate a mapping; the difference is that for a sequence, '
7104n/a 'the\n'
7105n/a 'allowable keys should be the integers *k* for which "0 <= '
7106n/a 'k < N" where\n'
7107n/a '*N* is the length of the sequence, or slice objects, which '
7108n/a 'define a\n'
7109n/a 'range of items. It is also recommended that mappings '
7110n/a 'provide the\n'
7111n/a 'methods "keys()", "values()", "items()", "get()", '
7112n/a '"clear()",\n'
7113n/a '"setdefault()", "pop()", "popitem()", "copy()", and '
7114n/a '"update()"\n'
7115n/a "behaving similar to those for Python's standard dictionary "
7116n/a 'objects.\n'
7117n/a 'The "collections" module provides a "MutableMapping" '
7118n/a 'abstract base\n'
7119n/a 'class to help create those methods from a base set of '
7120n/a '"__getitem__()",\n'
7121n/a '"__setitem__()", "__delitem__()", and "keys()". Mutable '
7122n/a 'sequences\n'
7123n/a 'should provide methods "append()", "count()", "index()", '
7124n/a '"extend()",\n'
7125n/a '"insert()", "pop()", "remove()", "reverse()" and "sort()", '
7126n/a 'like Python\n'
7127n/a 'standard list objects. Finally, sequence types should '
7128n/a 'implement\n'
7129n/a 'addition (meaning concatenation) and multiplication '
7130n/a '(meaning\n'
7131n/a 'repetition) by defining the methods "__add__()", '
7132n/a '"__radd__()",\n'
7133n/a '"__iadd__()", "__mul__()", "__rmul__()" and "__imul__()" '
7134n/a 'described\n'
7135n/a 'below; they should not define other numerical operators. '
7136n/a 'It is\n'
7137n/a 'recommended that both mappings and sequences implement '
7138n/a 'the\n'
7139n/a '"__contains__()" method to allow efficient use of the "in" '
7140n/a 'operator;\n'
7141n/a 'for mappings, "in" should search the mapping\'s keys; for '
7142n/a 'sequences, it\n'
7143n/a 'should search through the values. It is further '
7144n/a 'recommended that both\n'
7145n/a 'mappings and sequences implement the "__iter__()" method '
7146n/a 'to allow\n'
7147n/a 'efficient iteration through the container; for mappings, '
7148n/a '"__iter__()"\n'
7149n/a 'should be the same as "keys()"; for sequences, it should '
7150n/a 'iterate\n'
7151n/a 'through the values.\n'
7152n/a '\n'
7153n/a 'object.__len__(self)\n'
7154n/a '\n'
7155n/a ' Called to implement the built-in function "len()". '
7156n/a 'Should return\n'
7157n/a ' the length of the object, an integer ">=" 0. Also, an '
7158n/a 'object that\n'
7159n/a ' doesn\'t define a "__bool__()" method and whose '
7160n/a '"__len__()" method\n'
7161n/a ' returns zero is considered to be false in a Boolean '
7162n/a 'context.\n'
7163n/a '\n'
7164n/a 'object.__length_hint__(self)\n'
7165n/a '\n'
7166n/a ' Called to implement "operator.length_hint()". Should '
7167n/a 'return an\n'
7168n/a ' estimated length for the object (which may be greater '
7169n/a 'or less than\n'
7170n/a ' the actual length). The length must be an integer ">=" '
7171n/a '0. This\n'
7172n/a ' method is purely an optimization and is never required '
7173n/a 'for\n'
7174n/a ' correctness.\n'
7175n/a '\n'
7176n/a ' New in version 3.4.\n'
7177n/a '\n'
7178n/a 'Note: Slicing is done exclusively with the following three '
7179n/a 'methods.\n'
7180n/a ' A call like\n'
7181n/a '\n'
7182n/a ' a[1:2] = b\n'
7183n/a '\n'
7184n/a ' is translated to\n'
7185n/a '\n'
7186n/a ' a[slice(1, 2, None)] = b\n'
7187n/a '\n'
7188n/a ' and so forth. Missing slice items are always filled in '
7189n/a 'with "None".\n'
7190n/a '\n'
7191n/a 'object.__getitem__(self, key)\n'
7192n/a '\n'
7193n/a ' Called to implement evaluation of "self[key]". For '
7194n/a 'sequence types,\n'
7195n/a ' the accepted keys should be integers and slice '
7196n/a 'objects. Note that\n'
7197n/a ' the special interpretation of negative indexes (if the '
7198n/a 'class wishes\n'
7199n/a ' to emulate a sequence type) is up to the '
7200n/a '"__getitem__()" method. If\n'
7201n/a ' *key* is of an inappropriate type, "TypeError" may be '
7202n/a 'raised; if of\n'
7203n/a ' a value outside the set of indexes for the sequence '
7204n/a '(after any\n'
7205n/a ' special interpretation of negative values), '
7206n/a '"IndexError" should be\n'
7207n/a ' raised. For mapping types, if *key* is missing (not in '
7208n/a 'the\n'
7209n/a ' container), "KeyError" should be raised.\n'
7210n/a '\n'
7211n/a ' Note: "for" loops expect that an "IndexError" will be '
7212n/a 'raised for\n'
7213n/a ' illegal indexes to allow proper detection of the end '
7214n/a 'of the\n'
7215n/a ' sequence.\n'
7216n/a '\n'
7217n/a 'object.__missing__(self, key)\n'
7218n/a '\n'
7219n/a ' Called by "dict"."__getitem__()" to implement '
7220n/a '"self[key]" for dict\n'
7221n/a ' subclasses when key is not in the dictionary.\n'
7222n/a '\n'
7223n/a 'object.__setitem__(self, key, value)\n'
7224n/a '\n'
7225n/a ' Called to implement assignment to "self[key]". Same '
7226n/a 'note as for\n'
7227n/a ' "__getitem__()". This should only be implemented for '
7228n/a 'mappings if\n'
7229n/a ' the objects support changes to the values for keys, or '
7230n/a 'if new keys\n'
7231n/a ' can be added, or for sequences if elements can be '
7232n/a 'replaced. The\n'
7233n/a ' same exceptions should be raised for improper *key* '
7234n/a 'values as for\n'
7235n/a ' the "__getitem__()" method.\n'
7236n/a '\n'
7237n/a 'object.__delitem__(self, key)\n'
7238n/a '\n'
7239n/a ' Called to implement deletion of "self[key]". Same note '
7240n/a 'as for\n'
7241n/a ' "__getitem__()". This should only be implemented for '
7242n/a 'mappings if\n'
7243n/a ' the objects support removal of keys, or for sequences '
7244n/a 'if elements\n'
7245n/a ' can be removed from the sequence. The same exceptions '
7246n/a 'should be\n'
7247n/a ' raised for improper *key* values as for the '
7248n/a '"__getitem__()" method.\n'
7249n/a '\n'
7250n/a 'object.__iter__(self)\n'
7251n/a '\n'
7252n/a ' This method is called when an iterator is required for '
7253n/a 'a container.\n'
7254n/a ' This method should return a new iterator object that '
7255n/a 'can iterate\n'
7256n/a ' over all the objects in the container. For mappings, '
7257n/a 'it should\n'
7258n/a ' iterate over the keys of the container.\n'
7259n/a '\n'
7260n/a ' Iterator objects also need to implement this method; '
7261n/a 'they are\n'
7262n/a ' required to return themselves. For more information on '
7263n/a 'iterator\n'
7264n/a ' objects, see Iterator Types.\n'
7265n/a '\n'
7266n/a 'object.__reversed__(self)\n'
7267n/a '\n'
7268n/a ' Called (if present) by the "reversed()" built-in to '
7269n/a 'implement\n'
7270n/a ' reverse iteration. It should return a new iterator '
7271n/a 'object that\n'
7272n/a ' iterates over all the objects in the container in '
7273n/a 'reverse order.\n'
7274n/a '\n'
7275n/a ' If the "__reversed__()" method is not provided, the '
7276n/a '"reversed()"\n'
7277n/a ' built-in will fall back to using the sequence protocol '
7278n/a '("__len__()"\n'
7279n/a ' and "__getitem__()"). Objects that support the '
7280n/a 'sequence protocol\n'
7281n/a ' should only provide "__reversed__()" if they can '
7282n/a 'provide an\n'
7283n/a ' implementation that is more efficient than the one '
7284n/a 'provided by\n'
7285n/a ' "reversed()".\n'
7286n/a '\n'
7287n/a 'The membership test operators ("in" and "not in") are '
7288n/a 'normally\n'
7289n/a 'implemented as an iteration through a sequence. However, '
7290n/a 'container\n'
7291n/a 'objects can supply the following special method with a '
7292n/a 'more efficient\n'
7293n/a 'implementation, which also does not require the object be '
7294n/a 'a sequence.\n'
7295n/a '\n'
7296n/a 'object.__contains__(self, item)\n'
7297n/a '\n'
7298n/a ' Called to implement membership test operators. Should '
7299n/a 'return true\n'
7300n/a ' if *item* is in *self*, false otherwise. For mapping '
7301n/a 'objects, this\n'
7302n/a ' should consider the keys of the mapping rather than the '
7303n/a 'values or\n'
7304n/a ' the key-item pairs.\n'
7305n/a '\n'
7306n/a ' For objects that don\'t define "__contains__()", the '
7307n/a 'membership test\n'
7308n/a ' first tries iteration via "__iter__()", then the old '
7309n/a 'sequence\n'
7310n/a ' iteration protocol via "__getitem__()", see this '
7311n/a 'section in the\n'
7312n/a ' language reference.\n',
7313n/a 'shifting': '\n'
7314n/a 'Shifting operations\n'
7315n/a '*******************\n'
7316n/a '\n'
7317n/a 'The shifting operations have lower priority than the arithmetic\n'
7318n/a 'operations:\n'
7319n/a '\n'
7320n/a ' shift_expr ::= a_expr | shift_expr ( "<<" | ">>" ) a_expr\n'
7321n/a '\n'
7322n/a 'These operators accept integers as arguments. They shift the '
7323n/a 'first\n'
7324n/a 'argument to the left or right by the number of bits given by '
7325n/a 'the\n'
7326n/a 'second argument.\n'
7327n/a '\n'
7328n/a 'A right shift by *n* bits is defined as floor division by '
7329n/a '"pow(2,n)".\n'
7330n/a 'A left shift by *n* bits is defined as multiplication with '
7331n/a '"pow(2,n)".\n'
7332n/a '\n'
7333n/a 'Note: In the current implementation, the right-hand operand is\n'
7334n/a ' required to be at most "sys.maxsize". If the right-hand '
7335n/a 'operand is\n'
7336n/a ' larger than "sys.maxsize" an "OverflowError" exception is '
7337n/a 'raised.\n',
7338n/a 'slicings': '\n'
7339n/a 'Slicings\n'
7340n/a '********\n'
7341n/a '\n'
7342n/a 'A slicing selects a range of items in a sequence object (e.g., '
7343n/a 'a\n'
7344n/a 'string, tuple or list). Slicings may be used as expressions or '
7345n/a 'as\n'
7346n/a 'targets in assignment or "del" statements. The syntax for a '
7347n/a 'slicing:\n'
7348n/a '\n'
7349n/a ' slicing ::= primary "[" slice_list "]"\n'
7350n/a ' slice_list ::= slice_item ("," slice_item)* [","]\n'
7351n/a ' slice_item ::= expression | proper_slice\n'
7352n/a ' proper_slice ::= [lower_bound] ":" [upper_bound] [ ":" '
7353n/a '[stride] ]\n'
7354n/a ' lower_bound ::= expression\n'
7355n/a ' upper_bound ::= expression\n'
7356n/a ' stride ::= expression\n'
7357n/a '\n'
7358n/a 'There is ambiguity in the formal syntax here: anything that '
7359n/a 'looks like\n'
7360n/a 'an expression list also looks like a slice list, so any '
7361n/a 'subscription\n'
7362n/a 'can be interpreted as a slicing. Rather than further '
7363n/a 'complicating the\n'
7364n/a 'syntax, this is disambiguated by defining that in this case the\n'
7365n/a 'interpretation as a subscription takes priority over the\n'
7366n/a 'interpretation as a slicing (this is the case if the slice list\n'
7367n/a 'contains no proper slice).\n'
7368n/a '\n'
7369n/a 'The semantics for a slicing are as follows. The primary is '
7370n/a 'indexed\n'
7371n/a '(using the same "__getitem__()" method as normal subscription) '
7372n/a 'with a\n'
7373n/a 'key that is constructed from the slice list, as follows. If the '
7374n/a 'slice\n'
7375n/a 'list contains at least one comma, the key is a tuple containing '
7376n/a 'the\n'
7377n/a 'conversion of the slice items; otherwise, the conversion of the '
7378n/a 'lone\n'
7379n/a 'slice item is the key. The conversion of a slice item that is '
7380n/a 'an\n'
7381n/a 'expression is that expression. The conversion of a proper slice '
7382n/a 'is a\n'
7383n/a 'slice object (see section The standard type hierarchy) whose '
7384n/a '"start",\n'
7385n/a '"stop" and "step" attributes are the values of the expressions '
7386n/a 'given\n'
7387n/a 'as lower bound, upper bound and stride, respectively, '
7388n/a 'substituting\n'
7389n/a '"None" for missing expressions.\n',
7390n/a 'specialattrs': '\n'
7391n/a 'Special Attributes\n'
7392n/a '******************\n'
7393n/a '\n'
7394n/a 'The implementation adds a few special read-only attributes '
7395n/a 'to several\n'
7396n/a 'object types, where they are relevant. Some of these are '
7397n/a 'not reported\n'
7398n/a 'by the "dir()" built-in function.\n'
7399n/a '\n'
7400n/a 'object.__dict__\n'
7401n/a '\n'
7402n/a ' A dictionary or other mapping object used to store an '
7403n/a "object's\n"
7404n/a ' (writable) attributes.\n'
7405n/a '\n'
7406n/a 'instance.__class__\n'
7407n/a '\n'
7408n/a ' The class to which a class instance belongs.\n'
7409n/a '\n'
7410n/a 'class.__bases__\n'
7411n/a '\n'
7412n/a ' The tuple of base classes of a class object.\n'
7413n/a '\n'
7414n/a 'definition.__name__\n'
7415n/a '\n'
7416n/a ' The name of the class, function, method, descriptor, or '
7417n/a 'generator\n'
7418n/a ' instance.\n'
7419n/a '\n'
7420n/a 'definition.__qualname__\n'
7421n/a '\n'
7422n/a ' The *qualified name* of the class, function, method, '
7423n/a 'descriptor, or\n'
7424n/a ' generator instance.\n'
7425n/a '\n'
7426n/a ' New in version 3.3.\n'
7427n/a '\n'
7428n/a 'class.__mro__\n'
7429n/a '\n'
7430n/a ' This attribute is a tuple of classes that are considered '
7431n/a 'when\n'
7432n/a ' looking for base classes during method resolution.\n'
7433n/a '\n'
7434n/a 'class.mro()\n'
7435n/a '\n'
7436n/a ' This method can be overridden by a metaclass to customize '
7437n/a 'the\n'
7438n/a ' method resolution order for its instances. It is called '
7439n/a 'at class\n'
7440n/a ' instantiation, and its result is stored in "__mro__".\n'
7441n/a '\n'
7442n/a 'class.__subclasses__()\n'
7443n/a '\n'
7444n/a ' Each class keeps a list of weak references to its '
7445n/a 'immediate\n'
7446n/a ' subclasses. This method returns a list of all those '
7447n/a 'references\n'
7448n/a ' still alive. Example:\n'
7449n/a '\n'
7450n/a ' >>> int.__subclasses__()\n'
7451n/a " [<class 'bool'>]\n"
7452n/a '\n'
7453n/a '-[ Footnotes ]-\n'
7454n/a '\n'
7455n/a '[1] Additional information on these special methods may be '
7456n/a 'found\n'
7457n/a ' in the Python Reference Manual (Basic customization).\n'
7458n/a '\n'
7459n/a '[2] As a consequence, the list "[1, 2]" is considered equal '
7460n/a 'to\n'
7461n/a ' "[1.0, 2.0]", and similarly for tuples.\n'
7462n/a '\n'
7463n/a "[3] They must have since the parser can't tell the type of "
7464n/a 'the\n'
7465n/a ' operands.\n'
7466n/a '\n'
7467n/a '[4] Cased characters are those with general category '
7468n/a 'property\n'
7469n/a ' being one of "Lu" (Letter, uppercase), "Ll" (Letter, '
7470n/a 'lowercase),\n'
7471n/a ' or "Lt" (Letter, titlecase).\n'
7472n/a '\n'
7473n/a '[5] To format only a tuple you should therefore provide a\n'
7474n/a ' singleton tuple whose only element is the tuple to be '
7475n/a 'formatted.\n',
7476n/a 'specialnames': '\n'
7477n/a 'Special method names\n'
7478n/a '********************\n'
7479n/a '\n'
7480n/a 'A class can implement certain operations that are invoked by '
7481n/a 'special\n'
7482n/a 'syntax (such as arithmetic operations or subscripting and '
7483n/a 'slicing) by\n'
7484n/a "defining methods with special names. This is Python's "
7485n/a 'approach to\n'
7486n/a '*operator overloading*, allowing classes to define their own '
7487n/a 'behavior\n'
7488n/a 'with respect to language operators. For instance, if a '
7489n/a 'class defines\n'
7490n/a 'a method named "__getitem__()", and "x" is an instance of '
7491n/a 'this class,\n'
7492n/a 'then "x[i]" is roughly equivalent to "type(x).__getitem__(x, '
7493n/a 'i)".\n'
7494n/a 'Except where mentioned, attempts to execute an operation '
7495n/a 'raise an\n'
7496n/a 'exception when no appropriate method is defined (typically\n'
7497n/a '"AttributeError" or "TypeError").\n'
7498n/a '\n'
7499n/a 'Setting a special method to "None" indicates that the '
7500n/a 'corresponding\n'
7501n/a 'operation is not available. For example, if a class sets '
7502n/a '"__iter__()"\n'
7503n/a 'to "None", the class is not iterable, so calling "iter()" on '
7504n/a 'its\n'
7505n/a 'instances will raise a "TypeError" (without falling back to\n'
7506n/a '"__getitem__()"). [2]\n'
7507n/a '\n'
7508n/a 'When implementing a class that emulates any built-in type, '
7509n/a 'it is\n'
7510n/a 'important that the emulation only be implemented to the '
7511n/a 'degree that it\n'
7512n/a 'makes sense for the object being modelled. For example, '
7513n/a 'some\n'
7514n/a 'sequences may work well with retrieval of individual '
7515n/a 'elements, but\n'
7516n/a 'extracting a slice may not make sense. (One example of this '
7517n/a 'is the\n'
7518n/a '"NodeList" interface in the W3C\'s Document Object Model.)\n'
7519n/a '\n'
7520n/a '\n'
7521n/a 'Basic customization\n'
7522n/a '===================\n'
7523n/a '\n'
7524n/a 'object.__new__(cls[, ...])\n'
7525n/a '\n'
7526n/a ' Called to create a new instance of class *cls*. '
7527n/a '"__new__()" is a\n'
7528n/a ' static method (special-cased so you need not declare it '
7529n/a 'as such)\n'
7530n/a ' that takes the class of which an instance was requested '
7531n/a 'as its\n'
7532n/a ' first argument. The remaining arguments are those passed '
7533n/a 'to the\n'
7534n/a ' object constructor expression (the call to the class). '
7535n/a 'The return\n'
7536n/a ' value of "__new__()" should be the new object instance '
7537n/a '(usually an\n'
7538n/a ' instance of *cls*).\n'
7539n/a '\n'
7540n/a ' Typical implementations create a new instance of the '
7541n/a 'class by\n'
7542n/a ' invoking the superclass\'s "__new__()" method using\n'
7543n/a ' "super(currentclass, cls).__new__(cls[, ...])" with '
7544n/a 'appropriate\n'
7545n/a ' arguments and then modifying the newly-created instance '
7546n/a 'as\n'
7547n/a ' necessary before returning it.\n'
7548n/a '\n'
7549n/a ' If "__new__()" returns an instance of *cls*, then the '
7550n/a 'new\n'
7551n/a ' instance\'s "__init__()" method will be invoked like\n'
7552n/a ' "__init__(self[, ...])", where *self* is the new instance '
7553n/a 'and the\n'
7554n/a ' remaining arguments are the same as were passed to '
7555n/a '"__new__()".\n'
7556n/a '\n'
7557n/a ' If "__new__()" does not return an instance of *cls*, then '
7558n/a 'the new\n'
7559n/a ' instance\'s "__init__()" method will not be invoked.\n'
7560n/a '\n'
7561n/a ' "__new__()" is intended mainly to allow subclasses of '
7562n/a 'immutable\n'
7563n/a ' types (like int, str, or tuple) to customize instance '
7564n/a 'creation. It\n'
7565n/a ' is also commonly overridden in custom metaclasses in '
7566n/a 'order to\n'
7567n/a ' customize class creation.\n'
7568n/a '\n'
7569n/a 'object.__init__(self[, ...])\n'
7570n/a '\n'
7571n/a ' Called after the instance has been created (by '
7572n/a '"__new__()"), but\n'
7573n/a ' before it is returned to the caller. The arguments are '
7574n/a 'those\n'
7575n/a ' passed to the class constructor expression. If a base '
7576n/a 'class has an\n'
7577n/a ' "__init__()" method, the derived class\'s "__init__()" '
7578n/a 'method, if\n'
7579n/a ' any, must explicitly call it to ensure proper '
7580n/a 'initialization of the\n'
7581n/a ' base class part of the instance; for example:\n'
7582n/a ' "BaseClass.__init__(self, [args...])".\n'
7583n/a '\n'
7584n/a ' Because "__new__()" and "__init__()" work together in '
7585n/a 'constructing\n'
7586n/a ' objects ("__new__()" to create it, and "__init__()" to '
7587n/a 'customize\n'
7588n/a ' it), no non-"None" value may be returned by "__init__()"; '
7589n/a 'doing so\n'
7590n/a ' will cause a "TypeError" to be raised at runtime.\n'
7591n/a '\n'
7592n/a 'object.__del__(self)\n'
7593n/a '\n'
7594n/a ' Called when the instance is about to be destroyed. This '
7595n/a 'is also\n'
7596n/a ' called a destructor. If a base class has a "__del__()" '
7597n/a 'method, the\n'
7598n/a ' derived class\'s "__del__()" method, if any, must '
7599n/a 'explicitly call it\n'
7600n/a ' to ensure proper deletion of the base class part of the '
7601n/a 'instance.\n'
7602n/a ' Note that it is possible (though not recommended!) for '
7603n/a 'the\n'
7604n/a ' "__del__()" method to postpone destruction of the '
7605n/a 'instance by\n'
7606n/a ' creating a new reference to it. It may then be called at '
7607n/a 'a later\n'
7608n/a ' time when this new reference is deleted. It is not '
7609n/a 'guaranteed that\n'
7610n/a ' "__del__()" methods are called for objects that still '
7611n/a 'exist when\n'
7612n/a ' the interpreter exits.\n'
7613n/a '\n'
7614n/a ' Note: "del x" doesn\'t directly call "x.__del__()" --- '
7615n/a 'the former\n'
7616n/a ' decrements the reference count for "x" by one, and the '
7617n/a 'latter is\n'
7618n/a ' only called when "x"\'s reference count reaches zero. '
7619n/a 'Some common\n'
7620n/a ' situations that may prevent the reference count of an '
7621n/a 'object from\n'
7622n/a ' going to zero include: circular references between '
7623n/a 'objects (e.g.,\n'
7624n/a ' a doubly-linked list or a tree data structure with '
7625n/a 'parent and\n'
7626n/a ' child pointers); a reference to the object on the stack '
7627n/a 'frame of\n'
7628n/a ' a function that caught an exception (the traceback '
7629n/a 'stored in\n'
7630n/a ' "sys.exc_info()[2]" keeps the stack frame alive); or a '
7631n/a 'reference\n'
7632n/a ' to the object on the stack frame that raised an '
7633n/a 'unhandled\n'
7634n/a ' exception in interactive mode (the traceback stored in\n'
7635n/a ' "sys.last_traceback" keeps the stack frame alive). The '
7636n/a 'first\n'
7637n/a ' situation can only be remedied by explicitly breaking '
7638n/a 'the cycles;\n'
7639n/a ' the second can be resolved by freeing the reference to '
7640n/a 'the\n'
7641n/a ' traceback object when it is no longer useful, and the '
7642n/a 'third can\n'
7643n/a ' be resolved by storing "None" in "sys.last_traceback". '
7644n/a 'Circular\n'
7645n/a ' references which are garbage are detected and cleaned '
7646n/a 'up when the\n'
7647n/a " cyclic garbage collector is enabled (it's on by "
7648n/a 'default). Refer\n'
7649n/a ' to the documentation for the "gc" module for more '
7650n/a 'information\n'
7651n/a ' about this topic.\n'
7652n/a '\n'
7653n/a ' Warning: Due to the precarious circumstances under which\n'
7654n/a ' "__del__()" methods are invoked, exceptions that occur '
7655n/a 'during\n'
7656n/a ' their execution are ignored, and a warning is printed '
7657n/a 'to\n'
7658n/a ' "sys.stderr" instead. Also, when "__del__()" is invoked '
7659n/a 'in\n'
7660n/a ' response to a module being deleted (e.g., when '
7661n/a 'execution of the\n'
7662n/a ' program is done), other globals referenced by the '
7663n/a '"__del__()"\n'
7664n/a ' method may already have been deleted or in the process '
7665n/a 'of being\n'
7666n/a ' torn down (e.g. the import machinery shutting down). '
7667n/a 'For this\n'
7668n/a ' reason, "__del__()" methods should do the absolute '
7669n/a 'minimum needed\n'
7670n/a ' to maintain external invariants. Starting with version '
7671n/a '1.5,\n'
7672n/a ' Python guarantees that globals whose name begins with a '
7673n/a 'single\n'
7674n/a ' underscore are deleted from their module before other '
7675n/a 'globals are\n'
7676n/a ' deleted; if no other references to such globals exist, '
7677n/a 'this may\n'
7678n/a ' help in assuring that imported modules are still '
7679n/a 'available at the\n'
7680n/a ' time when the "__del__()" method is called.\n'
7681n/a '\n'
7682n/a 'object.__repr__(self)\n'
7683n/a '\n'
7684n/a ' Called by the "repr()" built-in function to compute the '
7685n/a '"official"\n'
7686n/a ' string representation of an object. If at all possible, '
7687n/a 'this\n'
7688n/a ' should look like a valid Python expression that could be '
7689n/a 'used to\n'
7690n/a ' recreate an object with the same value (given an '
7691n/a 'appropriate\n'
7692n/a ' environment). If this is not possible, a string of the '
7693n/a 'form\n'
7694n/a ' "<...some useful description...>" should be returned. The '
7695n/a 'return\n'
7696n/a ' value must be a string object. If a class defines '
7697n/a '"__repr__()" but\n'
7698n/a ' not "__str__()", then "__repr__()" is also used when an '
7699n/a '"informal"\n'
7700n/a ' string representation of instances of that class is '
7701n/a 'required.\n'
7702n/a '\n'
7703n/a ' This is typically used for debugging, so it is important '
7704n/a 'that the\n'
7705n/a ' representation is information-rich and unambiguous.\n'
7706n/a '\n'
7707n/a 'object.__str__(self)\n'
7708n/a '\n'
7709n/a ' Called by "str(object)" and the built-in functions '
7710n/a '"format()" and\n'
7711n/a ' "print()" to compute the "informal" or nicely printable '
7712n/a 'string\n'
7713n/a ' representation of an object. The return value must be a '
7714n/a 'string\n'
7715n/a ' object.\n'
7716n/a '\n'
7717n/a ' This method differs from "object.__repr__()" in that '
7718n/a 'there is no\n'
7719n/a ' expectation that "__str__()" return a valid Python '
7720n/a 'expression: a\n'
7721n/a ' more convenient or concise representation can be used.\n'
7722n/a '\n'
7723n/a ' The default implementation defined by the built-in type '
7724n/a '"object"\n'
7725n/a ' calls "object.__repr__()".\n'
7726n/a '\n'
7727n/a 'object.__bytes__(self)\n'
7728n/a '\n'
7729n/a ' Called by "bytes()" to compute a byte-string '
7730n/a 'representation of an\n'
7731n/a ' object. This should return a "bytes" object.\n'
7732n/a '\n'
7733n/a 'object.__format__(self, format_spec)\n'
7734n/a '\n'
7735n/a ' Called by the "format()" built-in function, and by '
7736n/a 'extension,\n'
7737n/a ' evaluation of formatted string literals and the '
7738n/a '"str.format()"\n'
7739n/a ' method, to produce a "formatted" string representation of '
7740n/a 'an\n'
7741n/a ' object. The "format_spec" argument is a string that '
7742n/a 'contains a\n'
7743n/a ' description of the formatting options desired. The '
7744n/a 'interpretation\n'
7745n/a ' of the "format_spec" argument is up to the type '
7746n/a 'implementing\n'
7747n/a ' "__format__()", however most classes will either '
7748n/a 'delegate\n'
7749n/a ' formatting to one of the built-in types, or use a '
7750n/a 'similar\n'
7751n/a ' formatting option syntax.\n'
7752n/a '\n'
7753n/a ' See Format Specification Mini-Language for a description '
7754n/a 'of the\n'
7755n/a ' standard formatting syntax.\n'
7756n/a '\n'
7757n/a ' The return value must be a string object.\n'
7758n/a '\n'
7759n/a ' Changed in version 3.4: The __format__ method of "object" '
7760n/a 'itself\n'
7761n/a ' raises a "TypeError" if passed any non-empty string.\n'
7762n/a '\n'
7763n/a 'object.__lt__(self, other)\n'
7764n/a 'object.__le__(self, other)\n'
7765n/a 'object.__eq__(self, other)\n'
7766n/a 'object.__ne__(self, other)\n'
7767n/a 'object.__gt__(self, other)\n'
7768n/a 'object.__ge__(self, other)\n'
7769n/a '\n'
7770n/a ' These are the so-called "rich comparison" methods. The\n'
7771n/a ' correspondence between operator symbols and method names '
7772n/a 'is as\n'
7773n/a ' follows: "x<y" calls "x.__lt__(y)", "x<=y" calls '
7774n/a '"x.__le__(y)",\n'
7775n/a ' "x==y" calls "x.__eq__(y)", "x!=y" calls "x.__ne__(y)", '
7776n/a '"x>y" calls\n'
7777n/a ' "x.__gt__(y)", and "x>=y" calls "x.__ge__(y)".\n'
7778n/a '\n'
7779n/a ' A rich comparison method may return the singleton '
7780n/a '"NotImplemented"\n'
7781n/a ' if it does not implement the operation for a given pair '
7782n/a 'of\n'
7783n/a ' arguments. By convention, "False" and "True" are returned '
7784n/a 'for a\n'
7785n/a ' successful comparison. However, these methods can return '
7786n/a 'any value,\n'
7787n/a ' so if the comparison operator is used in a Boolean '
7788n/a 'context (e.g.,\n'
7789n/a ' in the condition of an "if" statement), Python will call '
7790n/a '"bool()"\n'
7791n/a ' on the value to determine if the result is true or '
7792n/a 'false.\n'
7793n/a '\n'
7794n/a ' By default, "__ne__()" delegates to "__eq__()" and '
7795n/a 'inverts the\n'
7796n/a ' result unless it is "NotImplemented". There are no other '
7797n/a 'implied\n'
7798n/a ' relationships among the comparison operators, for '
7799n/a 'example, the\n'
7800n/a ' truth of "(x<y or x==y)" does not imply "x<=y". To '
7801n/a 'automatically\n'
7802n/a ' generate ordering operations from a single root '
7803n/a 'operation, see\n'
7804n/a ' "functools.total_ordering()".\n'
7805n/a '\n'
7806n/a ' See the paragraph on "__hash__()" for some important '
7807n/a 'notes on\n'
7808n/a ' creating *hashable* objects which support custom '
7809n/a 'comparison\n'
7810n/a ' operations and are usable as dictionary keys.\n'
7811n/a '\n'
7812n/a ' There are no swapped-argument versions of these methods '
7813n/a '(to be used\n'
7814n/a ' when the left argument does not support the operation but '
7815n/a 'the right\n'
7816n/a ' argument does); rather, "__lt__()" and "__gt__()" are '
7817n/a "each other's\n"
7818n/a ' reflection, "__le__()" and "__ge__()" are each other\'s '
7819n/a 'reflection,\n'
7820n/a ' and "__eq__()" and "__ne__()" are their own reflection. '
7821n/a 'If the\n'
7822n/a " operands are of different types, and right operand's type "
7823n/a 'is a\n'
7824n/a " direct or indirect subclass of the left operand's type, "
7825n/a 'the\n'
7826n/a ' reflected method of the right operand has priority, '
7827n/a 'otherwise the\n'
7828n/a " left operand's method has priority. Virtual subclassing "
7829n/a 'is not\n'
7830n/a ' considered.\n'
7831n/a '\n'
7832n/a 'object.__hash__(self)\n'
7833n/a '\n'
7834n/a ' Called by built-in function "hash()" and for operations '
7835n/a 'on members\n'
7836n/a ' of hashed collections including "set", "frozenset", and '
7837n/a '"dict".\n'
7838n/a ' "__hash__()" should return an integer. The only required '
7839n/a 'property\n'
7840n/a ' is that objects which compare equal have the same hash '
7841n/a 'value; it is\n'
7842n/a ' advised to somehow mix together (e.g. using exclusive or) '
7843n/a 'the hash\n'
7844n/a ' values for the components of the object that also play a '
7845n/a 'part in\n'
7846n/a ' comparison of objects.\n'
7847n/a '\n'
7848n/a ' Note: "hash()" truncates the value returned from an '
7849n/a "object's\n"
7850n/a ' custom "__hash__()" method to the size of a '
7851n/a '"Py_ssize_t". This\n'
7852n/a ' is typically 8 bytes on 64-bit builds and 4 bytes on '
7853n/a '32-bit\n'
7854n/a ' builds. If an object\'s "__hash__()" must '
7855n/a 'interoperate on builds\n'
7856n/a ' of different bit sizes, be sure to check the width on '
7857n/a 'all\n'
7858n/a ' supported builds. An easy way to do this is with '
7859n/a '"python -c\n'
7860n/a ' "import sys; print(sys.hash_info.width)"".\n'
7861n/a '\n'
7862n/a ' If a class does not define an "__eq__()" method it should '
7863n/a 'not\n'
7864n/a ' define a "__hash__()" operation either; if it defines '
7865n/a '"__eq__()"\n'
7866n/a ' but not "__hash__()", its instances will not be usable as '
7867n/a 'items in\n'
7868n/a ' hashable collections. If a class defines mutable objects '
7869n/a 'and\n'
7870n/a ' implements an "__eq__()" method, it should not implement\n'
7871n/a ' "__hash__()", since the implementation of hashable '
7872n/a 'collections\n'
7873n/a " requires that a key's hash value is immutable (if the "
7874n/a "object's hash\n"
7875n/a ' value changes, it will be in the wrong hash bucket).\n'
7876n/a '\n'
7877n/a ' User-defined classes have "__eq__()" and "__hash__()" '
7878n/a 'methods by\n'
7879n/a ' default; with them, all objects compare unequal (except '
7880n/a 'with\n'
7881n/a ' themselves) and "x.__hash__()" returns an appropriate '
7882n/a 'value such\n'
7883n/a ' that "x == y" implies both that "x is y" and "hash(x) == '
7884n/a 'hash(y)".\n'
7885n/a '\n'
7886n/a ' A class that overrides "__eq__()" and does not define '
7887n/a '"__hash__()"\n'
7888n/a ' will have its "__hash__()" implicitly set to "None". '
7889n/a 'When the\n'
7890n/a ' "__hash__()" method of a class is "None", instances of '
7891n/a 'the class\n'
7892n/a ' will raise an appropriate "TypeError" when a program '
7893n/a 'attempts to\n'
7894n/a ' retrieve their hash value, and will also be correctly '
7895n/a 'identified as\n'
7896n/a ' unhashable when checking "isinstance(obj, '
7897n/a 'collections.Hashable)".\n'
7898n/a '\n'
7899n/a ' If a class that overrides "__eq__()" needs to retain the\n'
7900n/a ' implementation of "__hash__()" from a parent class, the '
7901n/a 'interpreter\n'
7902n/a ' must be told this explicitly by setting "__hash__ =\n'
7903n/a ' <ParentClass>.__hash__".\n'
7904n/a '\n'
7905n/a ' If a class that does not override "__eq__()" wishes to '
7906n/a 'suppress\n'
7907n/a ' hash support, it should include "__hash__ = None" in the '
7908n/a 'class\n'
7909n/a ' definition. A class which defines its own "__hash__()" '
7910n/a 'that\n'
7911n/a ' explicitly raises a "TypeError" would be incorrectly '
7912n/a 'identified as\n'
7913n/a ' hashable by an "isinstance(obj, collections.Hashable)" '
7914n/a 'call.\n'
7915n/a '\n'
7916n/a ' Note: By default, the "__hash__()" values of str, bytes '
7917n/a 'and\n'
7918n/a ' datetime objects are "salted" with an unpredictable '
7919n/a 'random value.\n'
7920n/a ' Although they remain constant within an individual '
7921n/a 'Python\n'
7922n/a ' process, they are not predictable between repeated '
7923n/a 'invocations of\n'
7924n/a ' Python.This is intended to provide protection against a '
7925n/a 'denial-\n'
7926n/a ' of-service caused by carefully-chosen inputs that '
7927n/a 'exploit the\n'
7928n/a ' worst case performance of a dict insertion, O(n^2) '
7929n/a 'complexity.\n'
7930n/a ' See http://www.ocert.org/advisories/ocert-2011-003.html '
7931n/a 'for\n'
7932n/a ' details.Changing hash values affects the iteration '
7933n/a 'order of\n'
7934n/a ' dicts, sets and other mappings. Python has never made '
7935n/a 'guarantees\n'
7936n/a ' about this ordering (and it typically varies between '
7937n/a '32-bit and\n'
7938n/a ' 64-bit builds).See also "PYTHONHASHSEED".\n'
7939n/a '\n'
7940n/a ' Changed in version 3.3: Hash randomization is enabled by '
7941n/a 'default.\n'
7942n/a '\n'
7943n/a 'object.__bool__(self)\n'
7944n/a '\n'
7945n/a ' Called to implement truth value testing and the built-in '
7946n/a 'operation\n'
7947n/a ' "bool()"; should return "False" or "True". When this '
7948n/a 'method is not\n'
7949n/a ' defined, "__len__()" is called, if it is defined, and the '
7950n/a 'object is\n'
7951n/a ' considered true if its result is nonzero. If a class '
7952n/a 'defines\n'
7953n/a ' neither "__len__()" nor "__bool__()", all its instances '
7954n/a 'are\n'
7955n/a ' considered true.\n'
7956n/a '\n'
7957n/a '\n'
7958n/a 'Customizing attribute access\n'
7959n/a '============================\n'
7960n/a '\n'
7961n/a 'The following methods can be defined to customize the '
7962n/a 'meaning of\n'
7963n/a 'attribute access (use of, assignment to, or deletion of '
7964n/a '"x.name") for\n'
7965n/a 'class instances.\n'
7966n/a '\n'
7967n/a 'object.__getattr__(self, name)\n'
7968n/a '\n'
7969n/a ' Called when an attribute lookup has not found the '
7970n/a 'attribute in the\n'
7971n/a ' usual places (i.e. it is not an instance attribute nor is '
7972n/a 'it found\n'
7973n/a ' in the class tree for "self"). "name" is the attribute '
7974n/a 'name. This\n'
7975n/a ' method should return the (computed) attribute value or '
7976n/a 'raise an\n'
7977n/a ' "AttributeError" exception.\n'
7978n/a '\n'
7979n/a ' Note that if the attribute is found through the normal '
7980n/a 'mechanism,\n'
7981n/a ' "__getattr__()" is not called. (This is an intentional '
7982n/a 'asymmetry\n'
7983n/a ' between "__getattr__()" and "__setattr__()".) This is '
7984n/a 'done both for\n'
7985n/a ' efficiency reasons and because otherwise "__getattr__()" '
7986n/a 'would have\n'
7987n/a ' no way to access other attributes of the instance. Note '
7988n/a 'that at\n'
7989n/a ' least for instance variables, you can fake total control '
7990n/a 'by not\n'
7991n/a ' inserting any values in the instance attribute dictionary '
7992n/a '(but\n'
7993n/a ' instead inserting them in another object). See the\n'
7994n/a ' "__getattribute__()" method below for a way to actually '
7995n/a 'get total\n'
7996n/a ' control over attribute access.\n'
7997n/a '\n'
7998n/a 'object.__getattribute__(self, name)\n'
7999n/a '\n'
8000n/a ' Called unconditionally to implement attribute accesses '
8001n/a 'for\n'
8002n/a ' instances of the class. If the class also defines '
8003n/a '"__getattr__()",\n'
8004n/a ' the latter will not be called unless "__getattribute__()" '
8005n/a 'either\n'
8006n/a ' calls it explicitly or raises an "AttributeError". This '
8007n/a 'method\n'
8008n/a ' should return the (computed) attribute value or raise an\n'
8009n/a ' "AttributeError" exception. In order to avoid infinite '
8010n/a 'recursion in\n'
8011n/a ' this method, its implementation should always call the '
8012n/a 'base class\n'
8013n/a ' method with the same name to access any attributes it '
8014n/a 'needs, for\n'
8015n/a ' example, "object.__getattribute__(self, name)".\n'
8016n/a '\n'
8017n/a ' Note: This method may still be bypassed when looking up '
8018n/a 'special\n'
8019n/a ' methods as the result of implicit invocation via '
8020n/a 'language syntax\n'
8021n/a ' or built-in functions. See Special method lookup.\n'
8022n/a '\n'
8023n/a 'object.__setattr__(self, name, value)\n'
8024n/a '\n'
8025n/a ' Called when an attribute assignment is attempted. This '
8026n/a 'is called\n'
8027n/a ' instead of the normal mechanism (i.e. store the value in '
8028n/a 'the\n'
8029n/a ' instance dictionary). *name* is the attribute name, '
8030n/a '*value* is the\n'
8031n/a ' value to be assigned to it.\n'
8032n/a '\n'
8033n/a ' If "__setattr__()" wants to assign to an instance '
8034n/a 'attribute, it\n'
8035n/a ' should call the base class method with the same name, for '
8036n/a 'example,\n'
8037n/a ' "object.__setattr__(self, name, value)".\n'
8038n/a '\n'
8039n/a 'object.__delattr__(self, name)\n'
8040n/a '\n'
8041n/a ' Like "__setattr__()" but for attribute deletion instead '
8042n/a 'of\n'
8043n/a ' assignment. This should only be implemented if "del '
8044n/a 'obj.name" is\n'
8045n/a ' meaningful for the object.\n'
8046n/a '\n'
8047n/a 'object.__dir__(self)\n'
8048n/a '\n'
8049n/a ' Called when "dir()" is called on the object. A sequence '
8050n/a 'must be\n'
8051n/a ' returned. "dir()" converts the returned sequence to a '
8052n/a 'list and\n'
8053n/a ' sorts it.\n'
8054n/a '\n'
8055n/a '\n'
8056n/a 'Implementing Descriptors\n'
8057n/a '------------------------\n'
8058n/a '\n'
8059n/a 'The following methods only apply when an instance of the '
8060n/a 'class\n'
8061n/a 'containing the method (a so-called *descriptor* class) '
8062n/a 'appears in an\n'
8063n/a "*owner* class (the descriptor must be in either the owner's "
8064n/a 'class\n'
8065n/a 'dictionary or in the class dictionary for one of its '
8066n/a 'parents). In the\n'
8067n/a 'examples below, "the attribute" refers to the attribute '
8068n/a 'whose name is\n'
8069n/a 'the key of the property in the owner class\' "__dict__".\n'
8070n/a '\n'
8071n/a 'object.__get__(self, instance, owner)\n'
8072n/a '\n'
8073n/a ' Called to get the attribute of the owner class (class '
8074n/a 'attribute\n'
8075n/a ' access) or of an instance of that class (instance '
8076n/a 'attribute\n'
8077n/a ' access). *owner* is always the owner class, while '
8078n/a '*instance* is the\n'
8079n/a ' instance that the attribute was accessed through, or '
8080n/a '"None" when\n'
8081n/a ' the attribute is accessed through the *owner*. This '
8082n/a 'method should\n'
8083n/a ' return the (computed) attribute value or raise an '
8084n/a '"AttributeError"\n'
8085n/a ' exception.\n'
8086n/a '\n'
8087n/a 'object.__set__(self, instance, value)\n'
8088n/a '\n'
8089n/a ' Called to set the attribute on an instance *instance* of '
8090n/a 'the owner\n'
8091n/a ' class to a new value, *value*.\n'
8092n/a '\n'
8093n/a 'object.__delete__(self, instance)\n'
8094n/a '\n'
8095n/a ' Called to delete the attribute on an instance *instance* '
8096n/a 'of the\n'
8097n/a ' owner class.\n'
8098n/a '\n'
8099n/a 'object.__set_name__(self, owner, name)\n'
8100n/a '\n'
8101n/a ' Called at the time the owning class *owner* is created. '
8102n/a 'The\n'
8103n/a ' descriptor has been assigned to *name*.\n'
8104n/a '\n'
8105n/a ' New in version 3.6.\n'
8106n/a '\n'
8107n/a 'The attribute "__objclass__" is interpreted by the "inspect" '
8108n/a 'module as\n'
8109n/a 'specifying the class where this object was defined (setting '
8110n/a 'this\n'
8111n/a 'appropriately can assist in runtime introspection of dynamic '
8112n/a 'class\n'
8113n/a 'attributes). For callables, it may indicate that an instance '
8114n/a 'of the\n'
8115n/a 'given type (or a subclass) is expected or required as the '
8116n/a 'first\n'
8117n/a 'positional argument (for example, CPython sets this '
8118n/a 'attribute for\n'
8119n/a 'unbound methods that are implemented in C).\n'
8120n/a '\n'
8121n/a '\n'
8122n/a 'Invoking Descriptors\n'
8123n/a '--------------------\n'
8124n/a '\n'
8125n/a 'In general, a descriptor is an object attribute with '
8126n/a '"binding\n'
8127n/a 'behavior", one whose attribute access has been overridden by '
8128n/a 'methods\n'
8129n/a 'in the descriptor protocol: "__get__()", "__set__()", and\n'
8130n/a '"__delete__()". If any of those methods are defined for an '
8131n/a 'object, it\n'
8132n/a 'is said to be a descriptor.\n'
8133n/a '\n'
8134n/a 'The default behavior for attribute access is to get, set, or '
8135n/a 'delete\n'
8136n/a "the attribute from an object's dictionary. For instance, "
8137n/a '"a.x" has a\n'
8138n/a 'lookup chain starting with "a.__dict__[\'x\']", then\n'
8139n/a '"type(a).__dict__[\'x\']", and continuing through the base '
8140n/a 'classes of\n'
8141n/a '"type(a)" excluding metaclasses.\n'
8142n/a '\n'
8143n/a 'However, if the looked-up value is an object defining one of '
8144n/a 'the\n'
8145n/a 'descriptor methods, then Python may override the default '
8146n/a 'behavior and\n'
8147n/a 'invoke the descriptor method instead. Where this occurs in '
8148n/a 'the\n'
8149n/a 'precedence chain depends on which descriptor methods were '
8150n/a 'defined and\n'
8151n/a 'how they were called.\n'
8152n/a '\n'
8153n/a 'The starting point for descriptor invocation is a binding, '
8154n/a '"a.x". How\n'
8155n/a 'the arguments are assembled depends on "a":\n'
8156n/a '\n'
8157n/a 'Direct Call\n'
8158n/a ' The simplest and least common call is when user code '
8159n/a 'directly\n'
8160n/a ' invokes a descriptor method: "x.__get__(a)".\n'
8161n/a '\n'
8162n/a 'Instance Binding\n'
8163n/a ' If binding to an object instance, "a.x" is transformed '
8164n/a 'into the\n'
8165n/a ' call: "type(a).__dict__[\'x\'].__get__(a, type(a))".\n'
8166n/a '\n'
8167n/a 'Class Binding\n'
8168n/a ' If binding to a class, "A.x" is transformed into the '
8169n/a 'call:\n'
8170n/a ' "A.__dict__[\'x\'].__get__(None, A)".\n'
8171n/a '\n'
8172n/a 'Super Binding\n'
8173n/a ' If "a" is an instance of "super", then the binding '
8174n/a '"super(B,\n'
8175n/a ' obj).m()" searches "obj.__class__.__mro__" for the base '
8176n/a 'class "A"\n'
8177n/a ' immediately preceding "B" and then invokes the descriptor '
8178n/a 'with the\n'
8179n/a ' call: "A.__dict__[\'m\'].__get__(obj, obj.__class__)".\n'
8180n/a '\n'
8181n/a 'For instance bindings, the precedence of descriptor '
8182n/a 'invocation depends\n'
8183n/a 'on the which descriptor methods are defined. A descriptor '
8184n/a 'can define\n'
8185n/a 'any combination of "__get__()", "__set__()" and '
8186n/a '"__delete__()". If it\n'
8187n/a 'does not define "__get__()", then accessing the attribute '
8188n/a 'will return\n'
8189n/a 'the descriptor object itself unless there is a value in the '
8190n/a "object's\n"
8191n/a 'instance dictionary. If the descriptor defines "__set__()" '
8192n/a 'and/or\n'
8193n/a '"__delete__()", it is a data descriptor; if it defines '
8194n/a 'neither, it is\n'
8195n/a 'a non-data descriptor. Normally, data descriptors define '
8196n/a 'both\n'
8197n/a '"__get__()" and "__set__()", while non-data descriptors have '
8198n/a 'just the\n'
8199n/a '"__get__()" method. Data descriptors with "__set__()" and '
8200n/a '"__get__()"\n'
8201n/a 'defined always override a redefinition in an instance '
8202n/a 'dictionary. In\n'
8203n/a 'contrast, non-data descriptors can be overridden by '
8204n/a 'instances.\n'
8205n/a '\n'
8206n/a 'Python methods (including "staticmethod()" and '
8207n/a '"classmethod()") are\n'
8208n/a 'implemented as non-data descriptors. Accordingly, instances '
8209n/a 'can\n'
8210n/a 'redefine and override methods. This allows individual '
8211n/a 'instances to\n'
8212n/a 'acquire behaviors that differ from other instances of the '
8213n/a 'same class.\n'
8214n/a '\n'
8215n/a 'The "property()" function is implemented as a data '
8216n/a 'descriptor.\n'
8217n/a 'Accordingly, instances cannot override the behavior of a '
8218n/a 'property.\n'
8219n/a '\n'
8220n/a '\n'
8221n/a '__slots__\n'
8222n/a '---------\n'
8223n/a '\n'
8224n/a 'By default, instances of classes have a dictionary for '
8225n/a 'attribute\n'
8226n/a 'storage. This wastes space for objects having very few '
8227n/a 'instance\n'
8228n/a 'variables. The space consumption can become acute when '
8229n/a 'creating large\n'
8230n/a 'numbers of instances.\n'
8231n/a '\n'
8232n/a 'The default can be overridden by defining *__slots__* in a '
8233n/a 'class\n'
8234n/a 'definition. The *__slots__* declaration takes a sequence of '
8235n/a 'instance\n'
8236n/a 'variables and reserves just enough space in each instance to '
8237n/a 'hold a\n'
8238n/a 'value for each variable. Space is saved because *__dict__* '
8239n/a 'is not\n'
8240n/a 'created for each instance.\n'
8241n/a '\n'
8242n/a 'object.__slots__\n'
8243n/a '\n'
8244n/a ' This class variable can be assigned a string, iterable, '
8245n/a 'or sequence\n'
8246n/a ' of strings with variable names used by instances. '
8247n/a '*__slots__*\n'
8248n/a ' reserves space for the declared variables and prevents '
8249n/a 'the\n'
8250n/a ' automatic creation of *__dict__* and *__weakref__* for '
8251n/a 'each\n'
8252n/a ' instance.\n'
8253n/a '\n'
8254n/a '\n'
8255n/a 'Notes on using *__slots__*\n'
8256n/a '~~~~~~~~~~~~~~~~~~~~~~~~~~\n'
8257n/a '\n'
8258n/a '* When inheriting from a class without *__slots__*, the '
8259n/a '*__dict__*\n'
8260n/a ' attribute of that class will always be accessible, so a '
8261n/a '*__slots__*\n'
8262n/a ' definition in the subclass is meaningless.\n'
8263n/a '\n'
8264n/a '* Without a *__dict__* variable, instances cannot be '
8265n/a 'assigned new\n'
8266n/a ' variables not listed in the *__slots__* definition. '
8267n/a 'Attempts to\n'
8268n/a ' assign to an unlisted variable name raises '
8269n/a '"AttributeError". If\n'
8270n/a ' dynamic assignment of new variables is desired, then add\n'
8271n/a ' "\'__dict__\'" to the sequence of strings in the '
8272n/a '*__slots__*\n'
8273n/a ' declaration.\n'
8274n/a '\n'
8275n/a '* Without a *__weakref__* variable for each instance, '
8276n/a 'classes\n'
8277n/a ' defining *__slots__* do not support weak references to '
8278n/a 'its\n'
8279n/a ' instances. If weak reference support is needed, then add\n'
8280n/a ' "\'__weakref__\'" to the sequence of strings in the '
8281n/a '*__slots__*\n'
8282n/a ' declaration.\n'
8283n/a '\n'
8284n/a '* *__slots__* are implemented at the class level by '
8285n/a 'creating\n'
8286n/a ' descriptors (Implementing Descriptors) for each variable '
8287n/a 'name. As a\n'
8288n/a ' result, class attributes cannot be used to set default '
8289n/a 'values for\n'
8290n/a ' instance variables defined by *__slots__*; otherwise, the '
8291n/a 'class\n'
8292n/a ' attribute would overwrite the descriptor assignment.\n'
8293n/a '\n'
8294n/a '* The action of a *__slots__* declaration is limited to the '
8295n/a 'class\n'
8296n/a ' where it is defined. As a result, subclasses will have a '
8297n/a '*__dict__*\n'
8298n/a ' unless they also define *__slots__* (which must only '
8299n/a 'contain names\n'
8300n/a ' of any *additional* slots).\n'
8301n/a '\n'
8302n/a '* If a class defines a slot also defined in a base class, '
8303n/a 'the\n'
8304n/a ' instance variable defined by the base class slot is '
8305n/a 'inaccessible\n'
8306n/a ' (except by retrieving its descriptor directly from the '
8307n/a 'base class).\n'
8308n/a ' This renders the meaning of the program undefined. In the '
8309n/a 'future, a\n'
8310n/a ' check may be added to prevent this.\n'
8311n/a '\n'
8312n/a '* Nonempty *__slots__* does not work for classes derived '
8313n/a 'from\n'
8314n/a ' "variable-length" built-in types such as "int", "bytes" '
8315n/a 'and "tuple".\n'
8316n/a '\n'
8317n/a '* Any non-string iterable may be assigned to *__slots__*. '
8318n/a 'Mappings\n'
8319n/a ' may also be used; however, in the future, special meaning '
8320n/a 'may be\n'
8321n/a ' assigned to the values corresponding to each key.\n'
8322n/a '\n'
8323n/a '* *__class__* assignment works only if both classes have the '
8324n/a 'same\n'
8325n/a ' *__slots__*.\n'
8326n/a '\n'
8327n/a '\n'
8328n/a 'Customizing class creation\n'
8329n/a '==========================\n'
8330n/a '\n'
8331n/a 'Whenever a class inherits from another class, '
8332n/a '*__init_subclass__* is\n'
8333n/a 'called on that class. This way, it is possible to write '
8334n/a 'classes which\n'
8335n/a 'change the behavior of subclasses. This is closely related '
8336n/a 'to class\n'
8337n/a 'decorators, but where class decorators only affect the '
8338n/a 'specific class\n'
8339n/a 'they\'re applied to, "__init_subclass__" solely applies to '
8340n/a 'future\n'
8341n/a 'subclasses of the class defining the method.\n'
8342n/a '\n'
8343n/a 'classmethod object.__init_subclass__(cls)\n'
8344n/a '\n'
8345n/a ' This method is called whenever the containing class is '
8346n/a 'subclassed.\n'
8347n/a ' *cls* is then the new subclass. If defined as a normal '
8348n/a 'instance\n'
8349n/a ' method, this method is implicitly converted to a class '
8350n/a 'method.\n'
8351n/a '\n'
8352n/a ' Keyword arguments which are given to a new class are '
8353n/a 'passed to the\n'
8354n/a ' parent\'s class "__init_subclass__". For compatibility '
8355n/a 'with other\n'
8356n/a ' classes using "__init_subclass__", one should take out '
8357n/a 'the needed\n'
8358n/a ' keyword arguments and pass the others over to the base '
8359n/a 'class, as\n'
8360n/a ' in:\n'
8361n/a '\n'
8362n/a ' class Philosopher:\n'
8363n/a ' def __init_subclass__(cls, default_name, '
8364n/a '**kwargs):\n'
8365n/a ' super().__init_subclass__(**kwargs)\n'
8366n/a ' cls.default_name = default_name\n'
8367n/a '\n'
8368n/a ' class AustralianPhilosopher(Philosopher, '
8369n/a 'default_name="Bruce"):\n'
8370n/a ' pass\n'
8371n/a '\n'
8372n/a ' The default implementation "object.__init_subclass__" '
8373n/a 'does nothing,\n'
8374n/a ' but raises an error if it is called with any arguments.\n'
8375n/a '\n'
8376n/a ' Note: The metaclass hint "metaclass" is consumed by the '
8377n/a 'rest of\n'
8378n/a ' the type machinery, and is never passed to '
8379n/a '"__init_subclass__"\n'
8380n/a ' implementations. The actual metaclass (rather than the '
8381n/a 'explicit\n'
8382n/a ' hint) can be accessed as "type(cls)".\n'
8383n/a '\n'
8384n/a ' New in version 3.6.\n'
8385n/a '\n'
8386n/a '\n'
8387n/a 'Metaclasses\n'
8388n/a '-----------\n'
8389n/a '\n'
8390n/a 'By default, classes are constructed using "type()". The '
8391n/a 'class body is\n'
8392n/a 'executed in a new namespace and the class name is bound '
8393n/a 'locally to the\n'
8394n/a 'result of "type(name, bases, namespace)".\n'
8395n/a '\n'
8396n/a 'The class creation process can be customized by passing the\n'
8397n/a '"metaclass" keyword argument in the class definition line, '
8398n/a 'or by\n'
8399n/a 'inheriting from an existing class that included such an '
8400n/a 'argument. In\n'
8401n/a 'the following example, both "MyClass" and "MySubclass" are '
8402n/a 'instances\n'
8403n/a 'of "Meta":\n'
8404n/a '\n'
8405n/a ' class Meta(type):\n'
8406n/a ' pass\n'
8407n/a '\n'
8408n/a ' class MyClass(metaclass=Meta):\n'
8409n/a ' pass\n'
8410n/a '\n'
8411n/a ' class MySubclass(MyClass):\n'
8412n/a ' pass\n'
8413n/a '\n'
8414n/a 'Any other keyword arguments that are specified in the class '
8415n/a 'definition\n'
8416n/a 'are passed through to all metaclass operations described '
8417n/a 'below.\n'
8418n/a '\n'
8419n/a 'When a class definition is executed, the following steps '
8420n/a 'occur:\n'
8421n/a '\n'
8422n/a '* the appropriate metaclass is determined\n'
8423n/a '\n'
8424n/a '* the class namespace is prepared\n'
8425n/a '\n'
8426n/a '* the class body is executed\n'
8427n/a '\n'
8428n/a '* the class object is created\n'
8429n/a '\n'
8430n/a '\n'
8431n/a 'Determining the appropriate metaclass\n'
8432n/a '-------------------------------------\n'
8433n/a '\n'
8434n/a 'The appropriate metaclass for a class definition is '
8435n/a 'determined as\n'
8436n/a 'follows:\n'
8437n/a '\n'
8438n/a '* if no bases and no explicit metaclass are given, then '
8439n/a '"type()" is\n'
8440n/a ' used\n'
8441n/a '\n'
8442n/a '* if an explicit metaclass is given and it is *not* an '
8443n/a 'instance of\n'
8444n/a ' "type()", then it is used directly as the metaclass\n'
8445n/a '\n'
8446n/a '* if an instance of "type()" is given as the explicit '
8447n/a 'metaclass, or\n'
8448n/a ' bases are defined, then the most derived metaclass is '
8449n/a 'used\n'
8450n/a '\n'
8451n/a 'The most derived metaclass is selected from the explicitly '
8452n/a 'specified\n'
8453n/a 'metaclass (if any) and the metaclasses (i.e. "type(cls)") of '
8454n/a 'all\n'
8455n/a 'specified base classes. The most derived metaclass is one '
8456n/a 'which is a\n'
8457n/a 'subtype of *all* of these candidate metaclasses. If none of '
8458n/a 'the\n'
8459n/a 'candidate metaclasses meets that criterion, then the class '
8460n/a 'definition\n'
8461n/a 'will fail with "TypeError".\n'
8462n/a '\n'
8463n/a '\n'
8464n/a 'Preparing the class namespace\n'
8465n/a '-----------------------------\n'
8466n/a '\n'
8467n/a 'Once the appropriate metaclass has been identified, then the '
8468n/a 'class\n'
8469n/a 'namespace is prepared. If the metaclass has a "__prepare__" '
8470n/a 'attribute,\n'
8471n/a 'it is called as "namespace = metaclass.__prepare__(name, '
8472n/a 'bases,\n'
8473n/a '**kwds)" (where the additional keyword arguments, if any, '
8474n/a 'come from\n'
8475n/a 'the class definition).\n'
8476n/a '\n'
8477n/a 'If the metaclass has no "__prepare__" attribute, then the '
8478n/a 'class\n'
8479n/a 'namespace is initialised as an empty ordered mapping.\n'
8480n/a '\n'
8481n/a 'See also:\n'
8482n/a '\n'
8483n/a ' **PEP 3115** - Metaclasses in Python 3000\n'
8484n/a ' Introduced the "__prepare__" namespace hook\n'
8485n/a '\n'
8486n/a '\n'
8487n/a 'Executing the class body\n'
8488n/a '------------------------\n'
8489n/a '\n'
8490n/a 'The class body is executed (approximately) as "exec(body, '
8491n/a 'globals(),\n'
8492n/a 'namespace)". The key difference from a normal call to '
8493n/a '"exec()" is that\n'
8494n/a 'lexical scoping allows the class body (including any '
8495n/a 'methods) to\n'
8496n/a 'reference names from the current and outer scopes when the '
8497n/a 'class\n'
8498n/a 'definition occurs inside a function.\n'
8499n/a '\n'
8500n/a 'However, even when the class definition occurs inside the '
8501n/a 'function,\n'
8502n/a 'methods defined inside the class still cannot see names '
8503n/a 'defined at the\n'
8504n/a 'class scope. Class variables must be accessed through the '
8505n/a 'first\n'
8506n/a 'parameter of instance or class methods, and cannot be '
8507n/a 'accessed at all\n'
8508n/a 'from static methods.\n'
8509n/a '\n'
8510n/a '\n'
8511n/a 'Creating the class object\n'
8512n/a '-------------------------\n'
8513n/a '\n'
8514n/a 'Once the class namespace has been populated by executing the '
8515n/a 'class\n'
8516n/a 'body, the class object is created by calling '
8517n/a '"metaclass(name, bases,\n'
8518n/a 'namespace, **kwds)" (the additional keywords passed here are '
8519n/a 'the same\n'
8520n/a 'as those passed to "__prepare__").\n'
8521n/a '\n'
8522n/a 'This class object is the one that will be referenced by the '
8523n/a 'zero-\n'
8524n/a 'argument form of "super()". "__class__" is an implicit '
8525n/a 'closure\n'
8526n/a 'reference created by the compiler if any methods in a class '
8527n/a 'body refer\n'
8528n/a 'to either "__class__" or "super". This allows the zero '
8529n/a 'argument form\n'
8530n/a 'of "super()" to correctly identify the class being defined '
8531n/a 'based on\n'
8532n/a 'lexical scoping, while the class or instance that was used '
8533n/a 'to make the\n'
8534n/a 'current call is identified based on the first argument '
8535n/a 'passed to the\n'
8536n/a 'method.\n'
8537n/a '\n'
8538n/a 'After the class object is created, it is passed to the '
8539n/a 'class\n'
8540n/a 'decorators included in the class definition (if any) and the '
8541n/a 'resulting\n'
8542n/a 'object is bound in the local namespace as the defined '
8543n/a 'class.\n'
8544n/a '\n'
8545n/a 'When a new class is created by "type.__new__", the object '
8546n/a 'provided as\n'
8547n/a 'the namespace parameter is copied to a new ordered mapping '
8548n/a 'and the\n'
8549n/a 'original object is discarded. The new copy is wrapped in a '
8550n/a 'read-only\n'
8551n/a 'proxy, which becomes the "__dict__" attribute of the class '
8552n/a 'object.\n'
8553n/a '\n'
8554n/a 'See also:\n'
8555n/a '\n'
8556n/a ' **PEP 3135** - New super\n'
8557n/a ' Describes the implicit "__class__" closure reference\n'
8558n/a '\n'
8559n/a '\n'
8560n/a 'Metaclass example\n'
8561n/a '-----------------\n'
8562n/a '\n'
8563n/a 'The potential uses for metaclasses are boundless. Some ideas '
8564n/a 'that have\n'
8565n/a 'been explored include logging, interface checking, '
8566n/a 'automatic\n'
8567n/a 'delegation, automatic property creation, proxies, '
8568n/a 'frameworks, and\n'
8569n/a 'automatic resource locking/synchronization.\n'
8570n/a '\n'
8571n/a 'Here is an example of a metaclass that uses an\n'
8572n/a '"collections.OrderedDict" to remember the order that class '
8573n/a 'variables\n'
8574n/a 'are defined:\n'
8575n/a '\n'
8576n/a ' class OrderedClass(type):\n'
8577n/a '\n'
8578n/a ' @classmethod\n'
8579n/a ' def __prepare__(metacls, name, bases, **kwds):\n'
8580n/a ' return collections.OrderedDict()\n'
8581n/a '\n'
8582n/a ' def __new__(cls, name, bases, namespace, **kwds):\n'
8583n/a ' result = type.__new__(cls, name, bases, '
8584n/a 'dict(namespace))\n'
8585n/a ' result.members = tuple(namespace)\n'
8586n/a ' return result\n'
8587n/a '\n'
8588n/a ' class A(metaclass=OrderedClass):\n'
8589n/a ' def one(self): pass\n'
8590n/a ' def two(self): pass\n'
8591n/a ' def three(self): pass\n'
8592n/a ' def four(self): pass\n'
8593n/a '\n'
8594n/a ' >>> A.members\n'
8595n/a " ('__module__', 'one', 'two', 'three', 'four')\n"
8596n/a '\n'
8597n/a 'When the class definition for *A* gets executed, the process '
8598n/a 'begins\n'
8599n/a 'with calling the metaclass\'s "__prepare__()" method which '
8600n/a 'returns an\n'
8601n/a 'empty "collections.OrderedDict". That mapping records the '
8602n/a 'methods and\n'
8603n/a 'attributes of *A* as they are defined within the body of the '
8604n/a 'class\n'
8605n/a 'statement. Once those definitions are executed, the ordered '
8606n/a 'dictionary\n'
8607n/a 'is fully populated and the metaclass\'s "__new__()" method '
8608n/a 'gets\n'
8609n/a 'invoked. That method builds the new type and it saves the '
8610n/a 'ordered\n'
8611n/a 'dictionary keys in an attribute called "members".\n'
8612n/a '\n'
8613n/a '\n'
8614n/a 'Customizing instance and subclass checks\n'
8615n/a '========================================\n'
8616n/a '\n'
8617n/a 'The following methods are used to override the default '
8618n/a 'behavior of the\n'
8619n/a '"isinstance()" and "issubclass()" built-in functions.\n'
8620n/a '\n'
8621n/a 'In particular, the metaclass "abc.ABCMeta" implements these '
8622n/a 'methods in\n'
8623n/a 'order to allow the addition of Abstract Base Classes (ABCs) '
8624n/a 'as\n'
8625n/a '"virtual base classes" to any class or type (including '
8626n/a 'built-in\n'
8627n/a 'types), including other ABCs.\n'
8628n/a '\n'
8629n/a 'class.__instancecheck__(self, instance)\n'
8630n/a '\n'
8631n/a ' Return true if *instance* should be considered a (direct '
8632n/a 'or\n'
8633n/a ' indirect) instance of *class*. If defined, called to '
8634n/a 'implement\n'
8635n/a ' "isinstance(instance, class)".\n'
8636n/a '\n'
8637n/a 'class.__subclasscheck__(self, subclass)\n'
8638n/a '\n'
8639n/a ' Return true if *subclass* should be considered a (direct '
8640n/a 'or\n'
8641n/a ' indirect) subclass of *class*. If defined, called to '
8642n/a 'implement\n'
8643n/a ' "issubclass(subclass, class)".\n'
8644n/a '\n'
8645n/a 'Note that these methods are looked up on the type '
8646n/a '(metaclass) of a\n'
8647n/a 'class. They cannot be defined as class methods in the '
8648n/a 'actual class.\n'
8649n/a 'This is consistent with the lookup of special methods that '
8650n/a 'are called\n'
8651n/a 'on instances, only in this case the instance is itself a '
8652n/a 'class.\n'
8653n/a '\n'
8654n/a 'See also:\n'
8655n/a '\n'
8656n/a ' **PEP 3119** - Introducing Abstract Base Classes\n'
8657n/a ' Includes the specification for customizing '
8658n/a '"isinstance()" and\n'
8659n/a ' "issubclass()" behavior through "__instancecheck__()" '
8660n/a 'and\n'
8661n/a ' "__subclasscheck__()", with motivation for this '
8662n/a 'functionality in\n'
8663n/a ' the context of adding Abstract Base Classes (see the '
8664n/a '"abc"\n'
8665n/a ' module) to the language.\n'
8666n/a '\n'
8667n/a '\n'
8668n/a 'Emulating callable objects\n'
8669n/a '==========================\n'
8670n/a '\n'
8671n/a 'object.__call__(self[, args...])\n'
8672n/a '\n'
8673n/a ' Called when the instance is "called" as a function; if '
8674n/a 'this method\n'
8675n/a ' is defined, "x(arg1, arg2, ...)" is a shorthand for\n'
8676n/a ' "x.__call__(arg1, arg2, ...)".\n'
8677n/a '\n'
8678n/a '\n'
8679n/a 'Emulating container types\n'
8680n/a '=========================\n'
8681n/a '\n'
8682n/a 'The following methods can be defined to implement container '
8683n/a 'objects.\n'
8684n/a 'Containers usually are sequences (such as lists or tuples) '
8685n/a 'or mappings\n'
8686n/a '(like dictionaries), but can represent other containers as '
8687n/a 'well. The\n'
8688n/a 'first set of methods is used either to emulate a sequence or '
8689n/a 'to\n'
8690n/a 'emulate a mapping; the difference is that for a sequence, '
8691n/a 'the\n'
8692n/a 'allowable keys should be the integers *k* for which "0 <= k '
8693n/a '< N" where\n'
8694n/a '*N* is the length of the sequence, or slice objects, which '
8695n/a 'define a\n'
8696n/a 'range of items. It is also recommended that mappings '
8697n/a 'provide the\n'
8698n/a 'methods "keys()", "values()", "items()", "get()", '
8699n/a '"clear()",\n'
8700n/a '"setdefault()", "pop()", "popitem()", "copy()", and '
8701n/a '"update()"\n'
8702n/a "behaving similar to those for Python's standard dictionary "
8703n/a 'objects.\n'
8704n/a 'The "collections" module provides a "MutableMapping" '
8705n/a 'abstract base\n'
8706n/a 'class to help create those methods from a base set of '
8707n/a '"__getitem__()",\n'
8708n/a '"__setitem__()", "__delitem__()", and "keys()". Mutable '
8709n/a 'sequences\n'
8710n/a 'should provide methods "append()", "count()", "index()", '
8711n/a '"extend()",\n'
8712n/a '"insert()", "pop()", "remove()", "reverse()" and "sort()", '
8713n/a 'like Python\n'
8714n/a 'standard list objects. Finally, sequence types should '
8715n/a 'implement\n'
8716n/a 'addition (meaning concatenation) and multiplication '
8717n/a '(meaning\n'
8718n/a 'repetition) by defining the methods "__add__()", '
8719n/a '"__radd__()",\n'
8720n/a '"__iadd__()", "__mul__()", "__rmul__()" and "__imul__()" '
8721n/a 'described\n'
8722n/a 'below; they should not define other numerical operators. It '
8723n/a 'is\n'
8724n/a 'recommended that both mappings and sequences implement the\n'
8725n/a '"__contains__()" method to allow efficient use of the "in" '
8726n/a 'operator;\n'
8727n/a 'for mappings, "in" should search the mapping\'s keys; for '
8728n/a 'sequences, it\n'
8729n/a 'should search through the values. It is further recommended '
8730n/a 'that both\n'
8731n/a 'mappings and sequences implement the "__iter__()" method to '
8732n/a 'allow\n'
8733n/a 'efficient iteration through the container; for mappings, '
8734n/a '"__iter__()"\n'
8735n/a 'should be the same as "keys()"; for sequences, it should '
8736n/a 'iterate\n'
8737n/a 'through the values.\n'
8738n/a '\n'
8739n/a 'object.__len__(self)\n'
8740n/a '\n'
8741n/a ' Called to implement the built-in function "len()". '
8742n/a 'Should return\n'
8743n/a ' the length of the object, an integer ">=" 0. Also, an '
8744n/a 'object that\n'
8745n/a ' doesn\'t define a "__bool__()" method and whose '
8746n/a '"__len__()" method\n'
8747n/a ' returns zero is considered to be false in a Boolean '
8748n/a 'context.\n'
8749n/a '\n'
8750n/a 'object.__length_hint__(self)\n'
8751n/a '\n'
8752n/a ' Called to implement "operator.length_hint()". Should '
8753n/a 'return an\n'
8754n/a ' estimated length for the object (which may be greater or '
8755n/a 'less than\n'
8756n/a ' the actual length). The length must be an integer ">=" 0. '
8757n/a 'This\n'
8758n/a ' method is purely an optimization and is never required '
8759n/a 'for\n'
8760n/a ' correctness.\n'
8761n/a '\n'
8762n/a ' New in version 3.4.\n'
8763n/a '\n'
8764n/a 'Note: Slicing is done exclusively with the following three '
8765n/a 'methods.\n'
8766n/a ' A call like\n'
8767n/a '\n'
8768n/a ' a[1:2] = b\n'
8769n/a '\n'
8770n/a ' is translated to\n'
8771n/a '\n'
8772n/a ' a[slice(1, 2, None)] = b\n'
8773n/a '\n'
8774n/a ' and so forth. Missing slice items are always filled in '
8775n/a 'with "None".\n'
8776n/a '\n'
8777n/a 'object.__getitem__(self, key)\n'
8778n/a '\n'
8779n/a ' Called to implement evaluation of "self[key]". For '
8780n/a 'sequence types,\n'
8781n/a ' the accepted keys should be integers and slice objects. '
8782n/a 'Note that\n'
8783n/a ' the special interpretation of negative indexes (if the '
8784n/a 'class wishes\n'
8785n/a ' to emulate a sequence type) is up to the "__getitem__()" '
8786n/a 'method. If\n'
8787n/a ' *key* is of an inappropriate type, "TypeError" may be '
8788n/a 'raised; if of\n'
8789n/a ' a value outside the set of indexes for the sequence '
8790n/a '(after any\n'
8791n/a ' special interpretation of negative values), "IndexError" '
8792n/a 'should be\n'
8793n/a ' raised. For mapping types, if *key* is missing (not in '
8794n/a 'the\n'
8795n/a ' container), "KeyError" should be raised.\n'
8796n/a '\n'
8797n/a ' Note: "for" loops expect that an "IndexError" will be '
8798n/a 'raised for\n'
8799n/a ' illegal indexes to allow proper detection of the end of '
8800n/a 'the\n'
8801n/a ' sequence.\n'
8802n/a '\n'
8803n/a 'object.__missing__(self, key)\n'
8804n/a '\n'
8805n/a ' Called by "dict"."__getitem__()" to implement "self[key]" '
8806n/a 'for dict\n'
8807n/a ' subclasses when key is not in the dictionary.\n'
8808n/a '\n'
8809n/a 'object.__setitem__(self, key, value)\n'
8810n/a '\n'
8811n/a ' Called to implement assignment to "self[key]". Same note '
8812n/a 'as for\n'
8813n/a ' "__getitem__()". This should only be implemented for '
8814n/a 'mappings if\n'
8815n/a ' the objects support changes to the values for keys, or if '
8816n/a 'new keys\n'
8817n/a ' can be added, or for sequences if elements can be '
8818n/a 'replaced. The\n'
8819n/a ' same exceptions should be raised for improper *key* '
8820n/a 'values as for\n'
8821n/a ' the "__getitem__()" method.\n'
8822n/a '\n'
8823n/a 'object.__delitem__(self, key)\n'
8824n/a '\n'
8825n/a ' Called to implement deletion of "self[key]". Same note '
8826n/a 'as for\n'
8827n/a ' "__getitem__()". This should only be implemented for '
8828n/a 'mappings if\n'
8829n/a ' the objects support removal of keys, or for sequences if '
8830n/a 'elements\n'
8831n/a ' can be removed from the sequence. The same exceptions '
8832n/a 'should be\n'
8833n/a ' raised for improper *key* values as for the '
8834n/a '"__getitem__()" method.\n'
8835n/a '\n'
8836n/a 'object.__iter__(self)\n'
8837n/a '\n'
8838n/a ' This method is called when an iterator is required for a '
8839n/a 'container.\n'
8840n/a ' This method should return a new iterator object that can '
8841n/a 'iterate\n'
8842n/a ' over all the objects in the container. For mappings, it '
8843n/a 'should\n'
8844n/a ' iterate over the keys of the container.\n'
8845n/a '\n'
8846n/a ' Iterator objects also need to implement this method; they '
8847n/a 'are\n'
8848n/a ' required to return themselves. For more information on '
8849n/a 'iterator\n'
8850n/a ' objects, see Iterator Types.\n'
8851n/a '\n'
8852n/a 'object.__reversed__(self)\n'
8853n/a '\n'
8854n/a ' Called (if present) by the "reversed()" built-in to '
8855n/a 'implement\n'
8856n/a ' reverse iteration. It should return a new iterator '
8857n/a 'object that\n'
8858n/a ' iterates over all the objects in the container in reverse '
8859n/a 'order.\n'
8860n/a '\n'
8861n/a ' If the "__reversed__()" method is not provided, the '
8862n/a '"reversed()"\n'
8863n/a ' built-in will fall back to using the sequence protocol '
8864n/a '("__len__()"\n'
8865n/a ' and "__getitem__()"). Objects that support the sequence '
8866n/a 'protocol\n'
8867n/a ' should only provide "__reversed__()" if they can provide '
8868n/a 'an\n'
8869n/a ' implementation that is more efficient than the one '
8870n/a 'provided by\n'
8871n/a ' "reversed()".\n'
8872n/a '\n'
8873n/a 'The membership test operators ("in" and "not in") are '
8874n/a 'normally\n'
8875n/a 'implemented as an iteration through a sequence. However, '
8876n/a 'container\n'
8877n/a 'objects can supply the following special method with a more '
8878n/a 'efficient\n'
8879n/a 'implementation, which also does not require the object be a '
8880n/a 'sequence.\n'
8881n/a '\n'
8882n/a 'object.__contains__(self, item)\n'
8883n/a '\n'
8884n/a ' Called to implement membership test operators. Should '
8885n/a 'return true\n'
8886n/a ' if *item* is in *self*, false otherwise. For mapping '
8887n/a 'objects, this\n'
8888n/a ' should consider the keys of the mapping rather than the '
8889n/a 'values or\n'
8890n/a ' the key-item pairs.\n'
8891n/a '\n'
8892n/a ' For objects that don\'t define "__contains__()", the '
8893n/a 'membership test\n'
8894n/a ' first tries iteration via "__iter__()", then the old '
8895n/a 'sequence\n'
8896n/a ' iteration protocol via "__getitem__()", see this section '
8897n/a 'in the\n'
8898n/a ' language reference.\n'
8899n/a '\n'
8900n/a '\n'
8901n/a 'Emulating numeric types\n'
8902n/a '=======================\n'
8903n/a '\n'
8904n/a 'The following methods can be defined to emulate numeric '
8905n/a 'objects.\n'
8906n/a 'Methods corresponding to operations that are not supported '
8907n/a 'by the\n'
8908n/a 'particular kind of number implemented (e.g., bitwise '
8909n/a 'operations for\n'
8910n/a 'non-integral numbers) should be left undefined.\n'
8911n/a '\n'
8912n/a 'object.__add__(self, other)\n'
8913n/a 'object.__sub__(self, other)\n'
8914n/a 'object.__mul__(self, other)\n'
8915n/a 'object.__matmul__(self, other)\n'
8916n/a 'object.__truediv__(self, other)\n'
8917n/a 'object.__floordiv__(self, other)\n'
8918n/a 'object.__mod__(self, other)\n'
8919n/a 'object.__divmod__(self, other)\n'
8920n/a 'object.__pow__(self, other[, modulo])\n'
8921n/a 'object.__lshift__(self, other)\n'
8922n/a 'object.__rshift__(self, other)\n'
8923n/a 'object.__and__(self, other)\n'
8924n/a 'object.__xor__(self, other)\n'
8925n/a 'object.__or__(self, other)\n'
8926n/a '\n'
8927n/a ' These methods are called to implement the binary '
8928n/a 'arithmetic\n'
8929n/a ' operations ("+", "-", "*", "@", "/", "//", "%", '
8930n/a '"divmod()",\n'
8931n/a ' "pow()", "**", "<<", ">>", "&", "^", "|"). For instance, '
8932n/a 'to\n'
8933n/a ' evaluate the expression "x + y", where *x* is an instance '
8934n/a 'of a\n'
8935n/a ' class that has an "__add__()" method, "x.__add__(y)" is '
8936n/a 'called.\n'
8937n/a ' The "__divmod__()" method should be the equivalent to '
8938n/a 'using\n'
8939n/a ' "__floordiv__()" and "__mod__()"; it should not be '
8940n/a 'related to\n'
8941n/a ' "__truediv__()". Note that "__pow__()" should be defined '
8942n/a 'to accept\n'
8943n/a ' an optional third argument if the ternary version of the '
8944n/a 'built-in\n'
8945n/a ' "pow()" function is to be supported.\n'
8946n/a '\n'
8947n/a ' If one of those methods does not support the operation '
8948n/a 'with the\n'
8949n/a ' supplied arguments, it should return "NotImplemented".\n'
8950n/a '\n'
8951n/a 'object.__radd__(self, other)\n'
8952n/a 'object.__rsub__(self, other)\n'
8953n/a 'object.__rmul__(self, other)\n'
8954n/a 'object.__rmatmul__(self, other)\n'
8955n/a 'object.__rtruediv__(self, other)\n'
8956n/a 'object.__rfloordiv__(self, other)\n'
8957n/a 'object.__rmod__(self, other)\n'
8958n/a 'object.__rdivmod__(self, other)\n'
8959n/a 'object.__rpow__(self, other)\n'
8960n/a 'object.__rlshift__(self, other)\n'
8961n/a 'object.__rrshift__(self, other)\n'
8962n/a 'object.__rand__(self, other)\n'
8963n/a 'object.__rxor__(self, other)\n'
8964n/a 'object.__ror__(self, other)\n'
8965n/a '\n'
8966n/a ' These methods are called to implement the binary '
8967n/a 'arithmetic\n'
8968n/a ' operations ("+", "-", "*", "@", "/", "//", "%", '
8969n/a '"divmod()",\n'
8970n/a ' "pow()", "**", "<<", ">>", "&", "^", "|") with reflected '
8971n/a '(swapped)\n'
8972n/a ' operands. These functions are only called if the left '
8973n/a 'operand does\n'
8974n/a ' not support the corresponding operation [3] and the '
8975n/a 'operands are of\n'
8976n/a ' different types. [4] For instance, to evaluate the '
8977n/a 'expression "x -\n'
8978n/a ' y", where *y* is an instance of a class that has an '
8979n/a '"__rsub__()"\n'
8980n/a ' method, "y.__rsub__(x)" is called if "x.__sub__(y)" '
8981n/a 'returns\n'
8982n/a ' *NotImplemented*.\n'
8983n/a '\n'
8984n/a ' Note that ternary "pow()" will not try calling '
8985n/a '"__rpow__()" (the\n'
8986n/a ' coercion rules would become too complicated).\n'
8987n/a '\n'
8988n/a " Note: If the right operand's type is a subclass of the "
8989n/a 'left\n'
8990n/a " operand's type and that subclass provides the reflected "
8991n/a 'method\n'
8992n/a ' for the operation, this method will be called before '
8993n/a 'the left\n'
8994n/a " operand's non-reflected method. This behavior allows "
8995n/a 'subclasses\n'
8996n/a " to override their ancestors' operations.\n"
8997n/a '\n'
8998n/a 'object.__iadd__(self, other)\n'
8999n/a 'object.__isub__(self, other)\n'
9000n/a 'object.__imul__(self, other)\n'
9001n/a 'object.__imatmul__(self, other)\n'
9002n/a 'object.__itruediv__(self, other)\n'
9003n/a 'object.__ifloordiv__(self, other)\n'
9004n/a 'object.__imod__(self, other)\n'
9005n/a 'object.__ipow__(self, other[, modulo])\n'
9006n/a 'object.__ilshift__(self, other)\n'
9007n/a 'object.__irshift__(self, other)\n'
9008n/a 'object.__iand__(self, other)\n'
9009n/a 'object.__ixor__(self, other)\n'
9010n/a 'object.__ior__(self, other)\n'
9011n/a '\n'
9012n/a ' These methods are called to implement the augmented '
9013n/a 'arithmetic\n'
9014n/a ' assignments ("+=", "-=", "*=", "@=", "/=", "//=", "%=", '
9015n/a '"**=",\n'
9016n/a ' "<<=", ">>=", "&=", "^=", "|="). These methods should '
9017n/a 'attempt to\n'
9018n/a ' do the operation in-place (modifying *self*) and return '
9019n/a 'the result\n'
9020n/a ' (which could be, but does not have to be, *self*). If a '
9021n/a 'specific\n'
9022n/a ' method is not defined, the augmented assignment falls '
9023n/a 'back to the\n'
9024n/a ' normal methods. For instance, if *x* is an instance of a '
9025n/a 'class\n'
9026n/a ' with an "__iadd__()" method, "x += y" is equivalent to "x '
9027n/a '=\n'
9028n/a ' x.__iadd__(y)" . Otherwise, "x.__add__(y)" and '
9029n/a '"y.__radd__(x)" are\n'
9030n/a ' considered, as with the evaluation of "x + y". In '
9031n/a 'certain\n'
9032n/a ' situations, augmented assignment can result in unexpected '
9033n/a 'errors\n'
9034n/a " (see Why does a_tuple[i] += ['item'] raise an exception "
9035n/a 'when the\n'
9036n/a ' addition works?), but this behavior is in fact part of '
9037n/a 'the data\n'
9038n/a ' model.\n'
9039n/a '\n'
9040n/a 'object.__neg__(self)\n'
9041n/a 'object.__pos__(self)\n'
9042n/a 'object.__abs__(self)\n'
9043n/a 'object.__invert__(self)\n'
9044n/a '\n'
9045n/a ' Called to implement the unary arithmetic operations ("-", '
9046n/a '"+",\n'
9047n/a ' "abs()" and "~").\n'
9048n/a '\n'
9049n/a 'object.__complex__(self)\n'
9050n/a 'object.__int__(self)\n'
9051n/a 'object.__float__(self)\n'
9052n/a 'object.__round__(self[, n])\n'
9053n/a '\n'
9054n/a ' Called to implement the built-in functions "complex()", '
9055n/a '"int()",\n'
9056n/a ' "float()" and "round()". Should return a value of the '
9057n/a 'appropriate\n'
9058n/a ' type.\n'
9059n/a '\n'
9060n/a 'object.__index__(self)\n'
9061n/a '\n'
9062n/a ' Called to implement "operator.index()", and whenever '
9063n/a 'Python needs\n'
9064n/a ' to losslessly convert the numeric object to an integer '
9065n/a 'object (such\n'
9066n/a ' as in slicing, or in the built-in "bin()", "hex()" and '
9067n/a '"oct()"\n'
9068n/a ' functions). Presence of this method indicates that the '
9069n/a 'numeric\n'
9070n/a ' object is an integer type. Must return an integer.\n'
9071n/a '\n'
9072n/a ' Note: In order to have a coherent integer type class, '
9073n/a 'when\n'
9074n/a ' "__index__()" is defined "__int__()" should also be '
9075n/a 'defined, and\n'
9076n/a ' both should return the same value.\n'
9077n/a '\n'
9078n/a '\n'
9079n/a 'With Statement Context Managers\n'
9080n/a '===============================\n'
9081n/a '\n'
9082n/a 'A *context manager* is an object that defines the runtime '
9083n/a 'context to\n'
9084n/a 'be established when executing a "with" statement. The '
9085n/a 'context manager\n'
9086n/a 'handles the entry into, and the exit from, the desired '
9087n/a 'runtime context\n'
9088n/a 'for the execution of the block of code. Context managers '
9089n/a 'are normally\n'
9090n/a 'invoked using the "with" statement (described in section The '
9091n/a 'with\n'
9092n/a 'statement), but can also be used by directly invoking their '
9093n/a 'methods.\n'
9094n/a '\n'
9095n/a 'Typical uses of context managers include saving and '
9096n/a 'restoring various\n'
9097n/a 'kinds of global state, locking and unlocking resources, '
9098n/a 'closing opened\n'
9099n/a 'files, etc.\n'
9100n/a '\n'
9101n/a 'For more information on context managers, see Context '
9102n/a 'Manager Types.\n'
9103n/a '\n'
9104n/a 'object.__enter__(self)\n'
9105n/a '\n'
9106n/a ' Enter the runtime context related to this object. The '
9107n/a '"with"\n'
9108n/a " statement will bind this method's return value to the "
9109n/a 'target(s)\n'
9110n/a ' specified in the "as" clause of the statement, if any.\n'
9111n/a '\n'
9112n/a 'object.__exit__(self, exc_type, exc_value, traceback)\n'
9113n/a '\n'
9114n/a ' Exit the runtime context related to this object. The '
9115n/a 'parameters\n'
9116n/a ' describe the exception that caused the context to be '
9117n/a 'exited. If the\n'
9118n/a ' context was exited without an exception, all three '
9119n/a 'arguments will\n'
9120n/a ' be "None".\n'
9121n/a '\n'
9122n/a ' If an exception is supplied, and the method wishes to '
9123n/a 'suppress the\n'
9124n/a ' exception (i.e., prevent it from being propagated), it '
9125n/a 'should\n'
9126n/a ' return a true value. Otherwise, the exception will be '
9127n/a 'processed\n'
9128n/a ' normally upon exit from this method.\n'
9129n/a '\n'
9130n/a ' Note that "__exit__()" methods should not reraise the '
9131n/a 'passed-in\n'
9132n/a " exception; this is the caller's responsibility.\n"
9133n/a '\n'
9134n/a 'See also:\n'
9135n/a '\n'
9136n/a ' **PEP 343** - The "with" statement\n'
9137n/a ' The specification, background, and examples for the '
9138n/a 'Python "with"\n'
9139n/a ' statement.\n'
9140n/a '\n'
9141n/a '\n'
9142n/a 'Special method lookup\n'
9143n/a '=====================\n'
9144n/a '\n'
9145n/a 'For custom classes, implicit invocations of special methods '
9146n/a 'are only\n'
9147n/a "guaranteed to work correctly if defined on an object's type, "
9148n/a 'not in\n'
9149n/a "the object's instance dictionary. That behaviour is the "
9150n/a 'reason why\n'
9151n/a 'the following code raises an exception:\n'
9152n/a '\n'
9153n/a ' >>> class C:\n'
9154n/a ' ... pass\n'
9155n/a ' ...\n'
9156n/a ' >>> c = C()\n'
9157n/a ' >>> c.__len__ = lambda: 5\n'
9158n/a ' >>> len(c)\n'
9159n/a ' Traceback (most recent call last):\n'
9160n/a ' File "<stdin>", line 1, in <module>\n'
9161n/a " TypeError: object of type 'C' has no len()\n"
9162n/a '\n'
9163n/a 'The rationale behind this behaviour lies with a number of '
9164n/a 'special\n'
9165n/a 'methods such as "__hash__()" and "__repr__()" that are '
9166n/a 'implemented by\n'
9167n/a 'all objects, including type objects. If the implicit lookup '
9168n/a 'of these\n'
9169n/a 'methods used the conventional lookup process, they would '
9170n/a 'fail when\n'
9171n/a 'invoked on the type object itself:\n'
9172n/a '\n'
9173n/a ' >>> 1 .__hash__() == hash(1)\n'
9174n/a ' True\n'
9175n/a ' >>> int.__hash__() == hash(int)\n'
9176n/a ' Traceback (most recent call last):\n'
9177n/a ' File "<stdin>", line 1, in <module>\n'
9178n/a " TypeError: descriptor '__hash__' of 'int' object needs an "
9179n/a 'argument\n'
9180n/a '\n'
9181n/a 'Incorrectly attempting to invoke an unbound method of a '
9182n/a 'class in this\n'
9183n/a "way is sometimes referred to as 'metaclass confusion', and "
9184n/a 'is avoided\n'
9185n/a 'by bypassing the instance when looking up special methods:\n'
9186n/a '\n'
9187n/a ' >>> type(1).__hash__(1) == hash(1)\n'
9188n/a ' True\n'
9189n/a ' >>> type(int).__hash__(int) == hash(int)\n'
9190n/a ' True\n'
9191n/a '\n'
9192n/a 'In addition to bypassing any instance attributes in the '
9193n/a 'interest of\n'
9194n/a 'correctness, implicit special method lookup generally also '
9195n/a 'bypasses\n'
9196n/a 'the "__getattribute__()" method even of the object\'s '
9197n/a 'metaclass:\n'
9198n/a '\n'
9199n/a ' >>> class Meta(type):\n'
9200n/a ' ... def __getattribute__(*args):\n'
9201n/a ' ... print("Metaclass getattribute invoked")\n'
9202n/a ' ... return type.__getattribute__(*args)\n'
9203n/a ' ...\n'
9204n/a ' >>> class C(object, metaclass=Meta):\n'
9205n/a ' ... def __len__(self):\n'
9206n/a ' ... return 10\n'
9207n/a ' ... def __getattribute__(*args):\n'
9208n/a ' ... print("Class getattribute invoked")\n'
9209n/a ' ... return object.__getattribute__(*args)\n'
9210n/a ' ...\n'
9211n/a ' >>> c = C()\n'
9212n/a ' >>> c.__len__() # Explicit lookup via '
9213n/a 'instance\n'
9214n/a ' Class getattribute invoked\n'
9215n/a ' 10\n'
9216n/a ' >>> type(c).__len__(c) # Explicit lookup via '
9217n/a 'type\n'
9218n/a ' Metaclass getattribute invoked\n'
9219n/a ' 10\n'
9220n/a ' >>> len(c) # Implicit lookup\n'
9221n/a ' 10\n'
9222n/a '\n'
9223n/a 'Bypassing the "__getattribute__()" machinery in this fashion '
9224n/a 'provides\n'
9225n/a 'significant scope for speed optimisations within the '
9226n/a 'interpreter, at\n'
9227n/a 'the cost of some flexibility in the handling of special '
9228n/a 'methods (the\n'
9229n/a 'special method *must* be set on the class object itself in '
9230n/a 'order to be\n'
9231n/a 'consistently invoked by the interpreter).\n',
9232n/a 'string-methods': '\n'
9233n/a 'String Methods\n'
9234n/a '**************\n'
9235n/a '\n'
9236n/a 'Strings implement all of the common sequence operations, '
9237n/a 'along with\n'
9238n/a 'the additional methods described below.\n'
9239n/a '\n'
9240n/a 'Strings also support two styles of string formatting, one '
9241n/a 'providing a\n'
9242n/a 'large degree of flexibility and customization (see '
9243n/a '"str.format()",\n'
9244n/a 'Format String Syntax and Custom String Formatting) and the '
9245n/a 'other based\n'
9246n/a 'on C "printf" style formatting that handles a narrower '
9247n/a 'range of types\n'
9248n/a 'and is slightly harder to use correctly, but is often '
9249n/a 'faster for the\n'
9250n/a 'cases it can handle (printf-style String Formatting).\n'
9251n/a '\n'
9252n/a 'The Text Processing Services section of the standard '
9253n/a 'library covers a\n'
9254n/a 'number of other modules that provide various text related '
9255n/a 'utilities\n'
9256n/a '(including regular expression support in the "re" '
9257n/a 'module).\n'
9258n/a '\n'
9259n/a 'str.capitalize()\n'
9260n/a '\n'
9261n/a ' Return a copy of the string with its first character '
9262n/a 'capitalized\n'
9263n/a ' and the rest lowercased.\n'
9264n/a '\n'
9265n/a 'str.casefold()\n'
9266n/a '\n'
9267n/a ' Return a casefolded copy of the string. Casefolded '
9268n/a 'strings may be\n'
9269n/a ' used for caseless matching.\n'
9270n/a '\n'
9271n/a ' Casefolding is similar to lowercasing but more '
9272n/a 'aggressive because\n'
9273n/a ' it is intended to remove all case distinctions in a '
9274n/a 'string. For\n'
9275n/a ' example, the German lowercase letter "\'รƒŸ\'" is '
9276n/a 'equivalent to ""ss"".\n'
9277n/a ' Since it is already lowercase, "lower()" would do '
9278n/a 'nothing to "\'รƒŸ\'";\n'
9279n/a ' "casefold()" converts it to ""ss"".\n'
9280n/a '\n'
9281n/a ' The casefolding algorithm is described in section 3.13 '
9282n/a 'of the\n'
9283n/a ' Unicode Standard.\n'
9284n/a '\n'
9285n/a ' New in version 3.3.\n'
9286n/a '\n'
9287n/a 'str.center(width[, fillchar])\n'
9288n/a '\n'
9289n/a ' Return centered in a string of length *width*. Padding '
9290n/a 'is done\n'
9291n/a ' using the specified *fillchar* (default is an ASCII '
9292n/a 'space). The\n'
9293n/a ' original string is returned if *width* is less than or '
9294n/a 'equal to\n'
9295n/a ' "len(s)".\n'
9296n/a '\n'
9297n/a 'str.count(sub[, start[, end]])\n'
9298n/a '\n'
9299n/a ' Return the number of non-overlapping occurrences of '
9300n/a 'substring *sub*\n'
9301n/a ' in the range [*start*, *end*]. Optional arguments '
9302n/a '*start* and\n'
9303n/a ' *end* are interpreted as in slice notation.\n'
9304n/a '\n'
9305n/a 'str.encode(encoding="utf-8", errors="strict")\n'
9306n/a '\n'
9307n/a ' Return an encoded version of the string as a bytes '
9308n/a 'object. Default\n'
9309n/a ' encoding is "\'utf-8\'". *errors* may be given to set a '
9310n/a 'different\n'
9311n/a ' error handling scheme. The default for *errors* is '
9312n/a '"\'strict\'",\n'
9313n/a ' meaning that encoding errors raise a "UnicodeError". '
9314n/a 'Other possible\n'
9315n/a ' values are "\'ignore\'", "\'replace\'", '
9316n/a '"\'xmlcharrefreplace\'",\n'
9317n/a ' "\'backslashreplace\'" and any other name registered '
9318n/a 'via\n'
9319n/a ' "codecs.register_error()", see section Error Handlers. '
9320n/a 'For a list\n'
9321n/a ' of possible encodings, see section Standard Encodings.\n'
9322n/a '\n'
9323n/a ' Changed in version 3.1: Support for keyword arguments '
9324n/a 'added.\n'
9325n/a '\n'
9326n/a 'str.endswith(suffix[, start[, end]])\n'
9327n/a '\n'
9328n/a ' Return "True" if the string ends with the specified '
9329n/a '*suffix*,\n'
9330n/a ' otherwise return "False". *suffix* can also be a tuple '
9331n/a 'of suffixes\n'
9332n/a ' to look for. With optional *start*, test beginning at '
9333n/a 'that\n'
9334n/a ' position. With optional *end*, stop comparing at that '
9335n/a 'position.\n'
9336n/a '\n'
9337n/a 'str.expandtabs(tabsize=8)\n'
9338n/a '\n'
9339n/a ' Return a copy of the string where all tab characters '
9340n/a 'are replaced\n'
9341n/a ' by one or more spaces, depending on the current column '
9342n/a 'and the\n'
9343n/a ' given tab size. Tab positions occur every *tabsize* '
9344n/a 'characters\n'
9345n/a ' (default is 8, giving tab positions at columns 0, 8, 16 '
9346n/a 'and so on).\n'
9347n/a ' To expand the string, the current column is set to zero '
9348n/a 'and the\n'
9349n/a ' string is examined character by character. If the '
9350n/a 'character is a\n'
9351n/a ' tab ("\\t"), one or more space characters are inserted '
9352n/a 'in the result\n'
9353n/a ' until the current column is equal to the next tab '
9354n/a 'position. (The\n'
9355n/a ' tab character itself is not copied.) If the character '
9356n/a 'is a newline\n'
9357n/a ' ("\\n") or return ("\\r"), it is copied and the current '
9358n/a 'column is\n'
9359n/a ' reset to zero. Any other character is copied unchanged '
9360n/a 'and the\n'
9361n/a ' current column is incremented by one regardless of how '
9362n/a 'the\n'
9363n/a ' character is represented when printed.\n'
9364n/a '\n'
9365n/a " >>> '01\\t012\\t0123\\t01234'.expandtabs()\n"
9366n/a " '01 012 0123 01234'\n"
9367n/a " >>> '01\\t012\\t0123\\t01234'.expandtabs(4)\n"
9368n/a " '01 012 0123 01234'\n"
9369n/a '\n'
9370n/a 'str.find(sub[, start[, end]])\n'
9371n/a '\n'
9372n/a ' Return the lowest index in the string where substring '
9373n/a '*sub* is\n'
9374n/a ' found within the slice "s[start:end]". Optional '
9375n/a 'arguments *start*\n'
9376n/a ' and *end* are interpreted as in slice notation. Return '
9377n/a '"-1" if\n'
9378n/a ' *sub* is not found.\n'
9379n/a '\n'
9380n/a ' Note: The "find()" method should be used only if you '
9381n/a 'need to know\n'
9382n/a ' the position of *sub*. To check if *sub* is a '
9383n/a 'substring or not,\n'
9384n/a ' use the "in" operator:\n'
9385n/a '\n'
9386n/a " >>> 'Py' in 'Python'\n"
9387n/a ' True\n'
9388n/a '\n'
9389n/a 'str.format(*args, **kwargs)\n'
9390n/a '\n'
9391n/a ' Perform a string formatting operation. The string on '
9392n/a 'which this\n'
9393n/a ' method is called can contain literal text or '
9394n/a 'replacement fields\n'
9395n/a ' delimited by braces "{}". Each replacement field '
9396n/a 'contains either\n'
9397n/a ' the numeric index of a positional argument, or the name '
9398n/a 'of a\n'
9399n/a ' keyword argument. Returns a copy of the string where '
9400n/a 'each\n'
9401n/a ' replacement field is replaced with the string value of '
9402n/a 'the\n'
9403n/a ' corresponding argument.\n'
9404n/a '\n'
9405n/a ' >>> "The sum of 1 + 2 is {0}".format(1+2)\n'
9406n/a " 'The sum of 1 + 2 is 3'\n"
9407n/a '\n'
9408n/a ' See Format String Syntax for a description of the '
9409n/a 'various\n'
9410n/a ' formatting options that can be specified in format '
9411n/a 'strings.\n'
9412n/a '\n'
9413n/a 'str.format_map(mapping)\n'
9414n/a '\n'
9415n/a ' Similar to "str.format(**mapping)", except that '
9416n/a '"mapping" is used\n'
9417n/a ' directly and not copied to a "dict". This is useful if '
9418n/a 'for example\n'
9419n/a ' "mapping" is a dict subclass:\n'
9420n/a '\n'
9421n/a ' >>> class Default(dict):\n'
9422n/a ' ... def __missing__(self, key):\n'
9423n/a ' ... return key\n'
9424n/a ' ...\n'
9425n/a " >>> '{name} was born in "
9426n/a "{country}'.format_map(Default(name='Guido'))\n"
9427n/a " 'Guido was born in country'\n"
9428n/a '\n'
9429n/a ' New in version 3.2.\n'
9430n/a '\n'
9431n/a 'str.index(sub[, start[, end]])\n'
9432n/a '\n'
9433n/a ' Like "find()", but raise "ValueError" when the '
9434n/a 'substring is not\n'
9435n/a ' found.\n'
9436n/a '\n'
9437n/a 'str.isalnum()\n'
9438n/a '\n'
9439n/a ' Return true if all characters in the string are '
9440n/a 'alphanumeric and\n'
9441n/a ' there is at least one character, false otherwise. A '
9442n/a 'character "c"\n'
9443n/a ' is alphanumeric if one of the following returns '
9444n/a '"True":\n'
9445n/a ' "c.isalpha()", "c.isdecimal()", "c.isdigit()", or '
9446n/a '"c.isnumeric()".\n'
9447n/a '\n'
9448n/a 'str.isalpha()\n'
9449n/a '\n'
9450n/a ' Return true if all characters in the string are '
9451n/a 'alphabetic and\n'
9452n/a ' there is at least one character, false otherwise. '
9453n/a 'Alphabetic\n'
9454n/a ' characters are those characters defined in the Unicode '
9455n/a 'character\n'
9456n/a ' database as "Letter", i.e., those with general category '
9457n/a 'property\n'
9458n/a ' being one of "Lm", "Lt", "Lu", "Ll", or "Lo". Note '
9459n/a 'that this is\n'
9460n/a ' different from the "Alphabetic" property defined in the '
9461n/a 'Unicode\n'
9462n/a ' Standard.\n'
9463n/a '\n'
9464n/a 'str.isdecimal()\n'
9465n/a '\n'
9466n/a ' Return true if all characters in the string are decimal '
9467n/a 'characters\n'
9468n/a ' and there is at least one character, false otherwise. '
9469n/a 'Decimal\n'
9470n/a ' characters are those from general category "Nd". This '
9471n/a 'category\n'
9472n/a ' includes digit characters, and all characters that can '
9473n/a 'be used to\n'
9474n/a ' form decimal-radix numbers, e.g. U+0660, ARABIC-INDIC '
9475n/a 'DIGIT ZERO.\n'
9476n/a '\n'
9477n/a 'str.isdigit()\n'
9478n/a '\n'
9479n/a ' Return true if all characters in the string are digits '
9480n/a 'and there is\n'
9481n/a ' at least one character, false otherwise. Digits '
9482n/a 'include decimal\n'
9483n/a ' characters and digits that need special handling, such '
9484n/a 'as the\n'
9485n/a ' compatibility superscript digits. Formally, a digit is '
9486n/a 'a character\n'
9487n/a ' that has the property value Numeric_Type=Digit or\n'
9488n/a ' Numeric_Type=Decimal.\n'
9489n/a '\n'
9490n/a 'str.isidentifier()\n'
9491n/a '\n'
9492n/a ' Return true if the string is a valid identifier '
9493n/a 'according to the\n'
9494n/a ' language definition, section Identifiers and keywords.\n'
9495n/a '\n'
9496n/a ' Use "keyword.iskeyword()" to test for reserved '
9497n/a 'identifiers such as\n'
9498n/a ' "def" and "class".\n'
9499n/a '\n'
9500n/a 'str.islower()\n'
9501n/a '\n'
9502n/a ' Return true if all cased characters [4] in the string '
9503n/a 'are lowercase\n'
9504n/a ' and there is at least one cased character, false '
9505n/a 'otherwise.\n'
9506n/a '\n'
9507n/a 'str.isnumeric()\n'
9508n/a '\n'
9509n/a ' Return true if all characters in the string are numeric '
9510n/a 'characters,\n'
9511n/a ' and there is at least one character, false otherwise. '
9512n/a 'Numeric\n'
9513n/a ' characters include digit characters, and all characters '
9514n/a 'that have\n'
9515n/a ' the Unicode numeric value property, e.g. U+2155, VULGAR '
9516n/a 'FRACTION\n'
9517n/a ' ONE FIFTH. Formally, numeric characters are those with '
9518n/a 'the\n'
9519n/a ' property value Numeric_Type=Digit, Numeric_Type=Decimal '
9520n/a 'or\n'
9521n/a ' Numeric_Type=Numeric.\n'
9522n/a '\n'
9523n/a 'str.isprintable()\n'
9524n/a '\n'
9525n/a ' Return true if all characters in the string are '
9526n/a 'printable or the\n'
9527n/a ' string is empty, false otherwise. Nonprintable '
9528n/a 'characters are\n'
9529n/a ' those characters defined in the Unicode character '
9530n/a 'database as\n'
9531n/a ' "Other" or "Separator", excepting the ASCII space '
9532n/a '(0x20) which is\n'
9533n/a ' considered printable. (Note that printable characters '
9534n/a 'in this\n'
9535n/a ' context are those which should not be escaped when '
9536n/a '"repr()" is\n'
9537n/a ' invoked on a string. It has no bearing on the handling '
9538n/a 'of strings\n'
9539n/a ' written to "sys.stdout" or "sys.stderr".)\n'
9540n/a '\n'
9541n/a 'str.isspace()\n'
9542n/a '\n'
9543n/a ' Return true if there are only whitespace characters in '
9544n/a 'the string\n'
9545n/a ' and there is at least one character, false otherwise. '
9546n/a 'Whitespace\n'
9547n/a ' characters are those characters defined in the Unicode '
9548n/a 'character\n'
9549n/a ' database as "Other" or "Separator" and those with '
9550n/a 'bidirectional\n'
9551n/a ' property being one of "WS", "B", or "S".\n'
9552n/a '\n'
9553n/a 'str.istitle()\n'
9554n/a '\n'
9555n/a ' Return true if the string is a titlecased string and '
9556n/a 'there is at\n'
9557n/a ' least one character, for example uppercase characters '
9558n/a 'may only\n'
9559n/a ' follow uncased characters and lowercase characters only '
9560n/a 'cased ones.\n'
9561n/a ' Return false otherwise.\n'
9562n/a '\n'
9563n/a 'str.isupper()\n'
9564n/a '\n'
9565n/a ' Return true if all cased characters [4] in the string '
9566n/a 'are uppercase\n'
9567n/a ' and there is at least one cased character, false '
9568n/a 'otherwise.\n'
9569n/a '\n'
9570n/a 'str.join(iterable)\n'
9571n/a '\n'
9572n/a ' Return a string which is the concatenation of the '
9573n/a 'strings in the\n'
9574n/a ' *iterable* *iterable*. A "TypeError" will be raised if '
9575n/a 'there are\n'
9576n/a ' any non-string values in *iterable*, including "bytes" '
9577n/a 'objects.\n'
9578n/a ' The separator between elements is the string providing '
9579n/a 'this method.\n'
9580n/a '\n'
9581n/a 'str.ljust(width[, fillchar])\n'
9582n/a '\n'
9583n/a ' Return the string left justified in a string of length '
9584n/a '*width*.\n'
9585n/a ' Padding is done using the specified *fillchar* (default '
9586n/a 'is an ASCII\n'
9587n/a ' space). The original string is returned if *width* is '
9588n/a 'less than or\n'
9589n/a ' equal to "len(s)".\n'
9590n/a '\n'
9591n/a 'str.lower()\n'
9592n/a '\n'
9593n/a ' Return a copy of the string with all the cased '
9594n/a 'characters [4]\n'
9595n/a ' converted to lowercase.\n'
9596n/a '\n'
9597n/a ' The lowercasing algorithm used is described in section '
9598n/a '3.13 of the\n'
9599n/a ' Unicode Standard.\n'
9600n/a '\n'
9601n/a 'str.lstrip([chars])\n'
9602n/a '\n'
9603n/a ' Return a copy of the string with leading characters '
9604n/a 'removed. The\n'
9605n/a ' *chars* argument is a string specifying the set of '
9606n/a 'characters to be\n'
9607n/a ' removed. If omitted or "None", the *chars* argument '
9608n/a 'defaults to\n'
9609n/a ' removing whitespace. The *chars* argument is not a '
9610n/a 'prefix; rather,\n'
9611n/a ' all combinations of its values are stripped:\n'
9612n/a '\n'
9613n/a " >>> ' spacious '.lstrip()\n"
9614n/a " 'spacious '\n"
9615n/a " >>> 'www.example.com'.lstrip('cmowz.')\n"
9616n/a " 'example.com'\n"
9617n/a '\n'
9618n/a 'static str.maketrans(x[, y[, z]])\n'
9619n/a '\n'
9620n/a ' This static method returns a translation table usable '
9621n/a 'for\n'
9622n/a ' "str.translate()".\n'
9623n/a '\n'
9624n/a ' If there is only one argument, it must be a dictionary '
9625n/a 'mapping\n'
9626n/a ' Unicode ordinals (integers) or characters (strings of '
9627n/a 'length 1) to\n'
9628n/a ' Unicode ordinals, strings (of arbitrary lengths) or '
9629n/a 'None.\n'
9630n/a ' Character keys will then be converted to ordinals.\n'
9631n/a '\n'
9632n/a ' If there are two arguments, they must be strings of '
9633n/a 'equal length,\n'
9634n/a ' and in the resulting dictionary, each character in x '
9635n/a 'will be mapped\n'
9636n/a ' to the character at the same position in y. If there '
9637n/a 'is a third\n'
9638n/a ' argument, it must be a string, whose characters will be '
9639n/a 'mapped to\n'
9640n/a ' None in the result.\n'
9641n/a '\n'
9642n/a 'str.partition(sep)\n'
9643n/a '\n'
9644n/a ' Split the string at the first occurrence of *sep*, and '
9645n/a 'return a\n'
9646n/a ' 3-tuple containing the part before the separator, the '
9647n/a 'separator\n'
9648n/a ' itself, and the part after the separator. If the '
9649n/a 'separator is not\n'
9650n/a ' found, return a 3-tuple containing the string itself, '
9651n/a 'followed by\n'
9652n/a ' two empty strings.\n'
9653n/a '\n'
9654n/a 'str.replace(old, new[, count])\n'
9655n/a '\n'
9656n/a ' Return a copy of the string with all occurrences of '
9657n/a 'substring *old*\n'
9658n/a ' replaced by *new*. If the optional argument *count* is '
9659n/a 'given, only\n'
9660n/a ' the first *count* occurrences are replaced.\n'
9661n/a '\n'
9662n/a 'str.rfind(sub[, start[, end]])\n'
9663n/a '\n'
9664n/a ' Return the highest index in the string where substring '
9665n/a '*sub* is\n'
9666n/a ' found, such that *sub* is contained within '
9667n/a '"s[start:end]".\n'
9668n/a ' Optional arguments *start* and *end* are interpreted as '
9669n/a 'in slice\n'
9670n/a ' notation. Return "-1" on failure.\n'
9671n/a '\n'
9672n/a 'str.rindex(sub[, start[, end]])\n'
9673n/a '\n'
9674n/a ' Like "rfind()" but raises "ValueError" when the '
9675n/a 'substring *sub* is\n'
9676n/a ' not found.\n'
9677n/a '\n'
9678n/a 'str.rjust(width[, fillchar])\n'
9679n/a '\n'
9680n/a ' Return the string right justified in a string of length '
9681n/a '*width*.\n'
9682n/a ' Padding is done using the specified *fillchar* (default '
9683n/a 'is an ASCII\n'
9684n/a ' space). The original string is returned if *width* is '
9685n/a 'less than or\n'
9686n/a ' equal to "len(s)".\n'
9687n/a '\n'
9688n/a 'str.rpartition(sep)\n'
9689n/a '\n'
9690n/a ' Split the string at the last occurrence of *sep*, and '
9691n/a 'return a\n'
9692n/a ' 3-tuple containing the part before the separator, the '
9693n/a 'separator\n'
9694n/a ' itself, and the part after the separator. If the '
9695n/a 'separator is not\n'
9696n/a ' found, return a 3-tuple containing two empty strings, '
9697n/a 'followed by\n'
9698n/a ' the string itself.\n'
9699n/a '\n'
9700n/a 'str.rsplit(sep=None, maxsplit=-1)\n'
9701n/a '\n'
9702n/a ' Return a list of the words in the string, using *sep* '
9703n/a 'as the\n'
9704n/a ' delimiter string. If *maxsplit* is given, at most '
9705n/a '*maxsplit* splits\n'
9706n/a ' are done, the *rightmost* ones. If *sep* is not '
9707n/a 'specified or\n'
9708n/a ' "None", any whitespace string is a separator. Except '
9709n/a 'for splitting\n'
9710n/a ' from the right, "rsplit()" behaves like "split()" which '
9711n/a 'is\n'
9712n/a ' described in detail below.\n'
9713n/a '\n'
9714n/a 'str.rstrip([chars])\n'
9715n/a '\n'
9716n/a ' Return a copy of the string with trailing characters '
9717n/a 'removed. The\n'
9718n/a ' *chars* argument is a string specifying the set of '
9719n/a 'characters to be\n'
9720n/a ' removed. If omitted or "None", the *chars* argument '
9721n/a 'defaults to\n'
9722n/a ' removing whitespace. The *chars* argument is not a '
9723n/a 'suffix; rather,\n'
9724n/a ' all combinations of its values are stripped:\n'
9725n/a '\n'
9726n/a " >>> ' spacious '.rstrip()\n"
9727n/a " ' spacious'\n"
9728n/a " >>> 'mississippi'.rstrip('ipz')\n"
9729n/a " 'mississ'\n"
9730n/a '\n'
9731n/a 'str.split(sep=None, maxsplit=-1)\n'
9732n/a '\n'
9733n/a ' Return a list of the words in the string, using *sep* '
9734n/a 'as the\n'
9735n/a ' delimiter string. If *maxsplit* is given, at most '
9736n/a '*maxsplit*\n'
9737n/a ' splits are done (thus, the list will have at most '
9738n/a '"maxsplit+1"\n'
9739n/a ' elements). If *maxsplit* is not specified or "-1", '
9740n/a 'then there is\n'
9741n/a ' no limit on the number of splits (all possible splits '
9742n/a 'are made).\n'
9743n/a '\n'
9744n/a ' If *sep* is given, consecutive delimiters are not '
9745n/a 'grouped together\n'
9746n/a ' and are deemed to delimit empty strings (for example,\n'
9747n/a ' "\'1,,2\'.split(\',\')" returns "[\'1\', \'\', '
9748n/a '\'2\']"). The *sep* argument\n'
9749n/a ' may consist of multiple characters (for example,\n'
9750n/a ' "\'1<>2<>3\'.split(\'<>\')" returns "[\'1\', \'2\', '
9751n/a '\'3\']"). Splitting an\n'
9752n/a ' empty string with a specified separator returns '
9753n/a '"[\'\']".\n'
9754n/a '\n'
9755n/a ' For example:\n'
9756n/a '\n'
9757n/a " >>> '1,2,3'.split(',')\n"
9758n/a " ['1', '2', '3']\n"
9759n/a " >>> '1,2,3'.split(',', maxsplit=1)\n"
9760n/a " ['1', '2,3']\n"
9761n/a " >>> '1,2,,3,'.split(',')\n"
9762n/a " ['1', '2', '', '3', '']\n"
9763n/a '\n'
9764n/a ' If *sep* is not specified or is "None", a different '
9765n/a 'splitting\n'
9766n/a ' algorithm is applied: runs of consecutive whitespace '
9767n/a 'are regarded\n'
9768n/a ' as a single separator, and the result will contain no '
9769n/a 'empty strings\n'
9770n/a ' at the start or end if the string has leading or '
9771n/a 'trailing\n'
9772n/a ' whitespace. Consequently, splitting an empty string or '
9773n/a 'a string\n'
9774n/a ' consisting of just whitespace with a "None" separator '
9775n/a 'returns "[]".\n'
9776n/a '\n'
9777n/a ' For example:\n'
9778n/a '\n'
9779n/a " >>> '1 2 3'.split()\n"
9780n/a " ['1', '2', '3']\n"
9781n/a " >>> '1 2 3'.split(maxsplit=1)\n"
9782n/a " ['1', '2 3']\n"
9783n/a " >>> ' 1 2 3 '.split()\n"
9784n/a " ['1', '2', '3']\n"
9785n/a '\n'
9786n/a 'str.splitlines([keepends])\n'
9787n/a '\n'
9788n/a ' Return a list of the lines in the string, breaking at '
9789n/a 'line\n'
9790n/a ' boundaries. Line breaks are not included in the '
9791n/a 'resulting list\n'
9792n/a ' unless *keepends* is given and true.\n'
9793n/a '\n'
9794n/a ' This method splits on the following line boundaries. '
9795n/a 'In\n'
9796n/a ' particular, the boundaries are a superset of *universal '
9797n/a 'newlines*.\n'
9798n/a '\n'
9799n/a ' '
9800n/a '+-------------------------+-------------------------------+\n'
9801n/a ' | Representation | '
9802n/a 'Description |\n'
9803n/a ' '
9804n/a '+=========================+===============================+\n'
9805n/a ' | "\\n" | Line '
9806n/a 'Feed |\n'
9807n/a ' '
9808n/a '+-------------------------+-------------------------------+\n'
9809n/a ' | "\\r" | Carriage '
9810n/a 'Return |\n'
9811n/a ' '
9812n/a '+-------------------------+-------------------------------+\n'
9813n/a ' | "\\r\\n" | Carriage Return + Line '
9814n/a 'Feed |\n'
9815n/a ' '
9816n/a '+-------------------------+-------------------------------+\n'
9817n/a ' | "\\v" or "\\x0b" | Line '
9818n/a 'Tabulation |\n'
9819n/a ' '
9820n/a '+-------------------------+-------------------------------+\n'
9821n/a ' | "\\f" or "\\x0c" | Form '
9822n/a 'Feed |\n'
9823n/a ' '
9824n/a '+-------------------------+-------------------------------+\n'
9825n/a ' | "\\x1c" | File '
9826n/a 'Separator |\n'
9827n/a ' '
9828n/a '+-------------------------+-------------------------------+\n'
9829n/a ' | "\\x1d" | Group '
9830n/a 'Separator |\n'
9831n/a ' '
9832n/a '+-------------------------+-------------------------------+\n'
9833n/a ' | "\\x1e" | Record '
9834n/a 'Separator |\n'
9835n/a ' '
9836n/a '+-------------------------+-------------------------------+\n'
9837n/a ' | "\\x85" | Next Line (C1 Control '
9838n/a 'Code) |\n'
9839n/a ' '
9840n/a '+-------------------------+-------------------------------+\n'
9841n/a ' | "\\u2028" | Line '
9842n/a 'Separator |\n'
9843n/a ' '
9844n/a '+-------------------------+-------------------------------+\n'
9845n/a ' | "\\u2029" | Paragraph '
9846n/a 'Separator |\n'
9847n/a ' '
9848n/a '+-------------------------+-------------------------------+\n'
9849n/a '\n'
9850n/a ' Changed in version 3.2: "\\v" and "\\f" added to list '
9851n/a 'of line\n'
9852n/a ' boundaries.\n'
9853n/a '\n'
9854n/a ' For example:\n'
9855n/a '\n'
9856n/a " >>> 'ab c\\n\\nde fg\\rkl\\r\\n'.splitlines()\n"
9857n/a " ['ab c', '', 'de fg', 'kl']\n"
9858n/a " >>> 'ab c\\n\\nde "
9859n/a "fg\\rkl\\r\\n'.splitlines(keepends=True)\n"
9860n/a " ['ab c\\n', '\\n', 'de fg\\r', 'kl\\r\\n']\n"
9861n/a '\n'
9862n/a ' Unlike "split()" when a delimiter string *sep* is '
9863n/a 'given, this\n'
9864n/a ' method returns an empty list for the empty string, and '
9865n/a 'a terminal\n'
9866n/a ' line break does not result in an extra line:\n'
9867n/a '\n'
9868n/a ' >>> "".splitlines()\n'
9869n/a ' []\n'
9870n/a ' >>> "One line\\n".splitlines()\n'
9871n/a " ['One line']\n"
9872n/a '\n'
9873n/a ' For comparison, "split(\'\\n\')" gives:\n'
9874n/a '\n'
9875n/a " >>> ''.split('\\n')\n"
9876n/a " ['']\n"
9877n/a " >>> 'Two lines\\n'.split('\\n')\n"
9878n/a " ['Two lines', '']\n"
9879n/a '\n'
9880n/a 'str.startswith(prefix[, start[, end]])\n'
9881n/a '\n'
9882n/a ' Return "True" if string starts with the *prefix*, '
9883n/a 'otherwise return\n'
9884n/a ' "False". *prefix* can also be a tuple of prefixes to '
9885n/a 'look for.\n'
9886n/a ' With optional *start*, test string beginning at that '
9887n/a 'position.\n'
9888n/a ' With optional *end*, stop comparing string at that '
9889n/a 'position.\n'
9890n/a '\n'
9891n/a 'str.strip([chars])\n'
9892n/a '\n'
9893n/a ' Return a copy of the string with the leading and '
9894n/a 'trailing\n'
9895n/a ' characters removed. The *chars* argument is a string '
9896n/a 'specifying the\n'
9897n/a ' set of characters to be removed. If omitted or "None", '
9898n/a 'the *chars*\n'
9899n/a ' argument defaults to removing whitespace. The *chars* '
9900n/a 'argument is\n'
9901n/a ' not a prefix or suffix; rather, all combinations of its '
9902n/a 'values are\n'
9903n/a ' stripped:\n'
9904n/a '\n'
9905n/a " >>> ' spacious '.strip()\n"
9906n/a " 'spacious'\n"
9907n/a " >>> 'www.example.com'.strip('cmowz.')\n"
9908n/a " 'example'\n"
9909n/a '\n'
9910n/a ' The outermost leading and trailing *chars* argument '
9911n/a 'values are\n'
9912n/a ' stripped from the string. Characters are removed from '
9913n/a 'the leading\n'
9914n/a ' end until reaching a string character that is not '
9915n/a 'contained in the\n'
9916n/a ' set of characters in *chars*. A similar action takes '
9917n/a 'place on the\n'
9918n/a ' trailing end. For example:\n'
9919n/a '\n'
9920n/a " >>> comment_string = '#....... Section 3.2.1 Issue "
9921n/a "#32 .......'\n"
9922n/a " >>> comment_string.strip('.#! ')\n"
9923n/a " 'Section 3.2.1 Issue #32'\n"
9924n/a '\n'
9925n/a 'str.swapcase()\n'
9926n/a '\n'
9927n/a ' Return a copy of the string with uppercase characters '
9928n/a 'converted to\n'
9929n/a ' lowercase and vice versa. Note that it is not '
9930n/a 'necessarily true that\n'
9931n/a ' "s.swapcase().swapcase() == s".\n'
9932n/a '\n'
9933n/a 'str.title()\n'
9934n/a '\n'
9935n/a ' Return a titlecased version of the string where words '
9936n/a 'start with an\n'
9937n/a ' uppercase character and the remaining characters are '
9938n/a 'lowercase.\n'
9939n/a '\n'
9940n/a ' For example:\n'
9941n/a '\n'
9942n/a " >>> 'Hello world'.title()\n"
9943n/a " 'Hello World'\n"
9944n/a '\n'
9945n/a ' The algorithm uses a simple language-independent '
9946n/a 'definition of a\n'
9947n/a ' word as groups of consecutive letters. The definition '
9948n/a 'works in\n'
9949n/a ' many contexts but it means that apostrophes in '
9950n/a 'contractions and\n'
9951n/a ' possessives form word boundaries, which may not be the '
9952n/a 'desired\n'
9953n/a ' result:\n'
9954n/a '\n'
9955n/a ' >>> "they\'re bill\'s friends from the UK".title()\n'
9956n/a ' "They\'Re Bill\'S Friends From The Uk"\n'
9957n/a '\n'
9958n/a ' A workaround for apostrophes can be constructed using '
9959n/a 'regular\n'
9960n/a ' expressions:\n'
9961n/a '\n'
9962n/a ' >>> import re\n'
9963n/a ' >>> def titlecase(s):\n'
9964n/a ' ... return re.sub(r"[A-Za-z]+(\'[A-Za-z]+)?",\n'
9965n/a ' ... lambda mo: '
9966n/a 'mo.group(0)[0].upper() +\n'
9967n/a ' ... '
9968n/a 'mo.group(0)[1:].lower(),\n'
9969n/a ' ... s)\n'
9970n/a ' ...\n'
9971n/a ' >>> titlecase("they\'re bill\'s friends.")\n'
9972n/a ' "They\'re Bill\'s Friends."\n'
9973n/a '\n'
9974n/a 'str.translate(table)\n'
9975n/a '\n'
9976n/a ' Return a copy of the string in which each character has '
9977n/a 'been mapped\n'
9978n/a ' through the given translation table. The table must be '
9979n/a 'an object\n'
9980n/a ' that implements indexing via "__getitem__()", typically '
9981n/a 'a *mapping*\n'
9982n/a ' or *sequence*. When indexed by a Unicode ordinal (an '
9983n/a 'integer), the\n'
9984n/a ' table object can do any of the following: return a '
9985n/a 'Unicode ordinal\n'
9986n/a ' or a string, to map the character to one or more other '
9987n/a 'characters;\n'
9988n/a ' return "None", to delete the character from the return '
9989n/a 'string; or\n'
9990n/a ' raise a "LookupError" exception, to map the character '
9991n/a 'to itself.\n'
9992n/a '\n'
9993n/a ' You can use "str.maketrans()" to create a translation '
9994n/a 'map from\n'
9995n/a ' character-to-character mappings in different formats.\n'
9996n/a '\n'
9997n/a ' See also the "codecs" module for a more flexible '
9998n/a 'approach to custom\n'
9999n/a ' character mappings.\n'
10000n/a '\n'
10001n/a 'str.upper()\n'
10002n/a '\n'
10003n/a ' Return a copy of the string with all the cased '
10004n/a 'characters [4]\n'
10005n/a ' converted to uppercase. Note that '
10006n/a '"str.upper().isupper()" might be\n'
10007n/a ' "False" if "s" contains uncased characters or if the '
10008n/a 'Unicode\n'
10009n/a ' category of the resulting character(s) is not "Lu" '
10010n/a '(Letter,\n'
10011n/a ' uppercase), but e.g. "Lt" (Letter, titlecase).\n'
10012n/a '\n'
10013n/a ' The uppercasing algorithm used is described in section '
10014n/a '3.13 of the\n'
10015n/a ' Unicode Standard.\n'
10016n/a '\n'
10017n/a 'str.zfill(width)\n'
10018n/a '\n'
10019n/a ' Return a copy of the string left filled with ASCII '
10020n/a '"\'0\'" digits to\n'
10021n/a ' make a string of length *width*. A leading sign prefix\n'
10022n/a ' ("\'+\'"/"\'-\'") is handled by inserting the padding '
10023n/a '*after* the sign\n'
10024n/a ' character rather than before. The original string is '
10025n/a 'returned if\n'
10026n/a ' *width* is less than or equal to "len(s)".\n'
10027n/a '\n'
10028n/a ' For example:\n'
10029n/a '\n'
10030n/a ' >>> "42".zfill(5)\n'
10031n/a " '00042'\n"
10032n/a ' >>> "-42".zfill(5)\n'
10033n/a " '-0042'\n",
10034n/a 'strings': '\n'
10035n/a 'String and Bytes literals\n'
10036n/a '*************************\n'
10037n/a '\n'
10038n/a 'String literals are described by the following lexical '
10039n/a 'definitions:\n'
10040n/a '\n'
10041n/a ' stringliteral ::= [stringprefix](shortstring | longstring)\n'
10042n/a ' stringprefix ::= "r" | "u" | "R" | "U" | "f" | "F"\n'
10043n/a ' | "fr" | "Fr" | "fR" | "FR" | "rf" | "rF" | '
10044n/a '"Rf" | "RF"\n'
10045n/a ' shortstring ::= "\'" shortstringitem* "\'" | \'"\' '
10046n/a 'shortstringitem* \'"\'\n'
10047n/a ' longstring ::= "\'\'\'" longstringitem* "\'\'\'" | '
10048n/a '\'"""\' longstringitem* \'"""\'\n'
10049n/a ' shortstringitem ::= shortstringchar | stringescapeseq\n'
10050n/a ' longstringitem ::= longstringchar | stringescapeseq\n'
10051n/a ' shortstringchar ::= <any source character except "\\" or '
10052n/a 'newline or the quote>\n'
10053n/a ' longstringchar ::= <any source character except "\\">\n'
10054n/a ' stringescapeseq ::= "\\" <any source character>\n'
10055n/a '\n'
10056n/a ' bytesliteral ::= bytesprefix(shortbytes | longbytes)\n'
10057n/a ' bytesprefix ::= "b" | "B" | "br" | "Br" | "bR" | "BR" | '
10058n/a '"rb" | "rB" | "Rb" | "RB"\n'
10059n/a ' shortbytes ::= "\'" shortbytesitem* "\'" | \'"\' '
10060n/a 'shortbytesitem* \'"\'\n'
10061n/a ' longbytes ::= "\'\'\'" longbytesitem* "\'\'\'" | \'"""\' '
10062n/a 'longbytesitem* \'"""\'\n'
10063n/a ' shortbytesitem ::= shortbyteschar | bytesescapeseq\n'
10064n/a ' longbytesitem ::= longbyteschar | bytesescapeseq\n'
10065n/a ' shortbyteschar ::= <any ASCII character except "\\" or newline '
10066n/a 'or the quote>\n'
10067n/a ' longbyteschar ::= <any ASCII character except "\\">\n'
10068n/a ' bytesescapeseq ::= "\\" <any ASCII character>\n'
10069n/a '\n'
10070n/a 'One syntactic restriction not indicated by these productions is '
10071n/a 'that\n'
10072n/a 'whitespace is not allowed between the "stringprefix" or '
10073n/a '"bytesprefix"\n'
10074n/a 'and the rest of the literal. The source character set is defined '
10075n/a 'by\n'
10076n/a 'the encoding declaration; it is UTF-8 if no encoding declaration '
10077n/a 'is\n'
10078n/a 'given in the source file; see section Encoding declarations.\n'
10079n/a '\n'
10080n/a 'In plain English: Both types of literals can be enclosed in '
10081n/a 'matching\n'
10082n/a 'single quotes ("\'") or double quotes ("""). They can also be '
10083n/a 'enclosed\n'
10084n/a 'in matching groups of three single or double quotes (these are\n'
10085n/a 'generally referred to as *triple-quoted strings*). The '
10086n/a 'backslash\n'
10087n/a '("\\") character is used to escape characters that otherwise have '
10088n/a 'a\n'
10089n/a 'special meaning, such as newline, backslash itself, or the quote\n'
10090n/a 'character.\n'
10091n/a '\n'
10092n/a 'Bytes literals are always prefixed with "\'b\'" or "\'B\'"; they '
10093n/a 'produce\n'
10094n/a 'an instance of the "bytes" type instead of the "str" type. They '
10095n/a 'may\n'
10096n/a 'only contain ASCII characters; bytes with a numeric value of 128 '
10097n/a 'or\n'
10098n/a 'greater must be expressed with escapes.\n'
10099n/a '\n'
10100n/a 'As of Python 3.3 it is possible again to prefix string literals '
10101n/a 'with a\n'
10102n/a '"u" prefix to simplify maintenance of dual 2.x and 3.x '
10103n/a 'codebases.\n'
10104n/a '\n'
10105n/a 'Both string and bytes literals may optionally be prefixed with a\n'
10106n/a 'letter "\'r\'" or "\'R\'"; such strings are called *raw strings* '
10107n/a 'and treat\n'
10108n/a 'backslashes as literal characters. As a result, in string '
10109n/a 'literals,\n'
10110n/a '"\'\\U\'" and "\'\\u\'" escapes in raw strings are not treated '
10111n/a 'specially.\n'
10112n/a "Given that Python 2.x's raw unicode literals behave differently "
10113n/a 'than\n'
10114n/a 'Python 3.x\'s the "\'ur\'" syntax is not supported.\n'
10115n/a '\n'
10116n/a 'New in version 3.3: The "\'rb\'" prefix of raw bytes literals has '
10117n/a 'been\n'
10118n/a 'added as a synonym of "\'br\'".\n'
10119n/a '\n'
10120n/a 'New in version 3.3: Support for the unicode legacy literal\n'
10121n/a '("u\'value\'") was reintroduced to simplify the maintenance of '
10122n/a 'dual\n'
10123n/a 'Python 2.x and 3.x codebases. See **PEP 414** for more '
10124n/a 'information.\n'
10125n/a '\n'
10126n/a 'A string literal with "\'f\'" or "\'F\'" in its prefix is a '
10127n/a '*formatted\n'
10128n/a 'string literal*; see Formatted string literals. The "\'f\'" may '
10129n/a 'be\n'
10130n/a 'combined with "\'r\'", but not with "\'b\'" or "\'u\'", therefore '
10131n/a 'raw\n'
10132n/a 'formatted strings are possible, but formatted bytes literals are '
10133n/a 'not.\n'
10134n/a '\n'
10135n/a 'In triple-quoted literals, unescaped newlines and quotes are '
10136n/a 'allowed\n'
10137n/a '(and are retained), except that three unescaped quotes in a row\n'
10138n/a 'terminate the literal. (A "quote" is the character used to open '
10139n/a 'the\n'
10140n/a 'literal, i.e. either "\'" or """.)\n'
10141n/a '\n'
10142n/a 'Unless an "\'r\'" or "\'R\'" prefix is present, escape sequences '
10143n/a 'in string\n'
10144n/a 'and bytes literals are interpreted according to rules similar to '
10145n/a 'those\n'
10146n/a 'used by Standard C. The recognized escape sequences are:\n'
10147n/a '\n'
10148n/a '+-------------------+-----------------------------------+---------+\n'
10149n/a '| Escape Sequence | Meaning | Notes '
10150n/a '|\n'
10151n/a '+===================+===================================+=========+\n'
10152n/a '| "\\newline" | Backslash and newline ignored '
10153n/a '| |\n'
10154n/a '+-------------------+-----------------------------------+---------+\n'
10155n/a '| "\\\\" | Backslash ("\\") '
10156n/a '| |\n'
10157n/a '+-------------------+-----------------------------------+---------+\n'
10158n/a '| "\\\'" | Single quote ("\'") '
10159n/a '| |\n'
10160n/a '+-------------------+-----------------------------------+---------+\n'
10161n/a '| "\\"" | Double quote (""") '
10162n/a '| |\n'
10163n/a '+-------------------+-----------------------------------+---------+\n'
10164n/a '| "\\a" | ASCII Bell (BEL) '
10165n/a '| |\n'
10166n/a '+-------------------+-----------------------------------+---------+\n'
10167n/a '| "\\b" | ASCII Backspace (BS) '
10168n/a '| |\n'
10169n/a '+-------------------+-----------------------------------+---------+\n'
10170n/a '| "\\f" | ASCII Formfeed (FF) '
10171n/a '| |\n'
10172n/a '+-------------------+-----------------------------------+---------+\n'
10173n/a '| "\\n" | ASCII Linefeed (LF) '
10174n/a '| |\n'
10175n/a '+-------------------+-----------------------------------+---------+\n'
10176n/a '| "\\r" | ASCII Carriage Return (CR) '
10177n/a '| |\n'
10178n/a '+-------------------+-----------------------------------+---------+\n'
10179n/a '| "\\t" | ASCII Horizontal Tab (TAB) '
10180n/a '| |\n'
10181n/a '+-------------------+-----------------------------------+---------+\n'
10182n/a '| "\\v" | ASCII Vertical Tab (VT) '
10183n/a '| |\n'
10184n/a '+-------------------+-----------------------------------+---------+\n'
10185n/a '| "\\ooo" | Character with octal value *ooo* | '
10186n/a '(1,3) |\n'
10187n/a '+-------------------+-----------------------------------+---------+\n'
10188n/a '| "\\xhh" | Character with hex value *hh* | '
10189n/a '(2,3) |\n'
10190n/a '+-------------------+-----------------------------------+---------+\n'
10191n/a '\n'
10192n/a 'Escape sequences only recognized in string literals are:\n'
10193n/a '\n'
10194n/a '+-------------------+-----------------------------------+---------+\n'
10195n/a '| Escape Sequence | Meaning | Notes '
10196n/a '|\n'
10197n/a '+===================+===================================+=========+\n'
10198n/a '| "\\N{name}" | Character named *name* in the | '
10199n/a '(4) |\n'
10200n/a '| | Unicode database | '
10201n/a '|\n'
10202n/a '+-------------------+-----------------------------------+---------+\n'
10203n/a '| "\\uxxxx" | Character with 16-bit hex value | '
10204n/a '(5) |\n'
10205n/a '| | *xxxx* | '
10206n/a '|\n'
10207n/a '+-------------------+-----------------------------------+---------+\n'
10208n/a '| "\\Uxxxxxxxx" | Character with 32-bit hex value | '
10209n/a '(6) |\n'
10210n/a '| | *xxxxxxxx* | '
10211n/a '|\n'
10212n/a '+-------------------+-----------------------------------+---------+\n'
10213n/a '\n'
10214n/a 'Notes:\n'
10215n/a '\n'
10216n/a '1. As in Standard C, up to three octal digits are accepted.\n'
10217n/a '\n'
10218n/a '2. Unlike in Standard C, exactly two hex digits are required.\n'
10219n/a '\n'
10220n/a '3. In a bytes literal, hexadecimal and octal escapes denote the\n'
10221n/a ' byte with the given value. In a string literal, these escapes\n'
10222n/a ' denote a Unicode character with the given value.\n'
10223n/a '\n'
10224n/a '4. Changed in version 3.3: Support for name aliases [1] has been\n'
10225n/a ' added.\n'
10226n/a '\n'
10227n/a '5. Exactly four hex digits are required.\n'
10228n/a '\n'
10229n/a '6. Any Unicode character can be encoded this way. Exactly eight\n'
10230n/a ' hex digits are required.\n'
10231n/a '\n'
10232n/a 'Unlike Standard C, all unrecognized escape sequences are left in '
10233n/a 'the\n'
10234n/a 'string unchanged, i.e., *the backslash is left in the result*. '
10235n/a '(This\n'
10236n/a 'behavior is useful when debugging: if an escape sequence is '
10237n/a 'mistyped,\n'
10238n/a 'the resulting output is more easily recognized as broken.) It is '
10239n/a 'also\n'
10240n/a 'important to note that the escape sequences only recognized in '
10241n/a 'string\n'
10242n/a 'literals fall into the category of unrecognized escapes for '
10243n/a 'bytes\n'
10244n/a 'literals.\n'
10245n/a '\n'
10246n/a ' Changed in version 3.6: Unrecognized escape sequences produce '
10247n/a 'a\n'
10248n/a ' DeprecationWarning. In some future version of Python they '
10249n/a 'will be\n'
10250n/a ' a SyntaxError.\n'
10251n/a '\n'
10252n/a 'Even in a raw literal, quotes can be escaped with a backslash, '
10253n/a 'but the\n'
10254n/a 'backslash remains in the result; for example, "r"\\""" is a '
10255n/a 'valid\n'
10256n/a 'string literal consisting of two characters: a backslash and a '
10257n/a 'double\n'
10258n/a 'quote; "r"\\"" is not a valid string literal (even a raw string '
10259n/a 'cannot\n'
10260n/a 'end in an odd number of backslashes). Specifically, *a raw '
10261n/a 'literal\n'
10262n/a 'cannot end in a single backslash* (since the backslash would '
10263n/a 'escape\n'
10264n/a 'the following quote character). Note also that a single '
10265n/a 'backslash\n'
10266n/a 'followed by a newline is interpreted as those two characters as '
10267n/a 'part\n'
10268n/a 'of the literal, *not* as a line continuation.\n',
10269n/a 'subscriptions': '\n'
10270n/a 'Subscriptions\n'
10271n/a '*************\n'
10272n/a '\n'
10273n/a 'A subscription selects an item of a sequence (string, tuple '
10274n/a 'or list)\n'
10275n/a 'or mapping (dictionary) object:\n'
10276n/a '\n'
10277n/a ' subscription ::= primary "[" expression_list "]"\n'
10278n/a '\n'
10279n/a 'The primary must evaluate to an object that supports '
10280n/a 'subscription\n'
10281n/a '(lists or dictionaries for example). User-defined objects '
10282n/a 'can support\n'
10283n/a 'subscription by defining a "__getitem__()" method.\n'
10284n/a '\n'
10285n/a 'For built-in objects, there are two types of objects that '
10286n/a 'support\n'
10287n/a 'subscription:\n'
10288n/a '\n'
10289n/a 'If the primary is a mapping, the expression list must '
10290n/a 'evaluate to an\n'
10291n/a 'object whose value is one of the keys of the mapping, and '
10292n/a 'the\n'
10293n/a 'subscription selects the value in the mapping that '
10294n/a 'corresponds to that\n'
10295n/a 'key. (The expression list is a tuple except if it has '
10296n/a 'exactly one\n'
10297n/a 'item.)\n'
10298n/a '\n'
10299n/a 'If the primary is a sequence, the expression (list) must '
10300n/a 'evaluate to\n'
10301n/a 'an integer or a slice (as discussed in the following '
10302n/a 'section).\n'
10303n/a '\n'
10304n/a 'The formal syntax makes no special provision for negative '
10305n/a 'indices in\n'
10306n/a 'sequences; however, built-in sequences all provide a '
10307n/a '"__getitem__()"\n'
10308n/a 'method that interprets negative indices by adding the '
10309n/a 'length of the\n'
10310n/a 'sequence to the index (so that "x[-1]" selects the last '
10311n/a 'item of "x").\n'
10312n/a 'The resulting value must be a nonnegative integer less than '
10313n/a 'the number\n'
10314n/a 'of items in the sequence, and the subscription selects the '
10315n/a 'item whose\n'
10316n/a 'index is that value (counting from zero). Since the support '
10317n/a 'for\n'
10318n/a "negative indices and slicing occurs in the object's "
10319n/a '"__getitem__()"\n'
10320n/a 'method, subclasses overriding this method will need to '
10321n/a 'explicitly add\n'
10322n/a 'that support.\n'
10323n/a '\n'
10324n/a "A string's items are characters. A character is not a "
10325n/a 'separate data\n'
10326n/a 'type but a string of exactly one character.\n',
10327n/a 'truth': '\n'
10328n/a 'Truth Value Testing\n'
10329n/a '*******************\n'
10330n/a '\n'
10331n/a 'Any object can be tested for truth value, for use in an "if" or\n'
10332n/a '"while" condition or as operand of the Boolean operations below. '
10333n/a 'The\n'
10334n/a 'following values are considered false:\n'
10335n/a '\n'
10336n/a '* "None"\n'
10337n/a '\n'
10338n/a '* "False"\n'
10339n/a '\n'
10340n/a '* zero of any numeric type, for example, "0", "0.0", "0j".\n'
10341n/a '\n'
10342n/a '* any empty sequence, for example, "\'\'", "()", "[]".\n'
10343n/a '\n'
10344n/a '* any empty mapping, for example, "{}".\n'
10345n/a '\n'
10346n/a '* instances of user-defined classes, if the class defines a\n'
10347n/a ' "__bool__()" or "__len__()" method, when that method returns the\n'
10348n/a ' integer zero or "bool" value "False". [1]\n'
10349n/a '\n'
10350n/a 'All other values are considered true --- so objects of many types '
10351n/a 'are\n'
10352n/a 'always true.\n'
10353n/a '\n'
10354n/a 'Operations and built-in functions that have a Boolean result '
10355n/a 'always\n'
10356n/a 'return "0" or "False" for false and "1" or "True" for true, unless\n'
10357n/a 'otherwise stated. (Important exception: the Boolean operations '
10358n/a '"or"\n'
10359n/a 'and "and" always return one of their operands.)\n',
10360n/a 'try': '\n'
10361n/a 'The "try" statement\n'
10362n/a '*******************\n'
10363n/a '\n'
10364n/a 'The "try" statement specifies exception handlers and/or cleanup code\n'
10365n/a 'for a group of statements:\n'
10366n/a '\n'
10367n/a ' try_stmt ::= try1_stmt | try2_stmt\n'
10368n/a ' try1_stmt ::= "try" ":" suite\n'
10369n/a ' ("except" [expression ["as" identifier]] ":" '
10370n/a 'suite)+\n'
10371n/a ' ["else" ":" suite]\n'
10372n/a ' ["finally" ":" suite]\n'
10373n/a ' try2_stmt ::= "try" ":" suite\n'
10374n/a ' "finally" ":" suite\n'
10375n/a '\n'
10376n/a 'The "except" clause(s) specify one or more exception handlers. When '
10377n/a 'no\n'
10378n/a 'exception occurs in the "try" clause, no exception handler is\n'
10379n/a 'executed. When an exception occurs in the "try" suite, a search for '
10380n/a 'an\n'
10381n/a 'exception handler is started. This search inspects the except '
10382n/a 'clauses\n'
10383n/a 'in turn until one is found that matches the exception. An '
10384n/a 'expression-\n'
10385n/a 'less except clause, if present, must be last; it matches any\n'
10386n/a 'exception. For an except clause with an expression, that expression\n'
10387n/a 'is evaluated, and the clause matches the exception if the resulting\n'
10388n/a 'object is "compatible" with the exception. An object is compatible\n'
10389n/a 'with an exception if it is the class or a base class of the '
10390n/a 'exception\n'
10391n/a 'object or a tuple containing an item compatible with the exception.\n'
10392n/a '\n'
10393n/a 'If no except clause matches the exception, the search for an '
10394n/a 'exception\n'
10395n/a 'handler continues in the surrounding code and on the invocation '
10396n/a 'stack.\n'
10397n/a '[1]\n'
10398n/a '\n'
10399n/a 'If the evaluation of an expression in the header of an except clause\n'
10400n/a 'raises an exception, the original search for a handler is canceled '
10401n/a 'and\n'
10402n/a 'a search starts for the new exception in the surrounding code and on\n'
10403n/a 'the call stack (it is treated as if the entire "try" statement '
10404n/a 'raised\n'
10405n/a 'the exception).\n'
10406n/a '\n'
10407n/a 'When a matching except clause is found, the exception is assigned to\n'
10408n/a 'the target specified after the "as" keyword in that except clause, '
10409n/a 'if\n'
10410n/a "present, and the except clause's suite is executed. All except\n"
10411n/a 'clauses must have an executable block. When the end of this block '
10412n/a 'is\n'
10413n/a 'reached, execution continues normally after the entire try '
10414n/a 'statement.\n'
10415n/a '(This means that if two nested handlers exist for the same '
10416n/a 'exception,\n'
10417n/a 'and the exception occurs in the try clause of the inner handler, the\n'
10418n/a 'outer handler will not handle the exception.)\n'
10419n/a '\n'
10420n/a 'When an exception has been assigned using "as target", it is cleared\n'
10421n/a 'at the end of the except clause. This is as if\n'
10422n/a '\n'
10423n/a ' except E as N:\n'
10424n/a ' foo\n'
10425n/a '\n'
10426n/a 'was translated to\n'
10427n/a '\n'
10428n/a ' except E as N:\n'
10429n/a ' try:\n'
10430n/a ' foo\n'
10431n/a ' finally:\n'
10432n/a ' del N\n'
10433n/a '\n'
10434n/a 'This means the exception must be assigned to a different name to be\n'
10435n/a 'able to refer to it after the except clause. Exceptions are cleared\n'
10436n/a 'because with the traceback attached to them, they form a reference\n'
10437n/a 'cycle with the stack frame, keeping all locals in that frame alive\n'
10438n/a 'until the next garbage collection occurs.\n'
10439n/a '\n'
10440n/a "Before an except clause's suite is executed, details about the\n"
10441n/a 'exception are stored in the "sys" module and can be accessed via\n'
10442n/a '"sys.exc_info()". "sys.exc_info()" returns a 3-tuple consisting of '
10443n/a 'the\n'
10444n/a 'exception class, the exception instance and a traceback object (see\n'
10445n/a 'section The standard type hierarchy) identifying the point in the\n'
10446n/a 'program where the exception occurred. "sys.exc_info()" values are\n'
10447n/a 'restored to their previous values (before the call) when returning\n'
10448n/a 'from a function that handled an exception.\n'
10449n/a '\n'
10450n/a 'The optional "else" clause is executed if and when control flows off\n'
10451n/a 'the end of the "try" clause. [2] Exceptions in the "else" clause are\n'
10452n/a 'not handled by the preceding "except" clauses.\n'
10453n/a '\n'
10454n/a 'If "finally" is present, it specifies a \'cleanup\' handler. The '
10455n/a '"try"\n'
10456n/a 'clause is executed, including any "except" and "else" clauses. If '
10457n/a 'an\n'
10458n/a 'exception occurs in any of the clauses and is not handled, the\n'
10459n/a 'exception is temporarily saved. The "finally" clause is executed. '
10460n/a 'If\n'
10461n/a 'there is a saved exception it is re-raised at the end of the '
10462n/a '"finally"\n'
10463n/a 'clause. If the "finally" clause raises another exception, the saved\n'
10464n/a 'exception is set as the context of the new exception. If the '
10465n/a '"finally"\n'
10466n/a 'clause executes a "return" or "break" statement, the saved exception\n'
10467n/a 'is discarded:\n'
10468n/a '\n'
10469n/a ' >>> def f():\n'
10470n/a ' ... try:\n'
10471n/a ' ... 1/0\n'
10472n/a ' ... finally:\n'
10473n/a ' ... return 42\n'
10474n/a ' ...\n'
10475n/a ' >>> f()\n'
10476n/a ' 42\n'
10477n/a '\n'
10478n/a 'The exception information is not available to the program during\n'
10479n/a 'execution of the "finally" clause.\n'
10480n/a '\n'
10481n/a 'When a "return", "break" or "continue" statement is executed in the\n'
10482n/a '"try" suite of a "try"..."finally" statement, the "finally" clause '
10483n/a 'is\n'
10484n/a 'also executed \'on the way out.\' A "continue" statement is illegal '
10485n/a 'in\n'
10486n/a 'the "finally" clause. (The reason is a problem with the current\n'
10487n/a 'implementation --- this restriction may be lifted in the future).\n'
10488n/a '\n'
10489n/a 'The return value of a function is determined by the last "return"\n'
10490n/a 'statement executed. Since the "finally" clause always executes, a\n'
10491n/a '"return" statement executed in the "finally" clause will always be '
10492n/a 'the\n'
10493n/a 'last one executed:\n'
10494n/a '\n'
10495n/a ' >>> def foo():\n'
10496n/a ' ... try:\n'
10497n/a " ... return 'try'\n"
10498n/a ' ... finally:\n'
10499n/a " ... return 'finally'\n"
10500n/a ' ...\n'
10501n/a ' >>> foo()\n'
10502n/a " 'finally'\n"
10503n/a '\n'
10504n/a 'Additional information on exceptions can be found in section\n'
10505n/a 'Exceptions, and information on using the "raise" statement to '
10506n/a 'generate\n'
10507n/a 'exceptions may be found in section The raise statement.\n',
10508n/a 'types': '\n'
10509n/a 'The standard type hierarchy\n'
10510n/a '***************************\n'
10511n/a '\n'
10512n/a 'Below is a list of the types that are built into Python. '
10513n/a 'Extension\n'
10514n/a 'modules (written in C, Java, or other languages, depending on the\n'
10515n/a 'implementation) can define additional types. Future versions of\n'
10516n/a 'Python may add types to the type hierarchy (e.g., rational '
10517n/a 'numbers,\n'
10518n/a 'efficiently stored arrays of integers, etc.), although such '
10519n/a 'additions\n'
10520n/a 'will often be provided via the standard library instead.\n'
10521n/a '\n'
10522n/a 'Some of the type descriptions below contain a paragraph listing\n'
10523n/a "'special attributes.' These are attributes that provide access to "
10524n/a 'the\n'
10525n/a 'implementation and are not intended for general use. Their '
10526n/a 'definition\n'
10527n/a 'may change in the future.\n'
10528n/a '\n'
10529n/a 'None\n'
10530n/a ' This type has a single value. There is a single object with '
10531n/a 'this\n'
10532n/a ' value. This object is accessed through the built-in name "None". '
10533n/a 'It\n'
10534n/a ' is used to signify the absence of a value in many situations, '
10535n/a 'e.g.,\n'
10536n/a " it is returned from functions that don't explicitly return\n"
10537n/a ' anything. Its truth value is false.\n'
10538n/a '\n'
10539n/a 'NotImplemented\n'
10540n/a ' This type has a single value. There is a single object with '
10541n/a 'this\n'
10542n/a ' value. This object is accessed through the built-in name\n'
10543n/a ' "NotImplemented". Numeric methods and rich comparison methods\n'
10544n/a ' should return this value if they do not implement the operation '
10545n/a 'for\n'
10546n/a ' the operands provided. (The interpreter will then try the\n'
10547n/a ' reflected operation, or some other fallback, depending on the\n'
10548n/a ' operator.) Its truth value is true.\n'
10549n/a '\n'
10550n/a ' See Implementing the arithmetic operations for more details.\n'
10551n/a '\n'
10552n/a 'Ellipsis\n'
10553n/a ' This type has a single value. There is a single object with '
10554n/a 'this\n'
10555n/a ' value. This object is accessed through the literal "..." or the\n'
10556n/a ' built-in name "Ellipsis". Its truth value is true.\n'
10557n/a '\n'
10558n/a '"numbers.Number"\n'
10559n/a ' These are created by numeric literals and returned as results '
10560n/a 'by\n'
10561n/a ' arithmetic operators and arithmetic built-in functions. '
10562n/a 'Numeric\n'
10563n/a ' objects are immutable; once created their value never changes.\n'
10564n/a ' Python numbers are of course strongly related to mathematical\n'
10565n/a ' numbers, but subject to the limitations of numerical '
10566n/a 'representation\n'
10567n/a ' in computers.\n'
10568n/a '\n'
10569n/a ' Python distinguishes between integers, floating point numbers, '
10570n/a 'and\n'
10571n/a ' complex numbers:\n'
10572n/a '\n'
10573n/a ' "numbers.Integral"\n'
10574n/a ' These represent elements from the mathematical set of '
10575n/a 'integers\n'
10576n/a ' (positive and negative).\n'
10577n/a '\n'
10578n/a ' There are two types of integers:\n'
10579n/a '\n'
10580n/a ' Integers ("int")\n'
10581n/a '\n'
10582n/a ' These represent numbers in an unlimited range, subject to\n'
10583n/a ' available (virtual) memory only. For the purpose of '
10584n/a 'shift\n'
10585n/a ' and mask operations, a binary representation is assumed, '
10586n/a 'and\n'
10587n/a " negative numbers are represented in a variant of 2's\n"
10588n/a ' complement which gives the illusion of an infinite string '
10589n/a 'of\n'
10590n/a ' sign bits extending to the left.\n'
10591n/a '\n'
10592n/a ' Booleans ("bool")\n'
10593n/a ' These represent the truth values False and True. The two\n'
10594n/a ' objects representing the values "False" and "True" are '
10595n/a 'the\n'
10596n/a ' only Boolean objects. The Boolean type is a subtype of '
10597n/a 'the\n'
10598n/a ' integer type, and Boolean values behave like the values 0 '
10599n/a 'and\n'
10600n/a ' 1, respectively, in almost all contexts, the exception '
10601n/a 'being\n'
10602n/a ' that when converted to a string, the strings ""False"" or\n'
10603n/a ' ""True"" are returned, respectively.\n'
10604n/a '\n'
10605n/a ' The rules for integer representation are intended to give '
10606n/a 'the\n'
10607n/a ' most meaningful interpretation of shift and mask operations\n'
10608n/a ' involving negative integers.\n'
10609n/a '\n'
10610n/a ' "numbers.Real" ("float")\n'
10611n/a ' These represent machine-level double precision floating '
10612n/a 'point\n'
10613n/a ' numbers. You are at the mercy of the underlying machine\n'
10614n/a ' architecture (and C or Java implementation) for the accepted\n'
10615n/a ' range and handling of overflow. Python does not support '
10616n/a 'single-\n'
10617n/a ' precision floating point numbers; the savings in processor '
10618n/a 'and\n'
10619n/a ' memory usage that are usually the reason for using these are\n'
10620n/a ' dwarfed by the overhead of using objects in Python, so there '
10621n/a 'is\n'
10622n/a ' no reason to complicate the language with two kinds of '
10623n/a 'floating\n'
10624n/a ' point numbers.\n'
10625n/a '\n'
10626n/a ' "numbers.Complex" ("complex")\n'
10627n/a ' These represent complex numbers as a pair of machine-level\n'
10628n/a ' double precision floating point numbers. The same caveats '
10629n/a 'apply\n'
10630n/a ' as for floating point numbers. The real and imaginary parts '
10631n/a 'of a\n'
10632n/a ' complex number "z" can be retrieved through the read-only\n'
10633n/a ' attributes "z.real" and "z.imag".\n'
10634n/a '\n'
10635n/a 'Sequences\n'
10636n/a ' These represent finite ordered sets indexed by non-negative\n'
10637n/a ' numbers. The built-in function "len()" returns the number of '
10638n/a 'items\n'
10639n/a ' of a sequence. When the length of a sequence is *n*, the index '
10640n/a 'set\n'
10641n/a ' contains the numbers 0, 1, ..., *n*-1. Item *i* of sequence *a* '
10642n/a 'is\n'
10643n/a ' selected by "a[i]".\n'
10644n/a '\n'
10645n/a ' Sequences also support slicing: "a[i:j]" selects all items with\n'
10646n/a ' index *k* such that *i* "<=" *k* "<" *j*. When used as an\n'
10647n/a ' expression, a slice is a sequence of the same type. This '
10648n/a 'implies\n'
10649n/a ' that the index set is renumbered so that it starts at 0.\n'
10650n/a '\n'
10651n/a ' Some sequences also support "extended slicing" with a third '
10652n/a '"step"\n'
10653n/a ' parameter: "a[i:j:k]" selects all items of *a* with index *x* '
10654n/a 'where\n'
10655n/a ' "x = i + n*k", *n* ">=" "0" and *i* "<=" *x* "<" *j*.\n'
10656n/a '\n'
10657n/a ' Sequences are distinguished according to their mutability:\n'
10658n/a '\n'
10659n/a ' Immutable sequences\n'
10660n/a ' An object of an immutable sequence type cannot change once it '
10661n/a 'is\n'
10662n/a ' created. (If the object contains references to other '
10663n/a 'objects,\n'
10664n/a ' these other objects may be mutable and may be changed; '
10665n/a 'however,\n'
10666n/a ' the collection of objects directly referenced by an '
10667n/a 'immutable\n'
10668n/a ' object cannot change.)\n'
10669n/a '\n'
10670n/a ' The following types are immutable sequences:\n'
10671n/a '\n'
10672n/a ' Strings\n'
10673n/a ' A string is a sequence of values that represent Unicode '
10674n/a 'code\n'
10675n/a ' points. All the code points in the range "U+0000 - '
10676n/a 'U+10FFFF"\n'
10677n/a " can be represented in a string. Python doesn't have a "
10678n/a '"char"\n'
10679n/a ' type; instead, every code point in the string is '
10680n/a 'represented\n'
10681n/a ' as a string object with length "1". The built-in '
10682n/a 'function\n'
10683n/a ' "ord()" converts a code point from its string form to an\n'
10684n/a ' integer in the range "0 - 10FFFF"; "chr()" converts an\n'
10685n/a ' integer in the range "0 - 10FFFF" to the corresponding '
10686n/a 'length\n'
10687n/a ' "1" string object. "str.encode()" can be used to convert '
10688n/a 'a\n'
10689n/a ' "str" to "bytes" using the given text encoding, and\n'
10690n/a ' "bytes.decode()" can be used to achieve the opposite.\n'
10691n/a '\n'
10692n/a ' Tuples\n'
10693n/a ' The items of a tuple are arbitrary Python objects. Tuples '
10694n/a 'of\n'
10695n/a ' two or more items are formed by comma-separated lists of\n'
10696n/a " expressions. A tuple of one item (a 'singleton') can be\n"
10697n/a ' formed by affixing a comma to an expression (an expression '
10698n/a 'by\n'
10699n/a ' itself does not create a tuple, since parentheses must be\n'
10700n/a ' usable for grouping of expressions). An empty tuple can '
10701n/a 'be\n'
10702n/a ' formed by an empty pair of parentheses.\n'
10703n/a '\n'
10704n/a ' Bytes\n'
10705n/a ' A bytes object is an immutable array. The items are '
10706n/a '8-bit\n'
10707n/a ' bytes, represented by integers in the range 0 <= x < 256.\n'
10708n/a ' Bytes literals (like "b\'abc\'") and the built-in '
10709n/a 'function\n'
10710n/a ' "bytes()" can be used to construct bytes objects. Also,\n'
10711n/a ' bytes objects can be decoded to strings via the '
10712n/a '"decode()"\n'
10713n/a ' method.\n'
10714n/a '\n'
10715n/a ' Mutable sequences\n'
10716n/a ' Mutable sequences can be changed after they are created. '
10717n/a 'The\n'
10718n/a ' subscription and slicing notations can be used as the target '
10719n/a 'of\n'
10720n/a ' assignment and "del" (delete) statements.\n'
10721n/a '\n'
10722n/a ' There are currently two intrinsic mutable sequence types:\n'
10723n/a '\n'
10724n/a ' Lists\n'
10725n/a ' The items of a list are arbitrary Python objects. Lists '
10726n/a 'are\n'
10727n/a ' formed by placing a comma-separated list of expressions '
10728n/a 'in\n'
10729n/a ' square brackets. (Note that there are no special cases '
10730n/a 'needed\n'
10731n/a ' to form lists of length 0 or 1.)\n'
10732n/a '\n'
10733n/a ' Byte Arrays\n'
10734n/a ' A bytearray object is a mutable array. They are created '
10735n/a 'by\n'
10736n/a ' the built-in "bytearray()" constructor. Aside from being\n'
10737n/a ' mutable (and hence unhashable), byte arrays otherwise '
10738n/a 'provide\n'
10739n/a ' the same interface and functionality as immutable bytes\n'
10740n/a ' objects.\n'
10741n/a '\n'
10742n/a ' The extension module "array" provides an additional example '
10743n/a 'of a\n'
10744n/a ' mutable sequence type, as does the "collections" module.\n'
10745n/a '\n'
10746n/a 'Set types\n'
10747n/a ' These represent unordered, finite sets of unique, immutable\n'
10748n/a ' objects. As such, they cannot be indexed by any subscript. '
10749n/a 'However,\n'
10750n/a ' they can be iterated over, and the built-in function "len()"\n'
10751n/a ' returns the number of items in a set. Common uses for sets are '
10752n/a 'fast\n'
10753n/a ' membership testing, removing duplicates from a sequence, and\n'
10754n/a ' computing mathematical operations such as intersection, union,\n'
10755n/a ' difference, and symmetric difference.\n'
10756n/a '\n'
10757n/a ' For set elements, the same immutability rules apply as for\n'
10758n/a ' dictionary keys. Note that numeric types obey the normal rules '
10759n/a 'for\n'
10760n/a ' numeric comparison: if two numbers compare equal (e.g., "1" and\n'
10761n/a ' "1.0"), only one of them can be contained in a set.\n'
10762n/a '\n'
10763n/a ' There are currently two intrinsic set types:\n'
10764n/a '\n'
10765n/a ' Sets\n'
10766n/a ' These represent a mutable set. They are created by the '
10767n/a 'built-in\n'
10768n/a ' "set()" constructor and can be modified afterwards by '
10769n/a 'several\n'
10770n/a ' methods, such as "add()".\n'
10771n/a '\n'
10772n/a ' Frozen sets\n'
10773n/a ' These represent an immutable set. They are created by the\n'
10774n/a ' built-in "frozenset()" constructor. As a frozenset is '
10775n/a 'immutable\n'
10776n/a ' and *hashable*, it can be used again as an element of '
10777n/a 'another\n'
10778n/a ' set, or as a dictionary key.\n'
10779n/a '\n'
10780n/a 'Mappings\n'
10781n/a ' These represent finite sets of objects indexed by arbitrary '
10782n/a 'index\n'
10783n/a ' sets. The subscript notation "a[k]" selects the item indexed by '
10784n/a '"k"\n'
10785n/a ' from the mapping "a"; this can be used in expressions and as '
10786n/a 'the\n'
10787n/a ' target of assignments or "del" statements. The built-in '
10788n/a 'function\n'
10789n/a ' "len()" returns the number of items in a mapping.\n'
10790n/a '\n'
10791n/a ' There is currently a single intrinsic mapping type:\n'
10792n/a '\n'
10793n/a ' Dictionaries\n'
10794n/a ' These represent finite sets of objects indexed by nearly\n'
10795n/a ' arbitrary values. The only types of values not acceptable '
10796n/a 'as\n'
10797n/a ' keys are values containing lists or dictionaries or other\n'
10798n/a ' mutable types that are compared by value rather than by '
10799n/a 'object\n'
10800n/a ' identity, the reason being that the efficient implementation '
10801n/a 'of\n'
10802n/a " dictionaries requires a key's hash value to remain constant.\n"
10803n/a ' Numeric types used for keys obey the normal rules for '
10804n/a 'numeric\n'
10805n/a ' comparison: if two numbers compare equal (e.g., "1" and '
10806n/a '"1.0")\n'
10807n/a ' then they can be used interchangeably to index the same\n'
10808n/a ' dictionary entry.\n'
10809n/a '\n'
10810n/a ' Dictionaries are mutable; they can be created by the "{...}"\n'
10811n/a ' notation (see section Dictionary displays).\n'
10812n/a '\n'
10813n/a ' The extension modules "dbm.ndbm" and "dbm.gnu" provide\n'
10814n/a ' additional examples of mapping types, as does the '
10815n/a '"collections"\n'
10816n/a ' module.\n'
10817n/a '\n'
10818n/a 'Callable types\n'
10819n/a ' These are the types to which the function call operation (see\n'
10820n/a ' section Calls) can be applied:\n'
10821n/a '\n'
10822n/a ' User-defined functions\n'
10823n/a ' A user-defined function object is created by a function\n'
10824n/a ' definition (see section Function definitions). It should be\n'
10825n/a ' called with an argument list containing the same number of '
10826n/a 'items\n'
10827n/a " as the function's formal parameter list.\n"
10828n/a '\n'
10829n/a ' Special attributes:\n'
10830n/a '\n'
10831n/a ' '
10832n/a '+---------------------------+---------------------------------+-------------+\n'
10833n/a ' | Attribute | Meaning '
10834n/a '| |\n'
10835n/a ' '
10836n/a '+===========================+=================================+=============+\n'
10837n/a ' | "__doc__" | The function\'s '
10838n/a 'documentation | Writable |\n'
10839n/a ' | | string, or "None" if '
10840n/a '| |\n'
10841n/a ' | | unavailable; not inherited by '
10842n/a '| |\n'
10843n/a ' | | subclasses '
10844n/a '| |\n'
10845n/a ' '
10846n/a '+---------------------------+---------------------------------+-------------+\n'
10847n/a ' | "__name__" | The function\'s '
10848n/a 'name | Writable |\n'
10849n/a ' '
10850n/a '+---------------------------+---------------------------------+-------------+\n'
10851n/a ' | "__qualname__" | The function\'s *qualified '
10852n/a 'name* | Writable |\n'
10853n/a ' | | New in version 3.3. '
10854n/a '| |\n'
10855n/a ' '
10856n/a '+---------------------------+---------------------------------+-------------+\n'
10857n/a ' | "__module__" | The name of the module the '
10858n/a '| Writable |\n'
10859n/a ' | | function was defined in, or '
10860n/a '| |\n'
10861n/a ' | | "None" if unavailable. '
10862n/a '| |\n'
10863n/a ' '
10864n/a '+---------------------------+---------------------------------+-------------+\n'
10865n/a ' | "__defaults__" | A tuple containing default '
10866n/a '| Writable |\n'
10867n/a ' | | argument values for those '
10868n/a '| |\n'
10869n/a ' | | arguments that have defaults, '
10870n/a '| |\n'
10871n/a ' | | or "None" if no arguments have '
10872n/a '| |\n'
10873n/a ' | | a default value '
10874n/a '| |\n'
10875n/a ' '
10876n/a '+---------------------------+---------------------------------+-------------+\n'
10877n/a ' | "__code__" | The code object representing '
10878n/a '| Writable |\n'
10879n/a ' | | the compiled function body. '
10880n/a '| |\n'
10881n/a ' '
10882n/a '+---------------------------+---------------------------------+-------------+\n'
10883n/a ' | "__globals__" | A reference to the dictionary '
10884n/a '| Read-only |\n'
10885n/a " | | that holds the function's "
10886n/a '| |\n'
10887n/a ' | | global variables --- the global '
10888n/a '| |\n'
10889n/a ' | | namespace of the module in '
10890n/a '| |\n'
10891n/a ' | | which the function was defined. '
10892n/a '| |\n'
10893n/a ' '
10894n/a '+---------------------------+---------------------------------+-------------+\n'
10895n/a ' | "__dict__" | The namespace supporting '
10896n/a '| Writable |\n'
10897n/a ' | | arbitrary function attributes. '
10898n/a '| |\n'
10899n/a ' '
10900n/a '+---------------------------+---------------------------------+-------------+\n'
10901n/a ' | "__closure__" | "None" or a tuple of cells that '
10902n/a '| Read-only |\n'
10903n/a ' | | contain bindings for the '
10904n/a '| |\n'
10905n/a " | | function's free variables. "
10906n/a '| |\n'
10907n/a ' '
10908n/a '+---------------------------+---------------------------------+-------------+\n'
10909n/a ' | "__annotations__" | A dict containing annotations '
10910n/a '| Writable |\n'
10911n/a ' | | of parameters. The keys of the '
10912n/a '| |\n'
10913n/a ' | | dict are the parameter names, '
10914n/a '| |\n'
10915n/a ' | | and "\'return\'" for the '
10916n/a 'return | |\n'
10917n/a ' | | annotation, if provided. '
10918n/a '| |\n'
10919n/a ' '
10920n/a '+---------------------------+---------------------------------+-------------+\n'
10921n/a ' | "__kwdefaults__" | A dict containing defaults for '
10922n/a '| Writable |\n'
10923n/a ' | | keyword-only parameters. '
10924n/a '| |\n'
10925n/a ' '
10926n/a '+---------------------------+---------------------------------+-------------+\n'
10927n/a '\n'
10928n/a ' Most of the attributes labelled "Writable" check the type of '
10929n/a 'the\n'
10930n/a ' assigned value.\n'
10931n/a '\n'
10932n/a ' Function objects also support getting and setting arbitrary\n'
10933n/a ' attributes, which can be used, for example, to attach '
10934n/a 'metadata\n'
10935n/a ' to functions. Regular attribute dot-notation is used to get '
10936n/a 'and\n'
10937n/a ' set such attributes. *Note that the current implementation '
10938n/a 'only\n'
10939n/a ' supports function attributes on user-defined functions. '
10940n/a 'Function\n'
10941n/a ' attributes on built-in functions may be supported in the\n'
10942n/a ' future.*\n'
10943n/a '\n'
10944n/a " Additional information about a function's definition can be\n"
10945n/a ' retrieved from its code object; see the description of '
10946n/a 'internal\n'
10947n/a ' types below.\n'
10948n/a '\n'
10949n/a ' Instance methods\n'
10950n/a ' An instance method object combines a class, a class instance '
10951n/a 'and\n'
10952n/a ' any callable object (normally a user-defined function).\n'
10953n/a '\n'
10954n/a ' Special read-only attributes: "__self__" is the class '
10955n/a 'instance\n'
10956n/a ' object, "__func__" is the function object; "__doc__" is the\n'
10957n/a ' method\'s documentation (same as "__func__.__doc__"); '
10958n/a '"__name__"\n'
10959n/a ' is the method name (same as "__func__.__name__"); '
10960n/a '"__module__"\n'
10961n/a ' is the name of the module the method was defined in, or '
10962n/a '"None"\n'
10963n/a ' if unavailable.\n'
10964n/a '\n'
10965n/a ' Methods also support accessing (but not setting) the '
10966n/a 'arbitrary\n'
10967n/a ' function attributes on the underlying function object.\n'
10968n/a '\n'
10969n/a ' User-defined method objects may be created when getting an\n'
10970n/a ' attribute of a class (perhaps via an instance of that class), '
10971n/a 'if\n'
10972n/a ' that attribute is a user-defined function object or a class\n'
10973n/a ' method object.\n'
10974n/a '\n'
10975n/a ' When an instance method object is created by retrieving a '
10976n/a 'user-\n'
10977n/a ' defined function object from a class via one of its '
10978n/a 'instances,\n'
10979n/a ' its "__self__" attribute is the instance, and the method '
10980n/a 'object\n'
10981n/a ' is said to be bound. The new method\'s "__func__" attribute '
10982n/a 'is\n'
10983n/a ' the original function object.\n'
10984n/a '\n'
10985n/a ' When a user-defined method object is created by retrieving\n'
10986n/a ' another method object from a class or instance, the behaviour '
10987n/a 'is\n'
10988n/a ' the same as for a function object, except that the '
10989n/a '"__func__"\n'
10990n/a ' attribute of the new instance is not the original method '
10991n/a 'object\n'
10992n/a ' but its "__func__" attribute.\n'
10993n/a '\n'
10994n/a ' When an instance method object is created by retrieving a '
10995n/a 'class\n'
10996n/a ' method object from a class or instance, its "__self__" '
10997n/a 'attribute\n'
10998n/a ' is the class itself, and its "__func__" attribute is the\n'
10999n/a ' function object underlying the class method.\n'
11000n/a '\n'
11001n/a ' When an instance method object is called, the underlying\n'
11002n/a ' function ("__func__") is called, inserting the class '
11003n/a 'instance\n'
11004n/a ' ("__self__") in front of the argument list. For instance, '
11005n/a 'when\n'
11006n/a ' "C" is a class which contains a definition for a function '
11007n/a '"f()",\n'
11008n/a ' and "x" is an instance of "C", calling "x.f(1)" is equivalent '
11009n/a 'to\n'
11010n/a ' calling "C.f(x, 1)".\n'
11011n/a '\n'
11012n/a ' When an instance method object is derived from a class '
11013n/a 'method\n'
11014n/a ' object, the "class instance" stored in "__self__" will '
11015n/a 'actually\n'
11016n/a ' be the class itself, so that calling either "x.f(1)" or '
11017n/a '"C.f(1)"\n'
11018n/a ' is equivalent to calling "f(C,1)" where "f" is the '
11019n/a 'underlying\n'
11020n/a ' function.\n'
11021n/a '\n'
11022n/a ' Note that the transformation from function object to '
11023n/a 'instance\n'
11024n/a ' method object happens each time the attribute is retrieved '
11025n/a 'from\n'
11026n/a ' the instance. In some cases, a fruitful optimization is to\n'
11027n/a ' assign the attribute to a local variable and call that local\n'
11028n/a ' variable. Also notice that this transformation only happens '
11029n/a 'for\n'
11030n/a ' user-defined functions; other callable objects (and all non-\n'
11031n/a ' callable objects) are retrieved without transformation. It '
11032n/a 'is\n'
11033n/a ' also important to note that user-defined functions which are\n'
11034n/a ' attributes of a class instance are not converted to bound\n'
11035n/a ' methods; this *only* happens when the function is an '
11036n/a 'attribute\n'
11037n/a ' of the class.\n'
11038n/a '\n'
11039n/a ' Generator functions\n'
11040n/a ' A function or method which uses the "yield" statement (see\n'
11041n/a ' section The yield statement) is called a *generator '
11042n/a 'function*.\n'
11043n/a ' Such a function, when called, always returns an iterator '
11044n/a 'object\n'
11045n/a ' which can be used to execute the body of the function: '
11046n/a 'calling\n'
11047n/a ' the iterator\'s "iterator.__next__()" method will cause the\n'
11048n/a ' function to execute until it provides a value using the '
11049n/a '"yield"\n'
11050n/a ' statement. When the function executes a "return" statement '
11051n/a 'or\n'
11052n/a ' falls off the end, a "StopIteration" exception is raised and '
11053n/a 'the\n'
11054n/a ' iterator will have reached the end of the set of values to '
11055n/a 'be\n'
11056n/a ' returned.\n'
11057n/a '\n'
11058n/a ' Coroutine functions\n'
11059n/a ' A function or method which is defined using "async def" is\n'
11060n/a ' called a *coroutine function*. Such a function, when '
11061n/a 'called,\n'
11062n/a ' returns a *coroutine* object. It may contain "await"\n'
11063n/a ' expressions, as well as "async with" and "async for" '
11064n/a 'statements.\n'
11065n/a ' See also the Coroutine Objects section.\n'
11066n/a '\n'
11067n/a ' Built-in functions\n'
11068n/a ' A built-in function object is a wrapper around a C function.\n'
11069n/a ' Examples of built-in functions are "len()" and "math.sin()"\n'
11070n/a ' ("math" is a standard built-in module). The number and type '
11071n/a 'of\n'
11072n/a ' the arguments are determined by the C function. Special '
11073n/a 'read-\n'
11074n/a ' only attributes: "__doc__" is the function\'s documentation\n'
11075n/a ' string, or "None" if unavailable; "__name__" is the '
11076n/a "function's\n"
11077n/a ' name; "__self__" is set to "None" (but see the next item);\n'
11078n/a ' "__module__" is the name of the module the function was '
11079n/a 'defined\n'
11080n/a ' in or "None" if unavailable.\n'
11081n/a '\n'
11082n/a ' Built-in methods\n'
11083n/a ' This is really a different disguise of a built-in function, '
11084n/a 'this\n'
11085n/a ' time containing an object passed to the C function as an\n'
11086n/a ' implicit extra argument. An example of a built-in method is\n'
11087n/a ' "alist.append()", assuming *alist* is a list object. In this\n'
11088n/a ' case, the special read-only attribute "__self__" is set to '
11089n/a 'the\n'
11090n/a ' object denoted by *alist*.\n'
11091n/a '\n'
11092n/a ' Classes\n'
11093n/a ' Classes are callable. These objects normally act as '
11094n/a 'factories\n'
11095n/a ' for new instances of themselves, but variations are possible '
11096n/a 'for\n'
11097n/a ' class types that override "__new__()". The arguments of the\n'
11098n/a ' call are passed to "__new__()" and, in the typical case, to\n'
11099n/a ' "__init__()" to initialize the new instance.\n'
11100n/a '\n'
11101n/a ' Class Instances\n'
11102n/a ' Instances of arbitrary classes can be made callable by '
11103n/a 'defining\n'
11104n/a ' a "__call__()" method in their class.\n'
11105n/a '\n'
11106n/a 'Modules\n'
11107n/a ' Modules are a basic organizational unit of Python code, and are\n'
11108n/a ' created by the import system as invoked either by the "import"\n'
11109n/a ' statement (see "import"), or by calling functions such as\n'
11110n/a ' "importlib.import_module()" and built-in "__import__()". A '
11111n/a 'module\n'
11112n/a ' object has a namespace implemented by a dictionary object (this '
11113n/a 'is\n'
11114n/a ' the dictionary referenced by the "__globals__" attribute of\n'
11115n/a ' functions defined in the module). Attribute references are\n'
11116n/a ' translated to lookups in this dictionary, e.g., "m.x" is '
11117n/a 'equivalent\n'
11118n/a ' to "m.__dict__["x"]". A module object does not contain the code\n'
11119n/a " object used to initialize the module (since it isn't needed "
11120n/a 'once\n'
11121n/a ' the initialization is done).\n'
11122n/a '\n'
11123n/a " Attribute assignment updates the module's namespace dictionary,\n"
11124n/a ' e.g., "m.x = 1" is equivalent to "m.__dict__["x"] = 1".\n'
11125n/a '\n'
11126n/a ' Predefined (writable) attributes: "__name__" is the module\'s '
11127n/a 'name;\n'
11128n/a ' "__doc__" is the module\'s documentation string, or "None" if\n'
11129n/a ' unavailable; "__annotations__" (optional) is a dictionary\n'
11130n/a ' containing *variable annotations* collected during module body\n'
11131n/a ' execution; "__file__" is the pathname of the file from which '
11132n/a 'the\n'
11133n/a ' module was loaded, if it was loaded from a file. The "__file__"\n'
11134n/a ' attribute may be missing for certain types of modules, such as '
11135n/a 'C\n'
11136n/a ' modules that are statically linked into the interpreter; for\n'
11137n/a ' extension modules loaded dynamically from a shared library, it '
11138n/a 'is\n'
11139n/a ' the pathname of the shared library file.\n'
11140n/a '\n'
11141n/a ' Special read-only attribute: "__dict__" is the module\'s '
11142n/a 'namespace\n'
11143n/a ' as a dictionary object.\n'
11144n/a '\n'
11145n/a ' **CPython implementation detail:** Because of the way CPython\n'
11146n/a ' clears module dictionaries, the module dictionary will be '
11147n/a 'cleared\n'
11148n/a ' when the module falls out of scope even if the dictionary still '
11149n/a 'has\n'
11150n/a ' live references. To avoid this, copy the dictionary or keep '
11151n/a 'the\n'
11152n/a ' module around while using its dictionary directly.\n'
11153n/a '\n'
11154n/a 'Custom classes\n'
11155n/a ' Custom class types are typically created by class definitions '
11156n/a '(see\n'
11157n/a ' section Class definitions). A class has a namespace implemented '
11158n/a 'by\n'
11159n/a ' a dictionary object. Class attribute references are translated '
11160n/a 'to\n'
11161n/a ' lookups in this dictionary, e.g., "C.x" is translated to\n'
11162n/a ' "C.__dict__["x"]" (although there are a number of hooks which '
11163n/a 'allow\n'
11164n/a ' for other means of locating attributes). When the attribute name '
11165n/a 'is\n'
11166n/a ' not found there, the attribute search continues in the base\n'
11167n/a ' classes. This search of the base classes uses the C3 method\n'
11168n/a ' resolution order which behaves correctly even in the presence '
11169n/a 'of\n'
11170n/a " 'diamond' inheritance structures where there are multiple\n"
11171n/a ' inheritance paths leading back to a common ancestor. Additional\n'
11172n/a ' details on the C3 MRO used by Python can be found in the\n'
11173n/a ' documentation accompanying the 2.3 release at\n'
11174n/a ' https://www.python.org/download/releases/2.3/mro/.\n'
11175n/a '\n'
11176n/a ' When a class attribute reference (for class "C", say) would '
11177n/a 'yield a\n'
11178n/a ' class method object, it is transformed into an instance method\n'
11179n/a ' object whose "__self__" attributes is "C". When it would yield '
11180n/a 'a\n'
11181n/a ' static method object, it is transformed into the object wrapped '
11182n/a 'by\n'
11183n/a ' the static method object. See section Implementing Descriptors '
11184n/a 'for\n'
11185n/a ' another way in which attributes retrieved from a class may '
11186n/a 'differ\n'
11187n/a ' from those actually contained in its "__dict__".\n'
11188n/a '\n'
11189n/a " Class attribute assignments update the class's dictionary, "
11190n/a 'never\n'
11191n/a ' the dictionary of a base class.\n'
11192n/a '\n'
11193n/a ' A class object can be called (see above) to yield a class '
11194n/a 'instance\n'
11195n/a ' (see below).\n'
11196n/a '\n'
11197n/a ' Special attributes: "__name__" is the class name; "__module__" '
11198n/a 'is\n'
11199n/a ' the module name in which the class was defined; "__dict__" is '
11200n/a 'the\n'
11201n/a ' dictionary containing the class\'s namespace; "__bases__" is a '
11202n/a 'tuple\n'
11203n/a ' (possibly empty or a singleton) containing the base classes, in '
11204n/a 'the\n'
11205n/a ' order of their occurrence in the base class list; "__doc__" is '
11206n/a 'the\n'
11207n/a " class's documentation string, or None if undefined;\n"
11208n/a ' "__annotations__" (optional) is a dictionary containing '
11209n/a '*variable\n'
11210n/a ' annotations* collected during class body execution.\n'
11211n/a '\n'
11212n/a 'Class instances\n'
11213n/a ' A class instance is created by calling a class object (see '
11214n/a 'above).\n'
11215n/a ' A class instance has a namespace implemented as a dictionary '
11216n/a 'which\n'
11217n/a ' is the first place in which attribute references are searched.\n'
11218n/a " When an attribute is not found there, and the instance's class "
11219n/a 'has\n'
11220n/a ' an attribute by that name, the search continues with the class\n'
11221n/a ' attributes. If a class attribute is found that is a '
11222n/a 'user-defined\n'
11223n/a ' function object, it is transformed into an instance method '
11224n/a 'object\n'
11225n/a ' whose "__self__" attribute is the instance. Static method and\n'
11226n/a ' class method objects are also transformed; see above under\n'
11227n/a ' "Classes". See section Implementing Descriptors for another way '
11228n/a 'in\n'
11229n/a ' which attributes of a class retrieved via its instances may '
11230n/a 'differ\n'
11231n/a ' from the objects actually stored in the class\'s "__dict__". If '
11232n/a 'no\n'
11233n/a " class attribute is found, and the object's class has a\n"
11234n/a ' "__getattr__()" method, that is called to satisfy the lookup.\n'
11235n/a '\n'
11236n/a " Attribute assignments and deletions update the instance's\n"
11237n/a " dictionary, never a class's dictionary. If the class has a\n"
11238n/a ' "__setattr__()" or "__delattr__()" method, this is called '
11239n/a 'instead\n'
11240n/a ' of updating the instance dictionary directly.\n'
11241n/a '\n'
11242n/a ' Class instances can pretend to be numbers, sequences, or '
11243n/a 'mappings\n'
11244n/a ' if they have methods with certain special names. See section\n'
11245n/a ' Special method names.\n'
11246n/a '\n'
11247n/a ' Special attributes: "__dict__" is the attribute dictionary;\n'
11248n/a ' "__class__" is the instance\'s class.\n'
11249n/a '\n'
11250n/a 'I/O objects (also known as file objects)\n'
11251n/a ' A *file object* represents an open file. Various shortcuts are\n'
11252n/a ' available to create file objects: the "open()" built-in '
11253n/a 'function,\n'
11254n/a ' and also "os.popen()", "os.fdopen()", and the "makefile()" '
11255n/a 'method\n'
11256n/a ' of socket objects (and perhaps by other functions or methods\n'
11257n/a ' provided by extension modules).\n'
11258n/a '\n'
11259n/a ' The objects "sys.stdin", "sys.stdout" and "sys.stderr" are\n'
11260n/a " initialized to file objects corresponding to the interpreter's\n"
11261n/a ' standard input, output and error streams; they are all open in '
11262n/a 'text\n'
11263n/a ' mode and therefore follow the interface defined by the\n'
11264n/a ' "io.TextIOBase" abstract class.\n'
11265n/a '\n'
11266n/a 'Internal types\n'
11267n/a ' A few types used internally by the interpreter are exposed to '
11268n/a 'the\n'
11269n/a ' user. Their definitions may change with future versions of the\n'
11270n/a ' interpreter, but they are mentioned here for completeness.\n'
11271n/a '\n'
11272n/a ' Code objects\n'
11273n/a ' Code objects represent *byte-compiled* executable Python '
11274n/a 'code,\n'
11275n/a ' or *bytecode*. The difference between a code object and a\n'
11276n/a ' function object is that the function object contains an '
11277n/a 'explicit\n'
11278n/a " reference to the function's globals (the module in which it "
11279n/a 'was\n'
11280n/a ' defined), while a code object contains no context; also the\n'
11281n/a ' default argument values are stored in the function object, '
11282n/a 'not\n'
11283n/a ' in the code object (because they represent values calculated '
11284n/a 'at\n'
11285n/a ' run-time). Unlike function objects, code objects are '
11286n/a 'immutable\n'
11287n/a ' and contain no references (directly or indirectly) to '
11288n/a 'mutable\n'
11289n/a ' objects.\n'
11290n/a '\n'
11291n/a ' Special read-only attributes: "co_name" gives the function '
11292n/a 'name;\n'
11293n/a ' "co_argcount" is the number of positional arguments '
11294n/a '(including\n'
11295n/a ' arguments with default values); "co_nlocals" is the number '
11296n/a 'of\n'
11297n/a ' local variables used by the function (including arguments);\n'
11298n/a ' "co_varnames" is a tuple containing the names of the local\n'
11299n/a ' variables (starting with the argument names); "co_cellvars" '
11300n/a 'is a\n'
11301n/a ' tuple containing the names of local variables that are\n'
11302n/a ' referenced by nested functions; "co_freevars" is a tuple\n'
11303n/a ' containing the names of free variables; "co_code" is a '
11304n/a 'string\n'
11305n/a ' representing the sequence of bytecode instructions; '
11306n/a '"co_consts"\n'
11307n/a ' is a tuple containing the literals used by the bytecode;\n'
11308n/a ' "co_names" is a tuple containing the names used by the '
11309n/a 'bytecode;\n'
11310n/a ' "co_filename" is the filename from which the code was '
11311n/a 'compiled;\n'
11312n/a ' "co_firstlineno" is the first line number of the function;\n'
11313n/a ' "co_lnotab" is a string encoding the mapping from bytecode\n'
11314n/a ' offsets to line numbers (for details see the source code of '
11315n/a 'the\n'
11316n/a ' interpreter); "co_stacksize" is the required stack size\n'
11317n/a ' (including local variables); "co_flags" is an integer '
11318n/a 'encoding a\n'
11319n/a ' number of flags for the interpreter.\n'
11320n/a '\n'
11321n/a ' The following flag bits are defined for "co_flags": bit '
11322n/a '"0x04"\n'
11323n/a ' is set if the function uses the "*arguments" syntax to accept '
11324n/a 'an\n'
11325n/a ' arbitrary number of positional arguments; bit "0x08" is set '
11326n/a 'if\n'
11327n/a ' the function uses the "**keywords" syntax to accept '
11328n/a 'arbitrary\n'
11329n/a ' keyword arguments; bit "0x20" is set if the function is a\n'
11330n/a ' generator.\n'
11331n/a '\n'
11332n/a ' Future feature declarations ("from __future__ import '
11333n/a 'division")\n'
11334n/a ' also use bits in "co_flags" to indicate whether a code '
11335n/a 'object\n'
11336n/a ' was compiled with a particular feature enabled: bit "0x2000" '
11337n/a 'is\n'
11338n/a ' set if the function was compiled with future division '
11339n/a 'enabled;\n'
11340n/a ' bits "0x10" and "0x1000" were used in earlier versions of\n'
11341n/a ' Python.\n'
11342n/a '\n'
11343n/a ' Other bits in "co_flags" are reserved for internal use.\n'
11344n/a '\n'
11345n/a ' If a code object represents a function, the first item in\n'
11346n/a ' "co_consts" is the documentation string of the function, or\n'
11347n/a ' "None" if undefined.\n'
11348n/a '\n'
11349n/a ' Frame objects\n'
11350n/a ' Frame objects represent execution frames. They may occur in\n'
11351n/a ' traceback objects (see below).\n'
11352n/a '\n'
11353n/a ' Special read-only attributes: "f_back" is to the previous '
11354n/a 'stack\n'
11355n/a ' frame (towards the caller), or "None" if this is the bottom\n'
11356n/a ' stack frame; "f_code" is the code object being executed in '
11357n/a 'this\n'
11358n/a ' frame; "f_locals" is the dictionary used to look up local\n'
11359n/a ' variables; "f_globals" is used for global variables;\n'
11360n/a ' "f_builtins" is used for built-in (intrinsic) names; '
11361n/a '"f_lasti"\n'
11362n/a ' gives the precise instruction (this is an index into the\n'
11363n/a ' bytecode string of the code object).\n'
11364n/a '\n'
11365n/a ' Special writable attributes: "f_trace", if not "None", is a\n'
11366n/a ' function called at the start of each source code line (this '
11367n/a 'is\n'
11368n/a ' used by the debugger); "f_lineno" is the current line number '
11369n/a 'of\n'
11370n/a ' the frame --- writing to this from within a trace function '
11371n/a 'jumps\n'
11372n/a ' to the given line (only for the bottom-most frame). A '
11373n/a 'debugger\n'
11374n/a ' can implement a Jump command (aka Set Next Statement) by '
11375n/a 'writing\n'
11376n/a ' to f_lineno.\n'
11377n/a '\n'
11378n/a ' Frame objects support one method:\n'
11379n/a '\n'
11380n/a ' frame.clear()\n'
11381n/a '\n'
11382n/a ' This method clears all references to local variables held '
11383n/a 'by\n'
11384n/a ' the frame. Also, if the frame belonged to a generator, '
11385n/a 'the\n'
11386n/a ' generator is finalized. This helps break reference '
11387n/a 'cycles\n'
11388n/a ' involving frame objects (for example when catching an\n'
11389n/a ' exception and storing its traceback for later use).\n'
11390n/a '\n'
11391n/a ' "RuntimeError" is raised if the frame is currently '
11392n/a 'executing.\n'
11393n/a '\n'
11394n/a ' New in version 3.4.\n'
11395n/a '\n'
11396n/a ' Traceback objects\n'
11397n/a ' Traceback objects represent a stack trace of an exception. '
11398n/a 'A\n'
11399n/a ' traceback object is created when an exception occurs. When '
11400n/a 'the\n'
11401n/a ' search for an exception handler unwinds the execution stack, '
11402n/a 'at\n'
11403n/a ' each unwound level a traceback object is inserted in front '
11404n/a 'of\n'
11405n/a ' the current traceback. When an exception handler is '
11406n/a 'entered,\n'
11407n/a ' the stack trace is made available to the program. (See '
11408n/a 'section\n'
11409n/a ' The try statement.) It is accessible as the third item of '
11410n/a 'the\n'
11411n/a ' tuple returned by "sys.exc_info()". When the program contains '
11412n/a 'no\n'
11413n/a ' suitable handler, the stack trace is written (nicely '
11414n/a 'formatted)\n'
11415n/a ' to the standard error stream; if the interpreter is '
11416n/a 'interactive,\n'
11417n/a ' it is also made available to the user as '
11418n/a '"sys.last_traceback".\n'
11419n/a '\n'
11420n/a ' Special read-only attributes: "tb_next" is the next level in '
11421n/a 'the\n'
11422n/a ' stack trace (towards the frame where the exception occurred), '
11423n/a 'or\n'
11424n/a ' "None" if there is no next level; "tb_frame" points to the\n'
11425n/a ' execution frame of the current level; "tb_lineno" gives the '
11426n/a 'line\n'
11427n/a ' number where the exception occurred; "tb_lasti" indicates '
11428n/a 'the\n'
11429n/a ' precise instruction. The line number and last instruction '
11430n/a 'in\n'
11431n/a ' the traceback may differ from the line number of its frame\n'
11432n/a ' object if the exception occurred in a "try" statement with '
11433n/a 'no\n'
11434n/a ' matching except clause or with a finally clause.\n'
11435n/a '\n'
11436n/a ' Slice objects\n'
11437n/a ' Slice objects are used to represent slices for '
11438n/a '"__getitem__()"\n'
11439n/a ' methods. They are also created by the built-in "slice()"\n'
11440n/a ' function.\n'
11441n/a '\n'
11442n/a ' Special read-only attributes: "start" is the lower bound; '
11443n/a '"stop"\n'
11444n/a ' is the upper bound; "step" is the step value; each is "None" '
11445n/a 'if\n'
11446n/a ' omitted. These attributes can have any type.\n'
11447n/a '\n'
11448n/a ' Slice objects support one method:\n'
11449n/a '\n'
11450n/a ' slice.indices(self, length)\n'
11451n/a '\n'
11452n/a ' This method takes a single integer argument *length* and\n'
11453n/a ' computes information about the slice that the slice '
11454n/a 'object\n'
11455n/a ' would describe if applied to a sequence of *length* '
11456n/a 'items.\n'
11457n/a ' It returns a tuple of three integers; respectively these '
11458n/a 'are\n'
11459n/a ' the *start* and *stop* indices and the *step* or stride\n'
11460n/a ' length of the slice. Missing or out-of-bounds indices are\n'
11461n/a ' handled in a manner consistent with regular slices.\n'
11462n/a '\n'
11463n/a ' Static method objects\n'
11464n/a ' Static method objects provide a way of defeating the\n'
11465n/a ' transformation of function objects to method objects '
11466n/a 'described\n'
11467n/a ' above. A static method object is a wrapper around any other\n'
11468n/a ' object, usually a user-defined method object. When a static\n'
11469n/a ' method object is retrieved from a class or a class instance, '
11470n/a 'the\n'
11471n/a ' object actually returned is the wrapped object, which is not\n'
11472n/a ' subject to any further transformation. Static method objects '
11473n/a 'are\n'
11474n/a ' not themselves callable, although the objects they wrap '
11475n/a 'usually\n'
11476n/a ' are. Static method objects are created by the built-in\n'
11477n/a ' "staticmethod()" constructor.\n'
11478n/a '\n'
11479n/a ' Class method objects\n'
11480n/a ' A class method object, like a static method object, is a '
11481n/a 'wrapper\n'
11482n/a ' around another object that alters the way in which that '
11483n/a 'object\n'
11484n/a ' is retrieved from classes and class instances. The behaviour '
11485n/a 'of\n'
11486n/a ' class method objects upon such retrieval is described above,\n'
11487n/a ' under "User-defined methods". Class method objects are '
11488n/a 'created\n'
11489n/a ' by the built-in "classmethod()" constructor.\n',
11490n/a 'typesfunctions': '\n'
11491n/a 'Functions\n'
11492n/a '*********\n'
11493n/a '\n'
11494n/a 'Function objects are created by function definitions. The '
11495n/a 'only\n'
11496n/a 'operation on a function object is to call it: '
11497n/a '"func(argument-list)".\n'
11498n/a '\n'
11499n/a 'There are really two flavors of function objects: built-in '
11500n/a 'functions\n'
11501n/a 'and user-defined functions. Both support the same '
11502n/a 'operation (to call\n'
11503n/a 'the function), but the implementation is different, hence '
11504n/a 'the\n'
11505n/a 'different object types.\n'
11506n/a '\n'
11507n/a 'See Function definitions for more information.\n',
11508n/a 'typesmapping': '\n'
11509n/a 'Mapping Types --- "dict"\n'
11510n/a '************************\n'
11511n/a '\n'
11512n/a 'A *mapping* object maps *hashable* values to arbitrary '
11513n/a 'objects.\n'
11514n/a 'Mappings are mutable objects. There is currently only one '
11515n/a 'standard\n'
11516n/a 'mapping type, the *dictionary*. (For other containers see '
11517n/a 'the built-\n'
11518n/a 'in "list", "set", and "tuple" classes, and the "collections" '
11519n/a 'module.)\n'
11520n/a '\n'
11521n/a "A dictionary's keys are *almost* arbitrary values. Values "
11522n/a 'that are\n'
11523n/a 'not *hashable*, that is, values containing lists, '
11524n/a 'dictionaries or\n'
11525n/a 'other mutable types (that are compared by value rather than '
11526n/a 'by object\n'
11527n/a 'identity) may not be used as keys. Numeric types used for '
11528n/a 'keys obey\n'
11529n/a 'the normal rules for numeric comparison: if two numbers '
11530n/a 'compare equal\n'
11531n/a '(such as "1" and "1.0") then they can be used '
11532n/a 'interchangeably to index\n'
11533n/a 'the same dictionary entry. (Note however, that since '
11534n/a 'computers store\n'
11535n/a 'floating-point numbers as approximations it is usually '
11536n/a 'unwise to use\n'
11537n/a 'them as dictionary keys.)\n'
11538n/a '\n'
11539n/a 'Dictionaries can be created by placing a comma-separated '
11540n/a 'list of "key:\n'
11541n/a 'value" pairs within braces, for example: "{\'jack\': 4098, '
11542n/a "'sjoerd':\n"
11543n/a '4127}" or "{4098: \'jack\', 4127: \'sjoerd\'}", or by the '
11544n/a '"dict"\n'
11545n/a 'constructor.\n'
11546n/a '\n'
11547n/a 'class dict(**kwarg)\n'
11548n/a 'class dict(mapping, **kwarg)\n'
11549n/a 'class dict(iterable, **kwarg)\n'
11550n/a '\n'
11551n/a ' Return a new dictionary initialized from an optional '
11552n/a 'positional\n'
11553n/a ' argument and a possibly empty set of keyword arguments.\n'
11554n/a '\n'
11555n/a ' If no positional argument is given, an empty dictionary '
11556n/a 'is created.\n'
11557n/a ' If a positional argument is given and it is a mapping '
11558n/a 'object, a\n'
11559n/a ' dictionary is created with the same key-value pairs as '
11560n/a 'the mapping\n'
11561n/a ' object. Otherwise, the positional argument must be an '
11562n/a '*iterable*\n'
11563n/a ' object. Each item in the iterable must itself be an '
11564n/a 'iterable with\n'
11565n/a ' exactly two objects. The first object of each item '
11566n/a 'becomes a key\n'
11567n/a ' in the new dictionary, and the second object the '
11568n/a 'corresponding\n'
11569n/a ' value. If a key occurs more than once, the last value '
11570n/a 'for that key\n'
11571n/a ' becomes the corresponding value in the new dictionary.\n'
11572n/a '\n'
11573n/a ' If keyword arguments are given, the keyword arguments and '
11574n/a 'their\n'
11575n/a ' values are added to the dictionary created from the '
11576n/a 'positional\n'
11577n/a ' argument. If a key being added is already present, the '
11578n/a 'value from\n'
11579n/a ' the keyword argument replaces the value from the '
11580n/a 'positional\n'
11581n/a ' argument.\n'
11582n/a '\n'
11583n/a ' To illustrate, the following examples all return a '
11584n/a 'dictionary equal\n'
11585n/a ' to "{"one": 1, "two": 2, "three": 3}":\n'
11586n/a '\n'
11587n/a ' >>> a = dict(one=1, two=2, three=3)\n'
11588n/a " >>> b = {'one': 1, 'two': 2, 'three': 3}\n"
11589n/a " >>> c = dict(zip(['one', 'two', 'three'], [1, 2, 3]))\n"
11590n/a " >>> d = dict([('two', 2), ('one', 1), ('three', 3)])\n"
11591n/a " >>> e = dict({'three': 3, 'one': 1, 'two': 2})\n"
11592n/a ' >>> a == b == c == d == e\n'
11593n/a ' True\n'
11594n/a '\n'
11595n/a ' Providing keyword arguments as in the first example only '
11596n/a 'works for\n'
11597n/a ' keys that are valid Python identifiers. Otherwise, any '
11598n/a 'valid keys\n'
11599n/a ' can be used.\n'
11600n/a '\n'
11601n/a ' These are the operations that dictionaries support (and '
11602n/a 'therefore,\n'
11603n/a ' custom mapping types should support too):\n'
11604n/a '\n'
11605n/a ' len(d)\n'
11606n/a '\n'
11607n/a ' Return the number of items in the dictionary *d*.\n'
11608n/a '\n'
11609n/a ' d[key]\n'
11610n/a '\n'
11611n/a ' Return the item of *d* with key *key*. Raises a '
11612n/a '"KeyError" if\n'
11613n/a ' *key* is not in the map.\n'
11614n/a '\n'
11615n/a ' If a subclass of dict defines a method "__missing__()" '
11616n/a 'and *key*\n'
11617n/a ' is not present, the "d[key]" operation calls that '
11618n/a 'method with\n'
11619n/a ' the key *key* as argument. The "d[key]" operation '
11620n/a 'then returns\n'
11621n/a ' or raises whatever is returned or raised by the\n'
11622n/a ' "__missing__(key)" call. No other operations or '
11623n/a 'methods invoke\n'
11624n/a ' "__missing__()". If "__missing__()" is not defined, '
11625n/a '"KeyError"\n'
11626n/a ' is raised. "__missing__()" must be a method; it cannot '
11627n/a 'be an\n'
11628n/a ' instance variable:\n'
11629n/a '\n'
11630n/a ' >>> class Counter(dict):\n'
11631n/a ' ... def __missing__(self, key):\n'
11632n/a ' ... return 0\n'
11633n/a ' >>> c = Counter()\n'
11634n/a " >>> c['red']\n"
11635n/a ' 0\n'
11636n/a " >>> c['red'] += 1\n"
11637n/a " >>> c['red']\n"
11638n/a ' 1\n'
11639n/a '\n'
11640n/a ' The example above shows part of the implementation of\n'
11641n/a ' "collections.Counter". A different "__missing__" '
11642n/a 'method is used\n'
11643n/a ' by "collections.defaultdict".\n'
11644n/a '\n'
11645n/a ' d[key] = value\n'
11646n/a '\n'
11647n/a ' Set "d[key]" to *value*.\n'
11648n/a '\n'
11649n/a ' del d[key]\n'
11650n/a '\n'
11651n/a ' Remove "d[key]" from *d*. Raises a "KeyError" if '
11652n/a '*key* is not\n'
11653n/a ' in the map.\n'
11654n/a '\n'
11655n/a ' key in d\n'
11656n/a '\n'
11657n/a ' Return "True" if *d* has a key *key*, else "False".\n'
11658n/a '\n'
11659n/a ' key not in d\n'
11660n/a '\n'
11661n/a ' Equivalent to "not key in d".\n'
11662n/a '\n'
11663n/a ' iter(d)\n'
11664n/a '\n'
11665n/a ' Return an iterator over the keys of the dictionary. '
11666n/a 'This is a\n'
11667n/a ' shortcut for "iter(d.keys())".\n'
11668n/a '\n'
11669n/a ' clear()\n'
11670n/a '\n'
11671n/a ' Remove all items from the dictionary.\n'
11672n/a '\n'
11673n/a ' copy()\n'
11674n/a '\n'
11675n/a ' Return a shallow copy of the dictionary.\n'
11676n/a '\n'
11677n/a ' classmethod fromkeys(seq[, value])\n'
11678n/a '\n'
11679n/a ' Create a new dictionary with keys from *seq* and '
11680n/a 'values set to\n'
11681n/a ' *value*.\n'
11682n/a '\n'
11683n/a ' "fromkeys()" is a class method that returns a new '
11684n/a 'dictionary.\n'
11685n/a ' *value* defaults to "None".\n'
11686n/a '\n'
11687n/a ' get(key[, default])\n'
11688n/a '\n'
11689n/a ' Return the value for *key* if *key* is in the '
11690n/a 'dictionary, else\n'
11691n/a ' *default*. If *default* is not given, it defaults to '
11692n/a '"None", so\n'
11693n/a ' that this method never raises a "KeyError".\n'
11694n/a '\n'
11695n/a ' items()\n'
11696n/a '\n'
11697n/a ' Return a new view of the dictionary\'s items ("(key, '
11698n/a 'value)"\n'
11699n/a ' pairs). See the documentation of view objects.\n'
11700n/a '\n'
11701n/a ' keys()\n'
11702n/a '\n'
11703n/a " Return a new view of the dictionary's keys. See the\n"
11704n/a ' documentation of view objects.\n'
11705n/a '\n'
11706n/a ' pop(key[, default])\n'
11707n/a '\n'
11708n/a ' If *key* is in the dictionary, remove it and return '
11709n/a 'its value,\n'
11710n/a ' else return *default*. If *default* is not given and '
11711n/a '*key* is\n'
11712n/a ' not in the dictionary, a "KeyError" is raised.\n'
11713n/a '\n'
11714n/a ' popitem()\n'
11715n/a '\n'
11716n/a ' Remove and return an arbitrary "(key, value)" pair '
11717n/a 'from the\n'
11718n/a ' dictionary.\n'
11719n/a '\n'
11720n/a ' "popitem()" is useful to destructively iterate over a\n'
11721n/a ' dictionary, as often used in set algorithms. If the '
11722n/a 'dictionary\n'
11723n/a ' is empty, calling "popitem()" raises a "KeyError".\n'
11724n/a '\n'
11725n/a ' setdefault(key[, default])\n'
11726n/a '\n'
11727n/a ' If *key* is in the dictionary, return its value. If '
11728n/a 'not, insert\n'
11729n/a ' *key* with a value of *default* and return *default*. '
11730n/a '*default*\n'
11731n/a ' defaults to "None".\n'
11732n/a '\n'
11733n/a ' update([other])\n'
11734n/a '\n'
11735n/a ' Update the dictionary with the key/value pairs from '
11736n/a '*other*,\n'
11737n/a ' overwriting existing keys. Return "None".\n'
11738n/a '\n'
11739n/a ' "update()" accepts either another dictionary object or '
11740n/a 'an\n'
11741n/a ' iterable of key/value pairs (as tuples or other '
11742n/a 'iterables of\n'
11743n/a ' length two). If keyword arguments are specified, the '
11744n/a 'dictionary\n'
11745n/a ' is then updated with those key/value pairs: '
11746n/a '"d.update(red=1,\n'
11747n/a ' blue=2)".\n'
11748n/a '\n'
11749n/a ' values()\n'
11750n/a '\n'
11751n/a " Return a new view of the dictionary's values. See "
11752n/a 'the\n'
11753n/a ' documentation of view objects.\n'
11754n/a '\n'
11755n/a ' Dictionaries compare equal if and only if they have the '
11756n/a 'same "(key,\n'
11757n/a ' value)" pairs. Order comparisons (\'<\', \'<=\', \'>=\', '
11758n/a "'>') raise\n"
11759n/a ' "TypeError".\n'
11760n/a '\n'
11761n/a 'See also: "types.MappingProxyType" can be used to create a '
11762n/a 'read-only\n'
11763n/a ' view of a "dict".\n'
11764n/a '\n'
11765n/a '\n'
11766n/a 'Dictionary view objects\n'
11767n/a '=======================\n'
11768n/a '\n'
11769n/a 'The objects returned by "dict.keys()", "dict.values()" and\n'
11770n/a '"dict.items()" are *view objects*. They provide a dynamic '
11771n/a 'view on the\n'
11772n/a "dictionary's entries, which means that when the dictionary "
11773n/a 'changes,\n'
11774n/a 'the view reflects these changes.\n'
11775n/a '\n'
11776n/a 'Dictionary views can be iterated over to yield their '
11777n/a 'respective data,\n'
11778n/a 'and support membership tests:\n'
11779n/a '\n'
11780n/a 'len(dictview)\n'
11781n/a '\n'
11782n/a ' Return the number of entries in the dictionary.\n'
11783n/a '\n'
11784n/a 'iter(dictview)\n'
11785n/a '\n'
11786n/a ' Return an iterator over the keys, values or items '
11787n/a '(represented as\n'
11788n/a ' tuples of "(key, value)") in the dictionary.\n'
11789n/a '\n'
11790n/a ' Keys and values are iterated over in an arbitrary order '
11791n/a 'which is\n'
11792n/a ' non-random, varies across Python implementations, and '
11793n/a 'depends on\n'
11794n/a " the dictionary's history of insertions and deletions. If "
11795n/a 'keys,\n'
11796n/a ' values and items views are iterated over with no '
11797n/a 'intervening\n'
11798n/a ' modifications to the dictionary, the order of items will '
11799n/a 'directly\n'
11800n/a ' correspond. This allows the creation of "(value, key)" '
11801n/a 'pairs using\n'
11802n/a ' "zip()": "pairs = zip(d.values(), d.keys())". Another '
11803n/a 'way to\n'
11804n/a ' create the same list is "pairs = [(v, k) for (k, v) in '
11805n/a 'd.items()]".\n'
11806n/a '\n'
11807n/a ' Iterating views while adding or deleting entries in the '
11808n/a 'dictionary\n'
11809n/a ' may raise a "RuntimeError" or fail to iterate over all '
11810n/a 'entries.\n'
11811n/a '\n'
11812n/a 'x in dictview\n'
11813n/a '\n'
11814n/a ' Return "True" if *x* is in the underlying dictionary\'s '
11815n/a 'keys, values\n'
11816n/a ' or items (in the latter case, *x* should be a "(key, '
11817n/a 'value)"\n'
11818n/a ' tuple).\n'
11819n/a '\n'
11820n/a 'Keys views are set-like since their entries are unique and '
11821n/a 'hashable.\n'
11822n/a 'If all values are hashable, so that "(key, value)" pairs are '
11823n/a 'unique\n'
11824n/a 'and hashable, then the items view is also set-like. (Values '
11825n/a 'views are\n'
11826n/a 'not treated as set-like since the entries are generally not '
11827n/a 'unique.)\n'
11828n/a 'For set-like views, all of the operations defined for the '
11829n/a 'abstract\n'
11830n/a 'base class "collections.abc.Set" are available (for example, '
11831n/a '"==",\n'
11832n/a '"<", or "^").\n'
11833n/a '\n'
11834n/a 'An example of dictionary view usage:\n'
11835n/a '\n'
11836n/a " >>> dishes = {'eggs': 2, 'sausage': 1, 'bacon': 1, "
11837n/a "'spam': 500}\n"
11838n/a ' >>> keys = dishes.keys()\n'
11839n/a ' >>> values = dishes.values()\n'
11840n/a '\n'
11841n/a ' >>> # iteration\n'
11842n/a ' >>> n = 0\n'
11843n/a ' >>> for val in values:\n'
11844n/a ' ... n += val\n'
11845n/a ' >>> print(n)\n'
11846n/a ' 504\n'
11847n/a '\n'
11848n/a ' >>> # keys and values are iterated over in the same '
11849n/a 'order\n'
11850n/a ' >>> list(keys)\n'
11851n/a " ['eggs', 'bacon', 'sausage', 'spam']\n"
11852n/a ' >>> list(values)\n'
11853n/a ' [2, 1, 1, 500]\n'
11854n/a '\n'
11855n/a ' >>> # view objects are dynamic and reflect dict changes\n'
11856n/a " >>> del dishes['eggs']\n"
11857n/a " >>> del dishes['sausage']\n"
11858n/a ' >>> list(keys)\n'
11859n/a " ['spam', 'bacon']\n"
11860n/a '\n'
11861n/a ' >>> # set operations\n'
11862n/a " >>> keys & {'eggs', 'bacon', 'salad'}\n"
11863n/a " {'bacon'}\n"
11864n/a " >>> keys ^ {'sausage', 'juice'}\n"
11865n/a " {'juice', 'sausage', 'bacon', 'spam'}\n",
11866n/a 'typesmethods': '\n'
11867n/a 'Methods\n'
11868n/a '*******\n'
11869n/a '\n'
11870n/a 'Methods are functions that are called using the attribute '
11871n/a 'notation.\n'
11872n/a 'There are two flavors: built-in methods (such as "append()" '
11873n/a 'on lists)\n'
11874n/a 'and class instance methods. Built-in methods are described '
11875n/a 'with the\n'
11876n/a 'types that support them.\n'
11877n/a '\n'
11878n/a 'If you access a method (a function defined in a class '
11879n/a 'namespace)\n'
11880n/a 'through an instance, you get a special object: a *bound '
11881n/a 'method* (also\n'
11882n/a 'called *instance method*) object. When called, it will add '
11883n/a 'the "self"\n'
11884n/a 'argument to the argument list. Bound methods have two '
11885n/a 'special read-\n'
11886n/a 'only attributes: "m.__self__" is the object on which the '
11887n/a 'method\n'
11888n/a 'operates, and "m.__func__" is the function implementing the '
11889n/a 'method.\n'
11890n/a 'Calling "m(arg-1, arg-2, ..., arg-n)" is completely '
11891n/a 'equivalent to\n'
11892n/a 'calling "m.__func__(m.__self__, arg-1, arg-2, ..., arg-n)".\n'
11893n/a '\n'
11894n/a 'Like function objects, bound method objects support getting '
11895n/a 'arbitrary\n'
11896n/a 'attributes. However, since method attributes are actually '
11897n/a 'stored on\n'
11898n/a 'the underlying function object ("meth.__func__"), setting '
11899n/a 'method\n'
11900n/a 'attributes on bound methods is disallowed. Attempting to '
11901n/a 'set an\n'
11902n/a 'attribute on a method results in an "AttributeError" being '
11903n/a 'raised. In\n'
11904n/a 'order to set a method attribute, you need to explicitly set '
11905n/a 'it on the\n'
11906n/a 'underlying function object:\n'
11907n/a '\n'
11908n/a ' >>> class C:\n'
11909n/a ' ... def method(self):\n'
11910n/a ' ... pass\n'
11911n/a ' ...\n'
11912n/a ' >>> c = C()\n'
11913n/a " >>> c.method.whoami = 'my name is method' # can't set on "
11914n/a 'the method\n'
11915n/a ' Traceback (most recent call last):\n'
11916n/a ' File "<stdin>", line 1, in <module>\n'
11917n/a " AttributeError: 'method' object has no attribute "
11918n/a "'whoami'\n"
11919n/a " >>> c.method.__func__.whoami = 'my name is method'\n"
11920n/a ' >>> c.method.whoami\n'
11921n/a " 'my name is method'\n"
11922n/a '\n'
11923n/a 'See The standard type hierarchy for more information.\n',
11924n/a 'typesmodules': '\n'
11925n/a 'Modules\n'
11926n/a '*******\n'
11927n/a '\n'
11928n/a 'The only special operation on a module is attribute access: '
11929n/a '"m.name",\n'
11930n/a 'where *m* is a module and *name* accesses a name defined in '
11931n/a "*m*'s\n"
11932n/a 'symbol table. Module attributes can be assigned to. (Note '
11933n/a 'that the\n'
11934n/a '"import" statement is not, strictly speaking, an operation '
11935n/a 'on a module\n'
11936n/a 'object; "import foo" does not require a module object named '
11937n/a '*foo* to\n'
11938n/a 'exist, rather it requires an (external) *definition* for a '
11939n/a 'module\n'
11940n/a 'named *foo* somewhere.)\n'
11941n/a '\n'
11942n/a 'A special attribute of every module is "__dict__". This is '
11943n/a 'the\n'
11944n/a "dictionary containing the module's symbol table. Modifying "
11945n/a 'this\n'
11946n/a "dictionary will actually change the module's symbol table, "
11947n/a 'but direct\n'
11948n/a 'assignment to the "__dict__" attribute is not possible (you '
11949n/a 'can write\n'
11950n/a '"m.__dict__[\'a\'] = 1", which defines "m.a" to be "1", but '
11951n/a "you can't\n"
11952n/a 'write "m.__dict__ = {}"). Modifying "__dict__" directly is '
11953n/a 'not\n'
11954n/a 'recommended.\n'
11955n/a '\n'
11956n/a 'Modules built into the interpreter are written like this: '
11957n/a '"<module\n'
11958n/a '\'sys\' (built-in)>". If loaded from a file, they are '
11959n/a 'written as\n'
11960n/a '"<module \'os\' from '
11961n/a '\'/usr/local/lib/pythonX.Y/os.pyc\'>".\n',
11962n/a 'typesseq': '\n'
11963n/a 'Sequence Types --- "list", "tuple", "range"\n'
11964n/a '*******************************************\n'
11965n/a '\n'
11966n/a 'There are three basic sequence types: lists, tuples, and range\n'
11967n/a 'objects. Additional sequence types tailored for processing of '
11968n/a 'binary\n'
11969n/a 'data and text strings are described in dedicated sections.\n'
11970n/a '\n'
11971n/a '\n'
11972n/a 'Common Sequence Operations\n'
11973n/a '==========================\n'
11974n/a '\n'
11975n/a 'The operations in the following table are supported by most '
11976n/a 'sequence\n'
11977n/a 'types, both mutable and immutable. The '
11978n/a '"collections.abc.Sequence" ABC\n'
11979n/a 'is provided to make it easier to correctly implement these '
11980n/a 'operations\n'
11981n/a 'on custom sequence types.\n'
11982n/a '\n'
11983n/a 'This table lists the sequence operations sorted in ascending '
11984n/a 'priority.\n'
11985n/a 'In the table, *s* and *t* are sequences of the same type, *n*, '
11986n/a '*i*,\n'
11987n/a '*j* and *k* are integers and *x* is an arbitrary object that '
11988n/a 'meets any\n'
11989n/a 'type and value restrictions imposed by *s*.\n'
11990n/a '\n'
11991n/a 'The "in" and "not in" operations have the same priorities as '
11992n/a 'the\n'
11993n/a 'comparison operations. The "+" (concatenation) and "*" '
11994n/a '(repetition)\n'
11995n/a 'operations have the same priority as the corresponding numeric\n'
11996n/a 'operations.\n'
11997n/a '\n'
11998n/a '+----------------------------+----------------------------------+------------+\n'
11999n/a '| Operation | Result '
12000n/a '| Notes |\n'
12001n/a '+============================+==================================+============+\n'
12002n/a '| "x in s" | "True" if an item of *s* is '
12003n/a '| (1) |\n'
12004n/a '| | equal to *x*, else "False" '
12005n/a '| |\n'
12006n/a '+----------------------------+----------------------------------+------------+\n'
12007n/a '| "x not in s" | "False" if an item of *s* is '
12008n/a '| (1) |\n'
12009n/a '| | equal to *x*, else "True" '
12010n/a '| |\n'
12011n/a '+----------------------------+----------------------------------+------------+\n'
12012n/a '| "s + t" | the concatenation of *s* and *t* '
12013n/a '| (6)(7) |\n'
12014n/a '+----------------------------+----------------------------------+------------+\n'
12015n/a '| "s * n" or "n * s" | equivalent to adding *s* to '
12016n/a '| (2)(7) |\n'
12017n/a '| | itself *n* times '
12018n/a '| |\n'
12019n/a '+----------------------------+----------------------------------+------------+\n'
12020n/a '| "s[i]" | *i*th item of *s*, origin 0 '
12021n/a '| (3) |\n'
12022n/a '+----------------------------+----------------------------------+------------+\n'
12023n/a '| "s[i:j]" | slice of *s* from *i* to *j* '
12024n/a '| (3)(4) |\n'
12025n/a '+----------------------------+----------------------------------+------------+\n'
12026n/a '| "s[i:j:k]" | slice of *s* from *i* to *j* '
12027n/a '| (3)(5) |\n'
12028n/a '| | with step *k* '
12029n/a '| |\n'
12030n/a '+----------------------------+----------------------------------+------------+\n'
12031n/a '| "len(s)" | length of *s* '
12032n/a '| |\n'
12033n/a '+----------------------------+----------------------------------+------------+\n'
12034n/a '| "min(s)" | smallest item of *s* '
12035n/a '| |\n'
12036n/a '+----------------------------+----------------------------------+------------+\n'
12037n/a '| "max(s)" | largest item of *s* '
12038n/a '| |\n'
12039n/a '+----------------------------+----------------------------------+------------+\n'
12040n/a '| "s.index(x[, i[, j]])" | index of the first occurrence of '
12041n/a '| (8) |\n'
12042n/a '| | *x* in *s* (at or after index '
12043n/a '| |\n'
12044n/a '| | *i* and before index *j*) '
12045n/a '| |\n'
12046n/a '+----------------------------+----------------------------------+------------+\n'
12047n/a '| "s.count(x)" | total number of occurrences of '
12048n/a '| |\n'
12049n/a '| | *x* in *s* '
12050n/a '| |\n'
12051n/a '+----------------------------+----------------------------------+------------+\n'
12052n/a '\n'
12053n/a 'Sequences of the same type also support comparisons. In '
12054n/a 'particular,\n'
12055n/a 'tuples and lists are compared lexicographically by comparing\n'
12056n/a 'corresponding elements. This means that to compare equal, every\n'
12057n/a 'element must compare equal and the two sequences must be of the '
12058n/a 'same\n'
12059n/a 'type and have the same length. (For full details see '
12060n/a 'Comparisons in\n'
12061n/a 'the language reference.)\n'
12062n/a '\n'
12063n/a 'Notes:\n'
12064n/a '\n'
12065n/a '1. While the "in" and "not in" operations are used only for '
12066n/a 'simple\n'
12067n/a ' containment testing in the general case, some specialised '
12068n/a 'sequences\n'
12069n/a ' (such as "str", "bytes" and "bytearray") also use them for\n'
12070n/a ' subsequence testing:\n'
12071n/a '\n'
12072n/a ' >>> "gg" in "eggs"\n'
12073n/a ' True\n'
12074n/a '\n'
12075n/a '2. Values of *n* less than "0" are treated as "0" (which yields '
12076n/a 'an\n'
12077n/a ' empty sequence of the same type as *s*). Note that items in '
12078n/a 'the\n'
12079n/a ' sequence *s* are not copied; they are referenced multiple '
12080n/a 'times.\n'
12081n/a ' This often haunts new Python programmers; consider:\n'
12082n/a '\n'
12083n/a ' >>> lists = [[]] * 3\n'
12084n/a ' >>> lists\n'
12085n/a ' [[], [], []]\n'
12086n/a ' >>> lists[0].append(3)\n'
12087n/a ' >>> lists\n'
12088n/a ' [[3], [3], [3]]\n'
12089n/a '\n'
12090n/a ' What has happened is that "[[]]" is a one-element list '
12091n/a 'containing\n'
12092n/a ' an empty list, so all three elements of "[[]] * 3" are '
12093n/a 'references\n'
12094n/a ' to this single empty list. Modifying any of the elements of\n'
12095n/a ' "lists" modifies this single list. You can create a list of\n'
12096n/a ' different lists this way:\n'
12097n/a '\n'
12098n/a ' >>> lists = [[] for i in range(3)]\n'
12099n/a ' >>> lists[0].append(3)\n'
12100n/a ' >>> lists[1].append(5)\n'
12101n/a ' >>> lists[2].append(7)\n'
12102n/a ' >>> lists\n'
12103n/a ' [[3], [5], [7]]\n'
12104n/a '\n'
12105n/a ' Further explanation is available in the FAQ entry How do I '
12106n/a 'create a\n'
12107n/a ' multidimensional list?.\n'
12108n/a '\n'
12109n/a '3. If *i* or *j* is negative, the index is relative to the end '
12110n/a 'of\n'
12111n/a ' the string: "len(s) + i" or "len(s) + j" is substituted. But '
12112n/a 'note\n'
12113n/a ' that "-0" is still "0".\n'
12114n/a '\n'
12115n/a '4. The slice of *s* from *i* to *j* is defined as the sequence '
12116n/a 'of\n'
12117n/a ' items with index *k* such that "i <= k < j". If *i* or *j* '
12118n/a 'is\n'
12119n/a ' greater than "len(s)", use "len(s)". If *i* is omitted or '
12120n/a '"None",\n'
12121n/a ' use "0". If *j* is omitted or "None", use "len(s)". If *i* '
12122n/a 'is\n'
12123n/a ' greater than or equal to *j*, the slice is empty.\n'
12124n/a '\n'
12125n/a '5. The slice of *s* from *i* to *j* with step *k* is defined as '
12126n/a 'the\n'
12127n/a ' sequence of items with index "x = i + n*k" such that "0 <= n '
12128n/a '<\n'
12129n/a ' (j-i)/k". In other words, the indices are "i", "i+k", '
12130n/a '"i+2*k",\n'
12131n/a ' "i+3*k" and so on, stopping when *j* is reached (but never\n'
12132n/a ' including *j*). If *i* or *j* is greater than "len(s)", use\n'
12133n/a ' "len(s)". If *i* or *j* are omitted or "None", they become '
12134n/a '"end"\n'
12135n/a ' values (which end depends on the sign of *k*). Note, *k* '
12136n/a 'cannot be\n'
12137n/a ' zero. If *k* is "None", it is treated like "1".\n'
12138n/a '\n'
12139n/a '6. Concatenating immutable sequences always results in a new\n'
12140n/a ' object. This means that building up a sequence by repeated\n'
12141n/a ' concatenation will have a quadratic runtime cost in the '
12142n/a 'total\n'
12143n/a ' sequence length. To get a linear runtime cost, you must '
12144n/a 'switch to\n'
12145n/a ' one of the alternatives below:\n'
12146n/a '\n'
12147n/a ' * if concatenating "str" objects, you can build a list and '
12148n/a 'use\n'
12149n/a ' "str.join()" at the end or else write to an "io.StringIO"\n'
12150n/a ' instance and retrieve its value when complete\n'
12151n/a '\n'
12152n/a ' * if concatenating "bytes" objects, you can similarly use\n'
12153n/a ' "bytes.join()" or "io.BytesIO", or you can do in-place\n'
12154n/a ' concatenation with a "bytearray" object. "bytearray" '
12155n/a 'objects are\n'
12156n/a ' mutable and have an efficient overallocation mechanism\n'
12157n/a '\n'
12158n/a ' * if concatenating "tuple" objects, extend a "list" instead\n'
12159n/a '\n'
12160n/a ' * for other types, investigate the relevant class '
12161n/a 'documentation\n'
12162n/a '\n'
12163n/a '7. Some sequence types (such as "range") only support item\n'
12164n/a " sequences that follow specific patterns, and hence don't "
12165n/a 'support\n'
12166n/a ' sequence concatenation or repetition.\n'
12167n/a '\n'
12168n/a '8. "index" raises "ValueError" when *x* is not found in *s*. '
12169n/a 'When\n'
12170n/a ' supported, the additional arguments to the index method '
12171n/a 'allow\n'
12172n/a ' efficient searching of subsections of the sequence. Passing '
12173n/a 'the\n'
12174n/a ' extra arguments is roughly equivalent to using '
12175n/a '"s[i:j].index(x)",\n'
12176n/a ' only without copying any data and with the returned index '
12177n/a 'being\n'
12178n/a ' relative to the start of the sequence rather than the start '
12179n/a 'of the\n'
12180n/a ' slice.\n'
12181n/a '\n'
12182n/a '\n'
12183n/a 'Immutable Sequence Types\n'
12184n/a '========================\n'
12185n/a '\n'
12186n/a 'The only operation that immutable sequence types generally '
12187n/a 'implement\n'
12188n/a 'that is not also implemented by mutable sequence types is '
12189n/a 'support for\n'
12190n/a 'the "hash()" built-in.\n'
12191n/a '\n'
12192n/a 'This support allows immutable sequences, such as "tuple" '
12193n/a 'instances, to\n'
12194n/a 'be used as "dict" keys and stored in "set" and "frozenset" '
12195n/a 'instances.\n'
12196n/a '\n'
12197n/a 'Attempting to hash an immutable sequence that contains '
12198n/a 'unhashable\n'
12199n/a 'values will result in "TypeError".\n'
12200n/a '\n'
12201n/a '\n'
12202n/a 'Mutable Sequence Types\n'
12203n/a '======================\n'
12204n/a '\n'
12205n/a 'The operations in the following table are defined on mutable '
12206n/a 'sequence\n'
12207n/a 'types. The "collections.abc.MutableSequence" ABC is provided to '
12208n/a 'make\n'
12209n/a 'it easier to correctly implement these operations on custom '
12210n/a 'sequence\n'
12211n/a 'types.\n'
12212n/a '\n'
12213n/a 'In the table *s* is an instance of a mutable sequence type, *t* '
12214n/a 'is any\n'
12215n/a 'iterable object and *x* is an arbitrary object that meets any '
12216n/a 'type and\n'
12217n/a 'value restrictions imposed by *s* (for example, "bytearray" '
12218n/a 'only\n'
12219n/a 'accepts integers that meet the value restriction "0 <= x <= '
12220n/a '255").\n'
12221n/a '\n'
12222n/a '+--------------------------------+----------------------------------+-----------------------+\n'
12223n/a '| Operation | '
12224n/a 'Result | Notes |\n'
12225n/a '+================================+==================================+=======================+\n'
12226n/a '| "s[i] = x" | item *i* of *s* is replaced '
12227n/a 'by | |\n'
12228n/a '| | '
12229n/a '*x* | |\n'
12230n/a '+--------------------------------+----------------------------------+-----------------------+\n'
12231n/a '| "s[i:j] = t" | slice of *s* from *i* to *j* '
12232n/a 'is | |\n'
12233n/a '| | replaced by the contents of '
12234n/a 'the | |\n'
12235n/a '| | iterable '
12236n/a '*t* | |\n'
12237n/a '+--------------------------------+----------------------------------+-----------------------+\n'
12238n/a '| "del s[i:j]" | same as "s[i:j] = '
12239n/a '[]" | |\n'
12240n/a '+--------------------------------+----------------------------------+-----------------------+\n'
12241n/a '| "s[i:j:k] = t" | the elements of "s[i:j:k]" '
12242n/a 'are | (1) |\n'
12243n/a '| | replaced by those of '
12244n/a '*t* | |\n'
12245n/a '+--------------------------------+----------------------------------+-----------------------+\n'
12246n/a '| "del s[i:j:k]" | removes the elements '
12247n/a 'of | |\n'
12248n/a '| | "s[i:j:k]" from the '
12249n/a 'list | |\n'
12250n/a '+--------------------------------+----------------------------------+-----------------------+\n'
12251n/a '| "s.append(x)" | appends *x* to the end of '
12252n/a 'the | |\n'
12253n/a '| | sequence (same '
12254n/a 'as | |\n'
12255n/a '| | "s[len(s):len(s)] = '
12256n/a '[x]") | |\n'
12257n/a '+--------------------------------+----------------------------------+-----------------------+\n'
12258n/a '| "s.clear()" | removes all items from "s" '
12259n/a '(same | (5) |\n'
12260n/a '| | as "del '
12261n/a 's[:]") | |\n'
12262n/a '+--------------------------------+----------------------------------+-----------------------+\n'
12263n/a '| "s.copy()" | creates a shallow copy of '
12264n/a '"s" | (5) |\n'
12265n/a '| | (same as '
12266n/a '"s[:]") | |\n'
12267n/a '+--------------------------------+----------------------------------+-----------------------+\n'
12268n/a '| "s.extend(t)" or "s += t" | extends *s* with the contents '
12269n/a 'of | |\n'
12270n/a '| | *t* (for the most part the '
12271n/a 'same | |\n'
12272n/a '| | as "s[len(s):len(s)] = '
12273n/a 't") | |\n'
12274n/a '+--------------------------------+----------------------------------+-----------------------+\n'
12275n/a '| "s *= n" | updates *s* with its '
12276n/a 'contents | (6) |\n'
12277n/a '| | repeated *n* '
12278n/a 'times | |\n'
12279n/a '+--------------------------------+----------------------------------+-----------------------+\n'
12280n/a '| "s.insert(i, x)" | inserts *x* into *s* at '
12281n/a 'the | |\n'
12282n/a '| | index given by *i* (same '
12283n/a 'as | |\n'
12284n/a '| | "s[i:i] = '
12285n/a '[x]") | |\n'
12286n/a '+--------------------------------+----------------------------------+-----------------------+\n'
12287n/a '| "s.pop([i])" | retrieves the item at *i* '
12288n/a 'and | (2) |\n'
12289n/a '| | also removes it from '
12290n/a '*s* | |\n'
12291n/a '+--------------------------------+----------------------------------+-----------------------+\n'
12292n/a '| "s.remove(x)" | remove the first item from '
12293n/a '*s* | (3) |\n'
12294n/a '| | where "s[i] == '
12295n/a 'x" | |\n'
12296n/a '+--------------------------------+----------------------------------+-----------------------+\n'
12297n/a '| "s.reverse()" | reverses the items of *s* '
12298n/a 'in | (4) |\n'
12299n/a '| | '
12300n/a 'place | |\n'
12301n/a '+--------------------------------+----------------------------------+-----------------------+\n'
12302n/a '\n'
12303n/a 'Notes:\n'
12304n/a '\n'
12305n/a '1. *t* must have the same length as the slice it is replacing.\n'
12306n/a '\n'
12307n/a '2. The optional argument *i* defaults to "-1", so that by '
12308n/a 'default\n'
12309n/a ' the last item is removed and returned.\n'
12310n/a '\n'
12311n/a '3. "remove" raises "ValueError" when *x* is not found in *s*.\n'
12312n/a '\n'
12313n/a '4. The "reverse()" method modifies the sequence in place for\n'
12314n/a ' economy of space when reversing a large sequence. To remind '
12315n/a 'users\n'
12316n/a ' that it operates by side effect, it does not return the '
12317n/a 'reversed\n'
12318n/a ' sequence.\n'
12319n/a '\n'
12320n/a '5. "clear()" and "copy()" are included for consistency with the\n'
12321n/a " interfaces of mutable containers that don't support slicing\n"
12322n/a ' operations (such as "dict" and "set")\n'
12323n/a '\n'
12324n/a ' New in version 3.3: "clear()" and "copy()" methods.\n'
12325n/a '\n'
12326n/a '6. The value *n* is an integer, or an object implementing\n'
12327n/a ' "__index__()". Zero and negative values of *n* clear the '
12328n/a 'sequence.\n'
12329n/a ' Items in the sequence are not copied; they are referenced '
12330n/a 'multiple\n'
12331n/a ' times, as explained for "s * n" under Common Sequence '
12332n/a 'Operations.\n'
12333n/a '\n'
12334n/a '\n'
12335n/a 'Lists\n'
12336n/a '=====\n'
12337n/a '\n'
12338n/a 'Lists are mutable sequences, typically used to store collections '
12339n/a 'of\n'
12340n/a 'homogeneous items (where the precise degree of similarity will '
12341n/a 'vary by\n'
12342n/a 'application).\n'
12343n/a '\n'
12344n/a 'class list([iterable])\n'
12345n/a '\n'
12346n/a ' Lists may be constructed in several ways:\n'
12347n/a '\n'
12348n/a ' * Using a pair of square brackets to denote the empty list: '
12349n/a '"[]"\n'
12350n/a '\n'
12351n/a ' * Using square brackets, separating items with commas: '
12352n/a '"[a]",\n'
12353n/a ' "[a, b, c]"\n'
12354n/a '\n'
12355n/a ' * Using a list comprehension: "[x for x in iterable]"\n'
12356n/a '\n'
12357n/a ' * Using the type constructor: "list()" or "list(iterable)"\n'
12358n/a '\n'
12359n/a ' The constructor builds a list whose items are the same and in '
12360n/a 'the\n'
12361n/a " same order as *iterable*'s items. *iterable* may be either "
12362n/a 'a\n'
12363n/a ' sequence, a container that supports iteration, or an '
12364n/a 'iterator\n'
12365n/a ' object. If *iterable* is already a list, a copy is made and\n'
12366n/a ' returned, similar to "iterable[:]". For example, '
12367n/a '"list(\'abc\')"\n'
12368n/a ' returns "[\'a\', \'b\', \'c\']" and "list( (1, 2, 3) )" '
12369n/a 'returns "[1, 2,\n'
12370n/a ' 3]". If no argument is given, the constructor creates a new '
12371n/a 'empty\n'
12372n/a ' list, "[]".\n'
12373n/a '\n'
12374n/a ' Many other operations also produce lists, including the '
12375n/a '"sorted()"\n'
12376n/a ' built-in.\n'
12377n/a '\n'
12378n/a ' Lists implement all of the common and mutable sequence '
12379n/a 'operations.\n'
12380n/a ' Lists also provide the following additional method:\n'
12381n/a '\n'
12382n/a ' sort(*, key=None, reverse=None)\n'
12383n/a '\n'
12384n/a ' This method sorts the list in place, using only "<" '
12385n/a 'comparisons\n'
12386n/a ' between items. Exceptions are not suppressed - if any '
12387n/a 'comparison\n'
12388n/a ' operations fail, the entire sort operation will fail (and '
12389n/a 'the\n'
12390n/a ' list will likely be left in a partially modified state).\n'
12391n/a '\n'
12392n/a ' "sort()" accepts two arguments that can only be passed by\n'
12393n/a ' keyword (keyword-only arguments):\n'
12394n/a '\n'
12395n/a ' *key* specifies a function of one argument that is used '
12396n/a 'to\n'
12397n/a ' extract a comparison key from each list element (for '
12398n/a 'example,\n'
12399n/a ' "key=str.lower"). The key corresponding to each item in '
12400n/a 'the list\n'
12401n/a ' is calculated once and then used for the entire sorting '
12402n/a 'process.\n'
12403n/a ' The default value of "None" means that list items are '
12404n/a 'sorted\n'
12405n/a ' directly without calculating a separate key value.\n'
12406n/a '\n'
12407n/a ' The "functools.cmp_to_key()" utility is available to '
12408n/a 'convert a\n'
12409n/a ' 2.x style *cmp* function to a *key* function.\n'
12410n/a '\n'
12411n/a ' *reverse* is a boolean value. If set to "True", then the '
12412n/a 'list\n'
12413n/a ' elements are sorted as if each comparison were reversed.\n'
12414n/a '\n'
12415n/a ' This method modifies the sequence in place for economy of '
12416n/a 'space\n'
12417n/a ' when sorting a large sequence. To remind users that it '
12418n/a 'operates\n'
12419n/a ' by side effect, it does not return the sorted sequence '
12420n/a '(use\n'
12421n/a ' "sorted()" to explicitly request a new sorted list '
12422n/a 'instance).\n'
12423n/a '\n'
12424n/a ' The "sort()" method is guaranteed to be stable. A sort '
12425n/a 'is\n'
12426n/a ' stable if it guarantees not to change the relative order '
12427n/a 'of\n'
12428n/a ' elements that compare equal --- this is helpful for '
12429n/a 'sorting in\n'
12430n/a ' multiple passes (for example, sort by department, then by '
12431n/a 'salary\n'
12432n/a ' grade).\n'
12433n/a '\n'
12434n/a ' **CPython implementation detail:** While a list is being '
12435n/a 'sorted,\n'
12436n/a ' the effect of attempting to mutate, or even inspect, the '
12437n/a 'list is\n'
12438n/a ' undefined. The C implementation of Python makes the list '
12439n/a 'appear\n'
12440n/a ' empty for the duration, and raises "ValueError" if it can '
12441n/a 'detect\n'
12442n/a ' that the list has been mutated during a sort.\n'
12443n/a '\n'
12444n/a '\n'
12445n/a 'Tuples\n'
12446n/a '======\n'
12447n/a '\n'
12448n/a 'Tuples are immutable sequences, typically used to store '
12449n/a 'collections of\n'
12450n/a 'heterogeneous data (such as the 2-tuples produced by the '
12451n/a '"enumerate()"\n'
12452n/a 'built-in). Tuples are also used for cases where an immutable '
12453n/a 'sequence\n'
12454n/a 'of homogeneous data is needed (such as allowing storage in a '
12455n/a '"set" or\n'
12456n/a '"dict" instance).\n'
12457n/a '\n'
12458n/a 'class tuple([iterable])\n'
12459n/a '\n'
12460n/a ' Tuples may be constructed in a number of ways:\n'
12461n/a '\n'
12462n/a ' * Using a pair of parentheses to denote the empty tuple: '
12463n/a '"()"\n'
12464n/a '\n'
12465n/a ' * Using a trailing comma for a singleton tuple: "a," or '
12466n/a '"(a,)"\n'
12467n/a '\n'
12468n/a ' * Separating items with commas: "a, b, c" or "(a, b, c)"\n'
12469n/a '\n'
12470n/a ' * Using the "tuple()" built-in: "tuple()" or '
12471n/a '"tuple(iterable)"\n'
12472n/a '\n'
12473n/a ' The constructor builds a tuple whose items are the same and '
12474n/a 'in the\n'
12475n/a " same order as *iterable*'s items. *iterable* may be either "
12476n/a 'a\n'
12477n/a ' sequence, a container that supports iteration, or an '
12478n/a 'iterator\n'
12479n/a ' object. If *iterable* is already a tuple, it is returned\n'
12480n/a ' unchanged. For example, "tuple(\'abc\')" returns "(\'a\', '
12481n/a '\'b\', \'c\')"\n'
12482n/a ' and "tuple( [1, 2, 3] )" returns "(1, 2, 3)". If no argument '
12483n/a 'is\n'
12484n/a ' given, the constructor creates a new empty tuple, "()".\n'
12485n/a '\n'
12486n/a ' Note that it is actually the comma which makes a tuple, not '
12487n/a 'the\n'
12488n/a ' parentheses. The parentheses are optional, except in the '
12489n/a 'empty\n'
12490n/a ' tuple case, or when they are needed to avoid syntactic '
12491n/a 'ambiguity.\n'
12492n/a ' For example, "f(a, b, c)" is a function call with three '
12493n/a 'arguments,\n'
12494n/a ' while "f((a, b, c))" is a function call with a 3-tuple as the '
12495n/a 'sole\n'
12496n/a ' argument.\n'
12497n/a '\n'
12498n/a ' Tuples implement all of the common sequence operations.\n'
12499n/a '\n'
12500n/a 'For heterogeneous collections of data where access by name is '
12501n/a 'clearer\n'
12502n/a 'than access by index, "collections.namedtuple()" may be a more\n'
12503n/a 'appropriate choice than a simple tuple object.\n'
12504n/a '\n'
12505n/a '\n'
12506n/a 'Ranges\n'
12507n/a '======\n'
12508n/a '\n'
12509n/a 'The "range" type represents an immutable sequence of numbers and '
12510n/a 'is\n'
12511n/a 'commonly used for looping a specific number of times in "for" '
12512n/a 'loops.\n'
12513n/a '\n'
12514n/a 'class range(stop)\n'
12515n/a 'class range(start, stop[, step])\n'
12516n/a '\n'
12517n/a ' The arguments to the range constructor must be integers '
12518n/a '(either\n'
12519n/a ' built-in "int" or any object that implements the "__index__"\n'
12520n/a ' special method). If the *step* argument is omitted, it '
12521n/a 'defaults to\n'
12522n/a ' "1". If the *start* argument is omitted, it defaults to "0". '
12523n/a 'If\n'
12524n/a ' *step* is zero, "ValueError" is raised.\n'
12525n/a '\n'
12526n/a ' For a positive *step*, the contents of a range "r" are '
12527n/a 'determined\n'
12528n/a ' by the formula "r[i] = start + step*i" where "i >= 0" and '
12529n/a '"r[i] <\n'
12530n/a ' stop".\n'
12531n/a '\n'
12532n/a ' For a negative *step*, the contents of the range are still\n'
12533n/a ' determined by the formula "r[i] = start + step*i", but the\n'
12534n/a ' constraints are "i >= 0" and "r[i] > stop".\n'
12535n/a '\n'
12536n/a ' A range object will be empty if "r[0]" does not meet the '
12537n/a 'value\n'
12538n/a ' constraint. Ranges do support negative indices, but these '
12539n/a 'are\n'
12540n/a ' interpreted as indexing from the end of the sequence '
12541n/a 'determined by\n'
12542n/a ' the positive indices.\n'
12543n/a '\n'
12544n/a ' Ranges containing absolute values larger than "sys.maxsize" '
12545n/a 'are\n'
12546n/a ' permitted but some features (such as "len()") may raise\n'
12547n/a ' "OverflowError".\n'
12548n/a '\n'
12549n/a ' Range examples:\n'
12550n/a '\n'
12551n/a ' >>> list(range(10))\n'
12552n/a ' [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]\n'
12553n/a ' >>> list(range(1, 11))\n'
12554n/a ' [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]\n'
12555n/a ' >>> list(range(0, 30, 5))\n'
12556n/a ' [0, 5, 10, 15, 20, 25]\n'
12557n/a ' >>> list(range(0, 10, 3))\n'
12558n/a ' [0, 3, 6, 9]\n'
12559n/a ' >>> list(range(0, -10, -1))\n'
12560n/a ' [0, -1, -2, -3, -4, -5, -6, -7, -8, -9]\n'
12561n/a ' >>> list(range(0))\n'
12562n/a ' []\n'
12563n/a ' >>> list(range(1, 0))\n'
12564n/a ' []\n'
12565n/a '\n'
12566n/a ' Ranges implement all of the common sequence operations '
12567n/a 'except\n'
12568n/a ' concatenation and repetition (due to the fact that range '
12569n/a 'objects\n'
12570n/a ' can only represent sequences that follow a strict pattern '
12571n/a 'and\n'
12572n/a ' repetition and concatenation will usually violate that '
12573n/a 'pattern).\n'
12574n/a '\n'
12575n/a ' start\n'
12576n/a '\n'
12577n/a ' The value of the *start* parameter (or "0" if the '
12578n/a 'parameter was\n'
12579n/a ' not supplied)\n'
12580n/a '\n'
12581n/a ' stop\n'
12582n/a '\n'
12583n/a ' The value of the *stop* parameter\n'
12584n/a '\n'
12585n/a ' step\n'
12586n/a '\n'
12587n/a ' The value of the *step* parameter (or "1" if the parameter '
12588n/a 'was\n'
12589n/a ' not supplied)\n'
12590n/a '\n'
12591n/a 'The advantage of the "range" type over a regular "list" or '
12592n/a '"tuple" is\n'
12593n/a 'that a "range" object will always take the same (small) amount '
12594n/a 'of\n'
12595n/a 'memory, no matter the size of the range it represents (as it '
12596n/a 'only\n'
12597n/a 'stores the "start", "stop" and "step" values, calculating '
12598n/a 'individual\n'
12599n/a 'items and subranges as needed).\n'
12600n/a '\n'
12601n/a 'Range objects implement the "collections.abc.Sequence" ABC, and\n'
12602n/a 'provide features such as containment tests, element index '
12603n/a 'lookup,\n'
12604n/a 'slicing and support for negative indices (see Sequence Types --- '
12605n/a 'list,\n'
12606n/a 'tuple, range):\n'
12607n/a '\n'
12608n/a '>>> r = range(0, 20, 2)\n'
12609n/a '>>> r\n'
12610n/a 'range(0, 20, 2)\n'
12611n/a '>>> 11 in r\n'
12612n/a 'False\n'
12613n/a '>>> 10 in r\n'
12614n/a 'True\n'
12615n/a '>>> r.index(10)\n'
12616n/a '5\n'
12617n/a '>>> r[5]\n'
12618n/a '10\n'
12619n/a '>>> r[:5]\n'
12620n/a 'range(0, 10, 2)\n'
12621n/a '>>> r[-1]\n'
12622n/a '18\n'
12623n/a '\n'
12624n/a 'Testing range objects for equality with "==" and "!=" compares '
12625n/a 'them as\n'
12626n/a 'sequences. That is, two range objects are considered equal if '
12627n/a 'they\n'
12628n/a 'represent the same sequence of values. (Note that two range '
12629n/a 'objects\n'
12630n/a 'that compare equal might have different "start", "stop" and '
12631n/a '"step"\n'
12632n/a 'attributes, for example "range(0) == range(2, 1, 3)" or '
12633n/a '"range(0, 3,\n'
12634n/a '2) == range(0, 4, 2)".)\n'
12635n/a '\n'
12636n/a 'Changed in version 3.2: Implement the Sequence ABC. Support '
12637n/a 'slicing\n'
12638n/a 'and negative indices. Test "int" objects for membership in '
12639n/a 'constant\n'
12640n/a 'time instead of iterating through all items.\n'
12641n/a '\n'
12642n/a "Changed in version 3.3: Define '==' and '!=' to compare range "
12643n/a 'objects\n'
12644n/a 'based on the sequence of values they define (instead of '
12645n/a 'comparing\n'
12646n/a 'based on object identity).\n'
12647n/a '\n'
12648n/a 'New in version 3.3: The "start", "stop" and "step" attributes.\n'
12649n/a '\n'
12650n/a 'See also:\n'
12651n/a '\n'
12652n/a ' * The linspace recipe shows how to implement a lazy version '
12653n/a 'of\n'
12654n/a ' range that suitable for floating point applications.\n',
12655n/a 'typesseq-mutable': '\n'
12656n/a 'Mutable Sequence Types\n'
12657n/a '**********************\n'
12658n/a '\n'
12659n/a 'The operations in the following table are defined on '
12660n/a 'mutable sequence\n'
12661n/a 'types. The "collections.abc.MutableSequence" ABC is '
12662n/a 'provided to make\n'
12663n/a 'it easier to correctly implement these operations on '
12664n/a 'custom sequence\n'
12665n/a 'types.\n'
12666n/a '\n'
12667n/a 'In the table *s* is an instance of a mutable sequence '
12668n/a 'type, *t* is any\n'
12669n/a 'iterable object and *x* is an arbitrary object that '
12670n/a 'meets any type and\n'
12671n/a 'value restrictions imposed by *s* (for example, '
12672n/a '"bytearray" only\n'
12673n/a 'accepts integers that meet the value restriction "0 <= x '
12674n/a '<= 255").\n'
12675n/a '\n'
12676n/a '+--------------------------------+----------------------------------+-----------------------+\n'
12677n/a '| Operation | '
12678n/a 'Result | Notes '
12679n/a '|\n'
12680n/a '+================================+==================================+=======================+\n'
12681n/a '| "s[i] = x" | item *i* of *s* is '
12682n/a 'replaced by | |\n'
12683n/a '| | '
12684n/a '*x* | '
12685n/a '|\n'
12686n/a '+--------------------------------+----------------------------------+-----------------------+\n'
12687n/a '| "s[i:j] = t" | slice of *s* from *i* '
12688n/a 'to *j* is | |\n'
12689n/a '| | replaced by the '
12690n/a 'contents of the | |\n'
12691n/a '| | iterable '
12692n/a '*t* | |\n'
12693n/a '+--------------------------------+----------------------------------+-----------------------+\n'
12694n/a '| "del s[i:j]" | same as "s[i:j] = '
12695n/a '[]" | |\n'
12696n/a '+--------------------------------+----------------------------------+-----------------------+\n'
12697n/a '| "s[i:j:k] = t" | the elements of '
12698n/a '"s[i:j:k]" are | (1) |\n'
12699n/a '| | replaced by those of '
12700n/a '*t* | |\n'
12701n/a '+--------------------------------+----------------------------------+-----------------------+\n'
12702n/a '| "del s[i:j:k]" | removes the elements '
12703n/a 'of | |\n'
12704n/a '| | "s[i:j:k]" from the '
12705n/a 'list | |\n'
12706n/a '+--------------------------------+----------------------------------+-----------------------+\n'
12707n/a '| "s.append(x)" | appends *x* to the '
12708n/a 'end of the | |\n'
12709n/a '| | sequence (same '
12710n/a 'as | |\n'
12711n/a '| | "s[len(s):len(s)] = '
12712n/a '[x]") | |\n'
12713n/a '+--------------------------------+----------------------------------+-----------------------+\n'
12714n/a '| "s.clear()" | removes all items '
12715n/a 'from "s" (same | (5) |\n'
12716n/a '| | as "del '
12717n/a 's[:]") | |\n'
12718n/a '+--------------------------------+----------------------------------+-----------------------+\n'
12719n/a '| "s.copy()" | creates a shallow '
12720n/a 'copy of "s" | (5) |\n'
12721n/a '| | (same as '
12722n/a '"s[:]") | |\n'
12723n/a '+--------------------------------+----------------------------------+-----------------------+\n'
12724n/a '| "s.extend(t)" or "s += t" | extends *s* with the '
12725n/a 'contents of | |\n'
12726n/a '| | *t* (for the most '
12727n/a 'part the same | |\n'
12728n/a '| | as "s[len(s):len(s)] '
12729n/a '= t") | |\n'
12730n/a '+--------------------------------+----------------------------------+-----------------------+\n'
12731n/a '| "s *= n" | updates *s* with its '
12732n/a 'contents | (6) |\n'
12733n/a '| | repeated *n* '
12734n/a 'times | |\n'
12735n/a '+--------------------------------+----------------------------------+-----------------------+\n'
12736n/a '| "s.insert(i, x)" | inserts *x* into *s* '
12737n/a 'at the | |\n'
12738n/a '| | index given by *i* '
12739n/a '(same as | |\n'
12740n/a '| | "s[i:i] = '
12741n/a '[x]") | |\n'
12742n/a '+--------------------------------+----------------------------------+-----------------------+\n'
12743n/a '| "s.pop([i])" | retrieves the item at '
12744n/a '*i* and | (2) |\n'
12745n/a '| | also removes it from '
12746n/a '*s* | |\n'
12747n/a '+--------------------------------+----------------------------------+-----------------------+\n'
12748n/a '| "s.remove(x)" | remove the first item '
12749n/a 'from *s* | (3) |\n'
12750n/a '| | where "s[i] == '
12751n/a 'x" | |\n'
12752n/a '+--------------------------------+----------------------------------+-----------------------+\n'
12753n/a '| "s.reverse()" | reverses the items of '
12754n/a '*s* in | (4) |\n'
12755n/a '| | '
12756n/a 'place | '
12757n/a '|\n'
12758n/a '+--------------------------------+----------------------------------+-----------------------+\n'
12759n/a '\n'
12760n/a 'Notes:\n'
12761n/a '\n'
12762n/a '1. *t* must have the same length as the slice it is '
12763n/a 'replacing.\n'
12764n/a '\n'
12765n/a '2. The optional argument *i* defaults to "-1", so that '
12766n/a 'by default\n'
12767n/a ' the last item is removed and returned.\n'
12768n/a '\n'
12769n/a '3. "remove" raises "ValueError" when *x* is not found in '
12770n/a '*s*.\n'
12771n/a '\n'
12772n/a '4. The "reverse()" method modifies the sequence in place '
12773n/a 'for\n'
12774n/a ' economy of space when reversing a large sequence. To '
12775n/a 'remind users\n'
12776n/a ' that it operates by side effect, it does not return '
12777n/a 'the reversed\n'
12778n/a ' sequence.\n'
12779n/a '\n'
12780n/a '5. "clear()" and "copy()" are included for consistency '
12781n/a 'with the\n'
12782n/a " interfaces of mutable containers that don't support "
12783n/a 'slicing\n'
12784n/a ' operations (such as "dict" and "set")\n'
12785n/a '\n'
12786n/a ' New in version 3.3: "clear()" and "copy()" methods.\n'
12787n/a '\n'
12788n/a '6. The value *n* is an integer, or an object '
12789n/a 'implementing\n'
12790n/a ' "__index__()". Zero and negative values of *n* clear '
12791n/a 'the sequence.\n'
12792n/a ' Items in the sequence are not copied; they are '
12793n/a 'referenced multiple\n'
12794n/a ' times, as explained for "s * n" under Common Sequence '
12795n/a 'Operations.\n',
12796n/a 'unary': '\n'
12797n/a 'Unary arithmetic and bitwise operations\n'
12798n/a '***************************************\n'
12799n/a '\n'
12800n/a 'All unary arithmetic and bitwise operations have the same '
12801n/a 'priority:\n'
12802n/a '\n'
12803n/a ' u_expr ::= power | "-" u_expr | "+" u_expr | "~" u_expr\n'
12804n/a '\n'
12805n/a 'The unary "-" (minus) operator yields the negation of its numeric\n'
12806n/a 'argument.\n'
12807n/a '\n'
12808n/a 'The unary "+" (plus) operator yields its numeric argument '
12809n/a 'unchanged.\n'
12810n/a '\n'
12811n/a 'The unary "~" (invert) operator yields the bitwise inversion of '
12812n/a 'its\n'
12813n/a 'integer argument. The bitwise inversion of "x" is defined as\n'
12814n/a '"-(x+1)". It only applies to integral numbers.\n'
12815n/a '\n'
12816n/a 'In all three cases, if the argument does not have the proper type, '
12817n/a 'a\n'
12818n/a '"TypeError" exception is raised.\n',
12819n/a 'while': '\n'
12820n/a 'The "while" statement\n'
12821n/a '*********************\n'
12822n/a '\n'
12823n/a 'The "while" statement is used for repeated execution as long as an\n'
12824n/a 'expression is true:\n'
12825n/a '\n'
12826n/a ' while_stmt ::= "while" expression ":" suite\n'
12827n/a ' ["else" ":" suite]\n'
12828n/a '\n'
12829n/a 'This repeatedly tests the expression and, if it is true, executes '
12830n/a 'the\n'
12831n/a 'first suite; if the expression is false (which may be the first '
12832n/a 'time\n'
12833n/a 'it is tested) the suite of the "else" clause, if present, is '
12834n/a 'executed\n'
12835n/a 'and the loop terminates.\n'
12836n/a '\n'
12837n/a 'A "break" statement executed in the first suite terminates the '
12838n/a 'loop\n'
12839n/a 'without executing the "else" clause\'s suite. A "continue" '
12840n/a 'statement\n'
12841n/a 'executed in the first suite skips the rest of the suite and goes '
12842n/a 'back\n'
12843n/a 'to testing the expression.\n',
12844n/a 'with': '\n'
12845n/a 'The "with" statement\n'
12846n/a '********************\n'
12847n/a '\n'
12848n/a 'The "with" statement is used to wrap the execution of a block with\n'
12849n/a 'methods defined by a context manager (see section With Statement\n'
12850n/a 'Context Managers). This allows common "try"..."except"..."finally"\n'
12851n/a 'usage patterns to be encapsulated for convenient reuse.\n'
12852n/a '\n'
12853n/a ' with_stmt ::= "with" with_item ("," with_item)* ":" suite\n'
12854n/a ' with_item ::= expression ["as" target]\n'
12855n/a '\n'
12856n/a 'The execution of the "with" statement with one "item" proceeds as\n'
12857n/a 'follows:\n'
12858n/a '\n'
12859n/a '1. The context expression (the expression given in the "with_item")\n'
12860n/a ' is evaluated to obtain a context manager.\n'
12861n/a '\n'
12862n/a '2. The context manager\'s "__exit__()" is loaded for later use.\n'
12863n/a '\n'
12864n/a '3. The context manager\'s "__enter__()" method is invoked.\n'
12865n/a '\n'
12866n/a '4. If a target was included in the "with" statement, the return\n'
12867n/a ' value from "__enter__()" is assigned to it.\n'
12868n/a '\n'
12869n/a ' Note: The "with" statement guarantees that if the "__enter__()"\n'
12870n/a ' method returns without an error, then "__exit__()" will always '
12871n/a 'be\n'
12872n/a ' called. Thus, if an error occurs during the assignment to the\n'
12873n/a ' target list, it will be treated the same as an error occurring\n'
12874n/a ' within the suite would be. See step 6 below.\n'
12875n/a '\n'
12876n/a '5. The suite is executed.\n'
12877n/a '\n'
12878n/a '6. The context manager\'s "__exit__()" method is invoked. If an\n'
12879n/a ' exception caused the suite to be exited, its type, value, and\n'
12880n/a ' traceback are passed as arguments to "__exit__()". Otherwise, '
12881n/a 'three\n'
12882n/a ' "None" arguments are supplied.\n'
12883n/a '\n'
12884n/a ' If the suite was exited due to an exception, and the return '
12885n/a 'value\n'
12886n/a ' from the "__exit__()" method was false, the exception is '
12887n/a 'reraised.\n'
12888n/a ' If the return value was true, the exception is suppressed, and\n'
12889n/a ' execution continues with the statement following the "with"\n'
12890n/a ' statement.\n'
12891n/a '\n'
12892n/a ' If the suite was exited for any reason other than an exception, '
12893n/a 'the\n'
12894n/a ' return value from "__exit__()" is ignored, and execution '
12895n/a 'proceeds\n'
12896n/a ' at the normal location for the kind of exit that was taken.\n'
12897n/a '\n'
12898n/a 'With more than one item, the context managers are processed as if\n'
12899n/a 'multiple "with" statements were nested:\n'
12900n/a '\n'
12901n/a ' with A() as a, B() as b:\n'
12902n/a ' suite\n'
12903n/a '\n'
12904n/a 'is equivalent to\n'
12905n/a '\n'
12906n/a ' with A() as a:\n'
12907n/a ' with B() as b:\n'
12908n/a ' suite\n'
12909n/a '\n'
12910n/a 'Changed in version 3.1: Support for multiple context expressions.\n'
12911n/a '\n'
12912n/a 'See also:\n'
12913n/a '\n'
12914n/a ' **PEP 343** - The "with" statement\n'
12915n/a ' The specification, background, and examples for the Python '
12916n/a '"with"\n'
12917n/a ' statement.\n',
12918n/a 'yield': '\n'
12919n/a 'The "yield" statement\n'
12920n/a '*********************\n'
12921n/a '\n'
12922n/a ' yield_stmt ::= yield_expression\n'
12923n/a '\n'
12924n/a 'A "yield" statement is semantically equivalent to a yield '
12925n/a 'expression.\n'
12926n/a 'The yield statement can be used to omit the parentheses that would\n'
12927n/a 'otherwise be required in the equivalent yield expression '
12928n/a 'statement.\n'
12929n/a 'For example, the yield statements\n'
12930n/a '\n'
12931n/a ' yield <expr>\n'
12932n/a ' yield from <expr>\n'
12933n/a '\n'
12934n/a 'are equivalent to the yield expression statements\n'
12935n/a '\n'
12936n/a ' (yield <expr>)\n'
12937n/a ' (yield from <expr>)\n'
12938n/a '\n'
12939n/a 'Yield expressions and statements are only used when defining a\n'
12940n/a '*generator* function, and are only used in the body of the '
12941n/a 'generator\n'
12942n/a 'function. Using yield in a function definition is sufficient to '
12943n/a 'cause\n'
12944n/a 'that definition to create a generator function instead of a normal\n'
12945n/a 'function.\n'
12946n/a '\n'
12947n/a 'For full details of "yield" semantics, refer to the Yield '
12948n/a 'expressions\n'
12949n/a 'section.\n'}