Newer
Older
topics = {'assert': 'The "assert" statement\n'
'**********************\n'
'\n'
'Assert statements are a convenient way to insert debugging '
'assertions\n'
'into a program:\n'
'\n'
' assert_stmt ::= "assert" expression ["," expression]\n'
'\n'
'The simple form, "assert expression", is equivalent to\n'
'\n'
' if __debug__:\n'
' if not expression: raise AssertionError\n'
'\n'
'The extended form, "assert expression1, expression2", is '
'equivalent to\n'
'\n'
' if __debug__:\n'
' if not expression1: raise AssertionError(expression2)\n'
'\n'
'These equivalences assume that "__debug__" and "AssertionError" '
'refer\n'
'to the built-in variables with those names. In the current\n'
'implementation, the built-in variable "__debug__" is "True" under\n'
'normal circumstances, "False" when optimization is requested '
'(command\n'
'line option "-O"). The current code generator emits no code for '
'an\n'
'assert statement when optimization is requested at compile time. '
'Note\n'
'that it is unnecessary to include the source code for the '
'expression\n'
'that failed in the error message; it will be displayed as part of '
'the\n'
'stack trace.\n'
'\n'
'Assignments to "__debug__" are illegal. The value for the '
'built-in\n'
'variable is determined when the interpreter starts.\n',
'assignment': 'Assignment statements\n'
'*********************\n'
'\n'
'Assignment statements are used to (re)bind names to values and '
'to\n'
'modify attributes or items of mutable objects:\n'
'\n'
' assignment_stmt ::= (target_list "=")+ (starred_expression '
'| yield_expression)\n'
' target_list ::= target ("," target)* [","]\n'
' target ::= identifier\n'
' | "(" [target_list] ")"\n'
' | "[" [target_list] "]"\n'
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
' | attributeref\n'
' | subscription\n'
' | slicing\n'
' | "*" target\n'
'\n'
'(See section Primaries for the syntax definitions for '
'*attributeref*,\n'
'*subscription*, and *slicing*.)\n'
'\n'
'An assignment statement evaluates the expression list '
'(remember that\n'
'this can be a single expression or a comma-separated list, the '
'latter\n'
'yielding a tuple) and assigns the single resulting object to '
'each of\n'
'the target lists, from left to right.\n'
'\n'
'Assignment is defined recursively depending on the form of the '
'target\n'
'(list). When a target is part of a mutable object (an '
'attribute\n'
'reference, subscription or slicing), the mutable object must\n'
'ultimately perform the assignment and decide about its '
'validity, and\n'
'may raise an exception if the assignment is unacceptable. The '
'rules\n'
'observed by various types and the exceptions raised are given '
'with the\n'
'definition of the object types (see section The standard type\n'
'hierarchy).\n'
'\n'
'Assignment of an object to a target list, optionally enclosed '
'in\n'
'parentheses or square brackets, is recursively defined as '
'follows.\n'
'\n'
'* If the target list is a single target with no trailing '
'comma,\n'
' optionally in parentheses, the object is assigned to that '
'target.\n'
'* Else: The object must be an iterable with the same number of '
'items\n'
' as there are targets in the target list, and the items are '
'assigned,\n'
' from left to right, to the corresponding targets.\n'
' * If the target list contains one target prefixed with an '
'asterisk,\n'
' called a “starred” target: The object must be an iterable '
'with at\n'
' least as many items as there are targets in the target '
'list, minus\n'
' one. The first items of the iterable are assigned, from '
'left to\n'
' right, to the targets before the starred target. The '
'final items\n'
' of the iterable are assigned to the targets after the '
' target. A list of the remaining items in the iterable is '
'then\n'
' assigned to the starred target (the list can be empty).\n'
'\n'
' * Else: The object must be an iterable with the same number '
'of items\n'
' as there are targets in the target list, and the items '
'are\n'
' assigned, from left to right, to the corresponding '
'targets.\n'
'\n'
'Assignment of an object to a single target is recursively '
'defined as\n'
'follows.\n'
'\n'
'* If the target is an identifier (name):\n'
'\n'
' * If the name does not occur in a "global" or "nonlocal" '
'statement\n'
' in the current code block: the name is bound to the object '
'in the\n'
' current local namespace.\n'
'\n'
' * Otherwise: the name is bound to the object in the global '
'namespace\n'
' or the outer namespace determined by "nonlocal", '
'respectively.\n'
'\n'
' The name is rebound if it was already bound. This may cause '
'the\n'
' reference count for the object previously bound to the name '
'to reach\n'
' zero, causing the object to be deallocated and its '
'destructor (if it\n'
' has one) to be called.\n'
'\n'
'* If the target is an attribute reference: The primary '
'expression in\n'
' the reference is evaluated. It should yield an object with\n'
' assignable attributes; if this is not the case, "TypeError" '
'is\n'
' raised. That object is then asked to assign the assigned '
'object to\n'
' the given attribute; if it cannot perform the assignment, it '
'raises\n'
' an exception (usually but not necessarily '
'"AttributeError").\n'
'\n'
' Note: If the object is a class instance and the attribute '
'reference\n'
' occurs on both sides of the assignment operator, the '
'right-hand side\n'
' expression, "a.x" can access either an instance attribute or '
'(if no\n'
' instance attribute exists) a class attribute. The left-hand '
'side\n'
' target "a.x" is always set as an instance attribute, '
'creating it if\n'
' necessary. Thus, the two occurrences of "a.x" do not '
'necessarily\n'
' refer to the same attribute: if the right-hand side '
'expression\n'
' refers to a class attribute, the left-hand side creates a '
'new\n'
' instance attribute as the target of the assignment:\n'
'\n'
' class Cls:\n'
' x = 3 # class variable\n'
' inst = Cls()\n'
' inst.x = inst.x + 1 # writes inst.x as 4 leaving Cls.x '
'as 3\n'
'\n'
' This description does not necessarily apply to descriptor\n'
' attributes, such as properties created with "property()".\n'
'\n'
'* If the target is a subscription: The primary expression in '
'the\n'
' reference is evaluated. It should yield either a mutable '
'sequence\n'
' object (such as a list) or a mapping object (such as a '
'dictionary).\n'
' Next, the subscript expression is evaluated.\n'
'\n'
' If the primary is a mutable sequence object (such as a '
'list), the\n'
' subscript must yield an integer. If it is negative, the '
' length is added to it. The resulting value must be a '
'nonnegative\n'
' integer less than the sequence’s length, and the sequence is '
'asked\n'
' to assign the assigned object to its item with that index. '
'If the\n'
' index is out of range, "IndexError" is raised (assignment to '
'a\n'
' subscripted sequence cannot add new items to a list).\n'
'\n'
' If the primary is a mapping object (such as a dictionary), '
'the\n'
' subscript must have a type compatible with the mapping’s key '
'type,\n'
' and the mapping is then asked to create a key/datum pair '
'which maps\n'
' the subscript to the assigned object. This can either '
'replace an\n'
' existing key/value pair with the same key value, or insert a '
'new\n'
' key/value pair (if no key with the same value existed).\n'
'\n'
' For user-defined objects, the "__setitem__()" method is '
'called with\n'
' appropriate arguments.\n'
'\n'
'* If the target is a slicing: The primary expression in the '
'reference\n'
' is evaluated. It should yield a mutable sequence object '
'(such as a\n'
' list). The assigned object should be a sequence object of '
'the same\n'
' type. Next, the lower and upper bound expressions are '
'evaluated,\n'
' insofar they are present; defaults are zero and the '
' length. The bounds should evaluate to integers. If either '
'bound is\n'
' negative, the sequence’s length is added to it. The '
'resulting\n'
' bounds are clipped to lie between zero and the sequence’s '
'length,\n'
' inclusive. Finally, the sequence object is asked to replace '
'the\n'
' slice with the items of the assigned sequence. The length '
'of the\n'
' slice may be different from the length of the assigned '
'sequence,\n'
' thus changing the length of the target sequence, if the '
'target\n'
' sequence allows it.\n'
'\n'
'**CPython implementation detail:** In the current '
'implementation, the\n'
'syntax for targets is taken to be the same as for expressions, '
'and\n'
'invalid syntax is rejected during the code generation phase, '
'causing\n'
'less detailed error messages.\n'
'\n'
'Although the definition of assignment implies that overlaps '
'between\n'
'the left-hand side and the right-hand side are ‘simultaneous’ '
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
'(for\n'
'example "a, b = b, a" swaps two variables), overlaps *within* '
'the\n'
'collection of assigned-to variables occur left-to-right, '
'sometimes\n'
'resulting in confusion. For instance, the following program '
'prints\n'
'"[0, 2]":\n'
'\n'
' x = [0, 1]\n'
' i = 0\n'
' i, x[i] = 1, 2 # i is updated, then x[i] is '
'updated\n'
' print(x)\n'
'\n'
'See also:\n'
'\n'
' **PEP 3132** - Extended Iterable Unpacking\n'
' The specification for the "*target" feature.\n'
'\n'
'\n'
'Augmented assignment statements\n'
'===============================\n'
'\n'
'Augmented assignment is the combination, in a single '
'statement, of a\n'
'binary operation and an assignment statement:\n'
'\n'
' augmented_assignment_stmt ::= augtarget augop '
'(expression_list | yield_expression)\n'
' augtarget ::= identifier | attributeref | '
'subscription | slicing\n'
' augop ::= "+=" | "-=" | "*=" | "@=" | '
'"/=" | "//=" | "%=" | "**="\n'
' | ">>=" | "<<=" | "&=" | "^=" | "|="\n'
'\n'
'(See section Primaries for the syntax definitions of the last '
'three\n'
'symbols.)\n'
'\n'
'An augmented assignment evaluates the target (which, unlike '
'normal\n'
'assignment statements, cannot be an unpacking) and the '
'expression\n'
'list, performs the binary operation specific to the type of '
'assignment\n'
'on the two operands, and assigns the result to the original '
'target.\n'
'The target is only evaluated once.\n'
'\n'
'An augmented assignment expression like "x += 1" can be '
'rewritten as\n'
'"x = x + 1" to achieve a similar, but not exactly equal '
'effect. In the\n'
'augmented version, "x" is only evaluated once. Also, when '
'possible,\n'
'the actual operation is performed *in-place*, meaning that '
'rather than\n'
'creating a new object and assigning that to the target, the '
'old object\n'
'is modified instead.\n'
'\n'
'Unlike normal assignments, augmented assignments evaluate the '
'left-\n'
'hand side *before* evaluating the right-hand side. For '
'example, "a[i]\n'
'+= f(x)" first looks-up "a[i]", then it evaluates "f(x)" and '
'performs\n'
'the addition, and lastly, it writes the result back to '
'"a[i]".\n'
'\n'
'With the exception of assigning to tuples and multiple targets '
'in a\n'
'single statement, the assignment done by augmented assignment\n'
'statements is handled the same way as normal assignments. '
'Similarly,\n'
'with the exception of the possible *in-place* behavior, the '
'binary\n'
'operation performed by augmented assignment is the same as the '
'normal\n'
'binary operations.\n'
'\n'
'For targets which are attribute references, the same caveat '
'about\n'
'class and instance attributes applies as for regular '
'assignments.\n'
'\n'
'\n'
'Annotated assignment statements\n'
'===============================\n'
'\n'
'*Annotation* assignment is the combination, in a single '
'statement, of\n'
'a variable or attribute annotation and an optional assignment\n'
' annotated_assignment_stmt ::= augtarget ":" expression\n'
' ["=" (starred_expression | '
'yield_expression)]\n'
'\n'
'The difference from normal Assignment statements is that only '
'single\n'
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
'\n'
'For simple names as assignment targets, if in class or module '
'scope,\n'
'the annotations are evaluated and stored in a special class or '
'module\n'
'attribute "__annotations__" that is a dictionary mapping from '
'variable\n'
'names (mangled if private) to evaluated annotations. This '
'attribute is\n'
'writable and is automatically created at the start of class or '
'module\n'
'body execution, if annotations are found statically.\n'
'\n'
'For expressions as assignment targets, the annotations are '
'evaluated\n'
'if in class or module scope, but not stored.\n'
'\n'
'If a name is annotated in a function scope, then this name is '
'local\n'
'for that scope. Annotations are never evaluated and stored in '
'function\n'
'scopes.\n'
'\n'
'If the right hand side is present, an annotated assignment '
'performs\n'
'the actual assignment before evaluating annotations (where\n'
'applicable). If the right hand side is not present for an '
'expression\n'
'target, then the interpreter evaluates the target except for '
'the last\n'
'"__setitem__()" or "__setattr__()" call.\n'
'\n'
'See also:\n'
'\n'
' **PEP 526** - Syntax for Variable Annotations\n'
' The proposal that added syntax for annotating the types '
'of\n'
' variables (including class variables and instance '
'variables),\n'
' instead of expressing them through comments.\n'
'\n'
' **PEP 484** - Type hints\n'
' The proposal that added the "typing" module to provide a '
'standard\n'
' syntax for type annotations that can be used in static '
'analysis\n'
' tools and IDEs.\n'
'\n'
'Changed in version 3.8: Now annotated assignments allow same\n'
'expressions in the right hand side as the regular '
'assignments.\n'
'Previously, some expressions (like un-parenthesized tuple '
'expressions)\n'
'caused a syntax error.\n',
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
'async': 'Coroutines\n'
'**********\n'
'\n'
'New in version 3.5.\n'
'\n'
'\n'
'Coroutine function definition\n'
'=============================\n'
'\n'
' async_funcdef ::= [decorators] "async" "def" funcname "(" '
'[parameter_list] ")"\n'
' ["->" expression] ":" suite\n'
'\n'
'Execution of Python coroutines can be suspended and resumed at '
'many\n'
'points (see *coroutine*). Inside the body of a coroutine '
'function,\n'
'"await" and "async" identifiers become reserved keywords; "await"\n'
'expressions, "async for" and "async with" can only be used in\n'
'coroutine function bodies.\n'
'\n'
'Functions defined with "async def" syntax are always coroutine\n'
'functions, even if they do not contain "await" or "async" '
'keywords.\n'
'\n'
'It is a "SyntaxError" to use a "yield from" expression inside the '
'body\n'
'of a coroutine function.\n'
'\n'
'An example of a coroutine function:\n'
'\n'
' async def func(param1, param2):\n'
' do_stuff()\n'
' await some_coroutine()\n'
'\n'
'\n'
'The "async for" statement\n'
'=========================\n'
'\n'
' async_for_stmt ::= "async" for_stmt\n'
'\n'
'An *asynchronous iterable* is able to call asynchronous code in '
'its\n'
'*iter* implementation, and *asynchronous iterator* can call\n'
'asynchronous code in its *next* method.\n'
'\n'
'The "async for" statement allows convenient iteration over\n'
'asynchronous iterators.\n'
'\n'
'The following code:\n'
'\n'
' async for TARGET in ITER:\n'
'\n'
'Is semantically equivalent to:\n'
'\n'
' iter = (ITER)\n'
' iter = type(iter).__aiter__(iter)\n'
' running = True\n'
' while running:\n'
' try:\n'
' TARGET = await type(iter).__anext__(iter)\n'
' except StopAsyncIteration:\n'
' running = False\n'
' else:\n'
'\n'
'See also "__aiter__()" and "__anext__()" for details.\n'
'\n'
'It is a "SyntaxError" to use an "async for" statement outside the '
'body\n'
'of a coroutine function.\n'
'\n'
'\n'
'The "async with" statement\n'
'==========================\n'
'\n'
' async_with_stmt ::= "async" with_stmt\n'
'\n'
'An *asynchronous context manager* is a *context manager* that is '
'able\n'
'to suspend execution in its *enter* and *exit* methods.\n'
'\n'
'The following code:\n'
'\n'
' manager = (EXPRESSION)\n'
' aenter = type(manager).__aenter__\n'
' aexit = type(manager).__aexit__\n'
' value = await aenter(manager)\n'
' hit_except = False\n'
' hit_except = True\n'
' if not await aexit(manager, *sys.exc_info()):\n'
' finally:\n'
' if not hit_except:\n'
' await aexit(manager, None, None, None)\n'
'\n'
'See also "__aenter__()" and "__aexit__()" for details.\n'
'\n'
'It is a "SyntaxError" to use an "async with" statement outside the\n'
'body of a coroutine function.\n'
'\n'
'See also:\n'
'\n'
' **PEP 492** - Coroutines with async and await syntax\n'
' The proposal that made coroutines a proper standalone concept '
'in\n'
' Python, and added supporting syntax.\n'
'\n'
'-[ Footnotes ]-\n'
'\n'
'[1] The exception is propagated to the invocation stack unless '
'there\n'
' is a "finally" clause which happens to raise another '
'exception.\n'
' That new exception causes the old one to be lost.\n'
'[2] A string literal appearing as the first statement in the '
'function\n'
' body is transformed into the function’s "__doc__" attribute '
'and\n'
' therefore the function’s *docstring*.\n'
'\n'
'[3] A string literal appearing as the first statement in the class\n'
' body is transformed into the namespace’s "__doc__" item and\n'
' therefore the classLoading
Loading full blame…