ยป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'