Skip to content
Snippets Groups Projects
topics.py 736 KiB
Newer Older
  • Learn to ignore specific revisions
  • Georg Brandl's avatar
    Georg Brandl committed
    # -*- coding: utf-8 -*-
    
    Pablo Galindo's avatar
    Pablo Galindo committed
    # Autogenerated by Sphinx on Mon Jul 25 23:19:30 2022
    
    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'
    
                   '              | 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'
    
    Pablo Galindo's avatar
    Pablo Galindo committed
                   '* Else:\n'
    
    Pablo Galindo's avatar
    Pablo Galindo committed
                   '  * 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 '
    
                   'starred\n'
    
    Pablo Galindo's avatar
    Pablo Galindo committed
                   '    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 '
    
    Pablo Galindo's avatar
    Pablo Galindo committed
                   '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'
    
    Pablo Galindo's avatar
    Pablo Galindo committed
                   '  * 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'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                   '  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 '
    
                   'sequence’s\n'
    
                   '  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'
    
    Pablo Galindo's avatar
    Pablo Galindo committed
                   '* 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 '
    
                   'sequence’s\n'
    
    Pablo Galindo's avatar
    Pablo Galindo committed
                   '  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’ '
    
                   '(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'
    
                   'statement:\n'
                   '\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                   '   annotated_assignment_stmt ::= augtarget ":" expression\n'
                   '                                 ["=" (starred_expression | '
                   'yield_expression)]\n'
    
                   '\n'
                   'The difference from normal Assignment statements is that only '
                   'single\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                   'target is allowed.\n'
    
                   '\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'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                   '     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',
    
     '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'
    
    Pablo Galindo's avatar
    Pablo Galindo committed
              'points (see *coroutine*). "await" expressions, "async for" and '
              '"async\n'
              'with" can only be used in the body of a coroutine function.\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'
    
    Pablo Galindo's avatar
    Pablo Galindo committed
              'Changed in version 3.7: "await" and "async" are now keywords;\n'
              'previously they were only treated as such inside the body of a\n'
              'coroutine function.\n'
              '\n'
    
              '\n'
              'The "async for" statement\n'
              '=========================\n'
              '\n'
              '   async_for_stmt ::= "async" for_stmt\n'
              '\n'
    
    Pablo Galindo's avatar
    Pablo Galindo committed
              'An *asynchronous iterable* provides an "__aiter__" method that\n'
              'directly returns an *asynchronous iterator*, which can call\n'
              'asynchronous code in its "__anext__" method.\n'
    
              '\n'
              'The "async for" statement allows convenient iteration over\n'
    
    Pablo Galindo's avatar
    Pablo Galindo committed
              'asynchronous iterables.\n'
    
              '\n'
              'The following code:\n'
              '\n'
              '   async for TARGET in ITER:\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
              '       SUITE\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
              '       SUITE2\n'
    
              '\n'
              'Is semantically equivalent to:\n'
              '\n'
              '   iter = (ITER)\n'
              '   iter = type(iter).__aiter__(iter)\n'
              '   running = True\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
              '\n'
    
              '   while running:\n'
              '       try:\n'
              '           TARGET = await type(iter).__anext__(iter)\n'
              '       except StopAsyncIteration:\n'
              '           running = False\n'
              '       else:\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
              '           SUITE\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
              '       SUITE2\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'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
              '   async with EXPRESSION as TARGET:\n'
              '       SUITE\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
              'is semantically equivalent to:\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
              '   manager = (EXPRESSION)\n'
              '   aenter = type(manager).__aenter__\n'
              '   aexit = type(manager).__aexit__\n'
              '   value = await aenter(manager)\n'
              '   hit_except = False\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
              '       TARGET = value\n'
              '       SUITE\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
              '       hit_except = True\n'
              '       if not await aexit(manager, *sys.exc_info()):\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
              '   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'
    
    Pablo Galindo's avatar
    Pablo Galindo committed
              '[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'
    
    Pablo Galindo's avatar
    Pablo Galindo committed
              '[2] In pattern matching, a sequence is defined as one of the\n'
              '    following:\n'
              '\n'
              '       * a class that inherits from "collections.abc.Sequence"\n'
              '\n'
              '       * a Python class that has been registered as\n'
              '         "collections.abc.Sequence"\n'
              '\n'
              '       * a builtin class that has its (CPython) '
              '"Py_TPFLAGS_SEQUENCE"\n'
              '         bit set\n'
              '\n'
              '       * a class that inherits from any of the above\n'
              '\n'
              '    The following standard library classes are sequences:\n'
              '\n'
              '       * "array.array"\n'
              '\n'
              '       * "collections.deque"\n'
              '\n'
              '       * "list"\n'
              '\n'
              '       * "memoryview"\n'
              '\n'
              '       * "range"\n'
              '\n'
              '       * "tuple"\n'
              '\n'
              '    Note:\n'
              '\n'
              '      Subject values of type "str", "bytes", and "bytearray" do '
              'not\n'
              '      match sequence patterns.\n'
              '\n'
              '[3] In pattern matching, a mapping is defined as one of the '
              'following:\n'
              '\n'
              '       * a class that inherits from "collections.abc.Mapping"\n'
              '\n'
              '       * a Python class that has been registered as\n'
              '         "collections.abc.Mapping"\n'
              '\n'
              '       * a builtin class that has its (CPython) '
              '"Py_TPFLAGS_MAPPING"\n'
              '         bit set\n'
              '\n'
              '       * a class that inherits from any of the above\n'
              '\n'
              '    The standard library classes "dict" and '
              '"types.MappingProxyType"\n'
              '    are mappings.\n'
              '\n'
              '[4] A string literal appearing as the first statement in the '
    
    Pablo Galindo's avatar
    Pablo Galindo committed
              'function\n'
              '    body is transformed into the function’s "__doc__" attribute '
              'and\n'
              '    therefore the function’s *docstring*.\n'
    
    Pablo Galindo's avatar
    Pablo Galindo committed
              '[5] 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'
    
                         '*******************\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'
    
                         '\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'
    
    Pablo Galindo's avatar
    Pablo Galindo committed
                         '   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'
    
    Pablo Galindo's avatar
    Pablo Galindo committed
                         '   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'
    
    Pablo Galindo's avatar
    Pablo Galindo committed
                         '   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'
    
    Pablo Galindo's avatar
    Pablo Galindo committed
                         '   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'
    
    Ned Deily's avatar
    Ned Deily committed
                         '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 '
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                         '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'
    
    Ned Deily's avatar
    Ned Deily committed
                         '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'
    
    Ned Deily's avatar
    Ned Deily committed
                         '\n'
                         '   sys.modules[__name__].__class__ = VerboseModule\n'
                         '\n'
    
    Pablo Galindo's avatar
    Pablo Galindo committed
                         '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'
    
    Ned Deily's avatar
    Ned Deily committed
                         '\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'
    
    Ned Deily's avatar
    Ned Deily committed
                         '\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 '
    
                         'owner’s class\n'
    
                         'dictionary or in the class dictionary for one of its '
                         'parents).  In the\n'
    
                         'examples below, “the attribute” refers to the attribute '
    
                         'whose name is\n'
    
                         'the key of the property in the owner class’ "__dict__".\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                         'object.__get__(self, instance, owner=None)\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'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                         '   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'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                         '   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'
                         '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, '
    
                         '"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'