jpayne@69: # -*- coding: utf-8 -*- jpayne@69: # Autogenerated by Sphinx on Wed Dec 18 18:17:58 2019 jpayne@69: topics = {'assert': 'The "assert" statement\n' jpayne@69: '**********************\n' jpayne@69: '\n' jpayne@69: 'Assert statements are a convenient way to insert debugging ' jpayne@69: 'assertions\n' jpayne@69: 'into a program:\n' jpayne@69: '\n' jpayne@69: ' assert_stmt ::= "assert" expression ["," expression]\n' jpayne@69: '\n' jpayne@69: 'The simple form, "assert expression", is equivalent to\n' jpayne@69: '\n' jpayne@69: ' if __debug__:\n' jpayne@69: ' if not expression: raise AssertionError\n' jpayne@69: '\n' jpayne@69: 'The extended form, "assert expression1, expression2", is ' jpayne@69: 'equivalent to\n' jpayne@69: '\n' jpayne@69: ' if __debug__:\n' jpayne@69: ' if not expression1: raise AssertionError(expression2)\n' jpayne@69: '\n' jpayne@69: 'These equivalences assume that "__debug__" and "AssertionError" ' jpayne@69: 'refer\n' jpayne@69: 'to the built-in variables with those names. In the current\n' jpayne@69: 'implementation, the built-in variable "__debug__" is "True" under\n' jpayne@69: 'normal circumstances, "False" when optimization is requested ' jpayne@69: '(command\n' jpayne@69: 'line option "-O"). The current code generator emits no code for ' jpayne@69: 'an\n' jpayne@69: 'assert statement when optimization is requested at compile time. ' jpayne@69: 'Note\n' jpayne@69: 'that it is unnecessary to include the source code for the ' jpayne@69: 'expression\n' jpayne@69: 'that failed in the error message; it will be displayed as part of ' jpayne@69: 'the\n' jpayne@69: 'stack trace.\n' jpayne@69: '\n' jpayne@69: 'Assignments to "__debug__" are illegal. The value for the ' jpayne@69: 'built-in\n' jpayne@69: 'variable is determined when the interpreter starts.\n', jpayne@69: 'assignment': 'Assignment statements\n' jpayne@69: '*********************\n' jpayne@69: '\n' jpayne@69: 'Assignment statements are used to (re)bind names to values and ' jpayne@69: 'to\n' jpayne@69: 'modify attributes or items of mutable objects:\n' jpayne@69: '\n' jpayne@69: ' assignment_stmt ::= (target_list "=")+ (starred_expression ' jpayne@69: '| yield_expression)\n' jpayne@69: ' target_list ::= target ("," target)* [","]\n' jpayne@69: ' target ::= identifier\n' jpayne@69: ' | "(" [target_list] ")"\n' jpayne@69: ' | "[" [target_list] "]"\n' jpayne@69: ' | attributeref\n' jpayne@69: ' | subscription\n' jpayne@69: ' | slicing\n' jpayne@69: ' | "*" target\n' jpayne@69: '\n' jpayne@69: '(See section Primaries for the syntax definitions for ' jpayne@69: '*attributeref*,\n' jpayne@69: '*subscription*, and *slicing*.)\n' jpayne@69: '\n' jpayne@69: 'An assignment statement evaluates the expression list ' jpayne@69: '(remember that\n' jpayne@69: 'this can be a single expression or a comma-separated list, the ' jpayne@69: 'latter\n' jpayne@69: 'yielding a tuple) and assigns the single resulting object to ' jpayne@69: 'each of\n' jpayne@69: 'the target lists, from left to right.\n' jpayne@69: '\n' jpayne@69: 'Assignment is defined recursively depending on the form of the ' jpayne@69: 'target\n' jpayne@69: '(list). When a target is part of a mutable object (an ' jpayne@69: 'attribute\n' jpayne@69: 'reference, subscription or slicing), the mutable object must\n' jpayne@69: 'ultimately perform the assignment and decide about its ' jpayne@69: 'validity, and\n' jpayne@69: 'may raise an exception if the assignment is unacceptable. The ' jpayne@69: 'rules\n' jpayne@69: 'observed by various types and the exceptions raised are given ' jpayne@69: 'with the\n' jpayne@69: 'definition of the object types (see section The standard type\n' jpayne@69: 'hierarchy).\n' jpayne@69: '\n' jpayne@69: 'Assignment of an object to a target list, optionally enclosed ' jpayne@69: 'in\n' jpayne@69: 'parentheses or square brackets, is recursively defined as ' jpayne@69: 'follows.\n' jpayne@69: '\n' jpayne@69: '* If the target list is a single target with no trailing ' jpayne@69: 'comma,\n' jpayne@69: ' optionally in parentheses, the object is assigned to that ' jpayne@69: 'target.\n' jpayne@69: '\n' jpayne@69: '* Else: The object must be an iterable with the same number of ' jpayne@69: 'items\n' jpayne@69: ' as there are targets in the target list, and the items are ' jpayne@69: 'assigned,\n' jpayne@69: ' from left to right, to the corresponding targets.\n' jpayne@69: '\n' jpayne@69: ' * If the target list contains one target prefixed with an\n' jpayne@69: ' asterisk, called a “starred” target: The object must be ' jpayne@69: 'an\n' jpayne@69: ' iterable with at least as many items as there are targets ' jpayne@69: 'in the\n' jpayne@69: ' target list, minus one. The first items of the iterable ' jpayne@69: 'are\n' jpayne@69: ' assigned, from left to right, to the targets before the ' jpayne@69: 'starred\n' jpayne@69: ' target. The final items of the iterable are assigned to ' jpayne@69: 'the\n' jpayne@69: ' targets after the starred target. A list of the remaining ' jpayne@69: 'items\n' jpayne@69: ' in the iterable is then assigned to the starred target ' jpayne@69: '(the list\n' jpayne@69: ' can be empty).\n' jpayne@69: '\n' jpayne@69: ' * Else: The object must be an iterable with the same number ' jpayne@69: 'of\n' jpayne@69: ' items as there are targets in the target list, and the ' jpayne@69: 'items are\n' jpayne@69: ' assigned, from left to right, to the corresponding ' jpayne@69: 'targets.\n' jpayne@69: '\n' jpayne@69: 'Assignment of an object to a single target is recursively ' jpayne@69: 'defined as\n' jpayne@69: 'follows.\n' jpayne@69: '\n' jpayne@69: '* If the target is an identifier (name):\n' jpayne@69: '\n' jpayne@69: ' * If the name does not occur in a "global" or "nonlocal" ' jpayne@69: 'statement\n' jpayne@69: ' in the current code block: the name is bound to the object ' jpayne@69: 'in the\n' jpayne@69: ' current local namespace.\n' jpayne@69: '\n' jpayne@69: ' * Otherwise: the name is bound to the object in the global\n' jpayne@69: ' namespace or the outer namespace determined by ' jpayne@69: '"nonlocal",\n' jpayne@69: ' respectively.\n' jpayne@69: '\n' jpayne@69: ' The name is rebound if it was already bound. This may cause ' jpayne@69: 'the\n' jpayne@69: ' reference count for the object previously bound to the name ' jpayne@69: 'to reach\n' jpayne@69: ' zero, causing the object to be deallocated and its ' jpayne@69: 'destructor (if it\n' jpayne@69: ' has one) to be called.\n' jpayne@69: '\n' jpayne@69: '* If the target is an attribute reference: The primary ' jpayne@69: 'expression in\n' jpayne@69: ' the reference is evaluated. It should yield an object with\n' jpayne@69: ' assignable attributes; if this is not the case, "TypeError" ' jpayne@69: 'is\n' jpayne@69: ' raised. That object is then asked to assign the assigned ' jpayne@69: 'object to\n' jpayne@69: ' the given attribute; if it cannot perform the assignment, it ' jpayne@69: 'raises\n' jpayne@69: ' an exception (usually but not necessarily ' jpayne@69: '"AttributeError").\n' jpayne@69: '\n' jpayne@69: ' Note: If the object is a class instance and the attribute ' jpayne@69: 'reference\n' jpayne@69: ' occurs on both sides of the assignment operator, the ' jpayne@69: 'right-hand side\n' jpayne@69: ' expression, "a.x" can access either an instance attribute or ' jpayne@69: '(if no\n' jpayne@69: ' instance attribute exists) a class attribute. The left-hand ' jpayne@69: 'side\n' jpayne@69: ' target "a.x" is always set as an instance attribute, ' jpayne@69: 'creating it if\n' jpayne@69: ' necessary. Thus, the two occurrences of "a.x" do not ' jpayne@69: 'necessarily\n' jpayne@69: ' refer to the same attribute: if the right-hand side ' jpayne@69: 'expression\n' jpayne@69: ' refers to a class attribute, the left-hand side creates a ' jpayne@69: 'new\n' jpayne@69: ' instance attribute as the target of the assignment:\n' jpayne@69: '\n' jpayne@69: ' class Cls:\n' jpayne@69: ' x = 3 # class variable\n' jpayne@69: ' inst = Cls()\n' jpayne@69: ' inst.x = inst.x + 1 # writes inst.x as 4 leaving Cls.x ' jpayne@69: 'as 3\n' jpayne@69: '\n' jpayne@69: ' This description does not necessarily apply to descriptor\n' jpayne@69: ' attributes, such as properties created with "property()".\n' jpayne@69: '\n' jpayne@69: '* If the target is a subscription: The primary expression in ' jpayne@69: 'the\n' jpayne@69: ' reference is evaluated. It should yield either a mutable ' jpayne@69: 'sequence\n' jpayne@69: ' object (such as a list) or a mapping object (such as a ' jpayne@69: 'dictionary).\n' jpayne@69: ' Next, the subscript expression is evaluated.\n' jpayne@69: '\n' jpayne@69: ' If the primary is a mutable sequence object (such as a ' jpayne@69: 'list), the\n' jpayne@69: ' subscript must yield an integer. If it is negative, the ' jpayne@69: 'sequence’s\n' jpayne@69: ' length is added to it. The resulting value must be a ' jpayne@69: 'nonnegative\n' jpayne@69: ' integer less than the sequence’s length, and the sequence is ' jpayne@69: 'asked\n' jpayne@69: ' to assign the assigned object to its item with that index. ' jpayne@69: 'If the\n' jpayne@69: ' index is out of range, "IndexError" is raised (assignment to ' jpayne@69: 'a\n' jpayne@69: ' subscripted sequence cannot add new items to a list).\n' jpayne@69: '\n' jpayne@69: ' If the primary is a mapping object (such as a dictionary), ' jpayne@69: 'the\n' jpayne@69: ' subscript must have a type compatible with the mapping’s key ' jpayne@69: 'type,\n' jpayne@69: ' and the mapping is then asked to create a key/datum pair ' jpayne@69: 'which maps\n' jpayne@69: ' the subscript to the assigned object. This can either ' jpayne@69: 'replace an\n' jpayne@69: ' existing key/value pair with the same key value, or insert a ' jpayne@69: 'new\n' jpayne@69: ' key/value pair (if no key with the same value existed).\n' jpayne@69: '\n' jpayne@69: ' For user-defined objects, the "__setitem__()" method is ' jpayne@69: 'called with\n' jpayne@69: ' appropriate arguments.\n' jpayne@69: '\n' jpayne@69: '* If the target is a slicing: The primary expression in the\n' jpayne@69: ' reference is evaluated. It should yield a mutable sequence ' jpayne@69: 'object\n' jpayne@69: ' (such as a list). The assigned object should be a sequence ' jpayne@69: 'object\n' jpayne@69: ' of the same type. Next, the lower and upper bound ' jpayne@69: 'expressions are\n' jpayne@69: ' evaluated, insofar they are present; defaults are zero and ' jpayne@69: 'the\n' jpayne@69: ' sequence’s length. The bounds should evaluate to integers. ' jpayne@69: 'If\n' jpayne@69: ' either bound is negative, the sequence’s length is added to ' jpayne@69: 'it. The\n' jpayne@69: ' resulting bounds are clipped to lie between zero and the ' jpayne@69: 'sequence’s\n' jpayne@69: ' length, inclusive. Finally, the sequence object is asked to ' jpayne@69: 'replace\n' jpayne@69: ' the slice with the items of the assigned sequence. The ' jpayne@69: 'length of\n' jpayne@69: ' the slice may be different from the length of the assigned ' jpayne@69: 'sequence,\n' jpayne@69: ' thus changing the length of the target sequence, if the ' jpayne@69: 'target\n' jpayne@69: ' sequence allows it.\n' jpayne@69: '\n' jpayne@69: '**CPython implementation detail:** In the current ' jpayne@69: 'implementation, the\n' jpayne@69: 'syntax for targets is taken to be the same as for expressions, ' jpayne@69: 'and\n' jpayne@69: 'invalid syntax is rejected during the code generation phase, ' jpayne@69: 'causing\n' jpayne@69: 'less detailed error messages.\n' jpayne@69: '\n' jpayne@69: 'Although the definition of assignment implies that overlaps ' jpayne@69: 'between\n' jpayne@69: 'the left-hand side and the right-hand side are ‘simultaneous’ ' jpayne@69: '(for\n' jpayne@69: 'example "a, b = b, a" swaps two variables), overlaps *within* ' jpayne@69: 'the\n' jpayne@69: 'collection of assigned-to variables occur left-to-right, ' jpayne@69: 'sometimes\n' jpayne@69: 'resulting in confusion. For instance, the following program ' jpayne@69: 'prints\n' jpayne@69: '"[0, 2]":\n' jpayne@69: '\n' jpayne@69: ' x = [0, 1]\n' jpayne@69: ' i = 0\n' jpayne@69: ' i, x[i] = 1, 2 # i is updated, then x[i] is ' jpayne@69: 'updated\n' jpayne@69: ' print(x)\n' jpayne@69: '\n' jpayne@69: 'See also:\n' jpayne@69: '\n' jpayne@69: ' **PEP 3132** - Extended Iterable Unpacking\n' jpayne@69: ' The specification for the "*target" feature.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Augmented assignment statements\n' jpayne@69: '===============================\n' jpayne@69: '\n' jpayne@69: 'Augmented assignment is the combination, in a single ' jpayne@69: 'statement, of a\n' jpayne@69: 'binary operation and an assignment statement:\n' jpayne@69: '\n' jpayne@69: ' augmented_assignment_stmt ::= augtarget augop ' jpayne@69: '(expression_list | yield_expression)\n' jpayne@69: ' augtarget ::= identifier | attributeref | ' jpayne@69: 'subscription | slicing\n' jpayne@69: ' augop ::= "+=" | "-=" | "*=" | "@=" | ' jpayne@69: '"/=" | "//=" | "%=" | "**="\n' jpayne@69: ' | ">>=" | "<<=" | "&=" | "^=" | "|="\n' jpayne@69: '\n' jpayne@69: '(See section Primaries for the syntax definitions of the last ' jpayne@69: 'three\n' jpayne@69: 'symbols.)\n' jpayne@69: '\n' jpayne@69: 'An augmented assignment evaluates the target (which, unlike ' jpayne@69: 'normal\n' jpayne@69: 'assignment statements, cannot be an unpacking) and the ' jpayne@69: 'expression\n' jpayne@69: 'list, performs the binary operation specific to the type of ' jpayne@69: 'assignment\n' jpayne@69: 'on the two operands, and assigns the result to the original ' jpayne@69: 'target.\n' jpayne@69: 'The target is only evaluated once.\n' jpayne@69: '\n' jpayne@69: 'An augmented assignment expression like "x += 1" can be ' jpayne@69: 'rewritten as\n' jpayne@69: '"x = x + 1" to achieve a similar, but not exactly equal ' jpayne@69: 'effect. In the\n' jpayne@69: 'augmented version, "x" is only evaluated once. Also, when ' jpayne@69: 'possible,\n' jpayne@69: 'the actual operation is performed *in-place*, meaning that ' jpayne@69: 'rather than\n' jpayne@69: 'creating a new object and assigning that to the target, the ' jpayne@69: 'old object\n' jpayne@69: 'is modified instead.\n' jpayne@69: '\n' jpayne@69: 'Unlike normal assignments, augmented assignments evaluate the ' jpayne@69: 'left-\n' jpayne@69: 'hand side *before* evaluating the right-hand side. For ' jpayne@69: 'example, "a[i]\n' jpayne@69: '+= f(x)" first looks-up "a[i]", then it evaluates "f(x)" and ' jpayne@69: 'performs\n' jpayne@69: 'the addition, and lastly, it writes the result back to ' jpayne@69: '"a[i]".\n' jpayne@69: '\n' jpayne@69: 'With the exception of assigning to tuples and multiple targets ' jpayne@69: 'in a\n' jpayne@69: 'single statement, the assignment done by augmented assignment\n' jpayne@69: 'statements is handled the same way as normal assignments. ' jpayne@69: 'Similarly,\n' jpayne@69: 'with the exception of the possible *in-place* behavior, the ' jpayne@69: 'binary\n' jpayne@69: 'operation performed by augmented assignment is the same as the ' jpayne@69: 'normal\n' jpayne@69: 'binary operations.\n' jpayne@69: '\n' jpayne@69: 'For targets which are attribute references, the same caveat ' jpayne@69: 'about\n' jpayne@69: 'class and instance attributes applies as for regular ' jpayne@69: 'assignments.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Annotated assignment statements\n' jpayne@69: '===============================\n' jpayne@69: '\n' jpayne@69: '*Annotation* assignment is the combination, in a single ' jpayne@69: 'statement, of\n' jpayne@69: 'a variable or attribute annotation and an optional assignment\n' jpayne@69: 'statement:\n' jpayne@69: '\n' jpayne@69: ' annotated_assignment_stmt ::= augtarget ":" expression\n' jpayne@69: ' ["=" (starred_expression | ' jpayne@69: 'yield_expression)]\n' jpayne@69: '\n' jpayne@69: 'The difference from normal Assignment statements is that only ' jpayne@69: 'single\n' jpayne@69: 'target is allowed.\n' jpayne@69: '\n' jpayne@69: 'For simple names as assignment targets, if in class or module ' jpayne@69: 'scope,\n' jpayne@69: 'the annotations are evaluated and stored in a special class or ' jpayne@69: 'module\n' jpayne@69: 'attribute "__annotations__" that is a dictionary mapping from ' jpayne@69: 'variable\n' jpayne@69: 'names (mangled if private) to evaluated annotations. This ' jpayne@69: 'attribute is\n' jpayne@69: 'writable and is automatically created at the start of class or ' jpayne@69: 'module\n' jpayne@69: 'body execution, if annotations are found statically.\n' jpayne@69: '\n' jpayne@69: 'For expressions as assignment targets, the annotations are ' jpayne@69: 'evaluated\n' jpayne@69: 'if in class or module scope, but not stored.\n' jpayne@69: '\n' jpayne@69: 'If a name is annotated in a function scope, then this name is ' jpayne@69: 'local\n' jpayne@69: 'for that scope. Annotations are never evaluated and stored in ' jpayne@69: 'function\n' jpayne@69: 'scopes.\n' jpayne@69: '\n' jpayne@69: 'If the right hand side is present, an annotated assignment ' jpayne@69: 'performs\n' jpayne@69: 'the actual assignment before evaluating annotations (where\n' jpayne@69: 'applicable). If the right hand side is not present for an ' jpayne@69: 'expression\n' jpayne@69: 'target, then the interpreter evaluates the target except for ' jpayne@69: 'the last\n' jpayne@69: '"__setitem__()" or "__setattr__()" call.\n' jpayne@69: '\n' jpayne@69: 'See also:\n' jpayne@69: '\n' jpayne@69: ' **PEP 526** - Syntax for Variable Annotations\n' jpayne@69: ' The proposal that added syntax for annotating the types ' jpayne@69: 'of\n' jpayne@69: ' variables (including class variables and instance ' jpayne@69: 'variables),\n' jpayne@69: ' instead of expressing them through comments.\n' jpayne@69: '\n' jpayne@69: ' **PEP 484** - Type hints\n' jpayne@69: ' The proposal that added the "typing" module to provide a ' jpayne@69: 'standard\n' jpayne@69: ' syntax for type annotations that can be used in static ' jpayne@69: 'analysis\n' jpayne@69: ' tools and IDEs.\n' jpayne@69: '\n' jpayne@69: 'Changed in version 3.8: Now annotated assignments allow same\n' jpayne@69: 'expressions in the right hand side as the regular ' jpayne@69: 'assignments.\n' jpayne@69: 'Previously, some expressions (like un-parenthesized tuple ' jpayne@69: 'expressions)\n' jpayne@69: 'caused a syntax error.\n', jpayne@69: 'async': 'Coroutines\n' jpayne@69: '**********\n' jpayne@69: '\n' jpayne@69: 'New in version 3.5.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Coroutine function definition\n' jpayne@69: '=============================\n' jpayne@69: '\n' jpayne@69: ' async_funcdef ::= [decorators] "async" "def" funcname "(" ' jpayne@69: '[parameter_list] ")"\n' jpayne@69: ' ["->" expression] ":" suite\n' jpayne@69: '\n' jpayne@69: 'Execution of Python coroutines can be suspended and resumed at ' jpayne@69: 'many\n' jpayne@69: 'points (see *coroutine*). Inside the body of a coroutine ' jpayne@69: 'function,\n' jpayne@69: '"await" and "async" identifiers become reserved keywords; "await"\n' jpayne@69: 'expressions, "async for" and "async with" can only be used in\n' jpayne@69: 'coroutine function bodies.\n' jpayne@69: '\n' jpayne@69: 'Functions defined with "async def" syntax are always coroutine\n' jpayne@69: 'functions, even if they do not contain "await" or "async" ' jpayne@69: 'keywords.\n' jpayne@69: '\n' jpayne@69: 'It is a "SyntaxError" to use a "yield from" expression inside the ' jpayne@69: 'body\n' jpayne@69: 'of a coroutine function.\n' jpayne@69: '\n' jpayne@69: 'An example of a coroutine function:\n' jpayne@69: '\n' jpayne@69: ' async def func(param1, param2):\n' jpayne@69: ' do_stuff()\n' jpayne@69: ' await some_coroutine()\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'The "async for" statement\n' jpayne@69: '=========================\n' jpayne@69: '\n' jpayne@69: ' async_for_stmt ::= "async" for_stmt\n' jpayne@69: '\n' jpayne@69: 'An *asynchronous iterable* is able to call asynchronous code in ' jpayne@69: 'its\n' jpayne@69: '*iter* implementation, and *asynchronous iterator* can call\n' jpayne@69: 'asynchronous code in its *next* method.\n' jpayne@69: '\n' jpayne@69: 'The "async for" statement allows convenient iteration over\n' jpayne@69: 'asynchronous iterators.\n' jpayne@69: '\n' jpayne@69: 'The following code:\n' jpayne@69: '\n' jpayne@69: ' async for TARGET in ITER:\n' jpayne@69: ' BLOCK\n' jpayne@69: ' else:\n' jpayne@69: ' BLOCK2\n' jpayne@69: '\n' jpayne@69: 'Is semantically equivalent to:\n' jpayne@69: '\n' jpayne@69: ' iter = (ITER)\n' jpayne@69: ' iter = type(iter).__aiter__(iter)\n' jpayne@69: ' running = True\n' jpayne@69: ' while running:\n' jpayne@69: ' try:\n' jpayne@69: ' TARGET = await type(iter).__anext__(iter)\n' jpayne@69: ' except StopAsyncIteration:\n' jpayne@69: ' running = False\n' jpayne@69: ' else:\n' jpayne@69: ' BLOCK\n' jpayne@69: ' else:\n' jpayne@69: ' BLOCK2\n' jpayne@69: '\n' jpayne@69: 'See also "__aiter__()" and "__anext__()" for details.\n' jpayne@69: '\n' jpayne@69: 'It is a "SyntaxError" to use an "async for" statement outside the ' jpayne@69: 'body\n' jpayne@69: 'of a coroutine function.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'The "async with" statement\n' jpayne@69: '==========================\n' jpayne@69: '\n' jpayne@69: ' async_with_stmt ::= "async" with_stmt\n' jpayne@69: '\n' jpayne@69: 'An *asynchronous context manager* is a *context manager* that is ' jpayne@69: 'able\n' jpayne@69: 'to suspend execution in its *enter* and *exit* methods.\n' jpayne@69: '\n' jpayne@69: 'The following code:\n' jpayne@69: '\n' jpayne@69: ' async with EXPR as VAR:\n' jpayne@69: ' BLOCK\n' jpayne@69: '\n' jpayne@69: 'Is semantically equivalent to:\n' jpayne@69: '\n' jpayne@69: ' mgr = (EXPR)\n' jpayne@69: ' aexit = type(mgr).__aexit__\n' jpayne@69: ' aenter = type(mgr).__aenter__(mgr)\n' jpayne@69: '\n' jpayne@69: ' VAR = await aenter\n' jpayne@69: ' try:\n' jpayne@69: ' BLOCK\n' jpayne@69: ' except:\n' jpayne@69: ' if not await aexit(mgr, *sys.exc_info()):\n' jpayne@69: ' raise\n' jpayne@69: ' else:\n' jpayne@69: ' await aexit(mgr, None, None, None)\n' jpayne@69: '\n' jpayne@69: 'See also "__aenter__()" and "__aexit__()" for details.\n' jpayne@69: '\n' jpayne@69: 'It is a "SyntaxError" to use an "async with" statement outside the\n' jpayne@69: 'body of a coroutine function.\n' jpayne@69: '\n' jpayne@69: 'See also:\n' jpayne@69: '\n' jpayne@69: ' **PEP 492** - Coroutines with async and await syntax\n' jpayne@69: ' The proposal that made coroutines a proper standalone concept ' jpayne@69: 'in\n' jpayne@69: ' Python, and added supporting syntax.\n' jpayne@69: '\n' jpayne@69: '-[ Footnotes ]-\n' jpayne@69: '\n' jpayne@69: '[1] The exception is propagated to the invocation stack unless\n' jpayne@69: ' there is a "finally" clause which happens to raise another\n' jpayne@69: ' exception. That new exception causes the old one to be lost.\n' jpayne@69: '\n' jpayne@69: '[2] A string literal appearing as the first statement in the\n' jpayne@69: ' function body is transformed into the function’s "__doc__"\n' jpayne@69: ' attribute and therefore the function’s *docstring*.\n' jpayne@69: '\n' jpayne@69: '[3] A string literal appearing as the first statement in the class\n' jpayne@69: ' body is transformed into the namespace’s "__doc__" item and\n' jpayne@69: ' therefore the class’s *docstring*.\n', jpayne@69: 'atom-identifiers': 'Identifiers (Names)\n' jpayne@69: '*******************\n' jpayne@69: '\n' jpayne@69: 'An identifier occurring as an atom is a name. See ' jpayne@69: 'section Identifiers\n' jpayne@69: 'and keywords for lexical definition and section Naming ' jpayne@69: 'and binding for\n' jpayne@69: 'documentation of naming and binding.\n' jpayne@69: '\n' jpayne@69: 'When the name is bound to an object, evaluation of the ' jpayne@69: 'atom yields\n' jpayne@69: 'that object. When a name is not bound, an attempt to ' jpayne@69: 'evaluate it\n' jpayne@69: 'raises a "NameError" exception.\n' jpayne@69: '\n' jpayne@69: '**Private name mangling:** When an identifier that ' jpayne@69: 'textually occurs in\n' jpayne@69: 'a class definition begins with two or more underscore ' jpayne@69: 'characters and\n' jpayne@69: 'does not end in two or more underscores, it is ' jpayne@69: 'considered a *private\n' jpayne@69: 'name* of that class. Private names are transformed to a ' jpayne@69: 'longer form\n' jpayne@69: 'before code is generated for them. The transformation ' jpayne@69: 'inserts the\n' jpayne@69: 'class name, with leading underscores removed and a ' jpayne@69: 'single underscore\n' jpayne@69: 'inserted, in front of the name. For example, the ' jpayne@69: 'identifier "__spam"\n' jpayne@69: 'occurring in a class named "Ham" will be transformed to ' jpayne@69: '"_Ham__spam".\n' jpayne@69: 'This transformation is independent of the syntactical ' jpayne@69: 'context in which\n' jpayne@69: 'the identifier is used. If the transformed name is ' jpayne@69: 'extremely long\n' jpayne@69: '(longer than 255 characters), implementation defined ' jpayne@69: 'truncation may\n' jpayne@69: 'happen. If the class name consists only of underscores, ' jpayne@69: 'no\n' jpayne@69: 'transformation is done.\n', jpayne@69: 'atom-literals': 'Literals\n' jpayne@69: '********\n' jpayne@69: '\n' jpayne@69: 'Python supports string and bytes literals and various ' jpayne@69: 'numeric\n' jpayne@69: 'literals:\n' jpayne@69: '\n' jpayne@69: ' literal ::= stringliteral | bytesliteral\n' jpayne@69: ' | integer | floatnumber | imagnumber\n' jpayne@69: '\n' jpayne@69: 'Evaluation of a literal yields an object of the given type ' jpayne@69: '(string,\n' jpayne@69: 'bytes, integer, floating point number, complex number) with ' jpayne@69: 'the given\n' jpayne@69: 'value. The value may be approximated in the case of ' jpayne@69: 'floating point\n' jpayne@69: 'and imaginary (complex) literals. See section Literals for ' jpayne@69: 'details.\n' jpayne@69: '\n' jpayne@69: 'All literals correspond to immutable data types, and hence ' jpayne@69: 'the\n' jpayne@69: 'object’s identity is less important than its value. ' jpayne@69: 'Multiple\n' jpayne@69: 'evaluations of literals with the same value (either the ' jpayne@69: 'same\n' jpayne@69: 'occurrence in the program text or a different occurrence) ' jpayne@69: 'may obtain\n' jpayne@69: 'the same object or a different object with the same ' jpayne@69: 'value.\n', jpayne@69: 'attribute-access': 'Customizing attribute access\n' jpayne@69: '****************************\n' jpayne@69: '\n' jpayne@69: 'The following methods can be defined to customize the ' jpayne@69: 'meaning of\n' jpayne@69: 'attribute access (use of, assignment to, or deletion of ' jpayne@69: '"x.name") for\n' jpayne@69: 'class instances.\n' jpayne@69: '\n' jpayne@69: 'object.__getattr__(self, name)\n' jpayne@69: '\n' jpayne@69: ' Called when the default attribute access fails with ' jpayne@69: 'an\n' jpayne@69: ' "AttributeError" (either "__getattribute__()" raises ' jpayne@69: 'an\n' jpayne@69: ' "AttributeError" because *name* is not an instance ' jpayne@69: 'attribute or an\n' jpayne@69: ' attribute in the class tree for "self"; or ' jpayne@69: '"__get__()" of a *name*\n' jpayne@69: ' property raises "AttributeError"). This method ' jpayne@69: 'should either\n' jpayne@69: ' return the (computed) attribute value or raise an ' jpayne@69: '"AttributeError"\n' jpayne@69: ' exception.\n' jpayne@69: '\n' jpayne@69: ' Note that if the attribute is found through the ' jpayne@69: 'normal mechanism,\n' jpayne@69: ' "__getattr__()" is not called. (This is an ' jpayne@69: 'intentional asymmetry\n' jpayne@69: ' between "__getattr__()" and "__setattr__()".) This is ' jpayne@69: 'done both for\n' jpayne@69: ' efficiency reasons and because otherwise ' jpayne@69: '"__getattr__()" would have\n' jpayne@69: ' no way to access other attributes of the instance. ' jpayne@69: 'Note that at\n' jpayne@69: ' least for instance variables, you can fake total ' jpayne@69: 'control by not\n' jpayne@69: ' inserting any values in the instance attribute ' jpayne@69: 'dictionary (but\n' jpayne@69: ' instead inserting them in another object). See the\n' jpayne@69: ' "__getattribute__()" method below for a way to ' jpayne@69: 'actually get total\n' jpayne@69: ' control over attribute access.\n' jpayne@69: '\n' jpayne@69: 'object.__getattribute__(self, name)\n' jpayne@69: '\n' jpayne@69: ' Called unconditionally to implement attribute ' jpayne@69: 'accesses for\n' jpayne@69: ' instances of the class. If the class also defines ' jpayne@69: '"__getattr__()",\n' jpayne@69: ' the latter will not be called unless ' jpayne@69: '"__getattribute__()" either\n' jpayne@69: ' calls it explicitly or raises an "AttributeError". ' jpayne@69: 'This method\n' jpayne@69: ' should return the (computed) attribute value or raise ' jpayne@69: 'an\n' jpayne@69: ' "AttributeError" exception. In order to avoid ' jpayne@69: 'infinite recursion in\n' jpayne@69: ' this method, its implementation should always call ' jpayne@69: 'the base class\n' jpayne@69: ' method with the same name to access any attributes it ' jpayne@69: 'needs, for\n' jpayne@69: ' example, "object.__getattribute__(self, name)".\n' jpayne@69: '\n' jpayne@69: ' Note: This method may still be bypassed when looking ' jpayne@69: 'up special\n' jpayne@69: ' methods as the result of implicit invocation via ' jpayne@69: 'language syntax\n' jpayne@69: ' or built-in functions. See Special method lookup.\n' jpayne@69: '\n' jpayne@69: 'object.__setattr__(self, name, value)\n' jpayne@69: '\n' jpayne@69: ' Called when an attribute assignment is attempted. ' jpayne@69: 'This is called\n' jpayne@69: ' instead of the normal mechanism (i.e. store the value ' jpayne@69: 'in the\n' jpayne@69: ' instance dictionary). *name* is the attribute name, ' jpayne@69: '*value* is the\n' jpayne@69: ' value to be assigned to it.\n' jpayne@69: '\n' jpayne@69: ' If "__setattr__()" wants to assign to an instance ' jpayne@69: 'attribute, it\n' jpayne@69: ' should call the base class method with the same name, ' jpayne@69: 'for example,\n' jpayne@69: ' "object.__setattr__(self, name, value)".\n' jpayne@69: '\n' jpayne@69: 'object.__delattr__(self, name)\n' jpayne@69: '\n' jpayne@69: ' Like "__setattr__()" but for attribute deletion ' jpayne@69: 'instead of\n' jpayne@69: ' assignment. This should only be implemented if "del ' jpayne@69: 'obj.name" is\n' jpayne@69: ' meaningful for the object.\n' jpayne@69: '\n' jpayne@69: 'object.__dir__(self)\n' jpayne@69: '\n' jpayne@69: ' Called when "dir()" is called on the object. A ' jpayne@69: 'sequence must be\n' jpayne@69: ' returned. "dir()" converts the returned sequence to a ' jpayne@69: 'list and\n' jpayne@69: ' sorts it.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Customizing module attribute access\n' jpayne@69: '===================================\n' jpayne@69: '\n' jpayne@69: 'Special names "__getattr__" and "__dir__" can be also ' jpayne@69: 'used to\n' jpayne@69: 'customize access to module attributes. The "__getattr__" ' jpayne@69: 'function at\n' jpayne@69: 'the module level should accept one argument which is the ' jpayne@69: 'name of an\n' jpayne@69: 'attribute and return the computed value or raise an ' jpayne@69: '"AttributeError".\n' jpayne@69: 'If an attribute is not found on a module object through ' jpayne@69: 'the normal\n' jpayne@69: 'lookup, i.e. "object.__getattribute__()", then ' jpayne@69: '"__getattr__" is\n' jpayne@69: 'searched in the module "__dict__" before raising an ' jpayne@69: '"AttributeError".\n' jpayne@69: 'If found, it is called with the attribute name and the ' jpayne@69: 'result is\n' jpayne@69: 'returned.\n' jpayne@69: '\n' jpayne@69: 'The "__dir__" function should accept no arguments, and ' jpayne@69: 'return a\n' jpayne@69: 'sequence of strings that represents the names accessible ' jpayne@69: 'on module. If\n' jpayne@69: 'present, this function overrides the standard "dir()" ' jpayne@69: 'search on a\n' jpayne@69: 'module.\n' jpayne@69: '\n' jpayne@69: 'For a more fine grained customization of the module ' jpayne@69: 'behavior (setting\n' jpayne@69: 'attributes, properties, etc.), one can set the ' jpayne@69: '"__class__" attribute\n' jpayne@69: 'of a module object to a subclass of "types.ModuleType". ' jpayne@69: 'For example:\n' jpayne@69: '\n' jpayne@69: ' import sys\n' jpayne@69: ' from types import ModuleType\n' jpayne@69: '\n' jpayne@69: ' class VerboseModule(ModuleType):\n' jpayne@69: ' def __repr__(self):\n' jpayne@69: " return f'Verbose {self.__name__}'\n" jpayne@69: '\n' jpayne@69: ' def __setattr__(self, attr, value):\n' jpayne@69: " print(f'Setting {attr}...')\n" jpayne@69: ' super().__setattr__(attr, value)\n' jpayne@69: '\n' jpayne@69: ' sys.modules[__name__].__class__ = VerboseModule\n' jpayne@69: '\n' jpayne@69: 'Note: Defining module "__getattr__" and setting module ' jpayne@69: '"__class__"\n' jpayne@69: ' only affect lookups made using the attribute access ' jpayne@69: 'syntax –\n' jpayne@69: ' directly accessing the module globals (whether by code ' jpayne@69: 'within the\n' jpayne@69: ' module, or via a reference to the module’s globals ' jpayne@69: 'dictionary) is\n' jpayne@69: ' unaffected.\n' jpayne@69: '\n' jpayne@69: 'Changed in version 3.5: "__class__" module attribute is ' jpayne@69: 'now writable.\n' jpayne@69: '\n' jpayne@69: 'New in version 3.7: "__getattr__" and "__dir__" module ' jpayne@69: 'attributes.\n' jpayne@69: '\n' jpayne@69: 'See also:\n' jpayne@69: '\n' jpayne@69: ' **PEP 562** - Module __getattr__ and __dir__\n' jpayne@69: ' Describes the "__getattr__" and "__dir__" functions ' jpayne@69: 'on modules.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Implementing Descriptors\n' jpayne@69: '========================\n' jpayne@69: '\n' jpayne@69: 'The following methods only apply when an instance of the ' jpayne@69: 'class\n' jpayne@69: 'containing the method (a so-called *descriptor* class) ' jpayne@69: 'appears in an\n' jpayne@69: '*owner* class (the descriptor must be in either the ' jpayne@69: 'owner’s class\n' jpayne@69: 'dictionary or in the class dictionary for one of its ' jpayne@69: 'parents). In the\n' jpayne@69: 'examples below, “the attribute” refers to the attribute ' jpayne@69: 'whose name is\n' jpayne@69: 'the key of the property in the owner class’ "__dict__".\n' jpayne@69: '\n' jpayne@69: 'object.__get__(self, instance, owner=None)\n' jpayne@69: '\n' jpayne@69: ' Called to get the attribute of the owner class (class ' jpayne@69: 'attribute\n' jpayne@69: ' access) or of an instance of that class (instance ' jpayne@69: 'attribute\n' jpayne@69: ' access). The optional *owner* argument is the owner ' jpayne@69: 'class, while\n' jpayne@69: ' *instance* is the instance that the attribute was ' jpayne@69: 'accessed through,\n' jpayne@69: ' or "None" when the attribute is accessed through the ' jpayne@69: '*owner*.\n' jpayne@69: '\n' jpayne@69: ' This method should return the computed attribute ' jpayne@69: 'value or raise an\n' jpayne@69: ' "AttributeError" exception.\n' jpayne@69: '\n' jpayne@69: ' **PEP 252** specifies that "__get__()" is callable ' jpayne@69: 'with one or two\n' jpayne@69: ' arguments. Python’s own built-in descriptors support ' jpayne@69: 'this\n' jpayne@69: ' specification; however, it is likely that some ' jpayne@69: 'third-party tools\n' jpayne@69: ' have descriptors that require both arguments. ' jpayne@69: 'Python’s own\n' jpayne@69: ' "__getattribute__()" implementation always passes in ' jpayne@69: 'both arguments\n' jpayne@69: ' whether they are required or not.\n' jpayne@69: '\n' jpayne@69: 'object.__set__(self, instance, value)\n' jpayne@69: '\n' jpayne@69: ' Called to set the attribute on an instance *instance* ' jpayne@69: 'of the owner\n' jpayne@69: ' class to a new value, *value*.\n' jpayne@69: '\n' jpayne@69: ' Note, adding "__set__()" or "__delete__()" changes ' jpayne@69: 'the kind of\n' jpayne@69: ' descriptor to a “data descriptor”. See Invoking ' jpayne@69: 'Descriptors for\n' jpayne@69: ' more details.\n' jpayne@69: '\n' jpayne@69: 'object.__delete__(self, instance)\n' jpayne@69: '\n' jpayne@69: ' Called to delete the attribute on an instance ' jpayne@69: '*instance* of the\n' jpayne@69: ' owner class.\n' jpayne@69: '\n' jpayne@69: 'object.__set_name__(self, owner, name)\n' jpayne@69: '\n' jpayne@69: ' Called at the time the owning class *owner* is ' jpayne@69: 'created. The\n' jpayne@69: ' descriptor has been assigned to *name*.\n' jpayne@69: '\n' jpayne@69: ' Note: "__set_name__()" is only called implicitly as ' jpayne@69: 'part of the\n' jpayne@69: ' "type" constructor, so it will need to be called ' jpayne@69: 'explicitly with\n' jpayne@69: ' the appropriate parameters when a descriptor is ' jpayne@69: 'added to a class\n' jpayne@69: ' after initial creation:\n' jpayne@69: '\n' jpayne@69: ' class A:\n' jpayne@69: ' pass\n' jpayne@69: ' descr = custom_descriptor()\n' jpayne@69: ' A.attr = descr\n' jpayne@69: " descr.__set_name__(A, 'attr')\n" jpayne@69: '\n' jpayne@69: ' See Creating the class object for more details.\n' jpayne@69: '\n' jpayne@69: ' New in version 3.6.\n' jpayne@69: '\n' jpayne@69: 'The attribute "__objclass__" is interpreted by the ' jpayne@69: '"inspect" module as\n' jpayne@69: 'specifying the class where this object was defined ' jpayne@69: '(setting this\n' jpayne@69: 'appropriately can assist in runtime introspection of ' jpayne@69: 'dynamic class\n' jpayne@69: 'attributes). For callables, it may indicate that an ' jpayne@69: 'instance of the\n' jpayne@69: 'given type (or a subclass) is expected or required as ' jpayne@69: 'the first\n' jpayne@69: 'positional argument (for example, CPython sets this ' jpayne@69: 'attribute for\n' jpayne@69: 'unbound methods that are implemented in C).\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Invoking Descriptors\n' jpayne@69: '====================\n' jpayne@69: '\n' jpayne@69: 'In general, a descriptor is an object attribute with ' jpayne@69: '“binding\n' jpayne@69: 'behavior”, one whose attribute access has been ' jpayne@69: 'overridden by methods\n' jpayne@69: 'in the descriptor protocol: "__get__()", "__set__()", ' jpayne@69: 'and\n' jpayne@69: '"__delete__()". If any of those methods are defined for ' jpayne@69: 'an object, it\n' jpayne@69: 'is said to be a descriptor.\n' jpayne@69: '\n' jpayne@69: 'The default behavior for attribute access is to get, ' jpayne@69: 'set, or delete\n' jpayne@69: 'the attribute from an object’s dictionary. For instance, ' jpayne@69: '"a.x" has a\n' jpayne@69: 'lookup chain starting with "a.__dict__[\'x\']", then\n' jpayne@69: '"type(a).__dict__[\'x\']", and continuing through the ' jpayne@69: 'base classes of\n' jpayne@69: '"type(a)" excluding metaclasses.\n' jpayne@69: '\n' jpayne@69: 'However, if the looked-up value is an object defining ' jpayne@69: 'one of the\n' jpayne@69: 'descriptor methods, then Python may override the default ' jpayne@69: 'behavior and\n' jpayne@69: 'invoke the descriptor method instead. Where this occurs ' jpayne@69: 'in the\n' jpayne@69: 'precedence chain depends on which descriptor methods ' jpayne@69: 'were defined and\n' jpayne@69: 'how they were called.\n' jpayne@69: '\n' jpayne@69: 'The starting point for descriptor invocation is a ' jpayne@69: 'binding, "a.x". How\n' jpayne@69: 'the arguments are assembled depends on "a":\n' jpayne@69: '\n' jpayne@69: 'Direct Call\n' jpayne@69: ' The simplest and least common call is when user code ' jpayne@69: 'directly\n' jpayne@69: ' invokes a descriptor method: "x.__get__(a)".\n' jpayne@69: '\n' jpayne@69: 'Instance Binding\n' jpayne@69: ' If binding to an object instance, "a.x" is ' jpayne@69: 'transformed into the\n' jpayne@69: ' call: "type(a).__dict__[\'x\'].__get__(a, type(a))".\n' jpayne@69: '\n' jpayne@69: 'Class Binding\n' jpayne@69: ' If binding to a class, "A.x" is transformed into the ' jpayne@69: 'call:\n' jpayne@69: ' "A.__dict__[\'x\'].__get__(None, A)".\n' jpayne@69: '\n' jpayne@69: 'Super Binding\n' jpayne@69: ' If "a" is an instance of "super", then the binding ' jpayne@69: '"super(B,\n' jpayne@69: ' obj).m()" searches "obj.__class__.__mro__" for the ' jpayne@69: 'base class "A"\n' jpayne@69: ' immediately preceding "B" and then invokes the ' jpayne@69: 'descriptor with the\n' jpayne@69: ' call: "A.__dict__[\'m\'].__get__(obj, ' jpayne@69: 'obj.__class__)".\n' jpayne@69: '\n' jpayne@69: 'For instance bindings, the precedence of descriptor ' jpayne@69: 'invocation depends\n' jpayne@69: 'on the which descriptor methods are defined. A ' jpayne@69: 'descriptor can define\n' jpayne@69: 'any combination of "__get__()", "__set__()" and ' jpayne@69: '"__delete__()". If it\n' jpayne@69: 'does not define "__get__()", then accessing the ' jpayne@69: 'attribute will return\n' jpayne@69: 'the descriptor object itself unless there is a value in ' jpayne@69: 'the object’s\n' jpayne@69: 'instance dictionary. If the descriptor defines ' jpayne@69: '"__set__()" and/or\n' jpayne@69: '"__delete__()", it is a data descriptor; if it defines ' jpayne@69: 'neither, it is\n' jpayne@69: 'a non-data descriptor. Normally, data descriptors ' jpayne@69: 'define both\n' jpayne@69: '"__get__()" and "__set__()", while non-data descriptors ' jpayne@69: 'have just the\n' jpayne@69: '"__get__()" method. Data descriptors with "__set__()" ' jpayne@69: 'and "__get__()"\n' jpayne@69: 'defined always override a redefinition in an instance ' jpayne@69: 'dictionary. In\n' jpayne@69: 'contrast, non-data descriptors can be overridden by ' jpayne@69: 'instances.\n' jpayne@69: '\n' jpayne@69: 'Python methods (including "staticmethod()" and ' jpayne@69: '"classmethod()") are\n' jpayne@69: 'implemented as non-data descriptors. Accordingly, ' jpayne@69: 'instances can\n' jpayne@69: 'redefine and override methods. This allows individual ' jpayne@69: 'instances to\n' jpayne@69: 'acquire behaviors that differ from other instances of ' jpayne@69: 'the same class.\n' jpayne@69: '\n' jpayne@69: 'The "property()" function is implemented as a data ' jpayne@69: 'descriptor.\n' jpayne@69: 'Accordingly, instances cannot override the behavior of a ' jpayne@69: 'property.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: '__slots__\n' jpayne@69: '=========\n' jpayne@69: '\n' jpayne@69: '*__slots__* allow us to explicitly declare data members ' jpayne@69: '(like\n' jpayne@69: 'properties) and deny the creation of *__dict__* and ' jpayne@69: '*__weakref__*\n' jpayne@69: '(unless explicitly declared in *__slots__* or available ' jpayne@69: 'in a parent.)\n' jpayne@69: '\n' jpayne@69: 'The space saved over using *__dict__* can be ' jpayne@69: 'significant. Attribute\n' jpayne@69: 'lookup speed can be significantly improved as well.\n' jpayne@69: '\n' jpayne@69: 'object.__slots__\n' jpayne@69: '\n' jpayne@69: ' This class variable can be assigned a string, ' jpayne@69: 'iterable, or sequence\n' jpayne@69: ' of strings with variable names used by instances. ' jpayne@69: '*__slots__*\n' jpayne@69: ' reserves space for the declared variables and ' jpayne@69: 'prevents the\n' jpayne@69: ' automatic creation of *__dict__* and *__weakref__* ' jpayne@69: 'for each\n' jpayne@69: ' instance.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Notes on using *__slots__*\n' jpayne@69: '--------------------------\n' jpayne@69: '\n' jpayne@69: '* When inheriting from a class without *__slots__*, the ' jpayne@69: '*__dict__*\n' jpayne@69: ' and *__weakref__* attribute of the instances will ' jpayne@69: 'always be\n' jpayne@69: ' accessible.\n' jpayne@69: '\n' jpayne@69: '* Without a *__dict__* variable, instances cannot be ' jpayne@69: 'assigned new\n' jpayne@69: ' variables not listed in the *__slots__* definition. ' jpayne@69: 'Attempts to\n' jpayne@69: ' assign to an unlisted variable name raises ' jpayne@69: '"AttributeError". If\n' jpayne@69: ' dynamic assignment of new variables is desired, then ' jpayne@69: 'add\n' jpayne@69: ' "\'__dict__\'" to the sequence of strings in the ' jpayne@69: '*__slots__*\n' jpayne@69: ' declaration.\n' jpayne@69: '\n' jpayne@69: '* Without a *__weakref__* variable for each instance, ' jpayne@69: 'classes\n' jpayne@69: ' defining *__slots__* do not support weak references to ' jpayne@69: 'its\n' jpayne@69: ' instances. If weak reference support is needed, then ' jpayne@69: 'add\n' jpayne@69: ' "\'__weakref__\'" to the sequence of strings in the ' jpayne@69: '*__slots__*\n' jpayne@69: ' declaration.\n' jpayne@69: '\n' jpayne@69: '* *__slots__* are implemented at the class level by ' jpayne@69: 'creating\n' jpayne@69: ' descriptors (Implementing Descriptors) for each ' jpayne@69: 'variable name. As a\n' jpayne@69: ' result, class attributes cannot be used to set default ' jpayne@69: 'values for\n' jpayne@69: ' instance variables defined by *__slots__*; otherwise, ' jpayne@69: 'the class\n' jpayne@69: ' attribute would overwrite the descriptor assignment.\n' jpayne@69: '\n' jpayne@69: '* The action of a *__slots__* declaration is not limited ' jpayne@69: 'to the\n' jpayne@69: ' class where it is defined. *__slots__* declared in ' jpayne@69: 'parents are\n' jpayne@69: ' available in child classes. However, child subclasses ' jpayne@69: 'will get a\n' jpayne@69: ' *__dict__* and *__weakref__* unless they also define ' jpayne@69: '*__slots__*\n' jpayne@69: ' (which should only contain names of any *additional* ' jpayne@69: 'slots).\n' jpayne@69: '\n' jpayne@69: '* If a class defines a slot also defined in a base ' jpayne@69: 'class, the\n' jpayne@69: ' instance variable defined by the base class slot is ' jpayne@69: 'inaccessible\n' jpayne@69: ' (except by retrieving its descriptor directly from the ' jpayne@69: 'base class).\n' jpayne@69: ' This renders the meaning of the program undefined. In ' jpayne@69: 'the future, a\n' jpayne@69: ' check may be added to prevent this.\n' jpayne@69: '\n' jpayne@69: '* Nonempty *__slots__* does not work for classes derived ' jpayne@69: 'from\n' jpayne@69: ' “variable-length” built-in types such as "int", ' jpayne@69: '"bytes" and "tuple".\n' jpayne@69: '\n' jpayne@69: '* Any non-string iterable may be assigned to ' jpayne@69: '*__slots__*. Mappings\n' jpayne@69: ' may also be used; however, in the future, special ' jpayne@69: 'meaning may be\n' jpayne@69: ' assigned to the values corresponding to each key.\n' jpayne@69: '\n' jpayne@69: '* *__class__* assignment works only if both classes have ' jpayne@69: 'the same\n' jpayne@69: ' *__slots__*.\n' jpayne@69: '\n' jpayne@69: '* Multiple inheritance with multiple slotted parent ' jpayne@69: 'classes can be\n' jpayne@69: ' used, but only one parent is allowed to have ' jpayne@69: 'attributes created by\n' jpayne@69: ' slots (the other bases must have empty slot layouts) - ' jpayne@69: 'violations\n' jpayne@69: ' raise "TypeError".\n' jpayne@69: '\n' jpayne@69: '* If an iterator is used for *__slots__* then a ' jpayne@69: 'descriptor is\n' jpayne@69: ' created for each of the iterator’s values. However, ' jpayne@69: 'the *__slots__*\n' jpayne@69: ' attribute will be an empty iterator.\n', jpayne@69: 'attribute-references': 'Attribute references\n' jpayne@69: '********************\n' jpayne@69: '\n' jpayne@69: 'An attribute reference is a primary followed by a ' jpayne@69: 'period and a name:\n' jpayne@69: '\n' jpayne@69: ' attributeref ::= primary "." identifier\n' jpayne@69: '\n' jpayne@69: 'The primary must evaluate to an object of a type ' jpayne@69: 'that supports\n' jpayne@69: 'attribute references, which most objects do. This ' jpayne@69: 'object is then\n' jpayne@69: 'asked to produce the attribute whose name is the ' jpayne@69: 'identifier. This\n' jpayne@69: 'production can be customized by overriding the ' jpayne@69: '"__getattr__()" method.\n' jpayne@69: 'If this attribute is not available, the exception ' jpayne@69: '"AttributeError" is\n' jpayne@69: 'raised. Otherwise, the type and value of the object ' jpayne@69: 'produced is\n' jpayne@69: 'determined by the object. Multiple evaluations of ' jpayne@69: 'the same attribute\n' jpayne@69: 'reference may yield different objects.\n', jpayne@69: 'augassign': 'Augmented assignment statements\n' jpayne@69: '*******************************\n' jpayne@69: '\n' jpayne@69: 'Augmented assignment is the combination, in a single statement, ' jpayne@69: 'of a\n' jpayne@69: 'binary operation and an assignment statement:\n' jpayne@69: '\n' jpayne@69: ' augmented_assignment_stmt ::= augtarget augop ' jpayne@69: '(expression_list | yield_expression)\n' jpayne@69: ' augtarget ::= identifier | attributeref | ' jpayne@69: 'subscription | slicing\n' jpayne@69: ' augop ::= "+=" | "-=" | "*=" | "@=" | ' jpayne@69: '"/=" | "//=" | "%=" | "**="\n' jpayne@69: ' | ">>=" | "<<=" | "&=" | "^=" | "|="\n' jpayne@69: '\n' jpayne@69: '(See section Primaries for the syntax definitions of the last ' jpayne@69: 'three\n' jpayne@69: 'symbols.)\n' jpayne@69: '\n' jpayne@69: 'An augmented assignment evaluates the target (which, unlike ' jpayne@69: 'normal\n' jpayne@69: 'assignment statements, cannot be an unpacking) and the ' jpayne@69: 'expression\n' jpayne@69: 'list, performs the binary operation specific to the type of ' jpayne@69: 'assignment\n' jpayne@69: 'on the two operands, and assigns the result to the original ' jpayne@69: 'target.\n' jpayne@69: 'The target is only evaluated once.\n' jpayne@69: '\n' jpayne@69: 'An augmented assignment expression like "x += 1" can be ' jpayne@69: 'rewritten as\n' jpayne@69: '"x = x + 1" to achieve a similar, but not exactly equal effect. ' jpayne@69: 'In the\n' jpayne@69: 'augmented version, "x" is only evaluated once. Also, when ' jpayne@69: 'possible,\n' jpayne@69: 'the actual operation is performed *in-place*, meaning that ' jpayne@69: 'rather than\n' jpayne@69: 'creating a new object and assigning that to the target, the old ' jpayne@69: 'object\n' jpayne@69: 'is modified instead.\n' jpayne@69: '\n' jpayne@69: 'Unlike normal assignments, augmented assignments evaluate the ' jpayne@69: 'left-\n' jpayne@69: 'hand side *before* evaluating the right-hand side. For ' jpayne@69: 'example, "a[i]\n' jpayne@69: '+= f(x)" first looks-up "a[i]", then it evaluates "f(x)" and ' jpayne@69: 'performs\n' jpayne@69: 'the addition, and lastly, it writes the result back to "a[i]".\n' jpayne@69: '\n' jpayne@69: 'With the exception of assigning to tuples and multiple targets ' jpayne@69: 'in a\n' jpayne@69: 'single statement, the assignment done by augmented assignment\n' jpayne@69: 'statements is handled the same way as normal assignments. ' jpayne@69: 'Similarly,\n' jpayne@69: 'with the exception of the possible *in-place* behavior, the ' jpayne@69: 'binary\n' jpayne@69: 'operation performed by augmented assignment is the same as the ' jpayne@69: 'normal\n' jpayne@69: 'binary operations.\n' jpayne@69: '\n' jpayne@69: 'For targets which are attribute references, the same caveat ' jpayne@69: 'about\n' jpayne@69: 'class and instance attributes applies as for regular ' jpayne@69: 'assignments.\n', jpayne@69: 'await': 'Await expression\n' jpayne@69: '****************\n' jpayne@69: '\n' jpayne@69: 'Suspend the execution of *coroutine* on an *awaitable* object. Can\n' jpayne@69: 'only be used inside a *coroutine function*.\n' jpayne@69: '\n' jpayne@69: ' await_expr ::= "await" primary\n' jpayne@69: '\n' jpayne@69: 'New in version 3.5.\n', jpayne@69: 'binary': 'Binary arithmetic operations\n' jpayne@69: '****************************\n' jpayne@69: '\n' jpayne@69: 'The binary arithmetic operations have the conventional priority\n' jpayne@69: 'levels. Note that some of these operations also apply to certain ' jpayne@69: 'non-\n' jpayne@69: 'numeric types. Apart from the power operator, there are only two\n' jpayne@69: 'levels, one for multiplicative operators and one for additive\n' jpayne@69: 'operators:\n' jpayne@69: '\n' jpayne@69: ' m_expr ::= u_expr | m_expr "*" u_expr | m_expr "@" m_expr |\n' jpayne@69: ' m_expr "//" u_expr | m_expr "/" u_expr |\n' jpayne@69: ' m_expr "%" u_expr\n' jpayne@69: ' a_expr ::= m_expr | a_expr "+" m_expr | a_expr "-" m_expr\n' jpayne@69: '\n' jpayne@69: 'The "*" (multiplication) operator yields the product of its ' jpayne@69: 'arguments.\n' jpayne@69: 'The arguments must either both be numbers, or one argument must be ' jpayne@69: 'an\n' jpayne@69: 'integer and the other must be a sequence. In the former case, the\n' jpayne@69: 'numbers are converted to a common type and then multiplied ' jpayne@69: 'together.\n' jpayne@69: 'In the latter case, sequence repetition is performed; a negative\n' jpayne@69: 'repetition factor yields an empty sequence.\n' jpayne@69: '\n' jpayne@69: 'The "@" (at) operator is intended to be used for matrix\n' jpayne@69: 'multiplication. No builtin Python types implement this operator.\n' jpayne@69: '\n' jpayne@69: 'New in version 3.5.\n' jpayne@69: '\n' jpayne@69: 'The "/" (division) and "//" (floor division) operators yield the\n' jpayne@69: 'quotient of their arguments. The numeric arguments are first\n' jpayne@69: 'converted to a common type. Division of integers yields a float, ' jpayne@69: 'while\n' jpayne@69: 'floor division of integers results in an integer; the result is ' jpayne@69: 'that\n' jpayne@69: 'of mathematical division with the ‘floor’ function applied to the\n' jpayne@69: 'result. Division by zero raises the "ZeroDivisionError" ' jpayne@69: 'exception.\n' jpayne@69: '\n' jpayne@69: 'The "%" (modulo) operator yields the remainder from the division ' jpayne@69: 'of\n' jpayne@69: 'the first argument by the second. The numeric arguments are ' jpayne@69: 'first\n' jpayne@69: 'converted to a common type. A zero right argument raises the\n' jpayne@69: '"ZeroDivisionError" exception. The arguments may be floating ' jpayne@69: 'point\n' jpayne@69: 'numbers, e.g., "3.14%0.7" equals "0.34" (since "3.14" equals ' jpayne@69: '"4*0.7 +\n' jpayne@69: '0.34".) The modulo operator always yields a result with the same ' jpayne@69: 'sign\n' jpayne@69: 'as its second operand (or zero); the absolute value of the result ' jpayne@69: 'is\n' jpayne@69: 'strictly smaller than the absolute value of the second operand ' jpayne@69: '[1].\n' jpayne@69: '\n' jpayne@69: 'The floor division and modulo operators are connected by the ' jpayne@69: 'following\n' jpayne@69: 'identity: "x == (x//y)*y + (x%y)". Floor division and modulo are ' jpayne@69: 'also\n' jpayne@69: 'connected with the built-in function "divmod()": "divmod(x, y) ==\n' jpayne@69: '(x//y, x%y)". [2].\n' jpayne@69: '\n' jpayne@69: 'In addition to performing the modulo operation on numbers, the ' jpayne@69: '"%"\n' jpayne@69: 'operator is also overloaded by string objects to perform ' jpayne@69: 'old-style\n' jpayne@69: 'string formatting (also known as interpolation). The syntax for\n' jpayne@69: 'string formatting is described in the Python Library Reference,\n' jpayne@69: 'section printf-style String Formatting.\n' jpayne@69: '\n' jpayne@69: 'The floor division operator, the modulo operator, and the ' jpayne@69: '"divmod()"\n' jpayne@69: 'function are not defined for complex numbers. Instead, convert to ' jpayne@69: 'a\n' jpayne@69: 'floating point number using the "abs()" function if appropriate.\n' jpayne@69: '\n' jpayne@69: 'The "+" (addition) operator yields the sum of its arguments. The\n' jpayne@69: 'arguments must either both be numbers or both be sequences of the ' jpayne@69: 'same\n' jpayne@69: 'type. In the former case, the numbers are converted to a common ' jpayne@69: 'type\n' jpayne@69: 'and then added together. In the latter case, the sequences are\n' jpayne@69: 'concatenated.\n' jpayne@69: '\n' jpayne@69: 'The "-" (subtraction) operator yields the difference of its ' jpayne@69: 'arguments.\n' jpayne@69: 'The numeric arguments are first converted to a common type.\n', jpayne@69: 'bitwise': 'Binary bitwise operations\n' jpayne@69: '*************************\n' jpayne@69: '\n' jpayne@69: 'Each of the three bitwise operations has a different priority ' jpayne@69: 'level:\n' jpayne@69: '\n' jpayne@69: ' and_expr ::= shift_expr | and_expr "&" shift_expr\n' jpayne@69: ' xor_expr ::= and_expr | xor_expr "^" and_expr\n' jpayne@69: ' or_expr ::= xor_expr | or_expr "|" xor_expr\n' jpayne@69: '\n' jpayne@69: 'The "&" operator yields the bitwise AND of its arguments, which ' jpayne@69: 'must\n' jpayne@69: 'be integers.\n' jpayne@69: '\n' jpayne@69: 'The "^" operator yields the bitwise XOR (exclusive OR) of its\n' jpayne@69: 'arguments, which must be integers.\n' jpayne@69: '\n' jpayne@69: 'The "|" operator yields the bitwise (inclusive) OR of its ' jpayne@69: 'arguments,\n' jpayne@69: 'which must be integers.\n', jpayne@69: 'bltin-code-objects': 'Code Objects\n' jpayne@69: '************\n' jpayne@69: '\n' jpayne@69: 'Code objects are used by the implementation to ' jpayne@69: 'represent “pseudo-\n' jpayne@69: 'compiled” executable Python code such as a function ' jpayne@69: 'body. They differ\n' jpayne@69: 'from function objects because they don’t contain a ' jpayne@69: 'reference to their\n' jpayne@69: 'global execution environment. Code objects are ' jpayne@69: 'returned by the built-\n' jpayne@69: 'in "compile()" function and can be extracted from ' jpayne@69: 'function objects\n' jpayne@69: 'through their "__code__" attribute. See also the ' jpayne@69: '"code" module.\n' jpayne@69: '\n' jpayne@69: 'A code object can be executed or evaluated by passing ' jpayne@69: 'it (instead of a\n' jpayne@69: 'source string) to the "exec()" or "eval()" built-in ' jpayne@69: 'functions.\n' jpayne@69: '\n' jpayne@69: 'See The standard type hierarchy for more ' jpayne@69: 'information.\n', jpayne@69: 'bltin-ellipsis-object': 'The Ellipsis Object\n' jpayne@69: '*******************\n' jpayne@69: '\n' jpayne@69: 'This object is commonly used by slicing (see ' jpayne@69: 'Slicings). It supports\n' jpayne@69: 'no special operations. There is exactly one ' jpayne@69: 'ellipsis object, named\n' jpayne@69: '"Ellipsis" (a built-in name). "type(Ellipsis)()" ' jpayne@69: 'produces the\n' jpayne@69: '"Ellipsis" singleton.\n' jpayne@69: '\n' jpayne@69: 'It is written as "Ellipsis" or "...".\n', jpayne@69: 'bltin-null-object': 'The Null Object\n' jpayne@69: '***************\n' jpayne@69: '\n' jpayne@69: 'This object is returned by functions that don’t ' jpayne@69: 'explicitly return a\n' jpayne@69: 'value. It supports no special operations. There is ' jpayne@69: 'exactly one null\n' jpayne@69: 'object, named "None" (a built-in name). "type(None)()" ' jpayne@69: 'produces the\n' jpayne@69: 'same singleton.\n' jpayne@69: '\n' jpayne@69: 'It is written as "None".\n', jpayne@69: 'bltin-type-objects': 'Type Objects\n' jpayne@69: '************\n' jpayne@69: '\n' jpayne@69: 'Type objects represent the various object types. An ' jpayne@69: 'object’s type is\n' jpayne@69: 'accessed by the built-in function "type()". There are ' jpayne@69: 'no special\n' jpayne@69: 'operations on types. The standard module "types" ' jpayne@69: 'defines names for\n' jpayne@69: 'all standard built-in types.\n' jpayne@69: '\n' jpayne@69: 'Types are written like this: "".\n', jpayne@69: 'booleans': 'Boolean operations\n' jpayne@69: '******************\n' jpayne@69: '\n' jpayne@69: ' or_test ::= and_test | or_test "or" and_test\n' jpayne@69: ' and_test ::= not_test | and_test "and" not_test\n' jpayne@69: ' not_test ::= comparison | "not" not_test\n' jpayne@69: '\n' jpayne@69: 'In the context of Boolean operations, and also when expressions ' jpayne@69: 'are\n' jpayne@69: 'used by control flow statements, the following values are ' jpayne@69: 'interpreted\n' jpayne@69: 'as false: "False", "None", numeric zero of all types, and empty\n' jpayne@69: 'strings and containers (including strings, tuples, lists,\n' jpayne@69: 'dictionaries, sets and frozensets). All other values are ' jpayne@69: 'interpreted\n' jpayne@69: 'as true. User-defined objects can customize their truth value ' jpayne@69: 'by\n' jpayne@69: 'providing a "__bool__()" method.\n' jpayne@69: '\n' jpayne@69: 'The operator "not" yields "True" if its argument is false, ' jpayne@69: '"False"\n' jpayne@69: 'otherwise.\n' jpayne@69: '\n' jpayne@69: 'The expression "x and y" first evaluates *x*; if *x* is false, ' jpayne@69: 'its\n' jpayne@69: 'value is returned; otherwise, *y* is evaluated and the resulting ' jpayne@69: 'value\n' jpayne@69: 'is returned.\n' jpayne@69: '\n' jpayne@69: 'The expression "x or y" first evaluates *x*; if *x* is true, its ' jpayne@69: 'value\n' jpayne@69: 'is returned; otherwise, *y* is evaluated and the resulting value ' jpayne@69: 'is\n' jpayne@69: 'returned.\n' jpayne@69: '\n' jpayne@69: 'Note that neither "and" nor "or" restrict the value and type ' jpayne@69: 'they\n' jpayne@69: 'return to "False" and "True", but rather return the last ' jpayne@69: 'evaluated\n' jpayne@69: 'argument. This is sometimes useful, e.g., if "s" is a string ' jpayne@69: 'that\n' jpayne@69: 'should be replaced by a default value if it is empty, the ' jpayne@69: 'expression\n' jpayne@69: '"s or \'foo\'" yields the desired value. Because "not" has to ' jpayne@69: 'create a\n' jpayne@69: 'new value, it returns a boolean value regardless of the type of ' jpayne@69: 'its\n' jpayne@69: 'argument (for example, "not \'foo\'" produces "False" rather ' jpayne@69: 'than "\'\'".)\n', jpayne@69: 'break': 'The "break" statement\n' jpayne@69: '*********************\n' jpayne@69: '\n' jpayne@69: ' break_stmt ::= "break"\n' jpayne@69: '\n' jpayne@69: '"break" may only occur syntactically nested in a "for" or "while"\n' jpayne@69: 'loop, but not nested in a function or class definition within that\n' jpayne@69: 'loop.\n' jpayne@69: '\n' jpayne@69: 'It terminates the nearest enclosing loop, skipping the optional ' jpayne@69: '"else"\n' jpayne@69: 'clause if the loop has one.\n' jpayne@69: '\n' jpayne@69: 'If a "for" loop is terminated by "break", the loop control target\n' jpayne@69: 'keeps its current value.\n' jpayne@69: '\n' jpayne@69: 'When "break" passes control out of a "try" statement with a ' jpayne@69: '"finally"\n' jpayne@69: 'clause, that "finally" clause is executed before really leaving ' jpayne@69: 'the\n' jpayne@69: 'loop.\n', jpayne@69: 'callable-types': 'Emulating callable objects\n' jpayne@69: '**************************\n' jpayne@69: '\n' jpayne@69: 'object.__call__(self[, args...])\n' jpayne@69: '\n' jpayne@69: ' Called when the instance is “called” as a function; if ' jpayne@69: 'this method\n' jpayne@69: ' is defined, "x(arg1, arg2, ...)" is a shorthand for\n' jpayne@69: ' "x.__call__(arg1, arg2, ...)".\n', jpayne@69: 'calls': 'Calls\n' jpayne@69: '*****\n' jpayne@69: '\n' jpayne@69: 'A call calls a callable object (e.g., a *function*) with a ' jpayne@69: 'possibly\n' jpayne@69: 'empty series of *arguments*:\n' jpayne@69: '\n' jpayne@69: ' call ::= primary "(" [argument_list [","] | ' jpayne@69: 'comprehension] ")"\n' jpayne@69: ' argument_list ::= positional_arguments ["," ' jpayne@69: 'starred_and_keywords]\n' jpayne@69: ' ["," keywords_arguments]\n' jpayne@69: ' | starred_and_keywords ["," ' jpayne@69: 'keywords_arguments]\n' jpayne@69: ' | keywords_arguments\n' jpayne@69: ' positional_arguments ::= ["*"] expression ("," ["*"] ' jpayne@69: 'expression)*\n' jpayne@69: ' starred_and_keywords ::= ("*" expression | keyword_item)\n' jpayne@69: ' ("," "*" expression | "," ' jpayne@69: 'keyword_item)*\n' jpayne@69: ' keywords_arguments ::= (keyword_item | "**" expression)\n' jpayne@69: ' ("," keyword_item | "," "**" ' jpayne@69: 'expression)*\n' jpayne@69: ' keyword_item ::= identifier "=" expression\n' jpayne@69: '\n' jpayne@69: 'An optional trailing comma may be present after the positional and\n' jpayne@69: 'keyword arguments but does not affect the semantics.\n' jpayne@69: '\n' jpayne@69: 'The primary must evaluate to a callable object (user-defined\n' jpayne@69: 'functions, built-in functions, methods of built-in objects, class\n' jpayne@69: 'objects, methods of class instances, and all objects having a\n' jpayne@69: '"__call__()" method are callable). All argument expressions are\n' jpayne@69: 'evaluated before the call is attempted. Please refer to section\n' jpayne@69: 'Function definitions for the syntax of formal *parameter* lists.\n' jpayne@69: '\n' jpayne@69: 'If keyword arguments are present, they are first converted to\n' jpayne@69: 'positional arguments, as follows. First, a list of unfilled slots ' jpayne@69: 'is\n' jpayne@69: 'created for the formal parameters. If there are N positional\n' jpayne@69: 'arguments, they are placed in the first N slots. Next, for each\n' jpayne@69: 'keyword argument, the identifier is used to determine the\n' jpayne@69: 'corresponding slot (if the identifier is the same as the first ' jpayne@69: 'formal\n' jpayne@69: 'parameter name, the first slot is used, and so on). If the slot ' jpayne@69: 'is\n' jpayne@69: 'already filled, a "TypeError" exception is raised. Otherwise, the\n' jpayne@69: 'value of the argument is placed in the slot, filling it (even if ' jpayne@69: 'the\n' jpayne@69: 'expression is "None", it fills the slot). When all arguments have\n' jpayne@69: 'been processed, the slots that are still unfilled are filled with ' jpayne@69: 'the\n' jpayne@69: 'corresponding default value from the function definition. ' jpayne@69: '(Default\n' jpayne@69: 'values are calculated, once, when the function is defined; thus, a\n' jpayne@69: 'mutable object such as a list or dictionary used as default value ' jpayne@69: 'will\n' jpayne@69: 'be shared by all calls that don’t specify an argument value for ' jpayne@69: 'the\n' jpayne@69: 'corresponding slot; this should usually be avoided.) If there are ' jpayne@69: 'any\n' jpayne@69: 'unfilled slots for which no default value is specified, a ' jpayne@69: '"TypeError"\n' jpayne@69: 'exception is raised. Otherwise, the list of filled slots is used ' jpayne@69: 'as\n' jpayne@69: 'the argument list for the call.\n' jpayne@69: '\n' jpayne@69: '**CPython implementation detail:** An implementation may provide\n' jpayne@69: 'built-in functions whose positional parameters do not have names, ' jpayne@69: 'even\n' jpayne@69: 'if they are ‘named’ for the purpose of documentation, and which\n' jpayne@69: 'therefore cannot be supplied by keyword. In CPython, this is the ' jpayne@69: 'case\n' jpayne@69: 'for functions implemented in C that use "PyArg_ParseTuple()" to ' jpayne@69: 'parse\n' jpayne@69: 'their arguments.\n' jpayne@69: '\n' jpayne@69: 'If there are more positional arguments than there are formal ' jpayne@69: 'parameter\n' jpayne@69: 'slots, a "TypeError" exception is raised, unless a formal ' jpayne@69: 'parameter\n' jpayne@69: 'using the syntax "*identifier" is present; in this case, that ' jpayne@69: 'formal\n' jpayne@69: 'parameter receives a tuple containing the excess positional ' jpayne@69: 'arguments\n' jpayne@69: '(or an empty tuple if there were no excess positional arguments).\n' jpayne@69: '\n' jpayne@69: 'If any keyword argument does not correspond to a formal parameter\n' jpayne@69: 'name, a "TypeError" exception is raised, unless a formal parameter\n' jpayne@69: 'using the syntax "**identifier" is present; in this case, that ' jpayne@69: 'formal\n' jpayne@69: 'parameter receives a dictionary containing the excess keyword\n' jpayne@69: 'arguments (using the keywords as keys and the argument values as\n' jpayne@69: 'corresponding values), or a (new) empty dictionary if there were ' jpayne@69: 'no\n' jpayne@69: 'excess keyword arguments.\n' jpayne@69: '\n' jpayne@69: 'If the syntax "*expression" appears in the function call, ' jpayne@69: '"expression"\n' jpayne@69: 'must evaluate to an *iterable*. Elements from these iterables are\n' jpayne@69: 'treated as if they were additional positional arguments. For the ' jpayne@69: 'call\n' jpayne@69: '"f(x1, x2, *y, x3, x4)", if *y* evaluates to a sequence *y1*, …, ' jpayne@69: '*yM*,\n' jpayne@69: 'this is equivalent to a call with M+4 positional arguments *x1*, ' jpayne@69: '*x2*,\n' jpayne@69: '*y1*, …, *yM*, *x3*, *x4*.\n' jpayne@69: '\n' jpayne@69: 'A consequence of this is that although the "*expression" syntax ' jpayne@69: 'may\n' jpayne@69: 'appear *after* explicit keyword arguments, it is processed ' jpayne@69: '*before*\n' jpayne@69: 'the keyword arguments (and any "**expression" arguments – see ' jpayne@69: 'below).\n' jpayne@69: 'So:\n' jpayne@69: '\n' jpayne@69: ' >>> def f(a, b):\n' jpayne@69: ' ... print(a, b)\n' jpayne@69: ' ...\n' jpayne@69: ' >>> f(b=1, *(2,))\n' jpayne@69: ' 2 1\n' jpayne@69: ' >>> f(a=1, *(2,))\n' jpayne@69: ' Traceback (most recent call last):\n' jpayne@69: ' File "", line 1, in \n' jpayne@69: " TypeError: f() got multiple values for keyword argument 'a'\n" jpayne@69: ' >>> f(1, *(2,))\n' jpayne@69: ' 1 2\n' jpayne@69: '\n' jpayne@69: 'It is unusual for both keyword arguments and the "*expression" ' jpayne@69: 'syntax\n' jpayne@69: 'to be used in the same call, so in practice this confusion does ' jpayne@69: 'not\n' jpayne@69: 'arise.\n' jpayne@69: '\n' jpayne@69: 'If the syntax "**expression" appears in the function call,\n' jpayne@69: '"expression" must evaluate to a *mapping*, the contents of which ' jpayne@69: 'are\n' jpayne@69: 'treated as additional keyword arguments. If a keyword is already\n' jpayne@69: 'present (as an explicit keyword argument, or from another ' jpayne@69: 'unpacking),\n' jpayne@69: 'a "TypeError" exception is raised.\n' jpayne@69: '\n' jpayne@69: 'Formal parameters using the syntax "*identifier" or "**identifier"\n' jpayne@69: 'cannot be used as positional argument slots or as keyword argument\n' jpayne@69: 'names.\n' jpayne@69: '\n' jpayne@69: 'Changed in version 3.5: Function calls accept any number of "*" ' jpayne@69: 'and\n' jpayne@69: '"**" unpackings, positional arguments may follow iterable ' jpayne@69: 'unpackings\n' jpayne@69: '("*"), and keyword arguments may follow dictionary unpackings ' jpayne@69: '("**").\n' jpayne@69: 'Originally proposed by **PEP 448**.\n' jpayne@69: '\n' jpayne@69: 'A call always returns some value, possibly "None", unless it raises ' jpayne@69: 'an\n' jpayne@69: 'exception. How this value is computed depends on the type of the\n' jpayne@69: 'callable object.\n' jpayne@69: '\n' jpayne@69: 'If it is—\n' jpayne@69: '\n' jpayne@69: 'a user-defined function:\n' jpayne@69: ' The code block for the function is executed, passing it the\n' jpayne@69: ' argument list. The first thing the code block will do is bind ' jpayne@69: 'the\n' jpayne@69: ' formal parameters to the arguments; this is described in ' jpayne@69: 'section\n' jpayne@69: ' Function definitions. When the code block executes a "return"\n' jpayne@69: ' statement, this specifies the return value of the function ' jpayne@69: 'call.\n' jpayne@69: '\n' jpayne@69: 'a built-in function or method:\n' jpayne@69: ' The result is up to the interpreter; see Built-in Functions for ' jpayne@69: 'the\n' jpayne@69: ' descriptions of built-in functions and methods.\n' jpayne@69: '\n' jpayne@69: 'a class object:\n' jpayne@69: ' A new instance of that class is returned.\n' jpayne@69: '\n' jpayne@69: 'a class instance method:\n' jpayne@69: ' The corresponding user-defined function is called, with an ' jpayne@69: 'argument\n' jpayne@69: ' list that is one longer than the argument list of the call: the\n' jpayne@69: ' instance becomes the first argument.\n' jpayne@69: '\n' jpayne@69: 'a class instance:\n' jpayne@69: ' The class must define a "__call__()" method; the effect is then ' jpayne@69: 'the\n' jpayne@69: ' same as if that method was called.\n', jpayne@69: 'class': 'Class definitions\n' jpayne@69: '*****************\n' jpayne@69: '\n' jpayne@69: 'A class definition defines a class object (see section The ' jpayne@69: 'standard\n' jpayne@69: 'type hierarchy):\n' jpayne@69: '\n' jpayne@69: ' classdef ::= [decorators] "class" classname [inheritance] ":" ' jpayne@69: 'suite\n' jpayne@69: ' inheritance ::= "(" [argument_list] ")"\n' jpayne@69: ' classname ::= identifier\n' jpayne@69: '\n' jpayne@69: 'A class definition is an executable statement. The inheritance ' jpayne@69: 'list\n' jpayne@69: 'usually gives a list of base classes (see Metaclasses for more\n' jpayne@69: 'advanced uses), so each item in the list should evaluate to a ' jpayne@69: 'class\n' jpayne@69: 'object which allows subclassing. Classes without an inheritance ' jpayne@69: 'list\n' jpayne@69: 'inherit, by default, from the base class "object"; hence,\n' jpayne@69: '\n' jpayne@69: ' class Foo:\n' jpayne@69: ' pass\n' jpayne@69: '\n' jpayne@69: 'is equivalent to\n' jpayne@69: '\n' jpayne@69: ' class Foo(object):\n' jpayne@69: ' pass\n' jpayne@69: '\n' jpayne@69: 'The class’s suite is then executed in a new execution frame (see\n' jpayne@69: 'Naming and binding), using a newly created local namespace and the\n' jpayne@69: 'original global namespace. (Usually, the suite contains mostly\n' jpayne@69: 'function definitions.) When the class’s suite finishes execution, ' jpayne@69: 'its\n' jpayne@69: 'execution frame is discarded but its local namespace is saved. [3] ' jpayne@69: 'A\n' jpayne@69: 'class object is then created using the inheritance list for the ' jpayne@69: 'base\n' jpayne@69: 'classes and the saved local namespace for the attribute ' jpayne@69: 'dictionary.\n' jpayne@69: 'The class name is bound to this class object in the original local\n' jpayne@69: 'namespace.\n' jpayne@69: '\n' jpayne@69: 'The order in which attributes are defined in the class body is\n' jpayne@69: 'preserved in the new class’s "__dict__". Note that this is ' jpayne@69: 'reliable\n' jpayne@69: 'only right after the class is created and only for classes that ' jpayne@69: 'were\n' jpayne@69: 'defined using the definition syntax.\n' jpayne@69: '\n' jpayne@69: 'Class creation can be customized heavily using metaclasses.\n' jpayne@69: '\n' jpayne@69: 'Classes can also be decorated: just like when decorating ' jpayne@69: 'functions,\n' jpayne@69: '\n' jpayne@69: ' @f1(arg)\n' jpayne@69: ' @f2\n' jpayne@69: ' class Foo: pass\n' jpayne@69: '\n' jpayne@69: 'is roughly equivalent to\n' jpayne@69: '\n' jpayne@69: ' class Foo: pass\n' jpayne@69: ' Foo = f1(arg)(f2(Foo))\n' jpayne@69: '\n' jpayne@69: 'The evaluation rules for the decorator expressions are the same as ' jpayne@69: 'for\n' jpayne@69: 'function decorators. The result is then bound to the class name.\n' jpayne@69: '\n' jpayne@69: '**Programmer’s note:** Variables defined in the class definition ' jpayne@69: 'are\n' jpayne@69: 'class attributes; they are shared by instances. Instance ' jpayne@69: 'attributes\n' jpayne@69: 'can be set in a method with "self.name = value". Both class and\n' jpayne@69: 'instance attributes are accessible through the notation ' jpayne@69: '“"self.name"”,\n' jpayne@69: 'and an instance attribute hides a class attribute with the same ' jpayne@69: 'name\n' jpayne@69: 'when accessed in this way. Class attributes can be used as ' jpayne@69: 'defaults\n' jpayne@69: 'for instance attributes, but using mutable values there can lead ' jpayne@69: 'to\n' jpayne@69: 'unexpected results. Descriptors can be used to create instance\n' jpayne@69: 'variables with different implementation details.\n' jpayne@69: '\n' jpayne@69: 'See also:\n' jpayne@69: '\n' jpayne@69: ' **PEP 3115** - Metaclasses in Python 3000\n' jpayne@69: ' The proposal that changed the declaration of metaclasses to ' jpayne@69: 'the\n' jpayne@69: ' current syntax, and the semantics for how classes with\n' jpayne@69: ' metaclasses are constructed.\n' jpayne@69: '\n' jpayne@69: ' **PEP 3129** - Class Decorators\n' jpayne@69: ' The proposal that added class decorators. Function and ' jpayne@69: 'method\n' jpayne@69: ' decorators were introduced in **PEP 318**.\n', jpayne@69: 'comparisons': 'Comparisons\n' jpayne@69: '***********\n' jpayne@69: '\n' jpayne@69: 'Unlike C, all comparison operations in Python have the same ' jpayne@69: 'priority,\n' jpayne@69: 'which is lower than that of any arithmetic, shifting or ' jpayne@69: 'bitwise\n' jpayne@69: 'operation. Also unlike C, expressions like "a < b < c" have ' jpayne@69: 'the\n' jpayne@69: 'interpretation that is conventional in mathematics:\n' jpayne@69: '\n' jpayne@69: ' comparison ::= or_expr (comp_operator or_expr)*\n' jpayne@69: ' comp_operator ::= "<" | ">" | "==" | ">=" | "<=" | "!="\n' jpayne@69: ' | "is" ["not"] | ["not"] "in"\n' jpayne@69: '\n' jpayne@69: 'Comparisons yield boolean values: "True" or "False".\n' jpayne@69: '\n' jpayne@69: 'Comparisons can be chained arbitrarily, e.g., "x < y <= z" ' jpayne@69: 'is\n' jpayne@69: 'equivalent to "x < y and y <= z", except that "y" is ' jpayne@69: 'evaluated only\n' jpayne@69: 'once (but in both cases "z" is not evaluated at all when "x < ' jpayne@69: 'y" is\n' jpayne@69: 'found to be false).\n' jpayne@69: '\n' jpayne@69: 'Formally, if *a*, *b*, *c*, …, *y*, *z* are expressions and ' jpayne@69: '*op1*,\n' jpayne@69: '*op2*, …, *opN* are comparison operators, then "a op1 b op2 c ' jpayne@69: '... y\n' jpayne@69: 'opN z" is equivalent to "a op1 b and b op2 c and ... y opN ' jpayne@69: 'z", except\n' jpayne@69: 'that each expression is evaluated at most once.\n' jpayne@69: '\n' jpayne@69: 'Note that "a op1 b op2 c" doesn’t imply any kind of ' jpayne@69: 'comparison between\n' jpayne@69: '*a* and *c*, so that, e.g., "x < y > z" is perfectly legal ' jpayne@69: '(though\n' jpayne@69: 'perhaps not pretty).\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Value comparisons\n' jpayne@69: '=================\n' jpayne@69: '\n' jpayne@69: 'The operators "<", ">", "==", ">=", "<=", and "!=" compare ' jpayne@69: 'the values\n' jpayne@69: 'of two objects. The objects do not need to have the same ' jpayne@69: 'type.\n' jpayne@69: '\n' jpayne@69: 'Chapter Objects, values and types states that objects have a ' jpayne@69: 'value (in\n' jpayne@69: 'addition to type and identity). The value of an object is a ' jpayne@69: 'rather\n' jpayne@69: 'abstract notion in Python: For example, there is no canonical ' jpayne@69: 'access\n' jpayne@69: 'method for an object’s value. Also, there is no requirement ' jpayne@69: 'that the\n' jpayne@69: 'value of an object should be constructed in a particular way, ' jpayne@69: 'e.g.\n' jpayne@69: 'comprised of all its data attributes. Comparison operators ' jpayne@69: 'implement a\n' jpayne@69: 'particular notion of what the value of an object is. One can ' jpayne@69: 'think of\n' jpayne@69: 'them as defining the value of an object indirectly, by means ' jpayne@69: 'of their\n' jpayne@69: 'comparison implementation.\n' jpayne@69: '\n' jpayne@69: 'Because all types are (direct or indirect) subtypes of ' jpayne@69: '"object", they\n' jpayne@69: 'inherit the default comparison behavior from "object". Types ' jpayne@69: 'can\n' jpayne@69: 'customize their comparison behavior by implementing *rich ' jpayne@69: 'comparison\n' jpayne@69: 'methods* like "__lt__()", described in Basic customization.\n' jpayne@69: '\n' jpayne@69: 'The default behavior for equality comparison ("==" and "!=") ' jpayne@69: 'is based\n' jpayne@69: 'on the identity of the objects. Hence, equality comparison ' jpayne@69: 'of\n' jpayne@69: 'instances with the same identity results in equality, and ' jpayne@69: 'equality\n' jpayne@69: 'comparison of instances with different identities results in\n' jpayne@69: 'inequality. A motivation for this default behavior is the ' jpayne@69: 'desire that\n' jpayne@69: 'all objects should be reflexive (i.e. "x is y" implies "x == ' jpayne@69: 'y").\n' jpayne@69: '\n' jpayne@69: 'A default order comparison ("<", ">", "<=", and ">=") is not ' jpayne@69: 'provided;\n' jpayne@69: 'an attempt raises "TypeError". A motivation for this default ' jpayne@69: 'behavior\n' jpayne@69: 'is the lack of a similar invariant as for equality.\n' jpayne@69: '\n' jpayne@69: 'The behavior of the default equality comparison, that ' jpayne@69: 'instances with\n' jpayne@69: 'different identities are always unequal, may be in contrast ' jpayne@69: 'to what\n' jpayne@69: 'types will need that have a sensible definition of object ' jpayne@69: 'value and\n' jpayne@69: 'value-based equality. Such types will need to customize ' jpayne@69: 'their\n' jpayne@69: 'comparison behavior, and in fact, a number of built-in types ' jpayne@69: 'have done\n' jpayne@69: 'that.\n' jpayne@69: '\n' jpayne@69: 'The following list describes the comparison behavior of the ' jpayne@69: 'most\n' jpayne@69: 'important built-in types.\n' jpayne@69: '\n' jpayne@69: '* Numbers of built-in numeric types (Numeric Types — int, ' jpayne@69: 'float,\n' jpayne@69: ' complex) and of the standard library types ' jpayne@69: '"fractions.Fraction" and\n' jpayne@69: ' "decimal.Decimal" can be compared within and across their ' jpayne@69: 'types,\n' jpayne@69: ' with the restriction that complex numbers do not support ' jpayne@69: 'order\n' jpayne@69: ' comparison. Within the limits of the types involved, they ' jpayne@69: 'compare\n' jpayne@69: ' mathematically (algorithmically) correct without loss of ' jpayne@69: 'precision.\n' jpayne@69: '\n' jpayne@69: ' The not-a-number values "float(\'NaN\')" and ' jpayne@69: '"decimal.Decimal(\'NaN\')"\n' jpayne@69: ' are special. Any ordered comparison of a number to a ' jpayne@69: 'not-a-number\n' jpayne@69: ' value is false. A counter-intuitive implication is that ' jpayne@69: 'not-a-number\n' jpayne@69: ' values are not equal to themselves. For example, if "x =\n' jpayne@69: ' float(\'NaN\')", "3 < x", "x < 3", "x == x", "x != x" are ' jpayne@69: 'all false.\n' jpayne@69: ' This behavior is compliant with IEEE 754.\n' jpayne@69: '\n' jpayne@69: '* "None" and "NotImplemented" are singletons. **PEP 8** ' jpayne@69: 'advises\n' jpayne@69: ' that comparisons for singletons should always be done with ' jpayne@69: '"is" or\n' jpayne@69: ' "is not", never the equality operators.\n' jpayne@69: '\n' jpayne@69: '* Binary sequences (instances of "bytes" or "bytearray") can ' jpayne@69: 'be\n' jpayne@69: ' compared within and across their types. They compare\n' jpayne@69: ' lexicographically using the numeric values of their ' jpayne@69: 'elements.\n' jpayne@69: '\n' jpayne@69: '* Strings (instances of "str") compare lexicographically ' jpayne@69: 'using the\n' jpayne@69: ' numerical Unicode code points (the result of the built-in ' jpayne@69: 'function\n' jpayne@69: ' "ord()") of their characters. [3]\n' jpayne@69: '\n' jpayne@69: ' Strings and binary sequences cannot be directly compared.\n' jpayne@69: '\n' jpayne@69: '* Sequences (instances of "tuple", "list", or "range") can ' jpayne@69: 'be\n' jpayne@69: ' compared only within each of their types, with the ' jpayne@69: 'restriction that\n' jpayne@69: ' ranges do not support order comparison. Equality ' jpayne@69: 'comparison across\n' jpayne@69: ' these types results in inequality, and ordering comparison ' jpayne@69: 'across\n' jpayne@69: ' these types raises "TypeError".\n' jpayne@69: '\n' jpayne@69: ' Sequences compare lexicographically using comparison of\n' jpayne@69: ' corresponding elements. The built-in containers typically ' jpayne@69: 'assume\n' jpayne@69: ' identical objects are equal to themselves. That lets them ' jpayne@69: 'bypass\n' jpayne@69: ' equality tests for identical objects to improve performance ' jpayne@69: 'and to\n' jpayne@69: ' maintain their internal invariants.\n' jpayne@69: '\n' jpayne@69: ' Lexicographical comparison between built-in collections ' jpayne@69: 'works as\n' jpayne@69: ' follows:\n' jpayne@69: '\n' jpayne@69: ' * For two collections to compare equal, they must be of the ' jpayne@69: 'same\n' jpayne@69: ' type, have the same length, and each pair of ' jpayne@69: 'corresponding\n' jpayne@69: ' elements must compare equal (for example, "[1,2] == ' jpayne@69: '(1,2)" is\n' jpayne@69: ' false because the type is not the same).\n' jpayne@69: '\n' jpayne@69: ' * Collections that support order comparison are ordered the ' jpayne@69: 'same\n' jpayne@69: ' as their first unequal elements (for example, "[1,2,x] <= ' jpayne@69: '[1,2,y]"\n' jpayne@69: ' has the same value as "x <= y"). If a corresponding ' jpayne@69: 'element does\n' jpayne@69: ' not exist, the shorter collection is ordered first (for ' jpayne@69: 'example,\n' jpayne@69: ' "[1,2] < [1,2,3]" is true).\n' jpayne@69: '\n' jpayne@69: '* Mappings (instances of "dict") compare equal if and only if ' jpayne@69: 'they\n' jpayne@69: ' have equal *(key, value)* pairs. Equality comparison of the ' jpayne@69: 'keys and\n' jpayne@69: ' values enforces reflexivity.\n' jpayne@69: '\n' jpayne@69: ' Order comparisons ("<", ">", "<=", and ">=") raise ' jpayne@69: '"TypeError".\n' jpayne@69: '\n' jpayne@69: '* Sets (instances of "set" or "frozenset") can be compared ' jpayne@69: 'within\n' jpayne@69: ' and across their types.\n' jpayne@69: '\n' jpayne@69: ' They define order comparison operators to mean subset and ' jpayne@69: 'superset\n' jpayne@69: ' tests. Those relations do not define total orderings (for ' jpayne@69: 'example,\n' jpayne@69: ' the two sets "{1,2}" and "{2,3}" are not equal, nor subsets ' jpayne@69: 'of one\n' jpayne@69: ' another, nor supersets of one another). Accordingly, sets ' jpayne@69: 'are not\n' jpayne@69: ' appropriate arguments for functions which depend on total ' jpayne@69: 'ordering\n' jpayne@69: ' (for example, "min()", "max()", and "sorted()" produce ' jpayne@69: 'undefined\n' jpayne@69: ' results given a list of sets as inputs).\n' jpayne@69: '\n' jpayne@69: ' Comparison of sets enforces reflexivity of its elements.\n' jpayne@69: '\n' jpayne@69: '* Most other built-in types have no comparison methods ' jpayne@69: 'implemented,\n' jpayne@69: ' so they inherit the default comparison behavior.\n' jpayne@69: '\n' jpayne@69: 'User-defined classes that customize their comparison behavior ' jpayne@69: 'should\n' jpayne@69: 'follow some consistency rules, if possible:\n' jpayne@69: '\n' jpayne@69: '* Equality comparison should be reflexive. In other words, ' jpayne@69: 'identical\n' jpayne@69: ' objects should compare equal:\n' jpayne@69: '\n' jpayne@69: ' "x is y" implies "x == y"\n' jpayne@69: '\n' jpayne@69: '* Comparison should be symmetric. In other words, the ' jpayne@69: 'following\n' jpayne@69: ' expressions should have the same result:\n' jpayne@69: '\n' jpayne@69: ' "x == y" and "y == x"\n' jpayne@69: '\n' jpayne@69: ' "x != y" and "y != x"\n' jpayne@69: '\n' jpayne@69: ' "x < y" and "y > x"\n' jpayne@69: '\n' jpayne@69: ' "x <= y" and "y >= x"\n' jpayne@69: '\n' jpayne@69: '* Comparison should be transitive. The following ' jpayne@69: '(non-exhaustive)\n' jpayne@69: ' examples illustrate that:\n' jpayne@69: '\n' jpayne@69: ' "x > y and y > z" implies "x > z"\n' jpayne@69: '\n' jpayne@69: ' "x < y and y <= z" implies "x < z"\n' jpayne@69: '\n' jpayne@69: '* Inverse comparison should result in the boolean negation. ' jpayne@69: 'In other\n' jpayne@69: ' words, the following expressions should have the same ' jpayne@69: 'result:\n' jpayne@69: '\n' jpayne@69: ' "x == y" and "not x != y"\n' jpayne@69: '\n' jpayne@69: ' "x < y" and "not x >= y" (for total ordering)\n' jpayne@69: '\n' jpayne@69: ' "x > y" and "not x <= y" (for total ordering)\n' jpayne@69: '\n' jpayne@69: ' The last two expressions apply to totally ordered ' jpayne@69: 'collections (e.g.\n' jpayne@69: ' to sequences, but not to sets or mappings). See also the\n' jpayne@69: ' "total_ordering()" decorator.\n' jpayne@69: '\n' jpayne@69: '* The "hash()" result should be consistent with equality. ' jpayne@69: 'Objects\n' jpayne@69: ' that are equal should either have the same hash value, or ' jpayne@69: 'be marked\n' jpayne@69: ' as unhashable.\n' jpayne@69: '\n' jpayne@69: 'Python does not enforce these consistency rules. In fact, ' jpayne@69: 'the\n' jpayne@69: 'not-a-number values are an example for not following these ' jpayne@69: 'rules.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Membership test operations\n' jpayne@69: '==========================\n' jpayne@69: '\n' jpayne@69: 'The operators "in" and "not in" test for membership. "x in ' jpayne@69: 's"\n' jpayne@69: 'evaluates to "True" if *x* is a member of *s*, and "False" ' jpayne@69: 'otherwise.\n' jpayne@69: '"x not in s" returns the negation of "x in s". All built-in ' jpayne@69: 'sequences\n' jpayne@69: 'and set types support this as well as dictionary, for which ' jpayne@69: '"in" tests\n' jpayne@69: 'whether the dictionary has a given key. For container types ' jpayne@69: 'such as\n' jpayne@69: 'list, tuple, set, frozenset, dict, or collections.deque, the\n' jpayne@69: 'expression "x in y" is equivalent to "any(x is e or x == e ' jpayne@69: 'for e in\n' jpayne@69: 'y)".\n' jpayne@69: '\n' jpayne@69: 'For the string and bytes types, "x in y" is "True" if and ' jpayne@69: 'only if *x*\n' jpayne@69: 'is a substring of *y*. An equivalent test is "y.find(x) != ' jpayne@69: '-1".\n' jpayne@69: 'Empty strings are always considered to be a substring of any ' jpayne@69: 'other\n' jpayne@69: 'string, so """ in "abc"" will return "True".\n' jpayne@69: '\n' jpayne@69: 'For user-defined classes which define the "__contains__()" ' jpayne@69: 'method, "x\n' jpayne@69: 'in y" returns "True" if "y.__contains__(x)" returns a true ' jpayne@69: 'value, and\n' jpayne@69: '"False" otherwise.\n' jpayne@69: '\n' jpayne@69: 'For user-defined classes which do not define "__contains__()" ' jpayne@69: 'but do\n' jpayne@69: 'define "__iter__()", "x in y" is "True" if some value "z", ' jpayne@69: 'for which\n' jpayne@69: 'the expression "x is z or x == z" is true, is produced while ' jpayne@69: 'iterating\n' jpayne@69: 'over "y". If an exception is raised during the iteration, it ' jpayne@69: 'is as if\n' jpayne@69: '"in" raised that exception.\n' jpayne@69: '\n' jpayne@69: 'Lastly, the old-style iteration protocol is tried: if a class ' jpayne@69: 'defines\n' jpayne@69: '"__getitem__()", "x in y" is "True" if and only if there is a ' jpayne@69: 'non-\n' jpayne@69: 'negative integer index *i* such that "x is y[i] or x == ' jpayne@69: 'y[i]", and no\n' jpayne@69: 'lower integer index raises the "IndexError" exception. (If ' jpayne@69: 'any other\n' jpayne@69: 'exception is raised, it is as if "in" raised that ' jpayne@69: 'exception).\n' jpayne@69: '\n' jpayne@69: 'The operator "not in" is defined to have the inverse truth ' jpayne@69: 'value of\n' jpayne@69: '"in".\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Identity comparisons\n' jpayne@69: '====================\n' jpayne@69: '\n' jpayne@69: 'The operators "is" and "is not" test for an object’s ' jpayne@69: 'identity: "x is\n' jpayne@69: 'y" is true if and only if *x* and *y* are the same object. ' jpayne@69: 'An\n' jpayne@69: 'Object’s identity is determined using the "id()" function. ' jpayne@69: '"x is not\n' jpayne@69: 'y" yields the inverse truth value. [4]\n', jpayne@69: 'compound': 'Compound statements\n' jpayne@69: '*******************\n' jpayne@69: '\n' jpayne@69: 'Compound statements contain (groups of) other statements; they ' jpayne@69: 'affect\n' jpayne@69: 'or control the execution of those other statements in some way. ' jpayne@69: 'In\n' jpayne@69: 'general, compound statements span multiple lines, although in ' jpayne@69: 'simple\n' jpayne@69: 'incarnations a whole compound statement may be contained in one ' jpayne@69: 'line.\n' jpayne@69: '\n' jpayne@69: 'The "if", "while" and "for" statements implement traditional ' jpayne@69: 'control\n' jpayne@69: 'flow constructs. "try" specifies exception handlers and/or ' jpayne@69: 'cleanup\n' jpayne@69: 'code for a group of statements, while the "with" statement ' jpayne@69: 'allows the\n' jpayne@69: 'execution of initialization and finalization code around a block ' jpayne@69: 'of\n' jpayne@69: 'code. Function and class definitions are also syntactically ' jpayne@69: 'compound\n' jpayne@69: 'statements.\n' jpayne@69: '\n' jpayne@69: 'A compound statement consists of one or more ‘clauses.’ A ' jpayne@69: 'clause\n' jpayne@69: 'consists of a header and a ‘suite.’ The clause headers of a\n' jpayne@69: 'particular compound statement are all at the same indentation ' jpayne@69: 'level.\n' jpayne@69: 'Each clause header begins with a uniquely identifying keyword ' jpayne@69: 'and ends\n' jpayne@69: 'with a colon. A suite is a group of statements controlled by a\n' jpayne@69: 'clause. A suite can be one or more semicolon-separated simple\n' jpayne@69: 'statements on the same line as the header, following the ' jpayne@69: 'header’s\n' jpayne@69: 'colon, or it can be one or more indented statements on ' jpayne@69: 'subsequent\n' jpayne@69: 'lines. Only the latter form of a suite can contain nested ' jpayne@69: 'compound\n' jpayne@69: 'statements; the following is illegal, mostly because it wouldn’t ' jpayne@69: 'be\n' jpayne@69: 'clear to which "if" clause a following "else" clause would ' jpayne@69: 'belong:\n' jpayne@69: '\n' jpayne@69: ' if test1: if test2: print(x)\n' jpayne@69: '\n' jpayne@69: 'Also note that the semicolon binds tighter than the colon in ' jpayne@69: 'this\n' jpayne@69: 'context, so that in the following example, either all or none of ' jpayne@69: 'the\n' jpayne@69: '"print()" calls are executed:\n' jpayne@69: '\n' jpayne@69: ' if x < y < z: print(x); print(y); print(z)\n' jpayne@69: '\n' jpayne@69: 'Summarizing:\n' jpayne@69: '\n' jpayne@69: ' compound_stmt ::= if_stmt\n' jpayne@69: ' | while_stmt\n' jpayne@69: ' | for_stmt\n' jpayne@69: ' | try_stmt\n' jpayne@69: ' | with_stmt\n' jpayne@69: ' | funcdef\n' jpayne@69: ' | classdef\n' jpayne@69: ' | async_with_stmt\n' jpayne@69: ' | async_for_stmt\n' jpayne@69: ' | async_funcdef\n' jpayne@69: ' suite ::= stmt_list NEWLINE | NEWLINE INDENT ' jpayne@69: 'statement+ DEDENT\n' jpayne@69: ' statement ::= stmt_list NEWLINE | compound_stmt\n' jpayne@69: ' stmt_list ::= simple_stmt (";" simple_stmt)* [";"]\n' jpayne@69: '\n' jpayne@69: 'Note that statements always end in a "NEWLINE" possibly followed ' jpayne@69: 'by a\n' jpayne@69: '"DEDENT". Also note that optional continuation clauses always ' jpayne@69: 'begin\n' jpayne@69: 'with a keyword that cannot start a statement, thus there are no\n' jpayne@69: 'ambiguities (the ‘dangling "else"’ problem is solved in Python ' jpayne@69: 'by\n' jpayne@69: 'requiring nested "if" statements to be indented).\n' jpayne@69: '\n' jpayne@69: 'The formatting of the grammar rules in the following sections ' jpayne@69: 'places\n' jpayne@69: 'each clause on a separate line for clarity.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'The "if" statement\n' jpayne@69: '==================\n' jpayne@69: '\n' jpayne@69: 'The "if" statement is used for conditional execution:\n' jpayne@69: '\n' jpayne@69: ' if_stmt ::= "if" expression ":" suite\n' jpayne@69: ' ("elif" expression ":" suite)*\n' jpayne@69: ' ["else" ":" suite]\n' jpayne@69: '\n' jpayne@69: 'It selects exactly one of the suites by evaluating the ' jpayne@69: 'expressions one\n' jpayne@69: 'by one until one is found to be true (see section Boolean ' jpayne@69: 'operations\n' jpayne@69: 'for the definition of true and false); then that suite is ' jpayne@69: 'executed\n' jpayne@69: '(and no other part of the "if" statement is executed or ' jpayne@69: 'evaluated).\n' jpayne@69: 'If all expressions are false, the suite of the "else" clause, ' jpayne@69: 'if\n' jpayne@69: 'present, is executed.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'The "while" statement\n' jpayne@69: '=====================\n' jpayne@69: '\n' jpayne@69: 'The "while" statement is used for repeated execution as long as ' jpayne@69: 'an\n' jpayne@69: 'expression is true:\n' jpayne@69: '\n' jpayne@69: ' while_stmt ::= "while" expression ":" suite\n' jpayne@69: ' ["else" ":" suite]\n' jpayne@69: '\n' jpayne@69: 'This repeatedly tests the expression and, if it is true, ' jpayne@69: 'executes the\n' jpayne@69: 'first suite; if the expression is false (which may be the first ' jpayne@69: 'time\n' jpayne@69: 'it is tested) the suite of the "else" clause, if present, is ' jpayne@69: 'executed\n' jpayne@69: 'and the loop terminates.\n' jpayne@69: '\n' jpayne@69: 'A "break" statement executed in the first suite terminates the ' jpayne@69: 'loop\n' jpayne@69: 'without executing the "else" clause’s suite. A "continue" ' jpayne@69: 'statement\n' jpayne@69: 'executed in the first suite skips the rest of the suite and goes ' jpayne@69: 'back\n' jpayne@69: 'to testing the expression.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'The "for" statement\n' jpayne@69: '===================\n' jpayne@69: '\n' jpayne@69: 'The "for" statement is used to iterate over the elements of a ' jpayne@69: 'sequence\n' jpayne@69: '(such as a string, tuple or list) or other iterable object:\n' jpayne@69: '\n' jpayne@69: ' for_stmt ::= "for" target_list "in" expression_list ":" ' jpayne@69: 'suite\n' jpayne@69: ' ["else" ":" suite]\n' jpayne@69: '\n' jpayne@69: 'The expression list is evaluated once; it should yield an ' jpayne@69: 'iterable\n' jpayne@69: 'object. An iterator is created for the result of the\n' jpayne@69: '"expression_list". The suite is then executed once for each ' jpayne@69: 'item\n' jpayne@69: 'provided by the iterator, in the order returned by the ' jpayne@69: 'iterator. Each\n' jpayne@69: 'item in turn is assigned to the target list using the standard ' jpayne@69: 'rules\n' jpayne@69: 'for assignments (see Assignment statements), and then the suite ' jpayne@69: 'is\n' jpayne@69: 'executed. When the items are exhausted (which is immediately ' jpayne@69: 'when the\n' jpayne@69: 'sequence is empty or an iterator raises a "StopIteration" ' jpayne@69: 'exception),\n' jpayne@69: 'the suite in the "else" clause, if present, is executed, and the ' jpayne@69: 'loop\n' jpayne@69: 'terminates.\n' jpayne@69: '\n' jpayne@69: 'A "break" statement executed in the first suite terminates the ' jpayne@69: 'loop\n' jpayne@69: 'without executing the "else" clause’s suite. A "continue" ' jpayne@69: 'statement\n' jpayne@69: 'executed in the first suite skips the rest of the suite and ' jpayne@69: 'continues\n' jpayne@69: 'with the next item, or with the "else" clause if there is no ' jpayne@69: 'next\n' jpayne@69: 'item.\n' jpayne@69: '\n' jpayne@69: 'The for-loop makes assignments to the variables in the target ' jpayne@69: 'list.\n' jpayne@69: 'This overwrites all previous assignments to those variables ' jpayne@69: 'including\n' jpayne@69: 'those made in the suite of the for-loop:\n' jpayne@69: '\n' jpayne@69: ' for i in range(10):\n' jpayne@69: ' print(i)\n' jpayne@69: ' i = 5 # this will not affect the for-loop\n' jpayne@69: ' # because i will be overwritten with ' jpayne@69: 'the next\n' jpayne@69: ' # index in the range\n' jpayne@69: '\n' jpayne@69: 'Names in the target list are not deleted when the loop is ' jpayne@69: 'finished,\n' jpayne@69: 'but if the sequence is empty, they will not have been assigned ' jpayne@69: 'to at\n' jpayne@69: 'all by the loop. Hint: the built-in function "range()" returns ' jpayne@69: 'an\n' jpayne@69: 'iterator of integers suitable to emulate the effect of Pascal’s ' jpayne@69: '"for i\n' jpayne@69: ':= a to b do"; e.g., "list(range(3))" returns the list "[0, 1, ' jpayne@69: '2]".\n' jpayne@69: '\n' jpayne@69: 'Note: There is a subtlety when the sequence is being modified by ' jpayne@69: 'the\n' jpayne@69: ' loop (this can only occur for mutable sequences, e.g. lists). ' jpayne@69: 'An\n' jpayne@69: ' internal counter is used to keep track of which item is used ' jpayne@69: 'next,\n' jpayne@69: ' and this is incremented on each iteration. When this counter ' jpayne@69: 'has\n' jpayne@69: ' reached the length of the sequence the loop terminates. This ' jpayne@69: 'means\n' jpayne@69: ' that if the suite deletes the current (or a previous) item ' jpayne@69: 'from the\n' jpayne@69: ' sequence, the next item will be skipped (since it gets the ' jpayne@69: 'index of\n' jpayne@69: ' the current item which has already been treated). Likewise, ' jpayne@69: 'if the\n' jpayne@69: ' suite inserts an item in the sequence before the current item, ' jpayne@69: 'the\n' jpayne@69: ' current item will be treated again the next time through the ' jpayne@69: 'loop.\n' jpayne@69: ' This can lead to nasty bugs that can be avoided by making a\n' jpayne@69: ' temporary copy using a slice of the whole sequence, e.g.,\n' jpayne@69: '\n' jpayne@69: ' for x in a[:]:\n' jpayne@69: ' if x < 0: a.remove(x)\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'The "try" statement\n' jpayne@69: '===================\n' jpayne@69: '\n' jpayne@69: 'The "try" statement specifies exception handlers and/or cleanup ' jpayne@69: 'code\n' jpayne@69: 'for a group of statements:\n' jpayne@69: '\n' jpayne@69: ' try_stmt ::= try1_stmt | try2_stmt\n' jpayne@69: ' try1_stmt ::= "try" ":" suite\n' jpayne@69: ' ("except" [expression ["as" identifier]] ":" ' jpayne@69: 'suite)+\n' jpayne@69: ' ["else" ":" suite]\n' jpayne@69: ' ["finally" ":" suite]\n' jpayne@69: ' try2_stmt ::= "try" ":" suite\n' jpayne@69: ' "finally" ":" suite\n' jpayne@69: '\n' jpayne@69: 'The "except" clause(s) specify one or more exception handlers. ' jpayne@69: 'When no\n' jpayne@69: 'exception occurs in the "try" clause, no exception handler is\n' jpayne@69: 'executed. When an exception occurs in the "try" suite, a search ' jpayne@69: 'for an\n' jpayne@69: 'exception handler is started. This search inspects the except ' jpayne@69: 'clauses\n' jpayne@69: 'in turn until one is found that matches the exception. An ' jpayne@69: 'expression-\n' jpayne@69: 'less except clause, if present, must be last; it matches any\n' jpayne@69: 'exception. For an except clause with an expression, that ' jpayne@69: 'expression\n' jpayne@69: 'is evaluated, and the clause matches the exception if the ' jpayne@69: 'resulting\n' jpayne@69: 'object is “compatible” with the exception. An object is ' jpayne@69: 'compatible\n' jpayne@69: 'with an exception if it is the class or a base class of the ' jpayne@69: 'exception\n' jpayne@69: 'object or a tuple containing an item compatible with the ' jpayne@69: 'exception.\n' jpayne@69: '\n' jpayne@69: 'If no except clause matches the exception, the search for an ' jpayne@69: 'exception\n' jpayne@69: 'handler continues in the surrounding code and on the invocation ' jpayne@69: 'stack.\n' jpayne@69: '[1]\n' jpayne@69: '\n' jpayne@69: 'If the evaluation of an expression in the header of an except ' jpayne@69: 'clause\n' jpayne@69: 'raises an exception, the original search for a handler is ' jpayne@69: 'canceled and\n' jpayne@69: 'a search starts for the new exception in the surrounding code ' jpayne@69: 'and on\n' jpayne@69: 'the call stack (it is treated as if the entire "try" statement ' jpayne@69: 'raised\n' jpayne@69: 'the exception).\n' jpayne@69: '\n' jpayne@69: 'When a matching except clause is found, the exception is ' jpayne@69: 'assigned to\n' jpayne@69: 'the target specified after the "as" keyword in that except ' jpayne@69: 'clause, if\n' jpayne@69: 'present, and the except clause’s suite is executed. All except\n' jpayne@69: 'clauses must have an executable block. When the end of this ' jpayne@69: 'block is\n' jpayne@69: 'reached, execution continues normally after the entire try ' jpayne@69: 'statement.\n' jpayne@69: '(This means that if two nested handlers exist for the same ' jpayne@69: 'exception,\n' jpayne@69: 'and the exception occurs in the try clause of the inner handler, ' jpayne@69: 'the\n' jpayne@69: 'outer handler will not handle the exception.)\n' jpayne@69: '\n' jpayne@69: 'When an exception has been assigned using "as target", it is ' jpayne@69: 'cleared\n' jpayne@69: 'at the end of the except clause. This is as if\n' jpayne@69: '\n' jpayne@69: ' except E as N:\n' jpayne@69: ' foo\n' jpayne@69: '\n' jpayne@69: 'was translated to\n' jpayne@69: '\n' jpayne@69: ' except E as N:\n' jpayne@69: ' try:\n' jpayne@69: ' foo\n' jpayne@69: ' finally:\n' jpayne@69: ' del N\n' jpayne@69: '\n' jpayne@69: 'This means the exception must be assigned to a different name to ' jpayne@69: 'be\n' jpayne@69: 'able to refer to it after the except clause. Exceptions are ' jpayne@69: 'cleared\n' jpayne@69: 'because with the traceback attached to them, they form a ' jpayne@69: 'reference\n' jpayne@69: 'cycle with the stack frame, keeping all locals in that frame ' jpayne@69: 'alive\n' jpayne@69: 'until the next garbage collection occurs.\n' jpayne@69: '\n' jpayne@69: 'Before an except clause’s suite is executed, details about the\n' jpayne@69: 'exception are stored in the "sys" module and can be accessed ' jpayne@69: 'via\n' jpayne@69: '"sys.exc_info()". "sys.exc_info()" returns a 3-tuple consisting ' jpayne@69: 'of the\n' jpayne@69: 'exception class, the exception instance and a traceback object ' jpayne@69: '(see\n' jpayne@69: 'section The standard type hierarchy) identifying the point in ' jpayne@69: 'the\n' jpayne@69: 'program where the exception occurred. "sys.exc_info()" values ' jpayne@69: 'are\n' jpayne@69: 'restored to their previous values (before the call) when ' jpayne@69: 'returning\n' jpayne@69: 'from a function that handled an exception.\n' jpayne@69: '\n' jpayne@69: 'The optional "else" clause is executed if the control flow ' jpayne@69: 'leaves the\n' jpayne@69: '"try" suite, no exception was raised, and no "return", ' jpayne@69: '"continue", or\n' jpayne@69: '"break" statement was executed. Exceptions in the "else" clause ' jpayne@69: 'are\n' jpayne@69: 'not handled by the preceding "except" clauses.\n' jpayne@69: '\n' jpayne@69: 'If "finally" is present, it specifies a ‘cleanup’ handler. The ' jpayne@69: '"try"\n' jpayne@69: 'clause is executed, including any "except" and "else" clauses. ' jpayne@69: 'If an\n' jpayne@69: 'exception occurs in any of the clauses and is not handled, the\n' jpayne@69: 'exception is temporarily saved. The "finally" clause is ' jpayne@69: 'executed. If\n' jpayne@69: 'there is a saved exception it is re-raised at the end of the ' jpayne@69: '"finally"\n' jpayne@69: 'clause. If the "finally" clause raises another exception, the ' jpayne@69: 'saved\n' jpayne@69: 'exception is set as the context of the new exception. If the ' jpayne@69: '"finally"\n' jpayne@69: 'clause executes a "return", "break" or "continue" statement, the ' jpayne@69: 'saved\n' jpayne@69: 'exception is discarded:\n' jpayne@69: '\n' jpayne@69: ' >>> def f():\n' jpayne@69: ' ... try:\n' jpayne@69: ' ... 1/0\n' jpayne@69: ' ... finally:\n' jpayne@69: ' ... return 42\n' jpayne@69: ' ...\n' jpayne@69: ' >>> f()\n' jpayne@69: ' 42\n' jpayne@69: '\n' jpayne@69: 'The exception information is not available to the program ' jpayne@69: 'during\n' jpayne@69: 'execution of the "finally" clause.\n' jpayne@69: '\n' jpayne@69: 'When a "return", "break" or "continue" statement is executed in ' jpayne@69: 'the\n' jpayne@69: '"try" suite of a "try"…"finally" statement, the "finally" clause ' jpayne@69: 'is\n' jpayne@69: 'also executed ‘on the way out.’\n' jpayne@69: '\n' jpayne@69: 'The return value of a function is determined by the last ' jpayne@69: '"return"\n' jpayne@69: 'statement executed. Since the "finally" clause always executes, ' jpayne@69: 'a\n' jpayne@69: '"return" statement executed in the "finally" clause will always ' jpayne@69: 'be the\n' jpayne@69: 'last one executed:\n' jpayne@69: '\n' jpayne@69: ' >>> def foo():\n' jpayne@69: ' ... try:\n' jpayne@69: " ... return 'try'\n" jpayne@69: ' ... finally:\n' jpayne@69: " ... return 'finally'\n" jpayne@69: ' ...\n' jpayne@69: ' >>> foo()\n' jpayne@69: " 'finally'\n" jpayne@69: '\n' jpayne@69: 'Additional information on exceptions can be found in section\n' jpayne@69: 'Exceptions, and information on using the "raise" statement to ' jpayne@69: 'generate\n' jpayne@69: 'exceptions may be found in section The raise statement.\n' jpayne@69: '\n' jpayne@69: 'Changed in version 3.8: Prior to Python 3.8, a "continue" ' jpayne@69: 'statement\n' jpayne@69: 'was illegal in the "finally" clause due to a problem with the\n' jpayne@69: 'implementation.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'The "with" statement\n' jpayne@69: '====================\n' jpayne@69: '\n' jpayne@69: 'The "with" statement is used to wrap the execution of a block ' jpayne@69: 'with\n' jpayne@69: 'methods defined by a context manager (see section With ' jpayne@69: 'Statement\n' jpayne@69: 'Context Managers). This allows common "try"…"except"…"finally" ' jpayne@69: 'usage\n' jpayne@69: 'patterns to be encapsulated for convenient reuse.\n' jpayne@69: '\n' jpayne@69: ' with_stmt ::= "with" with_item ("," with_item)* ":" suite\n' jpayne@69: ' with_item ::= expression ["as" target]\n' jpayne@69: '\n' jpayne@69: 'The execution of the "with" statement with one “item” proceeds ' jpayne@69: 'as\n' jpayne@69: 'follows:\n' jpayne@69: '\n' jpayne@69: '1. The context expression (the expression given in the ' jpayne@69: '"with_item")\n' jpayne@69: ' is evaluated to obtain a context manager.\n' jpayne@69: '\n' jpayne@69: '2. The context manager’s "__exit__()" is loaded for later use.\n' jpayne@69: '\n' jpayne@69: '3. The context manager’s "__enter__()" method is invoked.\n' jpayne@69: '\n' jpayne@69: '4. If a target was included in the "with" statement, the return\n' jpayne@69: ' value from "__enter__()" is assigned to it.\n' jpayne@69: '\n' jpayne@69: ' Note: The "with" statement guarantees that if the ' jpayne@69: '"__enter__()"\n' jpayne@69: ' method returns without an error, then "__exit__()" will ' jpayne@69: 'always be\n' jpayne@69: ' called. Thus, if an error occurs during the assignment to ' jpayne@69: 'the\n' jpayne@69: ' target list, it will be treated the same as an error ' jpayne@69: 'occurring\n' jpayne@69: ' within the suite would be. See step 6 below.\n' jpayne@69: '\n' jpayne@69: '5. The suite is executed.\n' jpayne@69: '\n' jpayne@69: '6. The context manager’s "__exit__()" method is invoked. If an\n' jpayne@69: ' exception caused the suite to be exited, its type, value, ' jpayne@69: 'and\n' jpayne@69: ' traceback are passed as arguments to "__exit__()". Otherwise, ' jpayne@69: 'three\n' jpayne@69: ' "None" arguments are supplied.\n' jpayne@69: '\n' jpayne@69: ' If the suite was exited due to an exception, and the return ' jpayne@69: 'value\n' jpayne@69: ' from the "__exit__()" method was false, the exception is ' jpayne@69: 'reraised.\n' jpayne@69: ' If the return value was true, the exception is suppressed, ' jpayne@69: 'and\n' jpayne@69: ' execution continues with the statement following the "with"\n' jpayne@69: ' statement.\n' jpayne@69: '\n' jpayne@69: ' If the suite was exited for any reason other than an ' jpayne@69: 'exception, the\n' jpayne@69: ' return value from "__exit__()" is ignored, and execution ' jpayne@69: 'proceeds\n' jpayne@69: ' at the normal location for the kind of exit that was taken.\n' jpayne@69: '\n' jpayne@69: 'With more than one item, the context managers are processed as ' jpayne@69: 'if\n' jpayne@69: 'multiple "with" statements were nested:\n' jpayne@69: '\n' jpayne@69: ' with A() as a, B() as b:\n' jpayne@69: ' suite\n' jpayne@69: '\n' jpayne@69: 'is equivalent to\n' jpayne@69: '\n' jpayne@69: ' with A() as a:\n' jpayne@69: ' with B() as b:\n' jpayne@69: ' suite\n' jpayne@69: '\n' jpayne@69: 'Changed in version 3.1: Support for multiple context ' jpayne@69: 'expressions.\n' jpayne@69: '\n' jpayne@69: 'See also:\n' jpayne@69: '\n' jpayne@69: ' **PEP 343** - The “with” statement\n' jpayne@69: ' The specification, background, and examples for the Python ' jpayne@69: '"with"\n' jpayne@69: ' statement.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Function definitions\n' jpayne@69: '====================\n' jpayne@69: '\n' jpayne@69: 'A function definition defines a user-defined function object ' jpayne@69: '(see\n' jpayne@69: 'section The standard type hierarchy):\n' jpayne@69: '\n' jpayne@69: ' funcdef ::= [decorators] "def" funcname "(" ' jpayne@69: '[parameter_list] ")"\n' jpayne@69: ' ["->" expression] ":" suite\n' jpayne@69: ' decorators ::= decorator+\n' jpayne@69: ' decorator ::= "@" dotted_name ["(" ' jpayne@69: '[argument_list [","]] ")"] NEWLINE\n' jpayne@69: ' dotted_name ::= identifier ("." identifier)*\n' jpayne@69: ' parameter_list ::= defparameter ("," ' jpayne@69: 'defparameter)* "," "/" ["," [parameter_list_no_posonly]]\n' jpayne@69: ' | parameter_list_no_posonly\n' jpayne@69: ' parameter_list_no_posonly ::= defparameter ("," ' jpayne@69: 'defparameter)* ["," [parameter_list_starargs]]\n' jpayne@69: ' | parameter_list_starargs\n' jpayne@69: ' parameter_list_starargs ::= "*" [parameter] ("," ' jpayne@69: 'defparameter)* ["," ["**" parameter [","]]]\n' jpayne@69: ' | "**" parameter [","]\n' jpayne@69: ' parameter ::= identifier [":" expression]\n' jpayne@69: ' defparameter ::= parameter ["=" expression]\n' jpayne@69: ' funcname ::= identifier\n' jpayne@69: '\n' jpayne@69: 'A function definition is an executable statement. Its execution ' jpayne@69: 'binds\n' jpayne@69: 'the function name in the current local namespace to a function ' jpayne@69: 'object\n' jpayne@69: '(a wrapper around the executable code for the function). This\n' jpayne@69: 'function object contains a reference to the current global ' jpayne@69: 'namespace\n' jpayne@69: 'as the global namespace to be used when the function is called.\n' jpayne@69: '\n' jpayne@69: 'The function definition does not execute the function body; this ' jpayne@69: 'gets\n' jpayne@69: 'executed only when the function is called. [2]\n' jpayne@69: '\n' jpayne@69: 'A function definition may be wrapped by one or more *decorator*\n' jpayne@69: 'expressions. Decorator expressions are evaluated when the ' jpayne@69: 'function is\n' jpayne@69: 'defined, in the scope that contains the function definition. ' jpayne@69: 'The\n' jpayne@69: 'result must be a callable, which is invoked with the function ' jpayne@69: 'object\n' jpayne@69: 'as the only argument. The returned value is bound to the ' jpayne@69: 'function name\n' jpayne@69: 'instead of the function object. Multiple decorators are applied ' jpayne@69: 'in\n' jpayne@69: 'nested fashion. For example, the following code\n' jpayne@69: '\n' jpayne@69: ' @f1(arg)\n' jpayne@69: ' @f2\n' jpayne@69: ' def func(): pass\n' jpayne@69: '\n' jpayne@69: 'is roughly equivalent to\n' jpayne@69: '\n' jpayne@69: ' def func(): pass\n' jpayne@69: ' func = f1(arg)(f2(func))\n' jpayne@69: '\n' jpayne@69: 'except that the original function is not temporarily bound to ' jpayne@69: 'the name\n' jpayne@69: '"func".\n' jpayne@69: '\n' jpayne@69: 'When one or more *parameters* have the form *parameter* "="\n' jpayne@69: '*expression*, the function is said to have “default parameter ' jpayne@69: 'values.”\n' jpayne@69: 'For a parameter with a default value, the corresponding ' jpayne@69: '*argument* may\n' jpayne@69: 'be omitted from a call, in which case the parameter’s default ' jpayne@69: 'value is\n' jpayne@69: 'substituted. If a parameter has a default value, all following\n' jpayne@69: 'parameters up until the “"*"” must also have a default value — ' jpayne@69: 'this is\n' jpayne@69: 'a syntactic restriction that is not expressed by the grammar.\n' jpayne@69: '\n' jpayne@69: '**Default parameter values are evaluated from left to right when ' jpayne@69: 'the\n' jpayne@69: 'function definition is executed.** This means that the ' jpayne@69: 'expression is\n' jpayne@69: 'evaluated once, when the function is defined, and that the same ' jpayne@69: '“pre-\n' jpayne@69: 'computed” value is used for each call. This is especially ' jpayne@69: 'important\n' jpayne@69: 'to understand when a default parameter is a mutable object, such ' jpayne@69: 'as a\n' jpayne@69: 'list or a dictionary: if the function modifies the object (e.g. ' jpayne@69: 'by\n' jpayne@69: 'appending an item to a list), the default value is in effect ' jpayne@69: 'modified.\n' jpayne@69: 'This is generally not what was intended. A way around this is ' jpayne@69: 'to use\n' jpayne@69: '"None" as the default, and explicitly test for it in the body of ' jpayne@69: 'the\n' jpayne@69: 'function, e.g.:\n' jpayne@69: '\n' jpayne@69: ' def whats_on_the_telly(penguin=None):\n' jpayne@69: ' if penguin is None:\n' jpayne@69: ' penguin = []\n' jpayne@69: ' penguin.append("property of the zoo")\n' jpayne@69: ' return penguin\n' jpayne@69: '\n' jpayne@69: 'Function call semantics are described in more detail in section ' jpayne@69: 'Calls.\n' jpayne@69: 'A function call always assigns values to all parameters ' jpayne@69: 'mentioned in\n' jpayne@69: 'the parameter list, either from position arguments, from ' jpayne@69: 'keyword\n' jpayne@69: 'arguments, or from default values. If the form “"*identifier"” ' jpayne@69: 'is\n' jpayne@69: 'present, it is initialized to a tuple receiving any excess ' jpayne@69: 'positional\n' jpayne@69: 'parameters, defaulting to the empty tuple. If the form\n' jpayne@69: '“"**identifier"” is present, it is initialized to a new ordered\n' jpayne@69: 'mapping receiving any excess keyword arguments, defaulting to a ' jpayne@69: 'new\n' jpayne@69: 'empty mapping of the same type. Parameters after “"*"” or\n' jpayne@69: '“"*identifier"” are keyword-only parameters and may only be ' jpayne@69: 'passed\n' jpayne@69: 'used keyword arguments.\n' jpayne@69: '\n' jpayne@69: 'Parameters may have an *annotation* of the form “": ' jpayne@69: 'expression"”\n' jpayne@69: 'following the parameter name. Any parameter may have an ' jpayne@69: 'annotation,\n' jpayne@69: 'even those of the form "*identifier" or "**identifier". ' jpayne@69: 'Functions may\n' jpayne@69: 'have “return” annotation of the form “"-> expression"” after ' jpayne@69: 'the\n' jpayne@69: 'parameter list. These annotations can be any valid Python ' jpayne@69: 'expression.\n' jpayne@69: 'The presence of annotations does not change the semantics of a\n' jpayne@69: 'function. The annotation values are available as values of a\n' jpayne@69: 'dictionary keyed by the parameters’ names in the ' jpayne@69: '"__annotations__"\n' jpayne@69: 'attribute of the function object. If the "annotations" import ' jpayne@69: 'from\n' jpayne@69: '"__future__" is used, annotations are preserved as strings at ' jpayne@69: 'runtime\n' jpayne@69: 'which enables postponed evaluation. Otherwise, they are ' jpayne@69: 'evaluated\n' jpayne@69: 'when the function definition is executed. In this case ' jpayne@69: 'annotations\n' jpayne@69: 'may be evaluated in a different order than they appear in the ' jpayne@69: 'source\n' jpayne@69: 'code.\n' jpayne@69: '\n' jpayne@69: 'It is also possible to create anonymous functions (functions not ' jpayne@69: 'bound\n' jpayne@69: 'to a name), for immediate use in expressions. This uses lambda\n' jpayne@69: 'expressions, described in section Lambdas. Note that the ' jpayne@69: 'lambda\n' jpayne@69: 'expression is merely a shorthand for a simplified function ' jpayne@69: 'definition;\n' jpayne@69: 'a function defined in a “"def"” statement can be passed around ' jpayne@69: 'or\n' jpayne@69: 'assigned to another name just like a function defined by a ' jpayne@69: 'lambda\n' jpayne@69: 'expression. The “"def"” form is actually more powerful since ' jpayne@69: 'it\n' jpayne@69: 'allows the execution of multiple statements and annotations.\n' jpayne@69: '\n' jpayne@69: '**Programmer’s note:** Functions are first-class objects. A ' jpayne@69: '“"def"”\n' jpayne@69: 'statement executed inside a function definition defines a local\n' jpayne@69: 'function that can be returned or passed around. Free variables ' jpayne@69: 'used\n' jpayne@69: 'in the nested function can access the local variables of the ' jpayne@69: 'function\n' jpayne@69: 'containing the def. See section Naming and binding for ' jpayne@69: 'details.\n' jpayne@69: '\n' jpayne@69: 'See also:\n' jpayne@69: '\n' jpayne@69: ' **PEP 3107** - Function Annotations\n' jpayne@69: ' The original specification for function annotations.\n' jpayne@69: '\n' jpayne@69: ' **PEP 484** - Type Hints\n' jpayne@69: ' Definition of a standard meaning for annotations: type ' jpayne@69: 'hints.\n' jpayne@69: '\n' jpayne@69: ' **PEP 526** - Syntax for Variable Annotations\n' jpayne@69: ' Ability to type hint variable declarations, including ' jpayne@69: 'class\n' jpayne@69: ' variables and instance variables\n' jpayne@69: '\n' jpayne@69: ' **PEP 563** - Postponed Evaluation of Annotations\n' jpayne@69: ' Support for forward references within annotations by ' jpayne@69: 'preserving\n' jpayne@69: ' annotations in a string form at runtime instead of eager\n' jpayne@69: ' evaluation.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Class definitions\n' jpayne@69: '=================\n' jpayne@69: '\n' jpayne@69: 'A class definition defines a class object (see section The ' jpayne@69: 'standard\n' jpayne@69: 'type hierarchy):\n' jpayne@69: '\n' jpayne@69: ' classdef ::= [decorators] "class" classname [inheritance] ' jpayne@69: '":" suite\n' jpayne@69: ' inheritance ::= "(" [argument_list] ")"\n' jpayne@69: ' classname ::= identifier\n' jpayne@69: '\n' jpayne@69: 'A class definition is an executable statement. The inheritance ' jpayne@69: 'list\n' jpayne@69: 'usually gives a list of base classes (see Metaclasses for more\n' jpayne@69: 'advanced uses), so each item in the list should evaluate to a ' jpayne@69: 'class\n' jpayne@69: 'object which allows subclassing. Classes without an inheritance ' jpayne@69: 'list\n' jpayne@69: 'inherit, by default, from the base class "object"; hence,\n' jpayne@69: '\n' jpayne@69: ' class Foo:\n' jpayne@69: ' pass\n' jpayne@69: '\n' jpayne@69: 'is equivalent to\n' jpayne@69: '\n' jpayne@69: ' class Foo(object):\n' jpayne@69: ' pass\n' jpayne@69: '\n' jpayne@69: 'The class’s suite is then executed in a new execution frame ' jpayne@69: '(see\n' jpayne@69: 'Naming and binding), using a newly created local namespace and ' jpayne@69: 'the\n' jpayne@69: 'original global namespace. (Usually, the suite contains mostly\n' jpayne@69: 'function definitions.) When the class’s suite finishes ' jpayne@69: 'execution, its\n' jpayne@69: 'execution frame is discarded but its local namespace is saved. ' jpayne@69: '[3] A\n' jpayne@69: 'class object is then created using the inheritance list for the ' jpayne@69: 'base\n' jpayne@69: 'classes and the saved local namespace for the attribute ' jpayne@69: 'dictionary.\n' jpayne@69: 'The class name is bound to this class object in the original ' jpayne@69: 'local\n' jpayne@69: 'namespace.\n' jpayne@69: '\n' jpayne@69: 'The order in which attributes are defined in the class body is\n' jpayne@69: 'preserved in the new class’s "__dict__". Note that this is ' jpayne@69: 'reliable\n' jpayne@69: 'only right after the class is created and only for classes that ' jpayne@69: 'were\n' jpayne@69: 'defined using the definition syntax.\n' jpayne@69: '\n' jpayne@69: 'Class creation can be customized heavily using metaclasses.\n' jpayne@69: '\n' jpayne@69: 'Classes can also be decorated: just like when decorating ' jpayne@69: 'functions,\n' jpayne@69: '\n' jpayne@69: ' @f1(arg)\n' jpayne@69: ' @f2\n' jpayne@69: ' class Foo: pass\n' jpayne@69: '\n' jpayne@69: 'is roughly equivalent to\n' jpayne@69: '\n' jpayne@69: ' class Foo: pass\n' jpayne@69: ' Foo = f1(arg)(f2(Foo))\n' jpayne@69: '\n' jpayne@69: 'The evaluation rules for the decorator expressions are the same ' jpayne@69: 'as for\n' jpayne@69: 'function decorators. The result is then bound to the class ' jpayne@69: 'name.\n' jpayne@69: '\n' jpayne@69: '**Programmer’s note:** Variables defined in the class definition ' jpayne@69: 'are\n' jpayne@69: 'class attributes; they are shared by instances. Instance ' jpayne@69: 'attributes\n' jpayne@69: 'can be set in a method with "self.name = value". Both class ' jpayne@69: 'and\n' jpayne@69: 'instance attributes are accessible through the notation ' jpayne@69: '“"self.name"”,\n' jpayne@69: 'and an instance attribute hides a class attribute with the same ' jpayne@69: 'name\n' jpayne@69: 'when accessed in this way. Class attributes can be used as ' jpayne@69: 'defaults\n' jpayne@69: 'for instance attributes, but using mutable values there can lead ' jpayne@69: 'to\n' jpayne@69: 'unexpected results. Descriptors can be used to create instance\n' jpayne@69: 'variables with different implementation details.\n' jpayne@69: '\n' jpayne@69: 'See also:\n' jpayne@69: '\n' jpayne@69: ' **PEP 3115** - Metaclasses in Python 3000\n' jpayne@69: ' The proposal that changed the declaration of metaclasses to ' jpayne@69: 'the\n' jpayne@69: ' current syntax, and the semantics for how classes with\n' jpayne@69: ' metaclasses are constructed.\n' jpayne@69: '\n' jpayne@69: ' **PEP 3129** - Class Decorators\n' jpayne@69: ' The proposal that added class decorators. Function and ' jpayne@69: 'method\n' jpayne@69: ' decorators were introduced in **PEP 318**.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Coroutines\n' jpayne@69: '==========\n' jpayne@69: '\n' jpayne@69: 'New in version 3.5.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Coroutine function definition\n' jpayne@69: '-----------------------------\n' jpayne@69: '\n' jpayne@69: ' async_funcdef ::= [decorators] "async" "def" funcname "(" ' jpayne@69: '[parameter_list] ")"\n' jpayne@69: ' ["->" expression] ":" suite\n' jpayne@69: '\n' jpayne@69: 'Execution of Python coroutines can be suspended and resumed at ' jpayne@69: 'many\n' jpayne@69: 'points (see *coroutine*). Inside the body of a coroutine ' jpayne@69: 'function,\n' jpayne@69: '"await" and "async" identifiers become reserved keywords; ' jpayne@69: '"await"\n' jpayne@69: 'expressions, "async for" and "async with" can only be used in\n' jpayne@69: 'coroutine function bodies.\n' jpayne@69: '\n' jpayne@69: 'Functions defined with "async def" syntax are always coroutine\n' jpayne@69: 'functions, even if they do not contain "await" or "async" ' jpayne@69: 'keywords.\n' jpayne@69: '\n' jpayne@69: 'It is a "SyntaxError" to use a "yield from" expression inside ' jpayne@69: 'the body\n' jpayne@69: 'of a coroutine function.\n' jpayne@69: '\n' jpayne@69: 'An example of a coroutine function:\n' jpayne@69: '\n' jpayne@69: ' async def func(param1, param2):\n' jpayne@69: ' do_stuff()\n' jpayne@69: ' await some_coroutine()\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'The "async for" statement\n' jpayne@69: '-------------------------\n' jpayne@69: '\n' jpayne@69: ' async_for_stmt ::= "async" for_stmt\n' jpayne@69: '\n' jpayne@69: 'An *asynchronous iterable* is able to call asynchronous code in ' jpayne@69: 'its\n' jpayne@69: '*iter* implementation, and *asynchronous iterator* can call\n' jpayne@69: 'asynchronous code in its *next* method.\n' jpayne@69: '\n' jpayne@69: 'The "async for" statement allows convenient iteration over\n' jpayne@69: 'asynchronous iterators.\n' jpayne@69: '\n' jpayne@69: 'The following code:\n' jpayne@69: '\n' jpayne@69: ' async for TARGET in ITER:\n' jpayne@69: ' BLOCK\n' jpayne@69: ' else:\n' jpayne@69: ' BLOCK2\n' jpayne@69: '\n' jpayne@69: 'Is semantically equivalent to:\n' jpayne@69: '\n' jpayne@69: ' iter = (ITER)\n' jpayne@69: ' iter = type(iter).__aiter__(iter)\n' jpayne@69: ' running = True\n' jpayne@69: ' while running:\n' jpayne@69: ' try:\n' jpayne@69: ' TARGET = await type(iter).__anext__(iter)\n' jpayne@69: ' except StopAsyncIteration:\n' jpayne@69: ' running = False\n' jpayne@69: ' else:\n' jpayne@69: ' BLOCK\n' jpayne@69: ' else:\n' jpayne@69: ' BLOCK2\n' jpayne@69: '\n' jpayne@69: 'See also "__aiter__()" and "__anext__()" for details.\n' jpayne@69: '\n' jpayne@69: 'It is a "SyntaxError" to use an "async for" statement outside ' jpayne@69: 'the body\n' jpayne@69: 'of a coroutine function.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'The "async with" statement\n' jpayne@69: '--------------------------\n' jpayne@69: '\n' jpayne@69: ' async_with_stmt ::= "async" with_stmt\n' jpayne@69: '\n' jpayne@69: 'An *asynchronous context manager* is a *context manager* that is ' jpayne@69: 'able\n' jpayne@69: 'to suspend execution in its *enter* and *exit* methods.\n' jpayne@69: '\n' jpayne@69: 'The following code:\n' jpayne@69: '\n' jpayne@69: ' async with EXPR as VAR:\n' jpayne@69: ' BLOCK\n' jpayne@69: '\n' jpayne@69: 'Is semantically equivalent to:\n' jpayne@69: '\n' jpayne@69: ' mgr = (EXPR)\n' jpayne@69: ' aexit = type(mgr).__aexit__\n' jpayne@69: ' aenter = type(mgr).__aenter__(mgr)\n' jpayne@69: '\n' jpayne@69: ' VAR = await aenter\n' jpayne@69: ' try:\n' jpayne@69: ' BLOCK\n' jpayne@69: ' except:\n' jpayne@69: ' if not await aexit(mgr, *sys.exc_info()):\n' jpayne@69: ' raise\n' jpayne@69: ' else:\n' jpayne@69: ' await aexit(mgr, None, None, None)\n' jpayne@69: '\n' jpayne@69: 'See also "__aenter__()" and "__aexit__()" for details.\n' jpayne@69: '\n' jpayne@69: 'It is a "SyntaxError" to use an "async with" statement outside ' jpayne@69: 'the\n' jpayne@69: 'body of a coroutine function.\n' jpayne@69: '\n' jpayne@69: 'See also:\n' jpayne@69: '\n' jpayne@69: ' **PEP 492** - Coroutines with async and await syntax\n' jpayne@69: ' The proposal that made coroutines a proper standalone ' jpayne@69: 'concept in\n' jpayne@69: ' Python, and added supporting syntax.\n' jpayne@69: '\n' jpayne@69: '-[ Footnotes ]-\n' jpayne@69: '\n' jpayne@69: '[1] The exception is propagated to the invocation stack unless\n' jpayne@69: ' there is a "finally" clause which happens to raise another\n' jpayne@69: ' exception. That new exception causes the old one to be ' jpayne@69: 'lost.\n' jpayne@69: '\n' jpayne@69: '[2] A string literal appearing as the first statement in the\n' jpayne@69: ' function body is transformed into the function’s "__doc__"\n' jpayne@69: ' attribute and therefore the function’s *docstring*.\n' jpayne@69: '\n' jpayne@69: '[3] A string literal appearing as the first statement in the ' jpayne@69: 'class\n' jpayne@69: ' body is transformed into the namespace’s "__doc__" item and\n' jpayne@69: ' therefore the class’s *docstring*.\n', jpayne@69: 'context-managers': 'With Statement Context Managers\n' jpayne@69: '*******************************\n' jpayne@69: '\n' jpayne@69: 'A *context manager* is an object that defines the ' jpayne@69: 'runtime context to\n' jpayne@69: 'be established when executing a "with" statement. The ' jpayne@69: 'context manager\n' jpayne@69: 'handles the entry into, and the exit from, the desired ' jpayne@69: 'runtime context\n' jpayne@69: 'for the execution of the block of code. Context ' jpayne@69: 'managers are normally\n' jpayne@69: 'invoked using the "with" statement (described in section ' jpayne@69: 'The with\n' jpayne@69: 'statement), but can also be used by directly invoking ' jpayne@69: 'their methods.\n' jpayne@69: '\n' jpayne@69: 'Typical uses of context managers include saving and ' jpayne@69: 'restoring various\n' jpayne@69: 'kinds of global state, locking and unlocking resources, ' jpayne@69: 'closing opened\n' jpayne@69: 'files, etc.\n' jpayne@69: '\n' jpayne@69: 'For more information on context managers, see Context ' jpayne@69: 'Manager Types.\n' jpayne@69: '\n' jpayne@69: 'object.__enter__(self)\n' jpayne@69: '\n' jpayne@69: ' Enter the runtime context related to this object. The ' jpayne@69: '"with"\n' jpayne@69: ' statement will bind this method’s return value to the ' jpayne@69: 'target(s)\n' jpayne@69: ' specified in the "as" clause of the statement, if ' jpayne@69: 'any.\n' jpayne@69: '\n' jpayne@69: 'object.__exit__(self, exc_type, exc_value, traceback)\n' jpayne@69: '\n' jpayne@69: ' Exit the runtime context related to this object. The ' jpayne@69: 'parameters\n' jpayne@69: ' describe the exception that caused the context to be ' jpayne@69: 'exited. If the\n' jpayne@69: ' context was exited without an exception, all three ' jpayne@69: 'arguments will\n' jpayne@69: ' be "None".\n' jpayne@69: '\n' jpayne@69: ' If an exception is supplied, and the method wishes to ' jpayne@69: 'suppress the\n' jpayne@69: ' exception (i.e., prevent it from being propagated), ' jpayne@69: 'it should\n' jpayne@69: ' return a true value. Otherwise, the exception will be ' jpayne@69: 'processed\n' jpayne@69: ' normally upon exit from this method.\n' jpayne@69: '\n' jpayne@69: ' Note that "__exit__()" methods should not reraise the ' jpayne@69: 'passed-in\n' jpayne@69: ' exception; this is the caller’s responsibility.\n' jpayne@69: '\n' jpayne@69: 'See also:\n' jpayne@69: '\n' jpayne@69: ' **PEP 343** - The “with” statement\n' jpayne@69: ' The specification, background, and examples for the ' jpayne@69: 'Python "with"\n' jpayne@69: ' statement.\n', jpayne@69: 'continue': 'The "continue" statement\n' jpayne@69: '************************\n' jpayne@69: '\n' jpayne@69: ' continue_stmt ::= "continue"\n' jpayne@69: '\n' jpayne@69: '"continue" may only occur syntactically nested in a "for" or ' jpayne@69: '"while"\n' jpayne@69: 'loop, but not nested in a function or class definition within ' jpayne@69: 'that\n' jpayne@69: 'loop. It continues with the next cycle of the nearest enclosing ' jpayne@69: 'loop.\n' jpayne@69: '\n' jpayne@69: 'When "continue" passes control out of a "try" statement with a\n' jpayne@69: '"finally" clause, that "finally" clause is executed before ' jpayne@69: 'really\n' jpayne@69: 'starting the next loop cycle.\n', jpayne@69: 'conversions': 'Arithmetic conversions\n' jpayne@69: '**********************\n' jpayne@69: '\n' jpayne@69: 'When a description of an arithmetic operator below uses the ' jpayne@69: 'phrase\n' jpayne@69: '“the numeric arguments are converted to a common type,” this ' jpayne@69: 'means\n' jpayne@69: 'that the operator implementation for built-in types works as ' jpayne@69: 'follows:\n' jpayne@69: '\n' jpayne@69: '* If either argument is a complex number, the other is ' jpayne@69: 'converted to\n' jpayne@69: ' complex;\n' jpayne@69: '\n' jpayne@69: '* otherwise, if either argument is a floating point number, ' jpayne@69: 'the\n' jpayne@69: ' other is converted to floating point;\n' jpayne@69: '\n' jpayne@69: '* otherwise, both must be integers and no conversion is ' jpayne@69: 'necessary.\n' jpayne@69: '\n' jpayne@69: 'Some additional rules apply for certain operators (e.g., a ' jpayne@69: 'string as a\n' jpayne@69: 'left argument to the ‘%’ operator). Extensions must define ' jpayne@69: 'their own\n' jpayne@69: 'conversion behavior.\n', jpayne@69: 'customization': 'Basic customization\n' jpayne@69: '*******************\n' jpayne@69: '\n' jpayne@69: 'object.__new__(cls[, ...])\n' jpayne@69: '\n' jpayne@69: ' Called to create a new instance of class *cls*. ' jpayne@69: '"__new__()" is a\n' jpayne@69: ' static method (special-cased so you need not declare it ' jpayne@69: 'as such)\n' jpayne@69: ' that takes the class of which an instance was requested ' jpayne@69: 'as its\n' jpayne@69: ' first argument. The remaining arguments are those ' jpayne@69: 'passed to the\n' jpayne@69: ' object constructor expression (the call to the class). ' jpayne@69: 'The return\n' jpayne@69: ' value of "__new__()" should be the new object instance ' jpayne@69: '(usually an\n' jpayne@69: ' instance of *cls*).\n' jpayne@69: '\n' jpayne@69: ' Typical implementations create a new instance of the ' jpayne@69: 'class by\n' jpayne@69: ' invoking the superclass’s "__new__()" method using\n' jpayne@69: ' "super().__new__(cls[, ...])" with appropriate arguments ' jpayne@69: 'and then\n' jpayne@69: ' modifying the newly-created instance as necessary before ' jpayne@69: 'returning\n' jpayne@69: ' it.\n' jpayne@69: '\n' jpayne@69: ' If "__new__()" is invoked during object construction and ' jpayne@69: 'it returns\n' jpayne@69: ' an instance or subclass of *cls*, then the new ' jpayne@69: 'instance’s\n' jpayne@69: ' "__init__()" method will be invoked like ' jpayne@69: '"__init__(self[, ...])",\n' jpayne@69: ' where *self* is the new instance and the remaining ' jpayne@69: 'arguments are\n' jpayne@69: ' the same as were passed to the object constructor.\n' jpayne@69: '\n' jpayne@69: ' If "__new__()" does not return an instance of *cls*, ' jpayne@69: 'then the new\n' jpayne@69: ' instance’s "__init__()" method will not be invoked.\n' jpayne@69: '\n' jpayne@69: ' "__new__()" is intended mainly to allow subclasses of ' jpayne@69: 'immutable\n' jpayne@69: ' types (like int, str, or tuple) to customize instance ' jpayne@69: 'creation. It\n' jpayne@69: ' is also commonly overridden in custom metaclasses in ' jpayne@69: 'order to\n' jpayne@69: ' customize class creation.\n' jpayne@69: '\n' jpayne@69: 'object.__init__(self[, ...])\n' jpayne@69: '\n' jpayne@69: ' Called after the instance has been created (by ' jpayne@69: '"__new__()"), but\n' jpayne@69: ' before it is returned to the caller. The arguments are ' jpayne@69: 'those\n' jpayne@69: ' passed to the class constructor expression. If a base ' jpayne@69: 'class has an\n' jpayne@69: ' "__init__()" method, the derived class’s "__init__()" ' jpayne@69: 'method, if\n' jpayne@69: ' any, must explicitly call it to ensure proper ' jpayne@69: 'initialization of the\n' jpayne@69: ' base class part of the instance; for example:\n' jpayne@69: ' "super().__init__([args...])".\n' jpayne@69: '\n' jpayne@69: ' Because "__new__()" and "__init__()" work together in ' jpayne@69: 'constructing\n' jpayne@69: ' objects ("__new__()" to create it, and "__init__()" to ' jpayne@69: 'customize\n' jpayne@69: ' it), no non-"None" value may be returned by ' jpayne@69: '"__init__()"; doing so\n' jpayne@69: ' will cause a "TypeError" to be raised at runtime.\n' jpayne@69: '\n' jpayne@69: 'object.__del__(self)\n' jpayne@69: '\n' jpayne@69: ' Called when the instance is about to be destroyed. This ' jpayne@69: 'is also\n' jpayne@69: ' called a finalizer or (improperly) a destructor. If a ' jpayne@69: 'base class\n' jpayne@69: ' has a "__del__()" method, the derived class’s ' jpayne@69: '"__del__()" method,\n' jpayne@69: ' if any, must explicitly call it to ensure proper ' jpayne@69: 'deletion of the\n' jpayne@69: ' base class part of the instance.\n' jpayne@69: '\n' jpayne@69: ' It is possible (though not recommended!) for the ' jpayne@69: '"__del__()" method\n' jpayne@69: ' to postpone destruction of the instance by creating a ' jpayne@69: 'new reference\n' jpayne@69: ' to it. This is called object *resurrection*. It is\n' jpayne@69: ' implementation-dependent whether "__del__()" is called a ' jpayne@69: 'second\n' jpayne@69: ' time when a resurrected object is about to be destroyed; ' jpayne@69: 'the\n' jpayne@69: ' current *CPython* implementation only calls it once.\n' jpayne@69: '\n' jpayne@69: ' It is not guaranteed that "__del__()" methods are called ' jpayne@69: 'for\n' jpayne@69: ' objects that still exist when the interpreter exits.\n' jpayne@69: '\n' jpayne@69: ' Note: "del x" doesn’t directly call "x.__del__()" — the ' jpayne@69: 'former\n' jpayne@69: ' decrements the reference count for "x" by one, and the ' jpayne@69: 'latter is\n' jpayne@69: ' only called when "x"’s reference count reaches zero.\n' jpayne@69: '\n' jpayne@69: ' **CPython implementation detail:** It is possible for a ' jpayne@69: 'reference\n' jpayne@69: ' cycle to prevent the reference count of an object from ' jpayne@69: 'going to\n' jpayne@69: ' zero. In this case, the cycle will be later detected ' jpayne@69: 'and deleted\n' jpayne@69: ' by the *cyclic garbage collector*. A common cause of ' jpayne@69: 'reference\n' jpayne@69: ' cycles is when an exception has been caught in a local ' jpayne@69: 'variable.\n' jpayne@69: ' The frame’s locals then reference the exception, which ' jpayne@69: 'references\n' jpayne@69: ' its own traceback, which references the locals of all ' jpayne@69: 'frames caught\n' jpayne@69: ' in the traceback.\n' jpayne@69: '\n' jpayne@69: ' See also: Documentation for the "gc" module.\n' jpayne@69: '\n' jpayne@69: ' Warning: Due to the precarious circumstances under ' jpayne@69: 'which\n' jpayne@69: ' "__del__()" methods are invoked, exceptions that occur ' jpayne@69: 'during\n' jpayne@69: ' their execution are ignored, and a warning is printed ' jpayne@69: 'to\n' jpayne@69: ' "sys.stderr" instead. In particular:\n' jpayne@69: '\n' jpayne@69: ' * "__del__()" can be invoked when arbitrary code is ' jpayne@69: 'being\n' jpayne@69: ' executed, including from any arbitrary thread. If ' jpayne@69: '"__del__()"\n' jpayne@69: ' needs to take a lock or invoke any other blocking ' jpayne@69: 'resource, it\n' jpayne@69: ' may deadlock as the resource may already be taken by ' jpayne@69: 'the code\n' jpayne@69: ' that gets interrupted to execute "__del__()".\n' jpayne@69: '\n' jpayne@69: ' * "__del__()" can be executed during interpreter ' jpayne@69: 'shutdown. As\n' jpayne@69: ' a consequence, the global variables it needs to ' jpayne@69: 'access\n' jpayne@69: ' (including other modules) may already have been ' jpayne@69: 'deleted or set\n' jpayne@69: ' to "None". Python guarantees that globals whose name ' jpayne@69: 'begins\n' jpayne@69: ' with a single underscore are deleted from their ' jpayne@69: 'module before\n' jpayne@69: ' other globals are deleted; if no other references to ' jpayne@69: 'such\n' jpayne@69: ' globals exist, this may help in assuring that ' jpayne@69: 'imported modules\n' jpayne@69: ' are still available at the time when the "__del__()" ' jpayne@69: 'method is\n' jpayne@69: ' called.\n' jpayne@69: '\n' jpayne@69: 'object.__repr__(self)\n' jpayne@69: '\n' jpayne@69: ' Called by the "repr()" built-in function to compute the ' jpayne@69: '“official”\n' jpayne@69: ' string representation of an object. If at all possible, ' jpayne@69: 'this\n' jpayne@69: ' should look like a valid Python expression that could be ' jpayne@69: 'used to\n' jpayne@69: ' recreate an object with the same value (given an ' jpayne@69: 'appropriate\n' jpayne@69: ' environment). If this is not possible, a string of the ' jpayne@69: 'form\n' jpayne@69: ' "<...some useful description...>" should be returned. ' jpayne@69: 'The return\n' jpayne@69: ' value must be a string object. If a class defines ' jpayne@69: '"__repr__()" but\n' jpayne@69: ' not "__str__()", then "__repr__()" is also used when an ' jpayne@69: '“informal”\n' jpayne@69: ' string representation of instances of that class is ' jpayne@69: 'required.\n' jpayne@69: '\n' jpayne@69: ' This is typically used for debugging, so it is important ' jpayne@69: 'that the\n' jpayne@69: ' representation is information-rich and unambiguous.\n' jpayne@69: '\n' jpayne@69: 'object.__str__(self)\n' jpayne@69: '\n' jpayne@69: ' Called by "str(object)" and the built-in functions ' jpayne@69: '"format()" and\n' jpayne@69: ' "print()" to compute the “informal” or nicely printable ' jpayne@69: 'string\n' jpayne@69: ' representation of an object. The return value must be a ' jpayne@69: 'string\n' jpayne@69: ' object.\n' jpayne@69: '\n' jpayne@69: ' This method differs from "object.__repr__()" in that ' jpayne@69: 'there is no\n' jpayne@69: ' expectation that "__str__()" return a valid Python ' jpayne@69: 'expression: a\n' jpayne@69: ' more convenient or concise representation can be used.\n' jpayne@69: '\n' jpayne@69: ' The default implementation defined by the built-in type ' jpayne@69: '"object"\n' jpayne@69: ' calls "object.__repr__()".\n' jpayne@69: '\n' jpayne@69: 'object.__bytes__(self)\n' jpayne@69: '\n' jpayne@69: ' Called by bytes to compute a byte-string representation ' jpayne@69: 'of an\n' jpayne@69: ' object. This should return a "bytes" object.\n' jpayne@69: '\n' jpayne@69: 'object.__format__(self, format_spec)\n' jpayne@69: '\n' jpayne@69: ' Called by the "format()" built-in function, and by ' jpayne@69: 'extension,\n' jpayne@69: ' evaluation of formatted string literals and the ' jpayne@69: '"str.format()"\n' jpayne@69: ' method, to produce a “formatted” string representation ' jpayne@69: 'of an\n' jpayne@69: ' object. The *format_spec* argument is a string that ' jpayne@69: 'contains a\n' jpayne@69: ' description of the formatting options desired. The ' jpayne@69: 'interpretation\n' jpayne@69: ' of the *format_spec* argument is up to the type ' jpayne@69: 'implementing\n' jpayne@69: ' "__format__()", however most classes will either ' jpayne@69: 'delegate\n' jpayne@69: ' formatting to one of the built-in types, or use a ' jpayne@69: 'similar\n' jpayne@69: ' formatting option syntax.\n' jpayne@69: '\n' jpayne@69: ' See Format Specification Mini-Language for a description ' jpayne@69: 'of the\n' jpayne@69: ' standard formatting syntax.\n' jpayne@69: '\n' jpayne@69: ' The return value must be a string object.\n' jpayne@69: '\n' jpayne@69: ' Changed in version 3.4: The __format__ method of ' jpayne@69: '"object" itself\n' jpayne@69: ' raises a "TypeError" if passed any non-empty string.\n' jpayne@69: '\n' jpayne@69: ' Changed in version 3.7: "object.__format__(x, \'\')" is ' jpayne@69: 'now\n' jpayne@69: ' equivalent to "str(x)" rather than "format(str(self), ' jpayne@69: '\'\')".\n' jpayne@69: '\n' jpayne@69: 'object.__lt__(self, other)\n' jpayne@69: 'object.__le__(self, other)\n' jpayne@69: 'object.__eq__(self, other)\n' jpayne@69: 'object.__ne__(self, other)\n' jpayne@69: 'object.__gt__(self, other)\n' jpayne@69: 'object.__ge__(self, other)\n' jpayne@69: '\n' jpayne@69: ' These are the so-called “rich comparison” methods. The\n' jpayne@69: ' correspondence between operator symbols and method names ' jpayne@69: 'is as\n' jpayne@69: ' follows: "xy" calls\n' jpayne@69: ' "x.__gt__(y)", and "x>=y" calls "x.__ge__(y)".\n' jpayne@69: '\n' jpayne@69: ' A rich comparison method may return the singleton ' jpayne@69: '"NotImplemented"\n' jpayne@69: ' if it does not implement the operation for a given pair ' jpayne@69: 'of\n' jpayne@69: ' arguments. By convention, "False" and "True" are ' jpayne@69: 'returned for a\n' jpayne@69: ' successful comparison. However, these methods can return ' jpayne@69: 'any value,\n' jpayne@69: ' so if the comparison operator is used in a Boolean ' jpayne@69: 'context (e.g.,\n' jpayne@69: ' in the condition of an "if" statement), Python will call ' jpayne@69: '"bool()"\n' jpayne@69: ' on the value to determine if the result is true or ' jpayne@69: 'false.\n' jpayne@69: '\n' jpayne@69: ' By default, "__ne__()" delegates to "__eq__()" and ' jpayne@69: 'inverts the\n' jpayne@69: ' result unless it is "NotImplemented". There are no ' jpayne@69: 'other implied\n' jpayne@69: ' relationships among the comparison operators, for ' jpayne@69: 'example, the\n' jpayne@69: ' truth of "(x.__hash__".\n' jpayne@69: '\n' jpayne@69: ' If a class that does not override "__eq__()" wishes to ' jpayne@69: 'suppress\n' jpayne@69: ' hash support, it should include "__hash__ = None" in the ' jpayne@69: 'class\n' jpayne@69: ' definition. A class which defines its own "__hash__()" ' jpayne@69: 'that\n' jpayne@69: ' explicitly raises a "TypeError" would be incorrectly ' jpayne@69: 'identified as\n' jpayne@69: ' hashable by an "isinstance(obj, ' jpayne@69: 'collections.abc.Hashable)" call.\n' jpayne@69: '\n' jpayne@69: ' Note: By default, the "__hash__()" values of str and ' jpayne@69: 'bytes\n' jpayne@69: ' objects are “salted” with an unpredictable random ' jpayne@69: 'value.\n' jpayne@69: ' Although they remain constant within an individual ' jpayne@69: 'Python\n' jpayne@69: ' process, they are not predictable between repeated ' jpayne@69: 'invocations of\n' jpayne@69: ' Python.This is intended to provide protection against ' jpayne@69: 'a denial-\n' jpayne@69: ' of-service caused by carefully-chosen inputs that ' jpayne@69: 'exploit the\n' jpayne@69: ' worst case performance of a dict insertion, O(n^2) ' jpayne@69: 'complexity.\n' jpayne@69: ' See ' jpayne@69: 'http://www.ocert.org/advisories/ocert-2011-003.html for\n' jpayne@69: ' details.Changing hash values affects the iteration ' jpayne@69: 'order of sets.\n' jpayne@69: ' Python has never made guarantees about this ordering ' jpayne@69: '(and it\n' jpayne@69: ' typically varies between 32-bit and 64-bit builds).See ' jpayne@69: 'also\n' jpayne@69: ' "PYTHONHASHSEED".\n' jpayne@69: '\n' jpayne@69: ' Changed in version 3.3: Hash randomization is enabled by ' jpayne@69: 'default.\n' jpayne@69: '\n' jpayne@69: 'object.__bool__(self)\n' jpayne@69: '\n' jpayne@69: ' Called to implement truth value testing and the built-in ' jpayne@69: 'operation\n' jpayne@69: ' "bool()"; should return "False" or "True". When this ' jpayne@69: 'method is not\n' jpayne@69: ' defined, "__len__()" is called, if it is defined, and ' jpayne@69: 'the object is\n' jpayne@69: ' considered true if its result is nonzero. If a class ' jpayne@69: 'defines\n' jpayne@69: ' neither "__len__()" nor "__bool__()", all its instances ' jpayne@69: 'are\n' jpayne@69: ' considered true.\n', jpayne@69: 'debugger': '"pdb" — The Python Debugger\n' jpayne@69: '***************************\n' jpayne@69: '\n' jpayne@69: '**Source code:** Lib/pdb.py\n' jpayne@69: '\n' jpayne@69: '======================================================================\n' jpayne@69: '\n' jpayne@69: 'The module "pdb" defines an interactive source code debugger ' jpayne@69: 'for\n' jpayne@69: 'Python programs. It supports setting (conditional) breakpoints ' jpayne@69: 'and\n' jpayne@69: 'single stepping at the source line level, inspection of stack ' jpayne@69: 'frames,\n' jpayne@69: 'source code listing, and evaluation of arbitrary Python code in ' jpayne@69: 'the\n' jpayne@69: 'context of any stack frame. It also supports post-mortem ' jpayne@69: 'debugging\n' jpayne@69: 'and can be called under program control.\n' jpayne@69: '\n' jpayne@69: 'The debugger is extensible – it is actually defined as the ' jpayne@69: 'class\n' jpayne@69: '"Pdb". This is currently undocumented but easily understood by ' jpayne@69: 'reading\n' jpayne@69: 'the source. The extension interface uses the modules "bdb" and ' jpayne@69: '"cmd".\n' jpayne@69: '\n' jpayne@69: 'The debugger’s prompt is "(Pdb)". Typical usage to run a program ' jpayne@69: 'under\n' jpayne@69: 'control of the debugger is:\n' jpayne@69: '\n' jpayne@69: ' >>> import pdb\n' jpayne@69: ' >>> import mymodule\n' jpayne@69: " >>> pdb.run('mymodule.test()')\n" jpayne@69: ' > (0)?()\n' jpayne@69: ' (Pdb) continue\n' jpayne@69: ' > (1)?()\n' jpayne@69: ' (Pdb) continue\n' jpayne@69: " NameError: 'spam'\n" jpayne@69: ' > (1)?()\n' jpayne@69: ' (Pdb)\n' jpayne@69: '\n' jpayne@69: 'Changed in version 3.3: Tab-completion via the "readline" module ' jpayne@69: 'is\n' jpayne@69: 'available for commands and command arguments, e.g. the current ' jpayne@69: 'global\n' jpayne@69: 'and local names are offered as arguments of the "p" command.\n' jpayne@69: '\n' jpayne@69: '"pdb.py" can also be invoked as a script to debug other ' jpayne@69: 'scripts. For\n' jpayne@69: 'example:\n' jpayne@69: '\n' jpayne@69: ' python3 -m pdb myscript.py\n' jpayne@69: '\n' jpayne@69: 'When invoked as a script, pdb will automatically enter ' jpayne@69: 'post-mortem\n' jpayne@69: 'debugging if the program being debugged exits abnormally. After ' jpayne@69: 'post-\n' jpayne@69: 'mortem debugging (or after normal exit of the program), pdb ' jpayne@69: 'will\n' jpayne@69: 'restart the program. Automatic restarting preserves pdb’s state ' jpayne@69: '(such\n' jpayne@69: 'as breakpoints) and in most cases is more useful than quitting ' jpayne@69: 'the\n' jpayne@69: 'debugger upon program’s exit.\n' jpayne@69: '\n' jpayne@69: 'New in version 3.2: "pdb.py" now accepts a "-c" option that ' jpayne@69: 'executes\n' jpayne@69: 'commands as if given in a ".pdbrc" file, see Debugger Commands.\n' jpayne@69: '\n' jpayne@69: 'New in version 3.7: "pdb.py" now accepts a "-m" option that ' jpayne@69: 'execute\n' jpayne@69: 'modules similar to the way "python3 -m" does. As with a script, ' jpayne@69: 'the\n' jpayne@69: 'debugger will pause execution just before the first line of the\n' jpayne@69: 'module.\n' jpayne@69: '\n' jpayne@69: 'The typical usage to break into the debugger from a running ' jpayne@69: 'program is\n' jpayne@69: 'to insert\n' jpayne@69: '\n' jpayne@69: ' import pdb; pdb.set_trace()\n' jpayne@69: '\n' jpayne@69: 'at the location you want to break into the debugger. You can ' jpayne@69: 'then\n' jpayne@69: 'step through the code following this statement, and continue ' jpayne@69: 'running\n' jpayne@69: 'without the debugger using the "continue" command.\n' jpayne@69: '\n' jpayne@69: 'New in version 3.7: The built-in "breakpoint()", when called ' jpayne@69: 'with\n' jpayne@69: 'defaults, can be used instead of "import pdb; pdb.set_trace()".\n' jpayne@69: '\n' jpayne@69: 'The typical usage to inspect a crashed program is:\n' jpayne@69: '\n' jpayne@69: ' >>> import pdb\n' jpayne@69: ' >>> import mymodule\n' jpayne@69: ' >>> mymodule.test()\n' jpayne@69: ' Traceback (most recent call last):\n' jpayne@69: ' File "", line 1, in \n' jpayne@69: ' File "./mymodule.py", line 4, in test\n' jpayne@69: ' test2()\n' jpayne@69: ' File "./mymodule.py", line 3, in test2\n' jpayne@69: ' print(spam)\n' jpayne@69: ' NameError: spam\n' jpayne@69: ' >>> pdb.pm()\n' jpayne@69: ' > ./mymodule.py(3)test2()\n' jpayne@69: ' -> print(spam)\n' jpayne@69: ' (Pdb)\n' jpayne@69: '\n' jpayne@69: 'The module defines the following functions; each enters the ' jpayne@69: 'debugger\n' jpayne@69: 'in a slightly different way:\n' jpayne@69: '\n' jpayne@69: 'pdb.run(statement, globals=None, locals=None)\n' jpayne@69: '\n' jpayne@69: ' Execute the *statement* (given as a string or a code object) ' jpayne@69: 'under\n' jpayne@69: ' debugger control. The debugger prompt appears before any ' jpayne@69: 'code is\n' jpayne@69: ' executed; you can set breakpoints and type "continue", or you ' jpayne@69: 'can\n' jpayne@69: ' step through the statement using "step" or "next" (all these\n' jpayne@69: ' commands are explained below). The optional *globals* and ' jpayne@69: '*locals*\n' jpayne@69: ' arguments specify the environment in which the code is ' jpayne@69: 'executed; by\n' jpayne@69: ' default the dictionary of the module "__main__" is used. ' jpayne@69: '(See the\n' jpayne@69: ' explanation of the built-in "exec()" or "eval()" functions.)\n' jpayne@69: '\n' jpayne@69: 'pdb.runeval(expression, globals=None, locals=None)\n' jpayne@69: '\n' jpayne@69: ' Evaluate the *expression* (given as a string or a code ' jpayne@69: 'object)\n' jpayne@69: ' under debugger control. When "runeval()" returns, it returns ' jpayne@69: 'the\n' jpayne@69: ' value of the expression. Otherwise this function is similar ' jpayne@69: 'to\n' jpayne@69: ' "run()".\n' jpayne@69: '\n' jpayne@69: 'pdb.runcall(function, *args, **kwds)\n' jpayne@69: '\n' jpayne@69: ' Call the *function* (a function or method object, not a ' jpayne@69: 'string)\n' jpayne@69: ' with the given arguments. When "runcall()" returns, it ' jpayne@69: 'returns\n' jpayne@69: ' whatever the function call returned. The debugger prompt ' jpayne@69: 'appears\n' jpayne@69: ' as soon as the function is entered.\n' jpayne@69: '\n' jpayne@69: 'pdb.set_trace(*, header=None)\n' jpayne@69: '\n' jpayne@69: ' Enter the debugger at the calling stack frame. This is ' jpayne@69: 'useful to\n' jpayne@69: ' hard-code a breakpoint at a given point in a program, even if ' jpayne@69: 'the\n' jpayne@69: ' code is not otherwise being debugged (e.g. when an assertion\n' jpayne@69: ' fails). If given, *header* is printed to the console just ' jpayne@69: 'before\n' jpayne@69: ' debugging begins.\n' jpayne@69: '\n' jpayne@69: ' Changed in version 3.7: The keyword-only argument *header*.\n' jpayne@69: '\n' jpayne@69: 'pdb.post_mortem(traceback=None)\n' jpayne@69: '\n' jpayne@69: ' Enter post-mortem debugging of the given *traceback* object. ' jpayne@69: 'If no\n' jpayne@69: ' *traceback* is given, it uses the one of the exception that ' jpayne@69: 'is\n' jpayne@69: ' currently being handled (an exception must be being handled ' jpayne@69: 'if the\n' jpayne@69: ' default is to be used).\n' jpayne@69: '\n' jpayne@69: 'pdb.pm()\n' jpayne@69: '\n' jpayne@69: ' Enter post-mortem debugging of the traceback found in\n' jpayne@69: ' "sys.last_traceback".\n' jpayne@69: '\n' jpayne@69: 'The "run*" functions and "set_trace()" are aliases for ' jpayne@69: 'instantiating\n' jpayne@69: 'the "Pdb" class and calling the method of the same name. If you ' jpayne@69: 'want\n' jpayne@69: 'to access further features, you have to do this yourself:\n' jpayne@69: '\n' jpayne@69: "class pdb.Pdb(completekey='tab', stdin=None, stdout=None, " jpayne@69: 'skip=None, nosigint=False, readrc=True)\n' jpayne@69: '\n' jpayne@69: ' "Pdb" is the debugger class.\n' jpayne@69: '\n' jpayne@69: ' The *completekey*, *stdin* and *stdout* arguments are passed ' jpayne@69: 'to the\n' jpayne@69: ' underlying "cmd.Cmd" class; see the description there.\n' jpayne@69: '\n' jpayne@69: ' The *skip* argument, if given, must be an iterable of ' jpayne@69: 'glob-style\n' jpayne@69: ' module name patterns. The debugger will not step into frames ' jpayne@69: 'that\n' jpayne@69: ' originate in a module that matches one of these patterns. ' jpayne@69: '[1]\n' jpayne@69: '\n' jpayne@69: ' By default, Pdb sets a handler for the SIGINT signal (which ' jpayne@69: 'is sent\n' jpayne@69: ' when the user presses "Ctrl-C" on the console) when you give ' jpayne@69: 'a\n' jpayne@69: ' "continue" command. This allows you to break into the ' jpayne@69: 'debugger\n' jpayne@69: ' again by pressing "Ctrl-C". If you want Pdb not to touch ' jpayne@69: 'the\n' jpayne@69: ' SIGINT handler, set *nosigint* to true.\n' jpayne@69: '\n' jpayne@69: ' The *readrc* argument defaults to true and controls whether ' jpayne@69: 'Pdb\n' jpayne@69: ' will load .pdbrc files from the filesystem.\n' jpayne@69: '\n' jpayne@69: ' Example call to enable tracing with *skip*:\n' jpayne@69: '\n' jpayne@69: " import pdb; pdb.Pdb(skip=['django.*']).set_trace()\n" jpayne@69: '\n' jpayne@69: ' Raises an auditing event "pdb.Pdb" with no arguments.\n' jpayne@69: '\n' jpayne@69: ' New in version 3.1: The *skip* argument.\n' jpayne@69: '\n' jpayne@69: ' New in version 3.2: The *nosigint* argument. Previously, a ' jpayne@69: 'SIGINT\n' jpayne@69: ' handler was never set by Pdb.\n' jpayne@69: '\n' jpayne@69: ' Changed in version 3.6: The *readrc* argument.\n' jpayne@69: '\n' jpayne@69: ' run(statement, globals=None, locals=None)\n' jpayne@69: ' runeval(expression, globals=None, locals=None)\n' jpayne@69: ' runcall(function, *args, **kwds)\n' jpayne@69: ' set_trace()\n' jpayne@69: '\n' jpayne@69: ' See the documentation for the functions explained above.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Debugger Commands\n' jpayne@69: '=================\n' jpayne@69: '\n' jpayne@69: 'The commands recognized by the debugger are listed below. Most\n' jpayne@69: 'commands can be abbreviated to one or two letters as indicated; ' jpayne@69: 'e.g.\n' jpayne@69: '"h(elp)" means that either "h" or "help" can be used to enter ' jpayne@69: 'the help\n' jpayne@69: 'command (but not "he" or "hel", nor "H" or "Help" or "HELP").\n' jpayne@69: 'Arguments to commands must be separated by whitespace (spaces ' jpayne@69: 'or\n' jpayne@69: 'tabs). Optional arguments are enclosed in square brackets ' jpayne@69: '("[]") in\n' jpayne@69: 'the command syntax; the square brackets must not be typed.\n' jpayne@69: 'Alternatives in the command syntax are separated by a vertical ' jpayne@69: 'bar\n' jpayne@69: '("|").\n' jpayne@69: '\n' jpayne@69: 'Entering a blank line repeats the last command entered. ' jpayne@69: 'Exception: if\n' jpayne@69: 'the last command was a "list" command, the next 11 lines are ' jpayne@69: 'listed.\n' jpayne@69: '\n' jpayne@69: 'Commands that the debugger doesn’t recognize are assumed to be ' jpayne@69: 'Python\n' jpayne@69: 'statements and are executed in the context of the program being\n' jpayne@69: 'debugged. Python statements can also be prefixed with an ' jpayne@69: 'exclamation\n' jpayne@69: 'point ("!"). This is a powerful way to inspect the program ' jpayne@69: 'being\n' jpayne@69: 'debugged; it is even possible to change a variable or call a ' jpayne@69: 'function.\n' jpayne@69: 'When an exception occurs in such a statement, the exception name ' jpayne@69: 'is\n' jpayne@69: 'printed but the debugger’s state is not changed.\n' jpayne@69: '\n' jpayne@69: 'The debugger supports aliases. Aliases can have parameters ' jpayne@69: 'which\n' jpayne@69: 'allows one a certain level of adaptability to the context under\n' jpayne@69: 'examination.\n' jpayne@69: '\n' jpayne@69: 'Multiple commands may be entered on a single line, separated by ' jpayne@69: '";;".\n' jpayne@69: '(A single ";" is not used as it is the separator for multiple ' jpayne@69: 'commands\n' jpayne@69: 'in a line that is passed to the Python parser.) No intelligence ' jpayne@69: 'is\n' jpayne@69: 'applied to separating the commands; the input is split at the ' jpayne@69: 'first\n' jpayne@69: '";;" pair, even if it is in the middle of a quoted string.\n' jpayne@69: '\n' jpayne@69: 'If a file ".pdbrc" exists in the user’s home directory or in ' jpayne@69: 'the\n' jpayne@69: 'current directory, it is read in and executed as if it had been ' jpayne@69: 'typed\n' jpayne@69: 'at the debugger prompt. This is particularly useful for ' jpayne@69: 'aliases. If\n' jpayne@69: 'both files exist, the one in the home directory is read first ' jpayne@69: 'and\n' jpayne@69: 'aliases defined there can be overridden by the local file.\n' jpayne@69: '\n' jpayne@69: 'Changed in version 3.2: ".pdbrc" can now contain commands that\n' jpayne@69: 'continue debugging, such as "continue" or "next". Previously, ' jpayne@69: 'these\n' jpayne@69: 'commands had no effect.\n' jpayne@69: '\n' jpayne@69: 'h(elp) [command]\n' jpayne@69: '\n' jpayne@69: ' Without argument, print the list of available commands. With ' jpayne@69: 'a\n' jpayne@69: ' *command* as argument, print help about that command. "help ' jpayne@69: 'pdb"\n' jpayne@69: ' displays the full documentation (the docstring of the "pdb"\n' jpayne@69: ' module). Since the *command* argument must be an identifier, ' jpayne@69: '"help\n' jpayne@69: ' exec" must be entered to get help on the "!" command.\n' jpayne@69: '\n' jpayne@69: 'w(here)\n' jpayne@69: '\n' jpayne@69: ' Print a stack trace, with the most recent frame at the ' jpayne@69: 'bottom. An\n' jpayne@69: ' arrow indicates the current frame, which determines the ' jpayne@69: 'context of\n' jpayne@69: ' most commands.\n' jpayne@69: '\n' jpayne@69: 'd(own) [count]\n' jpayne@69: '\n' jpayne@69: ' Move the current frame *count* (default one) levels down in ' jpayne@69: 'the\n' jpayne@69: ' stack trace (to a newer frame).\n' jpayne@69: '\n' jpayne@69: 'u(p) [count]\n' jpayne@69: '\n' jpayne@69: ' Move the current frame *count* (default one) levels up in the ' jpayne@69: 'stack\n' jpayne@69: ' trace (to an older frame).\n' jpayne@69: '\n' jpayne@69: 'b(reak) [([filename:]lineno | function) [, condition]]\n' jpayne@69: '\n' jpayne@69: ' With a *lineno* argument, set a break there in the current ' jpayne@69: 'file.\n' jpayne@69: ' With a *function* argument, set a break at the first ' jpayne@69: 'executable\n' jpayne@69: ' statement within that function. The line number may be ' jpayne@69: 'prefixed\n' jpayne@69: ' with a filename and a colon, to specify a breakpoint in ' jpayne@69: 'another\n' jpayne@69: ' file (probably one that hasn’t been loaded yet). The file ' jpayne@69: 'is\n' jpayne@69: ' searched on "sys.path". Note that each breakpoint is ' jpayne@69: 'assigned a\n' jpayne@69: ' number to which all the other breakpoint commands refer.\n' jpayne@69: '\n' jpayne@69: ' If a second argument is present, it is an expression which ' jpayne@69: 'must\n' jpayne@69: ' evaluate to true before the breakpoint is honored.\n' jpayne@69: '\n' jpayne@69: ' Without argument, list all breaks, including for each ' jpayne@69: 'breakpoint,\n' jpayne@69: ' the number of times that breakpoint has been hit, the ' jpayne@69: 'current\n' jpayne@69: ' ignore count, and the associated condition if any.\n' jpayne@69: '\n' jpayne@69: 'tbreak [([filename:]lineno | function) [, condition]]\n' jpayne@69: '\n' jpayne@69: ' Temporary breakpoint, which is removed automatically when it ' jpayne@69: 'is\n' jpayne@69: ' first hit. The arguments are the same as for "break".\n' jpayne@69: '\n' jpayne@69: 'cl(ear) [filename:lineno | bpnumber [bpnumber ...]]\n' jpayne@69: '\n' jpayne@69: ' With a *filename:lineno* argument, clear all the breakpoints ' jpayne@69: 'at\n' jpayne@69: ' this line. With a space separated list of breakpoint numbers, ' jpayne@69: 'clear\n' jpayne@69: ' those breakpoints. Without argument, clear all breaks (but ' jpayne@69: 'first\n' jpayne@69: ' ask confirmation).\n' jpayne@69: '\n' jpayne@69: 'disable [bpnumber [bpnumber ...]]\n' jpayne@69: '\n' jpayne@69: ' Disable the breakpoints given as a space separated list of\n' jpayne@69: ' breakpoint numbers. Disabling a breakpoint means it cannot ' jpayne@69: 'cause\n' jpayne@69: ' the program to stop execution, but unlike clearing a ' jpayne@69: 'breakpoint, it\n' jpayne@69: ' remains in the list of breakpoints and can be (re-)enabled.\n' jpayne@69: '\n' jpayne@69: 'enable [bpnumber [bpnumber ...]]\n' jpayne@69: '\n' jpayne@69: ' Enable the breakpoints specified.\n' jpayne@69: '\n' jpayne@69: 'ignore bpnumber [count]\n' jpayne@69: '\n' jpayne@69: ' Set the ignore count for the given breakpoint number. If ' jpayne@69: 'count is\n' jpayne@69: ' omitted, the ignore count is set to 0. A breakpoint becomes ' jpayne@69: 'active\n' jpayne@69: ' when the ignore count is zero. When non-zero, the count is\n' jpayne@69: ' decremented each time the breakpoint is reached and the ' jpayne@69: 'breakpoint\n' jpayne@69: ' is not disabled and any associated condition evaluates to ' jpayne@69: 'true.\n' jpayne@69: '\n' jpayne@69: 'condition bpnumber [condition]\n' jpayne@69: '\n' jpayne@69: ' Set a new *condition* for the breakpoint, an expression which ' jpayne@69: 'must\n' jpayne@69: ' evaluate to true before the breakpoint is honored. If ' jpayne@69: '*condition*\n' jpayne@69: ' is absent, any existing condition is removed; i.e., the ' jpayne@69: 'breakpoint\n' jpayne@69: ' is made unconditional.\n' jpayne@69: '\n' jpayne@69: 'commands [bpnumber]\n' jpayne@69: '\n' jpayne@69: ' Specify a list of commands for breakpoint number *bpnumber*. ' jpayne@69: 'The\n' jpayne@69: ' commands themselves appear on the following lines. Type a ' jpayne@69: 'line\n' jpayne@69: ' containing just "end" to terminate the commands. An example:\n' jpayne@69: '\n' jpayne@69: ' (Pdb) commands 1\n' jpayne@69: ' (com) p some_variable\n' jpayne@69: ' (com) end\n' jpayne@69: ' (Pdb)\n' jpayne@69: '\n' jpayne@69: ' To remove all commands from a breakpoint, type "commands" ' jpayne@69: 'and\n' jpayne@69: ' follow it immediately with "end"; that is, give no commands.\n' jpayne@69: '\n' jpayne@69: ' With no *bpnumber* argument, "commands" refers to the last\n' jpayne@69: ' breakpoint set.\n' jpayne@69: '\n' jpayne@69: ' You can use breakpoint commands to start your program up ' jpayne@69: 'again.\n' jpayne@69: ' Simply use the "continue" command, or "step", or any other ' jpayne@69: 'command\n' jpayne@69: ' that resumes execution.\n' jpayne@69: '\n' jpayne@69: ' Specifying any command resuming execution (currently ' jpayne@69: '"continue",\n' jpayne@69: ' "step", "next", "return", "jump", "quit" and their ' jpayne@69: 'abbreviations)\n' jpayne@69: ' terminates the command list (as if that command was ' jpayne@69: 'immediately\n' jpayne@69: ' followed by end). This is because any time you resume ' jpayne@69: 'execution\n' jpayne@69: ' (even with a simple next or step), you may encounter another\n' jpayne@69: ' breakpoint—which could have its own command list, leading to\n' jpayne@69: ' ambiguities about which list to execute.\n' jpayne@69: '\n' jpayne@69: ' If you use the ‘silent’ command in the command list, the ' jpayne@69: 'usual\n' jpayne@69: ' message about stopping at a breakpoint is not printed. This ' jpayne@69: 'may be\n' jpayne@69: ' desirable for breakpoints that are to print a specific ' jpayne@69: 'message and\n' jpayne@69: ' then continue. If none of the other commands print anything, ' jpayne@69: 'you\n' jpayne@69: ' see no sign that the breakpoint was reached.\n' jpayne@69: '\n' jpayne@69: 's(tep)\n' jpayne@69: '\n' jpayne@69: ' Execute the current line, stop at the first possible ' jpayne@69: 'occasion\n' jpayne@69: ' (either in a function that is called or on the next line in ' jpayne@69: 'the\n' jpayne@69: ' current function).\n' jpayne@69: '\n' jpayne@69: 'n(ext)\n' jpayne@69: '\n' jpayne@69: ' Continue execution until the next line in the current ' jpayne@69: 'function is\n' jpayne@69: ' reached or it returns. (The difference between "next" and ' jpayne@69: '"step"\n' jpayne@69: ' is that "step" stops inside a called function, while "next"\n' jpayne@69: ' executes called functions at (nearly) full speed, only ' jpayne@69: 'stopping at\n' jpayne@69: ' the next line in the current function.)\n' jpayne@69: '\n' jpayne@69: 'unt(il) [lineno]\n' jpayne@69: '\n' jpayne@69: ' Without argument, continue execution until the line with a ' jpayne@69: 'number\n' jpayne@69: ' greater than the current one is reached.\n' jpayne@69: '\n' jpayne@69: ' With a line number, continue execution until a line with a ' jpayne@69: 'number\n' jpayne@69: ' greater or equal to that is reached. In both cases, also ' jpayne@69: 'stop when\n' jpayne@69: ' the current frame returns.\n' jpayne@69: '\n' jpayne@69: ' Changed in version 3.2: Allow giving an explicit line ' jpayne@69: 'number.\n' jpayne@69: '\n' jpayne@69: 'r(eturn)\n' jpayne@69: '\n' jpayne@69: ' Continue execution until the current function returns.\n' jpayne@69: '\n' jpayne@69: 'c(ont(inue))\n' jpayne@69: '\n' jpayne@69: ' Continue execution, only stop when a breakpoint is ' jpayne@69: 'encountered.\n' jpayne@69: '\n' jpayne@69: 'j(ump) lineno\n' jpayne@69: '\n' jpayne@69: ' Set the next line that will be executed. Only available in ' jpayne@69: 'the\n' jpayne@69: ' bottom-most frame. This lets you jump back and execute code ' jpayne@69: 'again,\n' jpayne@69: ' or jump forward to skip code that you don’t want to run.\n' jpayne@69: '\n' jpayne@69: ' It should be noted that not all jumps are allowed – for ' jpayne@69: 'instance it\n' jpayne@69: ' is not possible to jump into the middle of a "for" loop or ' jpayne@69: 'out of a\n' jpayne@69: ' "finally" clause.\n' jpayne@69: '\n' jpayne@69: 'l(ist) [first[, last]]\n' jpayne@69: '\n' jpayne@69: ' List source code for the current file. Without arguments, ' jpayne@69: 'list 11\n' jpayne@69: ' lines around the current line or continue the previous ' jpayne@69: 'listing.\n' jpayne@69: ' With "." as argument, list 11 lines around the current line. ' jpayne@69: 'With\n' jpayne@69: ' one argument, list 11 lines around at that line. With two\n' jpayne@69: ' arguments, list the given range; if the second argument is ' jpayne@69: 'less\n' jpayne@69: ' than the first, it is interpreted as a count.\n' jpayne@69: '\n' jpayne@69: ' The current line in the current frame is indicated by "->". ' jpayne@69: 'If an\n' jpayne@69: ' exception is being debugged, the line where the exception ' jpayne@69: 'was\n' jpayne@69: ' originally raised or propagated is indicated by ">>", if it ' jpayne@69: 'differs\n' jpayne@69: ' from the current line.\n' jpayne@69: '\n' jpayne@69: ' New in version 3.2: The ">>" marker.\n' jpayne@69: '\n' jpayne@69: 'll | longlist\n' jpayne@69: '\n' jpayne@69: ' List all source code for the current function or frame.\n' jpayne@69: ' Interesting lines are marked as for "list".\n' jpayne@69: '\n' jpayne@69: ' New in version 3.2.\n' jpayne@69: '\n' jpayne@69: 'a(rgs)\n' jpayne@69: '\n' jpayne@69: ' Print the argument list of the current function.\n' jpayne@69: '\n' jpayne@69: 'p expression\n' jpayne@69: '\n' jpayne@69: ' Evaluate the *expression* in the current context and print ' jpayne@69: 'its\n' jpayne@69: ' value.\n' jpayne@69: '\n' jpayne@69: ' Note: "print()" can also be used, but is not a debugger ' jpayne@69: 'command —\n' jpayne@69: ' this executes the Python "print()" function.\n' jpayne@69: '\n' jpayne@69: 'pp expression\n' jpayne@69: '\n' jpayne@69: ' Like the "p" command, except the value of the expression is ' jpayne@69: 'pretty-\n' jpayne@69: ' printed using the "pprint" module.\n' jpayne@69: '\n' jpayne@69: 'whatis expression\n' jpayne@69: '\n' jpayne@69: ' Print the type of the *expression*.\n' jpayne@69: '\n' jpayne@69: 'source expression\n' jpayne@69: '\n' jpayne@69: ' Try to get source code for the given object and display it.\n' jpayne@69: '\n' jpayne@69: ' New in version 3.2.\n' jpayne@69: '\n' jpayne@69: 'display [expression]\n' jpayne@69: '\n' jpayne@69: ' Display the value of the expression if it changed, each time\n' jpayne@69: ' execution stops in the current frame.\n' jpayne@69: '\n' jpayne@69: ' Without expression, list all display expressions for the ' jpayne@69: 'current\n' jpayne@69: ' frame.\n' jpayne@69: '\n' jpayne@69: ' New in version 3.2.\n' jpayne@69: '\n' jpayne@69: 'undisplay [expression]\n' jpayne@69: '\n' jpayne@69: ' Do not display the expression any more in the current frame.\n' jpayne@69: ' Without expression, clear all display expressions for the ' jpayne@69: 'current\n' jpayne@69: ' frame.\n' jpayne@69: '\n' jpayne@69: ' New in version 3.2.\n' jpayne@69: '\n' jpayne@69: 'interact\n' jpayne@69: '\n' jpayne@69: ' Start an interactive interpreter (using the "code" module) ' jpayne@69: 'whose\n' jpayne@69: ' global namespace contains all the (global and local) names ' jpayne@69: 'found in\n' jpayne@69: ' the current scope.\n' jpayne@69: '\n' jpayne@69: ' New in version 3.2.\n' jpayne@69: '\n' jpayne@69: 'alias [name [command]]\n' jpayne@69: '\n' jpayne@69: ' Create an alias called *name* that executes *command*. The ' jpayne@69: 'command\n' jpayne@69: ' must *not* be enclosed in quotes. Replaceable parameters can ' jpayne@69: 'be\n' jpayne@69: ' indicated by "%1", "%2", and so on, while "%*" is replaced by ' jpayne@69: 'all\n' jpayne@69: ' the parameters. If no command is given, the current alias ' jpayne@69: 'for\n' jpayne@69: ' *name* is shown. If no arguments are given, all aliases are ' jpayne@69: 'listed.\n' jpayne@69: '\n' jpayne@69: ' Aliases may be nested and can contain anything that can be ' jpayne@69: 'legally\n' jpayne@69: ' typed at the pdb prompt. Note that internal pdb commands ' jpayne@69: '*can* be\n' jpayne@69: ' overridden by aliases. Such a command is then hidden until ' jpayne@69: 'the\n' jpayne@69: ' alias is removed. Aliasing is recursively applied to the ' jpayne@69: 'first\n' jpayne@69: ' word of the command line; all other words in the line are ' jpayne@69: 'left\n' jpayne@69: ' alone.\n' jpayne@69: '\n' jpayne@69: ' As an example, here are two useful aliases (especially when ' jpayne@69: 'placed\n' jpayne@69: ' in the ".pdbrc" file):\n' jpayne@69: '\n' jpayne@69: ' # Print instance variables (usage "pi classInst")\n' jpayne@69: ' alias pi for k in %1.__dict__.keys(): ' jpayne@69: 'print("%1.",k,"=",%1.__dict__[k])\n' jpayne@69: ' # Print instance variables in self\n' jpayne@69: ' alias ps pi self\n' jpayne@69: '\n' jpayne@69: 'unalias name\n' jpayne@69: '\n' jpayne@69: ' Delete the specified alias.\n' jpayne@69: '\n' jpayne@69: '! statement\n' jpayne@69: '\n' jpayne@69: ' Execute the (one-line) *statement* in the context of the ' jpayne@69: 'current\n' jpayne@69: ' stack frame. The exclamation point can be omitted unless the ' jpayne@69: 'first\n' jpayne@69: ' word of the statement resembles a debugger command. To set ' jpayne@69: 'a\n' jpayne@69: ' global variable, you can prefix the assignment command with ' jpayne@69: 'a\n' jpayne@69: ' "global" statement on the same line, e.g.:\n' jpayne@69: '\n' jpayne@69: " (Pdb) global list_options; list_options = ['-l']\n" jpayne@69: ' (Pdb)\n' jpayne@69: '\n' jpayne@69: 'run [args ...]\n' jpayne@69: 'restart [args ...]\n' jpayne@69: '\n' jpayne@69: ' Restart the debugged Python program. If an argument is ' jpayne@69: 'supplied,\n' jpayne@69: ' it is split with "shlex" and the result is used as the new\n' jpayne@69: ' "sys.argv". History, breakpoints, actions and debugger ' jpayne@69: 'options are\n' jpayne@69: ' preserved. "restart" is an alias for "run".\n' jpayne@69: '\n' jpayne@69: 'q(uit)\n' jpayne@69: '\n' jpayne@69: ' Quit from the debugger. The program being executed is ' jpayne@69: 'aborted.\n' jpayne@69: '\n' jpayne@69: 'debug code\n' jpayne@69: '\n' jpayne@69: ' Enter a recursive debugger that steps through the code ' jpayne@69: 'argument\n' jpayne@69: ' (which is an arbitrary expression or statement to be executed ' jpayne@69: 'in\n' jpayne@69: ' the current environment).\n' jpayne@69: '\n' jpayne@69: 'retval\n' jpayne@69: 'Print the return value for the last return of a function.\n' jpayne@69: '\n' jpayne@69: '-[ Footnotes ]-\n' jpayne@69: '\n' jpayne@69: '[1] Whether a frame is considered to originate in a certain ' jpayne@69: 'module\n' jpayne@69: ' is determined by the "__name__" in the frame globals.\n', jpayne@69: 'del': 'The "del" statement\n' jpayne@69: '*******************\n' jpayne@69: '\n' jpayne@69: ' del_stmt ::= "del" target_list\n' jpayne@69: '\n' jpayne@69: 'Deletion is recursively defined very similar to the way assignment ' jpayne@69: 'is\n' jpayne@69: 'defined. Rather than spelling it out in full details, here are some\n' jpayne@69: 'hints.\n' jpayne@69: '\n' jpayne@69: 'Deletion of a target list recursively deletes each target, from left\n' jpayne@69: 'to right.\n' jpayne@69: '\n' jpayne@69: 'Deletion of a name removes the binding of that name from the local ' jpayne@69: 'or\n' jpayne@69: 'global namespace, depending on whether the name occurs in a "global"\n' jpayne@69: 'statement in the same code block. If the name is unbound, a\n' jpayne@69: '"NameError" exception will be raised.\n' jpayne@69: '\n' jpayne@69: 'Deletion of attribute references, subscriptions and slicings is ' jpayne@69: 'passed\n' jpayne@69: 'to the primary object involved; deletion of a slicing is in general\n' jpayne@69: 'equivalent to assignment of an empty slice of the right type (but ' jpayne@69: 'even\n' jpayne@69: 'this is determined by the sliced object).\n' jpayne@69: '\n' jpayne@69: 'Changed in version 3.2: Previously it was illegal to delete a name\n' jpayne@69: 'from the local namespace if it occurs as a free variable in a nested\n' jpayne@69: 'block.\n', jpayne@69: 'dict': 'Dictionary displays\n' jpayne@69: '*******************\n' jpayne@69: '\n' jpayne@69: 'A dictionary display is a possibly empty series of key/datum pairs\n' jpayne@69: 'enclosed in curly braces:\n' jpayne@69: '\n' jpayne@69: ' dict_display ::= "{" [key_datum_list | dict_comprehension] ' jpayne@69: '"}"\n' jpayne@69: ' key_datum_list ::= key_datum ("," key_datum)* [","]\n' jpayne@69: ' key_datum ::= expression ":" expression | "**" or_expr\n' jpayne@69: ' dict_comprehension ::= expression ":" expression comp_for\n' jpayne@69: '\n' jpayne@69: 'A dictionary display yields a new dictionary object.\n' jpayne@69: '\n' jpayne@69: 'If a comma-separated sequence of key/datum pairs is given, they are\n' jpayne@69: 'evaluated from left to right to define the entries of the ' jpayne@69: 'dictionary:\n' jpayne@69: 'each key object is used as a key into the dictionary to store the\n' jpayne@69: 'corresponding datum. This means that you can specify the same key\n' jpayne@69: 'multiple times in the key/datum list, and the final dictionary’s ' jpayne@69: 'value\n' jpayne@69: 'for that key will be the last one given.\n' jpayne@69: '\n' jpayne@69: 'A double asterisk "**" denotes *dictionary unpacking*. Its operand\n' jpayne@69: 'must be a *mapping*. Each mapping item is added to the new\n' jpayne@69: 'dictionary. Later values replace values already set by earlier\n' jpayne@69: 'key/datum pairs and earlier dictionary unpackings.\n' jpayne@69: '\n' jpayne@69: 'New in version 3.5: Unpacking into dictionary displays, originally\n' jpayne@69: 'proposed by **PEP 448**.\n' jpayne@69: '\n' jpayne@69: 'A dict comprehension, in contrast to list and set comprehensions,\n' jpayne@69: 'needs two expressions separated with a colon followed by the usual\n' jpayne@69: '“for” and “if” clauses. When the comprehension is run, the ' jpayne@69: 'resulting\n' jpayne@69: 'key and value elements are inserted in the new dictionary in the ' jpayne@69: 'order\n' jpayne@69: 'they are produced.\n' jpayne@69: '\n' jpayne@69: 'Restrictions on the types of the key values are listed earlier in\n' jpayne@69: 'section The standard type hierarchy. (To summarize, the key type\n' jpayne@69: 'should be *hashable*, which excludes all mutable objects.) Clashes\n' jpayne@69: 'between duplicate keys are not detected; the last datum (textually\n' jpayne@69: 'rightmost in the display) stored for a given key value prevails.\n' jpayne@69: '\n' jpayne@69: 'Changed in version 3.8: Prior to Python 3.8, in dict ' jpayne@69: 'comprehensions,\n' jpayne@69: 'the evaluation order of key and value was not well-defined. In\n' jpayne@69: 'CPython, the value was evaluated before the key. Starting with ' jpayne@69: '3.8,\n' jpayne@69: 'the key is evaluated before the value, as proposed by **PEP 572**.\n', jpayne@69: 'dynamic-features': 'Interaction with dynamic features\n' jpayne@69: '*********************************\n' jpayne@69: '\n' jpayne@69: 'Name resolution of free variables occurs at runtime, not ' jpayne@69: 'at compile\n' jpayne@69: 'time. This means that the following code will print 42:\n' jpayne@69: '\n' jpayne@69: ' i = 10\n' jpayne@69: ' def f():\n' jpayne@69: ' print(i)\n' jpayne@69: ' i = 42\n' jpayne@69: ' f()\n' jpayne@69: '\n' jpayne@69: 'The "eval()" and "exec()" functions do not have access ' jpayne@69: 'to the full\n' jpayne@69: 'environment for resolving names. Names may be resolved ' jpayne@69: 'in the local\n' jpayne@69: 'and global namespaces of the caller. Free variables are ' jpayne@69: 'not resolved\n' jpayne@69: 'in the nearest enclosing namespace, but in the global ' jpayne@69: 'namespace. [1]\n' jpayne@69: 'The "exec()" and "eval()" functions have optional ' jpayne@69: 'arguments to\n' jpayne@69: 'override the global and local namespace. If only one ' jpayne@69: 'namespace is\n' jpayne@69: 'specified, it is used for both.\n', jpayne@69: 'else': 'The "if" statement\n' jpayne@69: '******************\n' jpayne@69: '\n' jpayne@69: 'The "if" statement is used for conditional execution:\n' jpayne@69: '\n' jpayne@69: ' if_stmt ::= "if" expression ":" suite\n' jpayne@69: ' ("elif" expression ":" suite)*\n' jpayne@69: ' ["else" ":" suite]\n' jpayne@69: '\n' jpayne@69: 'It selects exactly one of the suites by evaluating the expressions ' jpayne@69: 'one\n' jpayne@69: 'by one until one is found to be true (see section Boolean ' jpayne@69: 'operations\n' jpayne@69: 'for the definition of true and false); then that suite is executed\n' jpayne@69: '(and no other part of the "if" statement is executed or evaluated).\n' jpayne@69: 'If all expressions are false, the suite of the "else" clause, if\n' jpayne@69: 'present, is executed.\n', jpayne@69: 'exceptions': 'Exceptions\n' jpayne@69: '**********\n' jpayne@69: '\n' jpayne@69: 'Exceptions are a means of breaking out of the normal flow of ' jpayne@69: 'control\n' jpayne@69: 'of a code block in order to handle errors or other ' jpayne@69: 'exceptional\n' jpayne@69: 'conditions. An exception is *raised* at the point where the ' jpayne@69: 'error is\n' jpayne@69: 'detected; it may be *handled* by the surrounding code block or ' jpayne@69: 'by any\n' jpayne@69: 'code block that directly or indirectly invoked the code block ' jpayne@69: 'where\n' jpayne@69: 'the error occurred.\n' jpayne@69: '\n' jpayne@69: 'The Python interpreter raises an exception when it detects a ' jpayne@69: 'run-time\n' jpayne@69: 'error (such as division by zero). A Python program can also\n' jpayne@69: 'explicitly raise an exception with the "raise" statement. ' jpayne@69: 'Exception\n' jpayne@69: 'handlers are specified with the "try" … "except" statement. ' jpayne@69: 'The\n' jpayne@69: '"finally" clause of such a statement can be used to specify ' jpayne@69: 'cleanup\n' jpayne@69: 'code which does not handle the exception, but is executed ' jpayne@69: 'whether an\n' jpayne@69: 'exception occurred or not in the preceding code.\n' jpayne@69: '\n' jpayne@69: 'Python uses the “termination” model of error handling: an ' jpayne@69: 'exception\n' jpayne@69: 'handler can find out what happened and continue execution at ' jpayne@69: 'an outer\n' jpayne@69: 'level, but it cannot repair the cause of the error and retry ' jpayne@69: 'the\n' jpayne@69: 'failing operation (except by re-entering the offending piece ' jpayne@69: 'of code\n' jpayne@69: 'from the top).\n' jpayne@69: '\n' jpayne@69: 'When an exception is not handled at all, the interpreter ' jpayne@69: 'terminates\n' jpayne@69: 'execution of the program, or returns to its interactive main ' jpayne@69: 'loop. In\n' jpayne@69: 'either case, it prints a stack traceback, except when the ' jpayne@69: 'exception is\n' jpayne@69: '"SystemExit".\n' jpayne@69: '\n' jpayne@69: 'Exceptions are identified by class instances. The "except" ' jpayne@69: 'clause is\n' jpayne@69: 'selected depending on the class of the instance: it must ' jpayne@69: 'reference the\n' jpayne@69: 'class of the instance or a base class thereof. The instance ' jpayne@69: 'can be\n' jpayne@69: 'received by the handler and can carry additional information ' jpayne@69: 'about the\n' jpayne@69: 'exceptional condition.\n' jpayne@69: '\n' jpayne@69: 'Note: Exception messages are not part of the Python API. ' jpayne@69: 'Their\n' jpayne@69: ' contents may change from one version of Python to the next ' jpayne@69: 'without\n' jpayne@69: ' warning and should not be relied on by code which will run ' jpayne@69: 'under\n' jpayne@69: ' multiple versions of the interpreter.\n' jpayne@69: '\n' jpayne@69: 'See also the description of the "try" statement in section The ' jpayne@69: 'try\n' jpayne@69: 'statement and "raise" statement in section The raise ' jpayne@69: 'statement.\n' jpayne@69: '\n' jpayne@69: '-[ Footnotes ]-\n' jpayne@69: '\n' jpayne@69: '[1] This limitation occurs because the code that is executed ' jpayne@69: 'by\n' jpayne@69: ' these operations is not available at the time the module ' jpayne@69: 'is\n' jpayne@69: ' compiled.\n', jpayne@69: 'execmodel': 'Execution model\n' jpayne@69: '***************\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Structure of a program\n' jpayne@69: '======================\n' jpayne@69: '\n' jpayne@69: 'A Python program is constructed from code blocks. A *block* is ' jpayne@69: 'a piece\n' jpayne@69: 'of Python program text that is executed as a unit. The ' jpayne@69: 'following are\n' jpayne@69: 'blocks: a module, a function body, and a class definition. ' jpayne@69: 'Each\n' jpayne@69: 'command typed interactively is a block. A script file (a file ' jpayne@69: 'given\n' jpayne@69: 'as standard input to the interpreter or specified as a command ' jpayne@69: 'line\n' jpayne@69: 'argument to the interpreter) is a code block. A script command ' jpayne@69: '(a\n' jpayne@69: 'command specified on the interpreter command line with the ' jpayne@69: '"-c"\n' jpayne@69: 'option) is a code block. The string argument passed to the ' jpayne@69: 'built-in\n' jpayne@69: 'functions "eval()" and "exec()" is a code block.\n' jpayne@69: '\n' jpayne@69: 'A code block is executed in an *execution frame*. A frame ' jpayne@69: 'contains\n' jpayne@69: 'some administrative information (used for debugging) and ' jpayne@69: 'determines\n' jpayne@69: 'where and how execution continues after the code block’s ' jpayne@69: 'execution has\n' jpayne@69: 'completed.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Naming and binding\n' jpayne@69: '==================\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Binding of names\n' jpayne@69: '----------------\n' jpayne@69: '\n' jpayne@69: '*Names* refer to objects. Names are introduced by name ' jpayne@69: 'binding\n' jpayne@69: 'operations.\n' jpayne@69: '\n' jpayne@69: 'The following constructs bind names: formal parameters to ' jpayne@69: 'functions,\n' jpayne@69: '"import" statements, class and function definitions (these bind ' jpayne@69: 'the\n' jpayne@69: 'class or function name in the defining block), and targets that ' jpayne@69: 'are\n' jpayne@69: 'identifiers if occurring in an assignment, "for" loop header, ' jpayne@69: 'or after\n' jpayne@69: '"as" in a "with" statement or "except" clause. The "import" ' jpayne@69: 'statement\n' jpayne@69: 'of the form "from ... import *" binds all names defined in the\n' jpayne@69: 'imported module, except those beginning with an underscore. ' jpayne@69: 'This form\n' jpayne@69: 'may only be used at the module level.\n' jpayne@69: '\n' jpayne@69: 'A target occurring in a "del" statement is also considered ' jpayne@69: 'bound for\n' jpayne@69: 'this purpose (though the actual semantics are to unbind the ' jpayne@69: 'name).\n' jpayne@69: '\n' jpayne@69: 'Each assignment or import statement occurs within a block ' jpayne@69: 'defined by a\n' jpayne@69: 'class or function definition or at the module level (the ' jpayne@69: 'top-level\n' jpayne@69: 'code block).\n' jpayne@69: '\n' jpayne@69: 'If a name is bound in a block, it is a local variable of that ' jpayne@69: 'block,\n' jpayne@69: 'unless declared as "nonlocal" or "global". If a name is bound ' jpayne@69: 'at the\n' jpayne@69: 'module level, it is a global variable. (The variables of the ' jpayne@69: 'module\n' jpayne@69: 'code block are local and global.) If a variable is used in a ' jpayne@69: 'code\n' jpayne@69: 'block but not defined there, it is a *free variable*.\n' jpayne@69: '\n' jpayne@69: 'Each occurrence of a name in the program text refers to the ' jpayne@69: '*binding*\n' jpayne@69: 'of that name established by the following name resolution ' jpayne@69: 'rules.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Resolution of names\n' jpayne@69: '-------------------\n' jpayne@69: '\n' jpayne@69: 'A *scope* defines the visibility of a name within a block. If ' jpayne@69: 'a local\n' jpayne@69: 'variable is defined in a block, its scope includes that block. ' jpayne@69: 'If the\n' jpayne@69: 'definition occurs in a function block, the scope extends to any ' jpayne@69: 'blocks\n' jpayne@69: 'contained within the defining one, unless a contained block ' jpayne@69: 'introduces\n' jpayne@69: 'a different binding for the name.\n' jpayne@69: '\n' jpayne@69: 'When a name is used in a code block, it is resolved using the ' jpayne@69: 'nearest\n' jpayne@69: 'enclosing scope. The set of all such scopes visible to a code ' jpayne@69: 'block\n' jpayne@69: 'is called the block’s *environment*.\n' jpayne@69: '\n' jpayne@69: 'When a name is not found at all, a "NameError" exception is ' jpayne@69: 'raised. If\n' jpayne@69: 'the current scope is a function scope, and the name refers to a ' jpayne@69: 'local\n' jpayne@69: 'variable that has not yet been bound to a value at the point ' jpayne@69: 'where the\n' jpayne@69: 'name is used, an "UnboundLocalError" exception is raised.\n' jpayne@69: '"UnboundLocalError" is a subclass of "NameError".\n' jpayne@69: '\n' jpayne@69: 'If a name binding operation occurs anywhere within a code ' jpayne@69: 'block, all\n' jpayne@69: 'uses of the name within the block are treated as references to ' jpayne@69: 'the\n' jpayne@69: 'current block. This can lead to errors when a name is used ' jpayne@69: 'within a\n' jpayne@69: 'block before it is bound. This rule is subtle. Python lacks\n' jpayne@69: 'declarations and allows name binding operations to occur ' jpayne@69: 'anywhere\n' jpayne@69: 'within a code block. The local variables of a code block can ' jpayne@69: 'be\n' jpayne@69: 'determined by scanning the entire text of the block for name ' jpayne@69: 'binding\n' jpayne@69: 'operations.\n' jpayne@69: '\n' jpayne@69: 'If the "global" statement occurs within a block, all uses of ' jpayne@69: 'the name\n' jpayne@69: 'specified in the statement refer to the binding of that name in ' jpayne@69: 'the\n' jpayne@69: 'top-level namespace. Names are resolved in the top-level ' jpayne@69: 'namespace by\n' jpayne@69: 'searching the global namespace, i.e. the namespace of the ' jpayne@69: 'module\n' jpayne@69: 'containing the code block, and the builtins namespace, the ' jpayne@69: 'namespace\n' jpayne@69: 'of the module "builtins". The global namespace is searched ' jpayne@69: 'first. If\n' jpayne@69: 'the name is not found there, the builtins namespace is ' jpayne@69: 'searched. The\n' jpayne@69: '"global" statement must precede all uses of the name.\n' jpayne@69: '\n' jpayne@69: 'The "global" statement has the same scope as a name binding ' jpayne@69: 'operation\n' jpayne@69: 'in the same block. If the nearest enclosing scope for a free ' jpayne@69: 'variable\n' jpayne@69: 'contains a global statement, the free variable is treated as a ' jpayne@69: 'global.\n' jpayne@69: '\n' jpayne@69: 'The "nonlocal" statement causes corresponding names to refer ' jpayne@69: 'to\n' jpayne@69: 'previously bound variables in the nearest enclosing function ' jpayne@69: 'scope.\n' jpayne@69: '"SyntaxError" is raised at compile time if the given name does ' jpayne@69: 'not\n' jpayne@69: 'exist in any enclosing function scope.\n' jpayne@69: '\n' jpayne@69: 'The namespace for a module is automatically created the first ' jpayne@69: 'time a\n' jpayne@69: 'module is imported. The main module for a script is always ' jpayne@69: 'called\n' jpayne@69: '"__main__".\n' jpayne@69: '\n' jpayne@69: 'Class definition blocks and arguments to "exec()" and "eval()" ' jpayne@69: 'are\n' jpayne@69: 'special in the context of name resolution. A class definition ' jpayne@69: 'is an\n' jpayne@69: 'executable statement that may use and define names. These ' jpayne@69: 'references\n' jpayne@69: 'follow the normal rules for name resolution with an exception ' jpayne@69: 'that\n' jpayne@69: 'unbound local variables are looked up in the global namespace. ' jpayne@69: 'The\n' jpayne@69: 'namespace of the class definition becomes the attribute ' jpayne@69: 'dictionary of\n' jpayne@69: 'the class. The scope of names defined in a class block is ' jpayne@69: 'limited to\n' jpayne@69: 'the class block; it does not extend to the code blocks of ' jpayne@69: 'methods –\n' jpayne@69: 'this includes comprehensions and generator expressions since ' jpayne@69: 'they are\n' jpayne@69: 'implemented using a function scope. This means that the ' jpayne@69: 'following\n' jpayne@69: 'will fail:\n' jpayne@69: '\n' jpayne@69: ' class A:\n' jpayne@69: ' a = 42\n' jpayne@69: ' b = list(a + i for i in range(10))\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Builtins and restricted execution\n' jpayne@69: '---------------------------------\n' jpayne@69: '\n' jpayne@69: '**CPython implementation detail:** Users should not touch\n' jpayne@69: '"__builtins__"; it is strictly an implementation detail. ' jpayne@69: 'Users\n' jpayne@69: 'wanting to override values in the builtins namespace should ' jpayne@69: '"import"\n' jpayne@69: 'the "builtins" module and modify its attributes appropriately.\n' jpayne@69: '\n' jpayne@69: 'The builtins namespace associated with the execution of a code ' jpayne@69: 'block\n' jpayne@69: 'is actually found by looking up the name "__builtins__" in its ' jpayne@69: 'global\n' jpayne@69: 'namespace; this should be a dictionary or a module (in the ' jpayne@69: 'latter case\n' jpayne@69: 'the module’s dictionary is used). By default, when in the ' jpayne@69: '"__main__"\n' jpayne@69: 'module, "__builtins__" is the built-in module "builtins"; when ' jpayne@69: 'in any\n' jpayne@69: 'other module, "__builtins__" is an alias for the dictionary of ' jpayne@69: 'the\n' jpayne@69: '"builtins" module itself.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Interaction with dynamic features\n' jpayne@69: '---------------------------------\n' jpayne@69: '\n' jpayne@69: 'Name resolution of free variables occurs at runtime, not at ' jpayne@69: 'compile\n' jpayne@69: 'time. This means that the following code will print 42:\n' jpayne@69: '\n' jpayne@69: ' i = 10\n' jpayne@69: ' def f():\n' jpayne@69: ' print(i)\n' jpayne@69: ' i = 42\n' jpayne@69: ' f()\n' jpayne@69: '\n' jpayne@69: 'The "eval()" and "exec()" functions do not have access to the ' jpayne@69: 'full\n' jpayne@69: 'environment for resolving names. Names may be resolved in the ' jpayne@69: 'local\n' jpayne@69: 'and global namespaces of the caller. Free variables are not ' jpayne@69: 'resolved\n' jpayne@69: 'in the nearest enclosing namespace, but in the global ' jpayne@69: 'namespace. [1]\n' jpayne@69: 'The "exec()" and "eval()" functions have optional arguments to\n' jpayne@69: 'override the global and local namespace. If only one namespace ' jpayne@69: 'is\n' jpayne@69: 'specified, it is used for both.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Exceptions\n' jpayne@69: '==========\n' jpayne@69: '\n' jpayne@69: 'Exceptions are a means of breaking out of the normal flow of ' jpayne@69: 'control\n' jpayne@69: 'of a code block in order to handle errors or other exceptional\n' jpayne@69: 'conditions. An exception is *raised* at the point where the ' jpayne@69: 'error is\n' jpayne@69: 'detected; it may be *handled* by the surrounding code block or ' jpayne@69: 'by any\n' jpayne@69: 'code block that directly or indirectly invoked the code block ' jpayne@69: 'where\n' jpayne@69: 'the error occurred.\n' jpayne@69: '\n' jpayne@69: 'The Python interpreter raises an exception when it detects a ' jpayne@69: 'run-time\n' jpayne@69: 'error (such as division by zero). A Python program can also\n' jpayne@69: 'explicitly raise an exception with the "raise" statement. ' jpayne@69: 'Exception\n' jpayne@69: 'handlers are specified with the "try" … "except" statement. ' jpayne@69: 'The\n' jpayne@69: '"finally" clause of such a statement can be used to specify ' jpayne@69: 'cleanup\n' jpayne@69: 'code which does not handle the exception, but is executed ' jpayne@69: 'whether an\n' jpayne@69: 'exception occurred or not in the preceding code.\n' jpayne@69: '\n' jpayne@69: 'Python uses the “termination” model of error handling: an ' jpayne@69: 'exception\n' jpayne@69: 'handler can find out what happened and continue execution at an ' jpayne@69: 'outer\n' jpayne@69: 'level, but it cannot repair the cause of the error and retry ' jpayne@69: 'the\n' jpayne@69: 'failing operation (except by re-entering the offending piece of ' jpayne@69: 'code\n' jpayne@69: 'from the top).\n' jpayne@69: '\n' jpayne@69: 'When an exception is not handled at all, the interpreter ' jpayne@69: 'terminates\n' jpayne@69: 'execution of the program, or returns to its interactive main ' jpayne@69: 'loop. In\n' jpayne@69: 'either case, it prints a stack traceback, except when the ' jpayne@69: 'exception is\n' jpayne@69: '"SystemExit".\n' jpayne@69: '\n' jpayne@69: 'Exceptions are identified by class instances. The "except" ' jpayne@69: 'clause is\n' jpayne@69: 'selected depending on the class of the instance: it must ' jpayne@69: 'reference the\n' jpayne@69: 'class of the instance or a base class thereof. The instance ' jpayne@69: 'can be\n' jpayne@69: 'received by the handler and can carry additional information ' jpayne@69: 'about the\n' jpayne@69: 'exceptional condition.\n' jpayne@69: '\n' jpayne@69: 'Note: Exception messages are not part of the Python API. ' jpayne@69: 'Their\n' jpayne@69: ' contents may change from one version of Python to the next ' jpayne@69: 'without\n' jpayne@69: ' warning and should not be relied on by code which will run ' jpayne@69: 'under\n' jpayne@69: ' multiple versions of the interpreter.\n' jpayne@69: '\n' jpayne@69: 'See also the description of the "try" statement in section The ' jpayne@69: 'try\n' jpayne@69: 'statement and "raise" statement in section The raise ' jpayne@69: 'statement.\n' jpayne@69: '\n' jpayne@69: '-[ Footnotes ]-\n' jpayne@69: '\n' jpayne@69: '[1] This limitation occurs because the code that is executed ' jpayne@69: 'by\n' jpayne@69: ' these operations is not available at the time the module ' jpayne@69: 'is\n' jpayne@69: ' compiled.\n', jpayne@69: 'exprlists': 'Expression lists\n' jpayne@69: '****************\n' jpayne@69: '\n' jpayne@69: ' expression_list ::= expression ("," expression)* [","]\n' jpayne@69: ' starred_list ::= starred_item ("," starred_item)* ' jpayne@69: '[","]\n' jpayne@69: ' starred_expression ::= expression | (starred_item ",")* ' jpayne@69: '[starred_item]\n' jpayne@69: ' starred_item ::= expression | "*" or_expr\n' jpayne@69: '\n' jpayne@69: 'Except when part of a list or set display, an expression list\n' jpayne@69: 'containing at least one comma yields a tuple. The length of ' jpayne@69: 'the tuple\n' jpayne@69: 'is the number of expressions in the list. The expressions are\n' jpayne@69: 'evaluated from left to right.\n' jpayne@69: '\n' jpayne@69: 'An asterisk "*" denotes *iterable unpacking*. Its operand must ' jpayne@69: 'be an\n' jpayne@69: '*iterable*. The iterable is expanded into a sequence of items, ' jpayne@69: 'which\n' jpayne@69: 'are included in the new tuple, list, or set, at the site of ' jpayne@69: 'the\n' jpayne@69: 'unpacking.\n' jpayne@69: '\n' jpayne@69: 'New in version 3.5: Iterable unpacking in expression lists, ' jpayne@69: 'originally\n' jpayne@69: 'proposed by **PEP 448**.\n' jpayne@69: '\n' jpayne@69: 'The trailing comma is required only to create a single tuple ' jpayne@69: '(a.k.a. a\n' jpayne@69: '*singleton*); it is optional in all other cases. A single ' jpayne@69: 'expression\n' jpayne@69: 'without a trailing comma doesn’t create a tuple, but rather ' jpayne@69: 'yields the\n' jpayne@69: 'value of that expression. (To create an empty tuple, use an ' jpayne@69: 'empty pair\n' jpayne@69: 'of parentheses: "()".)\n', jpayne@69: 'floating': 'Floating point literals\n' jpayne@69: '***********************\n' jpayne@69: '\n' jpayne@69: 'Floating point literals are described by the following lexical\n' jpayne@69: 'definitions:\n' jpayne@69: '\n' jpayne@69: ' floatnumber ::= pointfloat | exponentfloat\n' jpayne@69: ' pointfloat ::= [digitpart] fraction | digitpart "."\n' jpayne@69: ' exponentfloat ::= (digitpart | pointfloat) exponent\n' jpayne@69: ' digitpart ::= digit (["_"] digit)*\n' jpayne@69: ' fraction ::= "." digitpart\n' jpayne@69: ' exponent ::= ("e" | "E") ["+" | "-"] digitpart\n' jpayne@69: '\n' jpayne@69: 'Note that the integer and exponent parts are always interpreted ' jpayne@69: 'using\n' jpayne@69: 'radix 10. For example, "077e010" is legal, and denotes the same ' jpayne@69: 'number\n' jpayne@69: 'as "77e10". The allowed range of floating point literals is\n' jpayne@69: 'implementation-dependent. As in integer literals, underscores ' jpayne@69: 'are\n' jpayne@69: 'supported for digit grouping.\n' jpayne@69: '\n' jpayne@69: 'Some examples of floating point literals:\n' jpayne@69: '\n' jpayne@69: ' 3.14 10. .001 1e100 3.14e-10 0e0 ' jpayne@69: '3.14_15_93\n' jpayne@69: '\n' jpayne@69: 'Changed in version 3.6: Underscores are now allowed for ' jpayne@69: 'grouping\n' jpayne@69: 'purposes in literals.\n', jpayne@69: 'for': 'The "for" statement\n' jpayne@69: '*******************\n' jpayne@69: '\n' jpayne@69: 'The "for" statement is used to iterate over the elements of a ' jpayne@69: 'sequence\n' jpayne@69: '(such as a string, tuple or list) or other iterable object:\n' jpayne@69: '\n' jpayne@69: ' for_stmt ::= "for" target_list "in" expression_list ":" suite\n' jpayne@69: ' ["else" ":" suite]\n' jpayne@69: '\n' jpayne@69: 'The expression list is evaluated once; it should yield an iterable\n' jpayne@69: 'object. An iterator is created for the result of the\n' jpayne@69: '"expression_list". The suite is then executed once for each item\n' jpayne@69: 'provided by the iterator, in the order returned by the iterator. ' jpayne@69: 'Each\n' jpayne@69: 'item in turn is assigned to the target list using the standard rules\n' jpayne@69: 'for assignments (see Assignment statements), and then the suite is\n' jpayne@69: 'executed. When the items are exhausted (which is immediately when ' jpayne@69: 'the\n' jpayne@69: 'sequence is empty or an iterator raises a "StopIteration" ' jpayne@69: 'exception),\n' jpayne@69: 'the suite in the "else" clause, if present, is executed, and the ' jpayne@69: 'loop\n' jpayne@69: 'terminates.\n' jpayne@69: '\n' jpayne@69: 'A "break" statement executed in the first suite terminates the loop\n' jpayne@69: 'without executing the "else" clause’s suite. A "continue" statement\n' jpayne@69: 'executed in the first suite skips the rest of the suite and ' jpayne@69: 'continues\n' jpayne@69: 'with the next item, or with the "else" clause if there is no next\n' jpayne@69: 'item.\n' jpayne@69: '\n' jpayne@69: 'The for-loop makes assignments to the variables in the target list.\n' jpayne@69: 'This overwrites all previous assignments to those variables ' jpayne@69: 'including\n' jpayne@69: 'those made in the suite of the for-loop:\n' jpayne@69: '\n' jpayne@69: ' for i in range(10):\n' jpayne@69: ' print(i)\n' jpayne@69: ' i = 5 # this will not affect the for-loop\n' jpayne@69: ' # because i will be overwritten with the ' jpayne@69: 'next\n' jpayne@69: ' # index in the range\n' jpayne@69: '\n' jpayne@69: 'Names in the target list are not deleted when the loop is finished,\n' jpayne@69: 'but if the sequence is empty, they will not have been assigned to at\n' jpayne@69: 'all by the loop. Hint: the built-in function "range()" returns an\n' jpayne@69: 'iterator of integers suitable to emulate the effect of Pascal’s "for ' jpayne@69: 'i\n' jpayne@69: ':= a to b do"; e.g., "list(range(3))" returns the list "[0, 1, 2]".\n' jpayne@69: '\n' jpayne@69: 'Note: There is a subtlety when the sequence is being modified by the\n' jpayne@69: ' loop (this can only occur for mutable sequences, e.g. lists). An\n' jpayne@69: ' internal counter is used to keep track of which item is used next,\n' jpayne@69: ' and this is incremented on each iteration. When this counter has\n' jpayne@69: ' reached the length of the sequence the loop terminates. This ' jpayne@69: 'means\n' jpayne@69: ' that if the suite deletes the current (or a previous) item from ' jpayne@69: 'the\n' jpayne@69: ' sequence, the next item will be skipped (since it gets the index ' jpayne@69: 'of\n' jpayne@69: ' the current item which has already been treated). Likewise, if ' jpayne@69: 'the\n' jpayne@69: ' suite inserts an item in the sequence before the current item, the\n' jpayne@69: ' current item will be treated again the next time through the loop.\n' jpayne@69: ' This can lead to nasty bugs that can be avoided by making a\n' jpayne@69: ' temporary copy using a slice of the whole sequence, e.g.,\n' jpayne@69: '\n' jpayne@69: ' for x in a[:]:\n' jpayne@69: ' if x < 0: a.remove(x)\n', jpayne@69: 'formatstrings': 'Format String Syntax\n' jpayne@69: '********************\n' jpayne@69: '\n' jpayne@69: 'The "str.format()" method and the "Formatter" class share ' jpayne@69: 'the same\n' jpayne@69: 'syntax for format strings (although in the case of ' jpayne@69: '"Formatter",\n' jpayne@69: 'subclasses can define their own format string syntax). The ' jpayne@69: 'syntax is\n' jpayne@69: 'related to that of formatted string literals, but there ' jpayne@69: 'are\n' jpayne@69: 'differences.\n' jpayne@69: '\n' jpayne@69: 'Format strings contain “replacement fields” surrounded by ' jpayne@69: 'curly braces\n' jpayne@69: '"{}". Anything that is not contained in braces is ' jpayne@69: 'considered literal\n' jpayne@69: 'text, which is copied unchanged to the output. If you need ' jpayne@69: 'to include\n' jpayne@69: 'a brace character in the literal text, it can be escaped by ' jpayne@69: 'doubling:\n' jpayne@69: '"{{" and "}}".\n' jpayne@69: '\n' jpayne@69: 'The grammar for a replacement field is as follows:\n' jpayne@69: '\n' jpayne@69: ' replacement_field ::= "{" [field_name] ["!" ' jpayne@69: 'conversion] [":" format_spec] "}"\n' jpayne@69: ' field_name ::= arg_name ("." attribute_name | ' jpayne@69: '"[" element_index "]")*\n' jpayne@69: ' arg_name ::= [identifier | digit+]\n' jpayne@69: ' attribute_name ::= identifier\n' jpayne@69: ' element_index ::= digit+ | index_string\n' jpayne@69: ' index_string ::= +\n' jpayne@69: ' conversion ::= "r" | "s" | "a"\n' jpayne@69: ' format_spec ::= \n' jpayne@69: '\n' jpayne@69: 'In less formal terms, the replacement field can start with ' jpayne@69: 'a\n' jpayne@69: '*field_name* that specifies the object whose value is to be ' jpayne@69: 'formatted\n' jpayne@69: 'and inserted into the output instead of the replacement ' jpayne@69: 'field. The\n' jpayne@69: '*field_name* is optionally followed by a *conversion* ' jpayne@69: 'field, which is\n' jpayne@69: 'preceded by an exclamation point "\'!\'", and a ' jpayne@69: '*format_spec*, which is\n' jpayne@69: 'preceded by a colon "\':\'". These specify a non-default ' jpayne@69: 'format for the\n' jpayne@69: 'replacement value.\n' jpayne@69: '\n' jpayne@69: 'See also the Format Specification Mini-Language section.\n' jpayne@69: '\n' jpayne@69: 'The *field_name* itself begins with an *arg_name* that is ' jpayne@69: 'either a\n' jpayne@69: 'number or a keyword. If it’s a number, it refers to a ' jpayne@69: 'positional\n' jpayne@69: 'argument, and if it’s a keyword, it refers to a named ' jpayne@69: 'keyword\n' jpayne@69: 'argument. If the numerical arg_names in a format string ' jpayne@69: 'are 0, 1, 2,\n' jpayne@69: '… in sequence, they can all be omitted (not just some) and ' jpayne@69: 'the numbers\n' jpayne@69: '0, 1, 2, … will be automatically inserted in that order. ' jpayne@69: 'Because\n' jpayne@69: '*arg_name* is not quote-delimited, it is not possible to ' jpayne@69: 'specify\n' jpayne@69: 'arbitrary dictionary keys (e.g., the strings "\'10\'" or ' jpayne@69: '"\':-]\'") within\n' jpayne@69: 'a format string. The *arg_name* can be followed by any ' jpayne@69: 'number of index\n' jpayne@69: 'or attribute expressions. An expression of the form ' jpayne@69: '"\'.name\'" selects\n' jpayne@69: 'the named attribute using "getattr()", while an expression ' jpayne@69: 'of the form\n' jpayne@69: '"\'[index]\'" does an index lookup using "__getitem__()".\n' jpayne@69: '\n' jpayne@69: 'Changed in version 3.1: The positional argument specifiers ' jpayne@69: 'can be\n' jpayne@69: 'omitted for "str.format()", so "\'{} {}\'.format(a, b)" is ' jpayne@69: 'equivalent to\n' jpayne@69: '"\'{0} {1}\'.format(a, b)".\n' jpayne@69: '\n' jpayne@69: 'Changed in version 3.4: The positional argument specifiers ' jpayne@69: 'can be\n' jpayne@69: 'omitted for "Formatter".\n' jpayne@69: '\n' jpayne@69: 'Some simple format string examples:\n' jpayne@69: '\n' jpayne@69: ' "First, thou shalt count to {0}" # References first ' jpayne@69: 'positional argument\n' jpayne@69: ' "Bring me a {}" # Implicitly ' jpayne@69: 'references the first positional argument\n' jpayne@69: ' "From {} to {}" # Same as "From {0} to ' jpayne@69: '{1}"\n' jpayne@69: ' "My quest is {name}" # References keyword ' jpayne@69: "argument 'name'\n" jpayne@69: ' "Weight in tons {0.weight}" # \'weight\' attribute ' jpayne@69: 'of first positional arg\n' jpayne@69: ' "Units destroyed: {players[0]}" # First element of ' jpayne@69: "keyword argument 'players'.\n" jpayne@69: '\n' jpayne@69: 'The *conversion* field causes a type coercion before ' jpayne@69: 'formatting.\n' jpayne@69: 'Normally, the job of formatting a value is done by the ' jpayne@69: '"__format__()"\n' jpayne@69: 'method of the value itself. However, in some cases it is ' jpayne@69: 'desirable to\n' jpayne@69: 'force a type to be formatted as a string, overriding its ' jpayne@69: 'own\n' jpayne@69: 'definition of formatting. By converting the value to a ' jpayne@69: 'string before\n' jpayne@69: 'calling "__format__()", the normal formatting logic is ' jpayne@69: 'bypassed.\n' jpayne@69: '\n' jpayne@69: 'Three conversion flags are currently supported: "\'!s\'" ' jpayne@69: 'which calls\n' jpayne@69: '"str()" on the value, "\'!r\'" which calls "repr()" and ' jpayne@69: '"\'!a\'" which\n' jpayne@69: 'calls "ascii()".\n' jpayne@69: '\n' jpayne@69: 'Some examples:\n' jpayne@69: '\n' jpayne@69: ' "Harold\'s a clever {0!s}" # Calls str() on the ' jpayne@69: 'argument first\n' jpayne@69: ' "Bring out the holy {name!r}" # Calls repr() on the ' jpayne@69: 'argument first\n' jpayne@69: ' "More {!a}" # Calls ascii() on the ' jpayne@69: 'argument first\n' jpayne@69: '\n' jpayne@69: 'The *format_spec* field contains a specification of how the ' jpayne@69: 'value\n' jpayne@69: 'should be presented, including such details as field width, ' jpayne@69: 'alignment,\n' jpayne@69: 'padding, decimal precision and so on. Each value type can ' jpayne@69: 'define its\n' jpayne@69: 'own “formatting mini-language” or interpretation of the ' jpayne@69: '*format_spec*.\n' jpayne@69: '\n' jpayne@69: 'Most built-in types support a common formatting ' jpayne@69: 'mini-language, which\n' jpayne@69: 'is described in the next section.\n' jpayne@69: '\n' jpayne@69: 'A *format_spec* field can also include nested replacement ' jpayne@69: 'fields\n' jpayne@69: 'within it. These nested replacement fields may contain a ' jpayne@69: 'field name,\n' jpayne@69: 'conversion flag and format specification, but deeper ' jpayne@69: 'nesting is not\n' jpayne@69: 'allowed. The replacement fields within the format_spec ' jpayne@69: 'are\n' jpayne@69: 'substituted before the *format_spec* string is interpreted. ' jpayne@69: 'This\n' jpayne@69: 'allows the formatting of a value to be dynamically ' jpayne@69: 'specified.\n' jpayne@69: '\n' jpayne@69: 'See the Format examples section for some examples.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Format Specification Mini-Language\n' jpayne@69: '==================================\n' jpayne@69: '\n' jpayne@69: '“Format specifications” are used within replacement fields ' jpayne@69: 'contained\n' jpayne@69: 'within a format string to define how individual values are ' jpayne@69: 'presented\n' jpayne@69: '(see Format String Syntax and Formatted string literals). ' jpayne@69: 'They can\n' jpayne@69: 'also be passed directly to the built-in "format()" ' jpayne@69: 'function. Each\n' jpayne@69: 'formattable type may define how the format specification is ' jpayne@69: 'to be\n' jpayne@69: 'interpreted.\n' jpayne@69: '\n' jpayne@69: 'Most built-in types implement the following options for ' jpayne@69: 'format\n' jpayne@69: 'specifications, although some of the formatting options are ' jpayne@69: 'only\n' jpayne@69: 'supported by the numeric types.\n' jpayne@69: '\n' jpayne@69: 'A general convention is that an empty format string ("""") ' jpayne@69: 'produces\n' jpayne@69: 'the same result as if you had called "str()" on the value. ' jpayne@69: 'A non-empty\n' jpayne@69: 'format string typically modifies the result.\n' jpayne@69: '\n' jpayne@69: 'The general form of a *standard format specifier* is:\n' jpayne@69: '\n' jpayne@69: ' format_spec ::= ' jpayne@69: '[[fill]align][sign][#][0][width][grouping_option][.precision][type]\n' jpayne@69: ' fill ::= \n' jpayne@69: ' align ::= "<" | ">" | "=" | "^"\n' jpayne@69: ' sign ::= "+" | "-" | " "\n' jpayne@69: ' width ::= digit+\n' jpayne@69: ' grouping_option ::= "_" | ","\n' jpayne@69: ' precision ::= digit+\n' jpayne@69: ' type ::= "b" | "c" | "d" | "e" | "E" | "f" | ' jpayne@69: '"F" | "g" | "G" | "n" | "o" | "s" | "x" | "X" | "%"\n' jpayne@69: '\n' jpayne@69: 'If a valid *align* value is specified, it can be preceded ' jpayne@69: 'by a *fill*\n' jpayne@69: 'character that can be any character and defaults to a space ' jpayne@69: 'if\n' jpayne@69: 'omitted. It is not possible to use a literal curly brace ' jpayne@69: '(“"{"” or\n' jpayne@69: '“"}"”) as the *fill* character in a formatted string ' jpayne@69: 'literal or when\n' jpayne@69: 'using the "str.format()" method. However, it is possible ' jpayne@69: 'to insert a\n' jpayne@69: 'curly brace with a nested replacement field. This ' jpayne@69: 'limitation doesn’t\n' jpayne@69: 'affect the "format()" function.\n' jpayne@69: '\n' jpayne@69: 'The meaning of the various alignment options is as ' jpayne@69: 'follows:\n' jpayne@69: '\n' jpayne@69: ' ' jpayne@69: '+-----------+------------------------------------------------------------+\n' jpayne@69: ' | Option | ' jpayne@69: 'Meaning ' jpayne@69: '|\n' jpayne@69: ' ' jpayne@69: '|===========|============================================================|\n' jpayne@69: ' | "\'<\'" | Forces the field to be left-aligned ' jpayne@69: 'within the available |\n' jpayne@69: ' | | space (this is the default for most ' jpayne@69: 'objects). |\n' jpayne@69: ' ' jpayne@69: '+-----------+------------------------------------------------------------+\n' jpayne@69: ' | "\'>\'" | Forces the field to be right-aligned ' jpayne@69: 'within the available |\n' jpayne@69: ' | | space (this is the default for ' jpayne@69: 'numbers). |\n' jpayne@69: ' ' jpayne@69: '+-----------+------------------------------------------------------------+\n' jpayne@69: ' | "\'=\'" | Forces the padding to be placed after ' jpayne@69: 'the sign (if any) |\n' jpayne@69: ' | | but before the digits. This is used for ' jpayne@69: 'printing fields |\n' jpayne@69: ' | | in the form ‘+000000120’. This alignment ' jpayne@69: 'option is only |\n' jpayne@69: ' | | valid for numeric types. It becomes the ' jpayne@69: 'default when ‘0’ |\n' jpayne@69: ' | | immediately precedes the field ' jpayne@69: 'width. |\n' jpayne@69: ' ' jpayne@69: '+-----------+------------------------------------------------------------+\n' jpayne@69: ' | "\'^\'" | Forces the field to be centered within ' jpayne@69: 'the available |\n' jpayne@69: ' | | ' jpayne@69: 'space. ' jpayne@69: '|\n' jpayne@69: ' ' jpayne@69: '+-----------+------------------------------------------------------------+\n' jpayne@69: '\n' jpayne@69: 'Note that unless a minimum field width is defined, the ' jpayne@69: 'field width\n' jpayne@69: 'will always be the same size as the data to fill it, so ' jpayne@69: 'that the\n' jpayne@69: 'alignment option has no meaning in this case.\n' jpayne@69: '\n' jpayne@69: 'The *sign* option is only valid for number types, and can ' jpayne@69: 'be one of\n' jpayne@69: 'the following:\n' jpayne@69: '\n' jpayne@69: ' ' jpayne@69: '+-----------+------------------------------------------------------------+\n' jpayne@69: ' | Option | ' jpayne@69: 'Meaning ' jpayne@69: '|\n' jpayne@69: ' ' jpayne@69: '|===========|============================================================|\n' jpayne@69: ' | "\'+\'" | indicates that a sign should be used for ' jpayne@69: 'both positive as |\n' jpayne@69: ' | | well as negative ' jpayne@69: 'numbers. |\n' jpayne@69: ' ' jpayne@69: '+-----------+------------------------------------------------------------+\n' jpayne@69: ' | "\'-\'" | indicates that a sign should be used ' jpayne@69: 'only for negative |\n' jpayne@69: ' | | numbers (this is the default ' jpayne@69: 'behavior). |\n' jpayne@69: ' ' jpayne@69: '+-----------+------------------------------------------------------------+\n' jpayne@69: ' | space | indicates that a leading space should be ' jpayne@69: 'used on positive |\n' jpayne@69: ' | | numbers, and a minus sign on negative ' jpayne@69: 'numbers. |\n' jpayne@69: ' ' jpayne@69: '+-----------+------------------------------------------------------------+\n' jpayne@69: '\n' jpayne@69: 'The "\'#\'" option causes the “alternate form” to be used ' jpayne@69: 'for the\n' jpayne@69: 'conversion. The alternate form is defined differently for ' jpayne@69: 'different\n' jpayne@69: 'types. This option is only valid for integer, float, ' jpayne@69: 'complex and\n' jpayne@69: 'Decimal types. For integers, when binary, octal, or ' jpayne@69: 'hexadecimal output\n' jpayne@69: 'is used, this option adds the prefix respective "\'0b\'", ' jpayne@69: '"\'0o\'", or\n' jpayne@69: '"\'0x\'" to the output value. For floats, complex and ' jpayne@69: 'Decimal the\n' jpayne@69: 'alternate form causes the result of the conversion to ' jpayne@69: 'always contain a\n' jpayne@69: 'decimal-point character, even if no digits follow it. ' jpayne@69: 'Normally, a\n' jpayne@69: 'decimal-point character appears in the result of these ' jpayne@69: 'conversions\n' jpayne@69: 'only if a digit follows it. In addition, for "\'g\'" and ' jpayne@69: '"\'G\'"\n' jpayne@69: 'conversions, trailing zeros are not removed from the ' jpayne@69: 'result.\n' jpayne@69: '\n' jpayne@69: 'The "\',\'" option signals the use of a comma for a ' jpayne@69: 'thousands separator.\n' jpayne@69: 'For a locale aware separator, use the "\'n\'" integer ' jpayne@69: 'presentation type\n' jpayne@69: 'instead.\n' jpayne@69: '\n' jpayne@69: 'Changed in version 3.1: Added the "\',\'" option (see also ' jpayne@69: '**PEP 378**).\n' jpayne@69: '\n' jpayne@69: 'The "\'_\'" option signals the use of an underscore for a ' jpayne@69: 'thousands\n' jpayne@69: 'separator for floating point presentation types and for ' jpayne@69: 'integer\n' jpayne@69: 'presentation type "\'d\'". For integer presentation types ' jpayne@69: '"\'b\'", "\'o\'",\n' jpayne@69: '"\'x\'", and "\'X\'", underscores will be inserted every 4 ' jpayne@69: 'digits. For\n' jpayne@69: 'other presentation types, specifying this option is an ' jpayne@69: 'error.\n' jpayne@69: '\n' jpayne@69: 'Changed in version 3.6: Added the "\'_\'" option (see also ' jpayne@69: '**PEP 515**).\n' jpayne@69: '\n' jpayne@69: '*width* is a decimal integer defining the minimum field ' jpayne@69: 'width. If not\n' jpayne@69: 'specified, then the field width will be determined by the ' jpayne@69: 'content.\n' jpayne@69: '\n' jpayne@69: 'When no explicit alignment is given, preceding the *width* ' jpayne@69: 'field by a\n' jpayne@69: 'zero ("\'0\'") character enables sign-aware zero-padding ' jpayne@69: 'for numeric\n' jpayne@69: 'types. This is equivalent to a *fill* character of "\'0\'" ' jpayne@69: 'with an\n' jpayne@69: '*alignment* type of "\'=\'".\n' jpayne@69: '\n' jpayne@69: 'The *precision* is a decimal number indicating how many ' jpayne@69: 'digits should\n' jpayne@69: 'be displayed after the decimal point for a floating point ' jpayne@69: 'value\n' jpayne@69: 'formatted with "\'f\'" and "\'F\'", or before and after the ' jpayne@69: 'decimal point\n' jpayne@69: 'for a floating point value formatted with "\'g\'" or ' jpayne@69: '"\'G\'". For non-\n' jpayne@69: 'number types the field indicates the maximum field size - ' jpayne@69: 'in other\n' jpayne@69: 'words, how many characters will be used from the field ' jpayne@69: 'content. The\n' jpayne@69: '*precision* is not allowed for integer values.\n' jpayne@69: '\n' jpayne@69: 'Finally, the *type* determines how the data should be ' jpayne@69: 'presented.\n' jpayne@69: '\n' jpayne@69: 'The available string presentation types are:\n' jpayne@69: '\n' jpayne@69: ' ' jpayne@69: '+-----------+------------------------------------------------------------+\n' jpayne@69: ' | Type | ' jpayne@69: 'Meaning ' jpayne@69: '|\n' jpayne@69: ' ' jpayne@69: '|===========|============================================================|\n' jpayne@69: ' | "\'s\'" | String format. This is the default type ' jpayne@69: 'for strings and |\n' jpayne@69: ' | | may be ' jpayne@69: 'omitted. |\n' jpayne@69: ' ' jpayne@69: '+-----------+------------------------------------------------------------+\n' jpayne@69: ' | None | The same as ' jpayne@69: '"\'s\'". |\n' jpayne@69: ' ' jpayne@69: '+-----------+------------------------------------------------------------+\n' jpayne@69: '\n' jpayne@69: 'The available integer presentation types are:\n' jpayne@69: '\n' jpayne@69: ' ' jpayne@69: '+-----------+------------------------------------------------------------+\n' jpayne@69: ' | Type | ' jpayne@69: 'Meaning ' jpayne@69: '|\n' jpayne@69: ' ' jpayne@69: '|===========|============================================================|\n' jpayne@69: ' | "\'b\'" | Binary format. Outputs the number in ' jpayne@69: 'base 2. |\n' jpayne@69: ' ' jpayne@69: '+-----------+------------------------------------------------------------+\n' jpayne@69: ' | "\'c\'" | Character. Converts the integer to the ' jpayne@69: 'corresponding |\n' jpayne@69: ' | | unicode character before ' jpayne@69: 'printing. |\n' jpayne@69: ' ' jpayne@69: '+-----------+------------------------------------------------------------+\n' jpayne@69: ' | "\'d\'" | Decimal Integer. Outputs the number in ' jpayne@69: 'base 10. |\n' jpayne@69: ' ' jpayne@69: '+-----------+------------------------------------------------------------+\n' jpayne@69: ' | "\'o\'" | Octal format. Outputs the number in base ' jpayne@69: '8. |\n' jpayne@69: ' ' jpayne@69: '+-----------+------------------------------------------------------------+\n' jpayne@69: ' | "\'x\'" | Hex format. Outputs the number in base ' jpayne@69: '16, using lower- |\n' jpayne@69: ' | | case letters for the digits above ' jpayne@69: '9. |\n' jpayne@69: ' ' jpayne@69: '+-----------+------------------------------------------------------------+\n' jpayne@69: ' | "\'X\'" | Hex format. Outputs the number in base ' jpayne@69: '16, using upper- |\n' jpayne@69: ' | | case letters for the digits above ' jpayne@69: '9. |\n' jpayne@69: ' ' jpayne@69: '+-----------+------------------------------------------------------------+\n' jpayne@69: ' | "\'n\'" | Number. This is the same as "\'d\'", ' jpayne@69: 'except that it uses the |\n' jpayne@69: ' | | current locale setting to insert the ' jpayne@69: 'appropriate number |\n' jpayne@69: ' | | separator ' jpayne@69: 'characters. |\n' jpayne@69: ' ' jpayne@69: '+-----------+------------------------------------------------------------+\n' jpayne@69: ' | None | The same as ' jpayne@69: '"\'d\'". |\n' jpayne@69: ' ' jpayne@69: '+-----------+------------------------------------------------------------+\n' jpayne@69: '\n' jpayne@69: 'In addition to the above presentation types, integers can ' jpayne@69: 'be formatted\n' jpayne@69: 'with the floating point presentation types listed below ' jpayne@69: '(except "\'n\'"\n' jpayne@69: 'and "None"). When doing so, "float()" is used to convert ' jpayne@69: 'the integer\n' jpayne@69: 'to a floating point number before formatting.\n' jpayne@69: '\n' jpayne@69: 'The available presentation types for floating point and ' jpayne@69: 'decimal values\n' jpayne@69: 'are:\n' jpayne@69: '\n' jpayne@69: ' ' jpayne@69: '+-----------+------------------------------------------------------------+\n' jpayne@69: ' | Type | ' jpayne@69: 'Meaning ' jpayne@69: '|\n' jpayne@69: ' ' jpayne@69: '|===========|============================================================|\n' jpayne@69: ' | "\'e\'" | Exponent notation. Prints the number in ' jpayne@69: 'scientific |\n' jpayne@69: ' | | notation using the letter ‘e’ to indicate ' jpayne@69: 'the exponent. |\n' jpayne@69: ' | | The default precision is ' jpayne@69: '"6". |\n' jpayne@69: ' ' jpayne@69: '+-----------+------------------------------------------------------------+\n' jpayne@69: ' | "\'E\'" | Exponent notation. Same as "\'e\'" ' jpayne@69: 'except it uses an upper |\n' jpayne@69: ' | | case ‘E’ as the separator ' jpayne@69: 'character. |\n' jpayne@69: ' ' jpayne@69: '+-----------+------------------------------------------------------------+\n' jpayne@69: ' | "\'f\'" | Fixed-point notation. Displays the ' jpayne@69: 'number as a fixed-point |\n' jpayne@69: ' | | number. The default precision is ' jpayne@69: '"6". |\n' jpayne@69: ' ' jpayne@69: '+-----------+------------------------------------------------------------+\n' jpayne@69: ' | "\'F\'" | Fixed-point notation. Same as "\'f\'", ' jpayne@69: 'but converts "nan" to |\n' jpayne@69: ' | | "NAN" and "inf" to ' jpayne@69: '"INF". |\n' jpayne@69: ' ' jpayne@69: '+-----------+------------------------------------------------------------+\n' jpayne@69: ' | "\'g\'" | General format. For a given precision ' jpayne@69: '"p >= 1", this |\n' jpayne@69: ' | | rounds the number to "p" significant ' jpayne@69: 'digits and then |\n' jpayne@69: ' | | formats the result in either fixed-point ' jpayne@69: 'format or in |\n' jpayne@69: ' | | scientific notation, depending on its ' jpayne@69: 'magnitude. The |\n' jpayne@69: ' | | precise rules are as follows: suppose that ' jpayne@69: 'the result |\n' jpayne@69: ' | | formatted with presentation type "\'e\'" ' jpayne@69: 'and precision "p-1" |\n' jpayne@69: ' | | would have exponent "exp". Then, if "m <= ' jpayne@69: 'exp < p", where |\n' jpayne@69: ' | | "m" is -4 for floats and -6 for ' jpayne@69: '"Decimals", the number is |\n' jpayne@69: ' | | formatted with presentation type "\'f\'" ' jpayne@69: 'and precision |\n' jpayne@69: ' | | "p-1-exp". Otherwise, the number is ' jpayne@69: 'formatted with |\n' jpayne@69: ' | | presentation type "\'e\'" and precision ' jpayne@69: '"p-1". In both cases |\n' jpayne@69: ' | | insignificant trailing zeros are removed ' jpayne@69: 'from the |\n' jpayne@69: ' | | significand, and the decimal point is also ' jpayne@69: 'removed if |\n' jpayne@69: ' | | there are no remaining digits following ' jpayne@69: 'it, unless the |\n' jpayne@69: ' | | "\'#\'" option is used. Positive and ' jpayne@69: 'negative infinity, |\n' jpayne@69: ' | | positive and negative zero, and nans, are ' jpayne@69: 'formatted as |\n' jpayne@69: ' | | "inf", "-inf", "0", "-0" and "nan" ' jpayne@69: 'respectively, |\n' jpayne@69: ' | | regardless of the precision. A precision ' jpayne@69: 'of "0" is |\n' jpayne@69: ' | | treated as equivalent to a precision of ' jpayne@69: '"1". The default |\n' jpayne@69: ' | | precision is ' jpayne@69: '"6". |\n' jpayne@69: ' ' jpayne@69: '+-----------+------------------------------------------------------------+\n' jpayne@69: ' | "\'G\'" | General format. Same as "\'g\'" except ' jpayne@69: 'switches to "\'E\'" if |\n' jpayne@69: ' | | the number gets too large. The ' jpayne@69: 'representations of infinity |\n' jpayne@69: ' | | and NaN are uppercased, ' jpayne@69: 'too. |\n' jpayne@69: ' ' jpayne@69: '+-----------+------------------------------------------------------------+\n' jpayne@69: ' | "\'n\'" | Number. This is the same as "\'g\'", ' jpayne@69: 'except that it uses the |\n' jpayne@69: ' | | current locale setting to insert the ' jpayne@69: 'appropriate number |\n' jpayne@69: ' | | separator ' jpayne@69: 'characters. |\n' jpayne@69: ' ' jpayne@69: '+-----------+------------------------------------------------------------+\n' jpayne@69: ' | "\'%\'" | Percentage. Multiplies the number by 100 ' jpayne@69: 'and displays in |\n' jpayne@69: ' | | fixed ("\'f\'") format, followed by a ' jpayne@69: 'percent sign. |\n' jpayne@69: ' ' jpayne@69: '+-----------+------------------------------------------------------------+\n' jpayne@69: ' | None | Similar to "\'g\'", except that ' jpayne@69: 'fixed-point notation, when |\n' jpayne@69: ' | | used, has at least one digit past the ' jpayne@69: 'decimal point. The |\n' jpayne@69: ' | | default precision is as high as needed to ' jpayne@69: 'represent the |\n' jpayne@69: ' | | particular value. The overall effect is to ' jpayne@69: 'match the |\n' jpayne@69: ' | | output of "str()" as altered by the other ' jpayne@69: 'format |\n' jpayne@69: ' | | ' jpayne@69: 'modifiers. ' jpayne@69: '|\n' jpayne@69: ' ' jpayne@69: '+-----------+------------------------------------------------------------+\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Format examples\n' jpayne@69: '===============\n' jpayne@69: '\n' jpayne@69: 'This section contains examples of the "str.format()" syntax ' jpayne@69: 'and\n' jpayne@69: 'comparison with the old "%"-formatting.\n' jpayne@69: '\n' jpayne@69: 'In most of the cases the syntax is similar to the old ' jpayne@69: '"%"-formatting,\n' jpayne@69: 'with the addition of the "{}" and with ":" used instead of ' jpayne@69: '"%". For\n' jpayne@69: 'example, "\'%03.2f\'" can be translated to "\'{:03.2f}\'".\n' jpayne@69: '\n' jpayne@69: 'The new format syntax also supports new and different ' jpayne@69: 'options, shown\n' jpayne@69: 'in the following examples.\n' jpayne@69: '\n' jpayne@69: 'Accessing arguments by position:\n' jpayne@69: '\n' jpayne@69: " >>> '{0}, {1}, {2}'.format('a', 'b', 'c')\n" jpayne@69: " 'a, b, c'\n" jpayne@69: " >>> '{}, {}, {}'.format('a', 'b', 'c') # 3.1+ only\n" jpayne@69: " 'a, b, c'\n" jpayne@69: " >>> '{2}, {1}, {0}'.format('a', 'b', 'c')\n" jpayne@69: " 'c, b, a'\n" jpayne@69: " >>> '{2}, {1}, {0}'.format(*'abc') # unpacking " jpayne@69: 'argument sequence\n' jpayne@69: " 'c, b, a'\n" jpayne@69: " >>> '{0}{1}{0}'.format('abra', 'cad') # arguments' " jpayne@69: 'indices can be repeated\n' jpayne@69: " 'abracadabra'\n" jpayne@69: '\n' jpayne@69: 'Accessing arguments by name:\n' jpayne@69: '\n' jpayne@69: " >>> 'Coordinates: {latitude}, " jpayne@69: "{longitude}'.format(latitude='37.24N', " jpayne@69: "longitude='-115.81W')\n" jpayne@69: " 'Coordinates: 37.24N, -115.81W'\n" jpayne@69: " >>> coord = {'latitude': '37.24N', 'longitude': " jpayne@69: "'-115.81W'}\n" jpayne@69: " >>> 'Coordinates: {latitude}, " jpayne@69: "{longitude}'.format(**coord)\n" jpayne@69: " 'Coordinates: 37.24N, -115.81W'\n" jpayne@69: '\n' jpayne@69: 'Accessing arguments’ attributes:\n' jpayne@69: '\n' jpayne@69: ' >>> c = 3-5j\n' jpayne@69: " >>> ('The complex number {0} is formed from the real " jpayne@69: "part {0.real} '\n" jpayne@69: " ... 'and the imaginary part {0.imag}.').format(c)\n" jpayne@69: " 'The complex number (3-5j) is formed from the real part " jpayne@69: "3.0 and the imaginary part -5.0.'\n" jpayne@69: ' >>> class Point:\n' jpayne@69: ' ... def __init__(self, x, y):\n' jpayne@69: ' ... self.x, self.y = x, y\n' jpayne@69: ' ... def __str__(self):\n' jpayne@69: " ... return 'Point({self.x}, " jpayne@69: "{self.y})'.format(self=self)\n" jpayne@69: ' ...\n' jpayne@69: ' >>> str(Point(4, 2))\n' jpayne@69: " 'Point(4, 2)'\n" jpayne@69: '\n' jpayne@69: 'Accessing arguments’ items:\n' jpayne@69: '\n' jpayne@69: ' >>> coord = (3, 5)\n' jpayne@69: " >>> 'X: {0[0]}; Y: {0[1]}'.format(coord)\n" jpayne@69: " 'X: 3; Y: 5'\n" jpayne@69: '\n' jpayne@69: 'Replacing "%s" and "%r":\n' jpayne@69: '\n' jpayne@69: ' >>> "repr() shows quotes: {!r}; str() doesn\'t: ' jpayne@69: '{!s}".format(\'test1\', \'test2\')\n' jpayne@69: ' "repr() shows quotes: \'test1\'; str() doesn\'t: test2"\n' jpayne@69: '\n' jpayne@69: 'Aligning the text and specifying a width:\n' jpayne@69: '\n' jpayne@69: " >>> '{:<30}'.format('left aligned')\n" jpayne@69: " 'left aligned '\n" jpayne@69: " >>> '{:>30}'.format('right aligned')\n" jpayne@69: " ' right aligned'\n" jpayne@69: " >>> '{:^30}'.format('centered')\n" jpayne@69: " ' centered '\n" jpayne@69: " >>> '{:*^30}'.format('centered') # use '*' as a fill " jpayne@69: 'char\n' jpayne@69: " '***********centered***********'\n" jpayne@69: '\n' jpayne@69: 'Replacing "%+f", "%-f", and "% f" and specifying a sign:\n' jpayne@69: '\n' jpayne@69: " >>> '{:+f}; {:+f}'.format(3.14, -3.14) # show it " jpayne@69: 'always\n' jpayne@69: " '+3.140000; -3.140000'\n" jpayne@69: " >>> '{: f}; {: f}'.format(3.14, -3.14) # show a space " jpayne@69: 'for positive numbers\n' jpayne@69: " ' 3.140000; -3.140000'\n" jpayne@69: " >>> '{:-f}; {:-f}'.format(3.14, -3.14) # show only the " jpayne@69: "minus -- same as '{:f}; {:f}'\n" jpayne@69: " '3.140000; -3.140000'\n" jpayne@69: '\n' jpayne@69: 'Replacing "%x" and "%o" and converting the value to ' jpayne@69: 'different bases:\n' jpayne@69: '\n' jpayne@69: ' >>> # format also supports binary numbers\n' jpayne@69: ' >>> "int: {0:d}; hex: {0:x}; oct: {0:o}; bin: ' jpayne@69: '{0:b}".format(42)\n' jpayne@69: " 'int: 42; hex: 2a; oct: 52; bin: 101010'\n" jpayne@69: ' >>> # with 0x, 0o, or 0b as prefix:\n' jpayne@69: ' >>> "int: {0:d}; hex: {0:#x}; oct: {0:#o}; bin: ' jpayne@69: '{0:#b}".format(42)\n' jpayne@69: " 'int: 42; hex: 0x2a; oct: 0o52; bin: 0b101010'\n" jpayne@69: '\n' jpayne@69: 'Using the comma as a thousands separator:\n' jpayne@69: '\n' jpayne@69: " >>> '{:,}'.format(1234567890)\n" jpayne@69: " '1,234,567,890'\n" jpayne@69: '\n' jpayne@69: 'Expressing a percentage:\n' jpayne@69: '\n' jpayne@69: ' >>> points = 19\n' jpayne@69: ' >>> total = 22\n' jpayne@69: " >>> 'Correct answers: {:.2%}'.format(points/total)\n" jpayne@69: " 'Correct answers: 86.36%'\n" jpayne@69: '\n' jpayne@69: 'Using type-specific formatting:\n' jpayne@69: '\n' jpayne@69: ' >>> import datetime\n' jpayne@69: ' >>> d = datetime.datetime(2010, 7, 4, 12, 15, 58)\n' jpayne@69: " >>> '{:%Y-%m-%d %H:%M:%S}'.format(d)\n" jpayne@69: " '2010-07-04 12:15:58'\n" jpayne@69: '\n' jpayne@69: 'Nesting arguments and more complex examples:\n' jpayne@69: '\n' jpayne@69: " >>> for align, text in zip('<^>', ['left', 'center', " jpayne@69: "'right']):\n" jpayne@69: " ... '{0:{fill}{align}16}'.format(text, fill=align, " jpayne@69: 'align=align)\n' jpayne@69: ' ...\n' jpayne@69: " 'left<<<<<<<<<<<<'\n" jpayne@69: " '^^^^^center^^^^^'\n" jpayne@69: " '>>>>>>>>>>>right'\n" jpayne@69: ' >>>\n' jpayne@69: ' >>> octets = [192, 168, 0, 1]\n' jpayne@69: " >>> '{:02X}{:02X}{:02X}{:02X}'.format(*octets)\n" jpayne@69: " 'C0A80001'\n" jpayne@69: ' >>> int(_, 16)\n' jpayne@69: ' 3232235521\n' jpayne@69: ' >>>\n' jpayne@69: ' >>> width = 5\n' jpayne@69: ' >>> for num in range(5,12): \n' jpayne@69: " ... for base in 'dXob':\n" jpayne@69: " ... print('{0:{width}{base}}'.format(num, " jpayne@69: "base=base, width=width), end=' ')\n" jpayne@69: ' ... print()\n' jpayne@69: ' ...\n' jpayne@69: ' 5 5 5 101\n' jpayne@69: ' 6 6 6 110\n' jpayne@69: ' 7 7 7 111\n' jpayne@69: ' 8 8 10 1000\n' jpayne@69: ' 9 9 11 1001\n' jpayne@69: ' 10 A 12 1010\n' jpayne@69: ' 11 B 13 1011\n', jpayne@69: 'function': 'Function definitions\n' jpayne@69: '********************\n' jpayne@69: '\n' jpayne@69: 'A function definition defines a user-defined function object ' jpayne@69: '(see\n' jpayne@69: 'section The standard type hierarchy):\n' jpayne@69: '\n' jpayne@69: ' funcdef ::= [decorators] "def" funcname "(" ' jpayne@69: '[parameter_list] ")"\n' jpayne@69: ' ["->" expression] ":" suite\n' jpayne@69: ' decorators ::= decorator+\n' jpayne@69: ' decorator ::= "@" dotted_name ["(" ' jpayne@69: '[argument_list [","]] ")"] NEWLINE\n' jpayne@69: ' dotted_name ::= identifier ("." identifier)*\n' jpayne@69: ' parameter_list ::= defparameter ("," ' jpayne@69: 'defparameter)* "," "/" ["," [parameter_list_no_posonly]]\n' jpayne@69: ' | parameter_list_no_posonly\n' jpayne@69: ' parameter_list_no_posonly ::= defparameter ("," ' jpayne@69: 'defparameter)* ["," [parameter_list_starargs]]\n' jpayne@69: ' | parameter_list_starargs\n' jpayne@69: ' parameter_list_starargs ::= "*" [parameter] ("," ' jpayne@69: 'defparameter)* ["," ["**" parameter [","]]]\n' jpayne@69: ' | "**" parameter [","]\n' jpayne@69: ' parameter ::= identifier [":" expression]\n' jpayne@69: ' defparameter ::= parameter ["=" expression]\n' jpayne@69: ' funcname ::= identifier\n' jpayne@69: '\n' jpayne@69: 'A function definition is an executable statement. Its execution ' jpayne@69: 'binds\n' jpayne@69: 'the function name in the current local namespace to a function ' jpayne@69: 'object\n' jpayne@69: '(a wrapper around the executable code for the function). This\n' jpayne@69: 'function object contains a reference to the current global ' jpayne@69: 'namespace\n' jpayne@69: 'as the global namespace to be used when the function is called.\n' jpayne@69: '\n' jpayne@69: 'The function definition does not execute the function body; this ' jpayne@69: 'gets\n' jpayne@69: 'executed only when the function is called. [2]\n' jpayne@69: '\n' jpayne@69: 'A function definition may be wrapped by one or more *decorator*\n' jpayne@69: 'expressions. Decorator expressions are evaluated when the ' jpayne@69: 'function is\n' jpayne@69: 'defined, in the scope that contains the function definition. ' jpayne@69: 'The\n' jpayne@69: 'result must be a callable, which is invoked with the function ' jpayne@69: 'object\n' jpayne@69: 'as the only argument. The returned value is bound to the ' jpayne@69: 'function name\n' jpayne@69: 'instead of the function object. Multiple decorators are applied ' jpayne@69: 'in\n' jpayne@69: 'nested fashion. For example, the following code\n' jpayne@69: '\n' jpayne@69: ' @f1(arg)\n' jpayne@69: ' @f2\n' jpayne@69: ' def func(): pass\n' jpayne@69: '\n' jpayne@69: 'is roughly equivalent to\n' jpayne@69: '\n' jpayne@69: ' def func(): pass\n' jpayne@69: ' func = f1(arg)(f2(func))\n' jpayne@69: '\n' jpayne@69: 'except that the original function is not temporarily bound to ' jpayne@69: 'the name\n' jpayne@69: '"func".\n' jpayne@69: '\n' jpayne@69: 'When one or more *parameters* have the form *parameter* "="\n' jpayne@69: '*expression*, the function is said to have “default parameter ' jpayne@69: 'values.”\n' jpayne@69: 'For a parameter with a default value, the corresponding ' jpayne@69: '*argument* may\n' jpayne@69: 'be omitted from a call, in which case the parameter’s default ' jpayne@69: 'value is\n' jpayne@69: 'substituted. If a parameter has a default value, all following\n' jpayne@69: 'parameters up until the “"*"” must also have a default value — ' jpayne@69: 'this is\n' jpayne@69: 'a syntactic restriction that is not expressed by the grammar.\n' jpayne@69: '\n' jpayne@69: '**Default parameter values are evaluated from left to right when ' jpayne@69: 'the\n' jpayne@69: 'function definition is executed.** This means that the ' jpayne@69: 'expression is\n' jpayne@69: 'evaluated once, when the function is defined, and that the same ' jpayne@69: '“pre-\n' jpayne@69: 'computed” value is used for each call. This is especially ' jpayne@69: 'important\n' jpayne@69: 'to understand when a default parameter is a mutable object, such ' jpayne@69: 'as a\n' jpayne@69: 'list or a dictionary: if the function modifies the object (e.g. ' jpayne@69: 'by\n' jpayne@69: 'appending an item to a list), the default value is in effect ' jpayne@69: 'modified.\n' jpayne@69: 'This is generally not what was intended. A way around this is ' jpayne@69: 'to use\n' jpayne@69: '"None" as the default, and explicitly test for it in the body of ' jpayne@69: 'the\n' jpayne@69: 'function, e.g.:\n' jpayne@69: '\n' jpayne@69: ' def whats_on_the_telly(penguin=None):\n' jpayne@69: ' if penguin is None:\n' jpayne@69: ' penguin = []\n' jpayne@69: ' penguin.append("property of the zoo")\n' jpayne@69: ' return penguin\n' jpayne@69: '\n' jpayne@69: 'Function call semantics are described in more detail in section ' jpayne@69: 'Calls.\n' jpayne@69: 'A function call always assigns values to all parameters ' jpayne@69: 'mentioned in\n' jpayne@69: 'the parameter list, either from position arguments, from ' jpayne@69: 'keyword\n' jpayne@69: 'arguments, or from default values. If the form “"*identifier"” ' jpayne@69: 'is\n' jpayne@69: 'present, it is initialized to a tuple receiving any excess ' jpayne@69: 'positional\n' jpayne@69: 'parameters, defaulting to the empty tuple. If the form\n' jpayne@69: '“"**identifier"” is present, it is initialized to a new ordered\n' jpayne@69: 'mapping receiving any excess keyword arguments, defaulting to a ' jpayne@69: 'new\n' jpayne@69: 'empty mapping of the same type. Parameters after “"*"” or\n' jpayne@69: '“"*identifier"” are keyword-only parameters and may only be ' jpayne@69: 'passed\n' jpayne@69: 'used keyword arguments.\n' jpayne@69: '\n' jpayne@69: 'Parameters may have an *annotation* of the form “": ' jpayne@69: 'expression"”\n' jpayne@69: 'following the parameter name. Any parameter may have an ' jpayne@69: 'annotation,\n' jpayne@69: 'even those of the form "*identifier" or "**identifier". ' jpayne@69: 'Functions may\n' jpayne@69: 'have “return” annotation of the form “"-> expression"” after ' jpayne@69: 'the\n' jpayne@69: 'parameter list. These annotations can be any valid Python ' jpayne@69: 'expression.\n' jpayne@69: 'The presence of annotations does not change the semantics of a\n' jpayne@69: 'function. The annotation values are available as values of a\n' jpayne@69: 'dictionary keyed by the parameters’ names in the ' jpayne@69: '"__annotations__"\n' jpayne@69: 'attribute of the function object. If the "annotations" import ' jpayne@69: 'from\n' jpayne@69: '"__future__" is used, annotations are preserved as strings at ' jpayne@69: 'runtime\n' jpayne@69: 'which enables postponed evaluation. Otherwise, they are ' jpayne@69: 'evaluated\n' jpayne@69: 'when the function definition is executed. In this case ' jpayne@69: 'annotations\n' jpayne@69: 'may be evaluated in a different order than they appear in the ' jpayne@69: 'source\n' jpayne@69: 'code.\n' jpayne@69: '\n' jpayne@69: 'It is also possible to create anonymous functions (functions not ' jpayne@69: 'bound\n' jpayne@69: 'to a name), for immediate use in expressions. This uses lambda\n' jpayne@69: 'expressions, described in section Lambdas. Note that the ' jpayne@69: 'lambda\n' jpayne@69: 'expression is merely a shorthand for a simplified function ' jpayne@69: 'definition;\n' jpayne@69: 'a function defined in a “"def"” statement can be passed around ' jpayne@69: 'or\n' jpayne@69: 'assigned to another name just like a function defined by a ' jpayne@69: 'lambda\n' jpayne@69: 'expression. The “"def"” form is actually more powerful since ' jpayne@69: 'it\n' jpayne@69: 'allows the execution of multiple statements and annotations.\n' jpayne@69: '\n' jpayne@69: '**Programmer’s note:** Functions are first-class objects. A ' jpayne@69: '“"def"”\n' jpayne@69: 'statement executed inside a function definition defines a local\n' jpayne@69: 'function that can be returned or passed around. Free variables ' jpayne@69: 'used\n' jpayne@69: 'in the nested function can access the local variables of the ' jpayne@69: 'function\n' jpayne@69: 'containing the def. See section Naming and binding for ' jpayne@69: 'details.\n' jpayne@69: '\n' jpayne@69: 'See also:\n' jpayne@69: '\n' jpayne@69: ' **PEP 3107** - Function Annotations\n' jpayne@69: ' The original specification for function annotations.\n' jpayne@69: '\n' jpayne@69: ' **PEP 484** - Type Hints\n' jpayne@69: ' Definition of a standard meaning for annotations: type ' jpayne@69: 'hints.\n' jpayne@69: '\n' jpayne@69: ' **PEP 526** - Syntax for Variable Annotations\n' jpayne@69: ' Ability to type hint variable declarations, including ' jpayne@69: 'class\n' jpayne@69: ' variables and instance variables\n' jpayne@69: '\n' jpayne@69: ' **PEP 563** - Postponed Evaluation of Annotations\n' jpayne@69: ' Support for forward references within annotations by ' jpayne@69: 'preserving\n' jpayne@69: ' annotations in a string form at runtime instead of eager\n' jpayne@69: ' evaluation.\n', jpayne@69: 'global': 'The "global" statement\n' jpayne@69: '**********************\n' jpayne@69: '\n' jpayne@69: ' global_stmt ::= "global" identifier ("," identifier)*\n' jpayne@69: '\n' jpayne@69: 'The "global" statement is a declaration which holds for the ' jpayne@69: 'entire\n' jpayne@69: 'current code block. It means that the listed identifiers are to ' jpayne@69: 'be\n' jpayne@69: 'interpreted as globals. It would be impossible to assign to a ' jpayne@69: 'global\n' jpayne@69: 'variable without "global", although free variables may refer to\n' jpayne@69: 'globals without being declared global.\n' jpayne@69: '\n' jpayne@69: 'Names listed in a "global" statement must not be used in the same ' jpayne@69: 'code\n' jpayne@69: 'block textually preceding that "global" statement.\n' jpayne@69: '\n' jpayne@69: 'Names listed in a "global" statement must not be defined as ' jpayne@69: 'formal\n' jpayne@69: 'parameters or in a "for" loop control target, "class" definition,\n' jpayne@69: 'function definition, "import" statement, or variable annotation.\n' jpayne@69: '\n' jpayne@69: '**CPython implementation detail:** The current implementation does ' jpayne@69: 'not\n' jpayne@69: 'enforce some of these restrictions, but programs should not abuse ' jpayne@69: 'this\n' jpayne@69: 'freedom, as future implementations may enforce them or silently ' jpayne@69: 'change\n' jpayne@69: 'the meaning of the program.\n' jpayne@69: '\n' jpayne@69: '**Programmer’s note:** "global" is a directive to the parser. It\n' jpayne@69: 'applies only to code parsed at the same time as the "global"\n' jpayne@69: 'statement. In particular, a "global" statement contained in a ' jpayne@69: 'string\n' jpayne@69: 'or code object supplied to the built-in "exec()" function does ' jpayne@69: 'not\n' jpayne@69: 'affect the code block *containing* the function call, and code\n' jpayne@69: 'contained in such a string is unaffected by "global" statements in ' jpayne@69: 'the\n' jpayne@69: 'code containing the function call. The same applies to the ' jpayne@69: '"eval()"\n' jpayne@69: 'and "compile()" functions.\n', jpayne@69: 'id-classes': 'Reserved classes of identifiers\n' jpayne@69: '*******************************\n' jpayne@69: '\n' jpayne@69: 'Certain classes of identifiers (besides keywords) have ' jpayne@69: 'special\n' jpayne@69: 'meanings. These classes are identified by the patterns of ' jpayne@69: 'leading and\n' jpayne@69: 'trailing underscore characters:\n' jpayne@69: '\n' jpayne@69: '"_*"\n' jpayne@69: ' Not imported by "from module import *". The special ' jpayne@69: 'identifier "_"\n' jpayne@69: ' is used in the interactive interpreter to store the result ' jpayne@69: 'of the\n' jpayne@69: ' last evaluation; it is stored in the "builtins" module. ' jpayne@69: 'When not\n' jpayne@69: ' in interactive mode, "_" has no special meaning and is not ' jpayne@69: 'defined.\n' jpayne@69: ' See section The import statement.\n' jpayne@69: '\n' jpayne@69: ' Note: The name "_" is often used in conjunction with\n' jpayne@69: ' internationalization; refer to the documentation for the\n' jpayne@69: ' "gettext" module for more information on this ' jpayne@69: 'convention.\n' jpayne@69: '\n' jpayne@69: '"__*__"\n' jpayne@69: ' System-defined names. These names are defined by the ' jpayne@69: 'interpreter\n' jpayne@69: ' and its implementation (including the standard library). ' jpayne@69: 'Current\n' jpayne@69: ' system names are discussed in the Special method names ' jpayne@69: 'section and\n' jpayne@69: ' elsewhere. More will likely be defined in future versions ' jpayne@69: 'of\n' jpayne@69: ' Python. *Any* use of "__*__" names, in any context, that ' jpayne@69: 'does not\n' jpayne@69: ' follow explicitly documented use, is subject to breakage ' jpayne@69: 'without\n' jpayne@69: ' warning.\n' jpayne@69: '\n' jpayne@69: '"__*"\n' jpayne@69: ' Class-private names. Names in this category, when used ' jpayne@69: 'within the\n' jpayne@69: ' context of a class definition, are re-written to use a ' jpayne@69: 'mangled form\n' jpayne@69: ' to help avoid name clashes between “private” attributes of ' jpayne@69: 'base and\n' jpayne@69: ' derived classes. See section Identifiers (Names).\n', jpayne@69: 'identifiers': 'Identifiers and keywords\n' jpayne@69: '************************\n' jpayne@69: '\n' jpayne@69: 'Identifiers (also referred to as *names*) are described by ' jpayne@69: 'the\n' jpayne@69: 'following lexical definitions.\n' jpayne@69: '\n' jpayne@69: 'The syntax of identifiers in Python is based on the Unicode ' jpayne@69: 'standard\n' jpayne@69: 'annex UAX-31, with elaboration and changes as defined below; ' jpayne@69: 'see also\n' jpayne@69: '**PEP 3131** for further details.\n' jpayne@69: '\n' jpayne@69: 'Within the ASCII range (U+0001..U+007F), the valid characters ' jpayne@69: 'for\n' jpayne@69: 'identifiers are the same as in Python 2.x: the uppercase and ' jpayne@69: 'lowercase\n' jpayne@69: 'letters "A" through "Z", the underscore "_" and, except for ' jpayne@69: 'the first\n' jpayne@69: 'character, the digits "0" through "9".\n' jpayne@69: '\n' jpayne@69: 'Python 3.0 introduces additional characters from outside the ' jpayne@69: 'ASCII\n' jpayne@69: 'range (see **PEP 3131**). For these characters, the ' jpayne@69: 'classification\n' jpayne@69: 'uses the version of the Unicode Character Database as ' jpayne@69: 'included in the\n' jpayne@69: '"unicodedata" module.\n' jpayne@69: '\n' jpayne@69: 'Identifiers are unlimited in length. Case is significant.\n' jpayne@69: '\n' jpayne@69: ' identifier ::= xid_start xid_continue*\n' jpayne@69: ' id_start ::= \n' jpayne@69: ' id_continue ::= \n' jpayne@69: ' xid_start ::= \n' jpayne@69: ' xid_continue ::= \n' jpayne@69: '\n' jpayne@69: 'The Unicode category codes mentioned above stand for:\n' jpayne@69: '\n' jpayne@69: '* *Lu* - uppercase letters\n' jpayne@69: '\n' jpayne@69: '* *Ll* - lowercase letters\n' jpayne@69: '\n' jpayne@69: '* *Lt* - titlecase letters\n' jpayne@69: '\n' jpayne@69: '* *Lm* - modifier letters\n' jpayne@69: '\n' jpayne@69: '* *Lo* - other letters\n' jpayne@69: '\n' jpayne@69: '* *Nl* - letter numbers\n' jpayne@69: '\n' jpayne@69: '* *Mn* - nonspacing marks\n' jpayne@69: '\n' jpayne@69: '* *Mc* - spacing combining marks\n' jpayne@69: '\n' jpayne@69: '* *Nd* - decimal numbers\n' jpayne@69: '\n' jpayne@69: '* *Pc* - connector punctuations\n' jpayne@69: '\n' jpayne@69: '* *Other_ID_Start* - explicit list of characters in ' jpayne@69: 'PropList.txt to\n' jpayne@69: ' support backwards compatibility\n' jpayne@69: '\n' jpayne@69: '* *Other_ID_Continue* - likewise\n' jpayne@69: '\n' jpayne@69: 'All identifiers are converted into the normal form NFKC while ' jpayne@69: 'parsing;\n' jpayne@69: 'comparison of identifiers is based on NFKC.\n' jpayne@69: '\n' jpayne@69: 'A non-normative HTML file listing all valid identifier ' jpayne@69: 'characters for\n' jpayne@69: 'Unicode 4.1 can be found at https://www.dcl.hpi.uni-\n' jpayne@69: 'potsdam.de/home/loewis/table-3131.html.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Keywords\n' jpayne@69: '========\n' jpayne@69: '\n' jpayne@69: 'The following identifiers are used as reserved words, or ' jpayne@69: '*keywords* of\n' jpayne@69: 'the language, and cannot be used as ordinary identifiers. ' jpayne@69: 'They must\n' jpayne@69: 'be spelled exactly as written here:\n' jpayne@69: '\n' jpayne@69: ' False await else import pass\n' jpayne@69: ' None break except in raise\n' jpayne@69: ' True class finally is return\n' jpayne@69: ' and continue for lambda try\n' jpayne@69: ' as def from nonlocal while\n' jpayne@69: ' assert del global not with\n' jpayne@69: ' async elif if or yield\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Reserved classes of identifiers\n' jpayne@69: '===============================\n' jpayne@69: '\n' jpayne@69: 'Certain classes of identifiers (besides keywords) have ' jpayne@69: 'special\n' jpayne@69: 'meanings. These classes are identified by the patterns of ' jpayne@69: 'leading and\n' jpayne@69: 'trailing underscore characters:\n' jpayne@69: '\n' jpayne@69: '"_*"\n' jpayne@69: ' Not imported by "from module import *". The special ' jpayne@69: 'identifier "_"\n' jpayne@69: ' is used in the interactive interpreter to store the result ' jpayne@69: 'of the\n' jpayne@69: ' last evaluation; it is stored in the "builtins" module. ' jpayne@69: 'When not\n' jpayne@69: ' in interactive mode, "_" has no special meaning and is not ' jpayne@69: 'defined.\n' jpayne@69: ' See section The import statement.\n' jpayne@69: '\n' jpayne@69: ' Note: The name "_" is often used in conjunction with\n' jpayne@69: ' internationalization; refer to the documentation for ' jpayne@69: 'the\n' jpayne@69: ' "gettext" module for more information on this ' jpayne@69: 'convention.\n' jpayne@69: '\n' jpayne@69: '"__*__"\n' jpayne@69: ' System-defined names. These names are defined by the ' jpayne@69: 'interpreter\n' jpayne@69: ' and its implementation (including the standard library). ' jpayne@69: 'Current\n' jpayne@69: ' system names are discussed in the Special method names ' jpayne@69: 'section and\n' jpayne@69: ' elsewhere. More will likely be defined in future versions ' jpayne@69: 'of\n' jpayne@69: ' Python. *Any* use of "__*__" names, in any context, that ' jpayne@69: 'does not\n' jpayne@69: ' follow explicitly documented use, is subject to breakage ' jpayne@69: 'without\n' jpayne@69: ' warning.\n' jpayne@69: '\n' jpayne@69: '"__*"\n' jpayne@69: ' Class-private names. Names in this category, when used ' jpayne@69: 'within the\n' jpayne@69: ' context of a class definition, are re-written to use a ' jpayne@69: 'mangled form\n' jpayne@69: ' to help avoid name clashes between “private” attributes of ' jpayne@69: 'base and\n' jpayne@69: ' derived classes. See section Identifiers (Names).\n', jpayne@69: 'if': 'The "if" statement\n' jpayne@69: '******************\n' jpayne@69: '\n' jpayne@69: 'The "if" statement is used for conditional execution:\n' jpayne@69: '\n' jpayne@69: ' if_stmt ::= "if" expression ":" suite\n' jpayne@69: ' ("elif" expression ":" suite)*\n' jpayne@69: ' ["else" ":" suite]\n' jpayne@69: '\n' jpayne@69: 'It selects exactly one of the suites by evaluating the expressions ' jpayne@69: 'one\n' jpayne@69: 'by one until one is found to be true (see section Boolean operations\n' jpayne@69: 'for the definition of true and false); then that suite is executed\n' jpayne@69: '(and no other part of the "if" statement is executed or evaluated).\n' jpayne@69: 'If all expressions are false, the suite of the "else" clause, if\n' jpayne@69: 'present, is executed.\n', jpayne@69: 'imaginary': 'Imaginary literals\n' jpayne@69: '******************\n' jpayne@69: '\n' jpayne@69: 'Imaginary literals are described by the following lexical ' jpayne@69: 'definitions:\n' jpayne@69: '\n' jpayne@69: ' imagnumber ::= (floatnumber | digitpart) ("j" | "J")\n' jpayne@69: '\n' jpayne@69: 'An imaginary literal yields a complex number with a real part ' jpayne@69: 'of 0.0.\n' jpayne@69: 'Complex numbers are represented as a pair of floating point ' jpayne@69: 'numbers\n' jpayne@69: 'and have the same restrictions on their range. To create a ' jpayne@69: 'complex\n' jpayne@69: 'number with a nonzero real part, add a floating point number to ' jpayne@69: 'it,\n' jpayne@69: 'e.g., "(3+4j)". Some examples of imaginary literals:\n' jpayne@69: '\n' jpayne@69: ' 3.14j 10.j 10j .001j 1e100j 3.14e-10j ' jpayne@69: '3.14_15_93j\n', jpayne@69: 'import': 'The "import" statement\n' jpayne@69: '**********************\n' jpayne@69: '\n' jpayne@69: ' import_stmt ::= "import" module ["as" identifier] ("," ' jpayne@69: 'module ["as" identifier])*\n' jpayne@69: ' | "from" relative_module "import" identifier ' jpayne@69: '["as" identifier]\n' jpayne@69: ' ("," identifier ["as" identifier])*\n' jpayne@69: ' | "from" relative_module "import" "(" ' jpayne@69: 'identifier ["as" identifier]\n' jpayne@69: ' ("," identifier ["as" identifier])* [","] ")"\n' jpayne@69: ' | "from" module "import" "*"\n' jpayne@69: ' module ::= (identifier ".")* identifier\n' jpayne@69: ' relative_module ::= "."* module | "."+\n' jpayne@69: '\n' jpayne@69: 'The basic import statement (no "from" clause) is executed in two\n' jpayne@69: 'steps:\n' jpayne@69: '\n' jpayne@69: '1. find a module, loading and initializing it if necessary\n' jpayne@69: '\n' jpayne@69: '2. define a name or names in the local namespace for the scope\n' jpayne@69: ' where the "import" statement occurs.\n' jpayne@69: '\n' jpayne@69: 'When the statement contains multiple clauses (separated by commas) ' jpayne@69: 'the\n' jpayne@69: 'two steps are carried out separately for each clause, just as ' jpayne@69: 'though\n' jpayne@69: 'the clauses had been separated out into individual import ' jpayne@69: 'statements.\n' jpayne@69: '\n' jpayne@69: 'The details of the first step, finding and loading modules are\n' jpayne@69: 'described in greater detail in the section on the import system, ' jpayne@69: 'which\n' jpayne@69: 'also describes the various types of packages and modules that can ' jpayne@69: 'be\n' jpayne@69: 'imported, as well as all the hooks that can be used to customize ' jpayne@69: 'the\n' jpayne@69: 'import system. Note that failures in this step may indicate ' jpayne@69: 'either\n' jpayne@69: 'that the module could not be located, *or* that an error occurred\n' jpayne@69: 'while initializing the module, which includes execution of the\n' jpayne@69: 'module’s code.\n' jpayne@69: '\n' jpayne@69: 'If the requested module is retrieved successfully, it will be ' jpayne@69: 'made\n' jpayne@69: 'available in the local namespace in one of three ways:\n' jpayne@69: '\n' jpayne@69: '* If the module name is followed by "as", then the name following\n' jpayne@69: ' "as" is bound directly to the imported module.\n' jpayne@69: '\n' jpayne@69: '* If no other name is specified, and the module being imported is ' jpayne@69: 'a\n' jpayne@69: ' top level module, the module’s name is bound in the local ' jpayne@69: 'namespace\n' jpayne@69: ' as a reference to the imported module\n' jpayne@69: '\n' jpayne@69: '* If the module being imported is *not* a top level module, then ' jpayne@69: 'the\n' jpayne@69: ' name of the top level package that contains the module is bound ' jpayne@69: 'in\n' jpayne@69: ' the local namespace as a reference to the top level package. ' jpayne@69: 'The\n' jpayne@69: ' imported module must be accessed using its full qualified name\n' jpayne@69: ' rather than directly\n' jpayne@69: '\n' jpayne@69: 'The "from" form uses a slightly more complex process:\n' jpayne@69: '\n' jpayne@69: '1. find the module specified in the "from" clause, loading and\n' jpayne@69: ' initializing it if necessary;\n' jpayne@69: '\n' jpayne@69: '2. for each of the identifiers specified in the "import" clauses:\n' jpayne@69: '\n' jpayne@69: ' 1. check if the imported module has an attribute by that name\n' jpayne@69: '\n' jpayne@69: ' 2. if not, attempt to import a submodule with that name and ' jpayne@69: 'then\n' jpayne@69: ' check the imported module again for that attribute\n' jpayne@69: '\n' jpayne@69: ' 3. if the attribute is not found, "ImportError" is raised.\n' jpayne@69: '\n' jpayne@69: ' 4. otherwise, a reference to that value is stored in the local\n' jpayne@69: ' namespace, using the name in the "as" clause if it is ' jpayne@69: 'present,\n' jpayne@69: ' otherwise using the attribute name\n' jpayne@69: '\n' jpayne@69: 'Examples:\n' jpayne@69: '\n' jpayne@69: ' import foo # foo imported and bound locally\n' jpayne@69: ' import foo.bar.baz # foo.bar.baz imported, foo bound ' jpayne@69: 'locally\n' jpayne@69: ' import foo.bar.baz as fbb # foo.bar.baz imported and bound as ' jpayne@69: 'fbb\n' jpayne@69: ' from foo.bar import baz # foo.bar.baz imported and bound as ' jpayne@69: 'baz\n' jpayne@69: ' from foo import attr # foo imported and foo.attr bound as ' jpayne@69: 'attr\n' jpayne@69: '\n' jpayne@69: 'If the list of identifiers is replaced by a star ("\'*\'"), all ' jpayne@69: 'public\n' jpayne@69: 'names defined in the module are bound in the local namespace for ' jpayne@69: 'the\n' jpayne@69: 'scope where the "import" statement occurs.\n' jpayne@69: '\n' jpayne@69: 'The *public names* defined by a module are determined by checking ' jpayne@69: 'the\n' jpayne@69: 'module’s namespace for a variable named "__all__"; if defined, it ' jpayne@69: 'must\n' jpayne@69: 'be a sequence of strings which are names defined or imported by ' jpayne@69: 'that\n' jpayne@69: 'module. The names given in "__all__" are all considered public ' jpayne@69: 'and\n' jpayne@69: 'are required to exist. If "__all__" is not defined, the set of ' jpayne@69: 'public\n' jpayne@69: 'names includes all names found in the module’s namespace which do ' jpayne@69: 'not\n' jpayne@69: 'begin with an underscore character ("\'_\'"). "__all__" should ' jpayne@69: 'contain\n' jpayne@69: 'the entire public API. It is intended to avoid accidentally ' jpayne@69: 'exporting\n' jpayne@69: 'items that are not part of the API (such as library modules which ' jpayne@69: 'were\n' jpayne@69: 'imported and used within the module).\n' jpayne@69: '\n' jpayne@69: 'The wild card form of import — "from module import *" — is only\n' jpayne@69: 'allowed at the module level. Attempting to use it in class or\n' jpayne@69: 'function definitions will raise a "SyntaxError".\n' jpayne@69: '\n' jpayne@69: 'When specifying what module to import you do not have to specify ' jpayne@69: 'the\n' jpayne@69: 'absolute name of the module. When a module or package is ' jpayne@69: 'contained\n' jpayne@69: 'within another package it is possible to make a relative import ' jpayne@69: 'within\n' jpayne@69: 'the same top package without having to mention the package name. ' jpayne@69: 'By\n' jpayne@69: 'using leading dots in the specified module or package after "from" ' jpayne@69: 'you\n' jpayne@69: 'can specify how high to traverse up the current package hierarchy\n' jpayne@69: 'without specifying exact names. One leading dot means the current\n' jpayne@69: 'package where the module making the import exists. Two dots means ' jpayne@69: 'up\n' jpayne@69: 'one package level. Three dots is up two levels, etc. So if you ' jpayne@69: 'execute\n' jpayne@69: '"from . import mod" from a module in the "pkg" package then you ' jpayne@69: 'will\n' jpayne@69: 'end up importing "pkg.mod". If you execute "from ..subpkg2 import ' jpayne@69: 'mod"\n' jpayne@69: 'from within "pkg.subpkg1" you will import "pkg.subpkg2.mod". The\n' jpayne@69: 'specification for relative imports is contained in the Package\n' jpayne@69: 'Relative Imports section.\n' jpayne@69: '\n' jpayne@69: '"importlib.import_module()" is provided to support applications ' jpayne@69: 'that\n' jpayne@69: 'determine dynamically the modules to be loaded.\n' jpayne@69: '\n' jpayne@69: 'Raises an auditing event "import" with arguments "module", ' jpayne@69: '"filename",\n' jpayne@69: '"sys.path", "sys.meta_path", "sys.path_hooks".\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Future statements\n' jpayne@69: '=================\n' jpayne@69: '\n' jpayne@69: 'A *future statement* is a directive to the compiler that a ' jpayne@69: 'particular\n' jpayne@69: 'module should be compiled using syntax or semantics that will be\n' jpayne@69: 'available in a specified future release of Python where the ' jpayne@69: 'feature\n' jpayne@69: 'becomes standard.\n' jpayne@69: '\n' jpayne@69: 'The future statement is intended to ease migration to future ' jpayne@69: 'versions\n' jpayne@69: 'of Python that introduce incompatible changes to the language. ' jpayne@69: 'It\n' jpayne@69: 'allows use of the new features on a per-module basis before the\n' jpayne@69: 'release in which the feature becomes standard.\n' jpayne@69: '\n' jpayne@69: ' future_stmt ::= "from" "__future__" "import" feature ["as" ' jpayne@69: 'identifier]\n' jpayne@69: ' ("," feature ["as" identifier])*\n' jpayne@69: ' | "from" "__future__" "import" "(" feature ' jpayne@69: '["as" identifier]\n' jpayne@69: ' ("," feature ["as" identifier])* [","] ")"\n' jpayne@69: ' feature ::= identifier\n' jpayne@69: '\n' jpayne@69: 'A future statement must appear near the top of the module. The ' jpayne@69: 'only\n' jpayne@69: 'lines that can appear before a future statement are:\n' jpayne@69: '\n' jpayne@69: '* the module docstring (if any),\n' jpayne@69: '\n' jpayne@69: '* comments,\n' jpayne@69: '\n' jpayne@69: '* blank lines, and\n' jpayne@69: '\n' jpayne@69: '* other future statements.\n' jpayne@69: '\n' jpayne@69: 'The only feature in Python 3.7 that requires using the future\n' jpayne@69: 'statement is "annotations".\n' jpayne@69: '\n' jpayne@69: 'All historical features enabled by the future statement are still\n' jpayne@69: 'recognized by Python 3. The list includes "absolute_import",\n' jpayne@69: '"division", "generators", "generator_stop", "unicode_literals",\n' jpayne@69: '"print_function", "nested_scopes" and "with_statement". They are ' jpayne@69: 'all\n' jpayne@69: 'redundant because they are always enabled, and only kept for ' jpayne@69: 'backwards\n' jpayne@69: 'compatibility.\n' jpayne@69: '\n' jpayne@69: 'A future statement is recognized and treated specially at compile\n' jpayne@69: 'time: Changes to the semantics of core constructs are often\n' jpayne@69: 'implemented by generating different code. It may even be the ' jpayne@69: 'case\n' jpayne@69: 'that a new feature introduces new incompatible syntax (such as a ' jpayne@69: 'new\n' jpayne@69: 'reserved word), in which case the compiler may need to parse the\n' jpayne@69: 'module differently. Such decisions cannot be pushed off until\n' jpayne@69: 'runtime.\n' jpayne@69: '\n' jpayne@69: 'For any given release, the compiler knows which feature names ' jpayne@69: 'have\n' jpayne@69: 'been defined, and raises a compile-time error if a future ' jpayne@69: 'statement\n' jpayne@69: 'contains a feature not known to it.\n' jpayne@69: '\n' jpayne@69: 'The direct runtime semantics are the same as for any import ' jpayne@69: 'statement:\n' jpayne@69: 'there is a standard module "__future__", described later, and it ' jpayne@69: 'will\n' jpayne@69: 'be imported in the usual way at the time the future statement is\n' jpayne@69: 'executed.\n' jpayne@69: '\n' jpayne@69: 'The interesting runtime semantics depend on the specific feature\n' jpayne@69: 'enabled by the future statement.\n' jpayne@69: '\n' jpayne@69: 'Note that there is nothing special about the statement:\n' jpayne@69: '\n' jpayne@69: ' import __future__ [as name]\n' jpayne@69: '\n' jpayne@69: 'That is not a future statement; it’s an ordinary import statement ' jpayne@69: 'with\n' jpayne@69: 'no special semantics or syntax restrictions.\n' jpayne@69: '\n' jpayne@69: 'Code compiled by calls to the built-in functions "exec()" and\n' jpayne@69: '"compile()" that occur in a module "M" containing a future ' jpayne@69: 'statement\n' jpayne@69: 'will, by default, use the new syntax or semantics associated with ' jpayne@69: 'the\n' jpayne@69: 'future statement. This can be controlled by optional arguments ' jpayne@69: 'to\n' jpayne@69: '"compile()" — see the documentation of that function for details.\n' jpayne@69: '\n' jpayne@69: 'A future statement typed at an interactive interpreter prompt ' jpayne@69: 'will\n' jpayne@69: 'take effect for the rest of the interpreter session. If an\n' jpayne@69: 'interpreter is started with the "-i" option, is passed a script ' jpayne@69: 'name\n' jpayne@69: 'to execute, and the script includes a future statement, it will be ' jpayne@69: 'in\n' jpayne@69: 'effect in the interactive session started after the script is\n' jpayne@69: 'executed.\n' jpayne@69: '\n' jpayne@69: 'See also:\n' jpayne@69: '\n' jpayne@69: ' **PEP 236** - Back to the __future__\n' jpayne@69: ' The original proposal for the __future__ mechanism.\n', jpayne@69: 'in': 'Membership test operations\n' jpayne@69: '**************************\n' jpayne@69: '\n' jpayne@69: 'The operators "in" and "not in" test for membership. "x in s"\n' jpayne@69: 'evaluates to "True" if *x* is a member of *s*, and "False" otherwise.\n' jpayne@69: '"x not in s" returns the negation of "x in s". All built-in ' jpayne@69: 'sequences\n' jpayne@69: 'and set types support this as well as dictionary, for which "in" ' jpayne@69: 'tests\n' jpayne@69: 'whether the dictionary has a given key. For container types such as\n' jpayne@69: 'list, tuple, set, frozenset, dict, or collections.deque, the\n' jpayne@69: 'expression "x in y" is equivalent to "any(x is e or x == e for e in\n' jpayne@69: 'y)".\n' jpayne@69: '\n' jpayne@69: 'For the string and bytes types, "x in y" is "True" if and only if *x*\n' jpayne@69: 'is a substring of *y*. An equivalent test is "y.find(x) != -1".\n' jpayne@69: 'Empty strings are always considered to be a substring of any other\n' jpayne@69: 'string, so """ in "abc"" will return "True".\n' jpayne@69: '\n' jpayne@69: 'For user-defined classes which define the "__contains__()" method, "x\n' jpayne@69: 'in y" returns "True" if "y.__contains__(x)" returns a true value, and\n' jpayne@69: '"False" otherwise.\n' jpayne@69: '\n' jpayne@69: 'For user-defined classes which do not define "__contains__()" but do\n' jpayne@69: 'define "__iter__()", "x in y" is "True" if some value "z", for which\n' jpayne@69: 'the expression "x is z or x == z" is true, is produced while ' jpayne@69: 'iterating\n' jpayne@69: 'over "y". If an exception is raised during the iteration, it is as if\n' jpayne@69: '"in" raised that exception.\n' jpayne@69: '\n' jpayne@69: 'Lastly, the old-style iteration protocol is tried: if a class defines\n' jpayne@69: '"__getitem__()", "x in y" is "True" if and only if there is a non-\n' jpayne@69: 'negative integer index *i* such that "x is y[i] or x == y[i]", and no\n' jpayne@69: 'lower integer index raises the "IndexError" exception. (If any other\n' jpayne@69: 'exception is raised, it is as if "in" raised that exception).\n' jpayne@69: '\n' jpayne@69: 'The operator "not in" is defined to have the inverse truth value of\n' jpayne@69: '"in".\n', jpayne@69: 'integers': 'Integer literals\n' jpayne@69: '****************\n' jpayne@69: '\n' jpayne@69: 'Integer literals are described by the following lexical ' jpayne@69: 'definitions:\n' jpayne@69: '\n' jpayne@69: ' integer ::= decinteger | bininteger | octinteger | ' jpayne@69: 'hexinteger\n' jpayne@69: ' decinteger ::= nonzerodigit (["_"] digit)* | "0"+ (["_"] ' jpayne@69: '"0")*\n' jpayne@69: ' bininteger ::= "0" ("b" | "B") (["_"] bindigit)+\n' jpayne@69: ' octinteger ::= "0" ("o" | "O") (["_"] octdigit)+\n' jpayne@69: ' hexinteger ::= "0" ("x" | "X") (["_"] hexdigit)+\n' jpayne@69: ' nonzerodigit ::= "1"..."9"\n' jpayne@69: ' digit ::= "0"..."9"\n' jpayne@69: ' bindigit ::= "0" | "1"\n' jpayne@69: ' octdigit ::= "0"..."7"\n' jpayne@69: ' hexdigit ::= digit | "a"..."f" | "A"..."F"\n' jpayne@69: '\n' jpayne@69: 'There is no limit for the length of integer literals apart from ' jpayne@69: 'what\n' jpayne@69: 'can be stored in available memory.\n' jpayne@69: '\n' jpayne@69: 'Underscores are ignored for determining the numeric value of ' jpayne@69: 'the\n' jpayne@69: 'literal. They can be used to group digits for enhanced ' jpayne@69: 'readability.\n' jpayne@69: 'One underscore can occur between digits, and after base ' jpayne@69: 'specifiers\n' jpayne@69: 'like "0x".\n' jpayne@69: '\n' jpayne@69: 'Note that leading zeros in a non-zero decimal number are not ' jpayne@69: 'allowed.\n' jpayne@69: 'This is for disambiguation with C-style octal literals, which ' jpayne@69: 'Python\n' jpayne@69: 'used before version 3.0.\n' jpayne@69: '\n' jpayne@69: 'Some examples of integer literals:\n' jpayne@69: '\n' jpayne@69: ' 7 2147483647 0o177 0b100110111\n' jpayne@69: ' 3 79228162514264337593543950336 0o377 0xdeadbeef\n' jpayne@69: ' 100_000_000_000 0b_1110_0101\n' jpayne@69: '\n' jpayne@69: 'Changed in version 3.6: Underscores are now allowed for ' jpayne@69: 'grouping\n' jpayne@69: 'purposes in literals.\n', jpayne@69: 'lambda': 'Lambdas\n' jpayne@69: '*******\n' jpayne@69: '\n' jpayne@69: ' lambda_expr ::= "lambda" [parameter_list] ":" ' jpayne@69: 'expression\n' jpayne@69: ' lambda_expr_nocond ::= "lambda" [parameter_list] ":" ' jpayne@69: 'expression_nocond\n' jpayne@69: '\n' jpayne@69: 'Lambda expressions (sometimes called lambda forms) are used to ' jpayne@69: 'create\n' jpayne@69: 'anonymous functions. The expression "lambda parameters: ' jpayne@69: 'expression"\n' jpayne@69: 'yields a function object. The unnamed object behaves like a ' jpayne@69: 'function\n' jpayne@69: 'object defined with:\n' jpayne@69: '\n' jpayne@69: ' def (parameters):\n' jpayne@69: ' return expression\n' jpayne@69: '\n' jpayne@69: 'See section Function definitions for the syntax of parameter ' jpayne@69: 'lists.\n' jpayne@69: 'Note that functions created with lambda expressions cannot ' jpayne@69: 'contain\n' jpayne@69: 'statements or annotations.\n', jpayne@69: 'lists': 'List displays\n' jpayne@69: '*************\n' jpayne@69: '\n' jpayne@69: 'A list display is a possibly empty series of expressions enclosed ' jpayne@69: 'in\n' jpayne@69: 'square brackets:\n' jpayne@69: '\n' jpayne@69: ' list_display ::= "[" [starred_list | comprehension] "]"\n' jpayne@69: '\n' jpayne@69: 'A list display yields a new list object, the contents being ' jpayne@69: 'specified\n' jpayne@69: 'by either a list of expressions or a comprehension. When a comma-\n' jpayne@69: 'separated list of expressions is supplied, its elements are ' jpayne@69: 'evaluated\n' jpayne@69: 'from left to right and placed into the list object in that order.\n' jpayne@69: 'When a comprehension is supplied, the list is constructed from the\n' jpayne@69: 'elements resulting from the comprehension.\n', jpayne@69: 'naming': 'Naming and binding\n' jpayne@69: '******************\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Binding of names\n' jpayne@69: '================\n' jpayne@69: '\n' jpayne@69: '*Names* refer to objects. Names are introduced by name binding\n' jpayne@69: 'operations.\n' jpayne@69: '\n' jpayne@69: 'The following constructs bind names: formal parameters to ' jpayne@69: 'functions,\n' jpayne@69: '"import" statements, class and function definitions (these bind ' jpayne@69: 'the\n' jpayne@69: 'class or function name in the defining block), and targets that ' jpayne@69: 'are\n' jpayne@69: 'identifiers if occurring in an assignment, "for" loop header, or ' jpayne@69: 'after\n' jpayne@69: '"as" in a "with" statement or "except" clause. The "import" ' jpayne@69: 'statement\n' jpayne@69: 'of the form "from ... import *" binds all names defined in the\n' jpayne@69: 'imported module, except those beginning with an underscore. This ' jpayne@69: 'form\n' jpayne@69: 'may only be used at the module level.\n' jpayne@69: '\n' jpayne@69: 'A target occurring in a "del" statement is also considered bound ' jpayne@69: 'for\n' jpayne@69: 'this purpose (though the actual semantics are to unbind the ' jpayne@69: 'name).\n' jpayne@69: '\n' jpayne@69: 'Each assignment or import statement occurs within a block defined ' jpayne@69: 'by a\n' jpayne@69: 'class or function definition or at the module level (the ' jpayne@69: 'top-level\n' jpayne@69: 'code block).\n' jpayne@69: '\n' jpayne@69: 'If a name is bound in a block, it is a local variable of that ' jpayne@69: 'block,\n' jpayne@69: 'unless declared as "nonlocal" or "global". If a name is bound at ' jpayne@69: 'the\n' jpayne@69: 'module level, it is a global variable. (The variables of the ' jpayne@69: 'module\n' jpayne@69: 'code block are local and global.) If a variable is used in a ' jpayne@69: 'code\n' jpayne@69: 'block but not defined there, it is a *free variable*.\n' jpayne@69: '\n' jpayne@69: 'Each occurrence of a name in the program text refers to the ' jpayne@69: '*binding*\n' jpayne@69: 'of that name established by the following name resolution rules.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Resolution of names\n' jpayne@69: '===================\n' jpayne@69: '\n' jpayne@69: 'A *scope* defines the visibility of a name within a block. If a ' jpayne@69: 'local\n' jpayne@69: 'variable is defined in a block, its scope includes that block. If ' jpayne@69: 'the\n' jpayne@69: 'definition occurs in a function block, the scope extends to any ' jpayne@69: 'blocks\n' jpayne@69: 'contained within the defining one, unless a contained block ' jpayne@69: 'introduces\n' jpayne@69: 'a different binding for the name.\n' jpayne@69: '\n' jpayne@69: 'When a name is used in a code block, it is resolved using the ' jpayne@69: 'nearest\n' jpayne@69: 'enclosing scope. The set of all such scopes visible to a code ' jpayne@69: 'block\n' jpayne@69: 'is called the block’s *environment*.\n' jpayne@69: '\n' jpayne@69: 'When a name is not found at all, a "NameError" exception is ' jpayne@69: 'raised. If\n' jpayne@69: 'the current scope is a function scope, and the name refers to a ' jpayne@69: 'local\n' jpayne@69: 'variable that has not yet been bound to a value at the point where ' jpayne@69: 'the\n' jpayne@69: 'name is used, an "UnboundLocalError" exception is raised.\n' jpayne@69: '"UnboundLocalError" is a subclass of "NameError".\n' jpayne@69: '\n' jpayne@69: 'If a name binding operation occurs anywhere within a code block, ' jpayne@69: 'all\n' jpayne@69: 'uses of the name within the block are treated as references to ' jpayne@69: 'the\n' jpayne@69: 'current block. This can lead to errors when a name is used within ' jpayne@69: 'a\n' jpayne@69: 'block before it is bound. This rule is subtle. Python lacks\n' jpayne@69: 'declarations and allows name binding operations to occur anywhere\n' jpayne@69: 'within a code block. The local variables of a code block can be\n' jpayne@69: 'determined by scanning the entire text of the block for name ' jpayne@69: 'binding\n' jpayne@69: 'operations.\n' jpayne@69: '\n' jpayne@69: 'If the "global" statement occurs within a block, all uses of the ' jpayne@69: 'name\n' jpayne@69: 'specified in the statement refer to the binding of that name in ' jpayne@69: 'the\n' jpayne@69: 'top-level namespace. Names are resolved in the top-level ' jpayne@69: 'namespace by\n' jpayne@69: 'searching the global namespace, i.e. the namespace of the module\n' jpayne@69: 'containing the code block, and the builtins namespace, the ' jpayne@69: 'namespace\n' jpayne@69: 'of the module "builtins". The global namespace is searched ' jpayne@69: 'first. If\n' jpayne@69: 'the name is not found there, the builtins namespace is searched. ' jpayne@69: 'The\n' jpayne@69: '"global" statement must precede all uses of the name.\n' jpayne@69: '\n' jpayne@69: 'The "global" statement has the same scope as a name binding ' jpayne@69: 'operation\n' jpayne@69: 'in the same block. If the nearest enclosing scope for a free ' jpayne@69: 'variable\n' jpayne@69: 'contains a global statement, the free variable is treated as a ' jpayne@69: 'global.\n' jpayne@69: '\n' jpayne@69: 'The "nonlocal" statement causes corresponding names to refer to\n' jpayne@69: 'previously bound variables in the nearest enclosing function ' jpayne@69: 'scope.\n' jpayne@69: '"SyntaxError" is raised at compile time if the given name does ' jpayne@69: 'not\n' jpayne@69: 'exist in any enclosing function scope.\n' jpayne@69: '\n' jpayne@69: 'The namespace for a module is automatically created the first time ' jpayne@69: 'a\n' jpayne@69: 'module is imported. The main module for a script is always ' jpayne@69: 'called\n' jpayne@69: '"__main__".\n' jpayne@69: '\n' jpayne@69: 'Class definition blocks and arguments to "exec()" and "eval()" ' jpayne@69: 'are\n' jpayne@69: 'special in the context of name resolution. A class definition is ' jpayne@69: 'an\n' jpayne@69: 'executable statement that may use and define names. These ' jpayne@69: 'references\n' jpayne@69: 'follow the normal rules for name resolution with an exception ' jpayne@69: 'that\n' jpayne@69: 'unbound local variables are looked up in the global namespace. ' jpayne@69: 'The\n' jpayne@69: 'namespace of the class definition becomes the attribute dictionary ' jpayne@69: 'of\n' jpayne@69: 'the class. The scope of names defined in a class block is limited ' jpayne@69: 'to\n' jpayne@69: 'the class block; it does not extend to the code blocks of methods ' jpayne@69: '–\n' jpayne@69: 'this includes comprehensions and generator expressions since they ' jpayne@69: 'are\n' jpayne@69: 'implemented using a function scope. This means that the ' jpayne@69: 'following\n' jpayne@69: 'will fail:\n' jpayne@69: '\n' jpayne@69: ' class A:\n' jpayne@69: ' a = 42\n' jpayne@69: ' b = list(a + i for i in range(10))\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Builtins and restricted execution\n' jpayne@69: '=================================\n' jpayne@69: '\n' jpayne@69: '**CPython implementation detail:** Users should not touch\n' jpayne@69: '"__builtins__"; it is strictly an implementation detail. Users\n' jpayne@69: 'wanting to override values in the builtins namespace should ' jpayne@69: '"import"\n' jpayne@69: 'the "builtins" module and modify its attributes appropriately.\n' jpayne@69: '\n' jpayne@69: 'The builtins namespace associated with the execution of a code ' jpayne@69: 'block\n' jpayne@69: 'is actually found by looking up the name "__builtins__" in its ' jpayne@69: 'global\n' jpayne@69: 'namespace; this should be a dictionary or a module (in the latter ' jpayne@69: 'case\n' jpayne@69: 'the module’s dictionary is used). By default, when in the ' jpayne@69: '"__main__"\n' jpayne@69: 'module, "__builtins__" is the built-in module "builtins"; when in ' jpayne@69: 'any\n' jpayne@69: 'other module, "__builtins__" is an alias for the dictionary of ' jpayne@69: 'the\n' jpayne@69: '"builtins" module itself.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Interaction with dynamic features\n' jpayne@69: '=================================\n' jpayne@69: '\n' jpayne@69: 'Name resolution of free variables occurs at runtime, not at ' jpayne@69: 'compile\n' jpayne@69: 'time. This means that the following code will print 42:\n' jpayne@69: '\n' jpayne@69: ' i = 10\n' jpayne@69: ' def f():\n' jpayne@69: ' print(i)\n' jpayne@69: ' i = 42\n' jpayne@69: ' f()\n' jpayne@69: '\n' jpayne@69: 'The "eval()" and "exec()" functions do not have access to the ' jpayne@69: 'full\n' jpayne@69: 'environment for resolving names. Names may be resolved in the ' jpayne@69: 'local\n' jpayne@69: 'and global namespaces of the caller. Free variables are not ' jpayne@69: 'resolved\n' jpayne@69: 'in the nearest enclosing namespace, but in the global namespace. ' jpayne@69: '[1]\n' jpayne@69: 'The "exec()" and "eval()" functions have optional arguments to\n' jpayne@69: 'override the global and local namespace. If only one namespace ' jpayne@69: 'is\n' jpayne@69: 'specified, it is used for both.\n', jpayne@69: 'nonlocal': 'The "nonlocal" statement\n' jpayne@69: '************************\n' jpayne@69: '\n' jpayne@69: ' nonlocal_stmt ::= "nonlocal" identifier ("," identifier)*\n' jpayne@69: '\n' jpayne@69: 'The "nonlocal" statement causes the listed identifiers to refer ' jpayne@69: 'to\n' jpayne@69: 'previously bound variables in the nearest enclosing scope ' jpayne@69: 'excluding\n' jpayne@69: 'globals. This is important because the default behavior for ' jpayne@69: 'binding is\n' jpayne@69: 'to search the local namespace first. The statement allows\n' jpayne@69: 'encapsulated code to rebind variables outside of the local ' jpayne@69: 'scope\n' jpayne@69: 'besides the global (module) scope.\n' jpayne@69: '\n' jpayne@69: 'Names listed in a "nonlocal" statement, unlike those listed in ' jpayne@69: 'a\n' jpayne@69: '"global" statement, must refer to pre-existing bindings in an\n' jpayne@69: 'enclosing scope (the scope in which a new binding should be ' jpayne@69: 'created\n' jpayne@69: 'cannot be determined unambiguously).\n' jpayne@69: '\n' jpayne@69: 'Names listed in a "nonlocal" statement must not collide with ' jpayne@69: 'pre-\n' jpayne@69: 'existing bindings in the local scope.\n' jpayne@69: '\n' jpayne@69: 'See also:\n' jpayne@69: '\n' jpayne@69: ' **PEP 3104** - Access to Names in Outer Scopes\n' jpayne@69: ' The specification for the "nonlocal" statement.\n', jpayne@69: 'numbers': 'Numeric literals\n' jpayne@69: '****************\n' jpayne@69: '\n' jpayne@69: 'There are three types of numeric literals: integers, floating ' jpayne@69: 'point\n' jpayne@69: 'numbers, and imaginary numbers. There are no complex literals\n' jpayne@69: '(complex numbers can be formed by adding a real number and an\n' jpayne@69: 'imaginary number).\n' jpayne@69: '\n' jpayne@69: 'Note that numeric literals do not include a sign; a phrase like ' jpayne@69: '"-1"\n' jpayne@69: 'is actually an expression composed of the unary operator ‘"-"‘ ' jpayne@69: 'and the\n' jpayne@69: 'literal "1".\n', jpayne@69: 'numeric-types': 'Emulating numeric types\n' jpayne@69: '***********************\n' jpayne@69: '\n' jpayne@69: 'The following methods can be defined to emulate numeric ' jpayne@69: 'objects.\n' jpayne@69: 'Methods corresponding to operations that are not supported ' jpayne@69: 'by the\n' jpayne@69: 'particular kind of number implemented (e.g., bitwise ' jpayne@69: 'operations for\n' jpayne@69: 'non-integral numbers) should be left undefined.\n' jpayne@69: '\n' jpayne@69: 'object.__add__(self, other)\n' jpayne@69: 'object.__sub__(self, other)\n' jpayne@69: 'object.__mul__(self, other)\n' jpayne@69: 'object.__matmul__(self, other)\n' jpayne@69: 'object.__truediv__(self, other)\n' jpayne@69: 'object.__floordiv__(self, other)\n' jpayne@69: 'object.__mod__(self, other)\n' jpayne@69: 'object.__divmod__(self, other)\n' jpayne@69: 'object.__pow__(self, other[, modulo])\n' jpayne@69: 'object.__lshift__(self, other)\n' jpayne@69: 'object.__rshift__(self, other)\n' jpayne@69: 'object.__and__(self, other)\n' jpayne@69: 'object.__xor__(self, other)\n' jpayne@69: 'object.__or__(self, other)\n' jpayne@69: '\n' jpayne@69: ' These methods are called to implement the binary ' jpayne@69: 'arithmetic\n' jpayne@69: ' operations ("+", "-", "*", "@", "/", "//", "%", ' jpayne@69: '"divmod()",\n' jpayne@69: ' "pow()", "**", "<<", ">>", "&", "^", "|"). For ' jpayne@69: 'instance, to\n' jpayne@69: ' evaluate the expression "x + y", where *x* is an ' jpayne@69: 'instance of a\n' jpayne@69: ' class that has an "__add__()" method, "x.__add__(y)" is ' jpayne@69: 'called.\n' jpayne@69: ' The "__divmod__()" method should be the equivalent to ' jpayne@69: 'using\n' jpayne@69: ' "__floordiv__()" and "__mod__()"; it should not be ' jpayne@69: 'related to\n' jpayne@69: ' "__truediv__()". Note that "__pow__()" should be ' jpayne@69: 'defined to accept\n' jpayne@69: ' an optional third argument if the ternary version of the ' jpayne@69: 'built-in\n' jpayne@69: ' "pow()" function is to be supported.\n' jpayne@69: '\n' jpayne@69: ' If one of those methods does not support the operation ' jpayne@69: 'with the\n' jpayne@69: ' supplied arguments, it should return "NotImplemented".\n' jpayne@69: '\n' jpayne@69: 'object.__radd__(self, other)\n' jpayne@69: 'object.__rsub__(self, other)\n' jpayne@69: 'object.__rmul__(self, other)\n' jpayne@69: 'object.__rmatmul__(self, other)\n' jpayne@69: 'object.__rtruediv__(self, other)\n' jpayne@69: 'object.__rfloordiv__(self, other)\n' jpayne@69: 'object.__rmod__(self, other)\n' jpayne@69: 'object.__rdivmod__(self, other)\n' jpayne@69: 'object.__rpow__(self, other)\n' jpayne@69: 'object.__rlshift__(self, other)\n' jpayne@69: 'object.__rrshift__(self, other)\n' jpayne@69: 'object.__rand__(self, other)\n' jpayne@69: 'object.__rxor__(self, other)\n' jpayne@69: 'object.__ror__(self, other)\n' jpayne@69: '\n' jpayne@69: ' These methods are called to implement the binary ' jpayne@69: 'arithmetic\n' jpayne@69: ' operations ("+", "-", "*", "@", "/", "//", "%", ' jpayne@69: '"divmod()",\n' jpayne@69: ' "pow()", "**", "<<", ">>", "&", "^", "|") with reflected ' jpayne@69: '(swapped)\n' jpayne@69: ' operands. These functions are only called if the left ' jpayne@69: 'operand does\n' jpayne@69: ' not support the corresponding operation [3] and the ' jpayne@69: 'operands are of\n' jpayne@69: ' different types. [4] For instance, to evaluate the ' jpayne@69: 'expression "x -\n' jpayne@69: ' y", where *y* is an instance of a class that has an ' jpayne@69: '"__rsub__()"\n' jpayne@69: ' method, "y.__rsub__(x)" is called if "x.__sub__(y)" ' jpayne@69: 'returns\n' jpayne@69: ' *NotImplemented*.\n' jpayne@69: '\n' jpayne@69: ' Note that ternary "pow()" will not try calling ' jpayne@69: '"__rpow__()" (the\n' jpayne@69: ' coercion rules would become too complicated).\n' jpayne@69: '\n' jpayne@69: ' Note: If the right operand’s type is a subclass of the ' jpayne@69: 'left\n' jpayne@69: ' operand’s type and that subclass provides the ' jpayne@69: 'reflected method\n' jpayne@69: ' for the operation, this method will be called before ' jpayne@69: 'the left\n' jpayne@69: ' operand’s non-reflected method. This behavior allows ' jpayne@69: 'subclasses\n' jpayne@69: ' to override their ancestors’ operations.\n' jpayne@69: '\n' jpayne@69: 'object.__iadd__(self, other)\n' jpayne@69: 'object.__isub__(self, other)\n' jpayne@69: 'object.__imul__(self, other)\n' jpayne@69: 'object.__imatmul__(self, other)\n' jpayne@69: 'object.__itruediv__(self, other)\n' jpayne@69: 'object.__ifloordiv__(self, other)\n' jpayne@69: 'object.__imod__(self, other)\n' jpayne@69: 'object.__ipow__(self, other[, modulo])\n' jpayne@69: 'object.__ilshift__(self, other)\n' jpayne@69: 'object.__irshift__(self, other)\n' jpayne@69: 'object.__iand__(self, other)\n' jpayne@69: 'object.__ixor__(self, other)\n' jpayne@69: 'object.__ior__(self, other)\n' jpayne@69: '\n' jpayne@69: ' These methods are called to implement the augmented ' jpayne@69: 'arithmetic\n' jpayne@69: ' assignments ("+=", "-=", "*=", "@=", "/=", "//=", "%=", ' jpayne@69: '"**=",\n' jpayne@69: ' "<<=", ">>=", "&=", "^=", "|="). These methods should ' jpayne@69: 'attempt to\n' jpayne@69: ' do the operation in-place (modifying *self*) and return ' jpayne@69: 'the result\n' jpayne@69: ' (which could be, but does not have to be, *self*). If a ' jpayne@69: 'specific\n' jpayne@69: ' method is not defined, the augmented assignment falls ' jpayne@69: 'back to the\n' jpayne@69: ' normal methods. For instance, if *x* is an instance of ' jpayne@69: 'a class\n' jpayne@69: ' with an "__iadd__()" method, "x += y" is equivalent to ' jpayne@69: '"x =\n' jpayne@69: ' x.__iadd__(y)" . Otherwise, "x.__add__(y)" and ' jpayne@69: '"y.__radd__(x)" are\n' jpayne@69: ' considered, as with the evaluation of "x + y". In ' jpayne@69: 'certain\n' jpayne@69: ' situations, augmented assignment can result in ' jpayne@69: 'unexpected errors\n' jpayne@69: ' (see Why does a_tuple[i] += [‘item’] raise an exception ' jpayne@69: 'when the\n' jpayne@69: ' addition works?), but this behavior is in fact part of ' jpayne@69: 'the data\n' jpayne@69: ' model.\n' jpayne@69: '\n' jpayne@69: 'object.__neg__(self)\n' jpayne@69: 'object.__pos__(self)\n' jpayne@69: 'object.__abs__(self)\n' jpayne@69: 'object.__invert__(self)\n' jpayne@69: '\n' jpayne@69: ' Called to implement the unary arithmetic operations ' jpayne@69: '("-", "+",\n' jpayne@69: ' "abs()" and "~").\n' jpayne@69: '\n' jpayne@69: 'object.__complex__(self)\n' jpayne@69: 'object.__int__(self)\n' jpayne@69: 'object.__float__(self)\n' jpayne@69: '\n' jpayne@69: ' Called to implement the built-in functions "complex()", ' jpayne@69: '"int()" and\n' jpayne@69: ' "float()". Should return a value of the appropriate ' jpayne@69: 'type.\n' jpayne@69: '\n' jpayne@69: 'object.__index__(self)\n' jpayne@69: '\n' jpayne@69: ' Called to implement "operator.index()", and whenever ' jpayne@69: 'Python needs\n' jpayne@69: ' to losslessly convert the numeric object to an integer ' jpayne@69: 'object (such\n' jpayne@69: ' as in slicing, or in the built-in "bin()", "hex()" and ' jpayne@69: '"oct()"\n' jpayne@69: ' functions). Presence of this method indicates that the ' jpayne@69: 'numeric\n' jpayne@69: ' object is an integer type. Must return an integer.\n' jpayne@69: '\n' jpayne@69: ' If "__int__()", "__float__()" and "__complex__()" are ' jpayne@69: 'not defined\n' jpayne@69: ' then corresponding built-in functions "int()", "float()" ' jpayne@69: 'and\n' jpayne@69: ' "complex()" fall back to "__index__()".\n' jpayne@69: '\n' jpayne@69: 'object.__round__(self[, ndigits])\n' jpayne@69: 'object.__trunc__(self)\n' jpayne@69: 'object.__floor__(self)\n' jpayne@69: 'object.__ceil__(self)\n' jpayne@69: '\n' jpayne@69: ' Called to implement the built-in function "round()" and ' jpayne@69: '"math"\n' jpayne@69: ' functions "trunc()", "floor()" and "ceil()". Unless ' jpayne@69: '*ndigits* is\n' jpayne@69: ' passed to "__round__()" all these methods should return ' jpayne@69: 'the value\n' jpayne@69: ' of the object truncated to an "Integral" (typically an ' jpayne@69: '"int").\n' jpayne@69: '\n' jpayne@69: ' If "__int__()" is not defined then the built-in function ' jpayne@69: '"int()"\n' jpayne@69: ' falls back to "__trunc__()".\n', jpayne@69: 'objects': 'Objects, values and types\n' jpayne@69: '*************************\n' jpayne@69: '\n' jpayne@69: '*Objects* are Python’s abstraction for data. All data in a ' jpayne@69: 'Python\n' jpayne@69: 'program is represented by objects or by relations between ' jpayne@69: 'objects. (In\n' jpayne@69: 'a sense, and in conformance to Von Neumann’s model of a “stored\n' jpayne@69: 'program computer,” code is also represented by objects.)\n' jpayne@69: '\n' jpayne@69: 'Every object has an identity, a type and a value. An object’s\n' jpayne@69: '*identity* never changes once it has been created; you may think ' jpayne@69: 'of it\n' jpayne@69: 'as the object’s address in memory. The ‘"is"’ operator compares ' jpayne@69: 'the\n' jpayne@69: 'identity of two objects; the "id()" function returns an integer\n' jpayne@69: 'representing its identity.\n' jpayne@69: '\n' jpayne@69: '**CPython implementation detail:** For CPython, "id(x)" is the ' jpayne@69: 'memory\n' jpayne@69: 'address where "x" is stored.\n' jpayne@69: '\n' jpayne@69: 'An object’s type determines the operations that the object ' jpayne@69: 'supports\n' jpayne@69: '(e.g., “does it have a length?”) and also defines the possible ' jpayne@69: 'values\n' jpayne@69: 'for objects of that type. The "type()" function returns an ' jpayne@69: 'object’s\n' jpayne@69: 'type (which is an object itself). Like its identity, an ' jpayne@69: 'object’s\n' jpayne@69: '*type* is also unchangeable. [1]\n' jpayne@69: '\n' jpayne@69: 'The *value* of some objects can change. Objects whose value can\n' jpayne@69: 'change are said to be *mutable*; objects whose value is ' jpayne@69: 'unchangeable\n' jpayne@69: 'once they are created are called *immutable*. (The value of an\n' jpayne@69: 'immutable container object that contains a reference to a ' jpayne@69: 'mutable\n' jpayne@69: 'object can change when the latter’s value is changed; however ' jpayne@69: 'the\n' jpayne@69: 'container is still considered immutable, because the collection ' jpayne@69: 'of\n' jpayne@69: 'objects it contains cannot be changed. So, immutability is not\n' jpayne@69: 'strictly the same as having an unchangeable value, it is more ' jpayne@69: 'subtle.)\n' jpayne@69: 'An object’s mutability is determined by its type; for instance,\n' jpayne@69: 'numbers, strings and tuples are immutable, while dictionaries ' jpayne@69: 'and\n' jpayne@69: 'lists are mutable.\n' jpayne@69: '\n' jpayne@69: 'Objects are never explicitly destroyed; however, when they ' jpayne@69: 'become\n' jpayne@69: 'unreachable they may be garbage-collected. An implementation is\n' jpayne@69: 'allowed to postpone garbage collection or omit it altogether — it ' jpayne@69: 'is a\n' jpayne@69: 'matter of implementation quality how garbage collection is\n' jpayne@69: 'implemented, as long as no objects are collected that are still\n' jpayne@69: 'reachable.\n' jpayne@69: '\n' jpayne@69: '**CPython implementation detail:** CPython currently uses a ' jpayne@69: 'reference-\n' jpayne@69: 'counting scheme with (optional) delayed detection of cyclically ' jpayne@69: 'linked\n' jpayne@69: 'garbage, which collects most objects as soon as they become\n' jpayne@69: 'unreachable, but is not guaranteed to collect garbage containing\n' jpayne@69: 'circular references. See the documentation of the "gc" module ' jpayne@69: 'for\n' jpayne@69: 'information on controlling the collection of cyclic garbage. ' jpayne@69: 'Other\n' jpayne@69: 'implementations act differently and CPython may change. Do not ' jpayne@69: 'depend\n' jpayne@69: 'on immediate finalization of objects when they become unreachable ' jpayne@69: '(so\n' jpayne@69: 'you should always close files explicitly).\n' jpayne@69: '\n' jpayne@69: 'Note that the use of the implementation’s tracing or debugging\n' jpayne@69: 'facilities may keep objects alive that would normally be ' jpayne@69: 'collectable.\n' jpayne@69: 'Also note that catching an exception with a ‘"try"…"except"’ ' jpayne@69: 'statement\n' jpayne@69: 'may keep objects alive.\n' jpayne@69: '\n' jpayne@69: 'Some objects contain references to “external” resources such as ' jpayne@69: 'open\n' jpayne@69: 'files or windows. It is understood that these resources are ' jpayne@69: 'freed\n' jpayne@69: 'when the object is garbage-collected, but since garbage ' jpayne@69: 'collection is\n' jpayne@69: 'not guaranteed to happen, such objects also provide an explicit ' jpayne@69: 'way to\n' jpayne@69: 'release the external resource, usually a "close()" method. ' jpayne@69: 'Programs\n' jpayne@69: 'are strongly recommended to explicitly close such objects. The\n' jpayne@69: '‘"try"…"finally"’ statement and the ‘"with"’ statement provide\n' jpayne@69: 'convenient ways to do this.\n' jpayne@69: '\n' jpayne@69: 'Some objects contain references to other objects; these are ' jpayne@69: 'called\n' jpayne@69: '*containers*. Examples of containers are tuples, lists and\n' jpayne@69: 'dictionaries. The references are part of a container’s value. ' jpayne@69: 'In\n' jpayne@69: 'most cases, when we talk about the value of a container, we imply ' jpayne@69: 'the\n' jpayne@69: 'values, not the identities of the contained objects; however, ' jpayne@69: 'when we\n' jpayne@69: 'talk about the mutability of a container, only the identities of ' jpayne@69: 'the\n' jpayne@69: 'immediately contained objects are implied. So, if an immutable\n' jpayne@69: 'container (like a tuple) contains a reference to a mutable ' jpayne@69: 'object, its\n' jpayne@69: 'value changes if that mutable object is changed.\n' jpayne@69: '\n' jpayne@69: 'Types affect almost all aspects of object behavior. Even the\n' jpayne@69: 'importance of object identity is affected in some sense: for ' jpayne@69: 'immutable\n' jpayne@69: 'types, operations that compute new values may actually return a\n' jpayne@69: 'reference to any existing object with the same type and value, ' jpayne@69: 'while\n' jpayne@69: 'for mutable objects this is not allowed. E.g., after "a = 1; b = ' jpayne@69: '1",\n' jpayne@69: '"a" and "b" may or may not refer to the same object with the ' jpayne@69: 'value\n' jpayne@69: 'one, depending on the implementation, but after "c = []; d = []", ' jpayne@69: '"c"\n' jpayne@69: 'and "d" are guaranteed to refer to two different, unique, newly\n' jpayne@69: 'created empty lists. (Note that "c = d = []" assigns the same ' jpayne@69: 'object\n' jpayne@69: 'to both "c" and "d".)\n', jpayne@69: 'operator-summary': 'Operator precedence\n' jpayne@69: '*******************\n' jpayne@69: '\n' jpayne@69: 'The following table summarizes the operator precedence ' jpayne@69: 'in Python, from\n' jpayne@69: 'lowest precedence (least binding) to highest precedence ' jpayne@69: '(most\n' jpayne@69: 'binding). Operators in the same box have the same ' jpayne@69: 'precedence. Unless\n' jpayne@69: 'the syntax is explicitly given, operators are binary. ' jpayne@69: 'Operators in\n' jpayne@69: 'the same box group left to right (except for ' jpayne@69: 'exponentiation, which\n' jpayne@69: 'groups from right to left).\n' jpayne@69: '\n' jpayne@69: 'Note that comparisons, membership tests, and identity ' jpayne@69: 'tests, all have\n' jpayne@69: 'the same precedence and have a left-to-right chaining ' jpayne@69: 'feature as\n' jpayne@69: 'described in the Comparisons section.\n' jpayne@69: '\n' jpayne@69: '+-------------------------------------------------+---------------------------------------+\n' jpayne@69: '| Operator | ' jpayne@69: 'Description |\n' jpayne@69: '|=================================================|=======================================|\n' jpayne@69: '| ":=" | ' jpayne@69: 'Assignment expression |\n' jpayne@69: '+-------------------------------------------------+---------------------------------------+\n' jpayne@69: '| "lambda" | ' jpayne@69: 'Lambda expression |\n' jpayne@69: '+-------------------------------------------------+---------------------------------------+\n' jpayne@69: '| "if" – "else" | ' jpayne@69: 'Conditional expression |\n' jpayne@69: '+-------------------------------------------------+---------------------------------------+\n' jpayne@69: '| "or" | ' jpayne@69: 'Boolean OR |\n' jpayne@69: '+-------------------------------------------------+---------------------------------------+\n' jpayne@69: '| "and" | ' jpayne@69: 'Boolean AND |\n' jpayne@69: '+-------------------------------------------------+---------------------------------------+\n' jpayne@69: '| "not" "x" | ' jpayne@69: 'Boolean NOT |\n' jpayne@69: '+-------------------------------------------------+---------------------------------------+\n' jpayne@69: '| "in", "not in", "is", "is not", "<", "<=", ">", | ' jpayne@69: 'Comparisons, including membership |\n' jpayne@69: '| ">=", "!=", "==" | ' jpayne@69: 'tests and identity tests |\n' jpayne@69: '+-------------------------------------------------+---------------------------------------+\n' jpayne@69: '| "|" | ' jpayne@69: 'Bitwise OR |\n' jpayne@69: '+-------------------------------------------------+---------------------------------------+\n' jpayne@69: '| "^" | ' jpayne@69: 'Bitwise XOR |\n' jpayne@69: '+-------------------------------------------------+---------------------------------------+\n' jpayne@69: '| "&" | ' jpayne@69: 'Bitwise AND |\n' jpayne@69: '+-------------------------------------------------+---------------------------------------+\n' jpayne@69: '| "<<", ">>" | ' jpayne@69: 'Shifts |\n' jpayne@69: '+-------------------------------------------------+---------------------------------------+\n' jpayne@69: '| "+", "-" | ' jpayne@69: 'Addition and subtraction |\n' jpayne@69: '+-------------------------------------------------+---------------------------------------+\n' jpayne@69: '| "*", "@", "/", "//", "%" | ' jpayne@69: 'Multiplication, matrix |\n' jpayne@69: '| | ' jpayne@69: 'multiplication, division, floor |\n' jpayne@69: '| | ' jpayne@69: 'division, remainder [5] |\n' jpayne@69: '+-------------------------------------------------+---------------------------------------+\n' jpayne@69: '| "+x", "-x", "~x" | ' jpayne@69: 'Positive, negative, bitwise NOT |\n' jpayne@69: '+-------------------------------------------------+---------------------------------------+\n' jpayne@69: '| "**" | ' jpayne@69: 'Exponentiation [6] |\n' jpayne@69: '+-------------------------------------------------+---------------------------------------+\n' jpayne@69: '| "await" "x" | ' jpayne@69: 'Await expression |\n' jpayne@69: '+-------------------------------------------------+---------------------------------------+\n' jpayne@69: '| "x[index]", "x[index:index]", | ' jpayne@69: 'Subscription, slicing, call, |\n' jpayne@69: '| "x(arguments...)", "x.attribute" | ' jpayne@69: 'attribute reference |\n' jpayne@69: '+-------------------------------------------------+---------------------------------------+\n' jpayne@69: '| "(expressions...)", "[expressions...]", "{key: | ' jpayne@69: 'Binding or parenthesized expression, |\n' jpayne@69: '| value...}", "{expressions...}" | list ' jpayne@69: 'display, dictionary display, set |\n' jpayne@69: '| | ' jpayne@69: 'display |\n' jpayne@69: '+-------------------------------------------------+---------------------------------------+\n' jpayne@69: '\n' jpayne@69: '-[ Footnotes ]-\n' jpayne@69: '\n' jpayne@69: '[1] While "abs(x%y) < abs(y)" is true mathematically, ' jpayne@69: 'for floats\n' jpayne@69: ' it may not be true numerically due to roundoff. For ' jpayne@69: 'example, and\n' jpayne@69: ' assuming a platform on which a Python float is an ' jpayne@69: 'IEEE 754 double-\n' jpayne@69: ' precision number, in order that "-1e-100 % 1e100" ' jpayne@69: 'have the same\n' jpayne@69: ' sign as "1e100", the computed result is "-1e-100 + ' jpayne@69: '1e100", which\n' jpayne@69: ' is numerically exactly equal to "1e100". The ' jpayne@69: 'function\n' jpayne@69: ' "math.fmod()" returns a result whose sign matches ' jpayne@69: 'the sign of the\n' jpayne@69: ' first argument instead, and so returns "-1e-100" in ' jpayne@69: 'this case.\n' jpayne@69: ' Which approach is more appropriate depends on the ' jpayne@69: 'application.\n' jpayne@69: '\n' jpayne@69: '[2] If x is very close to an exact integer multiple of ' jpayne@69: 'y, it’s\n' jpayne@69: ' possible for "x//y" to be one larger than ' jpayne@69: '"(x-x%y)//y" due to\n' jpayne@69: ' rounding. In such cases, Python returns the latter ' jpayne@69: 'result, in\n' jpayne@69: ' order to preserve that "divmod(x,y)[0] * y + x % y" ' jpayne@69: 'be very close\n' jpayne@69: ' to "x".\n' jpayne@69: '\n' jpayne@69: '[3] The Unicode standard distinguishes between *code ' jpayne@69: 'points* (e.g.\n' jpayne@69: ' U+0041) and *abstract characters* (e.g. “LATIN ' jpayne@69: 'CAPITAL LETTER A”).\n' jpayne@69: ' While most abstract characters in Unicode are only ' jpayne@69: 'represented\n' jpayne@69: ' using one code point, there is a number of abstract ' jpayne@69: 'characters\n' jpayne@69: ' that can in addition be represented using a sequence ' jpayne@69: 'of more than\n' jpayne@69: ' one code point. For example, the abstract character ' jpayne@69: '“LATIN\n' jpayne@69: ' CAPITAL LETTER C WITH CEDILLA” can be represented as ' jpayne@69: 'a single\n' jpayne@69: ' *precomposed character* at code position U+00C7, or ' jpayne@69: 'as a sequence\n' jpayne@69: ' of a *base character* at code position U+0043 (LATIN ' jpayne@69: 'CAPITAL\n' jpayne@69: ' LETTER C), followed by a *combining character* at ' jpayne@69: 'code position\n' jpayne@69: ' U+0327 (COMBINING CEDILLA).\n' jpayne@69: '\n' jpayne@69: ' The comparison operators on strings compare at the ' jpayne@69: 'level of\n' jpayne@69: ' Unicode code points. This may be counter-intuitive ' jpayne@69: 'to humans. For\n' jpayne@69: ' example, ""\\u00C7" == "\\u0043\\u0327"" is "False", ' jpayne@69: 'even though both\n' jpayne@69: ' strings represent the same abstract character “LATIN ' jpayne@69: 'CAPITAL\n' jpayne@69: ' LETTER C WITH CEDILLA”.\n' jpayne@69: '\n' jpayne@69: ' To compare strings at the level of abstract ' jpayne@69: 'characters (that is,\n' jpayne@69: ' in a way intuitive to humans), use ' jpayne@69: '"unicodedata.normalize()".\n' jpayne@69: '\n' jpayne@69: '[4] Due to automatic garbage-collection, free lists, and ' jpayne@69: 'the\n' jpayne@69: ' dynamic nature of descriptors, you may notice ' jpayne@69: 'seemingly unusual\n' jpayne@69: ' behaviour in certain uses of the "is" operator, like ' jpayne@69: 'those\n' jpayne@69: ' involving comparisons between instance methods, or ' jpayne@69: 'constants.\n' jpayne@69: ' Check their documentation for more info.\n' jpayne@69: '\n' jpayne@69: '[5] The "%" operator is also used for string formatting; ' jpayne@69: 'the same\n' jpayne@69: ' precedence applies.\n' jpayne@69: '\n' jpayne@69: '[6] The power operator "**" binds less tightly than an ' jpayne@69: 'arithmetic\n' jpayne@69: ' or bitwise unary operator on its right, that is, ' jpayne@69: '"2**-1" is "0.5".\n', jpayne@69: 'pass': 'The "pass" statement\n' jpayne@69: '********************\n' jpayne@69: '\n' jpayne@69: ' pass_stmt ::= "pass"\n' jpayne@69: '\n' jpayne@69: '"pass" is a null operation — when it is executed, nothing happens. ' jpayne@69: 'It\n' jpayne@69: 'is useful as a placeholder when a statement is required ' jpayne@69: 'syntactically,\n' jpayne@69: 'but no code needs to be executed, for example:\n' jpayne@69: '\n' jpayne@69: ' def f(arg): pass # a function that does nothing (yet)\n' jpayne@69: '\n' jpayne@69: ' class C: pass # a class with no methods (yet)\n', jpayne@69: 'power': 'The power operator\n' jpayne@69: '******************\n' jpayne@69: '\n' jpayne@69: 'The power operator binds more tightly than unary operators on its\n' jpayne@69: 'left; it binds less tightly than unary operators on its right. ' jpayne@69: 'The\n' jpayne@69: 'syntax is:\n' jpayne@69: '\n' jpayne@69: ' power ::= (await_expr | primary) ["**" u_expr]\n' jpayne@69: '\n' jpayne@69: 'Thus, in an unparenthesized sequence of power and unary operators, ' jpayne@69: 'the\n' jpayne@69: 'operators are evaluated from right to left (this does not ' jpayne@69: 'constrain\n' jpayne@69: 'the evaluation order for the operands): "-1**2" results in "-1".\n' jpayne@69: '\n' jpayne@69: 'The power operator has the same semantics as the built-in "pow()"\n' jpayne@69: 'function, when called with two arguments: it yields its left ' jpayne@69: 'argument\n' jpayne@69: 'raised to the power of its right argument. The numeric arguments ' jpayne@69: 'are\n' jpayne@69: 'first converted to a common type, and the result is of that type.\n' jpayne@69: '\n' jpayne@69: 'For int operands, the result has the same type as the operands ' jpayne@69: 'unless\n' jpayne@69: 'the second argument is negative; in that case, all arguments are\n' jpayne@69: 'converted to float and a float result is delivered. For example,\n' jpayne@69: '"10**2" returns "100", but "10**-2" returns "0.01".\n' jpayne@69: '\n' jpayne@69: 'Raising "0.0" to a negative power results in a ' jpayne@69: '"ZeroDivisionError".\n' jpayne@69: 'Raising a negative number to a fractional power results in a ' jpayne@69: '"complex"\n' jpayne@69: 'number. (In earlier versions it raised a "ValueError".)\n', jpayne@69: 'raise': 'The "raise" statement\n' jpayne@69: '*********************\n' jpayne@69: '\n' jpayne@69: ' raise_stmt ::= "raise" [expression ["from" expression]]\n' jpayne@69: '\n' jpayne@69: 'If no expressions are present, "raise" re-raises the last ' jpayne@69: 'exception\n' jpayne@69: 'that was active in the current scope. If no exception is active ' jpayne@69: 'in\n' jpayne@69: 'the current scope, a "RuntimeError" exception is raised indicating\n' jpayne@69: 'that this is an error.\n' jpayne@69: '\n' jpayne@69: 'Otherwise, "raise" evaluates the first expression as the exception\n' jpayne@69: 'object. It must be either a subclass or an instance of\n' jpayne@69: '"BaseException". If it is a class, the exception instance will be\n' jpayne@69: 'obtained when needed by instantiating the class with no arguments.\n' jpayne@69: '\n' jpayne@69: 'The *type* of the exception is the exception instance’s class, the\n' jpayne@69: '*value* is the instance itself.\n' jpayne@69: '\n' jpayne@69: 'A traceback object is normally created automatically when an ' jpayne@69: 'exception\n' jpayne@69: 'is raised and attached to it as the "__traceback__" attribute, ' jpayne@69: 'which\n' jpayne@69: 'is writable. You can create an exception and set your own traceback ' jpayne@69: 'in\n' jpayne@69: 'one step using the "with_traceback()" exception method (which ' jpayne@69: 'returns\n' jpayne@69: 'the same exception instance, with its traceback set to its ' jpayne@69: 'argument),\n' jpayne@69: 'like so:\n' jpayne@69: '\n' jpayne@69: ' raise Exception("foo occurred").with_traceback(tracebackobj)\n' jpayne@69: '\n' jpayne@69: 'The "from" clause is used for exception chaining: if given, the ' jpayne@69: 'second\n' jpayne@69: '*expression* must be another exception class or instance, which ' jpayne@69: 'will\n' jpayne@69: 'then be attached to the raised exception as the "__cause__" ' jpayne@69: 'attribute\n' jpayne@69: '(which is writable). If the raised exception is not handled, both\n' jpayne@69: 'exceptions will be printed:\n' jpayne@69: '\n' jpayne@69: ' >>> try:\n' jpayne@69: ' ... print(1 / 0)\n' jpayne@69: ' ... except Exception as exc:\n' jpayne@69: ' ... raise RuntimeError("Something bad happened") from exc\n' jpayne@69: ' ...\n' jpayne@69: ' Traceback (most recent call last):\n' jpayne@69: ' File "", line 2, in \n' jpayne@69: ' ZeroDivisionError: division by zero\n' jpayne@69: '\n' jpayne@69: ' The above exception was the direct cause of the following ' jpayne@69: 'exception:\n' jpayne@69: '\n' jpayne@69: ' Traceback (most recent call last):\n' jpayne@69: ' File "", line 4, in \n' jpayne@69: ' RuntimeError: Something bad happened\n' jpayne@69: '\n' jpayne@69: 'A similar mechanism works implicitly if an exception is raised ' jpayne@69: 'inside\n' jpayne@69: 'an exception handler or a "finally" clause: the previous exception ' jpayne@69: 'is\n' jpayne@69: 'then attached as the new exception’s "__context__" attribute:\n' jpayne@69: '\n' jpayne@69: ' >>> try:\n' jpayne@69: ' ... print(1 / 0)\n' jpayne@69: ' ... except:\n' jpayne@69: ' ... raise RuntimeError("Something bad happened")\n' jpayne@69: ' ...\n' jpayne@69: ' Traceback (most recent call last):\n' jpayne@69: ' File "", line 2, in \n' jpayne@69: ' ZeroDivisionError: division by zero\n' jpayne@69: '\n' jpayne@69: ' During handling of the above exception, another exception ' jpayne@69: 'occurred:\n' jpayne@69: '\n' jpayne@69: ' Traceback (most recent call last):\n' jpayne@69: ' File "", line 4, in \n' jpayne@69: ' RuntimeError: Something bad happened\n' jpayne@69: '\n' jpayne@69: 'Exception chaining can be explicitly suppressed by specifying ' jpayne@69: '"None"\n' jpayne@69: 'in the "from" clause:\n' jpayne@69: '\n' jpayne@69: ' >>> try:\n' jpayne@69: ' ... print(1 / 0)\n' jpayne@69: ' ... except:\n' jpayne@69: ' ... raise RuntimeError("Something bad happened") from None\n' jpayne@69: ' ...\n' jpayne@69: ' Traceback (most recent call last):\n' jpayne@69: ' File "", line 4, in \n' jpayne@69: ' RuntimeError: Something bad happened\n' jpayne@69: '\n' jpayne@69: 'Additional information on exceptions can be found in section\n' jpayne@69: 'Exceptions, and information about handling exceptions is in ' jpayne@69: 'section\n' jpayne@69: 'The try statement.\n' jpayne@69: '\n' jpayne@69: 'Changed in version 3.3: "None" is now permitted as "Y" in "raise X\n' jpayne@69: 'from Y".\n' jpayne@69: '\n' jpayne@69: 'New in version 3.3: The "__suppress_context__" attribute to ' jpayne@69: 'suppress\n' jpayne@69: 'automatic display of the exception context.\n', jpayne@69: 'return': 'The "return" statement\n' jpayne@69: '**********************\n' jpayne@69: '\n' jpayne@69: ' return_stmt ::= "return" [expression_list]\n' jpayne@69: '\n' jpayne@69: '"return" may only occur syntactically nested in a function ' jpayne@69: 'definition,\n' jpayne@69: 'not within a nested class definition.\n' jpayne@69: '\n' jpayne@69: 'If an expression list is present, it is evaluated, else "None" is\n' jpayne@69: 'substituted.\n' jpayne@69: '\n' jpayne@69: '"return" leaves the current function call with the expression list ' jpayne@69: '(or\n' jpayne@69: '"None") as return value.\n' jpayne@69: '\n' jpayne@69: 'When "return" passes control out of a "try" statement with a ' jpayne@69: '"finally"\n' jpayne@69: 'clause, that "finally" clause is executed before really leaving ' jpayne@69: 'the\n' jpayne@69: 'function.\n' jpayne@69: '\n' jpayne@69: 'In a generator function, the "return" statement indicates that ' jpayne@69: 'the\n' jpayne@69: 'generator is done and will cause "StopIteration" to be raised. ' jpayne@69: 'The\n' jpayne@69: 'returned value (if any) is used as an argument to construct\n' jpayne@69: '"StopIteration" and becomes the "StopIteration.value" attribute.\n' jpayne@69: '\n' jpayne@69: 'In an asynchronous generator function, an empty "return" ' jpayne@69: 'statement\n' jpayne@69: 'indicates that the asynchronous generator is done and will cause\n' jpayne@69: '"StopAsyncIteration" to be raised. A non-empty "return" statement ' jpayne@69: 'is\n' jpayne@69: 'a syntax error in an asynchronous generator function.\n', jpayne@69: 'sequence-types': 'Emulating container types\n' jpayne@69: '*************************\n' jpayne@69: '\n' jpayne@69: 'The following methods can be defined to implement ' jpayne@69: 'container objects.\n' jpayne@69: 'Containers usually are sequences (such as lists or tuples) ' jpayne@69: 'or mappings\n' jpayne@69: '(like dictionaries), but can represent other containers as ' jpayne@69: 'well. The\n' jpayne@69: 'first set of methods is used either to emulate a sequence ' jpayne@69: 'or to\n' jpayne@69: 'emulate a mapping; the difference is that for a sequence, ' jpayne@69: 'the\n' jpayne@69: 'allowable keys should be the integers *k* for which "0 <= ' jpayne@69: 'k < N" where\n' jpayne@69: '*N* is the length of the sequence, or slice objects, which ' jpayne@69: 'define a\n' jpayne@69: 'range of items. It is also recommended that mappings ' jpayne@69: 'provide the\n' jpayne@69: 'methods "keys()", "values()", "items()", "get()", ' jpayne@69: '"clear()",\n' jpayne@69: '"setdefault()", "pop()", "popitem()", "copy()", and ' jpayne@69: '"update()"\n' jpayne@69: 'behaving similar to those for Python’s standard dictionary ' jpayne@69: 'objects.\n' jpayne@69: 'The "collections.abc" module provides a "MutableMapping" ' jpayne@69: 'abstract base\n' jpayne@69: 'class to help create those methods from a base set of ' jpayne@69: '"__getitem__()",\n' jpayne@69: '"__setitem__()", "__delitem__()", and "keys()". Mutable ' jpayne@69: 'sequences\n' jpayne@69: 'should provide methods "append()", "count()", "index()", ' jpayne@69: '"extend()",\n' jpayne@69: '"insert()", "pop()", "remove()", "reverse()" and "sort()", ' jpayne@69: 'like Python\n' jpayne@69: 'standard list objects. Finally, sequence types should ' jpayne@69: 'implement\n' jpayne@69: 'addition (meaning concatenation) and multiplication ' jpayne@69: '(meaning\n' jpayne@69: 'repetition) by defining the methods "__add__()", ' jpayne@69: '"__radd__()",\n' jpayne@69: '"__iadd__()", "__mul__()", "__rmul__()" and "__imul__()" ' jpayne@69: 'described\n' jpayne@69: 'below; they should not define other numerical operators. ' jpayne@69: 'It is\n' jpayne@69: 'recommended that both mappings and sequences implement ' jpayne@69: 'the\n' jpayne@69: '"__contains__()" method to allow efficient use of the "in" ' jpayne@69: 'operator;\n' jpayne@69: 'for mappings, "in" should search the mapping’s keys; for ' jpayne@69: 'sequences, it\n' jpayne@69: 'should search through the values. It is further ' jpayne@69: 'recommended that both\n' jpayne@69: 'mappings and sequences implement the "__iter__()" method ' jpayne@69: 'to allow\n' jpayne@69: 'efficient iteration through the container; for mappings, ' jpayne@69: '"__iter__()"\n' jpayne@69: 'should iterate through the object’s keys; for sequences, ' jpayne@69: 'it should\n' jpayne@69: 'iterate through the values.\n' jpayne@69: '\n' jpayne@69: 'object.__len__(self)\n' jpayne@69: '\n' jpayne@69: ' Called to implement the built-in function "len()". ' jpayne@69: 'Should return\n' jpayne@69: ' the length of the object, an integer ">=" 0. Also, an ' jpayne@69: 'object that\n' jpayne@69: ' doesn’t define a "__bool__()" method and whose ' jpayne@69: '"__len__()" method\n' jpayne@69: ' returns zero is considered to be false in a Boolean ' jpayne@69: 'context.\n' jpayne@69: '\n' jpayne@69: ' **CPython implementation detail:** In CPython, the ' jpayne@69: 'length is\n' jpayne@69: ' required to be at most "sys.maxsize". If the length is ' jpayne@69: 'larger than\n' jpayne@69: ' "sys.maxsize" some features (such as "len()") may ' jpayne@69: 'raise\n' jpayne@69: ' "OverflowError". To prevent raising "OverflowError" by ' jpayne@69: 'truth value\n' jpayne@69: ' testing, an object must define a "__bool__()" method.\n' jpayne@69: '\n' jpayne@69: 'object.__length_hint__(self)\n' jpayne@69: '\n' jpayne@69: ' Called to implement "operator.length_hint()". Should ' jpayne@69: 'return an\n' jpayne@69: ' estimated length for the object (which may be greater ' jpayne@69: 'or less than\n' jpayne@69: ' the actual length). The length must be an integer ">=" ' jpayne@69: '0. The\n' jpayne@69: ' return value may also be "NotImplemented", which is ' jpayne@69: 'treated the\n' jpayne@69: ' same as if the "__length_hint__" method didn’t exist at ' jpayne@69: 'all. This\n' jpayne@69: ' method is purely an optimization and is never required ' jpayne@69: 'for\n' jpayne@69: ' correctness.\n' jpayne@69: '\n' jpayne@69: ' New in version 3.4.\n' jpayne@69: '\n' jpayne@69: 'Note: Slicing is done exclusively with the following three ' jpayne@69: 'methods.\n' jpayne@69: ' A call like\n' jpayne@69: '\n' jpayne@69: ' a[1:2] = b\n' jpayne@69: '\n' jpayne@69: ' is translated to\n' jpayne@69: '\n' jpayne@69: ' a[slice(1, 2, None)] = b\n' jpayne@69: '\n' jpayne@69: ' and so forth. Missing slice items are always filled in ' jpayne@69: 'with "None".\n' jpayne@69: '\n' jpayne@69: 'object.__getitem__(self, key)\n' jpayne@69: '\n' jpayne@69: ' Called to implement evaluation of "self[key]". For ' jpayne@69: 'sequence types,\n' jpayne@69: ' the accepted keys should be integers and slice ' jpayne@69: 'objects. Note that\n' jpayne@69: ' the special interpretation of negative indexes (if the ' jpayne@69: 'class wishes\n' jpayne@69: ' to emulate a sequence type) is up to the ' jpayne@69: '"__getitem__()" method. If\n' jpayne@69: ' *key* is of an inappropriate type, "TypeError" may be ' jpayne@69: 'raised; if of\n' jpayne@69: ' a value outside the set of indexes for the sequence ' jpayne@69: '(after any\n' jpayne@69: ' special interpretation of negative values), ' jpayne@69: '"IndexError" should be\n' jpayne@69: ' raised. For mapping types, if *key* is missing (not in ' jpayne@69: 'the\n' jpayne@69: ' container), "KeyError" should be raised.\n' jpayne@69: '\n' jpayne@69: ' Note: "for" loops expect that an "IndexError" will be ' jpayne@69: 'raised for\n' jpayne@69: ' illegal indexes to allow proper detection of the end ' jpayne@69: 'of the\n' jpayne@69: ' sequence.\n' jpayne@69: '\n' jpayne@69: 'object.__setitem__(self, key, value)\n' jpayne@69: '\n' jpayne@69: ' Called to implement assignment to "self[key]". Same ' jpayne@69: 'note as for\n' jpayne@69: ' "__getitem__()". This should only be implemented for ' jpayne@69: 'mappings if\n' jpayne@69: ' the objects support changes to the values for keys, or ' jpayne@69: 'if new keys\n' jpayne@69: ' can be added, or for sequences if elements can be ' jpayne@69: 'replaced. The\n' jpayne@69: ' same exceptions should be raised for improper *key* ' jpayne@69: 'values as for\n' jpayne@69: ' the "__getitem__()" method.\n' jpayne@69: '\n' jpayne@69: 'object.__delitem__(self, key)\n' jpayne@69: '\n' jpayne@69: ' Called to implement deletion of "self[key]". Same note ' jpayne@69: 'as for\n' jpayne@69: ' "__getitem__()". This should only be implemented for ' jpayne@69: 'mappings if\n' jpayne@69: ' the objects support removal of keys, or for sequences ' jpayne@69: 'if elements\n' jpayne@69: ' can be removed from the sequence. The same exceptions ' jpayne@69: 'should be\n' jpayne@69: ' raised for improper *key* values as for the ' jpayne@69: '"__getitem__()" method.\n' jpayne@69: '\n' jpayne@69: 'object.__missing__(self, key)\n' jpayne@69: '\n' jpayne@69: ' Called by "dict"."__getitem__()" to implement ' jpayne@69: '"self[key]" for dict\n' jpayne@69: ' subclasses when key is not in the dictionary.\n' jpayne@69: '\n' jpayne@69: 'object.__iter__(self)\n' jpayne@69: '\n' jpayne@69: ' This method is called when an iterator is required for ' jpayne@69: 'a container.\n' jpayne@69: ' This method should return a new iterator object that ' jpayne@69: 'can iterate\n' jpayne@69: ' over all the objects in the container. For mappings, ' jpayne@69: 'it should\n' jpayne@69: ' iterate over the keys of the container.\n' jpayne@69: '\n' jpayne@69: ' Iterator objects also need to implement this method; ' jpayne@69: 'they are\n' jpayne@69: ' required to return themselves. For more information on ' jpayne@69: 'iterator\n' jpayne@69: ' objects, see Iterator Types.\n' jpayne@69: '\n' jpayne@69: 'object.__reversed__(self)\n' jpayne@69: '\n' jpayne@69: ' Called (if present) by the "reversed()" built-in to ' jpayne@69: 'implement\n' jpayne@69: ' reverse iteration. It should return a new iterator ' jpayne@69: 'object that\n' jpayne@69: ' iterates over all the objects in the container in ' jpayne@69: 'reverse order.\n' jpayne@69: '\n' jpayne@69: ' If the "__reversed__()" method is not provided, the ' jpayne@69: '"reversed()"\n' jpayne@69: ' built-in will fall back to using the sequence protocol ' jpayne@69: '("__len__()"\n' jpayne@69: ' and "__getitem__()"). Objects that support the ' jpayne@69: 'sequence protocol\n' jpayne@69: ' should only provide "__reversed__()" if they can ' jpayne@69: 'provide an\n' jpayne@69: ' implementation that is more efficient than the one ' jpayne@69: 'provided by\n' jpayne@69: ' "reversed()".\n' jpayne@69: '\n' jpayne@69: 'The membership test operators ("in" and "not in") are ' jpayne@69: 'normally\n' jpayne@69: 'implemented as an iteration through a container. However, ' jpayne@69: 'container\n' jpayne@69: 'objects can supply the following special method with a ' jpayne@69: 'more efficient\n' jpayne@69: 'implementation, which also does not require the object be ' jpayne@69: 'iterable.\n' jpayne@69: '\n' jpayne@69: 'object.__contains__(self, item)\n' jpayne@69: '\n' jpayne@69: ' Called to implement membership test operators. Should ' jpayne@69: 'return true\n' jpayne@69: ' if *item* is in *self*, false otherwise. For mapping ' jpayne@69: 'objects, this\n' jpayne@69: ' should consider the keys of the mapping rather than the ' jpayne@69: 'values or\n' jpayne@69: ' the key-item pairs.\n' jpayne@69: '\n' jpayne@69: ' For objects that don’t define "__contains__()", the ' jpayne@69: 'membership test\n' jpayne@69: ' first tries iteration via "__iter__()", then the old ' jpayne@69: 'sequence\n' jpayne@69: ' iteration protocol via "__getitem__()", see this ' jpayne@69: 'section in the\n' jpayne@69: ' language reference.\n', jpayne@69: 'shifting': 'Shifting operations\n' jpayne@69: '*******************\n' jpayne@69: '\n' jpayne@69: 'The shifting operations have lower priority than the arithmetic\n' jpayne@69: 'operations:\n' jpayne@69: '\n' jpayne@69: ' shift_expr ::= a_expr | shift_expr ("<<" | ">>") a_expr\n' jpayne@69: '\n' jpayne@69: 'These operators accept integers as arguments. They shift the ' jpayne@69: 'first\n' jpayne@69: 'argument to the left or right by the number of bits given by ' jpayne@69: 'the\n' jpayne@69: 'second argument.\n' jpayne@69: '\n' jpayne@69: 'A right shift by *n* bits is defined as floor division by ' jpayne@69: '"pow(2,n)".\n' jpayne@69: 'A left shift by *n* bits is defined as multiplication with ' jpayne@69: '"pow(2,n)".\n', jpayne@69: 'slicings': 'Slicings\n' jpayne@69: '********\n' jpayne@69: '\n' jpayne@69: 'A slicing selects a range of items in a sequence object (e.g., ' jpayne@69: 'a\n' jpayne@69: 'string, tuple or list). Slicings may be used as expressions or ' jpayne@69: 'as\n' jpayne@69: 'targets in assignment or "del" statements. The syntax for a ' jpayne@69: 'slicing:\n' jpayne@69: '\n' jpayne@69: ' slicing ::= primary "[" slice_list "]"\n' jpayne@69: ' slice_list ::= slice_item ("," slice_item)* [","]\n' jpayne@69: ' slice_item ::= expression | proper_slice\n' jpayne@69: ' proper_slice ::= [lower_bound] ":" [upper_bound] [ ":" ' jpayne@69: '[stride] ]\n' jpayne@69: ' lower_bound ::= expression\n' jpayne@69: ' upper_bound ::= expression\n' jpayne@69: ' stride ::= expression\n' jpayne@69: '\n' jpayne@69: 'There is ambiguity in the formal syntax here: anything that ' jpayne@69: 'looks like\n' jpayne@69: 'an expression list also looks like a slice list, so any ' jpayne@69: 'subscription\n' jpayne@69: 'can be interpreted as a slicing. Rather than further ' jpayne@69: 'complicating the\n' jpayne@69: 'syntax, this is disambiguated by defining that in this case the\n' jpayne@69: 'interpretation as a subscription takes priority over the\n' jpayne@69: 'interpretation as a slicing (this is the case if the slice list\n' jpayne@69: 'contains no proper slice).\n' jpayne@69: '\n' jpayne@69: 'The semantics for a slicing are as follows. The primary is ' jpayne@69: 'indexed\n' jpayne@69: '(using the same "__getitem__()" method as normal subscription) ' jpayne@69: 'with a\n' jpayne@69: 'key that is constructed from the slice list, as follows. If the ' jpayne@69: 'slice\n' jpayne@69: 'list contains at least one comma, the key is a tuple containing ' jpayne@69: 'the\n' jpayne@69: 'conversion of the slice items; otherwise, the conversion of the ' jpayne@69: 'lone\n' jpayne@69: 'slice item is the key. The conversion of a slice item that is ' jpayne@69: 'an\n' jpayne@69: 'expression is that expression. The conversion of a proper slice ' jpayne@69: 'is a\n' jpayne@69: 'slice object (see section The standard type hierarchy) whose ' jpayne@69: '"start",\n' jpayne@69: '"stop" and "step" attributes are the values of the expressions ' jpayne@69: 'given\n' jpayne@69: 'as lower bound, upper bound and stride, respectively, ' jpayne@69: 'substituting\n' jpayne@69: '"None" for missing expressions.\n', jpayne@69: 'specialattrs': 'Special Attributes\n' jpayne@69: '******************\n' jpayne@69: '\n' jpayne@69: 'The implementation adds a few special read-only attributes ' jpayne@69: 'to several\n' jpayne@69: 'object types, where they are relevant. Some of these are ' jpayne@69: 'not reported\n' jpayne@69: 'by the "dir()" built-in function.\n' jpayne@69: '\n' jpayne@69: 'object.__dict__\n' jpayne@69: '\n' jpayne@69: ' A dictionary or other mapping object used to store an ' jpayne@69: 'object’s\n' jpayne@69: ' (writable) attributes.\n' jpayne@69: '\n' jpayne@69: 'instance.__class__\n' jpayne@69: '\n' jpayne@69: ' The class to which a class instance belongs.\n' jpayne@69: '\n' jpayne@69: 'class.__bases__\n' jpayne@69: '\n' jpayne@69: ' The tuple of base classes of a class object.\n' jpayne@69: '\n' jpayne@69: 'definition.__name__\n' jpayne@69: '\n' jpayne@69: ' The name of the class, function, method, descriptor, or ' jpayne@69: 'generator\n' jpayne@69: ' instance.\n' jpayne@69: '\n' jpayne@69: 'definition.__qualname__\n' jpayne@69: '\n' jpayne@69: ' The *qualified name* of the class, function, method, ' jpayne@69: 'descriptor, or\n' jpayne@69: ' generator instance.\n' jpayne@69: '\n' jpayne@69: ' New in version 3.3.\n' jpayne@69: '\n' jpayne@69: 'class.__mro__\n' jpayne@69: '\n' jpayne@69: ' This attribute is a tuple of classes that are considered ' jpayne@69: 'when\n' jpayne@69: ' looking for base classes during method resolution.\n' jpayne@69: '\n' jpayne@69: 'class.mro()\n' jpayne@69: '\n' jpayne@69: ' This method can be overridden by a metaclass to customize ' jpayne@69: 'the\n' jpayne@69: ' method resolution order for its instances. It is called ' jpayne@69: 'at class\n' jpayne@69: ' instantiation, and its result is stored in "__mro__".\n' jpayne@69: '\n' jpayne@69: 'class.__subclasses__()\n' jpayne@69: '\n' jpayne@69: ' Each class keeps a list of weak references to its ' jpayne@69: 'immediate\n' jpayne@69: ' subclasses. This method returns a list of all those ' jpayne@69: 'references\n' jpayne@69: ' still alive. Example:\n' jpayne@69: '\n' jpayne@69: ' >>> int.__subclasses__()\n' jpayne@69: " []\n" jpayne@69: '\n' jpayne@69: '-[ Footnotes ]-\n' jpayne@69: '\n' jpayne@69: '[1] Additional information on these special methods may be ' jpayne@69: 'found\n' jpayne@69: ' in the Python Reference Manual (Basic customization).\n' jpayne@69: '\n' jpayne@69: '[2] As a consequence, the list "[1, 2]" is considered equal ' jpayne@69: 'to\n' jpayne@69: ' "[1.0, 2.0]", and similarly for tuples.\n' jpayne@69: '\n' jpayne@69: '[3] They must have since the parser can’t tell the type of ' jpayne@69: 'the\n' jpayne@69: ' operands.\n' jpayne@69: '\n' jpayne@69: '[4] Cased characters are those with general category ' jpayne@69: 'property\n' jpayne@69: ' being one of “Lu” (Letter, uppercase), “Ll” (Letter, ' jpayne@69: 'lowercase),\n' jpayne@69: ' or “Lt” (Letter, titlecase).\n' jpayne@69: '\n' jpayne@69: '[5] To format only a tuple you should therefore provide a\n' jpayne@69: ' singleton tuple whose only element is the tuple to be ' jpayne@69: 'formatted.\n', jpayne@69: 'specialnames': 'Special method names\n' jpayne@69: '********************\n' jpayne@69: '\n' jpayne@69: 'A class can implement certain operations that are invoked by ' jpayne@69: 'special\n' jpayne@69: 'syntax (such as arithmetic operations or subscripting and ' jpayne@69: 'slicing) by\n' jpayne@69: 'defining methods with special names. This is Python’s ' jpayne@69: 'approach to\n' jpayne@69: '*operator overloading*, allowing classes to define their own ' jpayne@69: 'behavior\n' jpayne@69: 'with respect to language operators. For instance, if a ' jpayne@69: 'class defines\n' jpayne@69: 'a method named "__getitem__()", and "x" is an instance of ' jpayne@69: 'this class,\n' jpayne@69: 'then "x[i]" is roughly equivalent to "type(x).__getitem__(x, ' jpayne@69: 'i)".\n' jpayne@69: 'Except where mentioned, attempts to execute an operation ' jpayne@69: 'raise an\n' jpayne@69: 'exception when no appropriate method is defined (typically\n' jpayne@69: '"AttributeError" or "TypeError").\n' jpayne@69: '\n' jpayne@69: 'Setting a special method to "None" indicates that the ' jpayne@69: 'corresponding\n' jpayne@69: 'operation is not available. For example, if a class sets ' jpayne@69: '"__iter__()"\n' jpayne@69: 'to "None", the class is not iterable, so calling "iter()" on ' jpayne@69: 'its\n' jpayne@69: 'instances will raise a "TypeError" (without falling back to\n' jpayne@69: '"__getitem__()"). [2]\n' jpayne@69: '\n' jpayne@69: 'When implementing a class that emulates any built-in type, ' jpayne@69: 'it is\n' jpayne@69: 'important that the emulation only be implemented to the ' jpayne@69: 'degree that it\n' jpayne@69: 'makes sense for the object being modelled. For example, ' jpayne@69: 'some\n' jpayne@69: 'sequences may work well with retrieval of individual ' jpayne@69: 'elements, but\n' jpayne@69: 'extracting a slice may not make sense. (One example of this ' jpayne@69: 'is the\n' jpayne@69: '"NodeList" interface in the W3C’s Document Object Model.)\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Basic customization\n' jpayne@69: '===================\n' jpayne@69: '\n' jpayne@69: 'object.__new__(cls[, ...])\n' jpayne@69: '\n' jpayne@69: ' Called to create a new instance of class *cls*. ' jpayne@69: '"__new__()" is a\n' jpayne@69: ' static method (special-cased so you need not declare it ' jpayne@69: 'as such)\n' jpayne@69: ' that takes the class of which an instance was requested ' jpayne@69: 'as its\n' jpayne@69: ' first argument. The remaining arguments are those passed ' jpayne@69: 'to the\n' jpayne@69: ' object constructor expression (the call to the class). ' jpayne@69: 'The return\n' jpayne@69: ' value of "__new__()" should be the new object instance ' jpayne@69: '(usually an\n' jpayne@69: ' instance of *cls*).\n' jpayne@69: '\n' jpayne@69: ' Typical implementations create a new instance of the ' jpayne@69: 'class by\n' jpayne@69: ' invoking the superclass’s "__new__()" method using\n' jpayne@69: ' "super().__new__(cls[, ...])" with appropriate arguments ' jpayne@69: 'and then\n' jpayne@69: ' modifying the newly-created instance as necessary before ' jpayne@69: 'returning\n' jpayne@69: ' it.\n' jpayne@69: '\n' jpayne@69: ' If "__new__()" is invoked during object construction and ' jpayne@69: 'it returns\n' jpayne@69: ' an instance or subclass of *cls*, then the new ' jpayne@69: 'instance’s\n' jpayne@69: ' "__init__()" method will be invoked like "__init__(self[, ' jpayne@69: '...])",\n' jpayne@69: ' where *self* is the new instance and the remaining ' jpayne@69: 'arguments are\n' jpayne@69: ' the same as were passed to the object constructor.\n' jpayne@69: '\n' jpayne@69: ' If "__new__()" does not return an instance of *cls*, then ' jpayne@69: 'the new\n' jpayne@69: ' instance’s "__init__()" method will not be invoked.\n' jpayne@69: '\n' jpayne@69: ' "__new__()" is intended mainly to allow subclasses of ' jpayne@69: 'immutable\n' jpayne@69: ' types (like int, str, or tuple) to customize instance ' jpayne@69: 'creation. It\n' jpayne@69: ' is also commonly overridden in custom metaclasses in ' jpayne@69: 'order to\n' jpayne@69: ' customize class creation.\n' jpayne@69: '\n' jpayne@69: 'object.__init__(self[, ...])\n' jpayne@69: '\n' jpayne@69: ' Called after the instance has been created (by ' jpayne@69: '"__new__()"), but\n' jpayne@69: ' before it is returned to the caller. The arguments are ' jpayne@69: 'those\n' jpayne@69: ' passed to the class constructor expression. If a base ' jpayne@69: 'class has an\n' jpayne@69: ' "__init__()" method, the derived class’s "__init__()" ' jpayne@69: 'method, if\n' jpayne@69: ' any, must explicitly call it to ensure proper ' jpayne@69: 'initialization of the\n' jpayne@69: ' base class part of the instance; for example:\n' jpayne@69: ' "super().__init__([args...])".\n' jpayne@69: '\n' jpayne@69: ' Because "__new__()" and "__init__()" work together in ' jpayne@69: 'constructing\n' jpayne@69: ' objects ("__new__()" to create it, and "__init__()" to ' jpayne@69: 'customize\n' jpayne@69: ' it), no non-"None" value may be returned by "__init__()"; ' jpayne@69: 'doing so\n' jpayne@69: ' will cause a "TypeError" to be raised at runtime.\n' jpayne@69: '\n' jpayne@69: 'object.__del__(self)\n' jpayne@69: '\n' jpayne@69: ' Called when the instance is about to be destroyed. This ' jpayne@69: 'is also\n' jpayne@69: ' called a finalizer or (improperly) a destructor. If a ' jpayne@69: 'base class\n' jpayne@69: ' has a "__del__()" method, the derived class’s "__del__()" ' jpayne@69: 'method,\n' jpayne@69: ' if any, must explicitly call it to ensure proper deletion ' jpayne@69: 'of the\n' jpayne@69: ' base class part of the instance.\n' jpayne@69: '\n' jpayne@69: ' It is possible (though not recommended!) for the ' jpayne@69: '"__del__()" method\n' jpayne@69: ' to postpone destruction of the instance by creating a new ' jpayne@69: 'reference\n' jpayne@69: ' to it. This is called object *resurrection*. It is\n' jpayne@69: ' implementation-dependent whether "__del__()" is called a ' jpayne@69: 'second\n' jpayne@69: ' time when a resurrected object is about to be destroyed; ' jpayne@69: 'the\n' jpayne@69: ' current *CPython* implementation only calls it once.\n' jpayne@69: '\n' jpayne@69: ' It is not guaranteed that "__del__()" methods are called ' jpayne@69: 'for\n' jpayne@69: ' objects that still exist when the interpreter exits.\n' jpayne@69: '\n' jpayne@69: ' Note: "del x" doesn’t directly call "x.__del__()" — the ' jpayne@69: 'former\n' jpayne@69: ' decrements the reference count for "x" by one, and the ' jpayne@69: 'latter is\n' jpayne@69: ' only called when "x"’s reference count reaches zero.\n' jpayne@69: '\n' jpayne@69: ' **CPython implementation detail:** It is possible for a ' jpayne@69: 'reference\n' jpayne@69: ' cycle to prevent the reference count of an object from ' jpayne@69: 'going to\n' jpayne@69: ' zero. In this case, the cycle will be later detected and ' jpayne@69: 'deleted\n' jpayne@69: ' by the *cyclic garbage collector*. A common cause of ' jpayne@69: 'reference\n' jpayne@69: ' cycles is when an exception has been caught in a local ' jpayne@69: 'variable.\n' jpayne@69: ' The frame’s locals then reference the exception, which ' jpayne@69: 'references\n' jpayne@69: ' its own traceback, which references the locals of all ' jpayne@69: 'frames caught\n' jpayne@69: ' in the traceback.\n' jpayne@69: '\n' jpayne@69: ' See also: Documentation for the "gc" module.\n' jpayne@69: '\n' jpayne@69: ' Warning: Due to the precarious circumstances under which\n' jpayne@69: ' "__del__()" methods are invoked, exceptions that occur ' jpayne@69: 'during\n' jpayne@69: ' their execution are ignored, and a warning is printed ' jpayne@69: 'to\n' jpayne@69: ' "sys.stderr" instead. In particular:\n' jpayne@69: '\n' jpayne@69: ' * "__del__()" can be invoked when arbitrary code is ' jpayne@69: 'being\n' jpayne@69: ' executed, including from any arbitrary thread. If ' jpayne@69: '"__del__()"\n' jpayne@69: ' needs to take a lock or invoke any other blocking ' jpayne@69: 'resource, it\n' jpayne@69: ' may deadlock as the resource may already be taken by ' jpayne@69: 'the code\n' jpayne@69: ' that gets interrupted to execute "__del__()".\n' jpayne@69: '\n' jpayne@69: ' * "__del__()" can be executed during interpreter ' jpayne@69: 'shutdown. As\n' jpayne@69: ' a consequence, the global variables it needs to ' jpayne@69: 'access\n' jpayne@69: ' (including other modules) may already have been ' jpayne@69: 'deleted or set\n' jpayne@69: ' to "None". Python guarantees that globals whose name ' jpayne@69: 'begins\n' jpayne@69: ' with a single underscore are deleted from their ' jpayne@69: 'module before\n' jpayne@69: ' other globals are deleted; if no other references to ' jpayne@69: 'such\n' jpayne@69: ' globals exist, this may help in assuring that ' jpayne@69: 'imported modules\n' jpayne@69: ' are still available at the time when the "__del__()" ' jpayne@69: 'method is\n' jpayne@69: ' called.\n' jpayne@69: '\n' jpayne@69: 'object.__repr__(self)\n' jpayne@69: '\n' jpayne@69: ' Called by the "repr()" built-in function to compute the ' jpayne@69: '“official”\n' jpayne@69: ' string representation of an object. If at all possible, ' jpayne@69: 'this\n' jpayne@69: ' should look like a valid Python expression that could be ' jpayne@69: 'used to\n' jpayne@69: ' recreate an object with the same value (given an ' jpayne@69: 'appropriate\n' jpayne@69: ' environment). If this is not possible, a string of the ' jpayne@69: 'form\n' jpayne@69: ' "<...some useful description...>" should be returned. The ' jpayne@69: 'return\n' jpayne@69: ' value must be a string object. If a class defines ' jpayne@69: '"__repr__()" but\n' jpayne@69: ' not "__str__()", then "__repr__()" is also used when an ' jpayne@69: '“informal”\n' jpayne@69: ' string representation of instances of that class is ' jpayne@69: 'required.\n' jpayne@69: '\n' jpayne@69: ' This is typically used for debugging, so it is important ' jpayne@69: 'that the\n' jpayne@69: ' representation is information-rich and unambiguous.\n' jpayne@69: '\n' jpayne@69: 'object.__str__(self)\n' jpayne@69: '\n' jpayne@69: ' Called by "str(object)" and the built-in functions ' jpayne@69: '"format()" and\n' jpayne@69: ' "print()" to compute the “informal” or nicely printable ' jpayne@69: 'string\n' jpayne@69: ' representation of an object. The return value must be a ' jpayne@69: 'string\n' jpayne@69: ' object.\n' jpayne@69: '\n' jpayne@69: ' This method differs from "object.__repr__()" in that ' jpayne@69: 'there is no\n' jpayne@69: ' expectation that "__str__()" return a valid Python ' jpayne@69: 'expression: a\n' jpayne@69: ' more convenient or concise representation can be used.\n' jpayne@69: '\n' jpayne@69: ' The default implementation defined by the built-in type ' jpayne@69: '"object"\n' jpayne@69: ' calls "object.__repr__()".\n' jpayne@69: '\n' jpayne@69: 'object.__bytes__(self)\n' jpayne@69: '\n' jpayne@69: ' Called by bytes to compute a byte-string representation ' jpayne@69: 'of an\n' jpayne@69: ' object. This should return a "bytes" object.\n' jpayne@69: '\n' jpayne@69: 'object.__format__(self, format_spec)\n' jpayne@69: '\n' jpayne@69: ' Called by the "format()" built-in function, and by ' jpayne@69: 'extension,\n' jpayne@69: ' evaluation of formatted string literals and the ' jpayne@69: '"str.format()"\n' jpayne@69: ' method, to produce a “formatted” string representation of ' jpayne@69: 'an\n' jpayne@69: ' object. The *format_spec* argument is a string that ' jpayne@69: 'contains a\n' jpayne@69: ' description of the formatting options desired. The ' jpayne@69: 'interpretation\n' jpayne@69: ' of the *format_spec* argument is up to the type ' jpayne@69: 'implementing\n' jpayne@69: ' "__format__()", however most classes will either ' jpayne@69: 'delegate\n' jpayne@69: ' formatting to one of the built-in types, or use a ' jpayne@69: 'similar\n' jpayne@69: ' formatting option syntax.\n' jpayne@69: '\n' jpayne@69: ' See Format Specification Mini-Language for a description ' jpayne@69: 'of the\n' jpayne@69: ' standard formatting syntax.\n' jpayne@69: '\n' jpayne@69: ' The return value must be a string object.\n' jpayne@69: '\n' jpayne@69: ' Changed in version 3.4: The __format__ method of "object" ' jpayne@69: 'itself\n' jpayne@69: ' raises a "TypeError" if passed any non-empty string.\n' jpayne@69: '\n' jpayne@69: ' Changed in version 3.7: "object.__format__(x, \'\')" is ' jpayne@69: 'now\n' jpayne@69: ' equivalent to "str(x)" rather than "format(str(self), ' jpayne@69: '\'\')".\n' jpayne@69: '\n' jpayne@69: 'object.__lt__(self, other)\n' jpayne@69: 'object.__le__(self, other)\n' jpayne@69: 'object.__eq__(self, other)\n' jpayne@69: 'object.__ne__(self, other)\n' jpayne@69: 'object.__gt__(self, other)\n' jpayne@69: 'object.__ge__(self, other)\n' jpayne@69: '\n' jpayne@69: ' These are the so-called “rich comparison” methods. The\n' jpayne@69: ' correspondence between operator symbols and method names ' jpayne@69: 'is as\n' jpayne@69: ' follows: "xy" calls\n' jpayne@69: ' "x.__gt__(y)", and "x>=y" calls "x.__ge__(y)".\n' jpayne@69: '\n' jpayne@69: ' A rich comparison method may return the singleton ' jpayne@69: '"NotImplemented"\n' jpayne@69: ' if it does not implement the operation for a given pair ' jpayne@69: 'of\n' jpayne@69: ' arguments. By convention, "False" and "True" are returned ' jpayne@69: 'for a\n' jpayne@69: ' successful comparison. However, these methods can return ' jpayne@69: 'any value,\n' jpayne@69: ' so if the comparison operator is used in a Boolean ' jpayne@69: 'context (e.g.,\n' jpayne@69: ' in the condition of an "if" statement), Python will call ' jpayne@69: '"bool()"\n' jpayne@69: ' on the value to determine if the result is true or ' jpayne@69: 'false.\n' jpayne@69: '\n' jpayne@69: ' By default, "__ne__()" delegates to "__eq__()" and ' jpayne@69: 'inverts the\n' jpayne@69: ' result unless it is "NotImplemented". There are no other ' jpayne@69: 'implied\n' jpayne@69: ' relationships among the comparison operators, for ' jpayne@69: 'example, the\n' jpayne@69: ' truth of "(x.__hash__".\n' jpayne@69: '\n' jpayne@69: ' If a class that does not override "__eq__()" wishes to ' jpayne@69: 'suppress\n' jpayne@69: ' hash support, it should include "__hash__ = None" in the ' jpayne@69: 'class\n' jpayne@69: ' definition. A class which defines its own "__hash__()" ' jpayne@69: 'that\n' jpayne@69: ' explicitly raises a "TypeError" would be incorrectly ' jpayne@69: 'identified as\n' jpayne@69: ' hashable by an "isinstance(obj, ' jpayne@69: 'collections.abc.Hashable)" call.\n' jpayne@69: '\n' jpayne@69: ' Note: By default, the "__hash__()" values of str and ' jpayne@69: 'bytes\n' jpayne@69: ' objects are “salted” with an unpredictable random ' jpayne@69: 'value.\n' jpayne@69: ' Although they remain constant within an individual ' jpayne@69: 'Python\n' jpayne@69: ' process, they are not predictable between repeated ' jpayne@69: 'invocations of\n' jpayne@69: ' Python.This is intended to provide protection against a ' jpayne@69: 'denial-\n' jpayne@69: ' of-service caused by carefully-chosen inputs that ' jpayne@69: 'exploit the\n' jpayne@69: ' worst case performance of a dict insertion, O(n^2) ' jpayne@69: 'complexity.\n' jpayne@69: ' See http://www.ocert.org/advisories/ocert-2011-003.html ' jpayne@69: 'for\n' jpayne@69: ' details.Changing hash values affects the iteration ' jpayne@69: 'order of sets.\n' jpayne@69: ' Python has never made guarantees about this ordering ' jpayne@69: '(and it\n' jpayne@69: ' typically varies between 32-bit and 64-bit builds).See ' jpayne@69: 'also\n' jpayne@69: ' "PYTHONHASHSEED".\n' jpayne@69: '\n' jpayne@69: ' Changed in version 3.3: Hash randomization is enabled by ' jpayne@69: 'default.\n' jpayne@69: '\n' jpayne@69: 'object.__bool__(self)\n' jpayne@69: '\n' jpayne@69: ' Called to implement truth value testing and the built-in ' jpayne@69: 'operation\n' jpayne@69: ' "bool()"; should return "False" or "True". When this ' jpayne@69: 'method is not\n' jpayne@69: ' defined, "__len__()" is called, if it is defined, and the ' jpayne@69: 'object is\n' jpayne@69: ' considered true if its result is nonzero. If a class ' jpayne@69: 'defines\n' jpayne@69: ' neither "__len__()" nor "__bool__()", all its instances ' jpayne@69: 'are\n' jpayne@69: ' considered true.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Customizing attribute access\n' jpayne@69: '============================\n' jpayne@69: '\n' jpayne@69: 'The following methods can be defined to customize the ' jpayne@69: 'meaning of\n' jpayne@69: 'attribute access (use of, assignment to, or deletion of ' jpayne@69: '"x.name") for\n' jpayne@69: 'class instances.\n' jpayne@69: '\n' jpayne@69: 'object.__getattr__(self, name)\n' jpayne@69: '\n' jpayne@69: ' Called when the default attribute access fails with an\n' jpayne@69: ' "AttributeError" (either "__getattribute__()" raises an\n' jpayne@69: ' "AttributeError" because *name* is not an instance ' jpayne@69: 'attribute or an\n' jpayne@69: ' attribute in the class tree for "self"; or "__get__()" of ' jpayne@69: 'a *name*\n' jpayne@69: ' property raises "AttributeError"). This method should ' jpayne@69: 'either\n' jpayne@69: ' return the (computed) attribute value or raise an ' jpayne@69: '"AttributeError"\n' jpayne@69: ' exception.\n' jpayne@69: '\n' jpayne@69: ' Note that if the attribute is found through the normal ' jpayne@69: 'mechanism,\n' jpayne@69: ' "__getattr__()" is not called. (This is an intentional ' jpayne@69: 'asymmetry\n' jpayne@69: ' between "__getattr__()" and "__setattr__()".) This is ' jpayne@69: 'done both for\n' jpayne@69: ' efficiency reasons and because otherwise "__getattr__()" ' jpayne@69: 'would have\n' jpayne@69: ' no way to access other attributes of the instance. Note ' jpayne@69: 'that at\n' jpayne@69: ' least for instance variables, you can fake total control ' jpayne@69: 'by not\n' jpayne@69: ' inserting any values in the instance attribute dictionary ' jpayne@69: '(but\n' jpayne@69: ' instead inserting them in another object). See the\n' jpayne@69: ' "__getattribute__()" method below for a way to actually ' jpayne@69: 'get total\n' jpayne@69: ' control over attribute access.\n' jpayne@69: '\n' jpayne@69: 'object.__getattribute__(self, name)\n' jpayne@69: '\n' jpayne@69: ' Called unconditionally to implement attribute accesses ' jpayne@69: 'for\n' jpayne@69: ' instances of the class. If the class also defines ' jpayne@69: '"__getattr__()",\n' jpayne@69: ' the latter will not be called unless "__getattribute__()" ' jpayne@69: 'either\n' jpayne@69: ' calls it explicitly or raises an "AttributeError". This ' jpayne@69: 'method\n' jpayne@69: ' should return the (computed) attribute value or raise an\n' jpayne@69: ' "AttributeError" exception. In order to avoid infinite ' jpayne@69: 'recursion in\n' jpayne@69: ' this method, its implementation should always call the ' jpayne@69: 'base class\n' jpayne@69: ' method with the same name to access any attributes it ' jpayne@69: 'needs, for\n' jpayne@69: ' example, "object.__getattribute__(self, name)".\n' jpayne@69: '\n' jpayne@69: ' Note: This method may still be bypassed when looking up ' jpayne@69: 'special\n' jpayne@69: ' methods as the result of implicit invocation via ' jpayne@69: 'language syntax\n' jpayne@69: ' or built-in functions. See Special method lookup.\n' jpayne@69: '\n' jpayne@69: 'object.__setattr__(self, name, value)\n' jpayne@69: '\n' jpayne@69: ' Called when an attribute assignment is attempted. This ' jpayne@69: 'is called\n' jpayne@69: ' instead of the normal mechanism (i.e. store the value in ' jpayne@69: 'the\n' jpayne@69: ' instance dictionary). *name* is the attribute name, ' jpayne@69: '*value* is the\n' jpayne@69: ' value to be assigned to it.\n' jpayne@69: '\n' jpayne@69: ' If "__setattr__()" wants to assign to an instance ' jpayne@69: 'attribute, it\n' jpayne@69: ' should call the base class method with the same name, for ' jpayne@69: 'example,\n' jpayne@69: ' "object.__setattr__(self, name, value)".\n' jpayne@69: '\n' jpayne@69: 'object.__delattr__(self, name)\n' jpayne@69: '\n' jpayne@69: ' Like "__setattr__()" but for attribute deletion instead ' jpayne@69: 'of\n' jpayne@69: ' assignment. This should only be implemented if "del ' jpayne@69: 'obj.name" is\n' jpayne@69: ' meaningful for the object.\n' jpayne@69: '\n' jpayne@69: 'object.__dir__(self)\n' jpayne@69: '\n' jpayne@69: ' Called when "dir()" is called on the object. A sequence ' jpayne@69: 'must be\n' jpayne@69: ' returned. "dir()" converts the returned sequence to a ' jpayne@69: 'list and\n' jpayne@69: ' sorts it.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Customizing module attribute access\n' jpayne@69: '-----------------------------------\n' jpayne@69: '\n' jpayne@69: 'Special names "__getattr__" and "__dir__" can be also used ' jpayne@69: 'to\n' jpayne@69: 'customize access to module attributes. The "__getattr__" ' jpayne@69: 'function at\n' jpayne@69: 'the module level should accept one argument which is the ' jpayne@69: 'name of an\n' jpayne@69: 'attribute and return the computed value or raise an ' jpayne@69: '"AttributeError".\n' jpayne@69: 'If an attribute is not found on a module object through the ' jpayne@69: 'normal\n' jpayne@69: 'lookup, i.e. "object.__getattribute__()", then "__getattr__" ' jpayne@69: 'is\n' jpayne@69: 'searched in the module "__dict__" before raising an ' jpayne@69: '"AttributeError".\n' jpayne@69: 'If found, it is called with the attribute name and the ' jpayne@69: 'result is\n' jpayne@69: 'returned.\n' jpayne@69: '\n' jpayne@69: 'The "__dir__" function should accept no arguments, and ' jpayne@69: 'return a\n' jpayne@69: 'sequence of strings that represents the names accessible on ' jpayne@69: 'module. If\n' jpayne@69: 'present, this function overrides the standard "dir()" search ' jpayne@69: 'on a\n' jpayne@69: 'module.\n' jpayne@69: '\n' jpayne@69: 'For a more fine grained customization of the module behavior ' jpayne@69: '(setting\n' jpayne@69: 'attributes, properties, etc.), one can set the "__class__" ' jpayne@69: 'attribute\n' jpayne@69: 'of a module object to a subclass of "types.ModuleType". For ' jpayne@69: 'example:\n' jpayne@69: '\n' jpayne@69: ' import sys\n' jpayne@69: ' from types import ModuleType\n' jpayne@69: '\n' jpayne@69: ' class VerboseModule(ModuleType):\n' jpayne@69: ' def __repr__(self):\n' jpayne@69: " return f'Verbose {self.__name__}'\n" jpayne@69: '\n' jpayne@69: ' def __setattr__(self, attr, value):\n' jpayne@69: " print(f'Setting {attr}...')\n" jpayne@69: ' super().__setattr__(attr, value)\n' jpayne@69: '\n' jpayne@69: ' sys.modules[__name__].__class__ = VerboseModule\n' jpayne@69: '\n' jpayne@69: 'Note: Defining module "__getattr__" and setting module ' jpayne@69: '"__class__"\n' jpayne@69: ' only affect lookups made using the attribute access syntax ' jpayne@69: '–\n' jpayne@69: ' directly accessing the module globals (whether by code ' jpayne@69: 'within the\n' jpayne@69: ' module, or via a reference to the module’s globals ' jpayne@69: 'dictionary) is\n' jpayne@69: ' unaffected.\n' jpayne@69: '\n' jpayne@69: 'Changed in version 3.5: "__class__" module attribute is now ' jpayne@69: 'writable.\n' jpayne@69: '\n' jpayne@69: 'New in version 3.7: "__getattr__" and "__dir__" module ' jpayne@69: 'attributes.\n' jpayne@69: '\n' jpayne@69: 'See also:\n' jpayne@69: '\n' jpayne@69: ' **PEP 562** - Module __getattr__ and __dir__\n' jpayne@69: ' Describes the "__getattr__" and "__dir__" functions on ' jpayne@69: 'modules.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Implementing Descriptors\n' jpayne@69: '------------------------\n' jpayne@69: '\n' jpayne@69: 'The following methods only apply when an instance of the ' jpayne@69: 'class\n' jpayne@69: 'containing the method (a so-called *descriptor* class) ' jpayne@69: 'appears in an\n' jpayne@69: '*owner* class (the descriptor must be in either the owner’s ' jpayne@69: 'class\n' jpayne@69: 'dictionary or in the class dictionary for one of its ' jpayne@69: 'parents). In the\n' jpayne@69: 'examples below, “the attribute” refers to the attribute ' jpayne@69: 'whose name is\n' jpayne@69: 'the key of the property in the owner class’ "__dict__".\n' jpayne@69: '\n' jpayne@69: 'object.__get__(self, instance, owner=None)\n' jpayne@69: '\n' jpayne@69: ' Called to get the attribute of the owner class (class ' jpayne@69: 'attribute\n' jpayne@69: ' access) or of an instance of that class (instance ' jpayne@69: 'attribute\n' jpayne@69: ' access). The optional *owner* argument is the owner ' jpayne@69: 'class, while\n' jpayne@69: ' *instance* is the instance that the attribute was ' jpayne@69: 'accessed through,\n' jpayne@69: ' or "None" when the attribute is accessed through the ' jpayne@69: '*owner*.\n' jpayne@69: '\n' jpayne@69: ' This method should return the computed attribute value or ' jpayne@69: 'raise an\n' jpayne@69: ' "AttributeError" exception.\n' jpayne@69: '\n' jpayne@69: ' **PEP 252** specifies that "__get__()" is callable with ' jpayne@69: 'one or two\n' jpayne@69: ' arguments. Python’s own built-in descriptors support ' jpayne@69: 'this\n' jpayne@69: ' specification; however, it is likely that some ' jpayne@69: 'third-party tools\n' jpayne@69: ' have descriptors that require both arguments. Python’s ' jpayne@69: 'own\n' jpayne@69: ' "__getattribute__()" implementation always passes in both ' jpayne@69: 'arguments\n' jpayne@69: ' whether they are required or not.\n' jpayne@69: '\n' jpayne@69: 'object.__set__(self, instance, value)\n' jpayne@69: '\n' jpayne@69: ' Called to set the attribute on an instance *instance* of ' jpayne@69: 'the owner\n' jpayne@69: ' class to a new value, *value*.\n' jpayne@69: '\n' jpayne@69: ' Note, adding "__set__()" or "__delete__()" changes the ' jpayne@69: 'kind of\n' jpayne@69: ' descriptor to a “data descriptor”. See Invoking ' jpayne@69: 'Descriptors for\n' jpayne@69: ' more details.\n' jpayne@69: '\n' jpayne@69: 'object.__delete__(self, instance)\n' jpayne@69: '\n' jpayne@69: ' Called to delete the attribute on an instance *instance* ' jpayne@69: 'of the\n' jpayne@69: ' owner class.\n' jpayne@69: '\n' jpayne@69: 'object.__set_name__(self, owner, name)\n' jpayne@69: '\n' jpayne@69: ' Called at the time the owning class *owner* is created. ' jpayne@69: 'The\n' jpayne@69: ' descriptor has been assigned to *name*.\n' jpayne@69: '\n' jpayne@69: ' Note: "__set_name__()" is only called implicitly as part ' jpayne@69: 'of the\n' jpayne@69: ' "type" constructor, so it will need to be called ' jpayne@69: 'explicitly with\n' jpayne@69: ' the appropriate parameters when a descriptor is added ' jpayne@69: 'to a class\n' jpayne@69: ' after initial creation:\n' jpayne@69: '\n' jpayne@69: ' class A:\n' jpayne@69: ' pass\n' jpayne@69: ' descr = custom_descriptor()\n' jpayne@69: ' A.attr = descr\n' jpayne@69: " descr.__set_name__(A, 'attr')\n" jpayne@69: '\n' jpayne@69: ' See Creating the class object for more details.\n' jpayne@69: '\n' jpayne@69: ' New in version 3.6.\n' jpayne@69: '\n' jpayne@69: 'The attribute "__objclass__" is interpreted by the "inspect" ' jpayne@69: 'module as\n' jpayne@69: 'specifying the class where this object was defined (setting ' jpayne@69: 'this\n' jpayne@69: 'appropriately can assist in runtime introspection of dynamic ' jpayne@69: 'class\n' jpayne@69: 'attributes). For callables, it may indicate that an instance ' jpayne@69: 'of the\n' jpayne@69: 'given type (or a subclass) is expected or required as the ' jpayne@69: 'first\n' jpayne@69: 'positional argument (for example, CPython sets this ' jpayne@69: 'attribute for\n' jpayne@69: 'unbound methods that are implemented in C).\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Invoking Descriptors\n' jpayne@69: '--------------------\n' jpayne@69: '\n' jpayne@69: 'In general, a descriptor is an object attribute with ' jpayne@69: '“binding\n' jpayne@69: 'behavior”, one whose attribute access has been overridden by ' jpayne@69: 'methods\n' jpayne@69: 'in the descriptor protocol: "__get__()", "__set__()", and\n' jpayne@69: '"__delete__()". If any of those methods are defined for an ' jpayne@69: 'object, it\n' jpayne@69: 'is said to be a descriptor.\n' jpayne@69: '\n' jpayne@69: 'The default behavior for attribute access is to get, set, or ' jpayne@69: 'delete\n' jpayne@69: 'the attribute from an object’s dictionary. For instance, ' jpayne@69: '"a.x" has a\n' jpayne@69: 'lookup chain starting with "a.__dict__[\'x\']", then\n' jpayne@69: '"type(a).__dict__[\'x\']", and continuing through the base ' jpayne@69: 'classes of\n' jpayne@69: '"type(a)" excluding metaclasses.\n' jpayne@69: '\n' jpayne@69: 'However, if the looked-up value is an object defining one of ' jpayne@69: 'the\n' jpayne@69: 'descriptor methods, then Python may override the default ' jpayne@69: 'behavior and\n' jpayne@69: 'invoke the descriptor method instead. Where this occurs in ' jpayne@69: 'the\n' jpayne@69: 'precedence chain depends on which descriptor methods were ' jpayne@69: 'defined and\n' jpayne@69: 'how they were called.\n' jpayne@69: '\n' jpayne@69: 'The starting point for descriptor invocation is a binding, ' jpayne@69: '"a.x". How\n' jpayne@69: 'the arguments are assembled depends on "a":\n' jpayne@69: '\n' jpayne@69: 'Direct Call\n' jpayne@69: ' The simplest and least common call is when user code ' jpayne@69: 'directly\n' jpayne@69: ' invokes a descriptor method: "x.__get__(a)".\n' jpayne@69: '\n' jpayne@69: 'Instance Binding\n' jpayne@69: ' If binding to an object instance, "a.x" is transformed ' jpayne@69: 'into the\n' jpayne@69: ' call: "type(a).__dict__[\'x\'].__get__(a, type(a))".\n' jpayne@69: '\n' jpayne@69: 'Class Binding\n' jpayne@69: ' If binding to a class, "A.x" is transformed into the ' jpayne@69: 'call:\n' jpayne@69: ' "A.__dict__[\'x\'].__get__(None, A)".\n' jpayne@69: '\n' jpayne@69: 'Super Binding\n' jpayne@69: ' If "a" is an instance of "super", then the binding ' jpayne@69: '"super(B,\n' jpayne@69: ' obj).m()" searches "obj.__class__.__mro__" for the base ' jpayne@69: 'class "A"\n' jpayne@69: ' immediately preceding "B" and then invokes the descriptor ' jpayne@69: 'with the\n' jpayne@69: ' call: "A.__dict__[\'m\'].__get__(obj, obj.__class__)".\n' jpayne@69: '\n' jpayne@69: 'For instance bindings, the precedence of descriptor ' jpayne@69: 'invocation depends\n' jpayne@69: 'on the which descriptor methods are defined. A descriptor ' jpayne@69: 'can define\n' jpayne@69: 'any combination of "__get__()", "__set__()" and ' jpayne@69: '"__delete__()". If it\n' jpayne@69: 'does not define "__get__()", then accessing the attribute ' jpayne@69: 'will return\n' jpayne@69: 'the descriptor object itself unless there is a value in the ' jpayne@69: 'object’s\n' jpayne@69: 'instance dictionary. If the descriptor defines "__set__()" ' jpayne@69: 'and/or\n' jpayne@69: '"__delete__()", it is a data descriptor; if it defines ' jpayne@69: 'neither, it is\n' jpayne@69: 'a non-data descriptor. Normally, data descriptors define ' jpayne@69: 'both\n' jpayne@69: '"__get__()" and "__set__()", while non-data descriptors have ' jpayne@69: 'just the\n' jpayne@69: '"__get__()" method. Data descriptors with "__set__()" and ' jpayne@69: '"__get__()"\n' jpayne@69: 'defined always override a redefinition in an instance ' jpayne@69: 'dictionary. In\n' jpayne@69: 'contrast, non-data descriptors can be overridden by ' jpayne@69: 'instances.\n' jpayne@69: '\n' jpayne@69: 'Python methods (including "staticmethod()" and ' jpayne@69: '"classmethod()") are\n' jpayne@69: 'implemented as non-data descriptors. Accordingly, instances ' jpayne@69: 'can\n' jpayne@69: 'redefine and override methods. This allows individual ' jpayne@69: 'instances to\n' jpayne@69: 'acquire behaviors that differ from other instances of the ' jpayne@69: 'same class.\n' jpayne@69: '\n' jpayne@69: 'The "property()" function is implemented as a data ' jpayne@69: 'descriptor.\n' jpayne@69: 'Accordingly, instances cannot override the behavior of a ' jpayne@69: 'property.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: '__slots__\n' jpayne@69: '---------\n' jpayne@69: '\n' jpayne@69: '*__slots__* allow us to explicitly declare data members ' jpayne@69: '(like\n' jpayne@69: 'properties) and deny the creation of *__dict__* and ' jpayne@69: '*__weakref__*\n' jpayne@69: '(unless explicitly declared in *__slots__* or available in a ' jpayne@69: 'parent.)\n' jpayne@69: '\n' jpayne@69: 'The space saved over using *__dict__* can be significant. ' jpayne@69: 'Attribute\n' jpayne@69: 'lookup speed can be significantly improved as well.\n' jpayne@69: '\n' jpayne@69: 'object.__slots__\n' jpayne@69: '\n' jpayne@69: ' This class variable can be assigned a string, iterable, ' jpayne@69: 'or sequence\n' jpayne@69: ' of strings with variable names used by instances. ' jpayne@69: '*__slots__*\n' jpayne@69: ' reserves space for the declared variables and prevents ' jpayne@69: 'the\n' jpayne@69: ' automatic creation of *__dict__* and *__weakref__* for ' jpayne@69: 'each\n' jpayne@69: ' instance.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Notes on using *__slots__*\n' jpayne@69: '~~~~~~~~~~~~~~~~~~~~~~~~~~\n' jpayne@69: '\n' jpayne@69: '* When inheriting from a class without *__slots__*, the ' jpayne@69: '*__dict__*\n' jpayne@69: ' and *__weakref__* attribute of the instances will always ' jpayne@69: 'be\n' jpayne@69: ' accessible.\n' jpayne@69: '\n' jpayne@69: '* Without a *__dict__* variable, instances cannot be ' jpayne@69: 'assigned new\n' jpayne@69: ' variables not listed in the *__slots__* definition. ' jpayne@69: 'Attempts to\n' jpayne@69: ' assign to an unlisted variable name raises ' jpayne@69: '"AttributeError". If\n' jpayne@69: ' dynamic assignment of new variables is desired, then add\n' jpayne@69: ' "\'__dict__\'" to the sequence of strings in the ' jpayne@69: '*__slots__*\n' jpayne@69: ' declaration.\n' jpayne@69: '\n' jpayne@69: '* Without a *__weakref__* variable for each instance, ' jpayne@69: 'classes\n' jpayne@69: ' defining *__slots__* do not support weak references to ' jpayne@69: 'its\n' jpayne@69: ' instances. If weak reference support is needed, then add\n' jpayne@69: ' "\'__weakref__\'" to the sequence of strings in the ' jpayne@69: '*__slots__*\n' jpayne@69: ' declaration.\n' jpayne@69: '\n' jpayne@69: '* *__slots__* are implemented at the class level by ' jpayne@69: 'creating\n' jpayne@69: ' descriptors (Implementing Descriptors) for each variable ' jpayne@69: 'name. As a\n' jpayne@69: ' result, class attributes cannot be used to set default ' jpayne@69: 'values for\n' jpayne@69: ' instance variables defined by *__slots__*; otherwise, the ' jpayne@69: 'class\n' jpayne@69: ' attribute would overwrite the descriptor assignment.\n' jpayne@69: '\n' jpayne@69: '* The action of a *__slots__* declaration is not limited to ' jpayne@69: 'the\n' jpayne@69: ' class where it is defined. *__slots__* declared in ' jpayne@69: 'parents are\n' jpayne@69: ' available in child classes. However, child subclasses will ' jpayne@69: 'get a\n' jpayne@69: ' *__dict__* and *__weakref__* unless they also define ' jpayne@69: '*__slots__*\n' jpayne@69: ' (which should only contain names of any *additional* ' jpayne@69: 'slots).\n' jpayne@69: '\n' jpayne@69: '* If a class defines a slot also defined in a base class, ' jpayne@69: 'the\n' jpayne@69: ' instance variable defined by the base class slot is ' jpayne@69: 'inaccessible\n' jpayne@69: ' (except by retrieving its descriptor directly from the ' jpayne@69: 'base class).\n' jpayne@69: ' This renders the meaning of the program undefined. In the ' jpayne@69: 'future, a\n' jpayne@69: ' check may be added to prevent this.\n' jpayne@69: '\n' jpayne@69: '* Nonempty *__slots__* does not work for classes derived ' jpayne@69: 'from\n' jpayne@69: ' “variable-length” built-in types such as "int", "bytes" ' jpayne@69: 'and "tuple".\n' jpayne@69: '\n' jpayne@69: '* Any non-string iterable may be assigned to *__slots__*. ' jpayne@69: 'Mappings\n' jpayne@69: ' may also be used; however, in the future, special meaning ' jpayne@69: 'may be\n' jpayne@69: ' assigned to the values corresponding to each key.\n' jpayne@69: '\n' jpayne@69: '* *__class__* assignment works only if both classes have the ' jpayne@69: 'same\n' jpayne@69: ' *__slots__*.\n' jpayne@69: '\n' jpayne@69: '* Multiple inheritance with multiple slotted parent classes ' jpayne@69: 'can be\n' jpayne@69: ' used, but only one parent is allowed to have attributes ' jpayne@69: 'created by\n' jpayne@69: ' slots (the other bases must have empty slot layouts) - ' jpayne@69: 'violations\n' jpayne@69: ' raise "TypeError".\n' jpayne@69: '\n' jpayne@69: '* If an iterator is used for *__slots__* then a descriptor ' jpayne@69: 'is\n' jpayne@69: ' created for each of the iterator’s values. However, the ' jpayne@69: '*__slots__*\n' jpayne@69: ' attribute will be an empty iterator.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Customizing class creation\n' jpayne@69: '==========================\n' jpayne@69: '\n' jpayne@69: 'Whenever a class inherits from another class, ' jpayne@69: '*__init_subclass__* is\n' jpayne@69: 'called on that class. This way, it is possible to write ' jpayne@69: 'classes which\n' jpayne@69: 'change the behavior of subclasses. This is closely related ' jpayne@69: 'to class\n' jpayne@69: 'decorators, but where class decorators only affect the ' jpayne@69: 'specific class\n' jpayne@69: 'they’re applied to, "__init_subclass__" solely applies to ' jpayne@69: 'future\n' jpayne@69: 'subclasses of the class defining the method.\n' jpayne@69: '\n' jpayne@69: 'classmethod object.__init_subclass__(cls)\n' jpayne@69: '\n' jpayne@69: ' This method is called whenever the containing class is ' jpayne@69: 'subclassed.\n' jpayne@69: ' *cls* is then the new subclass. If defined as a normal ' jpayne@69: 'instance\n' jpayne@69: ' method, this method is implicitly converted to a class ' jpayne@69: 'method.\n' jpayne@69: '\n' jpayne@69: ' Keyword arguments which are given to a new class are ' jpayne@69: 'passed to the\n' jpayne@69: ' parent’s class "__init_subclass__". For compatibility ' jpayne@69: 'with other\n' jpayne@69: ' classes using "__init_subclass__", one should take out ' jpayne@69: 'the needed\n' jpayne@69: ' keyword arguments and pass the others over to the base ' jpayne@69: 'class, as\n' jpayne@69: ' in:\n' jpayne@69: '\n' jpayne@69: ' class Philosopher:\n' jpayne@69: ' def __init_subclass__(cls, /, default_name, ' jpayne@69: '**kwargs):\n' jpayne@69: ' super().__init_subclass__(**kwargs)\n' jpayne@69: ' cls.default_name = default_name\n' jpayne@69: '\n' jpayne@69: ' class AustralianPhilosopher(Philosopher, ' jpayne@69: 'default_name="Bruce"):\n' jpayne@69: ' pass\n' jpayne@69: '\n' jpayne@69: ' The default implementation "object.__init_subclass__" ' jpayne@69: 'does nothing,\n' jpayne@69: ' but raises an error if it is called with any arguments.\n' jpayne@69: '\n' jpayne@69: ' Note: The metaclass hint "metaclass" is consumed by the ' jpayne@69: 'rest of\n' jpayne@69: ' the type machinery, and is never passed to ' jpayne@69: '"__init_subclass__"\n' jpayne@69: ' implementations. The actual metaclass (rather than the ' jpayne@69: 'explicit\n' jpayne@69: ' hint) can be accessed as "type(cls)".\n' jpayne@69: '\n' jpayne@69: ' New in version 3.6.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Metaclasses\n' jpayne@69: '-----------\n' jpayne@69: '\n' jpayne@69: 'By default, classes are constructed using "type()". The ' jpayne@69: 'class body is\n' jpayne@69: 'executed in a new namespace and the class name is bound ' jpayne@69: 'locally to the\n' jpayne@69: 'result of "type(name, bases, namespace)".\n' jpayne@69: '\n' jpayne@69: 'The class creation process can be customized by passing the\n' jpayne@69: '"metaclass" keyword argument in the class definition line, ' jpayne@69: 'or by\n' jpayne@69: 'inheriting from an existing class that included such an ' jpayne@69: 'argument. In\n' jpayne@69: 'the following example, both "MyClass" and "MySubclass" are ' jpayne@69: 'instances\n' jpayne@69: 'of "Meta":\n' jpayne@69: '\n' jpayne@69: ' class Meta(type):\n' jpayne@69: ' pass\n' jpayne@69: '\n' jpayne@69: ' class MyClass(metaclass=Meta):\n' jpayne@69: ' pass\n' jpayne@69: '\n' jpayne@69: ' class MySubclass(MyClass):\n' jpayne@69: ' pass\n' jpayne@69: '\n' jpayne@69: 'Any other keyword arguments that are specified in the class ' jpayne@69: 'definition\n' jpayne@69: 'are passed through to all metaclass operations described ' jpayne@69: 'below.\n' jpayne@69: '\n' jpayne@69: 'When a class definition is executed, the following steps ' jpayne@69: 'occur:\n' jpayne@69: '\n' jpayne@69: '* MRO entries are resolved;\n' jpayne@69: '\n' jpayne@69: '* the appropriate metaclass is determined;\n' jpayne@69: '\n' jpayne@69: '* the class namespace is prepared;\n' jpayne@69: '\n' jpayne@69: '* the class body is executed;\n' jpayne@69: '\n' jpayne@69: '* the class object is created.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Resolving MRO entries\n' jpayne@69: '---------------------\n' jpayne@69: '\n' jpayne@69: 'If a base that appears in class definition is not an ' jpayne@69: 'instance of\n' jpayne@69: '"type", then an "__mro_entries__" method is searched on it. ' jpayne@69: 'If found,\n' jpayne@69: 'it is called with the original bases tuple. This method must ' jpayne@69: 'return a\n' jpayne@69: 'tuple of classes that will be used instead of this base. The ' jpayne@69: 'tuple may\n' jpayne@69: 'be empty, in such case the original base is ignored.\n' jpayne@69: '\n' jpayne@69: 'See also: **PEP 560** - Core support for typing module and ' jpayne@69: 'generic\n' jpayne@69: ' types\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Determining the appropriate metaclass\n' jpayne@69: '-------------------------------------\n' jpayne@69: '\n' jpayne@69: 'The appropriate metaclass for a class definition is ' jpayne@69: 'determined as\n' jpayne@69: 'follows:\n' jpayne@69: '\n' jpayne@69: '* if no bases and no explicit metaclass are given, then ' jpayne@69: '"type()" is\n' jpayne@69: ' used;\n' jpayne@69: '\n' jpayne@69: '* if an explicit metaclass is given and it is *not* an ' jpayne@69: 'instance of\n' jpayne@69: ' "type()", then it is used directly as the metaclass;\n' jpayne@69: '\n' jpayne@69: '* if an instance of "type()" is given as the explicit ' jpayne@69: 'metaclass, or\n' jpayne@69: ' bases are defined, then the most derived metaclass is ' jpayne@69: 'used.\n' jpayne@69: '\n' jpayne@69: 'The most derived metaclass is selected from the explicitly ' jpayne@69: 'specified\n' jpayne@69: 'metaclass (if any) and the metaclasses (i.e. "type(cls)") of ' jpayne@69: 'all\n' jpayne@69: 'specified base classes. The most derived metaclass is one ' jpayne@69: 'which is a\n' jpayne@69: 'subtype of *all* of these candidate metaclasses. If none of ' jpayne@69: 'the\n' jpayne@69: 'candidate metaclasses meets that criterion, then the class ' jpayne@69: 'definition\n' jpayne@69: 'will fail with "TypeError".\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Preparing the class namespace\n' jpayne@69: '-----------------------------\n' jpayne@69: '\n' jpayne@69: 'Once the appropriate metaclass has been identified, then the ' jpayne@69: 'class\n' jpayne@69: 'namespace is prepared. If the metaclass has a "__prepare__" ' jpayne@69: 'attribute,\n' jpayne@69: 'it is called as "namespace = metaclass.__prepare__(name, ' jpayne@69: 'bases,\n' jpayne@69: '**kwds)" (where the additional keyword arguments, if any, ' jpayne@69: 'come from\n' jpayne@69: 'the class definition).\n' jpayne@69: '\n' jpayne@69: 'If the metaclass has no "__prepare__" attribute, then the ' jpayne@69: 'class\n' jpayne@69: 'namespace is initialised as an empty ordered mapping.\n' jpayne@69: '\n' jpayne@69: 'See also:\n' jpayne@69: '\n' jpayne@69: ' **PEP 3115** - Metaclasses in Python 3000\n' jpayne@69: ' Introduced the "__prepare__" namespace hook\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Executing the class body\n' jpayne@69: '------------------------\n' jpayne@69: '\n' jpayne@69: 'The class body is executed (approximately) as "exec(body, ' jpayne@69: 'globals(),\n' jpayne@69: 'namespace)". The key difference from a normal call to ' jpayne@69: '"exec()" is that\n' jpayne@69: 'lexical scoping allows the class body (including any ' jpayne@69: 'methods) to\n' jpayne@69: 'reference names from the current and outer scopes when the ' jpayne@69: 'class\n' jpayne@69: 'definition occurs inside a function.\n' jpayne@69: '\n' jpayne@69: 'However, even when the class definition occurs inside the ' jpayne@69: 'function,\n' jpayne@69: 'methods defined inside the class still cannot see names ' jpayne@69: 'defined at the\n' jpayne@69: 'class scope. Class variables must be accessed through the ' jpayne@69: 'first\n' jpayne@69: 'parameter of instance or class methods, or through the ' jpayne@69: 'implicit\n' jpayne@69: 'lexically scoped "__class__" reference described in the next ' jpayne@69: 'section.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Creating the class object\n' jpayne@69: '-------------------------\n' jpayne@69: '\n' jpayne@69: 'Once the class namespace has been populated by executing the ' jpayne@69: 'class\n' jpayne@69: 'body, the class object is created by calling ' jpayne@69: '"metaclass(name, bases,\n' jpayne@69: 'namespace, **kwds)" (the additional keywords passed here are ' jpayne@69: 'the same\n' jpayne@69: 'as those passed to "__prepare__").\n' jpayne@69: '\n' jpayne@69: 'This class object is the one that will be referenced by the ' jpayne@69: 'zero-\n' jpayne@69: 'argument form of "super()". "__class__" is an implicit ' jpayne@69: 'closure\n' jpayne@69: 'reference created by the compiler if any methods in a class ' jpayne@69: 'body refer\n' jpayne@69: 'to either "__class__" or "super". This allows the zero ' jpayne@69: 'argument form\n' jpayne@69: 'of "super()" to correctly identify the class being defined ' jpayne@69: 'based on\n' jpayne@69: 'lexical scoping, while the class or instance that was used ' jpayne@69: 'to make the\n' jpayne@69: 'current call is identified based on the first argument ' jpayne@69: 'passed to the\n' jpayne@69: 'method.\n' jpayne@69: '\n' jpayne@69: '**CPython implementation detail:** In CPython 3.6 and later, ' jpayne@69: 'the\n' jpayne@69: '"__class__" cell is passed to the metaclass as a ' jpayne@69: '"__classcell__" entry\n' jpayne@69: 'in the class namespace. If present, this must be propagated ' jpayne@69: 'up to the\n' jpayne@69: '"type.__new__" call in order for the class to be ' jpayne@69: 'initialised\n' jpayne@69: 'correctly. Failing to do so will result in a "RuntimeError" ' jpayne@69: 'in Python\n' jpayne@69: '3.8.\n' jpayne@69: '\n' jpayne@69: 'When using the default metaclass "type", or any metaclass ' jpayne@69: 'that\n' jpayne@69: 'ultimately calls "type.__new__", the following additional\n' jpayne@69: 'customisation steps are invoked after creating the class ' jpayne@69: 'object:\n' jpayne@69: '\n' jpayne@69: '* first, "type.__new__" collects all of the descriptors in ' jpayne@69: 'the class\n' jpayne@69: ' namespace that define a "__set_name__()" method;\n' jpayne@69: '\n' jpayne@69: '* second, all of these "__set_name__" methods are called ' jpayne@69: 'with the\n' jpayne@69: ' class being defined and the assigned name of that ' jpayne@69: 'particular\n' jpayne@69: ' descriptor;\n' jpayne@69: '\n' jpayne@69: '* finally, the "__init_subclass__()" hook is called on the ' jpayne@69: 'immediate\n' jpayne@69: ' parent of the new class in its method resolution order.\n' jpayne@69: '\n' jpayne@69: 'After the class object is created, it is passed to the ' jpayne@69: 'class\n' jpayne@69: 'decorators included in the class definition (if any) and the ' jpayne@69: 'resulting\n' jpayne@69: 'object is bound in the local namespace as the defined ' jpayne@69: 'class.\n' jpayne@69: '\n' jpayne@69: 'When a new class is created by "type.__new__", the object ' jpayne@69: 'provided as\n' jpayne@69: 'the namespace parameter is copied to a new ordered mapping ' jpayne@69: 'and the\n' jpayne@69: 'original object is discarded. The new copy is wrapped in a ' jpayne@69: 'read-only\n' jpayne@69: 'proxy, which becomes the "__dict__" attribute of the class ' jpayne@69: 'object.\n' jpayne@69: '\n' jpayne@69: 'See also:\n' jpayne@69: '\n' jpayne@69: ' **PEP 3135** - New super\n' jpayne@69: ' Describes the implicit "__class__" closure reference\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Uses for metaclasses\n' jpayne@69: '--------------------\n' jpayne@69: '\n' jpayne@69: 'The potential uses for metaclasses are boundless. Some ideas ' jpayne@69: 'that have\n' jpayne@69: 'been explored include enum, logging, interface checking, ' jpayne@69: 'automatic\n' jpayne@69: 'delegation, automatic property creation, proxies, ' jpayne@69: 'frameworks, and\n' jpayne@69: 'automatic resource locking/synchronization.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Customizing instance and subclass checks\n' jpayne@69: '========================================\n' jpayne@69: '\n' jpayne@69: 'The following methods are used to override the default ' jpayne@69: 'behavior of the\n' jpayne@69: '"isinstance()" and "issubclass()" built-in functions.\n' jpayne@69: '\n' jpayne@69: 'In particular, the metaclass "abc.ABCMeta" implements these ' jpayne@69: 'methods in\n' jpayne@69: 'order to allow the addition of Abstract Base Classes (ABCs) ' jpayne@69: 'as\n' jpayne@69: '“virtual base classes” to any class or type (including ' jpayne@69: 'built-in\n' jpayne@69: 'types), including other ABCs.\n' jpayne@69: '\n' jpayne@69: 'class.__instancecheck__(self, instance)\n' jpayne@69: '\n' jpayne@69: ' Return true if *instance* should be considered a (direct ' jpayne@69: 'or\n' jpayne@69: ' indirect) instance of *class*. If defined, called to ' jpayne@69: 'implement\n' jpayne@69: ' "isinstance(instance, class)".\n' jpayne@69: '\n' jpayne@69: 'class.__subclasscheck__(self, subclass)\n' jpayne@69: '\n' jpayne@69: ' Return true if *subclass* should be considered a (direct ' jpayne@69: 'or\n' jpayne@69: ' indirect) subclass of *class*. If defined, called to ' jpayne@69: 'implement\n' jpayne@69: ' "issubclass(subclass, class)".\n' jpayne@69: '\n' jpayne@69: 'Note that these methods are looked up on the type ' jpayne@69: '(metaclass) of a\n' jpayne@69: 'class. They cannot be defined as class methods in the ' jpayne@69: 'actual class.\n' jpayne@69: 'This is consistent with the lookup of special methods that ' jpayne@69: 'are called\n' jpayne@69: 'on instances, only in this case the instance is itself a ' jpayne@69: 'class.\n' jpayne@69: '\n' jpayne@69: 'See also:\n' jpayne@69: '\n' jpayne@69: ' **PEP 3119** - Introducing Abstract Base Classes\n' jpayne@69: ' Includes the specification for customizing ' jpayne@69: '"isinstance()" and\n' jpayne@69: ' "issubclass()" behavior through "__instancecheck__()" ' jpayne@69: 'and\n' jpayne@69: ' "__subclasscheck__()", with motivation for this ' jpayne@69: 'functionality in\n' jpayne@69: ' the context of adding Abstract Base Classes (see the ' jpayne@69: '"abc"\n' jpayne@69: ' module) to the language.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Emulating generic types\n' jpayne@69: '=======================\n' jpayne@69: '\n' jpayne@69: 'One can implement the generic class syntax as specified by ' jpayne@69: '**PEP 484**\n' jpayne@69: '(for example "List[int]") by defining a special method:\n' jpayne@69: '\n' jpayne@69: 'classmethod object.__class_getitem__(cls, key)\n' jpayne@69: '\n' jpayne@69: ' Return an object representing the specialization of a ' jpayne@69: 'generic class\n' jpayne@69: ' by type arguments found in *key*.\n' jpayne@69: '\n' jpayne@69: 'This method is looked up on the class object itself, and ' jpayne@69: 'when defined\n' jpayne@69: 'in the class body, this method is implicitly a class ' jpayne@69: 'method. Note,\n' jpayne@69: 'this mechanism is primarily reserved for use with static ' jpayne@69: 'type hints,\n' jpayne@69: 'other usage is discouraged.\n' jpayne@69: '\n' jpayne@69: 'See also: **PEP 560** - Core support for typing module and ' jpayne@69: 'generic\n' jpayne@69: ' types\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Emulating callable objects\n' jpayne@69: '==========================\n' jpayne@69: '\n' jpayne@69: 'object.__call__(self[, args...])\n' jpayne@69: '\n' jpayne@69: ' Called when the instance is “called” as a function; if ' jpayne@69: 'this method\n' jpayne@69: ' is defined, "x(arg1, arg2, ...)" is a shorthand for\n' jpayne@69: ' "x.__call__(arg1, arg2, ...)".\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Emulating container types\n' jpayne@69: '=========================\n' jpayne@69: '\n' jpayne@69: 'The following methods can be defined to implement container ' jpayne@69: 'objects.\n' jpayne@69: 'Containers usually are sequences (such as lists or tuples) ' jpayne@69: 'or mappings\n' jpayne@69: '(like dictionaries), but can represent other containers as ' jpayne@69: 'well. The\n' jpayne@69: 'first set of methods is used either to emulate a sequence or ' jpayne@69: 'to\n' jpayne@69: 'emulate a mapping; the difference is that for a sequence, ' jpayne@69: 'the\n' jpayne@69: 'allowable keys should be the integers *k* for which "0 <= k ' jpayne@69: '< N" where\n' jpayne@69: '*N* is the length of the sequence, or slice objects, which ' jpayne@69: 'define a\n' jpayne@69: 'range of items. It is also recommended that mappings ' jpayne@69: 'provide the\n' jpayne@69: 'methods "keys()", "values()", "items()", "get()", ' jpayne@69: '"clear()",\n' jpayne@69: '"setdefault()", "pop()", "popitem()", "copy()", and ' jpayne@69: '"update()"\n' jpayne@69: 'behaving similar to those for Python’s standard dictionary ' jpayne@69: 'objects.\n' jpayne@69: 'The "collections.abc" module provides a "MutableMapping" ' jpayne@69: 'abstract base\n' jpayne@69: 'class to help create those methods from a base set of ' jpayne@69: '"__getitem__()",\n' jpayne@69: '"__setitem__()", "__delitem__()", and "keys()". Mutable ' jpayne@69: 'sequences\n' jpayne@69: 'should provide methods "append()", "count()", "index()", ' jpayne@69: '"extend()",\n' jpayne@69: '"insert()", "pop()", "remove()", "reverse()" and "sort()", ' jpayne@69: 'like Python\n' jpayne@69: 'standard list objects. Finally, sequence types should ' jpayne@69: 'implement\n' jpayne@69: 'addition (meaning concatenation) and multiplication ' jpayne@69: '(meaning\n' jpayne@69: 'repetition) by defining the methods "__add__()", ' jpayne@69: '"__radd__()",\n' jpayne@69: '"__iadd__()", "__mul__()", "__rmul__()" and "__imul__()" ' jpayne@69: 'described\n' jpayne@69: 'below; they should not define other numerical operators. It ' jpayne@69: 'is\n' jpayne@69: 'recommended that both mappings and sequences implement the\n' jpayne@69: '"__contains__()" method to allow efficient use of the "in" ' jpayne@69: 'operator;\n' jpayne@69: 'for mappings, "in" should search the mapping’s keys; for ' jpayne@69: 'sequences, it\n' jpayne@69: 'should search through the values. It is further recommended ' jpayne@69: 'that both\n' jpayne@69: 'mappings and sequences implement the "__iter__()" method to ' jpayne@69: 'allow\n' jpayne@69: 'efficient iteration through the container; for mappings, ' jpayne@69: '"__iter__()"\n' jpayne@69: 'should iterate through the object’s keys; for sequences, it ' jpayne@69: 'should\n' jpayne@69: 'iterate through the values.\n' jpayne@69: '\n' jpayne@69: 'object.__len__(self)\n' jpayne@69: '\n' jpayne@69: ' Called to implement the built-in function "len()". ' jpayne@69: 'Should return\n' jpayne@69: ' the length of the object, an integer ">=" 0. Also, an ' jpayne@69: 'object that\n' jpayne@69: ' doesn’t define a "__bool__()" method and whose ' jpayne@69: '"__len__()" method\n' jpayne@69: ' returns zero is considered to be false in a Boolean ' jpayne@69: 'context.\n' jpayne@69: '\n' jpayne@69: ' **CPython implementation detail:** In CPython, the length ' jpayne@69: 'is\n' jpayne@69: ' required to be at most "sys.maxsize". If the length is ' jpayne@69: 'larger than\n' jpayne@69: ' "sys.maxsize" some features (such as "len()") may raise\n' jpayne@69: ' "OverflowError". To prevent raising "OverflowError" by ' jpayne@69: 'truth value\n' jpayne@69: ' testing, an object must define a "__bool__()" method.\n' jpayne@69: '\n' jpayne@69: 'object.__length_hint__(self)\n' jpayne@69: '\n' jpayne@69: ' Called to implement "operator.length_hint()". Should ' jpayne@69: 'return an\n' jpayne@69: ' estimated length for the object (which may be greater or ' jpayne@69: 'less than\n' jpayne@69: ' the actual length). The length must be an integer ">=" 0. ' jpayne@69: 'The\n' jpayne@69: ' return value may also be "NotImplemented", which is ' jpayne@69: 'treated the\n' jpayne@69: ' same as if the "__length_hint__" method didn’t exist at ' jpayne@69: 'all. This\n' jpayne@69: ' method is purely an optimization and is never required ' jpayne@69: 'for\n' jpayne@69: ' correctness.\n' jpayne@69: '\n' jpayne@69: ' New in version 3.4.\n' jpayne@69: '\n' jpayne@69: 'Note: Slicing is done exclusively with the following three ' jpayne@69: 'methods.\n' jpayne@69: ' A call like\n' jpayne@69: '\n' jpayne@69: ' a[1:2] = b\n' jpayne@69: '\n' jpayne@69: ' is translated to\n' jpayne@69: '\n' jpayne@69: ' a[slice(1, 2, None)] = b\n' jpayne@69: '\n' jpayne@69: ' and so forth. Missing slice items are always filled in ' jpayne@69: 'with "None".\n' jpayne@69: '\n' jpayne@69: 'object.__getitem__(self, key)\n' jpayne@69: '\n' jpayne@69: ' Called to implement evaluation of "self[key]". For ' jpayne@69: 'sequence types,\n' jpayne@69: ' the accepted keys should be integers and slice objects. ' jpayne@69: 'Note that\n' jpayne@69: ' the special interpretation of negative indexes (if the ' jpayne@69: 'class wishes\n' jpayne@69: ' to emulate a sequence type) is up to the "__getitem__()" ' jpayne@69: 'method. If\n' jpayne@69: ' *key* is of an inappropriate type, "TypeError" may be ' jpayne@69: 'raised; if of\n' jpayne@69: ' a value outside the set of indexes for the sequence ' jpayne@69: '(after any\n' jpayne@69: ' special interpretation of negative values), "IndexError" ' jpayne@69: 'should be\n' jpayne@69: ' raised. For mapping types, if *key* is missing (not in ' jpayne@69: 'the\n' jpayne@69: ' container), "KeyError" should be raised.\n' jpayne@69: '\n' jpayne@69: ' Note: "for" loops expect that an "IndexError" will be ' jpayne@69: 'raised for\n' jpayne@69: ' illegal indexes to allow proper detection of the end of ' jpayne@69: 'the\n' jpayne@69: ' sequence.\n' jpayne@69: '\n' jpayne@69: 'object.__setitem__(self, key, value)\n' jpayne@69: '\n' jpayne@69: ' Called to implement assignment to "self[key]". Same note ' jpayne@69: 'as for\n' jpayne@69: ' "__getitem__()". This should only be implemented for ' jpayne@69: 'mappings if\n' jpayne@69: ' the objects support changes to the values for keys, or if ' jpayne@69: 'new keys\n' jpayne@69: ' can be added, or for sequences if elements can be ' jpayne@69: 'replaced. The\n' jpayne@69: ' same exceptions should be raised for improper *key* ' jpayne@69: 'values as for\n' jpayne@69: ' the "__getitem__()" method.\n' jpayne@69: '\n' jpayne@69: 'object.__delitem__(self, key)\n' jpayne@69: '\n' jpayne@69: ' Called to implement deletion of "self[key]". Same note ' jpayne@69: 'as for\n' jpayne@69: ' "__getitem__()". This should only be implemented for ' jpayne@69: 'mappings if\n' jpayne@69: ' the objects support removal of keys, or for sequences if ' jpayne@69: 'elements\n' jpayne@69: ' can be removed from the sequence. The same exceptions ' jpayne@69: 'should be\n' jpayne@69: ' raised for improper *key* values as for the ' jpayne@69: '"__getitem__()" method.\n' jpayne@69: '\n' jpayne@69: 'object.__missing__(self, key)\n' jpayne@69: '\n' jpayne@69: ' Called by "dict"."__getitem__()" to implement "self[key]" ' jpayne@69: 'for dict\n' jpayne@69: ' subclasses when key is not in the dictionary.\n' jpayne@69: '\n' jpayne@69: 'object.__iter__(self)\n' jpayne@69: '\n' jpayne@69: ' This method is called when an iterator is required for a ' jpayne@69: 'container.\n' jpayne@69: ' This method should return a new iterator object that can ' jpayne@69: 'iterate\n' jpayne@69: ' over all the objects in the container. For mappings, it ' jpayne@69: 'should\n' jpayne@69: ' iterate over the keys of the container.\n' jpayne@69: '\n' jpayne@69: ' Iterator objects also need to implement this method; they ' jpayne@69: 'are\n' jpayne@69: ' required to return themselves. For more information on ' jpayne@69: 'iterator\n' jpayne@69: ' objects, see Iterator Types.\n' jpayne@69: '\n' jpayne@69: 'object.__reversed__(self)\n' jpayne@69: '\n' jpayne@69: ' Called (if present) by the "reversed()" built-in to ' jpayne@69: 'implement\n' jpayne@69: ' reverse iteration. It should return a new iterator ' jpayne@69: 'object that\n' jpayne@69: ' iterates over all the objects in the container in reverse ' jpayne@69: 'order.\n' jpayne@69: '\n' jpayne@69: ' If the "__reversed__()" method is not provided, the ' jpayne@69: '"reversed()"\n' jpayne@69: ' built-in will fall back to using the sequence protocol ' jpayne@69: '("__len__()"\n' jpayne@69: ' and "__getitem__()"). Objects that support the sequence ' jpayne@69: 'protocol\n' jpayne@69: ' should only provide "__reversed__()" if they can provide ' jpayne@69: 'an\n' jpayne@69: ' implementation that is more efficient than the one ' jpayne@69: 'provided by\n' jpayne@69: ' "reversed()".\n' jpayne@69: '\n' jpayne@69: 'The membership test operators ("in" and "not in") are ' jpayne@69: 'normally\n' jpayne@69: 'implemented as an iteration through a container. However, ' jpayne@69: 'container\n' jpayne@69: 'objects can supply the following special method with a more ' jpayne@69: 'efficient\n' jpayne@69: 'implementation, which also does not require the object be ' jpayne@69: 'iterable.\n' jpayne@69: '\n' jpayne@69: 'object.__contains__(self, item)\n' jpayne@69: '\n' jpayne@69: ' Called to implement membership test operators. Should ' jpayne@69: 'return true\n' jpayne@69: ' if *item* is in *self*, false otherwise. For mapping ' jpayne@69: 'objects, this\n' jpayne@69: ' should consider the keys of the mapping rather than the ' jpayne@69: 'values or\n' jpayne@69: ' the key-item pairs.\n' jpayne@69: '\n' jpayne@69: ' For objects that don’t define "__contains__()", the ' jpayne@69: 'membership test\n' jpayne@69: ' first tries iteration via "__iter__()", then the old ' jpayne@69: 'sequence\n' jpayne@69: ' iteration protocol via "__getitem__()", see this section ' jpayne@69: 'in the\n' jpayne@69: ' language reference.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Emulating numeric types\n' jpayne@69: '=======================\n' jpayne@69: '\n' jpayne@69: 'The following methods can be defined to emulate numeric ' jpayne@69: 'objects.\n' jpayne@69: 'Methods corresponding to operations that are not supported ' jpayne@69: 'by the\n' jpayne@69: 'particular kind of number implemented (e.g., bitwise ' jpayne@69: 'operations for\n' jpayne@69: 'non-integral numbers) should be left undefined.\n' jpayne@69: '\n' jpayne@69: 'object.__add__(self, other)\n' jpayne@69: 'object.__sub__(self, other)\n' jpayne@69: 'object.__mul__(self, other)\n' jpayne@69: 'object.__matmul__(self, other)\n' jpayne@69: 'object.__truediv__(self, other)\n' jpayne@69: 'object.__floordiv__(self, other)\n' jpayne@69: 'object.__mod__(self, other)\n' jpayne@69: 'object.__divmod__(self, other)\n' jpayne@69: 'object.__pow__(self, other[, modulo])\n' jpayne@69: 'object.__lshift__(self, other)\n' jpayne@69: 'object.__rshift__(self, other)\n' jpayne@69: 'object.__and__(self, other)\n' jpayne@69: 'object.__xor__(self, other)\n' jpayne@69: 'object.__or__(self, other)\n' jpayne@69: '\n' jpayne@69: ' These methods are called to implement the binary ' jpayne@69: 'arithmetic\n' jpayne@69: ' operations ("+", "-", "*", "@", "/", "//", "%", ' jpayne@69: '"divmod()",\n' jpayne@69: ' "pow()", "**", "<<", ">>", "&", "^", "|"). For instance, ' jpayne@69: 'to\n' jpayne@69: ' evaluate the expression "x + y", where *x* is an instance ' jpayne@69: 'of a\n' jpayne@69: ' class that has an "__add__()" method, "x.__add__(y)" is ' jpayne@69: 'called.\n' jpayne@69: ' The "__divmod__()" method should be the equivalent to ' jpayne@69: 'using\n' jpayne@69: ' "__floordiv__()" and "__mod__()"; it should not be ' jpayne@69: 'related to\n' jpayne@69: ' "__truediv__()". Note that "__pow__()" should be defined ' jpayne@69: 'to accept\n' jpayne@69: ' an optional third argument if the ternary version of the ' jpayne@69: 'built-in\n' jpayne@69: ' "pow()" function is to be supported.\n' jpayne@69: '\n' jpayne@69: ' If one of those methods does not support the operation ' jpayne@69: 'with the\n' jpayne@69: ' supplied arguments, it should return "NotImplemented".\n' jpayne@69: '\n' jpayne@69: 'object.__radd__(self, other)\n' jpayne@69: 'object.__rsub__(self, other)\n' jpayne@69: 'object.__rmul__(self, other)\n' jpayne@69: 'object.__rmatmul__(self, other)\n' jpayne@69: 'object.__rtruediv__(self, other)\n' jpayne@69: 'object.__rfloordiv__(self, other)\n' jpayne@69: 'object.__rmod__(self, other)\n' jpayne@69: 'object.__rdivmod__(self, other)\n' jpayne@69: 'object.__rpow__(self, other)\n' jpayne@69: 'object.__rlshift__(self, other)\n' jpayne@69: 'object.__rrshift__(self, other)\n' jpayne@69: 'object.__rand__(self, other)\n' jpayne@69: 'object.__rxor__(self, other)\n' jpayne@69: 'object.__ror__(self, other)\n' jpayne@69: '\n' jpayne@69: ' These methods are called to implement the binary ' jpayne@69: 'arithmetic\n' jpayne@69: ' operations ("+", "-", "*", "@", "/", "//", "%", ' jpayne@69: '"divmod()",\n' jpayne@69: ' "pow()", "**", "<<", ">>", "&", "^", "|") with reflected ' jpayne@69: '(swapped)\n' jpayne@69: ' operands. These functions are only called if the left ' jpayne@69: 'operand does\n' jpayne@69: ' not support the corresponding operation [3] and the ' jpayne@69: 'operands are of\n' jpayne@69: ' different types. [4] For instance, to evaluate the ' jpayne@69: 'expression "x -\n' jpayne@69: ' y", where *y* is an instance of a class that has an ' jpayne@69: '"__rsub__()"\n' jpayne@69: ' method, "y.__rsub__(x)" is called if "x.__sub__(y)" ' jpayne@69: 'returns\n' jpayne@69: ' *NotImplemented*.\n' jpayne@69: '\n' jpayne@69: ' Note that ternary "pow()" will not try calling ' jpayne@69: '"__rpow__()" (the\n' jpayne@69: ' coercion rules would become too complicated).\n' jpayne@69: '\n' jpayne@69: ' Note: If the right operand’s type is a subclass of the ' jpayne@69: 'left\n' jpayne@69: ' operand’s type and that subclass provides the reflected ' jpayne@69: 'method\n' jpayne@69: ' for the operation, this method will be called before ' jpayne@69: 'the left\n' jpayne@69: ' operand’s non-reflected method. This behavior allows ' jpayne@69: 'subclasses\n' jpayne@69: ' to override their ancestors’ operations.\n' jpayne@69: '\n' jpayne@69: 'object.__iadd__(self, other)\n' jpayne@69: 'object.__isub__(self, other)\n' jpayne@69: 'object.__imul__(self, other)\n' jpayne@69: 'object.__imatmul__(self, other)\n' jpayne@69: 'object.__itruediv__(self, other)\n' jpayne@69: 'object.__ifloordiv__(self, other)\n' jpayne@69: 'object.__imod__(self, other)\n' jpayne@69: 'object.__ipow__(self, other[, modulo])\n' jpayne@69: 'object.__ilshift__(self, other)\n' jpayne@69: 'object.__irshift__(self, other)\n' jpayne@69: 'object.__iand__(self, other)\n' jpayne@69: 'object.__ixor__(self, other)\n' jpayne@69: 'object.__ior__(self, other)\n' jpayne@69: '\n' jpayne@69: ' These methods are called to implement the augmented ' jpayne@69: 'arithmetic\n' jpayne@69: ' assignments ("+=", "-=", "*=", "@=", "/=", "//=", "%=", ' jpayne@69: '"**=",\n' jpayne@69: ' "<<=", ">>=", "&=", "^=", "|="). These methods should ' jpayne@69: 'attempt to\n' jpayne@69: ' do the operation in-place (modifying *self*) and return ' jpayne@69: 'the result\n' jpayne@69: ' (which could be, but does not have to be, *self*). If a ' jpayne@69: 'specific\n' jpayne@69: ' method is not defined, the augmented assignment falls ' jpayne@69: 'back to the\n' jpayne@69: ' normal methods. For instance, if *x* is an instance of a ' jpayne@69: 'class\n' jpayne@69: ' with an "__iadd__()" method, "x += y" is equivalent to "x ' jpayne@69: '=\n' jpayne@69: ' x.__iadd__(y)" . Otherwise, "x.__add__(y)" and ' jpayne@69: '"y.__radd__(x)" are\n' jpayne@69: ' considered, as with the evaluation of "x + y". In ' jpayne@69: 'certain\n' jpayne@69: ' situations, augmented assignment can result in unexpected ' jpayne@69: 'errors\n' jpayne@69: ' (see Why does a_tuple[i] += [‘item’] raise an exception ' jpayne@69: 'when the\n' jpayne@69: ' addition works?), but this behavior is in fact part of ' jpayne@69: 'the data\n' jpayne@69: ' model.\n' jpayne@69: '\n' jpayne@69: 'object.__neg__(self)\n' jpayne@69: 'object.__pos__(self)\n' jpayne@69: 'object.__abs__(self)\n' jpayne@69: 'object.__invert__(self)\n' jpayne@69: '\n' jpayne@69: ' Called to implement the unary arithmetic operations ("-", ' jpayne@69: '"+",\n' jpayne@69: ' "abs()" and "~").\n' jpayne@69: '\n' jpayne@69: 'object.__complex__(self)\n' jpayne@69: 'object.__int__(self)\n' jpayne@69: 'object.__float__(self)\n' jpayne@69: '\n' jpayne@69: ' Called to implement the built-in functions "complex()", ' jpayne@69: '"int()" and\n' jpayne@69: ' "float()". Should return a value of the appropriate ' jpayne@69: 'type.\n' jpayne@69: '\n' jpayne@69: 'object.__index__(self)\n' jpayne@69: '\n' jpayne@69: ' Called to implement "operator.index()", and whenever ' jpayne@69: 'Python needs\n' jpayne@69: ' to losslessly convert the numeric object to an integer ' jpayne@69: 'object (such\n' jpayne@69: ' as in slicing, or in the built-in "bin()", "hex()" and ' jpayne@69: '"oct()"\n' jpayne@69: ' functions). Presence of this method indicates that the ' jpayne@69: 'numeric\n' jpayne@69: ' object is an integer type. Must return an integer.\n' jpayne@69: '\n' jpayne@69: ' If "__int__()", "__float__()" and "__complex__()" are not ' jpayne@69: 'defined\n' jpayne@69: ' then corresponding built-in functions "int()", "float()" ' jpayne@69: 'and\n' jpayne@69: ' "complex()" fall back to "__index__()".\n' jpayne@69: '\n' jpayne@69: 'object.__round__(self[, ndigits])\n' jpayne@69: 'object.__trunc__(self)\n' jpayne@69: 'object.__floor__(self)\n' jpayne@69: 'object.__ceil__(self)\n' jpayne@69: '\n' jpayne@69: ' Called to implement the built-in function "round()" and ' jpayne@69: '"math"\n' jpayne@69: ' functions "trunc()", "floor()" and "ceil()". Unless ' jpayne@69: '*ndigits* is\n' jpayne@69: ' passed to "__round__()" all these methods should return ' jpayne@69: 'the value\n' jpayne@69: ' of the object truncated to an "Integral" (typically an ' jpayne@69: '"int").\n' jpayne@69: '\n' jpayne@69: ' If "__int__()" is not defined then the built-in function ' jpayne@69: '"int()"\n' jpayne@69: ' falls back to "__trunc__()".\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'With Statement Context Managers\n' jpayne@69: '===============================\n' jpayne@69: '\n' jpayne@69: 'A *context manager* is an object that defines the runtime ' jpayne@69: 'context to\n' jpayne@69: 'be established when executing a "with" statement. The ' jpayne@69: 'context manager\n' jpayne@69: 'handles the entry into, and the exit from, the desired ' jpayne@69: 'runtime context\n' jpayne@69: 'for the execution of the block of code. Context managers ' jpayne@69: 'are normally\n' jpayne@69: 'invoked using the "with" statement (described in section The ' jpayne@69: 'with\n' jpayne@69: 'statement), but can also be used by directly invoking their ' jpayne@69: 'methods.\n' jpayne@69: '\n' jpayne@69: 'Typical uses of context managers include saving and ' jpayne@69: 'restoring various\n' jpayne@69: 'kinds of global state, locking and unlocking resources, ' jpayne@69: 'closing opened\n' jpayne@69: 'files, etc.\n' jpayne@69: '\n' jpayne@69: 'For more information on context managers, see Context ' jpayne@69: 'Manager Types.\n' jpayne@69: '\n' jpayne@69: 'object.__enter__(self)\n' jpayne@69: '\n' jpayne@69: ' Enter the runtime context related to this object. The ' jpayne@69: '"with"\n' jpayne@69: ' statement will bind this method’s return value to the ' jpayne@69: 'target(s)\n' jpayne@69: ' specified in the "as" clause of the statement, if any.\n' jpayne@69: '\n' jpayne@69: 'object.__exit__(self, exc_type, exc_value, traceback)\n' jpayne@69: '\n' jpayne@69: ' Exit the runtime context related to this object. The ' jpayne@69: 'parameters\n' jpayne@69: ' describe the exception that caused the context to be ' jpayne@69: 'exited. If the\n' jpayne@69: ' context was exited without an exception, all three ' jpayne@69: 'arguments will\n' jpayne@69: ' be "None".\n' jpayne@69: '\n' jpayne@69: ' If an exception is supplied, and the method wishes to ' jpayne@69: 'suppress the\n' jpayne@69: ' exception (i.e., prevent it from being propagated), it ' jpayne@69: 'should\n' jpayne@69: ' return a true value. Otherwise, the exception will be ' jpayne@69: 'processed\n' jpayne@69: ' normally upon exit from this method.\n' jpayne@69: '\n' jpayne@69: ' Note that "__exit__()" methods should not reraise the ' jpayne@69: 'passed-in\n' jpayne@69: ' exception; this is the caller’s responsibility.\n' jpayne@69: '\n' jpayne@69: 'See also:\n' jpayne@69: '\n' jpayne@69: ' **PEP 343** - The “with” statement\n' jpayne@69: ' The specification, background, and examples for the ' jpayne@69: 'Python "with"\n' jpayne@69: ' statement.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Special method lookup\n' jpayne@69: '=====================\n' jpayne@69: '\n' jpayne@69: 'For custom classes, implicit invocations of special methods ' jpayne@69: 'are only\n' jpayne@69: 'guaranteed to work correctly if defined on an object’s type, ' jpayne@69: 'not in\n' jpayne@69: 'the object’s instance dictionary. That behaviour is the ' jpayne@69: 'reason why\n' jpayne@69: 'the following code raises an exception:\n' jpayne@69: '\n' jpayne@69: ' >>> class C:\n' jpayne@69: ' ... pass\n' jpayne@69: ' ...\n' jpayne@69: ' >>> c = C()\n' jpayne@69: ' >>> c.__len__ = lambda: 5\n' jpayne@69: ' >>> len(c)\n' jpayne@69: ' Traceback (most recent call last):\n' jpayne@69: ' File "", line 1, in \n' jpayne@69: " TypeError: object of type 'C' has no len()\n" jpayne@69: '\n' jpayne@69: 'The rationale behind this behaviour lies with a number of ' jpayne@69: 'special\n' jpayne@69: 'methods such as "__hash__()" and "__repr__()" that are ' jpayne@69: 'implemented by\n' jpayne@69: 'all objects, including type objects. If the implicit lookup ' jpayne@69: 'of these\n' jpayne@69: 'methods used the conventional lookup process, they would ' jpayne@69: 'fail when\n' jpayne@69: 'invoked on the type object itself:\n' jpayne@69: '\n' jpayne@69: ' >>> 1 .__hash__() == hash(1)\n' jpayne@69: ' True\n' jpayne@69: ' >>> int.__hash__() == hash(int)\n' jpayne@69: ' Traceback (most recent call last):\n' jpayne@69: ' File "", line 1, in \n' jpayne@69: " TypeError: descriptor '__hash__' of 'int' object needs an " jpayne@69: 'argument\n' jpayne@69: '\n' jpayne@69: 'Incorrectly attempting to invoke an unbound method of a ' jpayne@69: 'class in this\n' jpayne@69: 'way is sometimes referred to as ‘metaclass confusion’, and ' jpayne@69: 'is avoided\n' jpayne@69: 'by bypassing the instance when looking up special methods:\n' jpayne@69: '\n' jpayne@69: ' >>> type(1).__hash__(1) == hash(1)\n' jpayne@69: ' True\n' jpayne@69: ' >>> type(int).__hash__(int) == hash(int)\n' jpayne@69: ' True\n' jpayne@69: '\n' jpayne@69: 'In addition to bypassing any instance attributes in the ' jpayne@69: 'interest of\n' jpayne@69: 'correctness, implicit special method lookup generally also ' jpayne@69: 'bypasses\n' jpayne@69: 'the "__getattribute__()" method even of the object’s ' jpayne@69: 'metaclass:\n' jpayne@69: '\n' jpayne@69: ' >>> class Meta(type):\n' jpayne@69: ' ... def __getattribute__(*args):\n' jpayne@69: ' ... print("Metaclass getattribute invoked")\n' jpayne@69: ' ... return type.__getattribute__(*args)\n' jpayne@69: ' ...\n' jpayne@69: ' >>> class C(object, metaclass=Meta):\n' jpayne@69: ' ... def __len__(self):\n' jpayne@69: ' ... return 10\n' jpayne@69: ' ... def __getattribute__(*args):\n' jpayne@69: ' ... print("Class getattribute invoked")\n' jpayne@69: ' ... return object.__getattribute__(*args)\n' jpayne@69: ' ...\n' jpayne@69: ' >>> c = C()\n' jpayne@69: ' >>> c.__len__() # Explicit lookup via ' jpayne@69: 'instance\n' jpayne@69: ' Class getattribute invoked\n' jpayne@69: ' 10\n' jpayne@69: ' >>> type(c).__len__(c) # Explicit lookup via ' jpayne@69: 'type\n' jpayne@69: ' Metaclass getattribute invoked\n' jpayne@69: ' 10\n' jpayne@69: ' >>> len(c) # Implicit lookup\n' jpayne@69: ' 10\n' jpayne@69: '\n' jpayne@69: 'Bypassing the "__getattribute__()" machinery in this fashion ' jpayne@69: 'provides\n' jpayne@69: 'significant scope for speed optimisations within the ' jpayne@69: 'interpreter, at\n' jpayne@69: 'the cost of some flexibility in the handling of special ' jpayne@69: 'methods (the\n' jpayne@69: 'special method *must* be set on the class object itself in ' jpayne@69: 'order to be\n' jpayne@69: 'consistently invoked by the interpreter).\n', jpayne@69: 'string-methods': 'String Methods\n' jpayne@69: '**************\n' jpayne@69: '\n' jpayne@69: 'Strings implement all of the common sequence operations, ' jpayne@69: 'along with\n' jpayne@69: 'the additional methods described below.\n' jpayne@69: '\n' jpayne@69: 'Strings also support two styles of string formatting, one ' jpayne@69: 'providing a\n' jpayne@69: 'large degree of flexibility and customization (see ' jpayne@69: '"str.format()",\n' jpayne@69: 'Format String Syntax and Custom String Formatting) and the ' jpayne@69: 'other based\n' jpayne@69: 'on C "printf" style formatting that handles a narrower ' jpayne@69: 'range of types\n' jpayne@69: 'and is slightly harder to use correctly, but is often ' jpayne@69: 'faster for the\n' jpayne@69: 'cases it can handle (printf-style String Formatting).\n' jpayne@69: '\n' jpayne@69: 'The Text Processing Services section of the standard ' jpayne@69: 'library covers a\n' jpayne@69: 'number of other modules that provide various text related ' jpayne@69: 'utilities\n' jpayne@69: '(including regular expression support in the "re" ' jpayne@69: 'module).\n' jpayne@69: '\n' jpayne@69: 'str.capitalize()\n' jpayne@69: '\n' jpayne@69: ' Return a copy of the string with its first character ' jpayne@69: 'capitalized\n' jpayne@69: ' and the rest lowercased.\n' jpayne@69: '\n' jpayne@69: ' Changed in version 3.8: The first character is now put ' jpayne@69: 'into\n' jpayne@69: ' titlecase rather than uppercase. This means that ' jpayne@69: 'characters like\n' jpayne@69: ' digraphs will only have their first letter capitalized, ' jpayne@69: 'instead of\n' jpayne@69: ' the full character.\n' jpayne@69: '\n' jpayne@69: 'str.casefold()\n' jpayne@69: '\n' jpayne@69: ' Return a casefolded copy of the string. Casefolded ' jpayne@69: 'strings may be\n' jpayne@69: ' used for caseless matching.\n' jpayne@69: '\n' jpayne@69: ' Casefolding is similar to lowercasing but more ' jpayne@69: 'aggressive because\n' jpayne@69: ' it is intended to remove all case distinctions in a ' jpayne@69: 'string. For\n' jpayne@69: ' example, the German lowercase letter "\'ß\'" is ' jpayne@69: 'equivalent to ""ss"".\n' jpayne@69: ' Since it is already lowercase, "lower()" would do ' jpayne@69: 'nothing to "\'ß\'";\n' jpayne@69: ' "casefold()" converts it to ""ss"".\n' jpayne@69: '\n' jpayne@69: ' The casefolding algorithm is described in section 3.13 ' jpayne@69: 'of the\n' jpayne@69: ' Unicode Standard.\n' jpayne@69: '\n' jpayne@69: ' New in version 3.3.\n' jpayne@69: '\n' jpayne@69: 'str.center(width[, fillchar])\n' jpayne@69: '\n' jpayne@69: ' Return centered in a string of length *width*. Padding ' jpayne@69: 'is done\n' jpayne@69: ' using the specified *fillchar* (default is an ASCII ' jpayne@69: 'space). The\n' jpayne@69: ' original string is returned if *width* is less than or ' jpayne@69: 'equal to\n' jpayne@69: ' "len(s)".\n' jpayne@69: '\n' jpayne@69: 'str.count(sub[, start[, end]])\n' jpayne@69: '\n' jpayne@69: ' Return the number of non-overlapping occurrences of ' jpayne@69: 'substring *sub*\n' jpayne@69: ' in the range [*start*, *end*]. Optional arguments ' jpayne@69: '*start* and\n' jpayne@69: ' *end* are interpreted as in slice notation.\n' jpayne@69: '\n' jpayne@69: 'str.encode(encoding="utf-8", errors="strict")\n' jpayne@69: '\n' jpayne@69: ' Return an encoded version of the string as a bytes ' jpayne@69: 'object. Default\n' jpayne@69: ' encoding is "\'utf-8\'". *errors* may be given to set a ' jpayne@69: 'different\n' jpayne@69: ' error handling scheme. The default for *errors* is ' jpayne@69: '"\'strict\'",\n' jpayne@69: ' meaning that encoding errors raise a "UnicodeError". ' jpayne@69: 'Other possible\n' jpayne@69: ' values are "\'ignore\'", "\'replace\'", ' jpayne@69: '"\'xmlcharrefreplace\'",\n' jpayne@69: ' "\'backslashreplace\'" and any other name registered ' jpayne@69: 'via\n' jpayne@69: ' "codecs.register_error()", see section Error Handlers. ' jpayne@69: 'For a list\n' jpayne@69: ' of possible encodings, see section Standard Encodings.\n' jpayne@69: '\n' jpayne@69: ' Changed in version 3.1: Support for keyword arguments ' jpayne@69: 'added.\n' jpayne@69: '\n' jpayne@69: 'str.endswith(suffix[, start[, end]])\n' jpayne@69: '\n' jpayne@69: ' Return "True" if the string ends with the specified ' jpayne@69: '*suffix*,\n' jpayne@69: ' otherwise return "False". *suffix* can also be a tuple ' jpayne@69: 'of suffixes\n' jpayne@69: ' to look for. With optional *start*, test beginning at ' jpayne@69: 'that\n' jpayne@69: ' position. With optional *end*, stop comparing at that ' jpayne@69: 'position.\n' jpayne@69: '\n' jpayne@69: 'str.expandtabs(tabsize=8)\n' jpayne@69: '\n' jpayne@69: ' Return a copy of the string where all tab characters ' jpayne@69: 'are replaced\n' jpayne@69: ' by one or more spaces, depending on the current column ' jpayne@69: 'and the\n' jpayne@69: ' given tab size. Tab positions occur every *tabsize* ' jpayne@69: 'characters\n' jpayne@69: ' (default is 8, giving tab positions at columns 0, 8, 16 ' jpayne@69: 'and so on).\n' jpayne@69: ' To expand the string, the current column is set to zero ' jpayne@69: 'and the\n' jpayne@69: ' string is examined character by character. If the ' jpayne@69: 'character is a\n' jpayne@69: ' tab ("\\t"), one or more space characters are inserted ' jpayne@69: 'in the result\n' jpayne@69: ' until the current column is equal to the next tab ' jpayne@69: 'position. (The\n' jpayne@69: ' tab character itself is not copied.) If the character ' jpayne@69: 'is a newline\n' jpayne@69: ' ("\\n") or return ("\\r"), it is copied and the current ' jpayne@69: 'column is\n' jpayne@69: ' reset to zero. Any other character is copied unchanged ' jpayne@69: 'and the\n' jpayne@69: ' current column is incremented by one regardless of how ' jpayne@69: 'the\n' jpayne@69: ' character is represented when printed.\n' jpayne@69: '\n' jpayne@69: " >>> '01\\t012\\t0123\\t01234'.expandtabs()\n" jpayne@69: " '01 012 0123 01234'\n" jpayne@69: " >>> '01\\t012\\t0123\\t01234'.expandtabs(4)\n" jpayne@69: " '01 012 0123 01234'\n" jpayne@69: '\n' jpayne@69: 'str.find(sub[, start[, end]])\n' jpayne@69: '\n' jpayne@69: ' Return the lowest index in the string where substring ' jpayne@69: '*sub* is\n' jpayne@69: ' found within the slice "s[start:end]". Optional ' jpayne@69: 'arguments *start*\n' jpayne@69: ' and *end* are interpreted as in slice notation. Return ' jpayne@69: '"-1" if\n' jpayne@69: ' *sub* is not found.\n' jpayne@69: '\n' jpayne@69: ' Note: The "find()" method should be used only if you ' jpayne@69: 'need to know\n' jpayne@69: ' the position of *sub*. To check if *sub* is a ' jpayne@69: 'substring or not,\n' jpayne@69: ' use the "in" operator:\n' jpayne@69: '\n' jpayne@69: " >>> 'Py' in 'Python'\n" jpayne@69: ' True\n' jpayne@69: '\n' jpayne@69: 'str.format(*args, **kwargs)\n' jpayne@69: '\n' jpayne@69: ' Perform a string formatting operation. The string on ' jpayne@69: 'which this\n' jpayne@69: ' method is called can contain literal text or ' jpayne@69: 'replacement fields\n' jpayne@69: ' delimited by braces "{}". Each replacement field ' jpayne@69: 'contains either\n' jpayne@69: ' the numeric index of a positional argument, or the name ' jpayne@69: 'of a\n' jpayne@69: ' keyword argument. Returns a copy of the string where ' jpayne@69: 'each\n' jpayne@69: ' replacement field is replaced with the string value of ' jpayne@69: 'the\n' jpayne@69: ' corresponding argument.\n' jpayne@69: '\n' jpayne@69: ' >>> "The sum of 1 + 2 is {0}".format(1+2)\n' jpayne@69: " 'The sum of 1 + 2 is 3'\n" jpayne@69: '\n' jpayne@69: ' See Format String Syntax for a description of the ' jpayne@69: 'various\n' jpayne@69: ' formatting options that can be specified in format ' jpayne@69: 'strings.\n' jpayne@69: '\n' jpayne@69: ' Note: When formatting a number ("int", "float", ' jpayne@69: '"complex",\n' jpayne@69: ' "decimal.Decimal" and subclasses) with the "n" type ' jpayne@69: '(ex:\n' jpayne@69: ' "\'{:n}\'.format(1234)"), the function temporarily ' jpayne@69: 'sets the\n' jpayne@69: ' "LC_CTYPE" locale to the "LC_NUMERIC" locale to ' jpayne@69: 'decode\n' jpayne@69: ' "decimal_point" and "thousands_sep" fields of ' jpayne@69: '"localeconv()" if\n' jpayne@69: ' they are non-ASCII or longer than 1 byte, and the ' jpayne@69: '"LC_NUMERIC"\n' jpayne@69: ' locale is different than the "LC_CTYPE" locale. This ' jpayne@69: 'temporary\n' jpayne@69: ' change affects other threads.\n' jpayne@69: '\n' jpayne@69: ' Changed in version 3.7: When formatting a number with ' jpayne@69: 'the "n" type,\n' jpayne@69: ' the function sets temporarily the "LC_CTYPE" locale to ' jpayne@69: 'the\n' jpayne@69: ' "LC_NUMERIC" locale in some cases.\n' jpayne@69: '\n' jpayne@69: 'str.format_map(mapping)\n' jpayne@69: '\n' jpayne@69: ' Similar to "str.format(**mapping)", except that ' jpayne@69: '"mapping" is used\n' jpayne@69: ' directly and not copied to a "dict". This is useful if ' jpayne@69: 'for example\n' jpayne@69: ' "mapping" is a dict subclass:\n' jpayne@69: '\n' jpayne@69: ' >>> class Default(dict):\n' jpayne@69: ' ... def __missing__(self, key):\n' jpayne@69: ' ... return key\n' jpayne@69: ' ...\n' jpayne@69: " >>> '{name} was born in " jpayne@69: "{country}'.format_map(Default(name='Guido'))\n" jpayne@69: " 'Guido was born in country'\n" jpayne@69: '\n' jpayne@69: ' New in version 3.2.\n' jpayne@69: '\n' jpayne@69: 'str.index(sub[, start[, end]])\n' jpayne@69: '\n' jpayne@69: ' Like "find()", but raise "ValueError" when the ' jpayne@69: 'substring is not\n' jpayne@69: ' found.\n' jpayne@69: '\n' jpayne@69: 'str.isalnum()\n' jpayne@69: '\n' jpayne@69: ' Return "True" if all characters in the string are ' jpayne@69: 'alphanumeric and\n' jpayne@69: ' there is at least one character, "False" otherwise. A ' jpayne@69: 'character\n' jpayne@69: ' "c" is alphanumeric if one of the following returns ' jpayne@69: '"True":\n' jpayne@69: ' "c.isalpha()", "c.isdecimal()", "c.isdigit()", or ' jpayne@69: '"c.isnumeric()".\n' jpayne@69: '\n' jpayne@69: 'str.isalpha()\n' jpayne@69: '\n' jpayne@69: ' Return "True" if all characters in the string are ' jpayne@69: 'alphabetic and\n' jpayne@69: ' there is at least one character, "False" otherwise. ' jpayne@69: 'Alphabetic\n' jpayne@69: ' characters are those characters defined in the Unicode ' jpayne@69: 'character\n' jpayne@69: ' database as “Letter”, i.e., those with general category ' jpayne@69: 'property\n' jpayne@69: ' being one of “Lm”, “Lt”, “Lu”, “Ll”, or “Lo”. Note ' jpayne@69: 'that this is\n' jpayne@69: ' different from the “Alphabetic” property defined in the ' jpayne@69: 'Unicode\n' jpayne@69: ' Standard.\n' jpayne@69: '\n' jpayne@69: 'str.isascii()\n' jpayne@69: '\n' jpayne@69: ' Return "True" if the string is empty or all characters ' jpayne@69: 'in the\n' jpayne@69: ' string are ASCII, "False" otherwise. ASCII characters ' jpayne@69: 'have code\n' jpayne@69: ' points in the range U+0000-U+007F.\n' jpayne@69: '\n' jpayne@69: ' New in version 3.7.\n' jpayne@69: '\n' jpayne@69: 'str.isdecimal()\n' jpayne@69: '\n' jpayne@69: ' Return "True" if all characters in the string are ' jpayne@69: 'decimal\n' jpayne@69: ' characters and there is at least one character, "False" ' jpayne@69: 'otherwise.\n' jpayne@69: ' Decimal characters are those that can be used to form ' jpayne@69: 'numbers in\n' jpayne@69: ' base 10, e.g. U+0660, ARABIC-INDIC DIGIT ZERO. ' jpayne@69: 'Formally a decimal\n' jpayne@69: ' character is a character in the Unicode General ' jpayne@69: 'Category “Nd”.\n' jpayne@69: '\n' jpayne@69: 'str.isdigit()\n' jpayne@69: '\n' jpayne@69: ' Return "True" if all characters in the string are ' jpayne@69: 'digits and there\n' jpayne@69: ' is at least one character, "False" otherwise. Digits ' jpayne@69: 'include\n' jpayne@69: ' decimal characters and digits that need special ' jpayne@69: 'handling, such as\n' jpayne@69: ' the compatibility superscript digits. This covers ' jpayne@69: 'digits which\n' jpayne@69: ' cannot be used to form numbers in base 10, like the ' jpayne@69: 'Kharosthi\n' jpayne@69: ' numbers. Formally, a digit is a character that has the ' jpayne@69: 'property\n' jpayne@69: ' value Numeric_Type=Digit or Numeric_Type=Decimal.\n' jpayne@69: '\n' jpayne@69: 'str.isidentifier()\n' jpayne@69: '\n' jpayne@69: ' Return "True" if the string is a valid identifier ' jpayne@69: 'according to the\n' jpayne@69: ' language definition, section Identifiers and keywords.\n' jpayne@69: '\n' jpayne@69: ' Call "keyword.iskeyword()" to test whether string "s" ' jpayne@69: 'is a reserved\n' jpayne@69: ' identifier, such as "def" and "class".\n' jpayne@69: '\n' jpayne@69: ' Example:\n' jpayne@69: '\n' jpayne@69: ' >>> from keyword import iskeyword\n' jpayne@69: '\n' jpayne@69: " >>> 'hello'.isidentifier(), iskeyword('hello')\n" jpayne@69: ' True, False\n' jpayne@69: " >>> 'def'.isidentifier(), iskeyword('def')\n" jpayne@69: ' True, True\n' jpayne@69: '\n' jpayne@69: 'str.islower()\n' jpayne@69: '\n' jpayne@69: ' Return "True" if all cased characters [4] in the string ' jpayne@69: 'are\n' jpayne@69: ' lowercase and there is at least one cased character, ' jpayne@69: '"False"\n' jpayne@69: ' otherwise.\n' jpayne@69: '\n' jpayne@69: 'str.isnumeric()\n' jpayne@69: '\n' jpayne@69: ' Return "True" if all characters in the string are ' jpayne@69: 'numeric\n' jpayne@69: ' characters, and there is at least one character, ' jpayne@69: '"False" otherwise.\n' jpayne@69: ' Numeric characters include digit characters, and all ' jpayne@69: 'characters\n' jpayne@69: ' that have the Unicode numeric value property, e.g. ' jpayne@69: 'U+2155, VULGAR\n' jpayne@69: ' FRACTION ONE FIFTH. Formally, numeric characters are ' jpayne@69: 'those with\n' jpayne@69: ' the property value Numeric_Type=Digit, ' jpayne@69: 'Numeric_Type=Decimal or\n' jpayne@69: ' Numeric_Type=Numeric.\n' jpayne@69: '\n' jpayne@69: 'str.isprintable()\n' jpayne@69: '\n' jpayne@69: ' Return "True" if all characters in the string are ' jpayne@69: 'printable or the\n' jpayne@69: ' string is empty, "False" otherwise. Nonprintable ' jpayne@69: 'characters are\n' jpayne@69: ' those characters defined in the Unicode character ' jpayne@69: 'database as\n' jpayne@69: ' “Other” or “Separator”, excepting the ASCII space ' jpayne@69: '(0x20) which is\n' jpayne@69: ' considered printable. (Note that printable characters ' jpayne@69: 'in this\n' jpayne@69: ' context are those which should not be escaped when ' jpayne@69: '"repr()" is\n' jpayne@69: ' invoked on a string. It has no bearing on the handling ' jpayne@69: 'of strings\n' jpayne@69: ' written to "sys.stdout" or "sys.stderr".)\n' jpayne@69: '\n' jpayne@69: 'str.isspace()\n' jpayne@69: '\n' jpayne@69: ' Return "True" if there are only whitespace characters ' jpayne@69: 'in the string\n' jpayne@69: ' and there is at least one character, "False" ' jpayne@69: 'otherwise.\n' jpayne@69: '\n' jpayne@69: ' A character is *whitespace* if in the Unicode character ' jpayne@69: 'database\n' jpayne@69: ' (see "unicodedata"), either its general category is ' jpayne@69: '"Zs"\n' jpayne@69: ' (“Separator, space”), or its bidirectional class is one ' jpayne@69: 'of "WS",\n' jpayne@69: ' "B", or "S".\n' jpayne@69: '\n' jpayne@69: 'str.istitle()\n' jpayne@69: '\n' jpayne@69: ' Return "True" if the string is a titlecased string and ' jpayne@69: 'there is at\n' jpayne@69: ' least one character, for example uppercase characters ' jpayne@69: 'may only\n' jpayne@69: ' follow uncased characters and lowercase characters only ' jpayne@69: 'cased ones.\n' jpayne@69: ' Return "False" otherwise.\n' jpayne@69: '\n' jpayne@69: 'str.isupper()\n' jpayne@69: '\n' jpayne@69: ' Return "True" if all cased characters [4] in the string ' jpayne@69: 'are\n' jpayne@69: ' uppercase and there is at least one cased character, ' jpayne@69: '"False"\n' jpayne@69: ' otherwise.\n' jpayne@69: '\n' jpayne@69: 'str.join(iterable)\n' jpayne@69: '\n' jpayne@69: ' Return a string which is the concatenation of the ' jpayne@69: 'strings in\n' jpayne@69: ' *iterable*. A "TypeError" will be raised if there are ' jpayne@69: 'any non-\n' jpayne@69: ' string values in *iterable*, including "bytes" ' jpayne@69: 'objects. The\n' jpayne@69: ' separator between elements is the string providing this ' jpayne@69: 'method.\n' jpayne@69: '\n' jpayne@69: 'str.ljust(width[, fillchar])\n' jpayne@69: '\n' jpayne@69: ' Return the string left justified in a string of length ' jpayne@69: '*width*.\n' jpayne@69: ' Padding is done using the specified *fillchar* (default ' jpayne@69: 'is an ASCII\n' jpayne@69: ' space). The original string is returned if *width* is ' jpayne@69: 'less than or\n' jpayne@69: ' equal to "len(s)".\n' jpayne@69: '\n' jpayne@69: 'str.lower()\n' jpayne@69: '\n' jpayne@69: ' Return a copy of the string with all the cased ' jpayne@69: 'characters [4]\n' jpayne@69: ' converted to lowercase.\n' jpayne@69: '\n' jpayne@69: ' The lowercasing algorithm used is described in section ' jpayne@69: '3.13 of the\n' jpayne@69: ' Unicode Standard.\n' jpayne@69: '\n' jpayne@69: 'str.lstrip([chars])\n' jpayne@69: '\n' jpayne@69: ' Return a copy of the string with leading characters ' jpayne@69: 'removed. The\n' jpayne@69: ' *chars* argument is a string specifying the set of ' jpayne@69: 'characters to be\n' jpayne@69: ' removed. If omitted or "None", the *chars* argument ' jpayne@69: 'defaults to\n' jpayne@69: ' removing whitespace. The *chars* argument is not a ' jpayne@69: 'prefix; rather,\n' jpayne@69: ' all combinations of its values are stripped:\n' jpayne@69: '\n' jpayne@69: " >>> ' spacious '.lstrip()\n" jpayne@69: " 'spacious '\n" jpayne@69: " >>> 'www.example.com'.lstrip('cmowz.')\n" jpayne@69: " 'example.com'\n" jpayne@69: '\n' jpayne@69: 'static str.maketrans(x[, y[, z]])\n' jpayne@69: '\n' jpayne@69: ' This static method returns a translation table usable ' jpayne@69: 'for\n' jpayne@69: ' "str.translate()".\n' jpayne@69: '\n' jpayne@69: ' If there is only one argument, it must be a dictionary ' jpayne@69: 'mapping\n' jpayne@69: ' Unicode ordinals (integers) or characters (strings of ' jpayne@69: 'length 1) to\n' jpayne@69: ' Unicode ordinals, strings (of arbitrary lengths) or ' jpayne@69: '"None".\n' jpayne@69: ' Character keys will then be converted to ordinals.\n' jpayne@69: '\n' jpayne@69: ' If there are two arguments, they must be strings of ' jpayne@69: 'equal length,\n' jpayne@69: ' and in the resulting dictionary, each character in x ' jpayne@69: 'will be mapped\n' jpayne@69: ' to the character at the same position in y. If there ' jpayne@69: 'is a third\n' jpayne@69: ' argument, it must be a string, whose characters will be ' jpayne@69: 'mapped to\n' jpayne@69: ' "None" in the result.\n' jpayne@69: '\n' jpayne@69: 'str.partition(sep)\n' jpayne@69: '\n' jpayne@69: ' Split the string at the first occurrence of *sep*, and ' jpayne@69: 'return a\n' jpayne@69: ' 3-tuple containing the part before the separator, the ' jpayne@69: 'separator\n' jpayne@69: ' itself, and the part after the separator. If the ' jpayne@69: 'separator is not\n' jpayne@69: ' found, return a 3-tuple containing the string itself, ' jpayne@69: 'followed by\n' jpayne@69: ' two empty strings.\n' jpayne@69: '\n' jpayne@69: 'str.replace(old, new[, count])\n' jpayne@69: '\n' jpayne@69: ' Return a copy of the string with all occurrences of ' jpayne@69: 'substring *old*\n' jpayne@69: ' replaced by *new*. If the optional argument *count* is ' jpayne@69: 'given, only\n' jpayne@69: ' the first *count* occurrences are replaced.\n' jpayne@69: '\n' jpayne@69: 'str.rfind(sub[, start[, end]])\n' jpayne@69: '\n' jpayne@69: ' Return the highest index in the string where substring ' jpayne@69: '*sub* is\n' jpayne@69: ' found, such that *sub* is contained within ' jpayne@69: '"s[start:end]".\n' jpayne@69: ' Optional arguments *start* and *end* are interpreted as ' jpayne@69: 'in slice\n' jpayne@69: ' notation. Return "-1" on failure.\n' jpayne@69: '\n' jpayne@69: 'str.rindex(sub[, start[, end]])\n' jpayne@69: '\n' jpayne@69: ' Like "rfind()" but raises "ValueError" when the ' jpayne@69: 'substring *sub* is\n' jpayne@69: ' not found.\n' jpayne@69: '\n' jpayne@69: 'str.rjust(width[, fillchar])\n' jpayne@69: '\n' jpayne@69: ' Return the string right justified in a string of length ' jpayne@69: '*width*.\n' jpayne@69: ' Padding is done using the specified *fillchar* (default ' jpayne@69: 'is an ASCII\n' jpayne@69: ' space). The original string is returned if *width* is ' jpayne@69: 'less than or\n' jpayne@69: ' equal to "len(s)".\n' jpayne@69: '\n' jpayne@69: 'str.rpartition(sep)\n' jpayne@69: '\n' jpayne@69: ' Split the string at the last occurrence of *sep*, and ' jpayne@69: 'return a\n' jpayne@69: ' 3-tuple containing the part before the separator, the ' jpayne@69: 'separator\n' jpayne@69: ' itself, and the part after the separator. If the ' jpayne@69: 'separator is not\n' jpayne@69: ' found, return a 3-tuple containing two empty strings, ' jpayne@69: 'followed by\n' jpayne@69: ' the string itself.\n' jpayne@69: '\n' jpayne@69: 'str.rsplit(sep=None, maxsplit=-1)\n' jpayne@69: '\n' jpayne@69: ' Return a list of the words in the string, using *sep* ' jpayne@69: 'as the\n' jpayne@69: ' delimiter string. If *maxsplit* is given, at most ' jpayne@69: '*maxsplit* splits\n' jpayne@69: ' are done, the *rightmost* ones. If *sep* is not ' jpayne@69: 'specified or\n' jpayne@69: ' "None", any whitespace string is a separator. Except ' jpayne@69: 'for splitting\n' jpayne@69: ' from the right, "rsplit()" behaves like "split()" which ' jpayne@69: 'is\n' jpayne@69: ' described in detail below.\n' jpayne@69: '\n' jpayne@69: 'str.rstrip([chars])\n' jpayne@69: '\n' jpayne@69: ' Return a copy of the string with trailing characters ' jpayne@69: 'removed. The\n' jpayne@69: ' *chars* argument is a string specifying the set of ' jpayne@69: 'characters to be\n' jpayne@69: ' removed. If omitted or "None", the *chars* argument ' jpayne@69: 'defaults to\n' jpayne@69: ' removing whitespace. The *chars* argument is not a ' jpayne@69: 'suffix; rather,\n' jpayne@69: ' all combinations of its values are stripped:\n' jpayne@69: '\n' jpayne@69: " >>> ' spacious '.rstrip()\n" jpayne@69: " ' spacious'\n" jpayne@69: " >>> 'mississippi'.rstrip('ipz')\n" jpayne@69: " 'mississ'\n" jpayne@69: '\n' jpayne@69: 'str.split(sep=None, maxsplit=-1)\n' jpayne@69: '\n' jpayne@69: ' Return a list of the words in the string, using *sep* ' jpayne@69: 'as the\n' jpayne@69: ' delimiter string. If *maxsplit* is given, at most ' jpayne@69: '*maxsplit*\n' jpayne@69: ' splits are done (thus, the list will have at most ' jpayne@69: '"maxsplit+1"\n' jpayne@69: ' elements). If *maxsplit* is not specified or "-1", ' jpayne@69: 'then there is\n' jpayne@69: ' no limit on the number of splits (all possible splits ' jpayne@69: 'are made).\n' jpayne@69: '\n' jpayne@69: ' If *sep* is given, consecutive delimiters are not ' jpayne@69: 'grouped together\n' jpayne@69: ' and are deemed to delimit empty strings (for example,\n' jpayne@69: ' "\'1,,2\'.split(\',\')" returns "[\'1\', \'\', ' jpayne@69: '\'2\']"). The *sep* argument\n' jpayne@69: ' may consist of multiple characters (for example,\n' jpayne@69: ' "\'1<>2<>3\'.split(\'<>\')" returns "[\'1\', \'2\', ' jpayne@69: '\'3\']"). Splitting an\n' jpayne@69: ' empty string with a specified separator returns ' jpayne@69: '"[\'\']".\n' jpayne@69: '\n' jpayne@69: ' For example:\n' jpayne@69: '\n' jpayne@69: " >>> '1,2,3'.split(',')\n" jpayne@69: " ['1', '2', '3']\n" jpayne@69: " >>> '1,2,3'.split(',', maxsplit=1)\n" jpayne@69: " ['1', '2,3']\n" jpayne@69: " >>> '1,2,,3,'.split(',')\n" jpayne@69: " ['1', '2', '', '3', '']\n" jpayne@69: '\n' jpayne@69: ' If *sep* is not specified or is "None", a different ' jpayne@69: 'splitting\n' jpayne@69: ' algorithm is applied: runs of consecutive whitespace ' jpayne@69: 'are regarded\n' jpayne@69: ' as a single separator, and the result will contain no ' jpayne@69: 'empty strings\n' jpayne@69: ' at the start or end if the string has leading or ' jpayne@69: 'trailing\n' jpayne@69: ' whitespace. Consequently, splitting an empty string or ' jpayne@69: 'a string\n' jpayne@69: ' consisting of just whitespace with a "None" separator ' jpayne@69: 'returns "[]".\n' jpayne@69: '\n' jpayne@69: ' For example:\n' jpayne@69: '\n' jpayne@69: " >>> '1 2 3'.split()\n" jpayne@69: " ['1', '2', '3']\n" jpayne@69: " >>> '1 2 3'.split(maxsplit=1)\n" jpayne@69: " ['1', '2 3']\n" jpayne@69: " >>> ' 1 2 3 '.split()\n" jpayne@69: " ['1', '2', '3']\n" jpayne@69: '\n' jpayne@69: 'str.splitlines([keepends])\n' jpayne@69: '\n' jpayne@69: ' Return a list of the lines in the string, breaking at ' jpayne@69: 'line\n' jpayne@69: ' boundaries. Line breaks are not included in the ' jpayne@69: 'resulting list\n' jpayne@69: ' unless *keepends* is given and true.\n' jpayne@69: '\n' jpayne@69: ' This method splits on the following line boundaries. ' jpayne@69: 'In\n' jpayne@69: ' particular, the boundaries are a superset of *universal ' jpayne@69: 'newlines*.\n' jpayne@69: '\n' jpayne@69: ' ' jpayne@69: '+-------------------------+-------------------------------+\n' jpayne@69: ' | Representation | ' jpayne@69: 'Description |\n' jpayne@69: ' ' jpayne@69: '|=========================|===============================|\n' jpayne@69: ' | "\\n" | Line ' jpayne@69: 'Feed |\n' jpayne@69: ' ' jpayne@69: '+-------------------------+-------------------------------+\n' jpayne@69: ' | "\\r" | Carriage ' jpayne@69: 'Return |\n' jpayne@69: ' ' jpayne@69: '+-------------------------+-------------------------------+\n' jpayne@69: ' | "\\r\\n" | Carriage Return + Line ' jpayne@69: 'Feed |\n' jpayne@69: ' ' jpayne@69: '+-------------------------+-------------------------------+\n' jpayne@69: ' | "\\v" or "\\x0b" | Line ' jpayne@69: 'Tabulation |\n' jpayne@69: ' ' jpayne@69: '+-------------------------+-------------------------------+\n' jpayne@69: ' | "\\f" or "\\x0c" | Form ' jpayne@69: 'Feed |\n' jpayne@69: ' ' jpayne@69: '+-------------------------+-------------------------------+\n' jpayne@69: ' | "\\x1c" | File ' jpayne@69: 'Separator |\n' jpayne@69: ' ' jpayne@69: '+-------------------------+-------------------------------+\n' jpayne@69: ' | "\\x1d" | Group ' jpayne@69: 'Separator |\n' jpayne@69: ' ' jpayne@69: '+-------------------------+-------------------------------+\n' jpayne@69: ' | "\\x1e" | Record ' jpayne@69: 'Separator |\n' jpayne@69: ' ' jpayne@69: '+-------------------------+-------------------------------+\n' jpayne@69: ' | "\\x85" | Next Line (C1 Control ' jpayne@69: 'Code) |\n' jpayne@69: ' ' jpayne@69: '+-------------------------+-------------------------------+\n' jpayne@69: ' | "\\u2028" | Line ' jpayne@69: 'Separator |\n' jpayne@69: ' ' jpayne@69: '+-------------------------+-------------------------------+\n' jpayne@69: ' | "\\u2029" | Paragraph ' jpayne@69: 'Separator |\n' jpayne@69: ' ' jpayne@69: '+-------------------------+-------------------------------+\n' jpayne@69: '\n' jpayne@69: ' Changed in version 3.2: "\\v" and "\\f" added to list ' jpayne@69: 'of line\n' jpayne@69: ' boundaries.\n' jpayne@69: '\n' jpayne@69: ' For example:\n' jpayne@69: '\n' jpayne@69: " >>> 'ab c\\n\\nde fg\\rkl\\r\\n'.splitlines()\n" jpayne@69: " ['ab c', '', 'de fg', 'kl']\n" jpayne@69: " >>> 'ab c\\n\\nde " jpayne@69: "fg\\rkl\\r\\n'.splitlines(keepends=True)\n" jpayne@69: " ['ab c\\n', '\\n', 'de fg\\r', 'kl\\r\\n']\n" jpayne@69: '\n' jpayne@69: ' Unlike "split()" when a delimiter string *sep* is ' jpayne@69: 'given, this\n' jpayne@69: ' method returns an empty list for the empty string, and ' jpayne@69: 'a terminal\n' jpayne@69: ' line break does not result in an extra line:\n' jpayne@69: '\n' jpayne@69: ' >>> "".splitlines()\n' jpayne@69: ' []\n' jpayne@69: ' >>> "One line\\n".splitlines()\n' jpayne@69: " ['One line']\n" jpayne@69: '\n' jpayne@69: ' For comparison, "split(\'\\n\')" gives:\n' jpayne@69: '\n' jpayne@69: " >>> ''.split('\\n')\n" jpayne@69: " ['']\n" jpayne@69: " >>> 'Two lines\\n'.split('\\n')\n" jpayne@69: " ['Two lines', '']\n" jpayne@69: '\n' jpayne@69: 'str.startswith(prefix[, start[, end]])\n' jpayne@69: '\n' jpayne@69: ' Return "True" if string starts with the *prefix*, ' jpayne@69: 'otherwise return\n' jpayne@69: ' "False". *prefix* can also be a tuple of prefixes to ' jpayne@69: 'look for.\n' jpayne@69: ' With optional *start*, test string beginning at that ' jpayne@69: 'position.\n' jpayne@69: ' With optional *end*, stop comparing string at that ' jpayne@69: 'position.\n' jpayne@69: '\n' jpayne@69: 'str.strip([chars])\n' jpayne@69: '\n' jpayne@69: ' Return a copy of the string with the leading and ' jpayne@69: 'trailing\n' jpayne@69: ' characters removed. The *chars* argument is a string ' jpayne@69: 'specifying the\n' jpayne@69: ' set of characters to be removed. If omitted or "None", ' jpayne@69: 'the *chars*\n' jpayne@69: ' argument defaults to removing whitespace. The *chars* ' jpayne@69: 'argument is\n' jpayne@69: ' not a prefix or suffix; rather, all combinations of its ' jpayne@69: 'values are\n' jpayne@69: ' stripped:\n' jpayne@69: '\n' jpayne@69: " >>> ' spacious '.strip()\n" jpayne@69: " 'spacious'\n" jpayne@69: " >>> 'www.example.com'.strip('cmowz.')\n" jpayne@69: " 'example'\n" jpayne@69: '\n' jpayne@69: ' The outermost leading and trailing *chars* argument ' jpayne@69: 'values are\n' jpayne@69: ' stripped from the string. Characters are removed from ' jpayne@69: 'the leading\n' jpayne@69: ' end until reaching a string character that is not ' jpayne@69: 'contained in the\n' jpayne@69: ' set of characters in *chars*. A similar action takes ' jpayne@69: 'place on the\n' jpayne@69: ' trailing end. For example:\n' jpayne@69: '\n' jpayne@69: " >>> comment_string = '#....... Section 3.2.1 Issue " jpayne@69: "#32 .......'\n" jpayne@69: " >>> comment_string.strip('.#! ')\n" jpayne@69: " 'Section 3.2.1 Issue #32'\n" jpayne@69: '\n' jpayne@69: 'str.swapcase()\n' jpayne@69: '\n' jpayne@69: ' Return a copy of the string with uppercase characters ' jpayne@69: 'converted to\n' jpayne@69: ' lowercase and vice versa. Note that it is not ' jpayne@69: 'necessarily true that\n' jpayne@69: ' "s.swapcase().swapcase() == s".\n' jpayne@69: '\n' jpayne@69: 'str.title()\n' jpayne@69: '\n' jpayne@69: ' Return a titlecased version of the string where words ' jpayne@69: 'start with an\n' jpayne@69: ' uppercase character and the remaining characters are ' jpayne@69: 'lowercase.\n' jpayne@69: '\n' jpayne@69: ' For example:\n' jpayne@69: '\n' jpayne@69: " >>> 'Hello world'.title()\n" jpayne@69: " 'Hello World'\n" jpayne@69: '\n' jpayne@69: ' The algorithm uses a simple language-independent ' jpayne@69: 'definition of a\n' jpayne@69: ' word as groups of consecutive letters. The definition ' jpayne@69: 'works in\n' jpayne@69: ' many contexts but it means that apostrophes in ' jpayne@69: 'contractions and\n' jpayne@69: ' possessives form word boundaries, which may not be the ' jpayne@69: 'desired\n' jpayne@69: ' result:\n' jpayne@69: '\n' jpayne@69: ' >>> "they\'re bill\'s friends from the UK".title()\n' jpayne@69: ' "They\'Re Bill\'S Friends From The Uk"\n' jpayne@69: '\n' jpayne@69: ' A workaround for apostrophes can be constructed using ' jpayne@69: 'regular\n' jpayne@69: ' expressions:\n' jpayne@69: '\n' jpayne@69: ' >>> import re\n' jpayne@69: ' >>> def titlecase(s):\n' jpayne@69: ' ... return re.sub(r"[A-Za-z]+(\'[A-Za-z]+)?",\n' jpayne@69: ' ... lambda mo: ' jpayne@69: 'mo.group(0).capitalize(),\n' jpayne@69: ' ... s)\n' jpayne@69: ' ...\n' jpayne@69: ' >>> titlecase("they\'re bill\'s friends.")\n' jpayne@69: ' "They\'re Bill\'s Friends."\n' jpayne@69: '\n' jpayne@69: 'str.translate(table)\n' jpayne@69: '\n' jpayne@69: ' Return a copy of the string in which each character has ' jpayne@69: 'been mapped\n' jpayne@69: ' through the given translation table. The table must be ' jpayne@69: 'an object\n' jpayne@69: ' that implements indexing via "__getitem__()", typically ' jpayne@69: 'a *mapping*\n' jpayne@69: ' or *sequence*. When indexed by a Unicode ordinal (an ' jpayne@69: 'integer), the\n' jpayne@69: ' table object can do any of the following: return a ' jpayne@69: 'Unicode ordinal\n' jpayne@69: ' or a string, to map the character to one or more other ' jpayne@69: 'characters;\n' jpayne@69: ' return "None", to delete the character from the return ' jpayne@69: 'string; or\n' jpayne@69: ' raise a "LookupError" exception, to map the character ' jpayne@69: 'to itself.\n' jpayne@69: '\n' jpayne@69: ' You can use "str.maketrans()" to create a translation ' jpayne@69: 'map from\n' jpayne@69: ' character-to-character mappings in different formats.\n' jpayne@69: '\n' jpayne@69: ' See also the "codecs" module for a more flexible ' jpayne@69: 'approach to custom\n' jpayne@69: ' character mappings.\n' jpayne@69: '\n' jpayne@69: 'str.upper()\n' jpayne@69: '\n' jpayne@69: ' Return a copy of the string with all the cased ' jpayne@69: 'characters [4]\n' jpayne@69: ' converted to uppercase. Note that ' jpayne@69: '"s.upper().isupper()" might be\n' jpayne@69: ' "False" if "s" contains uncased characters or if the ' jpayne@69: 'Unicode\n' jpayne@69: ' category of the resulting character(s) is not “Lu” ' jpayne@69: '(Letter,\n' jpayne@69: ' uppercase), but e.g. “Lt” (Letter, titlecase).\n' jpayne@69: '\n' jpayne@69: ' The uppercasing algorithm used is described in section ' jpayne@69: '3.13 of the\n' jpayne@69: ' Unicode Standard.\n' jpayne@69: '\n' jpayne@69: 'str.zfill(width)\n' jpayne@69: '\n' jpayne@69: ' Return a copy of the string left filled with ASCII ' jpayne@69: '"\'0\'" digits to\n' jpayne@69: ' make a string of length *width*. A leading sign prefix\n' jpayne@69: ' ("\'+\'"/"\'-\'") is handled by inserting the padding ' jpayne@69: '*after* the sign\n' jpayne@69: ' character rather than before. The original string is ' jpayne@69: 'returned if\n' jpayne@69: ' *width* is less than or equal to "len(s)".\n' jpayne@69: '\n' jpayne@69: ' For example:\n' jpayne@69: '\n' jpayne@69: ' >>> "42".zfill(5)\n' jpayne@69: " '00042'\n" jpayne@69: ' >>> "-42".zfill(5)\n' jpayne@69: " '-0042'\n", jpayne@69: 'strings': 'String and Bytes literals\n' jpayne@69: '*************************\n' jpayne@69: '\n' jpayne@69: 'String literals are described by the following lexical ' jpayne@69: 'definitions:\n' jpayne@69: '\n' jpayne@69: ' stringliteral ::= [stringprefix](shortstring | longstring)\n' jpayne@69: ' stringprefix ::= "r" | "u" | "R" | "U" | "f" | "F"\n' jpayne@69: ' | "fr" | "Fr" | "fR" | "FR" | "rf" | "rF" | ' jpayne@69: '"Rf" | "RF"\n' jpayne@69: ' shortstring ::= "\'" shortstringitem* "\'" | \'"\' ' jpayne@69: 'shortstringitem* \'"\'\n' jpayne@69: ' longstring ::= "\'\'\'" longstringitem* "\'\'\'" | ' jpayne@69: '\'"""\' longstringitem* \'"""\'\n' jpayne@69: ' shortstringitem ::= shortstringchar | stringescapeseq\n' jpayne@69: ' longstringitem ::= longstringchar | stringescapeseq\n' jpayne@69: ' shortstringchar ::= \n' jpayne@69: ' longstringchar ::= \n' jpayne@69: ' stringescapeseq ::= "\\" \n' jpayne@69: '\n' jpayne@69: ' bytesliteral ::= bytesprefix(shortbytes | longbytes)\n' jpayne@69: ' bytesprefix ::= "b" | "B" | "br" | "Br" | "bR" | "BR" | ' jpayne@69: '"rb" | "rB" | "Rb" | "RB"\n' jpayne@69: ' shortbytes ::= "\'" shortbytesitem* "\'" | \'"\' ' jpayne@69: 'shortbytesitem* \'"\'\n' jpayne@69: ' longbytes ::= "\'\'\'" longbytesitem* "\'\'\'" | \'"""\' ' jpayne@69: 'longbytesitem* \'"""\'\n' jpayne@69: ' shortbytesitem ::= shortbyteschar | bytesescapeseq\n' jpayne@69: ' longbytesitem ::= longbyteschar | bytesescapeseq\n' jpayne@69: ' shortbyteschar ::= \n' jpayne@69: ' longbyteschar ::= \n' jpayne@69: ' bytesescapeseq ::= "\\" \n' jpayne@69: '\n' jpayne@69: 'One syntactic restriction not indicated by these productions is ' jpayne@69: 'that\n' jpayne@69: 'whitespace is not allowed between the "stringprefix" or ' jpayne@69: '"bytesprefix"\n' jpayne@69: 'and the rest of the literal. The source character set is defined ' jpayne@69: 'by\n' jpayne@69: 'the encoding declaration; it is UTF-8 if no encoding declaration ' jpayne@69: 'is\n' jpayne@69: 'given in the source file; see section Encoding declarations.\n' jpayne@69: '\n' jpayne@69: 'In plain English: Both types of literals can be enclosed in ' jpayne@69: 'matching\n' jpayne@69: 'single quotes ("\'") or double quotes ("""). They can also be ' jpayne@69: 'enclosed\n' jpayne@69: 'in matching groups of three single or double quotes (these are\n' jpayne@69: 'generally referred to as *triple-quoted strings*). The ' jpayne@69: 'backslash\n' jpayne@69: '("\\") character is used to escape characters that otherwise have ' jpayne@69: 'a\n' jpayne@69: 'special meaning, such as newline, backslash itself, or the quote\n' jpayne@69: 'character.\n' jpayne@69: '\n' jpayne@69: 'Bytes literals are always prefixed with "\'b\'" or "\'B\'"; they ' jpayne@69: 'produce\n' jpayne@69: 'an instance of the "bytes" type instead of the "str" type. They ' jpayne@69: 'may\n' jpayne@69: 'only contain ASCII characters; bytes with a numeric value of 128 ' jpayne@69: 'or\n' jpayne@69: 'greater must be expressed with escapes.\n' jpayne@69: '\n' jpayne@69: 'Both string and bytes literals may optionally be prefixed with a\n' jpayne@69: 'letter "\'r\'" or "\'R\'"; such strings are called *raw strings* ' jpayne@69: 'and treat\n' jpayne@69: 'backslashes as literal characters. As a result, in string ' jpayne@69: 'literals,\n' jpayne@69: '"\'\\U\'" and "\'\\u\'" escapes in raw strings are not treated ' jpayne@69: 'specially.\n' jpayne@69: 'Given that Python 2.x’s raw unicode literals behave differently ' jpayne@69: 'than\n' jpayne@69: 'Python 3.x’s the "\'ur\'" syntax is not supported.\n' jpayne@69: '\n' jpayne@69: 'New in version 3.3: The "\'rb\'" prefix of raw bytes literals has ' jpayne@69: 'been\n' jpayne@69: 'added as a synonym of "\'br\'".\n' jpayne@69: '\n' jpayne@69: 'New in version 3.3: Support for the unicode legacy literal\n' jpayne@69: '("u\'value\'") was reintroduced to simplify the maintenance of ' jpayne@69: 'dual\n' jpayne@69: 'Python 2.x and 3.x codebases. See **PEP 414** for more ' jpayne@69: 'information.\n' jpayne@69: '\n' jpayne@69: 'A string literal with "\'f\'" or "\'F\'" in its prefix is a ' jpayne@69: '*formatted\n' jpayne@69: 'string literal*; see Formatted string literals. The "\'f\'" may ' jpayne@69: 'be\n' jpayne@69: 'combined with "\'r\'", but not with "\'b\'" or "\'u\'", therefore ' jpayne@69: 'raw\n' jpayne@69: 'formatted strings are possible, but formatted bytes literals are ' jpayne@69: 'not.\n' jpayne@69: '\n' jpayne@69: 'In triple-quoted literals, unescaped newlines and quotes are ' jpayne@69: 'allowed\n' jpayne@69: '(and are retained), except that three unescaped quotes in a row\n' jpayne@69: 'terminate the literal. (A “quote” is the character used to open ' jpayne@69: 'the\n' jpayne@69: 'literal, i.e. either "\'" or """.)\n' jpayne@69: '\n' jpayne@69: 'Unless an "\'r\'" or "\'R\'" prefix is present, escape sequences ' jpayne@69: 'in string\n' jpayne@69: 'and bytes literals are interpreted according to rules similar to ' jpayne@69: 'those\n' jpayne@69: 'used by Standard C. The recognized escape sequences are:\n' jpayne@69: '\n' jpayne@69: '+-------------------+-----------------------------------+---------+\n' jpayne@69: '| Escape Sequence | Meaning | Notes ' jpayne@69: '|\n' jpayne@69: '|===================|===================================|=========|\n' jpayne@69: '| "\\newline" | Backslash and newline ignored ' jpayne@69: '| |\n' jpayne@69: '+-------------------+-----------------------------------+---------+\n' jpayne@69: '| "\\\\" | Backslash ("\\") ' jpayne@69: '| |\n' jpayne@69: '+-------------------+-----------------------------------+---------+\n' jpayne@69: '| "\\\'" | Single quote ("\'") ' jpayne@69: '| |\n' jpayne@69: '+-------------------+-----------------------------------+---------+\n' jpayne@69: '| "\\"" | Double quote (""") ' jpayne@69: '| |\n' jpayne@69: '+-------------------+-----------------------------------+---------+\n' jpayne@69: '| "\\a" | ASCII Bell (BEL) ' jpayne@69: '| |\n' jpayne@69: '+-------------------+-----------------------------------+---------+\n' jpayne@69: '| "\\b" | ASCII Backspace (BS) ' jpayne@69: '| |\n' jpayne@69: '+-------------------+-----------------------------------+---------+\n' jpayne@69: '| "\\f" | ASCII Formfeed (FF) ' jpayne@69: '| |\n' jpayne@69: '+-------------------+-----------------------------------+---------+\n' jpayne@69: '| "\\n" | ASCII Linefeed (LF) ' jpayne@69: '| |\n' jpayne@69: '+-------------------+-----------------------------------+---------+\n' jpayne@69: '| "\\r" | ASCII Carriage Return (CR) ' jpayne@69: '| |\n' jpayne@69: '+-------------------+-----------------------------------+---------+\n' jpayne@69: '| "\\t" | ASCII Horizontal Tab (TAB) ' jpayne@69: '| |\n' jpayne@69: '+-------------------+-----------------------------------+---------+\n' jpayne@69: '| "\\v" | ASCII Vertical Tab (VT) ' jpayne@69: '| |\n' jpayne@69: '+-------------------+-----------------------------------+---------+\n' jpayne@69: '| "\\ooo" | Character with octal value *ooo* | ' jpayne@69: '(1,3) |\n' jpayne@69: '+-------------------+-----------------------------------+---------+\n' jpayne@69: '| "\\xhh" | Character with hex value *hh* | ' jpayne@69: '(2,3) |\n' jpayne@69: '+-------------------+-----------------------------------+---------+\n' jpayne@69: '\n' jpayne@69: 'Escape sequences only recognized in string literals are:\n' jpayne@69: '\n' jpayne@69: '+-------------------+-----------------------------------+---------+\n' jpayne@69: '| Escape Sequence | Meaning | Notes ' jpayne@69: '|\n' jpayne@69: '|===================|===================================|=========|\n' jpayne@69: '| "\\N{name}" | Character named *name* in the | ' jpayne@69: '(4) |\n' jpayne@69: '| | Unicode database | ' jpayne@69: '|\n' jpayne@69: '+-------------------+-----------------------------------+---------+\n' jpayne@69: '| "\\uxxxx" | Character with 16-bit hex value | ' jpayne@69: '(5) |\n' jpayne@69: '| | *xxxx* | ' jpayne@69: '|\n' jpayne@69: '+-------------------+-----------------------------------+---------+\n' jpayne@69: '| "\\Uxxxxxxxx" | Character with 32-bit hex value | ' jpayne@69: '(6) |\n' jpayne@69: '| | *xxxxxxxx* | ' jpayne@69: '|\n' jpayne@69: '+-------------------+-----------------------------------+---------+\n' jpayne@69: '\n' jpayne@69: 'Notes:\n' jpayne@69: '\n' jpayne@69: '1. As in Standard C, up to three octal digits are accepted.\n' jpayne@69: '\n' jpayne@69: '2. Unlike in Standard C, exactly two hex digits are required.\n' jpayne@69: '\n' jpayne@69: '3. In a bytes literal, hexadecimal and octal escapes denote the\n' jpayne@69: ' byte with the given value. In a string literal, these escapes\n' jpayne@69: ' denote a Unicode character with the given value.\n' jpayne@69: '\n' jpayne@69: '4. Changed in version 3.3: Support for name aliases [1] has been\n' jpayne@69: ' added.\n' jpayne@69: '\n' jpayne@69: '5. Exactly four hex digits are required.\n' jpayne@69: '\n' jpayne@69: '6. Any Unicode character can be encoded this way. Exactly eight\n' jpayne@69: ' hex digits are required.\n' jpayne@69: '\n' jpayne@69: 'Unlike Standard C, all unrecognized escape sequences are left in ' jpayne@69: 'the\n' jpayne@69: 'string unchanged, i.e., *the backslash is left in the result*. ' jpayne@69: '(This\n' jpayne@69: 'behavior is useful when debugging: if an escape sequence is ' jpayne@69: 'mistyped,\n' jpayne@69: 'the resulting output is more easily recognized as broken.) It is ' jpayne@69: 'also\n' jpayne@69: 'important to note that the escape sequences only recognized in ' jpayne@69: 'string\n' jpayne@69: 'literals fall into the category of unrecognized escapes for ' jpayne@69: 'bytes\n' jpayne@69: 'literals.\n' jpayne@69: '\n' jpayne@69: ' Changed in version 3.6: Unrecognized escape sequences produce ' jpayne@69: 'a\n' jpayne@69: ' "DeprecationWarning". In a future Python version they will be ' jpayne@69: 'a\n' jpayne@69: ' "SyntaxWarning" and eventually a "SyntaxError".\n' jpayne@69: '\n' jpayne@69: 'Even in a raw literal, quotes can be escaped with a backslash, ' jpayne@69: 'but the\n' jpayne@69: 'backslash remains in the result; for example, "r"\\""" is a ' jpayne@69: 'valid\n' jpayne@69: 'string literal consisting of two characters: a backslash and a ' jpayne@69: 'double\n' jpayne@69: 'quote; "r"\\"" is not a valid string literal (even a raw string ' jpayne@69: 'cannot\n' jpayne@69: 'end in an odd number of backslashes). Specifically, *a raw ' jpayne@69: 'literal\n' jpayne@69: 'cannot end in a single backslash* (since the backslash would ' jpayne@69: 'escape\n' jpayne@69: 'the following quote character). Note also that a single ' jpayne@69: 'backslash\n' jpayne@69: 'followed by a newline is interpreted as those two characters as ' jpayne@69: 'part\n' jpayne@69: 'of the literal, *not* as a line continuation.\n', jpayne@69: 'subscriptions': 'Subscriptions\n' jpayne@69: '*************\n' jpayne@69: '\n' jpayne@69: 'A subscription selects an item of a sequence (string, tuple ' jpayne@69: 'or list)\n' jpayne@69: 'or mapping (dictionary) object:\n' jpayne@69: '\n' jpayne@69: ' subscription ::= primary "[" expression_list "]"\n' jpayne@69: '\n' jpayne@69: 'The primary must evaluate to an object that supports ' jpayne@69: 'subscription\n' jpayne@69: '(lists or dictionaries for example). User-defined objects ' jpayne@69: 'can support\n' jpayne@69: 'subscription by defining a "__getitem__()" method.\n' jpayne@69: '\n' jpayne@69: 'For built-in objects, there are two types of objects that ' jpayne@69: 'support\n' jpayne@69: 'subscription:\n' jpayne@69: '\n' jpayne@69: 'If the primary is a mapping, the expression list must ' jpayne@69: 'evaluate to an\n' jpayne@69: 'object whose value is one of the keys of the mapping, and ' jpayne@69: 'the\n' jpayne@69: 'subscription selects the value in the mapping that ' jpayne@69: 'corresponds to that\n' jpayne@69: 'key. (The expression list is a tuple except if it has ' jpayne@69: 'exactly one\n' jpayne@69: 'item.)\n' jpayne@69: '\n' jpayne@69: 'If the primary is a sequence, the expression list must ' jpayne@69: 'evaluate to an\n' jpayne@69: 'integer or a slice (as discussed in the following ' jpayne@69: 'section).\n' jpayne@69: '\n' jpayne@69: 'The formal syntax makes no special provision for negative ' jpayne@69: 'indices in\n' jpayne@69: 'sequences; however, built-in sequences all provide a ' jpayne@69: '"__getitem__()"\n' jpayne@69: 'method that interprets negative indices by adding the ' jpayne@69: 'length of the\n' jpayne@69: 'sequence to the index (so that "x[-1]" selects the last ' jpayne@69: 'item of "x").\n' jpayne@69: 'The resulting value must be a nonnegative integer less than ' jpayne@69: 'the number\n' jpayne@69: 'of items in the sequence, and the subscription selects the ' jpayne@69: 'item whose\n' jpayne@69: 'index is that value (counting from zero). Since the support ' jpayne@69: 'for\n' jpayne@69: 'negative indices and slicing occurs in the object’s ' jpayne@69: '"__getitem__()"\n' jpayne@69: 'method, subclasses overriding this method will need to ' jpayne@69: 'explicitly add\n' jpayne@69: 'that support.\n' jpayne@69: '\n' jpayne@69: 'A string’s items are characters. A character is not a ' jpayne@69: 'separate data\n' jpayne@69: 'type but a string of exactly one character.\n', jpayne@69: 'truth': 'Truth Value Testing\n' jpayne@69: '*******************\n' jpayne@69: '\n' jpayne@69: 'Any object can be tested for truth value, for use in an "if" or\n' jpayne@69: '"while" condition or as operand of the Boolean operations below.\n' jpayne@69: '\n' jpayne@69: 'By default, an object is considered true unless its class defines\n' jpayne@69: 'either a "__bool__()" method that returns "False" or a "__len__()"\n' jpayne@69: 'method that returns zero, when called with the object. [1] Here ' jpayne@69: 'are\n' jpayne@69: 'most of the built-in objects considered false:\n' jpayne@69: '\n' jpayne@69: '* constants defined to be false: "None" and "False".\n' jpayne@69: '\n' jpayne@69: '* zero of any numeric type: "0", "0.0", "0j", "Decimal(0)",\n' jpayne@69: ' "Fraction(0, 1)"\n' jpayne@69: '\n' jpayne@69: '* empty sequences and collections: "\'\'", "()", "[]", "{}", ' jpayne@69: '"set()",\n' jpayne@69: ' "range(0)"\n' jpayne@69: '\n' jpayne@69: 'Operations and built-in functions that have a Boolean result ' jpayne@69: 'always\n' jpayne@69: 'return "0" or "False" for false and "1" or "True" for true, unless\n' jpayne@69: 'otherwise stated. (Important exception: the Boolean operations ' jpayne@69: '"or"\n' jpayne@69: 'and "and" always return one of their operands.)\n', jpayne@69: 'try': 'The "try" statement\n' jpayne@69: '*******************\n' jpayne@69: '\n' jpayne@69: 'The "try" statement specifies exception handlers and/or cleanup code\n' jpayne@69: 'for a group of statements:\n' jpayne@69: '\n' jpayne@69: ' try_stmt ::= try1_stmt | try2_stmt\n' jpayne@69: ' try1_stmt ::= "try" ":" suite\n' jpayne@69: ' ("except" [expression ["as" identifier]] ":" ' jpayne@69: 'suite)+\n' jpayne@69: ' ["else" ":" suite]\n' jpayne@69: ' ["finally" ":" suite]\n' jpayne@69: ' try2_stmt ::= "try" ":" suite\n' jpayne@69: ' "finally" ":" suite\n' jpayne@69: '\n' jpayne@69: 'The "except" clause(s) specify one or more exception handlers. When ' jpayne@69: 'no\n' jpayne@69: 'exception occurs in the "try" clause, no exception handler is\n' jpayne@69: 'executed. When an exception occurs in the "try" suite, a search for ' jpayne@69: 'an\n' jpayne@69: 'exception handler is started. This search inspects the except ' jpayne@69: 'clauses\n' jpayne@69: 'in turn until one is found that matches the exception. An ' jpayne@69: 'expression-\n' jpayne@69: 'less except clause, if present, must be last; it matches any\n' jpayne@69: 'exception. For an except clause with an expression, that expression\n' jpayne@69: 'is evaluated, and the clause matches the exception if the resulting\n' jpayne@69: 'object is “compatible” with the exception. An object is compatible\n' jpayne@69: 'with an exception if it is the class or a base class of the ' jpayne@69: 'exception\n' jpayne@69: 'object or a tuple containing an item compatible with the exception.\n' jpayne@69: '\n' jpayne@69: 'If no except clause matches the exception, the search for an ' jpayne@69: 'exception\n' jpayne@69: 'handler continues in the surrounding code and on the invocation ' jpayne@69: 'stack.\n' jpayne@69: '[1]\n' jpayne@69: '\n' jpayne@69: 'If the evaluation of an expression in the header of an except clause\n' jpayne@69: 'raises an exception, the original search for a handler is canceled ' jpayne@69: 'and\n' jpayne@69: 'a search starts for the new exception in the surrounding code and on\n' jpayne@69: 'the call stack (it is treated as if the entire "try" statement ' jpayne@69: 'raised\n' jpayne@69: 'the exception).\n' jpayne@69: '\n' jpayne@69: 'When a matching except clause is found, the exception is assigned to\n' jpayne@69: 'the target specified after the "as" keyword in that except clause, ' jpayne@69: 'if\n' jpayne@69: 'present, and the except clause’s suite is executed. All except\n' jpayne@69: 'clauses must have an executable block. When the end of this block ' jpayne@69: 'is\n' jpayne@69: 'reached, execution continues normally after the entire try ' jpayne@69: 'statement.\n' jpayne@69: '(This means that if two nested handlers exist for the same ' jpayne@69: 'exception,\n' jpayne@69: 'and the exception occurs in the try clause of the inner handler, the\n' jpayne@69: 'outer handler will not handle the exception.)\n' jpayne@69: '\n' jpayne@69: 'When an exception has been assigned using "as target", it is cleared\n' jpayne@69: 'at the end of the except clause. This is as if\n' jpayne@69: '\n' jpayne@69: ' except E as N:\n' jpayne@69: ' foo\n' jpayne@69: '\n' jpayne@69: 'was translated to\n' jpayne@69: '\n' jpayne@69: ' except E as N:\n' jpayne@69: ' try:\n' jpayne@69: ' foo\n' jpayne@69: ' finally:\n' jpayne@69: ' del N\n' jpayne@69: '\n' jpayne@69: 'This means the exception must be assigned to a different name to be\n' jpayne@69: 'able to refer to it after the except clause. Exceptions are cleared\n' jpayne@69: 'because with the traceback attached to them, they form a reference\n' jpayne@69: 'cycle with the stack frame, keeping all locals in that frame alive\n' jpayne@69: 'until the next garbage collection occurs.\n' jpayne@69: '\n' jpayne@69: 'Before an except clause’s suite is executed, details about the\n' jpayne@69: 'exception are stored in the "sys" module and can be accessed via\n' jpayne@69: '"sys.exc_info()". "sys.exc_info()" returns a 3-tuple consisting of ' jpayne@69: 'the\n' jpayne@69: 'exception class, the exception instance and a traceback object (see\n' jpayne@69: 'section The standard type hierarchy) identifying the point in the\n' jpayne@69: 'program where the exception occurred. "sys.exc_info()" values are\n' jpayne@69: 'restored to their previous values (before the call) when returning\n' jpayne@69: 'from a function that handled an exception.\n' jpayne@69: '\n' jpayne@69: 'The optional "else" clause is executed if the control flow leaves ' jpayne@69: 'the\n' jpayne@69: '"try" suite, no exception was raised, and no "return", "continue", ' jpayne@69: 'or\n' jpayne@69: '"break" statement was executed. Exceptions in the "else" clause are\n' jpayne@69: 'not handled by the preceding "except" clauses.\n' jpayne@69: '\n' jpayne@69: 'If "finally" is present, it specifies a ‘cleanup’ handler. The ' jpayne@69: '"try"\n' jpayne@69: 'clause is executed, including any "except" and "else" clauses. If ' jpayne@69: 'an\n' jpayne@69: 'exception occurs in any of the clauses and is not handled, the\n' jpayne@69: 'exception is temporarily saved. The "finally" clause is executed. ' jpayne@69: 'If\n' jpayne@69: 'there is a saved exception it is re-raised at the end of the ' jpayne@69: '"finally"\n' jpayne@69: 'clause. If the "finally" clause raises another exception, the saved\n' jpayne@69: 'exception is set as the context of the new exception. If the ' jpayne@69: '"finally"\n' jpayne@69: 'clause executes a "return", "break" or "continue" statement, the ' jpayne@69: 'saved\n' jpayne@69: 'exception is discarded:\n' jpayne@69: '\n' jpayne@69: ' >>> def f():\n' jpayne@69: ' ... try:\n' jpayne@69: ' ... 1/0\n' jpayne@69: ' ... finally:\n' jpayne@69: ' ... return 42\n' jpayne@69: ' ...\n' jpayne@69: ' >>> f()\n' jpayne@69: ' 42\n' jpayne@69: '\n' jpayne@69: 'The exception information is not available to the program during\n' jpayne@69: 'execution of the "finally" clause.\n' jpayne@69: '\n' jpayne@69: 'When a "return", "break" or "continue" statement is executed in the\n' jpayne@69: '"try" suite of a "try"…"finally" statement, the "finally" clause is\n' jpayne@69: 'also executed ‘on the way out.’\n' jpayne@69: '\n' jpayne@69: 'The return value of a function is determined by the last "return"\n' jpayne@69: 'statement executed. Since the "finally" clause always executes, a\n' jpayne@69: '"return" statement executed in the "finally" clause will always be ' jpayne@69: 'the\n' jpayne@69: 'last one executed:\n' jpayne@69: '\n' jpayne@69: ' >>> def foo():\n' jpayne@69: ' ... try:\n' jpayne@69: " ... return 'try'\n" jpayne@69: ' ... finally:\n' jpayne@69: " ... return 'finally'\n" jpayne@69: ' ...\n' jpayne@69: ' >>> foo()\n' jpayne@69: " 'finally'\n" jpayne@69: '\n' jpayne@69: 'Additional information on exceptions can be found in section\n' jpayne@69: 'Exceptions, and information on using the "raise" statement to ' jpayne@69: 'generate\n' jpayne@69: 'exceptions may be found in section The raise statement.\n' jpayne@69: '\n' jpayne@69: 'Changed in version 3.8: Prior to Python 3.8, a "continue" statement\n' jpayne@69: 'was illegal in the "finally" clause due to a problem with the\n' jpayne@69: 'implementation.\n', jpayne@69: 'types': 'The standard type hierarchy\n' jpayne@69: '***************************\n' jpayne@69: '\n' jpayne@69: 'Below is a list of the types that are built into Python. ' jpayne@69: 'Extension\n' jpayne@69: 'modules (written in C, Java, or other languages, depending on the\n' jpayne@69: 'implementation) can define additional types. Future versions of\n' jpayne@69: 'Python may add types to the type hierarchy (e.g., rational ' jpayne@69: 'numbers,\n' jpayne@69: 'efficiently stored arrays of integers, etc.), although such ' jpayne@69: 'additions\n' jpayne@69: 'will often be provided via the standard library instead.\n' jpayne@69: '\n' jpayne@69: 'Some of the type descriptions below contain a paragraph listing\n' jpayne@69: '‘special attributes.’ These are attributes that provide access to ' jpayne@69: 'the\n' jpayne@69: 'implementation and are not intended for general use. Their ' jpayne@69: 'definition\n' jpayne@69: 'may change in the future.\n' jpayne@69: '\n' jpayne@69: 'None\n' jpayne@69: ' This type has a single value. There is a single object with ' jpayne@69: 'this\n' jpayne@69: ' value. This object is accessed through the built-in name "None". ' jpayne@69: 'It\n' jpayne@69: ' is used to signify the absence of a value in many situations, ' jpayne@69: 'e.g.,\n' jpayne@69: ' it is returned from functions that don’t explicitly return\n' jpayne@69: ' anything. Its truth value is false.\n' jpayne@69: '\n' jpayne@69: 'NotImplemented\n' jpayne@69: ' This type has a single value. There is a single object with ' jpayne@69: 'this\n' jpayne@69: ' value. This object is accessed through the built-in name\n' jpayne@69: ' "NotImplemented". Numeric methods and rich comparison methods\n' jpayne@69: ' should return this value if they do not implement the operation ' jpayne@69: 'for\n' jpayne@69: ' the operands provided. (The interpreter will then try the\n' jpayne@69: ' reflected operation, or some other fallback, depending on the\n' jpayne@69: ' operator.) Its truth value is true.\n' jpayne@69: '\n' jpayne@69: ' See Implementing the arithmetic operations for more details.\n' jpayne@69: '\n' jpayne@69: 'Ellipsis\n' jpayne@69: ' This type has a single value. There is a single object with ' jpayne@69: 'this\n' jpayne@69: ' value. This object is accessed through the literal "..." or the\n' jpayne@69: ' built-in name "Ellipsis". Its truth value is true.\n' jpayne@69: '\n' jpayne@69: '"numbers.Number"\n' jpayne@69: ' These are created by numeric literals and returned as results ' jpayne@69: 'by\n' jpayne@69: ' arithmetic operators and arithmetic built-in functions. ' jpayne@69: 'Numeric\n' jpayne@69: ' objects are immutable; once created their value never changes.\n' jpayne@69: ' Python numbers are of course strongly related to mathematical\n' jpayne@69: ' numbers, but subject to the limitations of numerical ' jpayne@69: 'representation\n' jpayne@69: ' in computers.\n' jpayne@69: '\n' jpayne@69: ' Python distinguishes between integers, floating point numbers, ' jpayne@69: 'and\n' jpayne@69: ' complex numbers:\n' jpayne@69: '\n' jpayne@69: ' "numbers.Integral"\n' jpayne@69: ' These represent elements from the mathematical set of ' jpayne@69: 'integers\n' jpayne@69: ' (positive and negative).\n' jpayne@69: '\n' jpayne@69: ' There are two types of integers:\n' jpayne@69: '\n' jpayne@69: ' Integers ("int")\n' jpayne@69: '\n' jpayne@69: ' These represent numbers in an unlimited range, subject to\n' jpayne@69: ' available (virtual) memory only. For the purpose of ' jpayne@69: 'shift\n' jpayne@69: ' and mask operations, a binary representation is assumed, ' jpayne@69: 'and\n' jpayne@69: ' negative numbers are represented in a variant of 2’s\n' jpayne@69: ' complement which gives the illusion of an infinite string ' jpayne@69: 'of\n' jpayne@69: ' sign bits extending to the left.\n' jpayne@69: '\n' jpayne@69: ' Booleans ("bool")\n' jpayne@69: ' These represent the truth values False and True. The two\n' jpayne@69: ' objects representing the values "False" and "True" are ' jpayne@69: 'the\n' jpayne@69: ' only Boolean objects. The Boolean type is a subtype of ' jpayne@69: 'the\n' jpayne@69: ' integer type, and Boolean values behave like the values 0 ' jpayne@69: 'and\n' jpayne@69: ' 1, respectively, in almost all contexts, the exception ' jpayne@69: 'being\n' jpayne@69: ' that when converted to a string, the strings ""False"" or\n' jpayne@69: ' ""True"" are returned, respectively.\n' jpayne@69: '\n' jpayne@69: ' The rules for integer representation are intended to give ' jpayne@69: 'the\n' jpayne@69: ' most meaningful interpretation of shift and mask operations\n' jpayne@69: ' involving negative integers.\n' jpayne@69: '\n' jpayne@69: ' "numbers.Real" ("float")\n' jpayne@69: ' These represent machine-level double precision floating ' jpayne@69: 'point\n' jpayne@69: ' numbers. You are at the mercy of the underlying machine\n' jpayne@69: ' architecture (and C or Java implementation) for the accepted\n' jpayne@69: ' range and handling of overflow. Python does not support ' jpayne@69: 'single-\n' jpayne@69: ' precision floating point numbers; the savings in processor ' jpayne@69: 'and\n' jpayne@69: ' memory usage that are usually the reason for using these are\n' jpayne@69: ' dwarfed by the overhead of using objects in Python, so there ' jpayne@69: 'is\n' jpayne@69: ' no reason to complicate the language with two kinds of ' jpayne@69: 'floating\n' jpayne@69: ' point numbers.\n' jpayne@69: '\n' jpayne@69: ' "numbers.Complex" ("complex")\n' jpayne@69: ' These represent complex numbers as a pair of machine-level\n' jpayne@69: ' double precision floating point numbers. The same caveats ' jpayne@69: 'apply\n' jpayne@69: ' as for floating point numbers. The real and imaginary parts ' jpayne@69: 'of a\n' jpayne@69: ' complex number "z" can be retrieved through the read-only\n' jpayne@69: ' attributes "z.real" and "z.imag".\n' jpayne@69: '\n' jpayne@69: 'Sequences\n' jpayne@69: ' These represent finite ordered sets indexed by non-negative\n' jpayne@69: ' numbers. The built-in function "len()" returns the number of ' jpayne@69: 'items\n' jpayne@69: ' of a sequence. When the length of a sequence is *n*, the index ' jpayne@69: 'set\n' jpayne@69: ' contains the numbers 0, 1, …, *n*-1. Item *i* of sequence *a* ' jpayne@69: 'is\n' jpayne@69: ' selected by "a[i]".\n' jpayne@69: '\n' jpayne@69: ' Sequences also support slicing: "a[i:j]" selects all items with\n' jpayne@69: ' index *k* such that *i* "<=" *k* "<" *j*. When used as an\n' jpayne@69: ' expression, a slice is a sequence of the same type. This ' jpayne@69: 'implies\n' jpayne@69: ' that the index set is renumbered so that it starts at 0.\n' jpayne@69: '\n' jpayne@69: ' Some sequences also support “extended slicing” with a third ' jpayne@69: '“step”\n' jpayne@69: ' parameter: "a[i:j:k]" selects all items of *a* with index *x* ' jpayne@69: 'where\n' jpayne@69: ' "x = i + n*k", *n* ">=" "0" and *i* "<=" *x* "<" *j*.\n' jpayne@69: '\n' jpayne@69: ' Sequences are distinguished according to their mutability:\n' jpayne@69: '\n' jpayne@69: ' Immutable sequences\n' jpayne@69: ' An object of an immutable sequence type cannot change once it ' jpayne@69: 'is\n' jpayne@69: ' created. (If the object contains references to other ' jpayne@69: 'objects,\n' jpayne@69: ' these other objects may be mutable and may be changed; ' jpayne@69: 'however,\n' jpayne@69: ' the collection of objects directly referenced by an ' jpayne@69: 'immutable\n' jpayne@69: ' object cannot change.)\n' jpayne@69: '\n' jpayne@69: ' The following types are immutable sequences:\n' jpayne@69: '\n' jpayne@69: ' Strings\n' jpayne@69: ' A string is a sequence of values that represent Unicode ' jpayne@69: 'code\n' jpayne@69: ' points. All the code points in the range "U+0000 - ' jpayne@69: 'U+10FFFF"\n' jpayne@69: ' can be represented in a string. Python doesn’t have a ' jpayne@69: '"char"\n' jpayne@69: ' type; instead, every code point in the string is ' jpayne@69: 'represented\n' jpayne@69: ' as a string object with length "1". The built-in ' jpayne@69: 'function\n' jpayne@69: ' "ord()" converts a code point from its string form to an\n' jpayne@69: ' integer in the range "0 - 10FFFF"; "chr()" converts an\n' jpayne@69: ' integer in the range "0 - 10FFFF" to the corresponding ' jpayne@69: 'length\n' jpayne@69: ' "1" string object. "str.encode()" can be used to convert ' jpayne@69: 'a\n' jpayne@69: ' "str" to "bytes" using the given text encoding, and\n' jpayne@69: ' "bytes.decode()" can be used to achieve the opposite.\n' jpayne@69: '\n' jpayne@69: ' Tuples\n' jpayne@69: ' The items of a tuple are arbitrary Python objects. Tuples ' jpayne@69: 'of\n' jpayne@69: ' two or more items are formed by comma-separated lists of\n' jpayne@69: ' expressions. A tuple of one item (a ‘singleton’) can be\n' jpayne@69: ' formed by affixing a comma to an expression (an expression ' jpayne@69: 'by\n' jpayne@69: ' itself does not create a tuple, since parentheses must be\n' jpayne@69: ' usable for grouping of expressions). An empty tuple can ' jpayne@69: 'be\n' jpayne@69: ' formed by an empty pair of parentheses.\n' jpayne@69: '\n' jpayne@69: ' Bytes\n' jpayne@69: ' A bytes object is an immutable array. The items are ' jpayne@69: '8-bit\n' jpayne@69: ' bytes, represented by integers in the range 0 <= x < 256.\n' jpayne@69: ' Bytes literals (like "b\'abc\'") and the built-in ' jpayne@69: '"bytes()"\n' jpayne@69: ' constructor can be used to create bytes objects. Also, ' jpayne@69: 'bytes\n' jpayne@69: ' objects can be decoded to strings via the "decode()" ' jpayne@69: 'method.\n' jpayne@69: '\n' jpayne@69: ' Mutable sequences\n' jpayne@69: ' Mutable sequences can be changed after they are created. ' jpayne@69: 'The\n' jpayne@69: ' subscription and slicing notations can be used as the target ' jpayne@69: 'of\n' jpayne@69: ' assignment and "del" (delete) statements.\n' jpayne@69: '\n' jpayne@69: ' There are currently two intrinsic mutable sequence types:\n' jpayne@69: '\n' jpayne@69: ' Lists\n' jpayne@69: ' The items of a list are arbitrary Python objects. Lists ' jpayne@69: 'are\n' jpayne@69: ' formed by placing a comma-separated list of expressions ' jpayne@69: 'in\n' jpayne@69: ' square brackets. (Note that there are no special cases ' jpayne@69: 'needed\n' jpayne@69: ' to form lists of length 0 or 1.)\n' jpayne@69: '\n' jpayne@69: ' Byte Arrays\n' jpayne@69: ' A bytearray object is a mutable array. They are created ' jpayne@69: 'by\n' jpayne@69: ' the built-in "bytearray()" constructor. Aside from being\n' jpayne@69: ' mutable (and hence unhashable), byte arrays otherwise ' jpayne@69: 'provide\n' jpayne@69: ' the same interface and functionality as immutable "bytes"\n' jpayne@69: ' objects.\n' jpayne@69: '\n' jpayne@69: ' The extension module "array" provides an additional example ' jpayne@69: 'of a\n' jpayne@69: ' mutable sequence type, as does the "collections" module.\n' jpayne@69: '\n' jpayne@69: 'Set types\n' jpayne@69: ' These represent unordered, finite sets of unique, immutable\n' jpayne@69: ' objects. As such, they cannot be indexed by any subscript. ' jpayne@69: 'However,\n' jpayne@69: ' they can be iterated over, and the built-in function "len()"\n' jpayne@69: ' returns the number of items in a set. Common uses for sets are ' jpayne@69: 'fast\n' jpayne@69: ' membership testing, removing duplicates from a sequence, and\n' jpayne@69: ' computing mathematical operations such as intersection, union,\n' jpayne@69: ' difference, and symmetric difference.\n' jpayne@69: '\n' jpayne@69: ' For set elements, the same immutability rules apply as for\n' jpayne@69: ' dictionary keys. Note that numeric types obey the normal rules ' jpayne@69: 'for\n' jpayne@69: ' numeric comparison: if two numbers compare equal (e.g., "1" and\n' jpayne@69: ' "1.0"), only one of them can be contained in a set.\n' jpayne@69: '\n' jpayne@69: ' There are currently two intrinsic set types:\n' jpayne@69: '\n' jpayne@69: ' Sets\n' jpayne@69: ' These represent a mutable set. They are created by the ' jpayne@69: 'built-in\n' jpayne@69: ' "set()" constructor and can be modified afterwards by ' jpayne@69: 'several\n' jpayne@69: ' methods, such as "add()".\n' jpayne@69: '\n' jpayne@69: ' Frozen sets\n' jpayne@69: ' These represent an immutable set. They are created by the\n' jpayne@69: ' built-in "frozenset()" constructor. As a frozenset is ' jpayne@69: 'immutable\n' jpayne@69: ' and *hashable*, it can be used again as an element of ' jpayne@69: 'another\n' jpayne@69: ' set, or as a dictionary key.\n' jpayne@69: '\n' jpayne@69: 'Mappings\n' jpayne@69: ' These represent finite sets of objects indexed by arbitrary ' jpayne@69: 'index\n' jpayne@69: ' sets. The subscript notation "a[k]" selects the item indexed by ' jpayne@69: '"k"\n' jpayne@69: ' from the mapping "a"; this can be used in expressions and as ' jpayne@69: 'the\n' jpayne@69: ' target of assignments or "del" statements. The built-in ' jpayne@69: 'function\n' jpayne@69: ' "len()" returns the number of items in a mapping.\n' jpayne@69: '\n' jpayne@69: ' There is currently a single intrinsic mapping type:\n' jpayne@69: '\n' jpayne@69: ' Dictionaries\n' jpayne@69: ' These represent finite sets of objects indexed by nearly\n' jpayne@69: ' arbitrary values. The only types of values not acceptable ' jpayne@69: 'as\n' jpayne@69: ' keys are values containing lists or dictionaries or other\n' jpayne@69: ' mutable types that are compared by value rather than by ' jpayne@69: 'object\n' jpayne@69: ' identity, the reason being that the efficient implementation ' jpayne@69: 'of\n' jpayne@69: ' dictionaries requires a key’s hash value to remain constant.\n' jpayne@69: ' Numeric types used for keys obey the normal rules for ' jpayne@69: 'numeric\n' jpayne@69: ' comparison: if two numbers compare equal (e.g., "1" and ' jpayne@69: '"1.0")\n' jpayne@69: ' then they can be used interchangeably to index the same\n' jpayne@69: ' dictionary entry.\n' jpayne@69: '\n' jpayne@69: ' Dictionaries are mutable; they can be created by the "{...}"\n' jpayne@69: ' notation (see section Dictionary displays).\n' jpayne@69: '\n' jpayne@69: ' The extension modules "dbm.ndbm" and "dbm.gnu" provide\n' jpayne@69: ' additional examples of mapping types, as does the ' jpayne@69: '"collections"\n' jpayne@69: ' module.\n' jpayne@69: '\n' jpayne@69: 'Callable types\n' jpayne@69: ' These are the types to which the function call operation (see\n' jpayne@69: ' section Calls) can be applied:\n' jpayne@69: '\n' jpayne@69: ' User-defined functions\n' jpayne@69: ' A user-defined function object is created by a function\n' jpayne@69: ' definition (see section Function definitions). It should be\n' jpayne@69: ' called with an argument list containing the same number of ' jpayne@69: 'items\n' jpayne@69: ' as the function’s formal parameter list.\n' jpayne@69: '\n' jpayne@69: ' Special attributes:\n' jpayne@69: '\n' jpayne@69: ' ' jpayne@69: '+---------------------------+---------------------------------+-------------+\n' jpayne@69: ' | Attribute | Meaning ' jpayne@69: '| |\n' jpayne@69: ' ' jpayne@69: '|===========================|=================================|=============|\n' jpayne@69: ' | "__doc__" | The function’s documentation ' jpayne@69: '| Writable |\n' jpayne@69: ' | | string, or "None" if ' jpayne@69: '| |\n' jpayne@69: ' | | unavailable; not inherited by ' jpayne@69: '| |\n' jpayne@69: ' | | subclasses. ' jpayne@69: '| |\n' jpayne@69: ' ' jpayne@69: '+---------------------------+---------------------------------+-------------+\n' jpayne@69: ' | "__name__" | The function’s name. ' jpayne@69: '| Writable |\n' jpayne@69: ' ' jpayne@69: '+---------------------------+---------------------------------+-------------+\n' jpayne@69: ' | "__qualname__" | The function’s *qualified ' jpayne@69: '| Writable |\n' jpayne@69: ' | | name*. New in version 3.3. ' jpayne@69: '| |\n' jpayne@69: ' ' jpayne@69: '+---------------------------+---------------------------------+-------------+\n' jpayne@69: ' | "__module__" | The name of the module the ' jpayne@69: '| Writable |\n' jpayne@69: ' | | function was defined in, or ' jpayne@69: '| |\n' jpayne@69: ' | | "None" if unavailable. ' jpayne@69: '| |\n' jpayne@69: ' ' jpayne@69: '+---------------------------+---------------------------------+-------------+\n' jpayne@69: ' | "__defaults__" | A tuple containing default ' jpayne@69: '| Writable |\n' jpayne@69: ' | | argument values for those ' jpayne@69: '| |\n' jpayne@69: ' | | arguments that have defaults, ' jpayne@69: '| |\n' jpayne@69: ' | | or "None" if no arguments have ' jpayne@69: '| |\n' jpayne@69: ' | | a default value. ' jpayne@69: '| |\n' jpayne@69: ' ' jpayne@69: '+---------------------------+---------------------------------+-------------+\n' jpayne@69: ' | "__code__" | The code object representing ' jpayne@69: '| Writable |\n' jpayne@69: ' | | the compiled function body. ' jpayne@69: '| |\n' jpayne@69: ' ' jpayne@69: '+---------------------------+---------------------------------+-------------+\n' jpayne@69: ' | "__globals__" | A reference to the dictionary ' jpayne@69: '| Read-only |\n' jpayne@69: ' | | that holds the function’s ' jpayne@69: '| |\n' jpayne@69: ' | | global variables — the global ' jpayne@69: '| |\n' jpayne@69: ' | | namespace of the module in ' jpayne@69: '| |\n' jpayne@69: ' | | which the function was defined. ' jpayne@69: '| |\n' jpayne@69: ' ' jpayne@69: '+---------------------------+---------------------------------+-------------+\n' jpayne@69: ' | "__dict__" | The namespace supporting ' jpayne@69: '| Writable |\n' jpayne@69: ' | | arbitrary function attributes. ' jpayne@69: '| |\n' jpayne@69: ' ' jpayne@69: '+---------------------------+---------------------------------+-------------+\n' jpayne@69: ' | "__closure__" | "None" or a tuple of cells that ' jpayne@69: '| Read-only |\n' jpayne@69: ' | | contain bindings for the ' jpayne@69: '| |\n' jpayne@69: ' | | function’s free variables. See ' jpayne@69: '| |\n' jpayne@69: ' | | below for information on the ' jpayne@69: '| |\n' jpayne@69: ' | | "cell_contents" attribute. ' jpayne@69: '| |\n' jpayne@69: ' ' jpayne@69: '+---------------------------+---------------------------------+-------------+\n' jpayne@69: ' | "__annotations__" | A dict containing annotations ' jpayne@69: '| Writable |\n' jpayne@69: ' | | of parameters. The keys of the ' jpayne@69: '| |\n' jpayne@69: ' | | dict are the parameter names, ' jpayne@69: '| |\n' jpayne@69: ' | | and "\'return\'" for the ' jpayne@69: 'return | |\n' jpayne@69: ' | | annotation, if provided. ' jpayne@69: '| |\n' jpayne@69: ' ' jpayne@69: '+---------------------------+---------------------------------+-------------+\n' jpayne@69: ' | "__kwdefaults__" | A dict containing defaults for ' jpayne@69: '| Writable |\n' jpayne@69: ' | | keyword-only parameters. ' jpayne@69: '| |\n' jpayne@69: ' ' jpayne@69: '+---------------------------+---------------------------------+-------------+\n' jpayne@69: '\n' jpayne@69: ' Most of the attributes labelled “Writable” check the type of ' jpayne@69: 'the\n' jpayne@69: ' assigned value.\n' jpayne@69: '\n' jpayne@69: ' Function objects also support getting and setting arbitrary\n' jpayne@69: ' attributes, which can be used, for example, to attach ' jpayne@69: 'metadata\n' jpayne@69: ' to functions. Regular attribute dot-notation is used to get ' jpayne@69: 'and\n' jpayne@69: ' set such attributes. *Note that the current implementation ' jpayne@69: 'only\n' jpayne@69: ' supports function attributes on user-defined functions. ' jpayne@69: 'Function\n' jpayne@69: ' attributes on built-in functions may be supported in the\n' jpayne@69: ' future.*\n' jpayne@69: '\n' jpayne@69: ' A cell object has the attribute "cell_contents". This can be\n' jpayne@69: ' used to get the value of the cell, as well as set the value.\n' jpayne@69: '\n' jpayne@69: ' Additional information about a function’s definition can be\n' jpayne@69: ' retrieved from its code object; see the description of ' jpayne@69: 'internal\n' jpayne@69: ' types below. The "cell" type can be accessed in the "types"\n' jpayne@69: ' module.\n' jpayne@69: '\n' jpayne@69: ' Instance methods\n' jpayne@69: ' An instance method object combines a class, a class instance ' jpayne@69: 'and\n' jpayne@69: ' any callable object (normally a user-defined function).\n' jpayne@69: '\n' jpayne@69: ' Special read-only attributes: "__self__" is the class ' jpayne@69: 'instance\n' jpayne@69: ' object, "__func__" is the function object; "__doc__" is the\n' jpayne@69: ' method’s documentation (same as "__func__.__doc__"); ' jpayne@69: '"__name__"\n' jpayne@69: ' is the method name (same as "__func__.__name__"); ' jpayne@69: '"__module__"\n' jpayne@69: ' is the name of the module the method was defined in, or ' jpayne@69: '"None"\n' jpayne@69: ' if unavailable.\n' jpayne@69: '\n' jpayne@69: ' Methods also support accessing (but not setting) the ' jpayne@69: 'arbitrary\n' jpayne@69: ' function attributes on the underlying function object.\n' jpayne@69: '\n' jpayne@69: ' User-defined method objects may be created when getting an\n' jpayne@69: ' attribute of a class (perhaps via an instance of that class), ' jpayne@69: 'if\n' jpayne@69: ' that attribute is a user-defined function object or a class\n' jpayne@69: ' method object.\n' jpayne@69: '\n' jpayne@69: ' When an instance method object is created by retrieving a ' jpayne@69: 'user-\n' jpayne@69: ' defined function object from a class via one of its ' jpayne@69: 'instances,\n' jpayne@69: ' its "__self__" attribute is the instance, and the method ' jpayne@69: 'object\n' jpayne@69: ' is said to be bound. The new method’s "__func__" attribute ' jpayne@69: 'is\n' jpayne@69: ' the original function object.\n' jpayne@69: '\n' jpayne@69: ' When an instance method object is created by retrieving a ' jpayne@69: 'class\n' jpayne@69: ' method object from a class or instance, its "__self__" ' jpayne@69: 'attribute\n' jpayne@69: ' is the class itself, and its "__func__" attribute is the\n' jpayne@69: ' function object underlying the class method.\n' jpayne@69: '\n' jpayne@69: ' When an instance method object is called, the underlying\n' jpayne@69: ' function ("__func__") is called, inserting the class ' jpayne@69: 'instance\n' jpayne@69: ' ("__self__") in front of the argument list. For instance, ' jpayne@69: 'when\n' jpayne@69: ' "C" is a class which contains a definition for a function ' jpayne@69: '"f()",\n' jpayne@69: ' and "x" is an instance of "C", calling "x.f(1)" is equivalent ' jpayne@69: 'to\n' jpayne@69: ' calling "C.f(x, 1)".\n' jpayne@69: '\n' jpayne@69: ' When an instance method object is derived from a class ' jpayne@69: 'method\n' jpayne@69: ' object, the “class instance” stored in "__self__" will ' jpayne@69: 'actually\n' jpayne@69: ' be the class itself, so that calling either "x.f(1)" or ' jpayne@69: '"C.f(1)"\n' jpayne@69: ' is equivalent to calling "f(C,1)" where "f" is the ' jpayne@69: 'underlying\n' jpayne@69: ' function.\n' jpayne@69: '\n' jpayne@69: ' Note that the transformation from function object to ' jpayne@69: 'instance\n' jpayne@69: ' method object happens each time the attribute is retrieved ' jpayne@69: 'from\n' jpayne@69: ' the instance. In some cases, a fruitful optimization is to\n' jpayne@69: ' assign the attribute to a local variable and call that local\n' jpayne@69: ' variable. Also notice that this transformation only happens ' jpayne@69: 'for\n' jpayne@69: ' user-defined functions; other callable objects (and all non-\n' jpayne@69: ' callable objects) are retrieved without transformation. It ' jpayne@69: 'is\n' jpayne@69: ' also important to note that user-defined functions which are\n' jpayne@69: ' attributes of a class instance are not converted to bound\n' jpayne@69: ' methods; this *only* happens when the function is an ' jpayne@69: 'attribute\n' jpayne@69: ' of the class.\n' jpayne@69: '\n' jpayne@69: ' Generator functions\n' jpayne@69: ' A function or method which uses the "yield" statement (see\n' jpayne@69: ' section The yield statement) is called a *generator ' jpayne@69: 'function*.\n' jpayne@69: ' Such a function, when called, always returns an iterator ' jpayne@69: 'object\n' jpayne@69: ' which can be used to execute the body of the function: ' jpayne@69: 'calling\n' jpayne@69: ' the iterator’s "iterator.__next__()" method will cause the\n' jpayne@69: ' function to execute until it provides a value using the ' jpayne@69: '"yield"\n' jpayne@69: ' statement. When the function executes a "return" statement ' jpayne@69: 'or\n' jpayne@69: ' falls off the end, a "StopIteration" exception is raised and ' jpayne@69: 'the\n' jpayne@69: ' iterator will have reached the end of the set of values to ' jpayne@69: 'be\n' jpayne@69: ' returned.\n' jpayne@69: '\n' jpayne@69: ' Coroutine functions\n' jpayne@69: ' A function or method which is defined using "async def" is\n' jpayne@69: ' called a *coroutine function*. Such a function, when ' jpayne@69: 'called,\n' jpayne@69: ' returns a *coroutine* object. It may contain "await"\n' jpayne@69: ' expressions, as well as "async with" and "async for" ' jpayne@69: 'statements.\n' jpayne@69: ' See also the Coroutine Objects section.\n' jpayne@69: '\n' jpayne@69: ' Asynchronous generator functions\n' jpayne@69: ' A function or method which is defined using "async def" and\n' jpayne@69: ' which uses the "yield" statement is called a *asynchronous\n' jpayne@69: ' generator function*. Such a function, when called, returns ' jpayne@69: 'an\n' jpayne@69: ' asynchronous iterator object which can be used in an "async ' jpayne@69: 'for"\n' jpayne@69: ' statement to execute the body of the function.\n' jpayne@69: '\n' jpayne@69: ' Calling the asynchronous iterator’s "aiterator.__anext__()"\n' jpayne@69: ' method will return an *awaitable* which when awaited will\n' jpayne@69: ' execute until it provides a value using the "yield" ' jpayne@69: 'expression.\n' jpayne@69: ' When the function executes an empty "return" statement or ' jpayne@69: 'falls\n' jpayne@69: ' off the end, a "StopAsyncIteration" exception is raised and ' jpayne@69: 'the\n' jpayne@69: ' asynchronous iterator will have reached the end of the set ' jpayne@69: 'of\n' jpayne@69: ' values to be yielded.\n' jpayne@69: '\n' jpayne@69: ' Built-in functions\n' jpayne@69: ' A built-in function object is a wrapper around a C function.\n' jpayne@69: ' Examples of built-in functions are "len()" and "math.sin()"\n' jpayne@69: ' ("math" is a standard built-in module). The number and type ' jpayne@69: 'of\n' jpayne@69: ' the arguments are determined by the C function. Special ' jpayne@69: 'read-\n' jpayne@69: ' only attributes: "__doc__" is the function’s documentation\n' jpayne@69: ' string, or "None" if unavailable; "__name__" is the ' jpayne@69: 'function’s\n' jpayne@69: ' name; "__self__" is set to "None" (but see the next item);\n' jpayne@69: ' "__module__" is the name of the module the function was ' jpayne@69: 'defined\n' jpayne@69: ' in or "None" if unavailable.\n' jpayne@69: '\n' jpayne@69: ' Built-in methods\n' jpayne@69: ' This is really a different disguise of a built-in function, ' jpayne@69: 'this\n' jpayne@69: ' time containing an object passed to the C function as an\n' jpayne@69: ' implicit extra argument. An example of a built-in method is\n' jpayne@69: ' "alist.append()", assuming *alist* is a list object. In this\n' jpayne@69: ' case, the special read-only attribute "__self__" is set to ' jpayne@69: 'the\n' jpayne@69: ' object denoted by *alist*.\n' jpayne@69: '\n' jpayne@69: ' Classes\n' jpayne@69: ' Classes are callable. These objects normally act as ' jpayne@69: 'factories\n' jpayne@69: ' for new instances of themselves, but variations are possible ' jpayne@69: 'for\n' jpayne@69: ' class types that override "__new__()". The arguments of the\n' jpayne@69: ' call are passed to "__new__()" and, in the typical case, to\n' jpayne@69: ' "__init__()" to initialize the new instance.\n' jpayne@69: '\n' jpayne@69: ' Class Instances\n' jpayne@69: ' Instances of arbitrary classes can be made callable by ' jpayne@69: 'defining\n' jpayne@69: ' a "__call__()" method in their class.\n' jpayne@69: '\n' jpayne@69: 'Modules\n' jpayne@69: ' Modules are a basic organizational unit of Python code, and are\n' jpayne@69: ' created by the import system as invoked either by the "import"\n' jpayne@69: ' statement, or by calling functions such as\n' jpayne@69: ' "importlib.import_module()" and built-in "__import__()". A ' jpayne@69: 'module\n' jpayne@69: ' object has a namespace implemented by a dictionary object (this ' jpayne@69: 'is\n' jpayne@69: ' the dictionary referenced by the "__globals__" attribute of\n' jpayne@69: ' functions defined in the module). Attribute references are\n' jpayne@69: ' translated to lookups in this dictionary, e.g., "m.x" is ' jpayne@69: 'equivalent\n' jpayne@69: ' to "m.__dict__["x"]". A module object does not contain the code\n' jpayne@69: ' object used to initialize the module (since it isn’t needed ' jpayne@69: 'once\n' jpayne@69: ' the initialization is done).\n' jpayne@69: '\n' jpayne@69: ' Attribute assignment updates the module’s namespace dictionary,\n' jpayne@69: ' e.g., "m.x = 1" is equivalent to "m.__dict__["x"] = 1".\n' jpayne@69: '\n' jpayne@69: ' Predefined (writable) attributes: "__name__" is the module’s ' jpayne@69: 'name;\n' jpayne@69: ' "__doc__" is the module’s documentation string, or "None" if\n' jpayne@69: ' unavailable; "__annotations__" (optional) is a dictionary\n' jpayne@69: ' containing *variable annotations* collected during module body\n' jpayne@69: ' execution; "__file__" is the pathname of the file from which ' jpayne@69: 'the\n' jpayne@69: ' module was loaded, if it was loaded from a file. The "__file__"\n' jpayne@69: ' attribute may be missing for certain types of modules, such as ' jpayne@69: 'C\n' jpayne@69: ' modules that are statically linked into the interpreter; for\n' jpayne@69: ' extension modules loaded dynamically from a shared library, it ' jpayne@69: 'is\n' jpayne@69: ' the pathname of the shared library file.\n' jpayne@69: '\n' jpayne@69: ' Special read-only attribute: "__dict__" is the module’s ' jpayne@69: 'namespace\n' jpayne@69: ' as a dictionary object.\n' jpayne@69: '\n' jpayne@69: ' **CPython implementation detail:** Because of the way CPython\n' jpayne@69: ' clears module dictionaries, the module dictionary will be ' jpayne@69: 'cleared\n' jpayne@69: ' when the module falls out of scope even if the dictionary still ' jpayne@69: 'has\n' jpayne@69: ' live references. To avoid this, copy the dictionary or keep ' jpayne@69: 'the\n' jpayne@69: ' module around while using its dictionary directly.\n' jpayne@69: '\n' jpayne@69: 'Custom classes\n' jpayne@69: ' Custom class types are typically created by class definitions ' jpayne@69: '(see\n' jpayne@69: ' section Class definitions). A class has a namespace implemented ' jpayne@69: 'by\n' jpayne@69: ' a dictionary object. Class attribute references are translated ' jpayne@69: 'to\n' jpayne@69: ' lookups in this dictionary, e.g., "C.x" is translated to\n' jpayne@69: ' "C.__dict__["x"]" (although there are a number of hooks which ' jpayne@69: 'allow\n' jpayne@69: ' for other means of locating attributes). When the attribute name ' jpayne@69: 'is\n' jpayne@69: ' not found there, the attribute search continues in the base\n' jpayne@69: ' classes. This search of the base classes uses the C3 method\n' jpayne@69: ' resolution order which behaves correctly even in the presence ' jpayne@69: 'of\n' jpayne@69: ' ‘diamond’ inheritance structures where there are multiple\n' jpayne@69: ' inheritance paths leading back to a common ancestor. Additional\n' jpayne@69: ' details on the C3 MRO used by Python can be found in the\n' jpayne@69: ' documentation accompanying the 2.3 release at\n' jpayne@69: ' https://www.python.org/download/releases/2.3/mro/.\n' jpayne@69: '\n' jpayne@69: ' When a class attribute reference (for class "C", say) would ' jpayne@69: 'yield a\n' jpayne@69: ' class method object, it is transformed into an instance method\n' jpayne@69: ' object whose "__self__" attribute is "C". When it would yield ' jpayne@69: 'a\n' jpayne@69: ' static method object, it is transformed into the object wrapped ' jpayne@69: 'by\n' jpayne@69: ' the static method object. See section Implementing Descriptors ' jpayne@69: 'for\n' jpayne@69: ' another way in which attributes retrieved from a class may ' jpayne@69: 'differ\n' jpayne@69: ' from those actually contained in its "__dict__".\n' jpayne@69: '\n' jpayne@69: ' Class attribute assignments update the class’s dictionary, ' jpayne@69: 'never\n' jpayne@69: ' the dictionary of a base class.\n' jpayne@69: '\n' jpayne@69: ' A class object can be called (see above) to yield a class ' jpayne@69: 'instance\n' jpayne@69: ' (see below).\n' jpayne@69: '\n' jpayne@69: ' Special attributes: "__name__" is the class name; "__module__" ' jpayne@69: 'is\n' jpayne@69: ' the module name in which the class was defined; "__dict__" is ' jpayne@69: 'the\n' jpayne@69: ' dictionary containing the class’s namespace; "__bases__" is a ' jpayne@69: 'tuple\n' jpayne@69: ' containing the base classes, in the order of their occurrence ' jpayne@69: 'in\n' jpayne@69: ' the base class list; "__doc__" is the class’s documentation ' jpayne@69: 'string,\n' jpayne@69: ' or "None" if undefined; "__annotations__" (optional) is a\n' jpayne@69: ' dictionary containing *variable annotations* collected during ' jpayne@69: 'class\n' jpayne@69: ' body execution.\n' jpayne@69: '\n' jpayne@69: 'Class instances\n' jpayne@69: ' A class instance is created by calling a class object (see ' jpayne@69: 'above).\n' jpayne@69: ' A class instance has a namespace implemented as a dictionary ' jpayne@69: 'which\n' jpayne@69: ' is the first place in which attribute references are searched.\n' jpayne@69: ' When an attribute is not found there, and the instance’s class ' jpayne@69: 'has\n' jpayne@69: ' an attribute by that name, the search continues with the class\n' jpayne@69: ' attributes. If a class attribute is found that is a ' jpayne@69: 'user-defined\n' jpayne@69: ' function object, it is transformed into an instance method ' jpayne@69: 'object\n' jpayne@69: ' whose "__self__" attribute is the instance. Static method and\n' jpayne@69: ' class method objects are also transformed; see above under\n' jpayne@69: ' “Classes”. See section Implementing Descriptors for another way ' jpayne@69: 'in\n' jpayne@69: ' which attributes of a class retrieved via its instances may ' jpayne@69: 'differ\n' jpayne@69: ' from the objects actually stored in the class’s "__dict__". If ' jpayne@69: 'no\n' jpayne@69: ' class attribute is found, and the object’s class has a\n' jpayne@69: ' "__getattr__()" method, that is called to satisfy the lookup.\n' jpayne@69: '\n' jpayne@69: ' Attribute assignments and deletions update the instance’s\n' jpayne@69: ' dictionary, never a class’s dictionary. If the class has a\n' jpayne@69: ' "__setattr__()" or "__delattr__()" method, this is called ' jpayne@69: 'instead\n' jpayne@69: ' of updating the instance dictionary directly.\n' jpayne@69: '\n' jpayne@69: ' Class instances can pretend to be numbers, sequences, or ' jpayne@69: 'mappings\n' jpayne@69: ' if they have methods with certain special names. See section\n' jpayne@69: ' Special method names.\n' jpayne@69: '\n' jpayne@69: ' Special attributes: "__dict__" is the attribute dictionary;\n' jpayne@69: ' "__class__" is the instance’s class.\n' jpayne@69: '\n' jpayne@69: 'I/O objects (also known as file objects)\n' jpayne@69: ' A *file object* represents an open file. Various shortcuts are\n' jpayne@69: ' available to create file objects: the "open()" built-in ' jpayne@69: 'function,\n' jpayne@69: ' and also "os.popen()", "os.fdopen()", and the "makefile()" ' jpayne@69: 'method\n' jpayne@69: ' of socket objects (and perhaps by other functions or methods\n' jpayne@69: ' provided by extension modules).\n' jpayne@69: '\n' jpayne@69: ' The objects "sys.stdin", "sys.stdout" and "sys.stderr" are\n' jpayne@69: ' initialized to file objects corresponding to the interpreter’s\n' jpayne@69: ' standard input, output and error streams; they are all open in ' jpayne@69: 'text\n' jpayne@69: ' mode and therefore follow the interface defined by the\n' jpayne@69: ' "io.TextIOBase" abstract class.\n' jpayne@69: '\n' jpayne@69: 'Internal types\n' jpayne@69: ' A few types used internally by the interpreter are exposed to ' jpayne@69: 'the\n' jpayne@69: ' user. Their definitions may change with future versions of the\n' jpayne@69: ' interpreter, but they are mentioned here for completeness.\n' jpayne@69: '\n' jpayne@69: ' Code objects\n' jpayne@69: ' Code objects represent *byte-compiled* executable Python ' jpayne@69: 'code,\n' jpayne@69: ' or *bytecode*. The difference between a code object and a\n' jpayne@69: ' function object is that the function object contains an ' jpayne@69: 'explicit\n' jpayne@69: ' reference to the function’s globals (the module in which it ' jpayne@69: 'was\n' jpayne@69: ' defined), while a code object contains no context; also the\n' jpayne@69: ' default argument values are stored in the function object, ' jpayne@69: 'not\n' jpayne@69: ' in the code object (because they represent values calculated ' jpayne@69: 'at\n' jpayne@69: ' run-time). Unlike function objects, code objects are ' jpayne@69: 'immutable\n' jpayne@69: ' and contain no references (directly or indirectly) to ' jpayne@69: 'mutable\n' jpayne@69: ' objects.\n' jpayne@69: '\n' jpayne@69: ' Special read-only attributes: "co_name" gives the function ' jpayne@69: 'name;\n' jpayne@69: ' "co_argcount" is the total number of positional arguments\n' jpayne@69: ' (including positional-only arguments and arguments with ' jpayne@69: 'default\n' jpayne@69: ' values); "co_posonlyargcount" is the number of ' jpayne@69: 'positional-only\n' jpayne@69: ' arguments (including arguments with default values);\n' jpayne@69: ' "co_kwonlyargcount" is the number of keyword-only arguments\n' jpayne@69: ' (including arguments with default values); "co_nlocals" is ' jpayne@69: 'the\n' jpayne@69: ' number of local variables used by the function (including\n' jpayne@69: ' arguments); "co_varnames" is a tuple containing the names of ' jpayne@69: 'the\n' jpayne@69: ' local variables (starting with the argument names);\n' jpayne@69: ' "co_cellvars" is a tuple containing the names of local ' jpayne@69: 'variables\n' jpayne@69: ' that are referenced by nested functions; "co_freevars" is a\n' jpayne@69: ' tuple containing the names of free variables; "co_code" is a\n' jpayne@69: ' string representing the sequence of bytecode instructions;\n' jpayne@69: ' "co_consts" is a tuple containing the literals used by the\n' jpayne@69: ' bytecode; "co_names" is a tuple containing the names used by ' jpayne@69: 'the\n' jpayne@69: ' bytecode; "co_filename" is the filename from which the code ' jpayne@69: 'was\n' jpayne@69: ' compiled; "co_firstlineno" is the first line number of the\n' jpayne@69: ' function; "co_lnotab" is a string encoding the mapping from\n' jpayne@69: ' bytecode offsets to line numbers (for details see the source\n' jpayne@69: ' code of the interpreter); "co_stacksize" is the required ' jpayne@69: 'stack\n' jpayne@69: ' size (including local variables); "co_flags" is an integer\n' jpayne@69: ' encoding a number of flags for the interpreter.\n' jpayne@69: '\n' jpayne@69: ' The following flag bits are defined for "co_flags": bit ' jpayne@69: '"0x04"\n' jpayne@69: ' is set if the function uses the "*arguments" syntax to accept ' jpayne@69: 'an\n' jpayne@69: ' arbitrary number of positional arguments; bit "0x08" is set ' jpayne@69: 'if\n' jpayne@69: ' the function uses the "**keywords" syntax to accept ' jpayne@69: 'arbitrary\n' jpayne@69: ' keyword arguments; bit "0x20" is set if the function is a\n' jpayne@69: ' generator.\n' jpayne@69: '\n' jpayne@69: ' Future feature declarations ("from __future__ import ' jpayne@69: 'division")\n' jpayne@69: ' also use bits in "co_flags" to indicate whether a code ' jpayne@69: 'object\n' jpayne@69: ' was compiled with a particular feature enabled: bit "0x2000" ' jpayne@69: 'is\n' jpayne@69: ' set if the function was compiled with future division ' jpayne@69: 'enabled;\n' jpayne@69: ' bits "0x10" and "0x1000" were used in earlier versions of\n' jpayne@69: ' Python.\n' jpayne@69: '\n' jpayne@69: ' Other bits in "co_flags" are reserved for internal use.\n' jpayne@69: '\n' jpayne@69: ' If a code object represents a function, the first item in\n' jpayne@69: ' "co_consts" is the documentation string of the function, or\n' jpayne@69: ' "None" if undefined.\n' jpayne@69: '\n' jpayne@69: ' Frame objects\n' jpayne@69: ' Frame objects represent execution frames. They may occur in\n' jpayne@69: ' traceback objects (see below), and are also passed to ' jpayne@69: 'registered\n' jpayne@69: ' trace functions.\n' jpayne@69: '\n' jpayne@69: ' Special read-only attributes: "f_back" is to the previous ' jpayne@69: 'stack\n' jpayne@69: ' frame (towards the caller), or "None" if this is the bottom\n' jpayne@69: ' stack frame; "f_code" is the code object being executed in ' jpayne@69: 'this\n' jpayne@69: ' frame; "f_locals" is the dictionary used to look up local\n' jpayne@69: ' variables; "f_globals" is used for global variables;\n' jpayne@69: ' "f_builtins" is used for built-in (intrinsic) names; ' jpayne@69: '"f_lasti"\n' jpayne@69: ' gives the precise instruction (this is an index into the\n' jpayne@69: ' bytecode string of the code object).\n' jpayne@69: '\n' jpayne@69: ' Special writable attributes: "f_trace", if not "None", is a\n' jpayne@69: ' function called for various events during code execution ' jpayne@69: '(this\n' jpayne@69: ' is used by the debugger). Normally an event is triggered for\n' jpayne@69: ' each new source line - this can be disabled by setting\n' jpayne@69: ' "f_trace_lines" to "False".\n' jpayne@69: '\n' jpayne@69: ' Implementations *may* allow per-opcode events to be requested ' jpayne@69: 'by\n' jpayne@69: ' setting "f_trace_opcodes" to "True". Note that this may lead ' jpayne@69: 'to\n' jpayne@69: ' undefined interpreter behaviour if exceptions raised by the\n' jpayne@69: ' trace function escape to the function being traced.\n' jpayne@69: '\n' jpayne@69: ' "f_lineno" is the current line number of the frame — writing ' jpayne@69: 'to\n' jpayne@69: ' this from within a trace function jumps to the given line ' jpayne@69: '(only\n' jpayne@69: ' for the bottom-most frame). A debugger can implement a Jump\n' jpayne@69: ' command (aka Set Next Statement) by writing to f_lineno.\n' jpayne@69: '\n' jpayne@69: ' Frame objects support one method:\n' jpayne@69: '\n' jpayne@69: ' frame.clear()\n' jpayne@69: '\n' jpayne@69: ' This method clears all references to local variables held ' jpayne@69: 'by\n' jpayne@69: ' the frame. Also, if the frame belonged to a generator, ' jpayne@69: 'the\n' jpayne@69: ' generator is finalized. This helps break reference ' jpayne@69: 'cycles\n' jpayne@69: ' involving frame objects (for example when catching an\n' jpayne@69: ' exception and storing its traceback for later use).\n' jpayne@69: '\n' jpayne@69: ' "RuntimeError" is raised if the frame is currently ' jpayne@69: 'executing.\n' jpayne@69: '\n' jpayne@69: ' New in version 3.4.\n' jpayne@69: '\n' jpayne@69: ' Traceback objects\n' jpayne@69: ' Traceback objects represent a stack trace of an exception. ' jpayne@69: 'A\n' jpayne@69: ' traceback object is implicitly created when an exception ' jpayne@69: 'occurs,\n' jpayne@69: ' and may also be explicitly created by calling\n' jpayne@69: ' "types.TracebackType".\n' jpayne@69: '\n' jpayne@69: ' For implicitly created tracebacks, when the search for an\n' jpayne@69: ' exception handler unwinds the execution stack, at each ' jpayne@69: 'unwound\n' jpayne@69: ' level a traceback object is inserted in front of the current\n' jpayne@69: ' traceback. When an exception handler is entered, the stack\n' jpayne@69: ' trace is made available to the program. (See section The try\n' jpayne@69: ' statement.) It is accessible as the third item of the tuple\n' jpayne@69: ' returned by "sys.exc_info()", and as the "__traceback__"\n' jpayne@69: ' attribute of the caught exception.\n' jpayne@69: '\n' jpayne@69: ' When the program contains no suitable handler, the stack ' jpayne@69: 'trace\n' jpayne@69: ' is written (nicely formatted) to the standard error stream; ' jpayne@69: 'if\n' jpayne@69: ' the interpreter is interactive, it is also made available to ' jpayne@69: 'the\n' jpayne@69: ' user as "sys.last_traceback".\n' jpayne@69: '\n' jpayne@69: ' For explicitly created tracebacks, it is up to the creator ' jpayne@69: 'of\n' jpayne@69: ' the traceback to determine how the "tb_next" attributes ' jpayne@69: 'should\n' jpayne@69: ' be linked to form a full stack trace.\n' jpayne@69: '\n' jpayne@69: ' Special read-only attributes: "tb_frame" points to the ' jpayne@69: 'execution\n' jpayne@69: ' frame of the current level; "tb_lineno" gives the line ' jpayne@69: 'number\n' jpayne@69: ' where the exception occurred; "tb_lasti" indicates the ' jpayne@69: 'precise\n' jpayne@69: ' instruction. The line number and last instruction in the\n' jpayne@69: ' traceback may differ from the line number of its frame object ' jpayne@69: 'if\n' jpayne@69: ' the exception occurred in a "try" statement with no matching\n' jpayne@69: ' except clause or with a finally clause.\n' jpayne@69: '\n' jpayne@69: ' Special writable attribute: "tb_next" is the next level in ' jpayne@69: 'the\n' jpayne@69: ' stack trace (towards the frame where the exception occurred), ' jpayne@69: 'or\n' jpayne@69: ' "None" if there is no next level.\n' jpayne@69: '\n' jpayne@69: ' Changed in version 3.7: Traceback objects can now be ' jpayne@69: 'explicitly\n' jpayne@69: ' instantiated from Python code, and the "tb_next" attribute ' jpayne@69: 'of\n' jpayne@69: ' existing instances can be updated.\n' jpayne@69: '\n' jpayne@69: ' Slice objects\n' jpayne@69: ' Slice objects are used to represent slices for ' jpayne@69: '"__getitem__()"\n' jpayne@69: ' methods. They are also created by the built-in "slice()"\n' jpayne@69: ' function.\n' jpayne@69: '\n' jpayne@69: ' Special read-only attributes: "start" is the lower bound; ' jpayne@69: '"stop"\n' jpayne@69: ' is the upper bound; "step" is the step value; each is "None" ' jpayne@69: 'if\n' jpayne@69: ' omitted. These attributes can have any type.\n' jpayne@69: '\n' jpayne@69: ' Slice objects support one method:\n' jpayne@69: '\n' jpayne@69: ' slice.indices(self, length)\n' jpayne@69: '\n' jpayne@69: ' This method takes a single integer argument *length* and\n' jpayne@69: ' computes information about the slice that the slice ' jpayne@69: 'object\n' jpayne@69: ' would describe if applied to a sequence of *length* ' jpayne@69: 'items.\n' jpayne@69: ' It returns a tuple of three integers; respectively these ' jpayne@69: 'are\n' jpayne@69: ' the *start* and *stop* indices and the *step* or stride\n' jpayne@69: ' length of the slice. Missing or out-of-bounds indices are\n' jpayne@69: ' handled in a manner consistent with regular slices.\n' jpayne@69: '\n' jpayne@69: ' Static method objects\n' jpayne@69: ' Static method objects provide a way of defeating the\n' jpayne@69: ' transformation of function objects to method objects ' jpayne@69: 'described\n' jpayne@69: ' above. A static method object is a wrapper around any other\n' jpayne@69: ' object, usually a user-defined method object. When a static\n' jpayne@69: ' method object is retrieved from a class or a class instance, ' jpayne@69: 'the\n' jpayne@69: ' object actually returned is the wrapped object, which is not\n' jpayne@69: ' subject to any further transformation. Static method objects ' jpayne@69: 'are\n' jpayne@69: ' not themselves callable, although the objects they wrap ' jpayne@69: 'usually\n' jpayne@69: ' are. Static method objects are created by the built-in\n' jpayne@69: ' "staticmethod()" constructor.\n' jpayne@69: '\n' jpayne@69: ' Class method objects\n' jpayne@69: ' A class method object, like a static method object, is a ' jpayne@69: 'wrapper\n' jpayne@69: ' around another object that alters the way in which that ' jpayne@69: 'object\n' jpayne@69: ' is retrieved from classes and class instances. The behaviour ' jpayne@69: 'of\n' jpayne@69: ' class method objects upon such retrieval is described above,\n' jpayne@69: ' under “User-defined methods”. Class method objects are ' jpayne@69: 'created\n' jpayne@69: ' by the built-in "classmethod()" constructor.\n', jpayne@69: 'typesfunctions': 'Functions\n' jpayne@69: '*********\n' jpayne@69: '\n' jpayne@69: 'Function objects are created by function definitions. The ' jpayne@69: 'only\n' jpayne@69: 'operation on a function object is to call it: ' jpayne@69: '"func(argument-list)".\n' jpayne@69: '\n' jpayne@69: 'There are really two flavors of function objects: built-in ' jpayne@69: 'functions\n' jpayne@69: 'and user-defined functions. Both support the same ' jpayne@69: 'operation (to call\n' jpayne@69: 'the function), but the implementation is different, hence ' jpayne@69: 'the\n' jpayne@69: 'different object types.\n' jpayne@69: '\n' jpayne@69: 'See Function definitions for more information.\n', jpayne@69: 'typesmapping': 'Mapping Types — "dict"\n' jpayne@69: '**********************\n' jpayne@69: '\n' jpayne@69: 'A *mapping* object maps *hashable* values to arbitrary ' jpayne@69: 'objects.\n' jpayne@69: 'Mappings are mutable objects. There is currently only one ' jpayne@69: 'standard\n' jpayne@69: 'mapping type, the *dictionary*. (For other containers see ' jpayne@69: 'the built-\n' jpayne@69: 'in "list", "set", and "tuple" classes, and the "collections" ' jpayne@69: 'module.)\n' jpayne@69: '\n' jpayne@69: 'A dictionary’s keys are *almost* arbitrary values. Values ' jpayne@69: 'that are\n' jpayne@69: 'not *hashable*, that is, values containing lists, ' jpayne@69: 'dictionaries or\n' jpayne@69: 'other mutable types (that are compared by value rather than ' jpayne@69: 'by object\n' jpayne@69: 'identity) may not be used as keys. Numeric types used for ' jpayne@69: 'keys obey\n' jpayne@69: 'the normal rules for numeric comparison: if two numbers ' jpayne@69: 'compare equal\n' jpayne@69: '(such as "1" and "1.0") then they can be used ' jpayne@69: 'interchangeably to index\n' jpayne@69: 'the same dictionary entry. (Note however, that since ' jpayne@69: 'computers store\n' jpayne@69: 'floating-point numbers as approximations it is usually ' jpayne@69: 'unwise to use\n' jpayne@69: 'them as dictionary keys.)\n' jpayne@69: '\n' jpayne@69: 'Dictionaries can be created by placing a comma-separated ' jpayne@69: 'list of "key:\n' jpayne@69: 'value" pairs within braces, for example: "{\'jack\': 4098, ' jpayne@69: "'sjoerd':\n" jpayne@69: '4127}" or "{4098: \'jack\', 4127: \'sjoerd\'}", or by the ' jpayne@69: '"dict"\n' jpayne@69: 'constructor.\n' jpayne@69: '\n' jpayne@69: 'class dict(**kwarg)\n' jpayne@69: 'class dict(mapping, **kwarg)\n' jpayne@69: 'class dict(iterable, **kwarg)\n' jpayne@69: '\n' jpayne@69: ' Return a new dictionary initialized from an optional ' jpayne@69: 'positional\n' jpayne@69: ' argument and a possibly empty set of keyword arguments.\n' jpayne@69: '\n' jpayne@69: ' If no positional argument is given, an empty dictionary ' jpayne@69: 'is created.\n' jpayne@69: ' If a positional argument is given and it is a mapping ' jpayne@69: 'object, a\n' jpayne@69: ' dictionary is created with the same key-value pairs as ' jpayne@69: 'the mapping\n' jpayne@69: ' object. Otherwise, the positional argument must be an ' jpayne@69: '*iterable*\n' jpayne@69: ' object. Each item in the iterable must itself be an ' jpayne@69: 'iterable with\n' jpayne@69: ' exactly two objects. The first object of each item ' jpayne@69: 'becomes a key\n' jpayne@69: ' in the new dictionary, and the second object the ' jpayne@69: 'corresponding\n' jpayne@69: ' value. If a key occurs more than once, the last value ' jpayne@69: 'for that key\n' jpayne@69: ' becomes the corresponding value in the new dictionary.\n' jpayne@69: '\n' jpayne@69: ' If keyword arguments are given, the keyword arguments and ' jpayne@69: 'their\n' jpayne@69: ' values are added to the dictionary created from the ' jpayne@69: 'positional\n' jpayne@69: ' argument. If a key being added is already present, the ' jpayne@69: 'value from\n' jpayne@69: ' the keyword argument replaces the value from the ' jpayne@69: 'positional\n' jpayne@69: ' argument.\n' jpayne@69: '\n' jpayne@69: ' To illustrate, the following examples all return a ' jpayne@69: 'dictionary equal\n' jpayne@69: ' to "{"one": 1, "two": 2, "three": 3}":\n' jpayne@69: '\n' jpayne@69: ' >>> a = dict(one=1, two=2, three=3)\n' jpayne@69: " >>> b = {'one': 1, 'two': 2, 'three': 3}\n" jpayne@69: " >>> c = dict(zip(['one', 'two', 'three'], [1, 2, 3]))\n" jpayne@69: " >>> d = dict([('two', 2), ('one', 1), ('three', 3)])\n" jpayne@69: " >>> e = dict({'three': 3, 'one': 1, 'two': 2})\n" jpayne@69: ' >>> a == b == c == d == e\n' jpayne@69: ' True\n' jpayne@69: '\n' jpayne@69: ' Providing keyword arguments as in the first example only ' jpayne@69: 'works for\n' jpayne@69: ' keys that are valid Python identifiers. Otherwise, any ' jpayne@69: 'valid keys\n' jpayne@69: ' can be used.\n' jpayne@69: '\n' jpayne@69: ' These are the operations that dictionaries support (and ' jpayne@69: 'therefore,\n' jpayne@69: ' custom mapping types should support too):\n' jpayne@69: '\n' jpayne@69: ' list(d)\n' jpayne@69: '\n' jpayne@69: ' Return a list of all the keys used in the dictionary ' jpayne@69: '*d*.\n' jpayne@69: '\n' jpayne@69: ' len(d)\n' jpayne@69: '\n' jpayne@69: ' Return the number of items in the dictionary *d*.\n' jpayne@69: '\n' jpayne@69: ' d[key]\n' jpayne@69: '\n' jpayne@69: ' Return the item of *d* with key *key*. Raises a ' jpayne@69: '"KeyError" if\n' jpayne@69: ' *key* is not in the map.\n' jpayne@69: '\n' jpayne@69: ' If a subclass of dict defines a method "__missing__()" ' jpayne@69: 'and *key*\n' jpayne@69: ' is not present, the "d[key]" operation calls that ' jpayne@69: 'method with\n' jpayne@69: ' the key *key* as argument. The "d[key]" operation ' jpayne@69: 'then returns\n' jpayne@69: ' or raises whatever is returned or raised by the\n' jpayne@69: ' "__missing__(key)" call. No other operations or ' jpayne@69: 'methods invoke\n' jpayne@69: ' "__missing__()". If "__missing__()" is not defined, ' jpayne@69: '"KeyError"\n' jpayne@69: ' is raised. "__missing__()" must be a method; it cannot ' jpayne@69: 'be an\n' jpayne@69: ' instance variable:\n' jpayne@69: '\n' jpayne@69: ' >>> class Counter(dict):\n' jpayne@69: ' ... def __missing__(self, key):\n' jpayne@69: ' ... return 0\n' jpayne@69: ' >>> c = Counter()\n' jpayne@69: " >>> c['red']\n" jpayne@69: ' 0\n' jpayne@69: " >>> c['red'] += 1\n" jpayne@69: " >>> c['red']\n" jpayne@69: ' 1\n' jpayne@69: '\n' jpayne@69: ' The example above shows part of the implementation of\n' jpayne@69: ' "collections.Counter". A different "__missing__" ' jpayne@69: 'method is used\n' jpayne@69: ' by "collections.defaultdict".\n' jpayne@69: '\n' jpayne@69: ' d[key] = value\n' jpayne@69: '\n' jpayne@69: ' Set "d[key]" to *value*.\n' jpayne@69: '\n' jpayne@69: ' del d[key]\n' jpayne@69: '\n' jpayne@69: ' Remove "d[key]" from *d*. Raises a "KeyError" if ' jpayne@69: '*key* is not\n' jpayne@69: ' in the map.\n' jpayne@69: '\n' jpayne@69: ' key in d\n' jpayne@69: '\n' jpayne@69: ' Return "True" if *d* has a key *key*, else "False".\n' jpayne@69: '\n' jpayne@69: ' key not in d\n' jpayne@69: '\n' jpayne@69: ' Equivalent to "not key in d".\n' jpayne@69: '\n' jpayne@69: ' iter(d)\n' jpayne@69: '\n' jpayne@69: ' Return an iterator over the keys of the dictionary. ' jpayne@69: 'This is a\n' jpayne@69: ' shortcut for "iter(d.keys())".\n' jpayne@69: '\n' jpayne@69: ' clear()\n' jpayne@69: '\n' jpayne@69: ' Remove all items from the dictionary.\n' jpayne@69: '\n' jpayne@69: ' copy()\n' jpayne@69: '\n' jpayne@69: ' Return a shallow copy of the dictionary.\n' jpayne@69: '\n' jpayne@69: ' classmethod fromkeys(iterable[, value])\n' jpayne@69: '\n' jpayne@69: ' Create a new dictionary with keys from *iterable* and ' jpayne@69: 'values set\n' jpayne@69: ' to *value*.\n' jpayne@69: '\n' jpayne@69: ' "fromkeys()" is a class method that returns a new ' jpayne@69: 'dictionary.\n' jpayne@69: ' *value* defaults to "None". All of the values refer ' jpayne@69: 'to just a\n' jpayne@69: ' single instance, so it generally doesn’t make sense ' jpayne@69: 'for *value*\n' jpayne@69: ' to be a mutable object such as an empty list. To get ' jpayne@69: 'distinct\n' jpayne@69: ' values, use a dict comprehension instead.\n' jpayne@69: '\n' jpayne@69: ' get(key[, default])\n' jpayne@69: '\n' jpayne@69: ' Return the value for *key* if *key* is in the ' jpayne@69: 'dictionary, else\n' jpayne@69: ' *default*. If *default* is not given, it defaults to ' jpayne@69: '"None", so\n' jpayne@69: ' that this method never raises a "KeyError".\n' jpayne@69: '\n' jpayne@69: ' items()\n' jpayne@69: '\n' jpayne@69: ' Return a new view of the dictionary’s items ("(key, ' jpayne@69: 'value)"\n' jpayne@69: ' pairs). See the documentation of view objects.\n' jpayne@69: '\n' jpayne@69: ' keys()\n' jpayne@69: '\n' jpayne@69: ' Return a new view of the dictionary’s keys. See the\n' jpayne@69: ' documentation of view objects.\n' jpayne@69: '\n' jpayne@69: ' pop(key[, default])\n' jpayne@69: '\n' jpayne@69: ' If *key* is in the dictionary, remove it and return ' jpayne@69: 'its value,\n' jpayne@69: ' else return *default*. If *default* is not given and ' jpayne@69: '*key* is\n' jpayne@69: ' not in the dictionary, a "KeyError" is raised.\n' jpayne@69: '\n' jpayne@69: ' popitem()\n' jpayne@69: '\n' jpayne@69: ' Remove and return a "(key, value)" pair from the ' jpayne@69: 'dictionary.\n' jpayne@69: ' Pairs are returned in LIFO (last-in, first-out) ' jpayne@69: 'order.\n' jpayne@69: '\n' jpayne@69: ' "popitem()" is useful to destructively iterate over a\n' jpayne@69: ' dictionary, as often used in set algorithms. If the ' jpayne@69: 'dictionary\n' jpayne@69: ' is empty, calling "popitem()" raises a "KeyError".\n' jpayne@69: '\n' jpayne@69: ' Changed in version 3.7: LIFO order is now guaranteed. ' jpayne@69: 'In prior\n' jpayne@69: ' versions, "popitem()" would return an arbitrary ' jpayne@69: 'key/value pair.\n' jpayne@69: '\n' jpayne@69: ' reversed(d)\n' jpayne@69: '\n' jpayne@69: ' Return a reverse iterator over the keys of the ' jpayne@69: 'dictionary. This\n' jpayne@69: ' is a shortcut for "reversed(d.keys())".\n' jpayne@69: '\n' jpayne@69: ' setdefault(key[, default])\n' jpayne@69: '\n' jpayne@69: ' If *key* is in the dictionary, return its value. If ' jpayne@69: 'not, insert\n' jpayne@69: ' *key* with a value of *default* and return *default*. ' jpayne@69: '*default*\n' jpayne@69: ' defaults to "None".\n' jpayne@69: '\n' jpayne@69: ' update([other])\n' jpayne@69: '\n' jpayne@69: ' Update the dictionary with the key/value pairs from ' jpayne@69: '*other*,\n' jpayne@69: ' overwriting existing keys. Return "None".\n' jpayne@69: '\n' jpayne@69: ' "update()" accepts either another dictionary object or ' jpayne@69: 'an\n' jpayne@69: ' iterable of key/value pairs (as tuples or other ' jpayne@69: 'iterables of\n' jpayne@69: ' length two). If keyword arguments are specified, the ' jpayne@69: 'dictionary\n' jpayne@69: ' is then updated with those key/value pairs: ' jpayne@69: '"d.update(red=1,\n' jpayne@69: ' blue=2)".\n' jpayne@69: '\n' jpayne@69: ' values()\n' jpayne@69: '\n' jpayne@69: ' Return a new view of the dictionary’s values. See ' jpayne@69: 'the\n' jpayne@69: ' documentation of view objects.\n' jpayne@69: '\n' jpayne@69: ' An equality comparison between one "dict.values()" ' jpayne@69: 'view and\n' jpayne@69: ' another will always return "False". This also applies ' jpayne@69: 'when\n' jpayne@69: ' comparing "dict.values()" to itself:\n' jpayne@69: '\n' jpayne@69: " >>> d = {'a': 1}\n" jpayne@69: ' >>> d.values() == d.values()\n' jpayne@69: ' False\n' jpayne@69: '\n' jpayne@69: ' Dictionaries compare equal if and only if they have the ' jpayne@69: 'same "(key,\n' jpayne@69: ' value)" pairs (regardless of ordering). Order comparisons ' jpayne@69: '(‘<’,\n' jpayne@69: ' ‘<=’, ‘>=’, ‘>’) raise "TypeError".\n' jpayne@69: '\n' jpayne@69: ' Dictionaries preserve insertion order. Note that ' jpayne@69: 'updating a key\n' jpayne@69: ' does not affect the order. Keys added after deletion are ' jpayne@69: 'inserted\n' jpayne@69: ' at the end.\n' jpayne@69: '\n' jpayne@69: ' >>> d = {"one": 1, "two": 2, "three": 3, "four": 4}\n' jpayne@69: ' >>> d\n' jpayne@69: " {'one': 1, 'two': 2, 'three': 3, 'four': 4}\n" jpayne@69: ' >>> list(d)\n' jpayne@69: " ['one', 'two', 'three', 'four']\n" jpayne@69: ' >>> list(d.values())\n' jpayne@69: ' [1, 2, 3, 4]\n' jpayne@69: ' >>> d["one"] = 42\n' jpayne@69: ' >>> d\n' jpayne@69: " {'one': 42, 'two': 2, 'three': 3, 'four': 4}\n" jpayne@69: ' >>> del d["two"]\n' jpayne@69: ' >>> d["two"] = None\n' jpayne@69: ' >>> d\n' jpayne@69: " {'one': 42, 'three': 3, 'four': 4, 'two': None}\n" jpayne@69: '\n' jpayne@69: ' Changed in version 3.7: Dictionary order is guaranteed to ' jpayne@69: 'be\n' jpayne@69: ' insertion order. This behavior was an implementation ' jpayne@69: 'detail of\n' jpayne@69: ' CPython from 3.6.\n' jpayne@69: '\n' jpayne@69: ' Dictionaries and dictionary views are reversible.\n' jpayne@69: '\n' jpayne@69: ' >>> d = {"one": 1, "two": 2, "three": 3, "four": 4}\n' jpayne@69: ' >>> d\n' jpayne@69: " {'one': 1, 'two': 2, 'three': 3, 'four': 4}\n" jpayne@69: ' >>> list(reversed(d))\n' jpayne@69: " ['four', 'three', 'two', 'one']\n" jpayne@69: ' >>> list(reversed(d.values()))\n' jpayne@69: ' [4, 3, 2, 1]\n' jpayne@69: ' >>> list(reversed(d.items()))\n' jpayne@69: " [('four', 4), ('three', 3), ('two', 2), ('one', 1)]\n" jpayne@69: '\n' jpayne@69: ' Changed in version 3.8: Dictionaries are now reversible.\n' jpayne@69: '\n' jpayne@69: 'See also: "types.MappingProxyType" can be used to create a ' jpayne@69: 'read-only\n' jpayne@69: ' view of a "dict".\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Dictionary view objects\n' jpayne@69: '=======================\n' jpayne@69: '\n' jpayne@69: 'The objects returned by "dict.keys()", "dict.values()" and\n' jpayne@69: '"dict.items()" are *view objects*. They provide a dynamic ' jpayne@69: 'view on the\n' jpayne@69: 'dictionary’s entries, which means that when the dictionary ' jpayne@69: 'changes,\n' jpayne@69: 'the view reflects these changes.\n' jpayne@69: '\n' jpayne@69: 'Dictionary views can be iterated over to yield their ' jpayne@69: 'respective data,\n' jpayne@69: 'and support membership tests:\n' jpayne@69: '\n' jpayne@69: 'len(dictview)\n' jpayne@69: '\n' jpayne@69: ' Return the number of entries in the dictionary.\n' jpayne@69: '\n' jpayne@69: 'iter(dictview)\n' jpayne@69: '\n' jpayne@69: ' Return an iterator over the keys, values or items ' jpayne@69: '(represented as\n' jpayne@69: ' tuples of "(key, value)") in the dictionary.\n' jpayne@69: '\n' jpayne@69: ' Keys and values are iterated over in insertion order. ' jpayne@69: 'This allows\n' jpayne@69: ' the creation of "(value, key)" pairs using "zip()": ' jpayne@69: '"pairs =\n' jpayne@69: ' zip(d.values(), d.keys())". Another way to create the ' jpayne@69: 'same list is\n' jpayne@69: ' "pairs = [(v, k) for (k, v) in d.items()]".\n' jpayne@69: '\n' jpayne@69: ' Iterating views while adding or deleting entries in the ' jpayne@69: 'dictionary\n' jpayne@69: ' may raise a "RuntimeError" or fail to iterate over all ' jpayne@69: 'entries.\n' jpayne@69: '\n' jpayne@69: ' Changed in version 3.7: Dictionary order is guaranteed to ' jpayne@69: 'be\n' jpayne@69: ' insertion order.\n' jpayne@69: '\n' jpayne@69: 'x in dictview\n' jpayne@69: '\n' jpayne@69: ' Return "True" if *x* is in the underlying dictionary’s ' jpayne@69: 'keys, values\n' jpayne@69: ' or items (in the latter case, *x* should be a "(key, ' jpayne@69: 'value)"\n' jpayne@69: ' tuple).\n' jpayne@69: '\n' jpayne@69: 'reversed(dictview)\n' jpayne@69: '\n' jpayne@69: ' Return a reverse iterator over the keys, values or items ' jpayne@69: 'of the\n' jpayne@69: ' dictionary. The view will be iterated in reverse order of ' jpayne@69: 'the\n' jpayne@69: ' insertion.\n' jpayne@69: '\n' jpayne@69: ' Changed in version 3.8: Dictionary views are now ' jpayne@69: 'reversible.\n' jpayne@69: '\n' jpayne@69: 'Keys views are set-like since their entries are unique and ' jpayne@69: 'hashable.\n' jpayne@69: 'If all values are hashable, so that "(key, value)" pairs are ' jpayne@69: 'unique\n' jpayne@69: 'and hashable, then the items view is also set-like. (Values ' jpayne@69: 'views are\n' jpayne@69: 'not treated as set-like since the entries are generally not ' jpayne@69: 'unique.)\n' jpayne@69: 'For set-like views, all of the operations defined for the ' jpayne@69: 'abstract\n' jpayne@69: 'base class "collections.abc.Set" are available (for example, ' jpayne@69: '"==",\n' jpayne@69: '"<", or "^").\n' jpayne@69: '\n' jpayne@69: 'An example of dictionary view usage:\n' jpayne@69: '\n' jpayne@69: " >>> dishes = {'eggs': 2, 'sausage': 1, 'bacon': 1, " jpayne@69: "'spam': 500}\n" jpayne@69: ' >>> keys = dishes.keys()\n' jpayne@69: ' >>> values = dishes.values()\n' jpayne@69: '\n' jpayne@69: ' >>> # iteration\n' jpayne@69: ' >>> n = 0\n' jpayne@69: ' >>> for val in values:\n' jpayne@69: ' ... n += val\n' jpayne@69: ' >>> print(n)\n' jpayne@69: ' 504\n' jpayne@69: '\n' jpayne@69: ' >>> # keys and values are iterated over in the same order ' jpayne@69: '(insertion order)\n' jpayne@69: ' >>> list(keys)\n' jpayne@69: " ['eggs', 'sausage', 'bacon', 'spam']\n" jpayne@69: ' >>> list(values)\n' jpayne@69: ' [2, 1, 1, 500]\n' jpayne@69: '\n' jpayne@69: ' >>> # view objects are dynamic and reflect dict changes\n' jpayne@69: " >>> del dishes['eggs']\n" jpayne@69: " >>> del dishes['sausage']\n" jpayne@69: ' >>> list(keys)\n' jpayne@69: " ['bacon', 'spam']\n" jpayne@69: '\n' jpayne@69: ' >>> # set operations\n' jpayne@69: " >>> keys & {'eggs', 'bacon', 'salad'}\n" jpayne@69: " {'bacon'}\n" jpayne@69: " >>> keys ^ {'sausage', 'juice'}\n" jpayne@69: " {'juice', 'sausage', 'bacon', 'spam'}\n", jpayne@69: 'typesmethods': 'Methods\n' jpayne@69: '*******\n' jpayne@69: '\n' jpayne@69: 'Methods are functions that are called using the attribute ' jpayne@69: 'notation.\n' jpayne@69: 'There are two flavors: built-in methods (such as "append()" ' jpayne@69: 'on lists)\n' jpayne@69: 'and class instance methods. Built-in methods are described ' jpayne@69: 'with the\n' jpayne@69: 'types that support them.\n' jpayne@69: '\n' jpayne@69: 'If you access a method (a function defined in a class ' jpayne@69: 'namespace)\n' jpayne@69: 'through an instance, you get a special object: a *bound ' jpayne@69: 'method* (also\n' jpayne@69: 'called *instance method*) object. When called, it will add ' jpayne@69: 'the "self"\n' jpayne@69: 'argument to the argument list. Bound methods have two ' jpayne@69: 'special read-\n' jpayne@69: 'only attributes: "m.__self__" is the object on which the ' jpayne@69: 'method\n' jpayne@69: 'operates, and "m.__func__" is the function implementing the ' jpayne@69: 'method.\n' jpayne@69: 'Calling "m(arg-1, arg-2, ..., arg-n)" is completely ' jpayne@69: 'equivalent to\n' jpayne@69: 'calling "m.__func__(m.__self__, arg-1, arg-2, ..., arg-n)".\n' jpayne@69: '\n' jpayne@69: 'Like function objects, bound method objects support getting ' jpayne@69: 'arbitrary\n' jpayne@69: 'attributes. However, since method attributes are actually ' jpayne@69: 'stored on\n' jpayne@69: 'the underlying function object ("meth.__func__"), setting ' jpayne@69: 'method\n' jpayne@69: 'attributes on bound methods is disallowed. Attempting to ' jpayne@69: 'set an\n' jpayne@69: 'attribute on a method results in an "AttributeError" being ' jpayne@69: 'raised. In\n' jpayne@69: 'order to set a method attribute, you need to explicitly set ' jpayne@69: 'it on the\n' jpayne@69: 'underlying function object:\n' jpayne@69: '\n' jpayne@69: ' >>> class C:\n' jpayne@69: ' ... def method(self):\n' jpayne@69: ' ... pass\n' jpayne@69: ' ...\n' jpayne@69: ' >>> c = C()\n' jpayne@69: " >>> c.method.whoami = 'my name is method' # can't set on " jpayne@69: 'the method\n' jpayne@69: ' Traceback (most recent call last):\n' jpayne@69: ' File "", line 1, in \n' jpayne@69: " AttributeError: 'method' object has no attribute " jpayne@69: "'whoami'\n" jpayne@69: " >>> c.method.__func__.whoami = 'my name is method'\n" jpayne@69: ' >>> c.method.whoami\n' jpayne@69: " 'my name is method'\n" jpayne@69: '\n' jpayne@69: 'See The standard type hierarchy for more information.\n', jpayne@69: 'typesmodules': 'Modules\n' jpayne@69: '*******\n' jpayne@69: '\n' jpayne@69: 'The only special operation on a module is attribute access: ' jpayne@69: '"m.name",\n' jpayne@69: 'where *m* is a module and *name* accesses a name defined in ' jpayne@69: '*m*’s\n' jpayne@69: 'symbol table. Module attributes can be assigned to. (Note ' jpayne@69: 'that the\n' jpayne@69: '"import" statement is not, strictly speaking, an operation ' jpayne@69: 'on a module\n' jpayne@69: 'object; "import foo" does not require a module object named ' jpayne@69: '*foo* to\n' jpayne@69: 'exist, rather it requires an (external) *definition* for a ' jpayne@69: 'module\n' jpayne@69: 'named *foo* somewhere.)\n' jpayne@69: '\n' jpayne@69: 'A special attribute of every module is "__dict__". This is ' jpayne@69: 'the\n' jpayne@69: 'dictionary containing the module’s symbol table. Modifying ' jpayne@69: 'this\n' jpayne@69: 'dictionary will actually change the module’s symbol table, ' jpayne@69: 'but direct\n' jpayne@69: 'assignment to the "__dict__" attribute is not possible (you ' jpayne@69: 'can write\n' jpayne@69: '"m.__dict__[\'a\'] = 1", which defines "m.a" to be "1", but ' jpayne@69: 'you can’t\n' jpayne@69: 'write "m.__dict__ = {}"). Modifying "__dict__" directly is ' jpayne@69: 'not\n' jpayne@69: 'recommended.\n' jpayne@69: '\n' jpayne@69: 'Modules built into the interpreter are written like this: ' jpayne@69: '"". If loaded from a file, they are ' jpayne@69: 'written as\n' jpayne@69: '"".\n', jpayne@69: 'typesseq': 'Sequence Types — "list", "tuple", "range"\n' jpayne@69: '*****************************************\n' jpayne@69: '\n' jpayne@69: 'There are three basic sequence types: lists, tuples, and range\n' jpayne@69: 'objects. Additional sequence types tailored for processing of ' jpayne@69: 'binary\n' jpayne@69: 'data and text strings are described in dedicated sections.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Common Sequence Operations\n' jpayne@69: '==========================\n' jpayne@69: '\n' jpayne@69: 'The operations in the following table are supported by most ' jpayne@69: 'sequence\n' jpayne@69: 'types, both mutable and immutable. The ' jpayne@69: '"collections.abc.Sequence" ABC\n' jpayne@69: 'is provided to make it easier to correctly implement these ' jpayne@69: 'operations\n' jpayne@69: 'on custom sequence types.\n' jpayne@69: '\n' jpayne@69: 'This table lists the sequence operations sorted in ascending ' jpayne@69: 'priority.\n' jpayne@69: 'In the table, *s* and *t* are sequences of the same type, *n*, ' jpayne@69: '*i*,\n' jpayne@69: '*j* and *k* are integers and *x* is an arbitrary object that ' jpayne@69: 'meets any\n' jpayne@69: 'type and value restrictions imposed by *s*.\n' jpayne@69: '\n' jpayne@69: 'The "in" and "not in" operations have the same priorities as ' jpayne@69: 'the\n' jpayne@69: 'comparison operations. The "+" (concatenation) and "*" ' jpayne@69: '(repetition)\n' jpayne@69: 'operations have the same priority as the corresponding numeric\n' jpayne@69: 'operations. [3]\n' jpayne@69: '\n' jpayne@69: '+----------------------------+----------------------------------+------------+\n' jpayne@69: '| Operation | Result ' jpayne@69: '| Notes |\n' jpayne@69: '|============================|==================================|============|\n' jpayne@69: '| "x in s" | "True" if an item of *s* is ' jpayne@69: '| (1) |\n' jpayne@69: '| | equal to *x*, else "False" ' jpayne@69: '| |\n' jpayne@69: '+----------------------------+----------------------------------+------------+\n' jpayne@69: '| "x not in s" | "False" if an item of *s* is ' jpayne@69: '| (1) |\n' jpayne@69: '| | equal to *x*, else "True" ' jpayne@69: '| |\n' jpayne@69: '+----------------------------+----------------------------------+------------+\n' jpayne@69: '| "s + t" | the concatenation of *s* and *t* ' jpayne@69: '| (6)(7) |\n' jpayne@69: '+----------------------------+----------------------------------+------------+\n' jpayne@69: '| "s * n" or "n * s" | equivalent to adding *s* to ' jpayne@69: '| (2)(7) |\n' jpayne@69: '| | itself *n* times ' jpayne@69: '| |\n' jpayne@69: '+----------------------------+----------------------------------+------------+\n' jpayne@69: '| "s[i]" | *i*th item of *s*, origin 0 ' jpayne@69: '| (3) |\n' jpayne@69: '+----------------------------+----------------------------------+------------+\n' jpayne@69: '| "s[i:j]" | slice of *s* from *i* to *j* ' jpayne@69: '| (3)(4) |\n' jpayne@69: '+----------------------------+----------------------------------+------------+\n' jpayne@69: '| "s[i:j:k]" | slice of *s* from *i* to *j* ' jpayne@69: '| (3)(5) |\n' jpayne@69: '| | with step *k* ' jpayne@69: '| |\n' jpayne@69: '+----------------------------+----------------------------------+------------+\n' jpayne@69: '| "len(s)" | length of *s* ' jpayne@69: '| |\n' jpayne@69: '+----------------------------+----------------------------------+------------+\n' jpayne@69: '| "min(s)" | smallest item of *s* ' jpayne@69: '| |\n' jpayne@69: '+----------------------------+----------------------------------+------------+\n' jpayne@69: '| "max(s)" | largest item of *s* ' jpayne@69: '| |\n' jpayne@69: '+----------------------------+----------------------------------+------------+\n' jpayne@69: '| "s.index(x[, i[, j]])" | index of the first occurrence of ' jpayne@69: '| (8) |\n' jpayne@69: '| | *x* in *s* (at or after index ' jpayne@69: '| |\n' jpayne@69: '| | *i* and before index *j*) ' jpayne@69: '| |\n' jpayne@69: '+----------------------------+----------------------------------+------------+\n' jpayne@69: '| "s.count(x)" | total number of occurrences of ' jpayne@69: '| |\n' jpayne@69: '| | *x* in *s* ' jpayne@69: '| |\n' jpayne@69: '+----------------------------+----------------------------------+------------+\n' jpayne@69: '\n' jpayne@69: 'Sequences of the same type also support comparisons. In ' jpayne@69: 'particular,\n' jpayne@69: 'tuples and lists are compared lexicographically by comparing\n' jpayne@69: 'corresponding elements. This means that to compare equal, every\n' jpayne@69: 'element must compare equal and the two sequences must be of the ' jpayne@69: 'same\n' jpayne@69: 'type and have the same length. (For full details see ' jpayne@69: 'Comparisons in\n' jpayne@69: 'the language reference.)\n' jpayne@69: '\n' jpayne@69: 'Notes:\n' jpayne@69: '\n' jpayne@69: '1. While the "in" and "not in" operations are used only for ' jpayne@69: 'simple\n' jpayne@69: ' containment testing in the general case, some specialised ' jpayne@69: 'sequences\n' jpayne@69: ' (such as "str", "bytes" and "bytearray") also use them for\n' jpayne@69: ' subsequence testing:\n' jpayne@69: '\n' jpayne@69: ' >>> "gg" in "eggs"\n' jpayne@69: ' True\n' jpayne@69: '\n' jpayne@69: '2. Values of *n* less than "0" are treated as "0" (which yields ' jpayne@69: 'an\n' jpayne@69: ' empty sequence of the same type as *s*). Note that items in ' jpayne@69: 'the\n' jpayne@69: ' sequence *s* are not copied; they are referenced multiple ' jpayne@69: 'times.\n' jpayne@69: ' This often haunts new Python programmers; consider:\n' jpayne@69: '\n' jpayne@69: ' >>> lists = [[]] * 3\n' jpayne@69: ' >>> lists\n' jpayne@69: ' [[], [], []]\n' jpayne@69: ' >>> lists[0].append(3)\n' jpayne@69: ' >>> lists\n' jpayne@69: ' [[3], [3], [3]]\n' jpayne@69: '\n' jpayne@69: ' What has happened is that "[[]]" is a one-element list ' jpayne@69: 'containing\n' jpayne@69: ' an empty list, so all three elements of "[[]] * 3" are ' jpayne@69: 'references\n' jpayne@69: ' to this single empty list. Modifying any of the elements of\n' jpayne@69: ' "lists" modifies this single list. You can create a list of\n' jpayne@69: ' different lists this way:\n' jpayne@69: '\n' jpayne@69: ' >>> lists = [[] for i in range(3)]\n' jpayne@69: ' >>> lists[0].append(3)\n' jpayne@69: ' >>> lists[1].append(5)\n' jpayne@69: ' >>> lists[2].append(7)\n' jpayne@69: ' >>> lists\n' jpayne@69: ' [[3], [5], [7]]\n' jpayne@69: '\n' jpayne@69: ' Further explanation is available in the FAQ entry How do I ' jpayne@69: 'create a\n' jpayne@69: ' multidimensional list?.\n' jpayne@69: '\n' jpayne@69: '3. If *i* or *j* is negative, the index is relative to the end ' jpayne@69: 'of\n' jpayne@69: ' sequence *s*: "len(s) + i" or "len(s) + j" is substituted. ' jpayne@69: 'But\n' jpayne@69: ' note that "-0" is still "0".\n' jpayne@69: '\n' jpayne@69: '4. The slice of *s* from *i* to *j* is defined as the sequence ' jpayne@69: 'of\n' jpayne@69: ' items with index *k* such that "i <= k < j". If *i* or *j* ' jpayne@69: 'is\n' jpayne@69: ' greater than "len(s)", use "len(s)". If *i* is omitted or ' jpayne@69: '"None",\n' jpayne@69: ' use "0". If *j* is omitted or "None", use "len(s)". If *i* ' jpayne@69: 'is\n' jpayne@69: ' greater than or equal to *j*, the slice is empty.\n' jpayne@69: '\n' jpayne@69: '5. The slice of *s* from *i* to *j* with step *k* is defined as ' jpayne@69: 'the\n' jpayne@69: ' sequence of items with index "x = i + n*k" such that "0 <= n ' jpayne@69: '<\n' jpayne@69: ' (j-i)/k". In other words, the indices are "i", "i+k", ' jpayne@69: '"i+2*k",\n' jpayne@69: ' "i+3*k" and so on, stopping when *j* is reached (but never\n' jpayne@69: ' including *j*). When *k* is positive, *i* and *j* are ' jpayne@69: 'reduced to\n' jpayne@69: ' "len(s)" if they are greater. When *k* is negative, *i* and ' jpayne@69: '*j* are\n' jpayne@69: ' reduced to "len(s) - 1" if they are greater. If *i* or *j* ' jpayne@69: 'are\n' jpayne@69: ' omitted or "None", they become “end” values (which end ' jpayne@69: 'depends on\n' jpayne@69: ' the sign of *k*). Note, *k* cannot be zero. If *k* is ' jpayne@69: '"None", it\n' jpayne@69: ' is treated like "1".\n' jpayne@69: '\n' jpayne@69: '6. Concatenating immutable sequences always results in a new\n' jpayne@69: ' object. This means that building up a sequence by repeated\n' jpayne@69: ' concatenation will have a quadratic runtime cost in the ' jpayne@69: 'total\n' jpayne@69: ' sequence length. To get a linear runtime cost, you must ' jpayne@69: 'switch to\n' jpayne@69: ' one of the alternatives below:\n' jpayne@69: '\n' jpayne@69: ' * if concatenating "str" objects, you can build a list and ' jpayne@69: 'use\n' jpayne@69: ' "str.join()" at the end or else write to an "io.StringIO"\n' jpayne@69: ' instance and retrieve its value when complete\n' jpayne@69: '\n' jpayne@69: ' * if concatenating "bytes" objects, you can similarly use\n' jpayne@69: ' "bytes.join()" or "io.BytesIO", or you can do in-place\n' jpayne@69: ' concatenation with a "bytearray" object. "bytearray" ' jpayne@69: 'objects are\n' jpayne@69: ' mutable and have an efficient overallocation mechanism\n' jpayne@69: '\n' jpayne@69: ' * if concatenating "tuple" objects, extend a "list" instead\n' jpayne@69: '\n' jpayne@69: ' * for other types, investigate the relevant class ' jpayne@69: 'documentation\n' jpayne@69: '\n' jpayne@69: '7. Some sequence types (such as "range") only support item\n' jpayne@69: ' sequences that follow specific patterns, and hence don’t ' jpayne@69: 'support\n' jpayne@69: ' sequence concatenation or repetition.\n' jpayne@69: '\n' jpayne@69: '8. "index" raises "ValueError" when *x* is not found in *s*. ' jpayne@69: 'Not\n' jpayne@69: ' all implementations support passing the additional arguments ' jpayne@69: '*i*\n' jpayne@69: ' and *j*. These arguments allow efficient searching of ' jpayne@69: 'subsections\n' jpayne@69: ' of the sequence. Passing the extra arguments is roughly ' jpayne@69: 'equivalent\n' jpayne@69: ' to using "s[i:j].index(x)", only without copying any data and ' jpayne@69: 'with\n' jpayne@69: ' the returned index being relative to the start of the ' jpayne@69: 'sequence\n' jpayne@69: ' rather than the start of the slice.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Immutable Sequence Types\n' jpayne@69: '========================\n' jpayne@69: '\n' jpayne@69: 'The only operation that immutable sequence types generally ' jpayne@69: 'implement\n' jpayne@69: 'that is not also implemented by mutable sequence types is ' jpayne@69: 'support for\n' jpayne@69: 'the "hash()" built-in.\n' jpayne@69: '\n' jpayne@69: 'This support allows immutable sequences, such as "tuple" ' jpayne@69: 'instances, to\n' jpayne@69: 'be used as "dict" keys and stored in "set" and "frozenset" ' jpayne@69: 'instances.\n' jpayne@69: '\n' jpayne@69: 'Attempting to hash an immutable sequence that contains ' jpayne@69: 'unhashable\n' jpayne@69: 'values will result in "TypeError".\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Mutable Sequence Types\n' jpayne@69: '======================\n' jpayne@69: '\n' jpayne@69: 'The operations in the following table are defined on mutable ' jpayne@69: 'sequence\n' jpayne@69: 'types. The "collections.abc.MutableSequence" ABC is provided to ' jpayne@69: 'make\n' jpayne@69: 'it easier to correctly implement these operations on custom ' jpayne@69: 'sequence\n' jpayne@69: 'types.\n' jpayne@69: '\n' jpayne@69: 'In the table *s* is an instance of a mutable sequence type, *t* ' jpayne@69: 'is any\n' jpayne@69: 'iterable object and *x* is an arbitrary object that meets any ' jpayne@69: 'type and\n' jpayne@69: 'value restrictions imposed by *s* (for example, "bytearray" ' jpayne@69: 'only\n' jpayne@69: 'accepts integers that meet the value restriction "0 <= x <= ' jpayne@69: '255").\n' jpayne@69: '\n' jpayne@69: '+--------------------------------+----------------------------------+-----------------------+\n' jpayne@69: '| Operation | ' jpayne@69: 'Result | Notes |\n' jpayne@69: '|================================|==================================|=======================|\n' jpayne@69: '| "s[i] = x" | item *i* of *s* is replaced ' jpayne@69: 'by | |\n' jpayne@69: '| | ' jpayne@69: '*x* | |\n' jpayne@69: '+--------------------------------+----------------------------------+-----------------------+\n' jpayne@69: '| "s[i:j] = t" | slice of *s* from *i* to *j* ' jpayne@69: 'is | |\n' jpayne@69: '| | replaced by the contents of ' jpayne@69: 'the | |\n' jpayne@69: '| | iterable ' jpayne@69: '*t* | |\n' jpayne@69: '+--------------------------------+----------------------------------+-----------------------+\n' jpayne@69: '| "del s[i:j]" | same as "s[i:j] = ' jpayne@69: '[]" | |\n' jpayne@69: '+--------------------------------+----------------------------------+-----------------------+\n' jpayne@69: '| "s[i:j:k] = t" | the elements of "s[i:j:k]" ' jpayne@69: 'are | (1) |\n' jpayne@69: '| | replaced by those of ' jpayne@69: '*t* | |\n' jpayne@69: '+--------------------------------+----------------------------------+-----------------------+\n' jpayne@69: '| "del s[i:j:k]" | removes the elements ' jpayne@69: 'of | |\n' jpayne@69: '| | "s[i:j:k]" from the ' jpayne@69: 'list | |\n' jpayne@69: '+--------------------------------+----------------------------------+-----------------------+\n' jpayne@69: '| "s.append(x)" | appends *x* to the end of ' jpayne@69: 'the | |\n' jpayne@69: '| | sequence (same ' jpayne@69: 'as | |\n' jpayne@69: '| | "s[len(s):len(s)] = ' jpayne@69: '[x]") | |\n' jpayne@69: '+--------------------------------+----------------------------------+-----------------------+\n' jpayne@69: '| "s.clear()" | removes all items from *s* ' jpayne@69: '(same | (5) |\n' jpayne@69: '| | as "del ' jpayne@69: 's[:]") | |\n' jpayne@69: '+--------------------------------+----------------------------------+-----------------------+\n' jpayne@69: '| "s.copy()" | creates a shallow copy of ' jpayne@69: '*s* | (5) |\n' jpayne@69: '| | (same as ' jpayne@69: '"s[:]") | |\n' jpayne@69: '+--------------------------------+----------------------------------+-----------------------+\n' jpayne@69: '| "s.extend(t)" or "s += t" | extends *s* with the contents ' jpayne@69: 'of | |\n' jpayne@69: '| | *t* (for the most part the ' jpayne@69: 'same | |\n' jpayne@69: '| | as "s[len(s):len(s)] = ' jpayne@69: 't") | |\n' jpayne@69: '+--------------------------------+----------------------------------+-----------------------+\n' jpayne@69: '| "s *= n" | updates *s* with its ' jpayne@69: 'contents | (6) |\n' jpayne@69: '| | repeated *n* ' jpayne@69: 'times | |\n' jpayne@69: '+--------------------------------+----------------------------------+-----------------------+\n' jpayne@69: '| "s.insert(i, x)" | inserts *x* into *s* at ' jpayne@69: 'the | |\n' jpayne@69: '| | index given by *i* (same ' jpayne@69: 'as | |\n' jpayne@69: '| | "s[i:i] = ' jpayne@69: '[x]") | |\n' jpayne@69: '+--------------------------------+----------------------------------+-----------------------+\n' jpayne@69: '| "s.pop([i])" | retrieves the item at *i* ' jpayne@69: 'and | (2) |\n' jpayne@69: '| | also removes it from ' jpayne@69: '*s* | |\n' jpayne@69: '+--------------------------------+----------------------------------+-----------------------+\n' jpayne@69: '| "s.remove(x)" | remove the first item from ' jpayne@69: '*s* | (3) |\n' jpayne@69: '| | where "s[i]" is equal to ' jpayne@69: '*x* | |\n' jpayne@69: '+--------------------------------+----------------------------------+-----------------------+\n' jpayne@69: '| "s.reverse()" | reverses the items of *s* ' jpayne@69: 'in | (4) |\n' jpayne@69: '| | ' jpayne@69: 'place | |\n' jpayne@69: '+--------------------------------+----------------------------------+-----------------------+\n' jpayne@69: '\n' jpayne@69: 'Notes:\n' jpayne@69: '\n' jpayne@69: '1. *t* must have the same length as the slice it is replacing.\n' jpayne@69: '\n' jpayne@69: '2. The optional argument *i* defaults to "-1", so that by ' jpayne@69: 'default\n' jpayne@69: ' the last item is removed and returned.\n' jpayne@69: '\n' jpayne@69: '3. "remove()" raises "ValueError" when *x* is not found in *s*.\n' jpayne@69: '\n' jpayne@69: '4. The "reverse()" method modifies the sequence in place for\n' jpayne@69: ' economy of space when reversing a large sequence. To remind ' jpayne@69: 'users\n' jpayne@69: ' that it operates by side effect, it does not return the ' jpayne@69: 'reversed\n' jpayne@69: ' sequence.\n' jpayne@69: '\n' jpayne@69: '5. "clear()" and "copy()" are included for consistency with the\n' jpayne@69: ' interfaces of mutable containers that don’t support slicing\n' jpayne@69: ' operations (such as "dict" and "set"). "copy()" is not part ' jpayne@69: 'of the\n' jpayne@69: ' "collections.abc.MutableSequence" ABC, but most concrete ' jpayne@69: 'mutable\n' jpayne@69: ' sequence classes provide it.\n' jpayne@69: '\n' jpayne@69: ' New in version 3.3: "clear()" and "copy()" methods.\n' jpayne@69: '\n' jpayne@69: '6. The value *n* is an integer, or an object implementing\n' jpayne@69: ' "__index__()". Zero and negative values of *n* clear the ' jpayne@69: 'sequence.\n' jpayne@69: ' Items in the sequence are not copied; they are referenced ' jpayne@69: 'multiple\n' jpayne@69: ' times, as explained for "s * n" under Common Sequence ' jpayne@69: 'Operations.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Lists\n' jpayne@69: '=====\n' jpayne@69: '\n' jpayne@69: 'Lists are mutable sequences, typically used to store collections ' jpayne@69: 'of\n' jpayne@69: 'homogeneous items (where the precise degree of similarity will ' jpayne@69: 'vary by\n' jpayne@69: 'application).\n' jpayne@69: '\n' jpayne@69: 'class list([iterable])\n' jpayne@69: '\n' jpayne@69: ' Lists may be constructed in several ways:\n' jpayne@69: '\n' jpayne@69: ' * Using a pair of square brackets to denote the empty list: ' jpayne@69: '"[]"\n' jpayne@69: '\n' jpayne@69: ' * Using square brackets, separating items with commas: ' jpayne@69: '"[a]",\n' jpayne@69: ' "[a, b, c]"\n' jpayne@69: '\n' jpayne@69: ' * Using a list comprehension: "[x for x in iterable]"\n' jpayne@69: '\n' jpayne@69: ' * Using the type constructor: "list()" or "list(iterable)"\n' jpayne@69: '\n' jpayne@69: ' The constructor builds a list whose items are the same and in ' jpayne@69: 'the\n' jpayne@69: ' same order as *iterable*’s items. *iterable* may be either ' jpayne@69: 'a\n' jpayne@69: ' sequence, a container that supports iteration, or an ' jpayne@69: 'iterator\n' jpayne@69: ' object. If *iterable* is already a list, a copy is made and\n' jpayne@69: ' returned, similar to "iterable[:]". For example, ' jpayne@69: '"list(\'abc\')"\n' jpayne@69: ' returns "[\'a\', \'b\', \'c\']" and "list( (1, 2, 3) )" ' jpayne@69: 'returns "[1, 2,\n' jpayne@69: ' 3]". If no argument is given, the constructor creates a new ' jpayne@69: 'empty\n' jpayne@69: ' list, "[]".\n' jpayne@69: '\n' jpayne@69: ' Many other operations also produce lists, including the ' jpayne@69: '"sorted()"\n' jpayne@69: ' built-in.\n' jpayne@69: '\n' jpayne@69: ' Lists implement all of the common and mutable sequence ' jpayne@69: 'operations.\n' jpayne@69: ' Lists also provide the following additional method:\n' jpayne@69: '\n' jpayne@69: ' sort(*, key=None, reverse=False)\n' jpayne@69: '\n' jpayne@69: ' This method sorts the list in place, using only "<" ' jpayne@69: 'comparisons\n' jpayne@69: ' between items. Exceptions are not suppressed - if any ' jpayne@69: 'comparison\n' jpayne@69: ' operations fail, the entire sort operation will fail (and ' jpayne@69: 'the\n' jpayne@69: ' list will likely be left in a partially modified state).\n' jpayne@69: '\n' jpayne@69: ' "sort()" accepts two arguments that can only be passed by\n' jpayne@69: ' keyword (keyword-only arguments):\n' jpayne@69: '\n' jpayne@69: ' *key* specifies a function of one argument that is used ' jpayne@69: 'to\n' jpayne@69: ' extract a comparison key from each list element (for ' jpayne@69: 'example,\n' jpayne@69: ' "key=str.lower"). The key corresponding to each item in ' jpayne@69: 'the list\n' jpayne@69: ' is calculated once and then used for the entire sorting ' jpayne@69: 'process.\n' jpayne@69: ' The default value of "None" means that list items are ' jpayne@69: 'sorted\n' jpayne@69: ' directly without calculating a separate key value.\n' jpayne@69: '\n' jpayne@69: ' The "functools.cmp_to_key()" utility is available to ' jpayne@69: 'convert a\n' jpayne@69: ' 2.x style *cmp* function to a *key* function.\n' jpayne@69: '\n' jpayne@69: ' *reverse* is a boolean value. If set to "True", then the ' jpayne@69: 'list\n' jpayne@69: ' elements are sorted as if each comparison were reversed.\n' jpayne@69: '\n' jpayne@69: ' This method modifies the sequence in place for economy of ' jpayne@69: 'space\n' jpayne@69: ' when sorting a large sequence. To remind users that it ' jpayne@69: 'operates\n' jpayne@69: ' by side effect, it does not return the sorted sequence ' jpayne@69: '(use\n' jpayne@69: ' "sorted()" to explicitly request a new sorted list ' jpayne@69: 'instance).\n' jpayne@69: '\n' jpayne@69: ' The "sort()" method is guaranteed to be stable. A sort ' jpayne@69: 'is\n' jpayne@69: ' stable if it guarantees not to change the relative order ' jpayne@69: 'of\n' jpayne@69: ' elements that compare equal — this is helpful for sorting ' jpayne@69: 'in\n' jpayne@69: ' multiple passes (for example, sort by department, then by ' jpayne@69: 'salary\n' jpayne@69: ' grade).\n' jpayne@69: '\n' jpayne@69: ' For sorting examples and a brief sorting tutorial, see ' jpayne@69: 'Sorting\n' jpayne@69: ' HOW TO.\n' jpayne@69: '\n' jpayne@69: ' **CPython implementation detail:** While a list is being ' jpayne@69: 'sorted,\n' jpayne@69: ' the effect of attempting to mutate, or even inspect, the ' jpayne@69: 'list is\n' jpayne@69: ' undefined. The C implementation of Python makes the list ' jpayne@69: 'appear\n' jpayne@69: ' empty for the duration, and raises "ValueError" if it can ' jpayne@69: 'detect\n' jpayne@69: ' that the list has been mutated during a sort.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Tuples\n' jpayne@69: '======\n' jpayne@69: '\n' jpayne@69: 'Tuples are immutable sequences, typically used to store ' jpayne@69: 'collections of\n' jpayne@69: 'heterogeneous data (such as the 2-tuples produced by the ' jpayne@69: '"enumerate()"\n' jpayne@69: 'built-in). Tuples are also used for cases where an immutable ' jpayne@69: 'sequence\n' jpayne@69: 'of homogeneous data is needed (such as allowing storage in a ' jpayne@69: '"set" or\n' jpayne@69: '"dict" instance).\n' jpayne@69: '\n' jpayne@69: 'class tuple([iterable])\n' jpayne@69: '\n' jpayne@69: ' Tuples may be constructed in a number of ways:\n' jpayne@69: '\n' jpayne@69: ' * Using a pair of parentheses to denote the empty tuple: ' jpayne@69: '"()"\n' jpayne@69: '\n' jpayne@69: ' * Using a trailing comma for a singleton tuple: "a," or ' jpayne@69: '"(a,)"\n' jpayne@69: '\n' jpayne@69: ' * Separating items with commas: "a, b, c" or "(a, b, c)"\n' jpayne@69: '\n' jpayne@69: ' * Using the "tuple()" built-in: "tuple()" or ' jpayne@69: '"tuple(iterable)"\n' jpayne@69: '\n' jpayne@69: ' The constructor builds a tuple whose items are the same and ' jpayne@69: 'in the\n' jpayne@69: ' same order as *iterable*’s items. *iterable* may be either ' jpayne@69: 'a\n' jpayne@69: ' sequence, a container that supports iteration, or an ' jpayne@69: 'iterator\n' jpayne@69: ' object. If *iterable* is already a tuple, it is returned\n' jpayne@69: ' unchanged. For example, "tuple(\'abc\')" returns "(\'a\', ' jpayne@69: '\'b\', \'c\')"\n' jpayne@69: ' and "tuple( [1, 2, 3] )" returns "(1, 2, 3)". If no argument ' jpayne@69: 'is\n' jpayne@69: ' given, the constructor creates a new empty tuple, "()".\n' jpayne@69: '\n' jpayne@69: ' Note that it is actually the comma which makes a tuple, not ' jpayne@69: 'the\n' jpayne@69: ' parentheses. The parentheses are optional, except in the ' jpayne@69: 'empty\n' jpayne@69: ' tuple case, or when they are needed to avoid syntactic ' jpayne@69: 'ambiguity.\n' jpayne@69: ' For example, "f(a, b, c)" is a function call with three ' jpayne@69: 'arguments,\n' jpayne@69: ' while "f((a, b, c))" is a function call with a 3-tuple as the ' jpayne@69: 'sole\n' jpayne@69: ' argument.\n' jpayne@69: '\n' jpayne@69: ' Tuples implement all of the common sequence operations.\n' jpayne@69: '\n' jpayne@69: 'For heterogeneous collections of data where access by name is ' jpayne@69: 'clearer\n' jpayne@69: 'than access by index, "collections.namedtuple()" may be a more\n' jpayne@69: 'appropriate choice than a simple tuple object.\n' jpayne@69: '\n' jpayne@69: '\n' jpayne@69: 'Ranges\n' jpayne@69: '======\n' jpayne@69: '\n' jpayne@69: 'The "range" type represents an immutable sequence of numbers and ' jpayne@69: 'is\n' jpayne@69: 'commonly used for looping a specific number of times in "for" ' jpayne@69: 'loops.\n' jpayne@69: '\n' jpayne@69: 'class range(stop)\n' jpayne@69: 'class range(start, stop[, step])\n' jpayne@69: '\n' jpayne@69: ' The arguments to the range constructor must be integers ' jpayne@69: '(either\n' jpayne@69: ' built-in "int" or any object that implements the "__index__"\n' jpayne@69: ' special method). If the *step* argument is omitted, it ' jpayne@69: 'defaults to\n' jpayne@69: ' "1". If the *start* argument is omitted, it defaults to "0". ' jpayne@69: 'If\n' jpayne@69: ' *step* is zero, "ValueError" is raised.\n' jpayne@69: '\n' jpayne@69: ' For a positive *step*, the contents of a range "r" are ' jpayne@69: 'determined\n' jpayne@69: ' by the formula "r[i] = start + step*i" where "i >= 0" and ' jpayne@69: '"r[i] <\n' jpayne@69: ' stop".\n' jpayne@69: '\n' jpayne@69: ' For a negative *step*, the contents of the range are still\n' jpayne@69: ' determined by the formula "r[i] = start + step*i", but the\n' jpayne@69: ' constraints are "i >= 0" and "r[i] > stop".\n' jpayne@69: '\n' jpayne@69: ' A range object will be empty if "r[0]" does not meet the ' jpayne@69: 'value\n' jpayne@69: ' constraint. Ranges do support negative indices, but these ' jpayne@69: 'are\n' jpayne@69: ' interpreted as indexing from the end of the sequence ' jpayne@69: 'determined by\n' jpayne@69: ' the positive indices.\n' jpayne@69: '\n' jpayne@69: ' Ranges containing absolute values larger than "sys.maxsize" ' jpayne@69: 'are\n' jpayne@69: ' permitted but some features (such as "len()") may raise\n' jpayne@69: ' "OverflowError".\n' jpayne@69: '\n' jpayne@69: ' Range examples:\n' jpayne@69: '\n' jpayne@69: ' >>> list(range(10))\n' jpayne@69: ' [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]\n' jpayne@69: ' >>> list(range(1, 11))\n' jpayne@69: ' [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]\n' jpayne@69: ' >>> list(range(0, 30, 5))\n' jpayne@69: ' [0, 5, 10, 15, 20, 25]\n' jpayne@69: ' >>> list(range(0, 10, 3))\n' jpayne@69: ' [0, 3, 6, 9]\n' jpayne@69: ' >>> list(range(0, -10, -1))\n' jpayne@69: ' [0, -1, -2, -3, -4, -5, -6, -7, -8, -9]\n' jpayne@69: ' >>> list(range(0))\n' jpayne@69: ' []\n' jpayne@69: ' >>> list(range(1, 0))\n' jpayne@69: ' []\n' jpayne@69: '\n' jpayne@69: ' Ranges implement all of the common sequence operations ' jpayne@69: 'except\n' jpayne@69: ' concatenation and repetition (due to the fact that range ' jpayne@69: 'objects\n' jpayne@69: ' can only represent sequences that follow a strict pattern ' jpayne@69: 'and\n' jpayne@69: ' repetition and concatenation will usually violate that ' jpayne@69: 'pattern).\n' jpayne@69: '\n' jpayne@69: ' start\n' jpayne@69: '\n' jpayne@69: ' The value of the *start* parameter (or "0" if the ' jpayne@69: 'parameter was\n' jpayne@69: ' not supplied)\n' jpayne@69: '\n' jpayne@69: ' stop\n' jpayne@69: '\n' jpayne@69: ' The value of the *stop* parameter\n' jpayne@69: '\n' jpayne@69: ' step\n' jpayne@69: '\n' jpayne@69: ' The value of the *step* parameter (or "1" if the parameter ' jpayne@69: 'was\n' jpayne@69: ' not supplied)\n' jpayne@69: '\n' jpayne@69: 'The advantage of the "range" type over a regular "list" or ' jpayne@69: '"tuple" is\n' jpayne@69: 'that a "range" object will always take the same (small) amount ' jpayne@69: 'of\n' jpayne@69: 'memory, no matter the size of the range it represents (as it ' jpayne@69: 'only\n' jpayne@69: 'stores the "start", "stop" and "step" values, calculating ' jpayne@69: 'individual\n' jpayne@69: 'items and subranges as needed).\n' jpayne@69: '\n' jpayne@69: 'Range objects implement the "collections.abc.Sequence" ABC, and\n' jpayne@69: 'provide features such as containment tests, element index ' jpayne@69: 'lookup,\n' jpayne@69: 'slicing and support for negative indices (see Sequence Types — ' jpayne@69: 'list,\n' jpayne@69: 'tuple, range):\n' jpayne@69: '\n' jpayne@69: '>>> r = range(0, 20, 2)\n' jpayne@69: '>>> r\n' jpayne@69: 'range(0, 20, 2)\n' jpayne@69: '>>> 11 in r\n' jpayne@69: 'False\n' jpayne@69: '>>> 10 in r\n' jpayne@69: 'True\n' jpayne@69: '>>> r.index(10)\n' jpayne@69: '5\n' jpayne@69: '>>> r[5]\n' jpayne@69: '10\n' jpayne@69: '>>> r[:5]\n' jpayne@69: 'range(0, 10, 2)\n' jpayne@69: '>>> r[-1]\n' jpayne@69: '18\n' jpayne@69: '\n' jpayne@69: 'Testing range objects for equality with "==" and "!=" compares ' jpayne@69: 'them as\n' jpayne@69: 'sequences. That is, two range objects are considered equal if ' jpayne@69: 'they\n' jpayne@69: 'represent the same sequence of values. (Note that two range ' jpayne@69: 'objects\n' jpayne@69: 'that compare equal might have different "start", "stop" and ' jpayne@69: '"step"\n' jpayne@69: 'attributes, for example "range(0) == range(2, 1, 3)" or ' jpayne@69: '"range(0, 3,\n' jpayne@69: '2) == range(0, 4, 2)".)\n' jpayne@69: '\n' jpayne@69: 'Changed in version 3.2: Implement the Sequence ABC. Support ' jpayne@69: 'slicing\n' jpayne@69: 'and negative indices. Test "int" objects for membership in ' jpayne@69: 'constant\n' jpayne@69: 'time instead of iterating through all items.\n' jpayne@69: '\n' jpayne@69: 'Changed in version 3.3: Define ‘==’ and ‘!=’ to compare range ' jpayne@69: 'objects\n' jpayne@69: 'based on the sequence of values they define (instead of ' jpayne@69: 'comparing\n' jpayne@69: 'based on object identity).\n' jpayne@69: '\n' jpayne@69: 'New in version 3.3: The "start", "stop" and "step" attributes.\n' jpayne@69: '\n' jpayne@69: 'See also:\n' jpayne@69: '\n' jpayne@69: ' * The linspace recipe shows how to implement a lazy version ' jpayne@69: 'of\n' jpayne@69: ' range suitable for floating point applications.\n', jpayne@69: 'typesseq-mutable': 'Mutable Sequence Types\n' jpayne@69: '**********************\n' jpayne@69: '\n' jpayne@69: 'The operations in the following table are defined on ' jpayne@69: 'mutable sequence\n' jpayne@69: 'types. The "collections.abc.MutableSequence" ABC is ' jpayne@69: 'provided to make\n' jpayne@69: 'it easier to correctly implement these operations on ' jpayne@69: 'custom sequence\n' jpayne@69: 'types.\n' jpayne@69: '\n' jpayne@69: 'In the table *s* is an instance of a mutable sequence ' jpayne@69: 'type, *t* is any\n' jpayne@69: 'iterable object and *x* is an arbitrary object that ' jpayne@69: 'meets any type and\n' jpayne@69: 'value restrictions imposed by *s* (for example, ' jpayne@69: '"bytearray" only\n' jpayne@69: 'accepts integers that meet the value restriction "0 <= x ' jpayne@69: '<= 255").\n' jpayne@69: '\n' jpayne@69: '+--------------------------------+----------------------------------+-----------------------+\n' jpayne@69: '| Operation | ' jpayne@69: 'Result | Notes ' jpayne@69: '|\n' jpayne@69: '|================================|==================================|=======================|\n' jpayne@69: '| "s[i] = x" | item *i* of *s* is ' jpayne@69: 'replaced by | |\n' jpayne@69: '| | ' jpayne@69: '*x* | ' jpayne@69: '|\n' jpayne@69: '+--------------------------------+----------------------------------+-----------------------+\n' jpayne@69: '| "s[i:j] = t" | slice of *s* from *i* ' jpayne@69: 'to *j* is | |\n' jpayne@69: '| | replaced by the ' jpayne@69: 'contents of the | |\n' jpayne@69: '| | iterable ' jpayne@69: '*t* | |\n' jpayne@69: '+--------------------------------+----------------------------------+-----------------------+\n' jpayne@69: '| "del s[i:j]" | same as "s[i:j] = ' jpayne@69: '[]" | |\n' jpayne@69: '+--------------------------------+----------------------------------+-----------------------+\n' jpayne@69: '| "s[i:j:k] = t" | the elements of ' jpayne@69: '"s[i:j:k]" are | (1) |\n' jpayne@69: '| | replaced by those of ' jpayne@69: '*t* | |\n' jpayne@69: '+--------------------------------+----------------------------------+-----------------------+\n' jpayne@69: '| "del s[i:j:k]" | removes the elements ' jpayne@69: 'of | |\n' jpayne@69: '| | "s[i:j:k]" from the ' jpayne@69: 'list | |\n' jpayne@69: '+--------------------------------+----------------------------------+-----------------------+\n' jpayne@69: '| "s.append(x)" | appends *x* to the ' jpayne@69: 'end of the | |\n' jpayne@69: '| | sequence (same ' jpayne@69: 'as | |\n' jpayne@69: '| | "s[len(s):len(s)] = ' jpayne@69: '[x]") | |\n' jpayne@69: '+--------------------------------+----------------------------------+-----------------------+\n' jpayne@69: '| "s.clear()" | removes all items ' jpayne@69: 'from *s* (same | (5) |\n' jpayne@69: '| | as "del ' jpayne@69: 's[:]") | |\n' jpayne@69: '+--------------------------------+----------------------------------+-----------------------+\n' jpayne@69: '| "s.copy()" | creates a shallow ' jpayne@69: 'copy of *s* | (5) |\n' jpayne@69: '| | (same as ' jpayne@69: '"s[:]") | |\n' jpayne@69: '+--------------------------------+----------------------------------+-----------------------+\n' jpayne@69: '| "s.extend(t)" or "s += t" | extends *s* with the ' jpayne@69: 'contents of | |\n' jpayne@69: '| | *t* (for the most ' jpayne@69: 'part the same | |\n' jpayne@69: '| | as "s[len(s):len(s)] ' jpayne@69: '= t") | |\n' jpayne@69: '+--------------------------------+----------------------------------+-----------------------+\n' jpayne@69: '| "s *= n" | updates *s* with its ' jpayne@69: 'contents | (6) |\n' jpayne@69: '| | repeated *n* ' jpayne@69: 'times | |\n' jpayne@69: '+--------------------------------+----------------------------------+-----------------------+\n' jpayne@69: '| "s.insert(i, x)" | inserts *x* into *s* ' jpayne@69: 'at the | |\n' jpayne@69: '| | index given by *i* ' jpayne@69: '(same as | |\n' jpayne@69: '| | "s[i:i] = ' jpayne@69: '[x]") | |\n' jpayne@69: '+--------------------------------+----------------------------------+-----------------------+\n' jpayne@69: '| "s.pop([i])" | retrieves the item at ' jpayne@69: '*i* and | (2) |\n' jpayne@69: '| | also removes it from ' jpayne@69: '*s* | |\n' jpayne@69: '+--------------------------------+----------------------------------+-----------------------+\n' jpayne@69: '| "s.remove(x)" | remove the first item ' jpayne@69: 'from *s* | (3) |\n' jpayne@69: '| | where "s[i]" is equal ' jpayne@69: 'to *x* | |\n' jpayne@69: '+--------------------------------+----------------------------------+-----------------------+\n' jpayne@69: '| "s.reverse()" | reverses the items of ' jpayne@69: '*s* in | (4) |\n' jpayne@69: '| | ' jpayne@69: 'place | ' jpayne@69: '|\n' jpayne@69: '+--------------------------------+----------------------------------+-----------------------+\n' jpayne@69: '\n' jpayne@69: 'Notes:\n' jpayne@69: '\n' jpayne@69: '1. *t* must have the same length as the slice it is ' jpayne@69: 'replacing.\n' jpayne@69: '\n' jpayne@69: '2. The optional argument *i* defaults to "-1", so that ' jpayne@69: 'by default\n' jpayne@69: ' the last item is removed and returned.\n' jpayne@69: '\n' jpayne@69: '3. "remove()" raises "ValueError" when *x* is not found ' jpayne@69: 'in *s*.\n' jpayne@69: '\n' jpayne@69: '4. The "reverse()" method modifies the sequence in place ' jpayne@69: 'for\n' jpayne@69: ' economy of space when reversing a large sequence. To ' jpayne@69: 'remind users\n' jpayne@69: ' that it operates by side effect, it does not return ' jpayne@69: 'the reversed\n' jpayne@69: ' sequence.\n' jpayne@69: '\n' jpayne@69: '5. "clear()" and "copy()" are included for consistency ' jpayne@69: 'with the\n' jpayne@69: ' interfaces of mutable containers that don’t support ' jpayne@69: 'slicing\n' jpayne@69: ' operations (such as "dict" and "set"). "copy()" is ' jpayne@69: 'not part of the\n' jpayne@69: ' "collections.abc.MutableSequence" ABC, but most ' jpayne@69: 'concrete mutable\n' jpayne@69: ' sequence classes provide it.\n' jpayne@69: '\n' jpayne@69: ' New in version 3.3: "clear()" and "copy()" methods.\n' jpayne@69: '\n' jpayne@69: '6. The value *n* is an integer, or an object ' jpayne@69: 'implementing\n' jpayne@69: ' "__index__()". Zero and negative values of *n* clear ' jpayne@69: 'the sequence.\n' jpayne@69: ' Items in the sequence are not copied; they are ' jpayne@69: 'referenced multiple\n' jpayne@69: ' times, as explained for "s * n" under Common Sequence ' jpayne@69: 'Operations.\n', jpayne@69: 'unary': 'Unary arithmetic and bitwise operations\n' jpayne@69: '***************************************\n' jpayne@69: '\n' jpayne@69: 'All unary arithmetic and bitwise operations have the same ' jpayne@69: 'priority:\n' jpayne@69: '\n' jpayne@69: ' u_expr ::= power | "-" u_expr | "+" u_expr | "~" u_expr\n' jpayne@69: '\n' jpayne@69: 'The unary "-" (minus) operator yields the negation of its numeric\n' jpayne@69: 'argument.\n' jpayne@69: '\n' jpayne@69: 'The unary "+" (plus) operator yields its numeric argument ' jpayne@69: 'unchanged.\n' jpayne@69: '\n' jpayne@69: 'The unary "~" (invert) operator yields the bitwise inversion of ' jpayne@69: 'its\n' jpayne@69: 'integer argument. The bitwise inversion of "x" is defined as\n' jpayne@69: '"-(x+1)". It only applies to integral numbers.\n' jpayne@69: '\n' jpayne@69: 'In all three cases, if the argument does not have the proper type, ' jpayne@69: 'a\n' jpayne@69: '"TypeError" exception is raised.\n', jpayne@69: 'while': 'The "while" statement\n' jpayne@69: '*********************\n' jpayne@69: '\n' jpayne@69: 'The "while" statement is used for repeated execution as long as an\n' jpayne@69: 'expression is true:\n' jpayne@69: '\n' jpayne@69: ' while_stmt ::= "while" expression ":" suite\n' jpayne@69: ' ["else" ":" suite]\n' jpayne@69: '\n' jpayne@69: 'This repeatedly tests the expression and, if it is true, executes ' jpayne@69: 'the\n' jpayne@69: 'first suite; if the expression is false (which may be the first ' jpayne@69: 'time\n' jpayne@69: 'it is tested) the suite of the "else" clause, if present, is ' jpayne@69: 'executed\n' jpayne@69: 'and the loop terminates.\n' jpayne@69: '\n' jpayne@69: 'A "break" statement executed in the first suite terminates the ' jpayne@69: 'loop\n' jpayne@69: 'without executing the "else" clause’s suite. A "continue" ' jpayne@69: 'statement\n' jpayne@69: 'executed in the first suite skips the rest of the suite and goes ' jpayne@69: 'back\n' jpayne@69: 'to testing the expression.\n', jpayne@69: 'with': 'The "with" statement\n' jpayne@69: '********************\n' jpayne@69: '\n' jpayne@69: 'The "with" statement is used to wrap the execution of a block with\n' jpayne@69: 'methods defined by a context manager (see section With Statement\n' jpayne@69: 'Context Managers). This allows common "try"…"except"…"finally" ' jpayne@69: 'usage\n' jpayne@69: 'patterns to be encapsulated for convenient reuse.\n' jpayne@69: '\n' jpayne@69: ' with_stmt ::= "with" with_item ("," with_item)* ":" suite\n' jpayne@69: ' with_item ::= expression ["as" target]\n' jpayne@69: '\n' jpayne@69: 'The execution of the "with" statement with one “item” proceeds as\n' jpayne@69: 'follows:\n' jpayne@69: '\n' jpayne@69: '1. The context expression (the expression given in the "with_item")\n' jpayne@69: ' is evaluated to obtain a context manager.\n' jpayne@69: '\n' jpayne@69: '2. The context manager’s "__exit__()" is loaded for later use.\n' jpayne@69: '\n' jpayne@69: '3. The context manager’s "__enter__()" method is invoked.\n' jpayne@69: '\n' jpayne@69: '4. If a target was included in the "with" statement, the return\n' jpayne@69: ' value from "__enter__()" is assigned to it.\n' jpayne@69: '\n' jpayne@69: ' Note: The "with" statement guarantees that if the "__enter__()"\n' jpayne@69: ' method returns without an error, then "__exit__()" will always ' jpayne@69: 'be\n' jpayne@69: ' called. Thus, if an error occurs during the assignment to the\n' jpayne@69: ' target list, it will be treated the same as an error occurring\n' jpayne@69: ' within the suite would be. See step 6 below.\n' jpayne@69: '\n' jpayne@69: '5. The suite is executed.\n' jpayne@69: '\n' jpayne@69: '6. The context manager’s "__exit__()" method is invoked. If an\n' jpayne@69: ' exception caused the suite to be exited, its type, value, and\n' jpayne@69: ' traceback are passed as arguments to "__exit__()". Otherwise, ' jpayne@69: 'three\n' jpayne@69: ' "None" arguments are supplied.\n' jpayne@69: '\n' jpayne@69: ' If the suite was exited due to an exception, and the return ' jpayne@69: 'value\n' jpayne@69: ' from the "__exit__()" method was false, the exception is ' jpayne@69: 'reraised.\n' jpayne@69: ' If the return value was true, the exception is suppressed, and\n' jpayne@69: ' execution continues with the statement following the "with"\n' jpayne@69: ' statement.\n' jpayne@69: '\n' jpayne@69: ' If the suite was exited for any reason other than an exception, ' jpayne@69: 'the\n' jpayne@69: ' return value from "__exit__()" is ignored, and execution ' jpayne@69: 'proceeds\n' jpayne@69: ' at the normal location for the kind of exit that was taken.\n' jpayne@69: '\n' jpayne@69: 'With more than one item, the context managers are processed as if\n' jpayne@69: 'multiple "with" statements were nested:\n' jpayne@69: '\n' jpayne@69: ' with A() as a, B() as b:\n' jpayne@69: ' suite\n' jpayne@69: '\n' jpayne@69: 'is equivalent to\n' jpayne@69: '\n' jpayne@69: ' with A() as a:\n' jpayne@69: ' with B() as b:\n' jpayne@69: ' suite\n' jpayne@69: '\n' jpayne@69: 'Changed in version 3.1: Support for multiple context expressions.\n' jpayne@69: '\n' jpayne@69: 'See also:\n' jpayne@69: '\n' jpayne@69: ' **PEP 343** - The “with” statement\n' jpayne@69: ' The specification, background, and examples for the Python ' jpayne@69: '"with"\n' jpayne@69: ' statement.\n', jpayne@69: 'yield': 'The "yield" statement\n' jpayne@69: '*********************\n' jpayne@69: '\n' jpayne@69: ' yield_stmt ::= yield_expression\n' jpayne@69: '\n' jpayne@69: 'A "yield" statement is semantically equivalent to a yield ' jpayne@69: 'expression.\n' jpayne@69: 'The yield statement can be used to omit the parentheses that would\n' jpayne@69: 'otherwise be required in the equivalent yield expression ' jpayne@69: 'statement.\n' jpayne@69: 'For example, the yield statements\n' jpayne@69: '\n' jpayne@69: ' yield \n' jpayne@69: ' yield from \n' jpayne@69: '\n' jpayne@69: 'are equivalent to the yield expression statements\n' jpayne@69: '\n' jpayne@69: ' (yield )\n' jpayne@69: ' (yield from )\n' jpayne@69: '\n' jpayne@69: 'Yield expressions and statements are only used when defining a\n' jpayne@69: '*generator* function, and are only used in the body of the ' jpayne@69: 'generator\n' jpayne@69: 'function. Using yield in a function definition is sufficient to ' jpayne@69: 'cause\n' jpayne@69: 'that definition to create a generator function instead of a normal\n' jpayne@69: 'function.\n' jpayne@69: '\n' jpayne@69: 'For full details of "yield" semantics, refer to the Yield ' jpayne@69: 'expressions\n' jpayne@69: 'section.\n'}