Skip to content
Snippets Groups Projects
topics.py 669 KiB
Newer Older
  • Learn to ignore specific revisions
  •                      'neither, it is\n'
                         'a non-data descriptor.  Normally, data descriptors '
                         'define both\n'
                         '"__get__()" and "__set__()", while non-data descriptors '
                         'have just the\n'
                         '"__get__()" method.  Data descriptors with "__set__()" '
                         'and "__get__()"\n'
                         'defined always override a redefinition in an instance '
                         'dictionary.  In\n'
                         'contrast, non-data descriptors can be overridden by '
                         'instances.\n'
                         '\n'
                         'Python methods (including "staticmethod()" and '
                         '"classmethod()") are\n'
                         'implemented as non-data descriptors.  Accordingly, '
                         'instances can\n'
                         'redefine and override methods.  This allows individual '
                         'instances to\n'
                         'acquire behaviors that differ from other instances of '
                         'the same class.\n'
                         '\n'
                         'The "property()" function is implemented as a data '
                         'descriptor.\n'
                         'Accordingly, instances cannot override the behavior of a '
                         'property.\n'
                         '\n'
                         '\n'
                         '__slots__\n'
                         '=========\n'
                         '\n'
    
                         '*__slots__* allow us to explicitly declare data members '
                         '(like\n'
                         'properties) and deny the creation of *__dict__* and '
                         '*__weakref__*\n'
                         '(unless explicitly declared in *__slots__* or available '
                         'in a parent.)\n'
    
                         'The space saved over using *__dict__* can be '
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                         'significant. Attribute\n'
                         'lookup speed can be significantly improved as well.\n'
    
                         '\n'
                         'object.__slots__\n'
                         '\n'
                         '   This class variable can be assigned a string, '
                         'iterable, or sequence\n'
                         '   of strings with variable names used by instances.  '
                         '*__slots__*\n'
                         '   reserves space for the declared variables and '
                         'prevents the\n'
                         '   automatic creation of *__dict__* and *__weakref__* '
                         'for each\n'
                         '   instance.\n'
                         '\n'
                         '\n'
                         'Notes on using *__slots__*\n'
                         '--------------------------\n'
                         '\n'
                         '* When inheriting from a class without *__slots__*, the '
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                         '*__dict__* and\n'
                         '  *__weakref__* attribute of the instances will always '
                         'be accessible.\n'
    
                         '\n'
                         '* Without a *__dict__* variable, instances cannot be '
                         'assigned new\n'
                         '  variables not listed in the *__slots__* definition.  '
                         'Attempts to\n'
                         '  assign to an unlisted variable name raises '
                         '"AttributeError". If\n'
                         '  dynamic assignment of new variables is desired, then '
                         'add\n'
                         '  "\'__dict__\'" to the sequence of strings in the '
                         '*__slots__*\n'
                         '  declaration.\n'
                         '\n'
                         '* Without a *__weakref__* variable for each instance, '
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                         'classes defining\n'
                         '  *__slots__* do not support weak references to its '
                         'instances. If weak\n'
                         '  reference support is needed, then add '
                         '"\'__weakref__\'" to the\n'
                         '  sequence of strings in the *__slots__* declaration.\n'
    
                         '\n'
                         '* *__slots__* are implemented at the class level by '
                         'creating\n'
                         '  descriptors (Implementing Descriptors) for each '
                         'variable name.  As a\n'
                         '  result, class attributes cannot be used to set default '
                         'values for\n'
                         '  instance variables defined by *__slots__*; otherwise, '
                         'the class\n'
                         '  attribute would overwrite the descriptor assignment.\n'
                         '\n'
    
                         '* The action of a *__slots__* declaration is not limited '
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                         'to the class\n'
                         '  where it is defined.  *__slots__* declared in parents '
                         'are available\n'
                         '  in child classes. However, child subclasses will get a '
                         '*__dict__*\n'
                         '  and *__weakref__* unless they also define *__slots__* '
                         '(which should\n'
                         '  only contain names of any *additional* slots).\n'
    
                         '\n'
                         '* If a class defines a slot also defined in a base '
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                         'class, the instance\n'
                         '  variable defined by the base class slot is '
                         'inaccessible (except by\n'
                         '  retrieving its descriptor directly from the base '
                         'class). This\n'
                         '  renders the meaning of the program undefined.  In the '
                         'future, a\n'
    
                         '  check may be added to prevent this.\n'
                         '\n'
                         '* Nonempty *__slots__* does not work for classes derived '
                         'from\n'
    
                         '  “variable-length” built-in types such as "int", '
    
                         '"bytes" and "tuple".\n'
                         '\n'
                         '* Any non-string iterable may be assigned to '
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                         '*__slots__*. Mappings may\n'
                         '  also be used; however, in the future, special meaning '
                         'may be\n'
    
                         '  assigned to the values corresponding to each key.\n'
                         '\n'
                         '* *__class__* assignment works only if both classes have '
                         'the same\n'
    
                         '  *__slots__*.\n'
                         '\n'
                         '* Multiple inheritance with multiple slotted parent '
                         'classes can be\n'
                         '  used, but only one parent is allowed to have '
                         'attributes created by\n'
                         '  slots (the other bases must have empty slot layouts) - '
                         'violations\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                         '  raise "TypeError".\n'
                         '\n'
                         '* If an iterator is used for *__slots__* then a '
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                         'descriptor is created\n'
                         '  for each of the iterator’s values. However, the '
                         '*__slots__*\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                         '  attribute will be an empty iterator.\n',
    
     'attribute-references': 'Attribute references\n'
    
                             '********************\n'
                             '\n'
                             'An attribute reference is a primary followed by a '
                             'period and a name:\n'
                             '\n'
                             '   attributeref ::= primary "." identifier\n'
                             '\n'
                             'The primary must evaluate to an object of a type '
                             'that supports\n'
                             'attribute references, which most objects do.  This '
                             'object is then\n'
                             'asked to produce the attribute whose name is the '
                             'identifier.  This\n'
                             'production can be customized by overriding the '
                             '"__getattr__()" method.\n'
                             'If this attribute is not available, the exception '
                             '"AttributeError" is\n'
                             'raised.  Otherwise, the type and value of the object '
                             'produced is\n'
                             'determined by the object.  Multiple evaluations of '
                             'the same attribute\n'
                             'reference may yield different objects.\n',
    
     'augassign': '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',
    
     'await': 'Await expression\n'
              '****************\n'
              '\n'
              'Suspend the execution of *coroutine* on an *awaitable* object. Can\n'
              'only be used inside a *coroutine function*.\n'
              '\n'
              '   await_expr ::= "await" primary\n'
              '\n'
              'New in version 3.5.\n',
    
     'binary': 'Binary arithmetic operations\n'
    
               '****************************\n'
               '\n'
               'The binary arithmetic operations have the conventional priority\n'
               'levels.  Note that some of these operations also apply to certain '
               'non-\n'
               'numeric types.  Apart from the power operator, there are only two\n'
               'levels, one for multiplicative operators and one for additive\n'
               'operators:\n'
               '\n'
               '   m_expr ::= u_expr | m_expr "*" u_expr | m_expr "@" m_expr |\n'
    
               '              m_expr "//" u_expr | m_expr "/" u_expr |\n'
    
               '              m_expr "%" u_expr\n'
               '   a_expr ::= m_expr | a_expr "+" m_expr | a_expr "-" m_expr\n'
               '\n'
               'The "*" (multiplication) operator yields the product of its '
               'arguments.\n'
               'The arguments must either both be numbers, or one argument must be '
               'an\n'
               'integer and the other must be a sequence. In the former case, the\n'
               'numbers are converted to a common type and then multiplied '
               'together.\n'
               'In the latter case, sequence repetition is performed; a negative\n'
               'repetition factor yields an empty sequence.\n'
               '\n'
               'The "@" (at) operator is intended to be used for matrix\n'
               'multiplication.  No builtin Python types implement this operator.\n'
               '\n'
               'New in version 3.5.\n'
               '\n'
               'The "/" (division) and "//" (floor division) operators yield the\n'
               'quotient of their arguments.  The numeric arguments are first\n'
               'converted to a common type. Division of integers yields a float, '
               'while\n'
               'floor division of integers results in an integer; the result is '
               'that\n'
    
               'of mathematical division with the ‘floor’ function applied to the\n'
    
               'result.  Division by zero raises the "ZeroDivisionError" '
               'exception.\n'
               '\n'
               'The "%" (modulo) operator yields the remainder from the division '
               'of\n'
               'the first argument by the second.  The numeric arguments are '
               'first\n'
               'converted to a common type.  A zero right argument raises the\n'
               '"ZeroDivisionError" exception.  The arguments may be floating '
               'point\n'
               'numbers, e.g., "3.14%0.7" equals "0.34" (since "3.14" equals '
               '"4*0.7 +\n'
               '0.34".)  The modulo operator always yields a result with the same '
               'sign\n'
               'as its second operand (or zero); the absolute value of the result '
               'is\n'
               'strictly smaller than the absolute value of the second operand '
               '[1].\n'
               '\n'
               'The floor division and modulo operators are connected by the '
               'following\n'
               'identity: "x == (x//y)*y + (x%y)".  Floor division and modulo are '
               'also\n'
               'connected with the built-in function "divmod()": "divmod(x, y) ==\n'
               '(x//y, x%y)". [2].\n'
               '\n'
               'In addition to performing the modulo operation on numbers, the '
               '"%"\n'
               'operator is also overloaded by string objects to perform '
               'old-style\n'
               'string formatting (also known as interpolation).  The syntax for\n'
               'string formatting is described in the Python Library Reference,\n'
               'section printf-style String Formatting.\n'
               '\n'
               'The floor division operator, the modulo operator, and the '
               '"divmod()"\n'
               'function are not defined for complex numbers.  Instead, convert to '
               'a\n'
               'floating point number using the "abs()" function if appropriate.\n'
               '\n'
               'The "+" (addition) operator yields the sum of its arguments.  The\n'
               'arguments must either both be numbers or both be sequences of the '
               'same\n'
               'type.  In the former case, the numbers are converted to a common '
               'type\n'
               'and then added together. In the latter case, the sequences are\n'
               'concatenated.\n'
               '\n'
               'The "-" (subtraction) operator yields the difference of its '
               'arguments.\n'
               'The numeric arguments are first converted to a common type.\n',
    
     'bitwise': 'Binary bitwise operations\n'
    
                '*************************\n'
                '\n'
                'Each of the three bitwise operations has a different priority '
                'level:\n'
                '\n'
                '   and_expr ::= shift_expr | and_expr "&" shift_expr\n'
                '   xor_expr ::= and_expr | xor_expr "^" and_expr\n'
                '   or_expr  ::= xor_expr | or_expr "|" xor_expr\n'
                '\n'
                'The "&" operator yields the bitwise AND of its arguments, which '
                'must\n'
                'be integers.\n'
                '\n'
                'The "^" operator yields the bitwise XOR (exclusive OR) of its\n'
                'arguments, which must be integers.\n'
                '\n'
                'The "|" operator yields the bitwise (inclusive) OR of its '
                'arguments,\n'
                'which must be integers.\n',
    
     'bltin-code-objects': 'Code Objects\n'
    
                           '************\n'
                           '\n'
                           'Code objects are used by the implementation to '
    
                           'represent “pseudo-\n'
                           'compiled” executable Python code such as a function '
    
                           'body. They differ\n'
    
                           'from function objects because they don’t contain a '
    
                           'reference to their\n'
                           'global execution environment.  Code objects are '
                           'returned by the built-\n'
                           'in "compile()" function and can be extracted from '
                           'function objects\n'
                           'through their "__code__" attribute. See also the '
                           '"code" module.\n'
                           '\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                           'Accessing "__code__" raises an auditing event '
                           '"object.__getattr__"\n'
                           'with arguments "obj" and ""__code__"".\n'
                           '\n'
    
                           'A code object can be executed or evaluated by passing '
                           'it (instead of a\n'
                           'source string) to the "exec()" or "eval()"  built-in '
                           'functions.\n'
                           '\n'
                           'See The standard type hierarchy for more '
                           'information.\n',
    
     'bltin-ellipsis-object': 'The Ellipsis Object\n'
    
                              '*******************\n'
                              '\n'
                              'This object is commonly used by slicing (see '
                              'Slicings).  It supports\n'
                              'no special operations.  There is exactly one '
                              'ellipsis object, named\n'
                              '"Ellipsis" (a built-in name).  "type(Ellipsis)()" '
                              'produces the\n'
                              '"Ellipsis" singleton.\n'
                              '\n'
                              'It is written as "Ellipsis" or "...".\n',
    
     'bltin-null-object': 'The Null Object\n'
    
                          '***************\n'
                          '\n'
    
                          'This object is returned by functions that don’t '
    
                          'explicitly return a\n'
                          'value.  It supports no special operations.  There is '
                          'exactly one null\n'
                          'object, named "None" (a built-in name).  "type(None)()" '
                          'produces the\n'
                          'same singleton.\n'
                          '\n'
                          'It is written as "None".\n',
    
     'bltin-type-objects': 'Type Objects\n'
    
                           '************\n'
                           '\n'
                           'Type objects represent the various object types.  An '
    
                           'object’s type is\n'
    
                           'accessed by the built-in function "type()".  There are '
                           'no special\n'
                           'operations on types.  The standard module "types" '
                           'defines names for\n'
                           'all standard built-in types.\n'
                           '\n'
                           'Types are written like this: "<class \'int\'>".\n',
    
     'booleans': 'Boolean operations\n'
    
                 '******************\n'
                 '\n'
                 '   or_test  ::= and_test | or_test "or" and_test\n'
                 '   and_test ::= not_test | and_test "and" not_test\n'
                 '   not_test ::= comparison | "not" not_test\n'
                 '\n'
                 'In the context of Boolean operations, and also when expressions '
                 'are\n'
                 'used by control flow statements, the following values are '
                 'interpreted\n'
                 'as false: "False", "None", numeric zero of all types, and empty\n'
                 'strings and containers (including strings, tuples, lists,\n'
                 'dictionaries, sets and frozensets).  All other values are '
                 'interpreted\n'
                 'as true.  User-defined objects can customize their truth value '
                 'by\n'
                 'providing a "__bool__()" method.\n'
                 '\n'
                 'The operator "not" yields "True" if its argument is false, '
                 '"False"\n'
                 'otherwise.\n'
                 '\n'
                 'The expression "x and y" first evaluates *x*; if *x* is false, '
                 'its\n'
                 'value is returned; otherwise, *y* is evaluated and the resulting '
                 'value\n'
                 'is returned.\n'
                 '\n'
                 'The expression "x or y" first evaluates *x*; if *x* is true, its '
                 'value\n'
                 'is returned; otherwise, *y* is evaluated and the resulting value '
                 'is\n'
                 'returned.\n'
                 '\n'
    
                 'Note that neither "and" nor "or" restrict the value and type '
    
                 'they\n'
                 'return to "False" and "True", but rather return the last '
                 'evaluated\n'
                 'argument.  This is sometimes useful, e.g., if "s" is a string '
                 'that\n'
                 'should be replaced by a default value if it is empty, the '
                 'expression\n'
                 '"s or \'foo\'" yields the desired value.  Because "not" has to '
                 'create a\n'
                 'new value, it returns a boolean value regardless of the type of '
                 'its\n'
                 'argument (for example, "not \'foo\'" produces "False" rather '
                 'than "\'\'".)\n',
    
     'break': 'The "break" statement\n'
    
              '*********************\n'
              '\n'
              '   break_stmt ::= "break"\n'
              '\n'
              '"break" may only occur syntactically nested in a "for" or "while"\n'
              'loop, but not nested in a function or class definition within that\n'
              'loop.\n'
              '\n'
              'It terminates the nearest enclosing loop, skipping the optional '
              '"else"\n'
              'clause if the loop has one.\n'
              '\n'
              'If a "for" loop is terminated by "break", the loop control target\n'
              'keeps its current value.\n'
              '\n'
              'When "break" passes control out of a "try" statement with a '
              '"finally"\n'
              'clause, that "finally" clause is executed before really leaving '
              'the\n'
              'loop.\n',
    
     'callable-types': 'Emulating callable objects\n'
    
                       '**************************\n'
                       '\n'
                       'object.__call__(self[, args...])\n'
                       '\n'
    
                       '   Called when the instance is “called” as a function; if '
    
                       'this method\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                       '   is defined, "x(arg1, arg2, ...)" roughly translates to\n'
                       '   "type(x).__call__(x, arg1, ...)".\n',
    
     'calls': 'Calls\n'
    
              '*****\n'
              '\n'
              'A call calls a callable object (e.g., a *function*) with a '
              'possibly\n'
              'empty series of *arguments*:\n'
              '\n'
              '   call                 ::= primary "(" [argument_list [","] | '
              'comprehension] ")"\n'
              '   argument_list        ::= positional_arguments ["," '
    
              'starred_and_keywords]\n'
              '                       ["," keywords_arguments]\n'
              '                     | starred_and_keywords ["," '
              'keywords_arguments]\n'
              '                     | keywords_arguments\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
              '   positional_arguments ::= positional_item ("," positional_item)*\n'
              '   positional_item      ::= assignment_expression | "*" expression\n'
    
              '   starred_and_keywords ::= ("*" expression | keyword_item)\n'
              '                            ("," "*" expression | "," '
              'keyword_item)*\n'
              '   keywords_arguments   ::= (keyword_item | "**" expression)\n'
    
              '                          ("," keyword_item | "," "**" '
              'expression)*\n'
    
              '   keyword_item         ::= identifier "=" expression\n'
              '\n'
              'An optional trailing comma may be present after the positional and\n'
              'keyword arguments but does not affect the semantics.\n'
              '\n'
              'The primary must evaluate to a callable object (user-defined\n'
              'functions, built-in functions, methods of built-in objects, class\n'
              'objects, methods of class instances, and all objects having a\n'
              '"__call__()" method are callable).  All argument expressions are\n'
              'evaluated before the call is attempted.  Please refer to section\n'
              'Function definitions for the syntax of formal *parameter* lists.\n'
              '\n'
              'If keyword arguments are present, they are first converted to\n'
              'positional arguments, as follows.  First, a list of unfilled slots '
              'is\n'
              'created for the formal parameters.  If there are N positional\n'
              'arguments, they are placed in the first N slots.  Next, for each\n'
              'keyword argument, the identifier is used to determine the\n'
              'corresponding slot (if the identifier is the same as the first '
              'formal\n'
              'parameter name, the first slot is used, and so on).  If the slot '
              'is\n'
              'already filled, a "TypeError" exception is raised. Otherwise, the\n'
              'value of the argument is placed in the slot, filling it (even if '
              'the\n'
              'expression is "None", it fills the slot).  When all arguments have\n'
              'been processed, the slots that are still unfilled are filled with '
              'the\n'
              'corresponding default value from the function definition.  '
              '(Default\n'
              'values are calculated, once, when the function is defined; thus, a\n'
              'mutable object such as a list or dictionary used as default value '
              'will\n'
    
              'be shared by all calls that don’t specify an argument value for '
    
              'the\n'
              'corresponding slot; this should usually be avoided.)  If there are '
              'any\n'
              'unfilled slots for which no default value is specified, a '
              '"TypeError"\n'
              'exception is raised.  Otherwise, the list of filled slots is used '
              'as\n'
              'the argument list for the call.\n'
              '\n'
              '**CPython implementation detail:** An implementation may provide\n'
              'built-in functions whose positional parameters do not have names, '
              'even\n'
    
              'if they are ‘named’ for the purpose of documentation, and which\n'
    
              'therefore cannot be supplied by keyword.  In CPython, this is the '
              'case\n'
              'for functions implemented in C that use "PyArg_ParseTuple()" to '
              'parse\n'
              'their arguments.\n'
              '\n'
              'If there are more positional arguments than there are formal '
              'parameter\n'
              'slots, a "TypeError" exception is raised, unless a formal '
              'parameter\n'
              'using the syntax "*identifier" is present; in this case, that '
              'formal\n'
              'parameter receives a tuple containing the excess positional '
              'arguments\n'
              '(or an empty tuple if there were no excess positional arguments).\n'
              '\n'
              'If any keyword argument does not correspond to a formal parameter\n'
              'name, a "TypeError" exception is raised, unless a formal parameter\n'
              'using the syntax "**identifier" is present; in this case, that '
              'formal\n'
              'parameter receives a dictionary containing the excess keyword\n'
              'arguments (using the keywords as keys and the argument values as\n'
              'corresponding values), or a (new) empty dictionary if there were '
              'no\n'
              'excess keyword arguments.\n'
              '\n'
              'If the syntax "*expression" appears in the function call, '
              '"expression"\n'
    
              'must evaluate to an *iterable*.  Elements from these iterables are\n'
              'treated as if they were additional positional arguments.  For the '
              'call\n'
    
              '"f(x1, x2, *y, x3, x4)", if *y* evaluates to a sequence *y1*, …, '
              '*yM*,\n'
              'this is equivalent to a call with M+4 positional arguments *x1*, '
              '*x2*,\n'
              '*y1*, …, *yM*, *x3*, *x4*.\n'
    
              '\n'
              'A consequence of this is that although the "*expression" syntax '
              'may\n'
    
              'appear *after* explicit keyword arguments, it is processed '
              '*before*\n'
    
              'the keyword arguments (and any "**expression" arguments – see '
    
              'below).\n'
              'So:\n'
    
              '\n'
              '   >>> def f(a, b):\n'
              '   ...     print(a, b)\n'
              '   ...\n'
              '   >>> f(b=1, *(2,))\n'
              '   2 1\n'
              '   >>> f(a=1, *(2,))\n'
              '   Traceback (most recent call last):\n'
    
              '     File "<stdin>", line 1, in <module>\n'
    
              "   TypeError: f() got multiple values for keyword argument 'a'\n"
              '   >>> f(1, *(2,))\n'
              '   1 2\n'
              '\n'
              'It is unusual for both keyword arguments and the "*expression" '
              'syntax\n'
              'to be used in the same call, so in practice this confusion does '
              'not\n'
              'arise.\n'
              '\n'
              'If the syntax "**expression" appears in the function call,\n'
    
              '"expression" must evaluate to a *mapping*, the contents of which '
              'are\n'
              'treated as additional keyword arguments.  If a keyword is already\n'
              'present (as an explicit keyword argument, or from another '
              'unpacking),\n'
              'a "TypeError" exception is raised.\n'
    
              '\n'
              'Formal parameters using the syntax "*identifier" or "**identifier"\n'
              'cannot be used as positional argument slots or as keyword argument\n'
              'names.\n'
              '\n'
    
              'Changed in version 3.5: Function calls accept any number of "*" '
              'and\n'
              '"**" unpackings, positional arguments may follow iterable '
              'unpackings\n'
              '("*"), and keyword arguments may follow dictionary unpackings '
              '("**").\n'
              'Originally proposed by **PEP 448**.\n'
              '\n'
    
              'A call always returns some value, possibly "None", unless it raises '
              'an\n'
              'exception.  How this value is computed depends on the type of the\n'
              'callable object.\n'
              '\n'
    
              'If it is—\n'
    
              '\n'
              'a user-defined function:\n'
              '   The code block for the function is executed, passing it the\n'
              '   argument list.  The first thing the code block will do is bind '
              'the\n'
              '   formal parameters to the arguments; this is described in '
              'section\n'
              '   Function definitions.  When the code block executes a "return"\n'
              '   statement, this specifies the return value of the function '
              'call.\n'
              '\n'
              'a built-in function or method:\n'
              '   The result is up to the interpreter; see Built-in Functions for '
              'the\n'
              '   descriptions of built-in functions and methods.\n'
              '\n'
              'a class object:\n'
              '   A new instance of that class is returned.\n'
              '\n'
              'a class instance method:\n'
              '   The corresponding user-defined function is called, with an '
              'argument\n'
              '   list that is one longer than the argument list of the call: the\n'
              '   instance becomes the first argument.\n'
              '\n'
              'a class instance:\n'
              '   The class must define a "__call__()" method; the effect is then '
              'the\n'
              '   same as if that method was called.\n',
    
     'class': 'Class definitions\n'
    
              '*****************\n'
              '\n'
              'A class definition defines a class object (see section The '
              'standard\n'
              'type hierarchy):\n'
              '\n'
              '   classdef    ::= [decorators] "class" classname [inheritance] ":" '
              'suite\n'
    
              '   inheritance ::= "(" [argument_list] ")"\n'
    
              '   classname   ::= identifier\n'
              '\n'
              'A class definition is an executable statement.  The inheritance '
              'list\n'
    
              'usually gives a list of base classes (see Metaclasses for more\n'
              'advanced uses), so each item in the list should evaluate to a '
              'class\n'
              'object which allows subclassing.  Classes without an inheritance '
              'list\n'
              'inherit, by default, from the base class "object"; hence,\n'
    
              '\n'
              '   class Foo:\n'
              '       pass\n'
              '\n'
              'is equivalent to\n'
              '\n'
              '   class Foo(object):\n'
              '       pass\n'
              '\n'
    
              'The class’s suite is then executed in a new execution frame (see\n'
    
              'Naming and binding), using a newly created local namespace and the\n'
              'original global namespace. (Usually, the suite contains mostly\n'
    
              'function definitions.)  When the class’s suite finishes execution, '
    
              'its\n'
    
              'execution frame is discarded but its local namespace is saved. [3] '
    
              'A\n'
              'class object is then created using the inheritance list for the '
              'base\n'
              'classes and the saved local namespace for the attribute '
              'dictionary.\n'
              'The class name is bound to this class object in the original local\n'
              'namespace.\n'
              '\n'
    
              'The order in which attributes are defined in the class body is\n'
    
              'preserved in the new class’s "__dict__".  Note that this is '
    
              'reliable\n'
              'only right after the class is created and only for classes that '
              'were\n'
              'defined using the definition syntax.\n'
              '\n'
    
              'Class creation can be customized heavily using metaclasses.\n'
              '\n'
              'Classes can also be decorated: just like when decorating '
              'functions,\n'
              '\n'
              '   @f1(arg)\n'
              '   @f2\n'
              '   class Foo: pass\n'
              '\n'
    
              'is roughly equivalent to\n'
    
              '\n'
              '   class Foo: pass\n'
              '   Foo = f1(arg)(f2(Foo))\n'
              '\n'
              'The evaluation rules for the decorator expressions are the same as '
              'for\n'
    
              'function decorators.  The result is then bound to the class name.\n'
    
              '**Programmer’s note:** Variables defined in the class definition '
    
              'are\n'
              'class attributes; they are shared by instances.  Instance '
              'attributes\n'
              'can be set in a method with "self.name = value".  Both class and\n'
              'instance attributes are accessible through the notation '
    
              '“"self.name"”,\n'
    
              'and an instance attribute hides a class attribute with the same '
              'name\n'
              'when accessed in this way.  Class attributes can be used as '
              'defaults\n'
              'for instance attributes, but using mutable values there can lead '
              'to\n'
              'unexpected results.  Descriptors can be used to create instance\n'
              'variables with different implementation details.\n'
              '\n'
    
              'See also:\n'
              '\n'
              '  **PEP 3115** - Metaclasses in Python 3000\n'
              '     The proposal that changed the declaration of metaclasses to '
              'the\n'
              '     current syntax, and the semantics for how classes with\n'
              '     metaclasses are constructed.\n'
              '\n'
              '  **PEP 3129** - Class Decorators\n'
              '     The proposal that added class decorators.  Function and '
              'method\n'
              '     decorators were introduced in **PEP 318**.\n',
    
     'comparisons': 'Comparisons\n'
    
                    '***********\n'
                    '\n'
                    'Unlike C, all comparison operations in Python have the same '
                    'priority,\n'
                    'which is lower than that of any arithmetic, shifting or '
                    'bitwise\n'
                    'operation.  Also unlike C, expressions like "a < b < c" have '
                    'the\n'
                    'interpretation that is conventional in mathematics:\n'
                    '\n'
    
                    '   comparison    ::= or_expr (comp_operator or_expr)*\n'
    
                    '   comp_operator ::= "<" | ">" | "==" | ">=" | "<=" | "!="\n'
                    '                     | "is" ["not"] | ["not"] "in"\n'
                    '\n'
                    'Comparisons yield boolean values: "True" or "False".\n'
                    '\n'
                    'Comparisons can be chained arbitrarily, e.g., "x < y <= z" '
                    'is\n'
                    'equivalent to "x < y and y <= z", except that "y" is '
                    'evaluated only\n'
                    'once (but in both cases "z" is not evaluated at all when "x < '
                    'y" is\n'
                    'found to be false).\n'
                    '\n'
    
                    'Formally, if *a*, *b*, *c*, …, *y*, *z* are expressions and '
    
                    '*op1*,\n'
    
                    '*op2*, …, *opN* are comparison operators, then "a op1 b op2 c '
                    '... y\n'
    
                    'opN z" is equivalent to "a op1 b and b op2 c and ... y opN '
                    'z", except\n'
                    'that each expression is evaluated at most once.\n'
                    '\n'
    
                    'Note that "a op1 b op2 c" doesn’t imply any kind of '
    
                    'comparison between\n'
                    '*a* and *c*, so that, e.g., "x < y > z" is perfectly legal '
                    '(though\n'
                    'perhaps not pretty).\n'
                    '\n'
                    '\n'
                    'Value comparisons\n'
                    '=================\n'
                    '\n'
                    'The operators "<", ">", "==", ">=", "<=", and "!=" compare '
                    'the values\n'
                    'of two objects.  The objects do not need to have the same '
                    'type.\n'
                    '\n'
                    'Chapter Objects, values and types states that objects have a '
                    'value (in\n'
                    'addition to type and identity).  The value of an object is a '
                    'rather\n'
                    'abstract notion in Python: For example, there is no canonical '
                    'access\n'
    
                    'method for an object’s value.  Also, there is no requirement '
    
                    'that the\n'
                    'value of an object should be constructed in a particular way, '
                    'e.g.\n'
                    'comprised of all its data attributes. Comparison operators '
                    'implement a\n'
                    'particular notion of what the value of an object is.  One can '
                    'think of\n'
                    'them as defining the value of an object indirectly, by means '
                    'of their\n'
                    'comparison implementation.\n'
                    '\n'
                    'Because all types are (direct or indirect) subtypes of '
                    '"object", they\n'
                    'inherit the default comparison behavior from "object".  Types '
                    'can\n'
                    'customize their comparison behavior by implementing *rich '
                    'comparison\n'
                    'methods* like "__lt__()", described in Basic customization.\n'
                    '\n'
                    'The default behavior for equality comparison ("==" and "!=") '
                    'is based\n'
                    'on the identity of the objects.  Hence, equality comparison '
                    'of\n'
                    'instances with the same identity results in equality, and '
                    'equality\n'
                    'comparison of instances with different identities results in\n'
                    'inequality.  A motivation for this default behavior is the '
                    'desire that\n'
                    'all objects should be reflexive (i.e. "x is y" implies "x == '
                    'y").\n'
                    '\n'
                    'A default order comparison ("<", ">", "<=", and ">=") is not '
                    'provided;\n'
                    'an attempt raises "TypeError".  A motivation for this default '
                    'behavior\n'
                    'is the lack of a similar invariant as for equality.\n'
                    '\n'
                    'The behavior of the default equality comparison, that '
                    'instances with\n'
                    'different identities are always unequal, may be in contrast '
                    'to what\n'
                    'types will need that have a sensible definition of object '
                    'value and\n'
                    'value-based equality.  Such types will need to customize '
                    'their\n'
                    'comparison behavior, and in fact, a number of built-in types '
                    'have done\n'
                    'that.\n'
                    '\n'
                    'The following list describes the comparison behavior of the '
                    'most\n'
                    'important built-in types.\n'
                    '\n'
    
                    '* Numbers of built-in numeric types (Numeric Types — int, '
    
                    'float,\n'
                    '  complex) and of the standard library types '
                    '"fractions.Fraction" and\n'
                    '  "decimal.Decimal" can be compared within and across their '
                    'types,\n'
                    '  with the restriction that complex numbers do not support '
                    'order\n'
                    '  comparison.  Within the limits of the types involved, they '
                    'compare\n'
                    '  mathematically (algorithmically) correct without loss of '
                    'precision.\n'
                    '\n'
                    '  The not-a-number values "float(\'NaN\')" and '
    
                    '"decimal.Decimal(\'NaN\')"\n'
                    '  are special.  Any ordered comparison of a number to a '
                    'not-a-number\n'
                    '  value is false. A counter-intuitive implication is that '
                    'not-a-number\n'
                    '  values are not equal to themselves.  For example, if "x =\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                    '  float(\'NaN\')", "3 < x", "x < 3" and "x == x" are all '
                    'false, while "x\n'
                    '  != x" is true.  This behavior is compliant with IEEE 754.\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                    '* "None" and "NotImplemented" are singletons.  **PEP 8** '
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                    'advises that\n'
                    '  comparisons for singletons should always be done with "is" '
                    'or "is\n'
                    '  not", never the equality operators.\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                    '\n'
    
                    '* Binary sequences (instances of "bytes" or "bytearray") can '
                    'be\n'
                    '  compared within and across their types.  They compare\n'
                    '  lexicographically using the numeric values of their '
                    'elements.\n'
                    '\n'
                    '* Strings (instances of "str") compare lexicographically '
                    'using the\n'
                    '  numerical Unicode code points (the result of the built-in '
                    'function\n'
                    '  "ord()") of their characters. [3]\n'
                    '\n'
                    '  Strings and binary sequences cannot be directly compared.\n'
                    '\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                    '* Sequences (instances of "tuple", "list", or "range") can be '
                    'compared\n'
                    '  only within each of their types, with the restriction that '
                    'ranges do\n'
                    '  not support order comparison.  Equality comparison across '
                    'these\n'
                    '  types results in inequality, and ordering comparison across '
                    'these\n'
                    '  types raises "TypeError".\n'
    
                    '\n'
                    '  Sequences compare lexicographically using comparison of\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                    '  corresponding elements.  The built-in containers typically '
                    'assume\n'
                    '  identical objects are equal to themselves.  That lets them '
                    'bypass\n'
                    '  equality tests for identical objects to improve performance '
                    'and to\n'
                    '  maintain their internal invariants.\n'
    
                    '\n'
                    '  Lexicographical comparison between built-in collections '
                    'works as\n'
                    '  follows:\n'
                    '\n'
                    '  * For two collections to compare equal, they must be of the '
                    'same\n'
                    '    type, have the same length, and each pair of '
                    'corresponding\n'
                    '    elements must compare equal (for example, "[1,2] == '
                    '(1,2)" is\n'
                    '    false because the type is not the same).\n'
                    '\n'
                    '  * Collections that support order comparison are ordered the '
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                    'same as\n'
                    '    their first unequal elements (for example, "[1,2,x] <= '
    
                    '[1,2,y]"\n'
                    '    has the same value as "x <= y").  If a corresponding '
                    'element does\n'
                    '    not exist, the shorter collection is ordered first (for '
                    'example,\n'
                    '    "[1,2] < [1,2,3]" is true).\n'
                    '\n'
                    '* Mappings (instances of "dict") compare equal if and only if '
                    'they\n'
                    '  have equal *(key, value)* pairs. Equality comparison of the '
                    'keys and\n'
    
                    '  values enforces reflexivity.\n'
    
                    '\n'
                    '  Order comparisons ("<", ">", "<=", and ">=") raise '
                    '"TypeError".\n'
                    '\n'
                    '* Sets (instances of "set" or "frozenset") can be compared '
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                    'within and\n'
                    '  across their types.\n'
    
                    '\n'
                    '  They define order comparison operators to mean subset and '
                    'superset\n'
                    '  tests.  Those relations do not define total orderings (for '
                    'example,\n'
                    '  the two sets "{1,2}" and "{2,3}" are not equal, nor subsets '
                    'of one\n'
                    '  another, nor supersets of one another).  Accordingly, sets '
                    'are not\n'
                    '  appropriate arguments for functions which depend on total '
                    'ordering\n'
                    '  (for example, "min()", "max()", and "sorted()" produce '
                    'undefined\n'
                    '  results given a list of sets as inputs).\n'
                    '\n'
                    '  Comparison of sets enforces reflexivity of its elements.\n'
                    '\n'
                    '* Most other built-in types have no comparison methods '
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                    'implemented, so\n'
                    '  they inherit the default comparison behavior.\n'
    
                    '\n'
                    'User-defined classes that customize their comparison behavior '
                    'should\n'
                    'follow some consistency rules, if possible:\n'
                    '\n'