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'
' aexit = type(manager).__aexit__\n'
' aenter = type(manager).__aenter__\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 class’s *docstring*.\n',
'atom-identifiers': 'Identifiers (Names)\n'
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
'*******************\n'
'\n'
'An identifier occurring as an atom is a name. See '
'section Identifiers\n'
'and keywords for lexical definition and section Naming '
'and binding for\n'
'documentation of naming and binding.\n'
'\n'
'When the name is bound to an object, evaluation of the '
'atom yields\n'
'that object. When a name is not bound, an attempt to '
'evaluate it\n'
'raises a "NameError" exception.\n'
'\n'
'**Private name mangling:** When an identifier that '
'textually occurs in\n'
'a class definition begins with two or more underscore '
'characters and\n'
'does not end in two or more underscores, it is '
'considered a *private\n'
'name* of that class. Private names are transformed to a '
'longer form\n'
'before code is generated for them. The transformation '
'inserts the\n'
'class name, with leading underscores removed and a '
'single underscore\n'
'inserted, in front of the name. For example, the '
'identifier "__spam"\n'
'occurring in a class named "Ham" will be transformed to '
'"_Ham__spam".\n'
'This transformation is independent of the syntactical '
'context in which\n'
'the identifier is used. If the transformed name is '
'extremely long\n'
'(longer than 255 characters), implementation defined '
'truncation may\n'
'happen. If the class name consists only of underscores, '
'no\n'
'transformation is done.\n',
'atom-literals': 'Literals\n'
'********\n'
'\n'
'Python supports string and bytes literals and various '
'numeric\n'
'literals:\n'
'\n'
' literal ::= stringliteral | bytesliteral\n'
' | integer | floatnumber | imagnumber\n'
'\n'
'Evaluation of a literal yields an object of the given type '
'(string,\n'
'bytes, integer, floating point number, complex number) with '
'the given\n'
'value. The value may be approximated in the case of '
'floating point\n'
'and imaginary (complex) literals. See section Literals for '
'details.\n'
'\n'
'All literals correspond to immutable data types, and hence '
'the\n'
'object’s identity is less important than its value. '
'Multiple\n'
'evaluations of literals with the same value (either the '
'same\n'
'occurrence in the program text or a different occurrence) '
'may obtain\n'
'the same object or a different object with the same '
'value.\n',
'attribute-access': 'Customizing attribute access\n'
'****************************\n'
'\n'
'The following methods can be defined to customize the '
'meaning of\n'
'attribute access (use of, assignment to, or deletion of '
'"x.name") for\n'
'class instances.\n'
'\n'
'object.__getattr__(self, name)\n'
'\n'
' Called when the default attribute access fails with '
'an\n'
' "AttributeError" (either "__getattribute__()" raises '
'an\n'
' "AttributeError" because *name* is not an instance '
'attribute or an\n'
' attribute in the class tree for "self"; or '
'"__get__()" of a *name*\n'
' property raises "AttributeError"). This method '
'should either\n'
' return the (computed) attribute value or raise an '
'"AttributeError"\n'
' exception.\n'
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
'\n'
' Note that if the attribute is found through the '
'normal mechanism,\n'
' "__getattr__()" is not called. (This is an '
'intentional asymmetry\n'
' between "__getattr__()" and "__setattr__()".) This is '
'done both for\n'
' efficiency reasons and because otherwise '
'"__getattr__()" would have\n'
' no way to access other attributes of the instance. '
'Note that at\n'
' least for instance variables, you can fake total '
'control by not\n'
' inserting any values in the instance attribute '
'dictionary (but\n'
' instead inserting them in another object). See the\n'
' "__getattribute__()" method below for a way to '
'actually get total\n'
' control over attribute access.\n'
'\n'
'object.__getattribute__(self, name)\n'
'\n'
' Called unconditionally to implement attribute '
'accesses for\n'
' instances of the class. If the class also defines '
'"__getattr__()",\n'
' the latter will not be called unless '
'"__getattribute__()" either\n'
' calls it explicitly or raises an "AttributeError". '
'This method\n'
' should return the (computed) attribute value or raise '
'an\n'
' "AttributeError" exception. In order to avoid '
'infinite recursion in\n'
' this method, its implementation should always call '
'the base class\n'
' method with the same name to access any attributes it '
'needs, for\n'
' example, "object.__getattribute__(self, name)".\n'
'\n'
' Note:\n'
'\n'
' This method may still be bypassed when looking up '
'special methods\n'
' as the result of implicit invocation via language '
'syntax or\n'
' built-in functions. See Special method lookup.\n'
'\n'
' For certain sensitive attribute accesses, raises an '
'auditing event\n'
' "object.__getattr__" with arguments "obj" and '
'"name".\n'
'\n'
'object.__setattr__(self, name, value)\n'
'\n'
' Called when an attribute assignment is attempted. '
'This is called\n'
' instead of the normal mechanism (i.e. store the value '
'in the\n'
' instance dictionary). *name* is the attribute name, '
'*value* is the\n'
' value to be assigned to it.\n'
'\n'
' If "__setattr__()" wants to assign to an instance '
'attribute, it\n'
' should call the base class method with the same name, '
'for example,\n'
' "object.__setattr__(self, name, value)".\n'
'\n'
' For certain sensitive attribute assignments, raises '
'an auditing\n'
' event "object.__setattr__" with arguments "obj", '
'"name", "value".\n'
'\n'
'object.__delattr__(self, name)\n'
'\n'
' Like "__setattr__()" but for attribute deletion '
'instead of\n'
' assignment. This should only be implemented if "del '
'obj.name" is\n'
' meaningful for the object.\n'
'\n'
' For certain sensitive attribute deletions, raises an '
'auditing event\n'
' "object.__delattr__" with arguments "obj" and '
'"name".\n'
'\n'
'object.__dir__(self)\n'
'\n'
' Called when "dir()" is called on the object. A '
'sequence must be\n'
' returned. "dir()" converts the returned sequence to a '
'list and\n'
' sorts it.\n'
'\n'
'\n'
'Customizing module attribute access\n'
'===================================\n'
'\n'
'Special names "__getattr__" and "__dir__" can be also '
'used to\n'
'customize access to module attributes. The "__getattr__" '
'function at\n'
'the module level should accept one argument which is the '
'name of an\n'
'attribute and return the computed value or raise an '
'"AttributeError".\n'
'If an attribute is not found on a module object through '
'the normal\n'
'lookup, i.e. "object.__getattribute__()", then '
'"__getattr__" is\n'
'searched in the module "__dict__" before raising an '
'"AttributeError".\n'
'If found, it is called with the attribute name and the '
'result is\n'
'returned.\n'
'\n'
'The "__dir__" function should accept no arguments, and '
'return a\n'
'sequence of strings that represents the names accessible '
'on module. If\n'
'present, this function overrides the standard "dir()" '
'search on a\n'
'module.\n'
'\n'
'For a more fine grained customization of the module '
'behavior (setting\n'
'attributes, properties, etc.), one can set the '
'"__class__" attribute\n'
'of a module object to a subclass of "types.ModuleType". '
'For example:\n'
'\n'
' import sys\n'
' from types import ModuleType\n'
'\n'
' class VerboseModule(ModuleType):\n'
' def __repr__(self):\n'
" return f'Verbose {self.__name__}'\n"
'\n'
' def __setattr__(self, attr, value):\n'
" print(f'Setting {attr}...')\n"
' super().__setattr__(attr, value)\n'
'\n'
' sys.modules[__name__].__class__ = VerboseModule\n'
'\n'
'Note:\n'
'\n'
' Defining module "__getattr__" and setting module '
'"__class__" only\n'
' affect lookups made using the attribute access syntax '
'– directly\n'
' accessing the module globals (whether by code within '
'the module, or\n'
' via a reference to the module’s globals dictionary) is '
'unaffected.\n'
'Changed in version 3.5: "__class__" module attribute is '
'now writable.\n'
'\n'
'New in version 3.7: "__getattr__" and "__dir__" module '
'attributes.\n'
'\n'
'See also:\n'
'\n'
' **PEP 562** - Module __getattr__ and __dir__\n'
' Describes the "__getattr__" and "__dir__" functions '
'on modules.\n'
'\n'
'Implementing Descriptors\n'
'========================\n'
'\n'
'The following methods only apply when an instance of the '
'class\n'
'containing the method (a so-called *descriptor* class) '
'appears in an\n'
'*owner* class (the descriptor must be in either the '
'dictionary or in the class dictionary for one of its '
'parents). In the\n'
'examples below, “the attribute” refers to the attribute '
'the key of the property in the owner class’ "__dict__".\n'
'\n'
' Called to get the attribute of the owner class (class '
'attribute\n'
' access) or of an instance of that class (instance '
'attribute\n'
' access). The optional *owner* argument is the owner '
'class, while\n'
' *instance* is the instance that the attribute was '
'accessed through,\n'
' or "None" when the attribute is accessed through the '
'*owner*.\n'
'\n'
' This method should return the computed attribute '
'value or raise an\n'
' "AttributeError" exception.\n'
'\n'
' **PEP 252** specifies that "__get__()" is callable '
'with one or two\n'
' arguments. Python’s own built-in descriptors support '
'this\n'
' specification; however, it is likely that some '
'third-party tools\n'
' have descriptors that require both arguments. '
'Python’s own\n'
' "__getattribute__()" implementation always passes in '
'both arguments\n'
' whether they are required or not.\n'
'\n'
'object.__set__(self, instance, value)\n'
'\n'
' Called to set the attribute on an instance *instance* '
'of the owner\n'
' class to a new value, *value*.\n'
'\n'
' Note, adding "__set__()" or "__delete__()" changes '
'the kind of\n'
' descriptor to a “data descriptor”. See Invoking '
'Descriptors for\n'
' more details.\n'
'\n'
'object.__delete__(self, instance)\n'
'\n'
' Called to delete the attribute on an instance '
'*instance* of the\n'
' owner class.\n'
'\n'
'object.__set_name__(self, owner, name)\n'
'\n'
' Called at the time the owning class *owner* is '
'created. The\n'
' descriptor has been assigned to *name*.\n'
'\n'
' Note:\n'
'\n'
' "__set_name__()" is only called implicitly as part '
'of the "type"\n'
' constructor, so it will need to be called '
'explicitly with the\n'
' appropriate parameters when a descriptor is added '
'to a class\n'
' after initial creation:\n'
'\n'
' class A:\n'
' pass\n'
' descr = custom_descriptor()\n'
' A.attr = descr\n'
" descr.__set_name__(A, 'attr')\n"
'\n'
' See Creating the class object for more details.\n'
'\n'
'The attribute "__objclass__" is interpreted by the '
'"inspect" module as\n'
'specifying the class where this object was defined '
'(setting this\n'
'appropriately can assist in runtime introspection of '
'dynamic class\n'
'attributes). For callables, it may indicate that an '
'instance of the\n'
'given type (or a subclass) is expected or required as '
'the first\n'
'positional argument (for example, CPython sets this '
'attribute for\n'
'unbound methods that are implemented in C).\n'
'\n'
'\n'
'Invoking Descriptors\n'
'====================\n'
'\n'
'In general, a descriptor is an object attribute with '
'“binding\n'
'behavior”, one whose attribute access has been '
'overridden by methods\n'
'in the descriptor protocol: "__get__()", "__set__()", '
'and\n'
'"__delete__()". If any of those methods are defined for '
'an object, it\n'
'is said to be a descriptor.\n'
'\n'
'The default behavior for attribute access is to get, '
'set, or delete\n'
'the attribute from an object’s dictionary. For instance, '
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
'"a.x" has a\n'
'lookup chain starting with "a.__dict__[\'x\']", then\n'
'"type(a).__dict__[\'x\']", and continuing through the '
'base classes of\n'
'"type(a)" excluding metaclasses.\n'
'\n'
'However, if the looked-up value is an object defining '
'one of the\n'
'descriptor methods, then Python may override the default '
'behavior and\n'
'invoke the descriptor method instead. Where this occurs '
'in the\n'
'precedence chain depends on which descriptor methods '
'were defined and\n'
'how they were called.\n'
'\n'
'The starting point for descriptor invocation is a '
'binding, "a.x". How\n'
'the arguments are assembled depends on "a":\n'
'\n'
'Direct Call\n'
' The simplest and least common call is when user code '
'directly\n'
' invokes a descriptor method: "x.__get__(a)".\n'
'\n'
'Instance Binding\n'
' If binding to an object instance, "a.x" is '
'transformed into the\n'
' call: "type(a).__dict__[\'x\'].__get__(a, type(a))".\n'
'\n'
'Class Binding\n'
' If binding to a class, "A.x" is transformed into the '
'call:\n'
' "A.__dict__[\'x\'].__get__(None, A)".\n'
'\n'
'Super Binding\n'
' If "a" is an instance of "super", then the binding '
'"super(B,\n'
' obj).m()" searches "obj.__class__.__mro__" for the '
'base class "A"\n'
' immediately preceding "B" and then invokes the '
'descriptor with the\n'
' call: "A.__dict__[\'m\'].__get__(obj, '
'obj.__class__)".\n'
'\n'
'For instance bindings, the precedence of descriptor '
'invocation depends\n'
'on which descriptor methods are defined. A descriptor '
'can define any\n'
'combination of "__get__()", "__set__()" and '
'"__delete__()". If it\n'
'does not define "__get__()", then accessing the '
'attribute will return\n'
'the descriptor object itself unless there is a value in '
'instance dictionary. If the descriptor defines '
'"__set__()" and/or\n'
'"__delete__()", it is a data descriptor; if it defines '