diff options
Diffstat (limited to 'Lib/pydoc_data')
| -rw-r--r-- | Lib/pydoc_data/_pydoc.css | 6 | ||||
| -rw-r--r-- | Lib/pydoc_data/topics.py | 13785 |
2 files changed, 6856 insertions, 6935 deletions
diff --git a/Lib/pydoc_data/_pydoc.css b/Lib/pydoc_data/_pydoc.css deleted file mode 100644 index f036ef3..0000000 --- a/Lib/pydoc_data/_pydoc.css +++ /dev/null @@ -1,6 +0,0 @@ -/* - CSS file for pydoc. - - Contents of this file are subject to change without notice. - -*/ diff --git a/Lib/pydoc_data/topics.py b/Lib/pydoc_data/topics.py index c3fe079..5fc84a8 100644 --- a/Lib/pydoc_data/topics.py +++ b/Lib/pydoc_data/topics.py @@ -1,6 +1,7 @@ # -*- coding: utf-8 -*- -# Autogenerated by Sphinx on Tue Nov 19 11:42:25 2019 -topics = {'assert': 'The "assert" statement\n' +# Autogenerated by Sphinx on Sat Aug 26 11:16:28 2017 +topics = {'assert': '\n' + 'The "assert" statement\n' '**********************\n' '\n' 'Assert statements are a convenient way to insert debugging ' @@ -26,8 +27,7 @@ topics = {'assert': 'The "assert" statement\n' 'implementation, the built-in variable "__debug__" is "True" under\n' 'normal circumstances, "False" when optimization is requested ' '(command\n' - 'line option "-O"). The current code generator emits no code for ' - 'an\n' + 'line option -O). The current code generator emits no code for an\n' 'assert statement when optimization is requested at compile time. ' 'Note\n' 'that it is unnecessary to include the source code for the ' @@ -39,27 +39,27 @@ topics = {'assert': 'The "assert" statement\n' 'Assignments to "__debug__" are illegal. The value for the ' 'built-in\n' 'variable is determined when the interpreter starts.\n', - 'assignment': 'Assignment statements\n' + 'assignment': '\n' + 'Assignment statements\n' '*********************\n' '\n' 'Assignment statements are used to (re)bind names to values and ' 'to\n' 'modify attributes or items of mutable objects:\n' '\n' - ' assignment_stmt ::= (target_list "=")+ (starred_expression ' - '| yield_expression)\n' + ' assignment_stmt ::= (target_list "=")+ (expression_list | ' + 'yield_expression)\n' ' target_list ::= target ("," target)* [","]\n' ' target ::= identifier\n' - ' | "(" [target_list] ")"\n' + ' | "(" target_list ")"\n' ' | "[" [target_list] "]"\n' ' | attributeref\n' ' | subscription\n' ' | slicing\n' - ' | "*" target\n' '\n' - '(See section Primaries for the syntax definitions for ' - '*attributeref*,\n' - '*subscription*, and *slicing*.)\n' + '(See section Primaries for the syntax definitions for the last ' + 'three\n' + 'symbols.)\n' '\n' 'An assignment statement evaluates the expression list ' '(remember that\n' @@ -83,45 +83,21 @@ topics = {'assert': 'The "assert" statement\n' 'definition of the object types (see section The standard type\n' 'hierarchy).\n' '\n' - 'Assignment of an object to a target list, optionally enclosed ' - 'in\n' - 'parentheses or square brackets, is recursively defined as ' + 'Assignment of an object to a target list is recursively ' + 'defined as\n' 'follows.\n' '\n' - '* If the target list is a single target with no trailing ' - 'comma,\n' - ' optionally in parentheses, the object is assigned to that ' - 'target.\n' - '\n' - '* Else: The object must be an iterable with the same number of ' - 'items\n' - ' as there are targets in the target list, and the items are ' - 'assigned,\n' - ' from left to right, to the corresponding targets.\n' - '\n' - ' * If the target list contains one target prefixed with an\n' - ' asterisk, called a “starred” target: The object must be ' - 'an\n' - ' iterable with at least as many items as there are targets ' - 'in the\n' - ' target list, minus one. The first items of the iterable ' - 'are\n' - ' assigned, from left to right, to the targets before the ' - 'starred\n' - ' target. The final items of the iterable are assigned to ' - 'the\n' - ' targets after the starred target. A list of the remaining ' - 'items\n' - ' in the iterable is then assigned to the starred target ' - '(the list\n' - ' can be empty).\n' + '* If the target list is a single target: The object is ' + 'assigned to\n' + ' that target.\n' '\n' - ' * Else: The object must be an iterable with the same number ' - 'of\n' - ' items as there are targets in the target list, and the ' - 'items are\n' - ' assigned, from left to right, to the corresponding ' - 'targets.\n' + '* If the target list is a comma-separated list of targets: ' + 'The\n' + ' object must be an iterable with the same number of items as ' + 'there\n' + ' are targets in the target list, and the items are assigned, ' + 'from\n' + ' left to right, to the corresponding targets.\n' '\n' 'Assignment of an object to a single target is recursively ' 'defined as\n' @@ -129,16 +105,14 @@ topics = {'assert': 'The "assert" statement\n' '\n' '* If the target is an identifier (name):\n' '\n' - ' * If the name does not occur in a "global" or "nonlocal" ' - 'statement\n' - ' in the current code block: the name is bound to the object ' - 'in the\n' - ' current local namespace.\n' + ' * If the name does not occur in a "global" statement in the\n' + ' current code block: the name is bound to the object in the ' + 'current\n' + ' local namespace.\n' '\n' - ' * Otherwise: the name is bound to the object in the global\n' - ' namespace or the outer namespace determined by ' - '"nonlocal",\n' - ' respectively.\n' + ' * Otherwise: the name is bound to the object in the current ' + 'global\n' + ' namespace.\n' '\n' ' The name is rebound if it was already bound. This may cause ' 'the\n' @@ -148,6 +122,14 @@ topics = {'assert': 'The "assert" statement\n' 'destructor (if it\n' ' has one) to be called.\n' '\n' + '* If the target is a target list enclosed in parentheses or ' + 'in\n' + ' square brackets: The object must be an iterable with the ' + 'same number\n' + ' of items as there are targets in the target list, and its ' + 'items are\n' + ' assigned, from left to right, to the corresponding targets.\n' + '\n' '* If the target is an attribute reference: The primary ' 'expression in\n' ' the reference is evaluated. It should yield an object with\n' @@ -162,21 +144,20 @@ topics = {'assert': 'The "assert" statement\n' '\n' ' Note: If the object is a class instance and the attribute ' 'reference\n' - ' occurs on both sides of the assignment operator, the ' - 'right-hand side\n' - ' expression, "a.x" can access either an instance attribute or ' - '(if no\n' - ' instance attribute exists) a class attribute. The left-hand ' - 'side\n' - ' target "a.x" is always set as an instance attribute, ' - 'creating it if\n' - ' necessary. Thus, the two occurrences of "a.x" do not ' - 'necessarily\n' - ' refer to the same attribute: if the right-hand side ' - 'expression\n' - ' refers to a class attribute, the left-hand side creates a ' - 'new\n' - ' instance attribute as the target of the assignment:\n' + ' occurs on both sides of the assignment operator, the RHS ' + 'expression,\n' + ' "a.x" can access either an instance attribute or (if no ' + 'instance\n' + ' attribute exists) a class attribute. The LHS target "a.x" ' + 'is always\n' + ' set as an instance attribute, creating it if necessary. ' + 'Thus, the\n' + ' two occurrences of "a.x" do not necessarily refer to the ' + 'same\n' + ' attribute: if the RHS expression refers to a class ' + 'attribute, the\n' + ' LHS creates a new instance attribute as the target of the\n' + ' assignment:\n' '\n' ' class Cls:\n' ' x = 3 # class variable\n' @@ -197,21 +178,23 @@ topics = {'assert': 'The "assert" statement\n' '\n' ' If the primary is a mutable sequence object (such as a ' 'list), the\n' - ' subscript must yield an integer. If it is negative, the ' - 'sequence’s\n' - ' length is added to it. The resulting value must be a ' - 'nonnegative\n' - ' integer less than the sequence’s length, and the sequence is ' - 'asked\n' - ' to assign the assigned object to its item with that index. ' - 'If the\n' - ' index is out of range, "IndexError" is raised (assignment to ' - 'a\n' - ' subscripted sequence cannot add new items to a list).\n' + ' subscript must yield a plain integer. If it is negative, ' + 'the\n' + " sequence's length is added to it. The resulting value must " + 'be a\n' + " nonnegative integer less than the sequence's length, and " + 'the\n' + ' sequence is asked to assign the assigned object to its item ' + 'with\n' + ' that index. If the index is out of range, "IndexError" is ' + 'raised\n' + ' (assignment to a subscripted sequence cannot add new items ' + 'to a\n' + ' list).\n' '\n' ' If the primary is a mapping object (such as a dictionary), ' 'the\n' - ' subscript must have a type compatible with the mapping’s key ' + " subscript must have a type compatible with the mapping's key " 'type,\n' ' and the mapping is then asked to create a key/datum pair ' 'which maps\n' @@ -221,10 +204,6 @@ topics = {'assert': 'The "assert" statement\n' 'new\n' ' key/value pair (if no key with the same value existed).\n' '\n' - ' For user-defined objects, the "__setitem__()" method is ' - 'called with\n' - ' appropriate arguments.\n' - '\n' '* If the target is a slicing: The primary expression in the\n' ' reference is evaluated. It should yield a mutable sequence ' 'object\n' @@ -234,21 +213,21 @@ topics = {'assert': 'The "assert" statement\n' 'expressions are\n' ' evaluated, insofar they are present; defaults are zero and ' 'the\n' - ' sequence’s length. The bounds should evaluate to integers. ' - 'If\n' - ' either bound is negative, the sequence’s length is added to ' - 'it. The\n' - ' resulting bounds are clipped to lie between zero and the ' - 'sequence’s\n' - ' length, inclusive. Finally, the sequence object is asked to ' - 'replace\n' - ' the slice with the items of the assigned sequence. The ' - 'length of\n' - ' the slice may be different from the length of the assigned ' - 'sequence,\n' - ' thus changing the length of the target sequence, if the ' - 'target\n' - ' sequence allows it.\n' + " sequence's length. The bounds should evaluate to (small) " + 'integers.\n' + " If either bound is negative, the sequence's length is added " + 'to it.\n' + ' The resulting bounds are clipped to lie between zero and ' + 'the\n' + " sequence's length, inclusive. Finally, the sequence object " + 'is asked\n' + ' to replace the slice with the items of the assigned ' + 'sequence. The\n' + ' length of the slice may be different from the length of the ' + 'assigned\n' + ' sequence, thus changing the length of the target sequence, ' + 'if the\n' + ' object allows it.\n' '\n' '**CPython implementation detail:** In the current ' 'implementation, the\n' @@ -258,28 +237,20 @@ topics = {'assert': 'The "assert" statement\n' 'causing\n' 'less detailed error messages.\n' '\n' - 'Although the definition of assignment implies that overlaps ' - 'between\n' - 'the left-hand side and the right-hand side are ‘simultaneous’ ' + 'WARNING: Although the definition of assignment implies that ' + 'overlaps\n' + "between the left-hand side and the right-hand side are 'safe' " '(for\n' 'example "a, b = b, a" swaps two variables), overlaps *within* ' 'the\n' - 'collection of assigned-to variables occur left-to-right, ' - 'sometimes\n' - 'resulting in confusion. For instance, the following program ' - 'prints\n' - '"[0, 2]":\n' + 'collection of assigned-to variables are not safe! For ' + 'instance, the\n' + 'following program prints "[0, 2]":\n' '\n' ' x = [0, 1]\n' ' i = 0\n' - ' i, x[i] = 1, 2 # i is updated, then x[i] is ' - 'updated\n' - ' print(x)\n' - '\n' - 'See also:\n' - '\n' - ' **PEP 3132** - Extended Iterable Unpacking\n' - ' The specification for the "*target" feature.\n' + ' i, x[i] = 1, 2\n' + ' print x\n' '\n' '\n' 'Augmented assignment statements\n' @@ -293,11 +264,11 @@ topics = {'assert': 'The "assert" statement\n' '(expression_list | yield_expression)\n' ' augtarget ::= identifier | attributeref | ' 'subscription | slicing\n' - ' augop ::= "+=" | "-=" | "*=" | "@=" | ' - '"/=" | "//=" | "%=" | "**="\n' + ' augop ::= "+=" | "-=" | "*=" | "/=" | ' + '"//=" | "%=" | "**="\n' ' | ">>=" | "<<=" | "&=" | "^=" | "|="\n' '\n' - '(See section Primaries for the syntax definitions of the last ' + '(See section Primaries for the syntax definitions for the last ' 'three\n' 'symbols.)\n' '\n' @@ -323,15 +294,6 @@ topics = {'assert': 'The "assert" statement\n' 'old object\n' 'is modified instead.\n' '\n' - 'Unlike normal assignments, augmented assignments evaluate the ' - 'left-\n' - 'hand side *before* evaluating the right-hand side. For ' - 'example, "a[i]\n' - '+= f(x)" first looks-up "a[i]", then it evaluates "f(x)" and ' - 'performs\n' - 'the addition, and lastly, it writes the result back to ' - '"a[i]".\n' - '\n' 'With the exception of assigning to tuples and multiple targets ' 'in a\n' 'single statement, the assignment done by augmented assignment\n' @@ -346,211 +308,9 @@ topics = {'assert': 'The "assert" statement\n' 'For targets which are attribute references, the same caveat ' 'about\n' 'class and instance attributes applies as for regular ' - 'assignments.\n' - '\n' - '\n' - 'Annotated assignment statements\n' - '===============================\n' - '\n' - '*Annotation* assignment is the combination, in a single ' - 'statement, of\n' - 'a variable or attribute annotation and an optional assignment\n' - 'statement:\n' - '\n' - ' annotated_assignment_stmt ::= augtarget ":" expression\n' - ' ["=" (starred_expression | ' - 'yield_expression)]\n' - '\n' - 'The difference from normal Assignment statements is that only ' - 'single\n' - 'target is allowed.\n' - '\n' - 'For simple names as assignment targets, if in class or module ' - 'scope,\n' - 'the annotations are evaluated and stored in a special class or ' - 'module\n' - 'attribute "__annotations__" that is a dictionary mapping from ' - 'variable\n' - 'names (mangled if private) to evaluated annotations. This ' - 'attribute is\n' - 'writable and is automatically created at the start of class or ' - 'module\n' - 'body execution, if annotations are found statically.\n' - '\n' - 'For expressions as assignment targets, the annotations are ' - 'evaluated\n' - 'if in class or module scope, but not stored.\n' - '\n' - 'If a name is annotated in a function scope, then this name is ' - 'local\n' - 'for that scope. Annotations are never evaluated and stored in ' - 'function\n' - 'scopes.\n' - '\n' - 'If the right hand side is present, an annotated assignment ' - 'performs\n' - 'the actual assignment before evaluating annotations (where\n' - 'applicable). If the right hand side is not present for an ' - 'expression\n' - 'target, then the interpreter evaluates the target except for ' - 'the last\n' - '"__setitem__()" or "__setattr__()" call.\n' - '\n' - 'See also:\n' - '\n' - ' **PEP 526** - Syntax for Variable Annotations\n' - ' The proposal that added syntax for annotating the types ' - 'of\n' - ' variables (including class variables and instance ' - 'variables),\n' - ' instead of expressing them through comments.\n' - '\n' - ' **PEP 484** - Type hints\n' - ' The proposal that added the "typing" module to provide a ' - 'standard\n' - ' syntax for type annotations that can be used in static ' - 'analysis\n' - ' tools and IDEs.\n' - '\n' - 'Changed in version 3.8: Now annotated assignments allow same\n' - 'expressions in the right hand side as the regular ' - 'assignments.\n' - 'Previously, some expressions (like un-parenthesized tuple ' - 'expressions)\n' - 'caused a syntax error.\n', - 'async': 'Coroutines\n' - '**********\n' - '\n' - 'New in version 3.5.\n' - '\n' - '\n' - 'Coroutine function definition\n' - '=============================\n' - '\n' - ' async_funcdef ::= [decorators] "async" "def" funcname "(" ' - '[parameter_list] ")"\n' - ' ["->" expression] ":" suite\n' - '\n' - 'Execution of Python coroutines can be suspended and resumed at ' - 'many\n' - 'points (see *coroutine*). Inside the body of a coroutine ' - 'function,\n' - '"await" and "async" identifiers become reserved keywords; "await"\n' - 'expressions, "async for" and "async with" can only be used in\n' - 'coroutine function bodies.\n' - '\n' - 'Functions defined with "async def" syntax are always coroutine\n' - 'functions, even if they do not contain "await" or "async" ' - 'keywords.\n' - '\n' - 'It is a "SyntaxError" to use a "yield from" expression inside the ' - 'body\n' - 'of a coroutine function.\n' - '\n' - 'An example of a coroutine function:\n' - '\n' - ' async def func(param1, param2):\n' - ' do_stuff()\n' - ' await some_coroutine()\n' - '\n' - '\n' - 'The "async for" statement\n' - '=========================\n' - '\n' - ' async_for_stmt ::= "async" for_stmt\n' - '\n' - 'An *asynchronous iterable* is able to call asynchronous code in ' - 'its\n' - '*iter* implementation, and *asynchronous iterator* can call\n' - 'asynchronous code in its *next* method.\n' - '\n' - 'The "async for" statement allows convenient iteration over\n' - 'asynchronous iterators.\n' - '\n' - 'The following code:\n' - '\n' - ' async for TARGET in ITER:\n' - ' BLOCK\n' - ' else:\n' - ' BLOCK2\n' - '\n' - 'Is semantically equivalent to:\n' - '\n' - ' iter = (ITER)\n' - ' iter = type(iter).__aiter__(iter)\n' - ' running = True\n' - ' while running:\n' - ' try:\n' - ' TARGET = await type(iter).__anext__(iter)\n' - ' except StopAsyncIteration:\n' - ' running = False\n' - ' else:\n' - ' BLOCK\n' - ' else:\n' - ' BLOCK2\n' - '\n' - 'See also "__aiter__()" and "__anext__()" for details.\n' - '\n' - 'It is a "SyntaxError" to use an "async for" statement outside the ' - 'body\n' - 'of a coroutine function.\n' - '\n' - '\n' - 'The "async with" statement\n' - '==========================\n' - '\n' - ' async_with_stmt ::= "async" with_stmt\n' - '\n' - 'An *asynchronous context manager* is a *context manager* that is ' - 'able\n' - 'to suspend execution in its *enter* and *exit* methods.\n' - '\n' - 'The following code:\n' - '\n' - ' async with EXPR as VAR:\n' - ' BLOCK\n' - '\n' - 'Is semantically equivalent to:\n' - '\n' - ' mgr = (EXPR)\n' - ' aexit = type(mgr).__aexit__\n' - ' aenter = type(mgr).__aenter__(mgr)\n' - '\n' - ' VAR = await aenter\n' - ' try:\n' - ' BLOCK\n' - ' except:\n' - ' if not await aexit(mgr, *sys.exc_info()):\n' - ' raise\n' - ' else:\n' - ' await aexit(mgr, None, None, None)\n' - '\n' - 'See also "__aenter__()" and "__aexit__()" for details.\n' - '\n' - 'It is a "SyntaxError" to use an "async with" statement outside the\n' - 'body of a coroutine function.\n' - '\n' - 'See also:\n' - '\n' - ' **PEP 492** - Coroutines with async and await syntax\n' - ' The proposal that made coroutines a proper standalone concept ' - 'in\n' - ' Python, and added supporting syntax.\n' - '\n' - '-[ Footnotes ]-\n' - '\n' - '[1] The exception is propagated to the invocation stack unless\n' - ' there is a "finally" clause which happens to raise another\n' - ' exception. That new exception causes the old one to be lost.\n' - '\n' - '[2] A string literal appearing as the first statement in the\n' - ' function body is transformed into the function’s "__doc__"\n' - ' attribute and therefore the function’s *docstring*.\n' - '\n' - '[3] A string literal appearing as the first statement in the class\n' - ' body is transformed into the namespace’s "__doc__" item and\n' - ' therefore the class’s *docstring*.\n', - 'atom-identifiers': 'Identifiers (Names)\n' + 'assignments.\n', + 'atom-identifiers': '\n' + 'Identifiers (Names)\n' '*******************\n' '\n' 'An identifier occurring as an atom is a name. See ' @@ -590,28 +350,29 @@ topics = {'assert': 'The "assert" statement\n' 'happen. If the class name consists only of underscores, ' 'no\n' 'transformation is done.\n', - 'atom-literals': 'Literals\n' + 'atom-literals': '\n' + 'Literals\n' '********\n' '\n' - 'Python supports string and bytes literals and various ' - 'numeric\n' + 'Python supports string literals and various numeric ' 'literals:\n' '\n' - ' literal ::= stringliteral | bytesliteral\n' - ' | integer | floatnumber | imagnumber\n' + ' literal ::= stringliteral | integer | longinteger\n' + ' | floatnumber | imagnumber\n' '\n' 'Evaluation of a literal yields an object of the given type ' '(string,\n' - 'bytes, integer, floating point number, complex number) with ' - 'the given\n' - 'value. The value may be approximated in the case of ' - 'floating point\n' - 'and imaginary (complex) literals. See section Literals for ' + 'integer, long integer, floating point number, complex ' + 'number) with the\n' + 'given value. The value may be approximated in the case of ' + 'floating\n' + 'point and imaginary (complex) literals. See section ' + 'Literals for\n' 'details.\n' '\n' 'All literals correspond to immutable data types, and hence ' 'the\n' - 'object’s identity is less important than its value. ' + "object's identity is less important than its value. " 'Multiple\n' 'evaluations of literals with the same value (either the ' 'same\n' @@ -619,7 +380,8 @@ topics = {'assert': 'The "assert" statement\n' 'may obtain\n' 'the same object or a different object with the same ' 'value.\n', - 'attribute-access': 'Customizing attribute access\n' + 'attribute-access': '\n' + 'Customizing attribute access\n' '****************************\n' '\n' 'The following methods can be defined to customize the ' @@ -630,19 +392,15 @@ topics = {'assert': 'The "assert" statement\n' '\n' 'object.__getattr__(self, name)\n' '\n' - ' Called when the default attribute access fails with ' - 'an\n' - ' "AttributeError" (either "__getattribute__()" raises ' - 'an\n' - ' "AttributeError" because *name* is not an instance ' - 'attribute or an\n' - ' attribute in the class tree for "self"; or ' - '"__get__()" of a *name*\n' - ' property raises "AttributeError"). This method ' - 'should either\n' - ' return the (computed) attribute value or raise an ' - '"AttributeError"\n' - ' exception.\n' + ' Called when an attribute lookup has not found the ' + 'attribute in the\n' + ' usual places (i.e. it is not an instance attribute ' + 'nor is it found\n' + ' in the class tree for "self"). "name" is the ' + 'attribute name. This\n' + ' method should return the (computed) attribute value ' + 'or raise an\n' + ' "AttributeError" exception.\n' '\n' ' Note that if the attribute is found through the ' 'normal mechanism,\n' @@ -661,33 +419,7 @@ topics = {'assert': 'The "assert" statement\n' ' instead inserting them in another object). See the\n' ' "__getattribute__()" method below for a way to ' 'actually get total\n' - ' control over attribute access.\n' - '\n' - 'object.__getattribute__(self, name)\n' - '\n' - ' Called unconditionally to implement attribute ' - 'accesses for\n' - ' instances of the class. If the class also defines ' - '"__getattr__()",\n' - ' the latter will not be called unless ' - '"__getattribute__()" either\n' - ' calls it explicitly or raises an "AttributeError". ' - 'This method\n' - ' should return the (computed) attribute value or raise ' - 'an\n' - ' "AttributeError" exception. In order to avoid ' - 'infinite recursion in\n' - ' this method, its implementation should always call ' - 'the base class\n' - ' method with the same name to access any attributes it ' - 'needs, for\n' - ' example, "object.__getattribute__(self, name)".\n' - '\n' - ' Note: This method may still be bypassed when looking ' - 'up special\n' - ' methods as the result of implicit invocation via ' - 'language syntax\n' - ' or built-in functions. See Special method lookup.\n' + ' control in new-style classes.\n' '\n' 'object.__setattr__(self, name, value)\n' '\n' @@ -695,15 +427,24 @@ topics = {'assert': 'The "assert" statement\n' 'This is called\n' ' instead of the normal mechanism (i.e. store the value ' 'in the\n' - ' instance dictionary). *name* is the attribute name, ' + ' instance dictionary). *name* is the attribute name, ' '*value* is the\n' ' value to be assigned to it.\n' '\n' ' If "__setattr__()" wants to assign to an instance ' 'attribute, it\n' - ' should call the base class method with the same name, ' - 'for example,\n' - ' "object.__setattr__(self, name, value)".\n' + ' should not simply execute "self.name = value" --- ' + 'this would cause\n' + ' a recursive call to itself. Instead, it should ' + 'insert the value in\n' + ' the dictionary of instance attributes, e.g., ' + '"self.__dict__[name] =\n' + ' value". For new-style classes, rather than accessing ' + 'the instance\n' + ' dictionary, it should call the base class method with ' + 'the same\n' + ' name, for example, "object.__setattr__(self, name, ' + 'value)".\n' '\n' 'object.__delattr__(self, name)\n' '\n' @@ -713,85 +454,39 @@ topics = {'assert': 'The "assert" statement\n' 'obj.name" is\n' ' meaningful for the object.\n' '\n' - 'object.__dir__(self)\n' - '\n' - ' Called when "dir()" is called on the object. A ' - 'sequence must be\n' - ' returned. "dir()" converts the returned sequence to a ' - 'list and\n' - ' sorts it.\n' - '\n' - '\n' - 'Customizing module attribute access\n' - '===================================\n' - '\n' - 'Special names "__getattr__" and "__dir__" can be also ' - 'used to\n' - 'customize access to module attributes. The "__getattr__" ' - 'function at\n' - 'the module level should accept one argument which is the ' - 'name of an\n' - 'attribute and return the computed value or raise an ' - '"AttributeError".\n' - 'If an attribute is not found on a module object through ' - 'the normal\n' - 'lookup, i.e. "object.__getattribute__()", then ' - '"__getattr__" is\n' - 'searched in the module "__dict__" before raising an ' - '"AttributeError".\n' - 'If found, it is called with the attribute name and the ' - 'result is\n' - 'returned.\n' - '\n' - 'The "__dir__" function should accept no arguments, and ' - 'return a\n' - 'sequence of strings that represents the names accessible ' - 'on module. If\n' - 'present, this function overrides the standard "dir()" ' - 'search on a\n' - 'module.\n' - '\n' - 'For a more fine grained customization of the module ' - 'behavior (setting\n' - 'attributes, properties, etc.), one can set the ' - '"__class__" attribute\n' - 'of a module object to a subclass of "types.ModuleType". ' - 'For example:\n' - '\n' - ' import sys\n' - ' from types import ModuleType\n' - '\n' - ' class VerboseModule(ModuleType):\n' - ' def __repr__(self):\n' - " return f'Verbose {self.__name__}'\n" '\n' - ' def __setattr__(self, attr, value):\n' - " print(f'Setting {attr}...')\n" - ' super().__setattr__(attr, value)\n' + 'More attribute access for new-style classes\n' + '===========================================\n' '\n' - ' sys.modules[__name__].__class__ = VerboseModule\n' + 'The following methods only apply to new-style classes.\n' '\n' - 'Note: Defining module "__getattr__" and setting module ' - '"__class__"\n' - ' only affect lookups made using the attribute access ' - 'syntax –\n' - ' directly accessing the module globals (whether by code ' - 'within the\n' - ' module, or via a reference to the module’s globals ' - 'dictionary) is\n' - ' unaffected.\n' - '\n' - 'Changed in version 3.5: "__class__" module attribute is ' - 'now writable.\n' - '\n' - 'New in version 3.7: "__getattr__" and "__dir__" module ' - 'attributes.\n' + 'object.__getattribute__(self, name)\n' '\n' - 'See also:\n' + ' Called unconditionally to implement attribute ' + 'accesses for\n' + ' instances of the class. If the class also defines ' + '"__getattr__()",\n' + ' the latter will not be called unless ' + '"__getattribute__()" either\n' + ' calls it explicitly or raises an "AttributeError". ' + 'This method\n' + ' should return the (computed) attribute value or raise ' + 'an\n' + ' "AttributeError" exception. In order to avoid ' + 'infinite recursion in\n' + ' this method, its implementation should always call ' + 'the base class\n' + ' method with the same name to access any attributes it ' + 'needs, for\n' + ' example, "object.__getattribute__(self, name)".\n' '\n' - ' **PEP 562** - Module __getattr__ and __dir__\n' - ' Describes the "__getattr__" and "__dir__" functions ' - 'on modules.\n' + ' Note: This method may still be bypassed when looking ' + 'up special\n' + ' methods as the result of implicit invocation via ' + 'language syntax\n' + ' or built-in functions. See Special method lookup ' + 'for new-style\n' + ' classes.\n' '\n' '\n' 'Implementing Descriptors\n' @@ -802,41 +497,29 @@ topics = {'assert': 'The "assert" statement\n' 'containing the method (a so-called *descriptor* class) ' 'appears in an\n' '*owner* class (the descriptor must be in either the ' - 'owner’s class\n' + "owner's class\n" 'dictionary or in the class dictionary for one of its ' 'parents). In the\n' - 'examples below, “the attribute” refers to the attribute ' + 'examples below, "the attribute" refers to the attribute ' 'whose name is\n' - 'the key of the property in the owner class’ "__dict__".\n' + "the key of the property in the owner class' " + '"__dict__".\n' '\n' - 'object.__get__(self, instance, owner=None)\n' + 'object.__get__(self, instance, owner)\n' '\n' ' Called to get the attribute of the owner class (class ' 'attribute\n' ' access) or of an instance of that class (instance ' 'attribute\n' - ' access). The optional *owner* argument is the owner ' - 'class, while\n' - ' *instance* is the instance that the attribute was ' - 'accessed through,\n' - ' or "None" when the attribute is accessed through the ' - '*owner*.\n' - '\n' - ' This method should return the computed attribute ' - 'value or raise an\n' - ' "AttributeError" exception.\n' - '\n' - ' **PEP 252** specifies that "__get__()" is callable ' - 'with one or two\n' - ' arguments. Python’s own built-in descriptors support ' - 'this\n' - ' specification; however, it is likely that some ' - 'third-party tools\n' - ' have descriptors that require both arguments. ' - 'Python’s own\n' - ' "__getattribute__()" implementation always passes in ' - 'both arguments\n' - ' whether they are required or not.\n' + ' access). *owner* is always the owner class, while ' + '*instance* is the\n' + ' instance that the attribute was accessed through, or ' + '"None" when\n' + ' the attribute is accessed through the *owner*. This ' + 'method should\n' + ' return the (computed) attribute value or raise an ' + '"AttributeError"\n' + ' exception.\n' '\n' 'object.__set__(self, instance, value)\n' '\n' @@ -844,47 +527,19 @@ topics = {'assert': 'The "assert" statement\n' 'of the owner\n' ' class to a new value, *value*.\n' '\n' - ' Note, adding "__set__()" or "__delete__()" changes ' - 'the kind of\n' - ' descriptor to a “data descriptor”. See Invoking ' - 'Descriptors for\n' - ' more details.\n' - '\n' 'object.__delete__(self, instance)\n' '\n' ' Called to delete the attribute on an instance ' '*instance* of the\n' ' owner class.\n' '\n' - 'object.__set_name__(self, owner, name)\n' - '\n' - ' Called at the time the owning class *owner* is ' - 'created. The\n' - ' descriptor has been assigned to *name*.\n' - '\n' - ' New in version 3.6.\n' - '\n' - 'The attribute "__objclass__" is interpreted by the ' - '"inspect" module as\n' - 'specifying the class where this object was defined ' - '(setting this\n' - 'appropriately can assist in runtime introspection of ' - 'dynamic class\n' - 'attributes). For callables, it may indicate that an ' - 'instance of the\n' - 'given type (or a subclass) is expected or required as ' - 'the first\n' - 'positional argument (for example, CPython sets this ' - 'attribute for\n' - 'unbound methods that are implemented in C).\n' - '\n' '\n' 'Invoking Descriptors\n' '====================\n' '\n' 'In general, a descriptor is an object attribute with ' - '“binding\n' - 'behavior”, one whose attribute access has been ' + '"binding\n' + 'behavior", one whose attribute access has been ' 'overridden by methods\n' 'in the descriptor protocol: "__get__()", "__set__()", ' 'and\n' @@ -894,7 +549,7 @@ topics = {'assert': 'The "assert" statement\n' '\n' 'The default behavior for attribute access is to get, ' 'set, or delete\n' - 'the attribute from an object’s dictionary. For instance, ' + "the attribute from an object's dictionary. For instance, " '"a.x" has a\n' 'lookup chain starting with "a.__dict__[\'x\']", then\n' '"type(a).__dict__[\'x\']", and continuing through the ' @@ -909,7 +564,10 @@ topics = {'assert': 'The "assert" statement\n' 'in the\n' 'precedence chain depends on which descriptor methods ' 'were defined and\n' - 'how they were called.\n' + 'how they were called. Note that descriptors are only ' + 'invoked for new\n' + 'style objects or classes (ones that subclass "object()" ' + 'or "type()").\n' '\n' 'The starting point for descriptor invocation is a ' 'binding, "a.x". How\n' @@ -921,14 +579,15 @@ topics = {'assert': 'The "assert" statement\n' ' invokes a descriptor method: "x.__get__(a)".\n' '\n' 'Instance Binding\n' - ' If binding to an object instance, "a.x" is ' - 'transformed into the\n' - ' call: "type(a).__dict__[\'x\'].__get__(a, type(a))".\n' + ' If binding to a new-style object instance, "a.x" is ' + 'transformed\n' + ' into the call: "type(a).__dict__[\'x\'].__get__(a, ' + 'type(a))".\n' '\n' 'Class Binding\n' - ' If binding to a class, "A.x" is transformed into the ' - 'call:\n' - ' "A.__dict__[\'x\'].__get__(None, A)".\n' + ' If binding to a new-style class, "A.x" is transformed ' + 'into the\n' + ' call: "A.__dict__[\'x\'].__get__(None, A)".\n' '\n' 'Super Binding\n' ' If "a" is an instance of "super", then the binding ' @@ -949,7 +608,7 @@ topics = {'assert': 'The "assert" statement\n' 'does not define "__get__()", then accessing the ' 'attribute will return\n' 'the descriptor object itself unless there is a value in ' - 'the object’s\n' + "the object's\n" 'instance dictionary. If the descriptor defines ' '"__set__()" and/or\n' '"__delete__()", it is a data descriptor; if it defines ' @@ -958,13 +617,12 @@ topics = {'assert': 'The "assert" statement\n' 'define both\n' '"__get__()" and "__set__()", while non-data descriptors ' 'have just the\n' - '"__get__()" method. Data descriptors with "__get__()" ' - 'and "__set__()"\n' - '(and/or "__delete__()") defined always override a ' - 'redefinition in an\n' - 'instance dictionary. In contrast, non-data descriptors ' - 'can be\n' - 'overridden by instances.\n' + '"__get__()" method. Data descriptors with "__set__()" ' + 'and "__get__()"\n' + 'defined always override a redefinition in an instance ' + 'dictionary. In\n' + 'contrast, non-data descriptors can be overridden by ' + 'instances.\n' '\n' 'Python methods (including "staticmethod()" and ' '"classmethod()") are\n' @@ -984,38 +642,45 @@ topics = {'assert': 'The "assert" statement\n' '__slots__\n' '=========\n' '\n' - '*__slots__* allow us to explicitly declare data members ' - '(like\n' - 'properties) and deny the creation of *__dict__* and ' - '*__weakref__*\n' - '(unless explicitly declared in *__slots__* or available ' - 'in a parent.)\n' + 'By default, instances of both old and new-style classes ' + 'have a\n' + 'dictionary for attribute storage. This wastes space for ' + 'objects\n' + 'having very few instance variables. The space ' + 'consumption can become\n' + 'acute when creating large numbers of instances.\n' '\n' - 'The space saved over using *__dict__* can be ' - 'significant. Attribute\n' - 'lookup speed can be significantly improved as well.\n' + 'The default can be overridden by defining *__slots__* in ' + 'a new-style\n' + 'class definition. The *__slots__* declaration takes a ' + 'sequence of\n' + 'instance variables and reserves just enough space in ' + 'each instance to\n' + 'hold a value for each variable. Space is saved because ' + '*__dict__* is\n' + 'not created for each instance.\n' '\n' - 'object.__slots__\n' + '__slots__\n' '\n' ' This class variable can be assigned a string, ' 'iterable, or sequence\n' - ' of strings with variable names used by instances. ' - '*__slots__*\n' - ' reserves space for the declared variables and ' - 'prevents the\n' - ' automatic creation of *__dict__* and *__weakref__* ' - 'for each\n' - ' instance.\n' + ' of strings with variable names used by instances. If ' + 'defined in a\n' + ' new-style class, *__slots__* reserves space for the ' + 'declared\n' + ' variables and prevents the automatic creation of ' + '*__dict__* and\n' + ' *__weakref__* for each instance.\n' '\n' + ' New in version 2.2.\n' '\n' 'Notes on using *__slots__*\n' - '--------------------------\n' '\n' '* When inheriting from a class without *__slots__*, the ' '*__dict__*\n' - ' and *__weakref__* attribute of the instances will ' - 'always be\n' - ' accessible.\n' + ' attribute of that class will always be accessible, so ' + 'a *__slots__*\n' + ' definition in the subclass is meaningless.\n' '\n' '* Without a *__dict__* variable, instances cannot be ' 'assigned new\n' @@ -1029,6 +694,14 @@ topics = {'assert': 'The "assert" statement\n' '*__slots__*\n' ' declaration.\n' '\n' + ' Changed in version 2.3: Previously, adding ' + '"\'__dict__\'" to the\n' + ' *__slots__* declaration would not enable the ' + 'assignment of new\n' + ' attributes not specifically listed in the sequence of ' + 'instance\n' + ' variable names.\n' + '\n' '* Without a *__weakref__* variable for each instance, ' 'classes\n' ' defining *__slots__* do not support weak references to ' @@ -1039,6 +712,12 @@ topics = {'assert': 'The "assert" statement\n' '*__slots__*\n' ' declaration.\n' '\n' + ' Changed in version 2.3: Previously, adding ' + '"\'__weakref__\'" to the\n' + ' *__slots__* declaration would not enable support for ' + 'weak\n' + ' references.\n' + '\n' '* *__slots__* are implemented at the class level by ' 'creating\n' ' descriptors (Implementing Descriptors) for each ' @@ -1049,16 +728,13 @@ topics = {'assert': 'The "assert" statement\n' 'the class\n' ' attribute would overwrite the descriptor assignment.\n' '\n' - '* The action of a *__slots__* declaration is not limited ' - 'to the\n' - ' class where it is defined. *__slots__* declared in ' - 'parents are\n' - ' available in child classes. However, child subclasses ' - 'will get a\n' - ' *__dict__* and *__weakref__* unless they also define ' - '*__slots__*\n' - ' (which should only contain names of any *additional* ' - 'slots).\n' + '* The action of a *__slots__* declaration is limited to ' + 'the class\n' + ' where it is defined. As a result, subclasses will ' + 'have a *__dict__*\n' + ' unless they also define *__slots__* (which must only ' + 'contain names\n' + ' of any *additional* slots).\n' '\n' '* If a class defines a slot also defined in a base ' 'class, the\n' @@ -1072,8 +748,8 @@ topics = {'assert': 'The "assert" statement\n' '\n' '* Nonempty *__slots__* does not work for classes derived ' 'from\n' - ' “variable-length” built-in types such as "int", ' - '"bytes" and "tuple".\n' + ' "variable-length" built-in types such as "long", "str" ' + 'and "tuple".\n' '\n' '* Any non-string iterable may be assigned to ' '*__slots__*. Mappings\n' @@ -1085,20 +761,11 @@ topics = {'assert': 'The "assert" statement\n' 'the same\n' ' *__slots__*.\n' '\n' - '* Multiple inheritance with multiple slotted parent ' - 'classes can be\n' - ' used, but only one parent is allowed to have ' - 'attributes created by\n' - ' slots (the other bases must have empty slot layouts) - ' - 'violations\n' - ' raise "TypeError".\n' - '\n' - '* If an iterator is used for *__slots__* then a ' - 'descriptor is\n' - ' created for each of the iterator’s values. However, ' - 'the *__slots__*\n' - ' attribute will be an empty iterator.\n', - 'attribute-references': 'Attribute references\n' + ' Changed in version 2.6: Previously, *__class__* ' + 'assignment raised an\n' + ' error if either new or old class had *__slots__*.\n', + 'attribute-references': '\n' + 'Attribute references\n' '********************\n' '\n' 'An attribute reference is a primary followed by a ' @@ -1108,20 +775,20 @@ topics = {'assert': 'The "assert" statement\n' '\n' 'The primary must evaluate to an object of a type ' 'that supports\n' - 'attribute references, which most objects do. This ' - 'object is then\n' - 'asked to produce the attribute whose name is the ' - 'identifier. This\n' - 'production can be customized by overriding the ' - '"__getattr__()" method.\n' - 'If this attribute is not available, the exception ' - '"AttributeError" is\n' - 'raised. Otherwise, the type and value of the object ' - 'produced is\n' - 'determined by the object. Multiple evaluations of ' - 'the same attribute\n' - 'reference may yield different objects.\n', - 'augassign': 'Augmented assignment statements\n' + 'attribute references, e.g., a module, list, or an ' + 'instance. This\n' + 'object is then asked to produce the attribute whose ' + 'name is the\n' + 'identifier. If this attribute is not available, the ' + 'exception\n' + '"AttributeError" is raised. Otherwise, the type and ' + 'value of the\n' + 'object produced is determined by the object. ' + 'Multiple evaluations of\n' + 'the same attribute reference may yield different ' + 'objects.\n', + 'augassign': '\n' + 'Augmented assignment statements\n' '*******************************\n' '\n' 'Augmented assignment is the combination, in a single statement, ' @@ -1132,11 +799,11 @@ topics = {'assert': 'The "assert" statement\n' '(expression_list | yield_expression)\n' ' augtarget ::= identifier | attributeref | ' 'subscription | slicing\n' - ' augop ::= "+=" | "-=" | "*=" | "@=" | ' - '"/=" | "//=" | "%=" | "**="\n' + ' augop ::= "+=" | "-=" | "*=" | "/=" | ' + '"//=" | "%=" | "**="\n' ' | ">>=" | "<<=" | "&=" | "^=" | "|="\n' '\n' - '(See section Primaries for the syntax definitions of the last ' + '(See section Primaries for the syntax definitions for the last ' 'three\n' 'symbols.)\n' '\n' @@ -1162,14 +829,6 @@ topics = {'assert': 'The "assert" statement\n' 'object\n' 'is modified instead.\n' '\n' - 'Unlike normal assignments, augmented assignments evaluate the ' - 'left-\n' - 'hand side *before* evaluating the right-hand side. For ' - 'example, "a[i]\n' - '+= f(x)" first looks-up "a[i]", then it evaluates "f(x)" and ' - 'performs\n' - 'the addition, and lastly, it writes the result back to "a[i]".\n' - '\n' 'With the exception of assigning to tuples and multiple targets ' 'in a\n' 'single statement, the assignment done by augmented assignment\n' @@ -1185,16 +844,8 @@ topics = {'assert': 'The "assert" statement\n' 'about\n' 'class and instance attributes applies as for regular ' 'assignments.\n', - 'await': 'Await expression\n' - '****************\n' - '\n' - 'Suspend the execution of *coroutine* on an *awaitable* object. Can\n' - 'only be used inside a *coroutine function*.\n' - '\n' - ' await_expr ::= "await" primary\n' - '\n' - 'New in version 3.5.\n', - 'binary': 'Binary arithmetic operations\n' + 'binary': '\n' + 'Binary arithmetic operations\n' '****************************\n' '\n' 'The binary arithmetic operations have the conventional priority\n' @@ -1204,35 +855,28 @@ topics = {'assert': 'The "assert" statement\n' 'levels, one for multiplicative operators and one for additive\n' 'operators:\n' '\n' - ' m_expr ::= u_expr | m_expr "*" u_expr | m_expr "@" m_expr |\n' - ' m_expr "//" u_expr | m_expr "/" u_expr |\n' - ' m_expr "%" u_expr\n' + ' m_expr ::= u_expr | m_expr "*" u_expr | m_expr "//" u_expr | ' + 'm_expr "/" u_expr\n' + ' | m_expr "%" u_expr\n' ' a_expr ::= m_expr | a_expr "+" m_expr | a_expr "-" m_expr\n' '\n' 'The "*" (multiplication) operator yields the product of its ' 'arguments.\n' 'The arguments must either both be numbers, or one argument must be ' 'an\n' - 'integer and the other must be a sequence. In the former case, the\n' - 'numbers are converted to a common type and then multiplied ' - 'together.\n' - 'In the latter case, sequence repetition is performed; a negative\n' - 'repetition factor yields an empty sequence.\n' - '\n' - 'The "@" (at) operator is intended to be used for matrix\n' - 'multiplication. No builtin Python types implement this operator.\n' - '\n' - 'New in version 3.5.\n' + 'integer (plain or long) and the other must be a sequence. In the\n' + 'former case, the numbers are converted to a common type and then\n' + 'multiplied together. In the latter case, sequence repetition is\n' + 'performed; a negative repetition factor yields an empty sequence.\n' '\n' 'The "/" (division) and "//" (floor division) operators yield the\n' 'quotient of their arguments. The numeric arguments are first\n' - 'converted to a common type. Division of integers yields a float, ' - 'while\n' - 'floor division of integers results in an integer; the result is ' - 'that\n' - 'of mathematical division with the ‘floor’ function applied to the\n' - 'result. Division by zero raises the "ZeroDivisionError" ' - 'exception.\n' + 'converted to a common type. Plain or long integer division yields ' + 'an\n' + 'integer of the same type; the result is that of mathematical ' + 'division\n' + "with the 'floor' function applied to the result. Division by zero\n" + 'raises the "ZeroDivisionError" exception.\n' '\n' 'The "%" (modulo) operator yields the remainder from the division ' 'of\n' @@ -1248,41 +892,45 @@ topics = {'assert': 'The "assert" statement\n' 'as its second operand (or zero); the absolute value of the result ' 'is\n' 'strictly smaller than the absolute value of the second operand ' - '[1].\n' + '[2].\n' '\n' - 'The floor division and modulo operators are connected by the ' - 'following\n' - 'identity: "x == (x//y)*y + (x%y)". Floor division and modulo are ' - 'also\n' - 'connected with the built-in function "divmod()": "divmod(x, y) ==\n' - '(x//y, x%y)". [2].\n' + 'The integer division and modulo operators are connected by the\n' + 'following identity: "x == (x/y)*y + (x%y)". Integer division and\n' + 'modulo are also connected with the built-in function "divmod()":\n' + '"divmod(x, y) == (x/y, x%y)". These identities don\'t hold for\n' + 'floating point numbers; there similar identities hold ' + 'approximately\n' + 'where "x/y" is replaced by "floor(x/y)" or "floor(x/y) - 1" [3].\n' '\n' 'In addition to performing the modulo operation on numbers, the ' '"%"\n' - 'operator is also overloaded by string objects to perform ' - 'old-style\n' - 'string formatting (also known as interpolation). The syntax for\n' - 'string formatting is described in the Python Library Reference,\n' - 'section printf-style String Formatting.\n' + 'operator is also overloaded by string and unicode objects to ' + 'perform\n' + 'string formatting (also known as interpolation). The syntax for ' + 'string\n' + 'formatting is described in the Python Library Reference, section\n' + 'String Formatting Operations.\n' '\n' - 'The floor division operator, the modulo operator, and the ' - '"divmod()"\n' - 'function are not defined for complex numbers. Instead, convert to ' - 'a\n' - 'floating point number using the "abs()" function if appropriate.\n' + 'Deprecated since version 2.3: The floor division operator, the ' + 'modulo\n' + 'operator, and the "divmod()" function are no longer defined for\n' + 'complex numbers. Instead, convert to a floating point number ' + 'using\n' + 'the "abs()" function if appropriate.\n' '\n' - 'The "+" (addition) operator yields the sum of its arguments. The\n' - 'arguments must either both be numbers or both be sequences of the ' + 'The "+" (addition) operator yields the sum of its arguments. The\n' + 'arguments must either both be numbers or both sequences of the ' 'same\n' 'type. In the former case, the numbers are converted to a common ' 'type\n' - 'and then added together. In the latter case, the sequences are\n' + 'and then added together. In the latter case, the sequences are\n' 'concatenated.\n' '\n' 'The "-" (subtraction) operator yields the difference of its ' 'arguments.\n' 'The numeric arguments are first converted to a common type.\n', - 'bitwise': 'Binary bitwise operations\n' + 'bitwise': '\n' + 'Binary bitwise operations\n' '*************************\n' '\n' 'Each of the three bitwise operations has a different priority ' @@ -1294,74 +942,506 @@ topics = {'assert': 'The "assert" statement\n' '\n' 'The "&" operator yields the bitwise AND of its arguments, which ' 'must\n' - 'be integers.\n' + 'be plain or long integers. The arguments are converted to a ' + 'common\n' + 'type.\n' '\n' 'The "^" operator yields the bitwise XOR (exclusive OR) of its\n' - 'arguments, which must be integers.\n' + 'arguments, which must be plain or long integers. The arguments ' + 'are\n' + 'converted to a common type.\n' '\n' 'The "|" operator yields the bitwise (inclusive) OR of its ' 'arguments,\n' - 'which must be integers.\n', - 'bltin-code-objects': 'Code Objects\n' + 'which must be plain or long integers. The arguments are ' + 'converted to\n' + 'a common type.\n', + 'bltin-code-objects': '\n' + 'Code Objects\n' '************\n' '\n' 'Code objects are used by the implementation to ' - 'represent “pseudo-\n' - 'compiled” executable Python code such as a function ' + 'represent "pseudo-\n' + 'compiled" executable Python code such as a function ' 'body. They differ\n' - 'from function objects because they don’t contain a ' + "from function objects because they don't contain a " 'reference to their\n' 'global execution environment. Code objects are ' 'returned by the built-\n' 'in "compile()" function and can be extracted from ' 'function objects\n' - 'through their "__code__" attribute. See also the ' + 'through their "func_code" attribute. See also the ' '"code" module.\n' '\n' 'A code object can be executed or evaluated by passing ' 'it (instead of a\n' - 'source string) to the "exec()" or "eval()" built-in ' - 'functions.\n' + 'source string) to the "exec" statement or the built-in ' + '"eval()"\n' + 'function.\n' '\n' 'See The standard type hierarchy for more ' 'information.\n', - 'bltin-ellipsis-object': 'The Ellipsis Object\n' + 'bltin-ellipsis-object': '\n' + 'The Ellipsis Object\n' '*******************\n' '\n' - 'This object is commonly used by slicing (see ' - 'Slicings). It supports\n' - 'no special operations. There is exactly one ' - 'ellipsis object, named\n' - '"Ellipsis" (a built-in name). "type(Ellipsis)()" ' - 'produces the\n' - '"Ellipsis" singleton.\n' + 'This object is used by extended slice notation (see ' + 'Slicings). It\n' + 'supports no special operations. There is exactly ' + 'one ellipsis object,\n' + 'named "Ellipsis" (a built-in name).\n' '\n' - 'It is written as "Ellipsis" or "...".\n', - 'bltin-null-object': 'The Null Object\n' + 'It is written as "Ellipsis". When in a subscript, ' + 'it can also be\n' + 'written as "...", for example "seq[...]".\n', + 'bltin-file-objects': '\n' + 'File Objects\n' + '************\n' + '\n' + 'File objects are implemented using C\'s "stdio" ' + 'package and can be\n' + 'created with the built-in "open()" function. File ' + 'objects are also\n' + 'returned by some other built-in functions and methods, ' + 'such as\n' + '"os.popen()" and "os.fdopen()" and the "makefile()" ' + 'method of socket\n' + 'objects. Temporary files can be created using the ' + '"tempfile" module,\n' + 'and high-level file operations such as copying, ' + 'moving, and deleting\n' + 'files and directories can be achieved with the ' + '"shutil" module.\n' + '\n' + 'When a file operation fails for an I/O-related reason, ' + 'the exception\n' + '"IOError" is raised. This includes situations where ' + 'the operation is\n' + 'not defined for some reason, like "seek()" on a tty ' + 'device or writing\n' + 'a file opened for reading.\n' + '\n' + 'Files have the following methods:\n' + '\n' + 'file.close()\n' + '\n' + ' Close the file. A closed file cannot be read or ' + 'written any more.\n' + ' Any operation which requires that the file be open ' + 'will raise a\n' + ' "ValueError" after the file has been closed. ' + 'Calling "close()"\n' + ' more than once is allowed.\n' + '\n' + ' As of Python 2.5, you can avoid having to call this ' + 'method\n' + ' explicitly if you use the "with" statement. For ' + 'example, the\n' + ' following code will automatically close *f* when ' + 'the "with" block\n' + ' is exited:\n' + '\n' + ' from __future__ import with_statement # This ' + "isn't required in Python 2.6\n" + '\n' + ' with open("hello.txt") as f:\n' + ' for line in f:\n' + ' print line,\n' + '\n' + ' In older versions of Python, you would have needed ' + 'to do this to\n' + ' get the same effect:\n' + '\n' + ' f = open("hello.txt")\n' + ' try:\n' + ' for line in f:\n' + ' print line,\n' + ' finally:\n' + ' f.close()\n' + '\n' + ' Note: Not all "file-like" types in Python support ' + 'use as a\n' + ' context manager for the "with" statement. If ' + 'your code is\n' + ' intended to work with any file-like object, you ' + 'can use the\n' + ' function "contextlib.closing()" instead of using ' + 'the object\n' + ' directly.\n' + '\n' + 'file.flush()\n' + '\n' + ' Flush the internal buffer, like "stdio"\'s ' + '"fflush()". This may be\n' + ' a no-op on some file-like objects.\n' + '\n' + ' Note: "flush()" does not necessarily write the ' + "file's data to\n" + ' disk. Use "flush()" followed by "os.fsync()" to ' + 'ensure this\n' + ' behavior.\n' + '\n' + 'file.fileno()\n' + '\n' + ' Return the integer "file descriptor" that is used ' + 'by the underlying\n' + ' implementation to request I/O operations from the ' + 'operating system.\n' + ' This can be useful for other, lower level ' + 'interfaces that use file\n' + ' descriptors, such as the "fcntl" module or ' + '"os.read()" and friends.\n' + '\n' + ' Note: File-like objects which do not have a real ' + 'file descriptor\n' + ' should *not* provide this method!\n' + '\n' + 'file.isatty()\n' + '\n' + ' Return "True" if the file is connected to a ' + 'tty(-like) device, else\n' + ' "False".\n' + '\n' + ' Note: If a file-like object is not associated with ' + 'a real file,\n' + ' this method should *not* be implemented.\n' + '\n' + 'file.next()\n' + '\n' + ' A file object is its own iterator, for example ' + '"iter(f)" returns\n' + ' *f* (unless *f* is closed). When a file is used as ' + 'an iterator,\n' + ' typically in a "for" loop (for example, "for line ' + 'in f: print\n' + ' line.strip()"), the "next()" method is called ' + 'repeatedly. This\n' + ' method returns the next input line, or raises ' + '"StopIteration" when\n' + ' EOF is hit when the file is open for reading ' + '(behavior is undefined\n' + ' when the file is open for writing). In order to ' + 'make a "for" loop\n' + ' the most efficient way of looping over the lines of ' + 'a file (a very\n' + ' common operation), the "next()" method uses a ' + 'hidden read-ahead\n' + ' buffer. As a consequence of using a read-ahead ' + 'buffer, combining\n' + ' "next()" with other file methods (like ' + '"readline()") does not work\n' + ' right. However, using "seek()" to reposition the ' + 'file to an\n' + ' absolute position will flush the read-ahead ' + 'buffer.\n' + '\n' + ' New in version 2.3.\n' + '\n' + 'file.read([size])\n' + '\n' + ' Read at most *size* bytes from the file (less if ' + 'the read hits EOF\n' + ' before obtaining *size* bytes). If the *size* ' + 'argument is negative\n' + ' or omitted, read all data until EOF is reached. ' + 'The bytes are\n' + ' returned as a string object. An empty string is ' + 'returned when EOF\n' + ' is encountered immediately. (For certain files, ' + 'like ttys, it\n' + ' makes sense to continue reading after an EOF is ' + 'hit.) Note that\n' + ' this method may call the underlying C function ' + '"fread()" more than\n' + ' once in an effort to acquire as close to *size* ' + 'bytes as possible.\n' + ' Also note that when in non-blocking mode, less data ' + 'than was\n' + ' requested may be returned, even if no *size* ' + 'parameter was given.\n' + '\n' + ' Note: This function is simply a wrapper for the ' + 'underlying\n' + ' "fread()" C function, and will behave the same in ' + 'corner cases,\n' + ' such as whether the EOF value is cached.\n' + '\n' + 'file.readline([size])\n' + '\n' + ' Read one entire line from the file. A trailing ' + 'newline character\n' + ' is kept in the string (but may be absent when a ' + 'file ends with an\n' + ' incomplete line). [6] If the *size* argument is ' + 'present and non-\n' + ' negative, it is a maximum byte count (including the ' + 'trailing\n' + ' newline) and an incomplete line may be returned. ' + 'When *size* is not\n' + ' 0, an empty string is returned *only* when EOF is ' + 'encountered\n' + ' immediately.\n' + '\n' + ' Note: Unlike "stdio"\'s "fgets()", the returned ' + 'string contains\n' + ' null characters ("\'\\0\'") if they occurred in ' + 'the input.\n' + '\n' + 'file.readlines([sizehint])\n' + '\n' + ' Read until EOF using "readline()" and return a list ' + 'containing the\n' + ' lines thus read. If the optional *sizehint* ' + 'argument is present,\n' + ' instead of reading up to EOF, whole lines totalling ' + 'approximately\n' + ' *sizehint* bytes (possibly after rounding up to an ' + 'internal buffer\n' + ' size) are read. Objects implementing a file-like ' + 'interface may\n' + ' choose to ignore *sizehint* if it cannot be ' + 'implemented, or cannot\n' + ' be implemented efficiently.\n' + '\n' + 'file.xreadlines()\n' + '\n' + ' This method returns the same thing as "iter(f)".\n' + '\n' + ' New in version 2.1.\n' + '\n' + ' Deprecated since version 2.3: Use "for line in ' + 'file" instead.\n' + '\n' + 'file.seek(offset[, whence])\n' + '\n' + ' Set the file\'s current position, like "stdio"\'s ' + '"fseek()". The\n' + ' *whence* argument is optional and defaults to ' + '"os.SEEK_SET" or "0"\n' + ' (absolute file positioning); other values are ' + '"os.SEEK_CUR" or "1"\n' + ' (seek relative to the current position) and ' + '"os.SEEK_END" or "2"\n' + " (seek relative to the file's end). There is no " + 'return value.\n' + '\n' + ' For example, "f.seek(2, os.SEEK_CUR)" advances the ' + 'position by two\n' + ' and "f.seek(-3, os.SEEK_END)" sets the position to ' + 'the third to\n' + ' last.\n' + '\n' + ' Note that if the file is opened for appending (mode ' + '"\'a\'" or\n' + ' "\'a+\'"), any "seek()" operations will be undone ' + 'at the next write.\n' + ' If the file is only opened for writing in append ' + 'mode (mode "\'a\'"),\n' + ' this method is essentially a no-op, but it remains ' + 'useful for files\n' + ' opened in append mode with reading enabled (mode ' + '"\'a+\'"). If the\n' + ' file is opened in text mode (without "\'b\'"), only ' + 'offsets returned\n' + ' by "tell()" are legal. Use of other offsets causes ' + 'undefined\n' + ' behavior.\n' + '\n' + ' Note that not all file objects are seekable.\n' + '\n' + ' Changed in version 2.6: Passing float values as ' + 'offset has been\n' + ' deprecated.\n' + '\n' + 'file.tell()\n' + '\n' + " Return the file's current position, like " + '"stdio"\'s "ftell()".\n' + '\n' + ' Note: On Windows, "tell()" can return illegal ' + 'values (after an\n' + ' "fgets()") when reading files with Unix-style ' + 'line-endings. Use\n' + ' binary mode ("\'rb\'") to circumvent this ' + 'problem.\n' + '\n' + 'file.truncate([size])\n' + '\n' + " Truncate the file's size. If the optional *size* " + 'argument is\n' + ' present, the file is truncated to (at most) that ' + 'size. The size\n' + ' defaults to the current position. The current file ' + 'position is not\n' + ' changed. Note that if a specified size exceeds the ' + "file's current\n" + ' size, the result is platform-dependent: ' + 'possibilities include that\n' + ' the file may remain unchanged, increase to the ' + 'specified size as if\n' + ' zero-filled, or increase to the specified size with ' + 'undefined new\n' + ' content. Availability: Windows, many Unix ' + 'variants.\n' + '\n' + 'file.write(str)\n' + '\n' + ' Write a string to the file. There is no return ' + 'value. Due to\n' + ' buffering, the string may not actually show up in ' + 'the file until\n' + ' the "flush()" or "close()" method is called.\n' + '\n' + 'file.writelines(sequence)\n' + '\n' + ' Write a sequence of strings to the file. The ' + 'sequence can be any\n' + ' iterable object producing strings, typically a list ' + 'of strings.\n' + ' There is no return value. (The name is intended to ' + 'match\n' + ' "readlines()"; "writelines()" does not add line ' + 'separators.)\n' + '\n' + 'Files support the iterator protocol. Each iteration ' + 'returns the same\n' + 'result as "readline()", and iteration ends when the ' + '"readline()"\n' + 'method returns an empty string.\n' + '\n' + 'File objects also offer a number of other interesting ' + 'attributes.\n' + 'These are not required for file-like objects, but ' + 'should be\n' + 'implemented if they make sense for the particular ' + 'object.\n' + '\n' + 'file.closed\n' + '\n' + ' bool indicating the current state of the file ' + 'object. This is a\n' + ' read-only attribute; the "close()" method changes ' + 'the value. It may\n' + ' not be available on all file-like objects.\n' + '\n' + 'file.encoding\n' + '\n' + ' The encoding that this file uses. When Unicode ' + 'strings are written\n' + ' to a file, they will be converted to byte strings ' + 'using this\n' + ' encoding. In addition, when the file is connected ' + 'to a terminal,\n' + ' the attribute gives the encoding that the terminal ' + 'is likely to use\n' + ' (that information might be incorrect if the user ' + 'has misconfigured\n' + ' the terminal). The attribute is read-only and may ' + 'not be present\n' + ' on all file-like objects. It may also be "None", in ' + 'which case the\n' + ' file uses the system default encoding for ' + 'converting Unicode\n' + ' strings.\n' + '\n' + ' New in version 2.3.\n' + '\n' + 'file.errors\n' + '\n' + ' The Unicode error handler used along with the ' + 'encoding.\n' + '\n' + ' New in version 2.6.\n' + '\n' + 'file.mode\n' + '\n' + ' The I/O mode for the file. If the file was created ' + 'using the\n' + ' "open()" built-in function, this will be the value ' + 'of the *mode*\n' + ' parameter. This is a read-only attribute and may ' + 'not be present on\n' + ' all file-like objects.\n' + '\n' + 'file.name\n' + '\n' + ' If the file object was created using "open()", the ' + 'name of the\n' + ' file. Otherwise, some string that indicates the ' + 'source of the file\n' + ' object, of the form "<...>". This is a read-only ' + 'attribute and may\n' + ' not be present on all file-like objects.\n' + '\n' + 'file.newlines\n' + '\n' + ' If Python was built with *universal newlines* ' + 'enabled (the default)\n' + ' this read-only attribute exists, and for files ' + 'opened in universal\n' + ' newline read mode it keeps track of the types of ' + 'newlines\n' + ' encountered while reading the file. The values it ' + 'can take are\n' + ' "\'\\r\'", "\'\\n\'", "\'\\r\\n\'", "None" ' + '(unknown, no newlines read yet) or\n' + ' a tuple containing all the newline types seen, to ' + 'indicate that\n' + ' multiple newline conventions were encountered. For ' + 'files not opened\n' + ' in universal newlines read mode the value of this ' + 'attribute will be\n' + ' "None".\n' + '\n' + 'file.softspace\n' + '\n' + ' Boolean that indicates whether a space character ' + 'needs to be\n' + ' printed before another value when using the "print" ' + 'statement.\n' + ' Classes that are trying to simulate a file object ' + 'should also have\n' + ' a writable "softspace" attribute, which should be ' + 'initialized to\n' + ' zero. This will be automatic for most classes ' + 'implemented in\n' + ' Python (care may be needed for objects that ' + 'override attribute\n' + ' access); types implemented in C will have to ' + 'provide a writable\n' + ' "softspace" attribute.\n' + '\n' + ' Note: This attribute is not used to control the ' + '"print"\n' + ' statement, but to allow the implementation of ' + '"print" to keep\n' + ' track of its internal state.\n', + 'bltin-null-object': '\n' + 'The Null Object\n' '***************\n' '\n' - 'This object is returned by functions that don’t ' + "This object is returned by functions that don't " 'explicitly return a\n' 'value. It supports no special operations. There is ' 'exactly one null\n' - 'object, named "None" (a built-in name). "type(None)()" ' - 'produces the\n' - 'same singleton.\n' + 'object, named "None" (a built-in name).\n' '\n' 'It is written as "None".\n', - 'bltin-type-objects': 'Type Objects\n' + 'bltin-type-objects': '\n' + 'Type Objects\n' '************\n' '\n' 'Type objects represent the various object types. An ' - 'object’s type is\n' + "object's type is\n" 'accessed by the built-in function "type()". There are ' 'no special\n' 'operations on types. The standard module "types" ' 'defines names for\n' 'all standard built-in types.\n' '\n' - 'Types are written like this: "<class \'int\'>".\n', - 'booleans': 'Boolean operations\n' + 'Types are written like this: "<type \'int\'>".\n', + 'booleans': '\n' + 'Boolean operations\n' '******************\n' '\n' ' or_test ::= and_test | or_test "or" and_test\n' @@ -1376,9 +1456,9 @@ topics = {'assert': 'The "assert" statement\n' 'strings and containers (including strings, tuples, lists,\n' 'dictionaries, sets and frozensets). All other values are ' 'interpreted\n' - 'as true. User-defined objects can customize their truth value ' - 'by\n' - 'providing a "__bool__()" method.\n' + 'as true. (See the "__nonzero__()" special method for a way to ' + 'change\n' + 'this.)\n' '\n' 'The operator "not" yields "True" if its argument is false, ' '"False"\n' @@ -1396,21 +1476,22 @@ topics = {'assert': 'The "assert" statement\n' 'is\n' 'returned.\n' '\n' - 'Note that neither "and" nor "or" restrict the value and type ' + '(Note that neither "and" nor "or" restrict the value and type ' 'they\n' 'return to "False" and "True", but rather return the last ' 'evaluated\n' - 'argument. This is sometimes useful, e.g., if "s" is a string ' + 'argument. This is sometimes useful, e.g., if "s" is a string ' 'that\n' 'should be replaced by a default value if it is empty, the ' 'expression\n' '"s or \'foo\'" yields the desired value. Because "not" has to ' - 'create a\n' - 'new value, it returns a boolean value regardless of the type of ' - 'its\n' - 'argument (for example, "not \'foo\'" produces "False" rather ' - 'than "\'\'".)\n', - 'break': 'The "break" statement\n' + 'invent a\n' + 'value anyway, it does not bother to return a value of the same ' + 'type as\n' + 'its argument, so e.g., "not \'foo\'" yields "False", not ' + '"\'\'".)\n', + 'break': '\n' + 'The "break" statement\n' '*********************\n' '\n' ' break_stmt ::= "break"\n' @@ -1431,49 +1512,52 @@ topics = {'assert': 'The "assert" statement\n' 'clause, that "finally" clause is executed before really leaving ' 'the\n' 'loop.\n', - 'callable-types': 'Emulating callable objects\n' + 'callable-types': '\n' + 'Emulating callable objects\n' '**************************\n' '\n' 'object.__call__(self[, args...])\n' '\n' - ' Called when the instance is “called” as a function; if ' + ' Called when the instance is "called" as a function; if ' 'this method\n' ' is defined, "x(arg1, arg2, ...)" is a shorthand for\n' ' "x.__call__(arg1, arg2, ...)".\n', - 'calls': 'Calls\n' + 'calls': '\n' + 'Calls\n' '*****\n' '\n' 'A call calls a callable object (e.g., a *function*) with a ' 'possibly\n' 'empty series of *arguments*:\n' '\n' - ' call ::= primary "(" [argument_list [","] | ' - 'comprehension] ")"\n' + ' call ::= primary "(" [argument_list [","]\n' + ' | expression genexpr_for] ")"\n' ' argument_list ::= positional_arguments ["," ' - 'starred_and_keywords]\n' - ' ["," keywords_arguments]\n' - ' | starred_and_keywords ["," ' - 'keywords_arguments]\n' - ' | keywords_arguments\n' - ' positional_arguments ::= ["*"] expression ("," ["*"] ' - 'expression)*\n' - ' starred_and_keywords ::= ("*" expression | keyword_item)\n' - ' ("," "*" expression | "," ' - 'keyword_item)*\n' - ' keywords_arguments ::= (keyword_item | "**" expression)\n' - ' ("," keyword_item | "," "**" ' - 'expression)*\n' + 'keyword_arguments]\n' + ' ["," "*" expression] ["," ' + 'keyword_arguments]\n' + ' ["," "**" expression]\n' + ' | keyword_arguments ["," "*" expression]\n' + ' ["," "**" expression]\n' + ' | "*" expression ["," keyword_arguments] ["," ' + '"**" expression]\n' + ' | "**" expression\n' + ' positional_arguments ::= expression ("," expression)*\n' + ' keyword_arguments ::= keyword_item ("," keyword_item)*\n' ' keyword_item ::= identifier "=" expression\n' '\n' - 'An optional trailing comma may be present after the positional and\n' - 'keyword arguments but does not affect the semantics.\n' + 'A trailing comma may be present after the positional and keyword\n' + 'arguments but does not affect the semantics.\n' '\n' 'The primary must evaluate to a callable object (user-defined\n' 'functions, built-in functions, methods of built-in objects, class\n' - 'objects, methods of class instances, and all objects having a\n' - '"__call__()" method are callable). All argument expressions are\n' - 'evaluated before the call is attempted. Please refer to section\n' - 'Function definitions for the syntax of formal *parameter* lists.\n' + 'objects, methods of class instances, and certain class instances\n' + 'themselves are callable; extensions may define additional callable\n' + 'object types). All argument expressions are evaluated before the ' + 'call\n' + 'is attempted. Please refer to section Function definitions for ' + 'the\n' + 'syntax of formal *parameter* lists.\n' '\n' 'If keyword arguments are present, they are first converted to\n' 'positional arguments, as follows. First, a list of unfilled slots ' @@ -1496,7 +1580,7 @@ topics = {'assert': 'The "assert" statement\n' 'values are calculated, once, when the function is defined; thus, a\n' 'mutable object such as a list or dictionary used as default value ' 'will\n' - 'be shared by all calls that don’t specify an argument value for ' + "be shared by all calls that don't specify an argument value for " 'the\n' 'corresponding slot; this should usually be avoided.) If there are ' 'any\n' @@ -1509,7 +1593,7 @@ topics = {'assert': 'The "assert" statement\n' '**CPython implementation detail:** An implementation may provide\n' 'built-in functions whose positional parameters do not have names, ' 'even\n' - 'if they are ‘named’ for the purpose of documentation, and which\n' + "if they are 'named' for the purpose of documentation, and which\n" 'therefore cannot be supplied by keyword. In CPython, this is the ' 'case\n' 'for functions implemented in C that use "PyArg_ParseTuple()" to ' @@ -1538,25 +1622,23 @@ topics = {'assert': 'The "assert" statement\n' '\n' 'If the syntax "*expression" appears in the function call, ' '"expression"\n' - 'must evaluate to an *iterable*. Elements from these iterables are\n' - 'treated as if they were additional positional arguments. For the ' - 'call\n' - '"f(x1, x2, *y, x3, x4)", if *y* evaluates to a sequence *y1*, …, ' - '*yM*,\n' - 'this is equivalent to a call with M+4 positional arguments *x1*, ' - '*x2*,\n' - '*y1*, …, *yM*, *x3*, *x4*.\n' + 'must evaluate to an iterable. Elements from this iterable are ' + 'treated\n' + 'as if they were additional positional arguments; if there are\n' + 'positional arguments *x1*, ..., *xN*, and "expression" evaluates to ' + 'a\n' + 'sequence *y1*, ..., *yM*, this is equivalent to a call with M+N\n' + 'positional arguments *x1*, ..., *xN*, *y1*, ..., *yM*.\n' '\n' 'A consequence of this is that although the "*expression" syntax ' 'may\n' - 'appear *after* explicit keyword arguments, it is processed ' - '*before*\n' - 'the keyword arguments (and any "**expression" arguments – see ' - 'below).\n' - 'So:\n' + 'appear *after* some keyword arguments, it is processed *before* ' + 'the\n' + 'keyword arguments (and the "**expression" argument, if any -- see\n' + 'below). So:\n' '\n' ' >>> def f(a, b):\n' - ' ... print(a, b)\n' + ' ... print a, b\n' ' ...\n' ' >>> f(b=1, *(2,))\n' ' 2 1\n' @@ -1574,31 +1656,28 @@ topics = {'assert': 'The "assert" statement\n' 'arise.\n' '\n' 'If the syntax "**expression" appears in the function call,\n' - '"expression" must evaluate to a *mapping*, the contents of which ' - 'are\n' - 'treated as additional keyword arguments. If a keyword is already\n' - 'present (as an explicit keyword argument, or from another ' - 'unpacking),\n' - 'a "TypeError" exception is raised.\n' + '"expression" must evaluate to a mapping, the contents of which are\n' + 'treated as additional keyword arguments. In the case of a keyword\n' + 'appearing in both "expression" and as an explicit keyword argument, ' + 'a\n' + '"TypeError" exception is raised.\n' '\n' 'Formal parameters using the syntax "*identifier" or "**identifier"\n' 'cannot be used as positional argument slots or as keyword argument\n' - 'names.\n' - '\n' - 'Changed in version 3.5: Function calls accept any number of "*" ' - 'and\n' - '"**" unpackings, positional arguments may follow iterable ' - 'unpackings\n' - '("*"), and keyword arguments may follow dictionary unpackings ' - '("**").\n' - 'Originally proposed by **PEP 448**.\n' + 'names. Formal parameters using the syntax "(sublist)" cannot be ' + 'used\n' + 'as keyword argument names; the outermost sublist corresponds to a\n' + 'single unnamed argument slot, and the argument value is assigned ' + 'to\n' + 'the sublist using the usual tuple assignment rules after all other\n' + 'parameter processing is done.\n' '\n' 'A call always returns some value, possibly "None", unless it raises ' 'an\n' 'exception. How this value is computed depends on the type of the\n' 'callable object.\n' '\n' - 'If it is—\n' + 'If it is---\n' '\n' 'a user-defined function:\n' ' The code block for the function is executed, passing it the\n' @@ -1628,103 +1707,83 @@ topics = {'assert': 'The "assert" statement\n' ' The class must define a "__call__()" method; the effect is then ' 'the\n' ' same as if that method was called.\n', - 'class': 'Class definitions\n' + 'class': '\n' + 'Class definitions\n' '*****************\n' '\n' 'A class definition defines a class object (see section The ' 'standard\n' 'type hierarchy):\n' '\n' - ' classdef ::= [decorators] "class" classname [inheritance] ":" ' - 'suite\n' - ' inheritance ::= "(" [argument_list] ")"\n' + ' classdef ::= "class" classname [inheritance] ":" suite\n' + ' inheritance ::= "(" [expression_list] ")"\n' ' classname ::= identifier\n' '\n' - 'A class definition is an executable statement. The inheritance ' - 'list\n' - 'usually gives a list of base classes (see Metaclasses for more\n' - 'advanced uses), so each item in the list should evaluate to a ' - 'class\n' - 'object which allows subclassing. Classes without an inheritance ' + 'A class definition is an executable statement. It first evaluates ' + 'the\n' + 'inheritance list, if present. Each item in the inheritance list\n' + 'should evaluate to a class object or class type which allows\n' + "subclassing. The class's suite is then executed in a new " + 'execution\n' + 'frame (see section Naming and binding), using a newly created ' + 'local\n' + 'namespace and the original global namespace. (Usually, the suite\n' + "contains only function definitions.) When the class's suite " + 'finishes\n' + 'execution, its execution frame is discarded but its local namespace ' + 'is\n' + 'saved. [4] A class object is then created using the inheritance ' 'list\n' - 'inherit, by default, from the base class "object"; hence,\n' - '\n' - ' class Foo:\n' - ' pass\n' - '\n' - 'is equivalent to\n' - '\n' - ' class Foo(object):\n' - ' pass\n' - '\n' - 'The class’s suite is then executed in a new execution frame (see\n' - 'Naming and binding), using a newly created local namespace and the\n' - 'original global namespace. (Usually, the suite contains mostly\n' - 'function definitions.) When the class’s suite finishes execution, ' - 'its\n' - 'execution frame is discarded but its local namespace is saved. [3] ' - 'A\n' - 'class object is then created using the inheritance list for the ' - 'base\n' - 'classes and the saved local namespace for the attribute ' - 'dictionary.\n' - 'The class name is bound to this class object in the original local\n' - 'namespace.\n' - '\n' - 'The order in which attributes are defined in the class body is\n' - 'preserved in the new class’s "__dict__". Note that this is ' - 'reliable\n' - 'only right after the class is created and only for classes that ' - 'were\n' - 'defined using the definition syntax.\n' - '\n' - 'Class creation can be customized heavily using metaclasses.\n' - '\n' - 'Classes can also be decorated: just like when decorating ' - 'functions,\n' - '\n' - ' @f1(arg)\n' - ' @f2\n' - ' class Foo: pass\n' - '\n' - 'is roughly equivalent to\n' + 'for the base classes and the saved local namespace for the ' + 'attribute\n' + 'dictionary. The class name is bound to this class object in the\n' + 'original local namespace.\n' '\n' - ' class Foo: pass\n' - ' Foo = f1(arg)(f2(Foo))\n' + "**Programmer's note:** Variables defined in the class definition " + 'are\n' + 'class variables; they are shared by all instances. To create ' + 'instance\n' + 'variables, they can be set in a method with "self.name = value". ' + 'Both\n' + 'class and instance variables are accessible through the notation\n' + '""self.name"", and an instance variable hides a class variable ' + 'with\n' + 'the same name when accessed in this way. Class variables can be ' + 'used\n' + 'as defaults for instance variables, but using mutable values there ' + 'can\n' + 'lead to unexpected results. For *new-style class*es, descriptors ' + 'can\n' + 'be used to create instance variables with different implementation\n' + 'details.\n' + '\n' + 'Class definitions, like function definitions, may be wrapped by one ' + 'or\n' + 'more *decorator* expressions. The evaluation rules for the ' + 'decorator\n' + 'expressions are the same as for functions. The result must be a ' + 'class\n' + 'object, which is then bound to the class name.\n' '\n' - 'The evaluation rules for the decorator expressions are the same as ' - 'for\n' - 'function decorators. The result is then bound to the class name.\n' + '-[ Footnotes ]-\n' '\n' - '**Programmer’s note:** Variables defined in the class definition ' - 'are\n' - 'class attributes; they are shared by instances. Instance ' - 'attributes\n' - 'can be set in a method with "self.name = value". Both class and\n' - 'instance attributes are accessible through the notation ' - '“"self.name"”,\n' - 'and an instance attribute hides a class attribute with the same ' - 'name\n' - 'when accessed in this way. Class attributes can be used as ' - 'defaults\n' - 'for instance attributes, but using mutable values there can lead ' - 'to\n' - 'unexpected results. Descriptors can be used to create instance\n' - 'variables with different implementation details.\n' + '[1] The exception is propagated to the invocation stack unless\n' + ' there is a "finally" clause which happens to raise another\n' + ' exception. That new exception causes the old one to be lost.\n' '\n' - 'See also:\n' + '[2] Currently, control "flows off the end" except in the case of\n' + ' an exception or the execution of a "return", "continue", or\n' + ' "break" statement.\n' '\n' - ' **PEP 3115** - Metaclasses in Python 3000\n' - ' The proposal that changed the declaration of metaclasses to ' - 'the\n' - ' current syntax, and the semantics for how classes with\n' - ' metaclasses are constructed.\n' + '[3] A string literal appearing as the first statement in the\n' + ' function body is transformed into the function\'s "__doc__"\n' + " attribute and therefore the function's *docstring*.\n" '\n' - ' **PEP 3129** - Class Decorators\n' - ' The proposal that added class decorators. Function and ' - 'method\n' - ' decorators were introduced in **PEP 318**.\n', - 'comparisons': 'Comparisons\n' + '[4] A string literal appearing as the first statement in the class\n' + ' body is transformed into the namespace\'s "__doc__" item and\n' + " therefore the class's *docstring*.\n", + 'comparisons': '\n' + 'Comparisons\n' '***********\n' '\n' 'Unlike C, all comparison operations in Python have the same ' @@ -1735,8 +1794,9 @@ topics = {'assert': 'The "assert" statement\n' 'the\n' 'interpretation that is conventional in mathematics:\n' '\n' - ' comparison ::= or_expr (comp_operator or_expr)*\n' - ' comp_operator ::= "<" | ">" | "==" | ">=" | "<=" | "!="\n' + ' comparison ::= or_expr ( comp_operator or_expr )*\n' + ' comp_operator ::= "<" | ">" | "==" | ">=" | "<=" | "<>" | ' + '"!="\n' ' | "is" ["not"] | ["not"] "in"\n' '\n' 'Comparisons yield boolean values: "True" or "False".\n' @@ -1749,20 +1809,26 @@ topics = {'assert': 'The "assert" statement\n' 'y" is\n' 'found to be false).\n' '\n' - 'Formally, if *a*, *b*, *c*, …, *y*, *z* are expressions and ' + 'Formally, if *a*, *b*, *c*, ..., *y*, *z* are expressions and ' '*op1*,\n' - '*op2*, …, *opN* are comparison operators, then "a op1 b op2 c ' - '... y\n' + '*op2*, ..., *opN* are comparison operators, then "a op1 b op2 ' + 'c ... y\n' 'opN z" is equivalent to "a op1 b and b op2 c and ... y opN ' 'z", except\n' 'that each expression is evaluated at most once.\n' '\n' - 'Note that "a op1 b op2 c" doesn’t imply any kind of ' + 'Note that "a op1 b op2 c" doesn\'t imply any kind of ' 'comparison between\n' '*a* and *c*, so that, e.g., "x < y > z" is perfectly legal ' '(though\n' 'perhaps not pretty).\n' '\n' + 'The forms "<>" and "!=" are equivalent; for consistency with ' + 'C, "!="\n' + 'is preferred; where "!=" is mentioned below "<>" is also ' + 'accepted.\n' + 'The "<>" spelling is considered obsolescent.\n' + '\n' '\n' 'Value comparisons\n' '=================\n' @@ -1778,7 +1844,7 @@ topics = {'assert': 'The "assert" statement\n' 'rather\n' 'abstract notion in Python: For example, there is no canonical ' 'access\n' - 'method for an object’s value. Also, there is no requirement ' + "method for an object's value. Also, there is no requirement " 'that the\n' 'value of an object should be constructed in a particular way, ' 'e.g.\n' @@ -1790,13 +1856,11 @@ topics = {'assert': 'The "assert" statement\n' 'of their\n' 'comparison implementation.\n' '\n' - 'Because all types are (direct or indirect) subtypes of ' - '"object", they\n' - 'inherit the default comparison behavior from "object". Types ' - 'can\n' - 'customize their comparison behavior by implementing *rich ' - 'comparison\n' - 'methods* like "__lt__()", described in Basic customization.\n' + 'Types can customize their comparison behavior by implementing ' + 'a\n' + '"__cmp__()" method or *rich comparison methods* like ' + '"__lt__()",\n' + 'described in Basic customization.\n' '\n' 'The default behavior for equality comparison ("==" and "!=") ' 'is based\n' @@ -1810,11 +1874,17 @@ topics = {'assert': 'The "assert" statement\n' 'all objects should be reflexive (i.e. "x is y" implies "x == ' 'y").\n' '\n' - 'A default order comparison ("<", ">", "<=", and ">=") is not ' - 'provided;\n' - 'an attempt raises "TypeError". A motivation for this default ' - 'behavior\n' - 'is the lack of a similar invariant as for equality.\n' + 'The default order comparison ("<", ">", "<=", and ">=") gives ' + 'a\n' + 'consistent but arbitrary order.\n' + '\n' + '(This unusual definition of comparison was used to simplify ' + 'the\n' + 'definition of operations like sorting and the "in" and "not ' + 'in"\n' + 'operators. In the future, the comparison rules for objects ' + 'of\n' + 'different types are likely to change.)\n' '\n' 'The behavior of the default equality comparison, that ' 'instances with\n' @@ -1832,68 +1902,58 @@ topics = {'assert': 'The "assert" statement\n' 'most\n' 'important built-in types.\n' '\n' - '* Numbers of built-in numeric types (Numeric Types — int, ' + '* Numbers of built-in numeric types (Numeric Types --- int, ' 'float,\n' - ' complex) and of the standard library types ' - '"fractions.Fraction" and\n' - ' "decimal.Decimal" can be compared within and across their ' - 'types,\n' - ' with the restriction that complex numbers do not support ' - 'order\n' - ' comparison. Within the limits of the types involved, they ' - 'compare\n' - ' mathematically (algorithmically) correct without loss of ' - 'precision.\n' - '\n' - ' The not-a-number values "float(\'NaN\')" and ' - '"decimal.Decimal(\'NaN\')"\n' - ' are special. Any ordered comparison of a number to a ' - 'not-a-number\n' - ' value is false. A counter-intuitive implication is that ' - 'not-a-number\n' - ' values are not equal to themselves. For example, if "x =\n' - ' float(\'NaN\')", "3 < x", "x < 3", "x == x", "x != x" are ' - 'all false.\n' - ' This behavior is compliant with IEEE 754.\n' - '\n' - '* "None" and "NotImplemented" are singletons. **PEP 8** ' - 'advises\n' - ' that comparisons for singletons should always be done with ' - '"is" or\n' - ' "is not", never the equality operators.\n' - '\n' - '* Binary sequences (instances of "bytes" or "bytearray") can ' - 'be\n' - ' compared within and across their types. They compare\n' - ' lexicographically using the numeric values of their ' - 'elements.\n' + ' long, complex) and of the standard library types\n' + ' "fractions.Fraction" and "decimal.Decimal" can be compared ' + 'within\n' + ' and across their types, with the restriction that complex ' + 'numbers do\n' + ' not support order comparison. Within the limits of the ' + 'types\n' + ' involved, they compare mathematically (algorithmically) ' + 'correct\n' + ' without loss of precision.\n' '\n' - '* Strings (instances of "str") compare lexicographically ' - 'using the\n' - ' numerical Unicode code points (the result of the built-in ' - 'function\n' - ' "ord()") of their characters. [3]\n' + '* Strings (instances of "str" or "unicode") compare\n' + ' lexicographically using the numeric equivalents (the result ' + 'of the\n' + ' built-in function "ord()") of their characters. [4] When ' + 'comparing\n' + ' an 8-bit string and a Unicode string, the 8-bit string is ' + 'converted\n' + ' to Unicode. If the conversion fails, the strings are ' + 'considered\n' + ' unequal.\n' '\n' - ' Strings and binary sequences cannot be directly compared.\n' + '* Instances of "tuple" or "list" can be compared only within ' + 'each of\n' + ' their types. Equality comparison across these types ' + 'results in\n' + ' unequality, and ordering comparison across these types ' + 'gives an\n' + ' arbitrary order.\n' '\n' - '* Sequences (instances of "tuple", "list", or "range") can ' - 'be\n' - ' compared only within each of their types, with the ' - 'restriction that\n' - ' ranges do not support order comparison. Equality ' - 'comparison across\n' - ' these types results in inequality, and ordering comparison ' - 'across\n' - ' these types raises "TypeError".\n' + ' These sequences compare lexicographically using comparison ' + 'of\n' + ' corresponding elements, whereby reflexivity of the elements ' + 'is\n' + ' enforced.\n' '\n' - ' Sequences compare lexicographically using comparison of\n' - ' corresponding elements. The built-in containers typically ' - 'assume\n' - ' identical objects are equal to themselves. That lets them ' - 'bypass\n' - ' equality tests for identical objects to improve performance ' - 'and to\n' - ' maintain their internal invariants.\n' + ' In enforcing reflexivity of elements, the comparison of ' + 'collections\n' + ' assumes that for a collection element "x", "x == x" is ' + 'always true.\n' + ' Based on that assumption, element identity is compared ' + 'first, and\n' + ' element comparison is performed only for distinct ' + 'elements. This\n' + ' approach yields the same result as a strict element ' + 'comparison\n' + ' would, if the compared elements are reflexive. For ' + 'non-reflexive\n' + ' elements, the result is different than for strict element\n' + ' comparison.\n' '\n' ' Lexicographical comparison between built-in collections ' 'works as\n' @@ -1907,15 +1967,15 @@ topics = {'assert': 'The "assert" statement\n' '(1,2)" is\n' ' false because the type is not the same).\n' '\n' - ' * Collections that support order comparison are ordered the ' - 'same\n' - ' as their first unequal elements (for example, "[1,2,x] <= ' - '[1,2,y]"\n' - ' has the same value as "x <= y"). If a corresponding ' - 'element does\n' - ' not exist, the shorter collection is ordered first (for ' - 'example,\n' - ' "[1,2] < [1,2,3]" is true).\n' + ' * Collections are ordered the same as their first unequal ' + 'elements\n' + ' (for example, "cmp([1,2,x], [1,2,y])" returns the same ' + 'as\n' + ' "cmp(x,y)"). If a corresponding element does not exist, ' + 'the\n' + ' shorter collection is ordered first (for example, "[1,2] ' + '<\n' + ' [1,2,3]" is true).\n' '\n' '* Mappings (instances of "dict") compare equal if and only if ' 'they\n' @@ -1923,32 +1983,16 @@ topics = {'assert': 'The "assert" statement\n' 'keys and\n' ' values enforces reflexivity.\n' '\n' - ' Order comparisons ("<", ">", "<=", and ">=") raise ' - '"TypeError".\n' - '\n' - '* Sets (instances of "set" or "frozenset") can be compared ' - 'within\n' - ' and across their types.\n' - '\n' - ' They define order comparison operators to mean subset and ' - 'superset\n' - ' tests. Those relations do not define total orderings (for ' - 'example,\n' - ' the two sets "{1,2}" and "{2,3}" are not equal, nor subsets ' - 'of one\n' - ' another, nor supersets of one another). Accordingly, sets ' + ' Outcomes other than equality are resolved consistently, but ' 'are not\n' - ' appropriate arguments for functions which depend on total ' - 'ordering\n' - ' (for example, "min()", "max()", and "sorted()" produce ' - 'undefined\n' - ' results given a list of sets as inputs).\n' - '\n' - ' Comparison of sets enforces reflexivity of its elements.\n' + ' otherwise defined. [5]\n' '\n' - '* Most other built-in types have no comparison methods ' - 'implemented,\n' - ' so they inherit the default comparison behavior.\n' + '* Most other objects of built-in types compare unequal unless ' + 'they\n' + ' are the same object; the choice whether one object is ' + 'considered\n' + ' smaller or larger than another one is made arbitrarily but\n' + ' consistently within one execution of a program.\n' '\n' 'User-defined classes that customize their comparison behavior ' 'should\n' @@ -2002,10 +2046,7 @@ topics = {'assert': 'The "assert" statement\n' 'be marked\n' ' as unhashable.\n' '\n' - 'Python does not enforce these consistency rules. In fact, ' - 'the\n' - 'not-a-number values are an example for not following these ' - 'rules.\n' + 'Python does not enforce these consistency rules.\n' '\n' '\n' 'Membership test operations\n' @@ -2042,26 +2083,25 @@ topics = {'assert': 'The "assert" statement\n' '\n' 'For user-defined classes which do not define "__contains__()" ' 'but do\n' - 'define "__iter__()", "x in y" is "True" if some value "z", ' - 'for which\n' - 'the expression "x is z or x == z" is true, is produced while ' - 'iterating\n' - 'over "y". If an exception is raised during the iteration, it ' - 'is as if\n' - '"in" raised that exception.\n' + 'define "__iter__()", "x in y" is "True" if some value "z" ' + 'with "x ==\n' + 'z" is produced while iterating over "y". If an exception is ' + 'raised\n' + 'during the iteration, it is as if "in" raised that ' + 'exception.\n' '\n' 'Lastly, the old-style iteration protocol is tried: if a class ' 'defines\n' '"__getitem__()", "x in y" is "True" if and only if there is a ' 'non-\n' - 'negative integer index *i* such that "x is y[i] or x == ' - 'y[i]", and no\n' - 'lower integer index raises the "IndexError" exception. (If ' - 'any other\n' + 'negative integer index *i* such that "x == y[i]", and all ' + 'lower\n' + 'integer indices do not raise "IndexError" exception. (If any ' + 'other\n' 'exception is raised, it is as if "in" raised that ' 'exception).\n' '\n' - 'The operator "not in" is defined to have the inverse truth ' + 'The operator "not in" is defined to have the inverse true ' 'value of\n' '"in".\n' '\n' @@ -2069,14 +2109,13 @@ topics = {'assert': 'The "assert" statement\n' 'Identity comparisons\n' '====================\n' '\n' - 'The operators "is" and "is not" test for an object’s ' - 'identity: "x is\n' - 'y" is true if and only if *x* and *y* are the same object. ' - 'An\n' - 'Object’s identity is determined using the "id()" function. ' - '"x is not\n' - 'y" yields the inverse truth value. [4]\n', - 'compound': 'Compound statements\n' + 'The operators "is" and "is not" test for object identity: "x ' + 'is y" is\n' + 'true if and only if *x* and *y* are the same object. "x is ' + 'not y"\n' + 'yields the inverse truth value. [6]\n', + 'compound': '\n' + 'Compound statements\n' '*******************\n' '\n' 'Compound statements contain (groups of) other statements; they ' @@ -2092,17 +2131,12 @@ topics = {'assert': 'The "assert" statement\n' 'control\n' 'flow constructs. "try" specifies exception handlers and/or ' 'cleanup\n' - 'code for a group of statements, while the "with" statement ' - 'allows the\n' - 'execution of initialization and finalization code around a block ' - 'of\n' - 'code. Function and class definitions are also syntactically ' - 'compound\n' - 'statements.\n' + 'code for a group of statements. Function and class definitions ' + 'are\n' + 'also syntactically compound statements.\n' '\n' - 'A compound statement consists of one or more ‘clauses.’ A ' - 'clause\n' - 'consists of a header and a ‘suite.’ The clause headers of a\n' + "Compound statements consist of one or more 'clauses.' A clause\n" + "consists of a header and a 'suite.' The clause headers of a\n" 'particular compound statement are all at the same indentation ' 'level.\n' 'Each clause header begins with a uniquely identifying keyword ' @@ -2110,25 +2144,25 @@ topics = {'assert': 'The "assert" statement\n' 'with a colon. A suite is a group of statements controlled by a\n' 'clause. A suite can be one or more semicolon-separated simple\n' 'statements on the same line as the header, following the ' - 'header’s\n' + "header's\n" 'colon, or it can be one or more indented statements on ' 'subsequent\n' - 'lines. Only the latter form of a suite can contain nested ' + 'lines. Only the latter form of suite can contain nested ' 'compound\n' - 'statements; the following is illegal, mostly because it wouldn’t ' + "statements; the following is illegal, mostly because it wouldn't " 'be\n' 'clear to which "if" clause a following "else" clause would ' 'belong:\n' '\n' - ' if test1: if test2: print(x)\n' + ' if test1: if test2: print x\n' '\n' 'Also note that the semicolon binds tighter than the colon in ' 'this\n' 'context, so that in the following example, either all or none of ' 'the\n' - '"print()" calls are executed:\n' + '"print" statements are executed:\n' '\n' - ' if x < y < z: print(x); print(y); print(z)\n' + ' if x < y < z: print x; print y; print z\n' '\n' 'Summarizing:\n' '\n' @@ -2139,9 +2173,7 @@ topics = {'assert': 'The "assert" statement\n' ' | with_stmt\n' ' | funcdef\n' ' | classdef\n' - ' | async_with_stmt\n' - ' | async_for_stmt\n' - ' | async_funcdef\n' + ' | decorated\n' ' suite ::= stmt_list NEWLINE | NEWLINE INDENT ' 'statement+ DEDENT\n' ' statement ::= stmt_list NEWLINE | compound_stmt\n' @@ -2149,10 +2181,10 @@ topics = {'assert': 'The "assert" statement\n' '\n' 'Note that statements always end in a "NEWLINE" possibly followed ' 'by a\n' - '"DEDENT". Also note that optional continuation clauses always ' + '"DEDENT". Also note that optional continuation clauses always ' 'begin\n' 'with a keyword that cannot start a statement, thus there are no\n' - 'ambiguities (the ‘dangling "else"’ problem is solved in Python ' + 'ambiguities (the \'dangling "else"\' problem is solved in Python ' 'by\n' 'requiring nested "if" statements to be indented).\n' '\n' @@ -2167,7 +2199,7 @@ topics = {'assert': 'The "assert" statement\n' 'The "if" statement is used for conditional execution:\n' '\n' ' if_stmt ::= "if" expression ":" suite\n' - ' ("elif" expression ":" suite)*\n' + ' ( "elif" expression ":" suite )*\n' ' ["else" ":" suite]\n' '\n' 'It selects exactly one of the suites by evaluating the ' @@ -2203,7 +2235,7 @@ topics = {'assert': 'The "assert" statement\n' '\n' 'A "break" statement executed in the first suite terminates the ' 'loop\n' - 'without executing the "else" clause’s suite. A "continue" ' + 'without executing the "else" clause\'s suite. A "continue" ' 'statement\n' 'executed in the first suite skips the rest of the suite and goes ' 'back\n' @@ -2226,57 +2258,44 @@ topics = {'assert': 'The "assert" statement\n' 'object. An iterator is created for the result of the\n' '"expression_list". The suite is then executed once for each ' 'item\n' - 'provided by the iterator, in the order returned by the ' - 'iterator. Each\n' + 'provided by the iterator, in the order of ascending indices. ' + 'Each\n' 'item in turn is assigned to the target list using the standard ' 'rules\n' - 'for assignments (see Assignment statements), and then the suite ' - 'is\n' - 'executed. When the items are exhausted (which is immediately ' - 'when the\n' - 'sequence is empty or an iterator raises a "StopIteration" ' - 'exception),\n' - 'the suite in the "else" clause, if present, is executed, and the ' - 'loop\n' + 'for assignments, and then the suite is executed. When the items ' + 'are\n' + 'exhausted (which is immediately when the sequence is empty), the ' + 'suite\n' + 'in the "else" clause, if present, is executed, and the loop\n' 'terminates.\n' '\n' 'A "break" statement executed in the first suite terminates the ' 'loop\n' - 'without executing the "else" clause’s suite. A "continue" ' + 'without executing the "else" clause\'s suite. A "continue" ' 'statement\n' 'executed in the first suite skips the rest of the suite and ' 'continues\n' - 'with the next item, or with the "else" clause if there is no ' + 'with the next item, or with the "else" clause if there was no ' 'next\n' 'item.\n' '\n' - 'The for-loop makes assignments to the variables in the target ' - 'list.\n' - 'This overwrites all previous assignments to those variables ' - 'including\n' - 'those made in the suite of the for-loop:\n' - '\n' - ' for i in range(10):\n' - ' print(i)\n' - ' i = 5 # this will not affect the for-loop\n' - ' # because i will be overwritten with ' - 'the next\n' - ' # index in the range\n' - '\n' - 'Names in the target list are not deleted when the loop is ' - 'finished,\n' - 'but if the sequence is empty, they will not have been assigned ' - 'to at\n' - 'all by the loop. Hint: the built-in function "range()" returns ' - 'an\n' - 'iterator of integers suitable to emulate the effect of Pascal’s ' - '"for i\n' - ':= a to b do"; e.g., "list(range(3))" returns the list "[0, 1, ' - '2]".\n' + 'The suite may assign to the variable(s) in the target list; this ' + 'does\n' + 'not affect the next item assigned to it.\n' + '\n' + 'The target list is not deleted when the loop is finished, but if ' + 'the\n' + 'sequence is empty, it will not have been assigned to at all by ' + 'the\n' + 'loop. Hint: the built-in function "range()" returns a sequence ' + 'of\n' + 'integers suitable to emulate the effect of Pascal\'s "for i := a ' + 'to b\n' + 'do"; e.g., "range(3)" returns the list "[0, 1, 2]".\n' '\n' 'Note: There is a subtlety when the sequence is being modified by ' 'the\n' - ' loop (this can only occur for mutable sequences, e.g. lists). ' + ' loop (this can only occur for mutable sequences, i.e. lists). ' 'An\n' ' internal counter is used to keep track of which item is used ' 'next,\n' @@ -2310,13 +2329,18 @@ topics = {'assert': 'The "assert" statement\n' '\n' ' try_stmt ::= try1_stmt | try2_stmt\n' ' try1_stmt ::= "try" ":" suite\n' - ' ("except" [expression ["as" identifier]] ":" ' - 'suite)+\n' + ' ("except" [expression [("as" | ",") ' + 'identifier]] ":" suite)+\n' ' ["else" ":" suite]\n' ' ["finally" ":" suite]\n' ' try2_stmt ::= "try" ":" suite\n' ' "finally" ":" suite\n' '\n' + 'Changed in version 2.5: In previous versions of Python,\n' + '"try"..."except"..."finally" did not work. "try"..."except" had ' + 'to be\n' + 'nested in "try"..."finally".\n' + '\n' 'The "except" clause(s) specify one or more exception handlers. ' 'When no\n' 'exception occurs in the "try" clause, no exception handler is\n' @@ -2331,11 +2355,11 @@ topics = {'assert': 'The "assert" statement\n' 'expression\n' 'is evaluated, and the clause matches the exception if the ' 'resulting\n' - 'object is “compatible” with the exception. An object is ' + 'object is "compatible" with the exception. An object is ' 'compatible\n' 'with an exception if it is the class or a base class of the ' 'exception\n' - 'object or a tuple containing an item compatible with the ' + 'object, or a tuple containing an item compatible with the ' 'exception.\n' '\n' 'If no except clause matches the exception, the search for an ' @@ -2356,83 +2380,59 @@ topics = {'assert': 'The "assert" statement\n' '\n' 'When a matching except clause is found, the exception is ' 'assigned to\n' - 'the target specified after the "as" keyword in that except ' - 'clause, if\n' - 'present, and the except clause’s suite is executed. All except\n' - 'clauses must have an executable block. When the end of this ' - 'block is\n' - 'reached, execution continues normally after the entire try ' - 'statement.\n' - '(This means that if two nested handlers exist for the same ' - 'exception,\n' - 'and the exception occurs in the try clause of the inner handler, ' - 'the\n' - 'outer handler will not handle the exception.)\n' - '\n' - 'When an exception has been assigned using "as target", it is ' - 'cleared\n' - 'at the end of the except clause. This is as if\n' - '\n' - ' except E as N:\n' - ' foo\n' - '\n' - 'was translated to\n' - '\n' - ' except E as N:\n' - ' try:\n' - ' foo\n' - ' finally:\n' - ' del N\n' + 'the target specified in that except clause, if present, and the ' + 'except\n' + "clause's suite is executed. All except clauses must have an\n" + 'executable block. When the end of this block is reached, ' + 'execution\n' + 'continues normally after the entire try statement. (This means ' + 'that\n' + 'if two nested handlers exist for the same exception, and the ' + 'exception\n' + 'occurs in the try clause of the inner handler, the outer handler ' + 'will\n' + 'not handle the exception.)\n' '\n' - 'This means the exception must be assigned to a different name to ' - 'be\n' - 'able to refer to it after the except clause. Exceptions are ' - 'cleared\n' - 'because with the traceback attached to them, they form a ' - 'reference\n' - 'cycle with the stack frame, keeping all locals in that frame ' - 'alive\n' - 'until the next garbage collection occurs.\n' - '\n' - 'Before an except clause’s suite is executed, details about the\n' - 'exception are stored in the "sys" module and can be accessed ' - 'via\n' - '"sys.exc_info()". "sys.exc_info()" returns a 3-tuple consisting ' - 'of the\n' - 'exception class, the exception instance and a traceback object ' - '(see\n' - 'section The standard type hierarchy) identifying the point in ' + "Before an except clause's suite is executed, details about the\n" + 'exception are assigned to three variables in the "sys" module:\n' + '"sys.exc_type" receives the object identifying the exception;\n' + '"sys.exc_value" receives the exception\'s parameter;\n' + '"sys.exc_traceback" receives a traceback object (see section ' + 'The\n' + 'standard type hierarchy) identifying the point in the program ' + 'where\n' + 'the exception occurred. These details are also available through ' 'the\n' - 'program where the exception occurred. "sys.exc_info()" values ' - 'are\n' - 'restored to their previous values (before the call) when ' - 'returning\n' - 'from a function that handled an exception.\n' - '\n' - 'The optional "else" clause is executed if the control flow ' - 'leaves the\n' - '"try" suite, no exception was raised, and no "return", ' - '"continue", or\n' - '"break" statement was executed. Exceptions in the "else" clause ' + '"sys.exc_info()" function, which returns a tuple "(exc_type,\n' + 'exc_value, exc_traceback)". Use of the corresponding variables ' + 'is\n' + 'deprecated in favor of this function, since their use is unsafe ' + 'in a\n' + 'threaded program. As of Python 1.5, the variables are restored ' + 'to\n' + 'their previous values (before the call) when returning from a ' + 'function\n' + 'that handled an exception.\n' + '\n' + 'The optional "else" clause is executed if and when control flows ' + 'off\n' + 'the end of the "try" clause. [2] Exceptions in the "else" clause ' 'are\n' 'not handled by the preceding "except" clauses.\n' '\n' - 'If "finally" is present, it specifies a ‘cleanup’ handler. The ' - '"try"\n' + 'If "finally" is present, it specifies a \'cleanup\' handler. ' + 'The "try"\n' 'clause is executed, including any "except" and "else" clauses. ' 'If an\n' 'exception occurs in any of the clauses and is not handled, the\n' 'exception is temporarily saved. The "finally" clause is ' 'executed. If\n' - 'there is a saved exception it is re-raised at the end of the ' - '"finally"\n' - 'clause. If the "finally" clause raises another exception, the ' - 'saved\n' - 'exception is set as the context of the new exception. If the ' - '"finally"\n' - 'clause executes a "return", "break" or "continue" statement, the ' - 'saved\n' - 'exception is discarded:\n' + 'there is a saved exception, it is re-raised at the end of the\n' + '"finally" clause. If the "finally" clause raises another ' + 'exception or\n' + 'executes a "return" or "break" statement, the saved exception ' + 'is\n' + 'discarded:\n' '\n' ' >>> def f():\n' ' ... try:\n' @@ -2449,9 +2449,13 @@ topics = {'assert': 'The "assert" statement\n' '\n' 'When a "return", "break" or "continue" statement is executed in ' 'the\n' - '"try" suite of a "try"…"finally" statement, the "finally" clause ' - 'is\n' - 'also executed ‘on the way out.’\n' + '"try" suite of a "try"..."finally" statement, the "finally" ' + 'clause is\n' + 'also executed \'on the way out.\' A "continue" statement is ' + 'illegal in\n' + 'the "finally" clause. (The reason is a problem with the current\n' + 'implementation --- this restriction may be lifted in the ' + 'future).\n' '\n' 'The return value of a function is determined by the last ' '"return"\n' @@ -2475,27 +2479,24 @@ topics = {'assert': 'The "assert" statement\n' 'generate\n' 'exceptions may be found in section The raise statement.\n' '\n' - 'Changed in version 3.8: Prior to Python 3.8, a "continue" ' - 'statement\n' - 'was illegal in the "finally" clause due to a problem with the\n' - 'implementation.\n' - '\n' '\n' 'The "with" statement\n' '====================\n' '\n' + 'New in version 2.5.\n' + '\n' 'The "with" statement is used to wrap the execution of a block ' 'with\n' 'methods defined by a context manager (see section With ' 'Statement\n' - 'Context Managers). This allows common "try"…"except"…"finally" ' - 'usage\n' - 'patterns to be encapsulated for convenient reuse.\n' + 'Context Managers). This allows common ' + '"try"..."except"..."finally"\n' + 'usage patterns to be encapsulated for convenient reuse.\n' '\n' ' with_stmt ::= "with" with_item ("," with_item)* ":" suite\n' ' with_item ::= expression ["as" target]\n' '\n' - 'The execution of the "with" statement with one “item” proceeds ' + 'The execution of the "with" statement with one "item" proceeds ' 'as\n' 'follows:\n' '\n' @@ -2503,9 +2504,9 @@ topics = {'assert': 'The "assert" statement\n' '"with_item")\n' ' is evaluated to obtain a context manager.\n' '\n' - '2. The context manager’s "__exit__()" is loaded for later use.\n' + '2. The context manager\'s "__exit__()" is loaded for later use.\n' '\n' - '3. The context manager’s "__enter__()" method is invoked.\n' + '3. The context manager\'s "__enter__()" method is invoked.\n' '\n' '4. If a target was included in the "with" statement, the return\n' ' value from "__enter__()" is assigned to it.\n' @@ -2522,7 +2523,7 @@ topics = {'assert': 'The "assert" statement\n' '\n' '5. The suite is executed.\n' '\n' - '6. The context manager’s "__exit__()" method is invoked. If an\n' + '6. The context manager\'s "__exit__()" method is invoked. If an\n' ' exception caused the suite to be exited, its type, value, ' 'and\n' ' traceback are passed as arguments to "__exit__()". Otherwise, ' @@ -2557,12 +2558,18 @@ topics = {'assert': 'The "assert" statement\n' ' with B() as b:\n' ' suite\n' '\n' - 'Changed in version 3.1: Support for multiple context ' + 'Note: In Python 2.5, the "with" statement is only allowed when ' + 'the\n' + ' "with_statement" feature has been enabled. It is always ' + 'enabled in\n' + ' Python 2.6.\n' + '\n' + 'Changed in version 2.7: Support for multiple context ' 'expressions.\n' '\n' 'See also:\n' '\n' - ' **PEP 343** - The “with” statement\n' + ' **PEP 343** - The "with" statement\n' ' The specification, background, and examples for the Python ' '"with"\n' ' statement.\n' @@ -2575,25 +2582,21 @@ topics = {'assert': 'The "assert" statement\n' '(see\n' 'section The standard type hierarchy):\n' '\n' - ' funcdef ::= [decorators] "def" funcname "(" ' - '[parameter_list] ")"\n' - ' ["->" expression] ":" suite\n' - ' decorators ::= decorator+\n' - ' decorator ::= "@" dotted_name ["(" ' - '[argument_list [","]] ")"] NEWLINE\n' - ' dotted_name ::= identifier ("." identifier)*\n' - ' parameter_list ::= defparameter ("," ' - 'defparameter)* "," "/" ["," [parameter_list_no_posonly]]\n' - ' | parameter_list_no_posonly\n' - ' parameter_list_no_posonly ::= defparameter ("," ' - 'defparameter)* ["," [parameter_list_starargs]]\n' - ' | parameter_list_starargs\n' - ' parameter_list_starargs ::= "*" [parameter] ("," ' - 'defparameter)* ["," ["**" parameter [","]]]\n' - ' | "**" parameter [","]\n' - ' parameter ::= identifier [":" expression]\n' - ' defparameter ::= parameter ["=" expression]\n' - ' funcname ::= identifier\n' + ' decorated ::= decorators (classdef | funcdef)\n' + ' decorators ::= decorator+\n' + ' decorator ::= "@" dotted_name ["(" [argument_list [","]] ' + '")"] NEWLINE\n' + ' funcdef ::= "def" funcname "(" [parameter_list] ")" ' + '":" suite\n' + ' dotted_name ::= identifier ("." identifier)*\n' + ' parameter_list ::= (defparameter ",")*\n' + ' ( "*" identifier ["," "**" identifier]\n' + ' | "**" identifier\n' + ' | defparameter [","] )\n' + ' defparameter ::= parameter ["=" expression]\n' + ' sublist ::= parameter ("," parameter)* [","]\n' + ' parameter ::= identifier | "(" sublist ")"\n' + ' funcname ::= identifier\n' '\n' 'A function definition is an executable statement. Its execution ' 'binds\n' @@ -2606,7 +2609,7 @@ topics = {'assert': 'The "assert" statement\n' '\n' 'The function definition does not execute the function body; this ' 'gets\n' - 'executed only when the function is called. [2]\n' + 'executed only when the function is called. [3]\n' '\n' 'A function definition may be wrapped by one or more *decorator*\n' 'expressions. Decorator expressions are evaluated when the ' @@ -2619,52 +2622,47 @@ topics = {'assert': 'The "assert" statement\n' 'function name\n' 'instead of the function object. Multiple decorators are applied ' 'in\n' - 'nested fashion. For example, the following code\n' + 'nested fashion. For example, the following code:\n' '\n' ' @f1(arg)\n' ' @f2\n' ' def func(): pass\n' '\n' - 'is roughly equivalent to\n' + 'is equivalent to:\n' '\n' ' def func(): pass\n' ' func = f1(arg)(f2(func))\n' '\n' - 'except that the original function is not temporarily bound to ' - 'the name\n' - '"func".\n' - '\n' - 'When one or more *parameters* have the form *parameter* "="\n' - '*expression*, the function is said to have “default parameter ' - 'values.”\n' + 'When one or more top-level *parameters* have the form ' + '*parameter* "="\n' + '*expression*, the function is said to have "default parameter ' + 'values."\n' 'For a parameter with a default value, the corresponding ' '*argument* may\n' - 'be omitted from a call, in which case the parameter’s default ' + "be omitted from a call, in which case the parameter's default " 'value is\n' 'substituted. If a parameter has a default value, all following\n' - 'parameters up until the “"*"” must also have a default value — ' - 'this is\n' - 'a syntactic restriction that is not expressed by the grammar.\n' - '\n' - '**Default parameter values are evaluated from left to right when ' - 'the\n' - 'function definition is executed.** This means that the ' - 'expression is\n' - 'evaluated once, when the function is defined, and that the same ' - '“pre-\n' - 'computed” value is used for each call. This is especially ' - 'important\n' - 'to understand when a default parameter is a mutable object, such ' - 'as a\n' - 'list or a dictionary: if the function modifies the object (e.g. ' - 'by\n' - 'appending an item to a list), the default value is in effect ' - 'modified.\n' - 'This is generally not what was intended. A way around this is ' - 'to use\n' - '"None" as the default, and explicitly test for it in the body of ' - 'the\n' - 'function, e.g.:\n' + 'parameters must also have a default value --- this is a ' + 'syntactic\n' + 'restriction that is not expressed by the grammar.\n' + '\n' + '**Default parameter values are evaluated when the function ' + 'definition\n' + 'is executed.** This means that the expression is evaluated ' + 'once, when\n' + 'the function is defined, and that the same "pre-computed" value ' + 'is\n' + 'used for each call. This is especially important to understand ' + 'when a\n' + 'default parameter is a mutable object, such as a list or a ' + 'dictionary:\n' + 'if the function modifies the object (e.g. by appending an item ' + 'to a\n' + 'list), the default value is in effect modified. This is ' + 'generally not\n' + 'what was intended. A way around this is to use "None" as the\n' + 'default, and explicitly test for it in the body of the function, ' + 'e.g.:\n' '\n' ' def whats_on_the_telly(penguin=None):\n' ' if penguin is None:\n' @@ -2678,44 +2676,16 @@ topics = {'assert': 'The "assert" statement\n' 'mentioned in\n' 'the parameter list, either from position arguments, from ' 'keyword\n' - 'arguments, or from default values. If the form “"*identifier"” ' + 'arguments, or from default values. If the form ""*identifier"" ' 'is\n' 'present, it is initialized to a tuple receiving any excess ' 'positional\n' - 'parameters, defaulting to the empty tuple. If the form\n' - '“"**identifier"” is present, it is initialized to a new ordered\n' - 'mapping receiving any excess keyword arguments, defaulting to a ' - 'new\n' - 'empty mapping of the same type. Parameters after “"*"” or\n' - '“"*identifier"” are keyword-only parameters and may only be ' - 'passed\n' - 'used keyword arguments.\n' - '\n' - 'Parameters may have an *annotation* of the form “": ' - 'expression"”\n' - 'following the parameter name. Any parameter may have an ' - 'annotation,\n' - 'even those of the form "*identifier" or "**identifier". ' - 'Functions may\n' - 'have “return” annotation of the form “"-> expression"” after ' - 'the\n' - 'parameter list. These annotations can be any valid Python ' - 'expression.\n' - 'The presence of annotations does not change the semantics of a\n' - 'function. The annotation values are available as values of a\n' - 'dictionary keyed by the parameters’ names in the ' - '"__annotations__"\n' - 'attribute of the function object. If the "annotations" import ' - 'from\n' - '"__future__" is used, annotations are preserved as strings at ' - 'runtime\n' - 'which enables postponed evaluation. Otherwise, they are ' - 'evaluated\n' - 'when the function definition is executed. In this case ' - 'annotations\n' - 'may be evaluated in a different order than they appear in the ' - 'source\n' - 'code.\n' + 'parameters, defaulting to the empty tuple. If the form\n' + '""**identifier"" is present, it is initialized to a new ' + 'dictionary\n' + 'receiving any excess keyword arguments, defaulting to a new ' + 'empty\n' + 'dictionary.\n' '\n' 'It is also possible to create anonymous functions (functions not ' 'bound\n' @@ -2724,44 +2694,24 @@ topics = {'assert': 'The "assert" statement\n' 'lambda\n' 'expression is merely a shorthand for a simplified function ' 'definition;\n' - 'a function defined in a “"def"” statement can be passed around ' + 'a function defined in a ""def"" statement can be passed around ' 'or\n' 'assigned to another name just like a function defined by a ' 'lambda\n' - 'expression. The “"def"” form is actually more powerful since ' + 'expression. The ""def"" form is actually more powerful since ' 'it\n' - 'allows the execution of multiple statements and annotations.\n' + 'allows the execution of multiple statements.\n' '\n' - '**Programmer’s note:** Functions are first-class objects. A ' - '“"def"”\n' - 'statement executed inside a function definition defines a local\n' - 'function that can be returned or passed around. Free variables ' - 'used\n' - 'in the nested function can access the local variables of the ' + "**Programmer's note:** Functions are first-class objects. A " + '""def""\n' + 'form executed inside a function definition defines a local ' 'function\n' + 'that can be returned or passed around. Free variables used in ' + 'the\n' + 'nested function can access the local variables of the function\n' 'containing the def. See section Naming and binding for ' 'details.\n' '\n' - 'See also:\n' - '\n' - ' **PEP 3107** - Function Annotations\n' - ' The original specification for function annotations.\n' - '\n' - ' **PEP 484** - Type Hints\n' - ' Definition of a standard meaning for annotations: type ' - 'hints.\n' - '\n' - ' **PEP 526** - Syntax for Variable Annotations\n' - ' Ability to type hint variable declarations, including ' - 'class\n' - ' variables and instance variables\n' - '\n' - ' **PEP 563** - Postponed Evaluation of Annotations\n' - ' Support for forward references within annotations by ' - 'preserving\n' - ' annotations in a string form at runtime instead of eager\n' - ' evaluation.\n' - '\n' '\n' 'Class definitions\n' '=================\n' @@ -2770,222 +2720,60 @@ topics = {'assert': 'The "assert" statement\n' 'standard\n' 'type hierarchy):\n' '\n' - ' classdef ::= [decorators] "class" classname [inheritance] ' - '":" suite\n' - ' inheritance ::= "(" [argument_list] ")"\n' + ' classdef ::= "class" classname [inheritance] ":" suite\n' + ' inheritance ::= "(" [expression_list] ")"\n' ' classname ::= identifier\n' '\n' - 'A class definition is an executable statement. The inheritance ' + 'A class definition is an executable statement. It first ' + 'evaluates the\n' + 'inheritance list, if present. Each item in the inheritance ' 'list\n' - 'usually gives a list of base classes (see Metaclasses for more\n' - 'advanced uses), so each item in the list should evaluate to a ' - 'class\n' - 'object which allows subclassing. Classes without an inheritance ' + 'should evaluate to a class object or class type which allows\n' + "subclassing. The class's suite is then executed in a new " + 'execution\n' + 'frame (see section Naming and binding), using a newly created ' + 'local\n' + 'namespace and the original global namespace. (Usually, the ' + 'suite\n' + "contains only function definitions.) When the class's suite " + 'finishes\n' + 'execution, its execution frame is discarded but its local ' + 'namespace is\n' + 'saved. [4] A class object is then created using the inheritance ' 'list\n' - 'inherit, by default, from the base class "object"; hence,\n' - '\n' - ' class Foo:\n' - ' pass\n' - '\n' - 'is equivalent to\n' - '\n' - ' class Foo(object):\n' - ' pass\n' - '\n' - 'The class’s suite is then executed in a new execution frame ' - '(see\n' - 'Naming and binding), using a newly created local namespace and ' + 'for the base classes and the saved local namespace for the ' + 'attribute\n' + 'dictionary. The class name is bound to this class object in ' 'the\n' - 'original global namespace. (Usually, the suite contains mostly\n' - 'function definitions.) When the class’s suite finishes ' - 'execution, its\n' - 'execution frame is discarded but its local namespace is saved. ' - '[3] A\n' - 'class object is then created using the inheritance list for the ' - 'base\n' - 'classes and the saved local namespace for the attribute ' - 'dictionary.\n' - 'The class name is bound to this class object in the original ' - 'local\n' - 'namespace.\n' - '\n' - 'The order in which attributes are defined in the class body is\n' - 'preserved in the new class’s "__dict__". Note that this is ' - 'reliable\n' - 'only right after the class is created and only for classes that ' - 'were\n' - 'defined using the definition syntax.\n' - '\n' - 'Class creation can be customized heavily using metaclasses.\n' - '\n' - 'Classes can also be decorated: just like when decorating ' - 'functions,\n' - '\n' - ' @f1(arg)\n' - ' @f2\n' - ' class Foo: pass\n' - '\n' - 'is roughly equivalent to\n' - '\n' - ' class Foo: pass\n' - ' Foo = f1(arg)(f2(Foo))\n' + 'original local namespace.\n' '\n' - 'The evaluation rules for the decorator expressions are the same ' - 'as for\n' - 'function decorators. The result is then bound to the class ' - 'name.\n' - '\n' - '**Programmer’s note:** Variables defined in the class definition ' + "**Programmer's note:** Variables defined in the class definition " 'are\n' - 'class attributes; they are shared by instances. Instance ' - 'attributes\n' - 'can be set in a method with "self.name = value". Both class ' - 'and\n' - 'instance attributes are accessible through the notation ' - '“"self.name"”,\n' - 'and an instance attribute hides a class attribute with the same ' - 'name\n' - 'when accessed in this way. Class attributes can be used as ' - 'defaults\n' - 'for instance attributes, but using mutable values there can lead ' - 'to\n' - 'unexpected results. Descriptors can be used to create instance\n' - 'variables with different implementation details.\n' - '\n' - 'See also:\n' - '\n' - ' **PEP 3115** - Metaclasses in Python 3000\n' - ' The proposal that changed the declaration of metaclasses to ' - 'the\n' - ' current syntax, and the semantics for how classes with\n' - ' metaclasses are constructed.\n' - '\n' - ' **PEP 3129** - Class Decorators\n' - ' The proposal that added class decorators. Function and ' - 'method\n' - ' decorators were introduced in **PEP 318**.\n' - '\n' - '\n' - 'Coroutines\n' - '==========\n' - '\n' - 'New in version 3.5.\n' - '\n' - '\n' - 'Coroutine function definition\n' - '-----------------------------\n' - '\n' - ' async_funcdef ::= [decorators] "async" "def" funcname "(" ' - '[parameter_list] ")"\n' - ' ["->" expression] ":" suite\n' - '\n' - 'Execution of Python coroutines can be suspended and resumed at ' - 'many\n' - 'points (see *coroutine*). Inside the body of a coroutine ' - 'function,\n' - '"await" and "async" identifiers become reserved keywords; ' - '"await"\n' - 'expressions, "async for" and "async with" can only be used in\n' - 'coroutine function bodies.\n' - '\n' - 'Functions defined with "async def" syntax are always coroutine\n' - 'functions, even if they do not contain "await" or "async" ' - 'keywords.\n' - '\n' - 'It is a "SyntaxError" to use a "yield from" expression inside ' - 'the body\n' - 'of a coroutine function.\n' - '\n' - 'An example of a coroutine function:\n' - '\n' - ' async def func(param1, param2):\n' - ' do_stuff()\n' - ' await some_coroutine()\n' - '\n' - '\n' - 'The "async for" statement\n' - '-------------------------\n' - '\n' - ' async_for_stmt ::= "async" for_stmt\n' - '\n' - 'An *asynchronous iterable* is able to call asynchronous code in ' - 'its\n' - '*iter* implementation, and *asynchronous iterator* can call\n' - 'asynchronous code in its *next* method.\n' - '\n' - 'The "async for" statement allows convenient iteration over\n' - 'asynchronous iterators.\n' - '\n' - 'The following code:\n' - '\n' - ' async for TARGET in ITER:\n' - ' BLOCK\n' - ' else:\n' - ' BLOCK2\n' - '\n' - 'Is semantically equivalent to:\n' - '\n' - ' iter = (ITER)\n' - ' iter = type(iter).__aiter__(iter)\n' - ' running = True\n' - ' while running:\n' - ' try:\n' - ' TARGET = await type(iter).__anext__(iter)\n' - ' except StopAsyncIteration:\n' - ' running = False\n' - ' else:\n' - ' BLOCK\n' - ' else:\n' - ' BLOCK2\n' - '\n' - 'See also "__aiter__()" and "__anext__()" for details.\n' - '\n' - 'It is a "SyntaxError" to use an "async for" statement outside ' - 'the body\n' - 'of a coroutine function.\n' - '\n' - '\n' - 'The "async with" statement\n' - '--------------------------\n' - '\n' - ' async_with_stmt ::= "async" with_stmt\n' - '\n' - 'An *asynchronous context manager* is a *context manager* that is ' - 'able\n' - 'to suspend execution in its *enter* and *exit* methods.\n' - '\n' - 'The following code:\n' - '\n' - ' async with EXPR as VAR:\n' - ' BLOCK\n' - '\n' - 'Is semantically equivalent to:\n' - '\n' - ' mgr = (EXPR)\n' - ' aexit = type(mgr).__aexit__\n' - ' aenter = type(mgr).__aenter__(mgr)\n' - '\n' - ' VAR = await aenter\n' - ' try:\n' - ' BLOCK\n' - ' except:\n' - ' if not await aexit(mgr, *sys.exc_info()):\n' - ' raise\n' - ' else:\n' - ' await aexit(mgr, None, None, None)\n' - '\n' - 'See also "__aenter__()" and "__aexit__()" for details.\n' - '\n' - 'It is a "SyntaxError" to use an "async with" statement outside ' - 'the\n' - 'body of a coroutine function.\n' - '\n' - 'See also:\n' + 'class variables; they are shared by all instances. To create ' + 'instance\n' + 'variables, they can be set in a method with "self.name = ' + 'value". Both\n' + 'class and instance variables are accessible through the ' + 'notation\n' + '""self.name"", and an instance variable hides a class variable ' + 'with\n' + 'the same name when accessed in this way. Class variables can be ' + 'used\n' + 'as defaults for instance variables, but using mutable values ' + 'there can\n' + 'lead to unexpected results. For *new-style class*es, ' + 'descriptors can\n' + 'be used to create instance variables with different ' + 'implementation\n' + 'details.\n' '\n' - ' **PEP 492** - Coroutines with async and await syntax\n' - ' The proposal that made coroutines a proper standalone ' - 'concept in\n' - ' Python, and added supporting syntax.\n' + 'Class definitions, like function definitions, may be wrapped by ' + 'one or\n' + 'more *decorator* expressions. The evaluation rules for the ' + 'decorator\n' + 'expressions are the same as for functions. The result must be a ' + 'class\n' + 'object, which is then bound to the class name.\n' '\n' '-[ Footnotes ]-\n' '\n' @@ -2994,17 +2782,26 @@ topics = {'assert': 'The "assert" statement\n' ' exception. That new exception causes the old one to be ' 'lost.\n' '\n' - '[2] A string literal appearing as the first statement in the\n' - ' function body is transformed into the function’s "__doc__"\n' - ' attribute and therefore the function’s *docstring*.\n' + '[2] Currently, control "flows off the end" except in the case ' + 'of\n' + ' an exception or the execution of a "return", "continue", or\n' + ' "break" statement.\n' + '\n' + '[3] A string literal appearing as the first statement in the\n' + ' function body is transformed into the function\'s "__doc__"\n' + " attribute and therefore the function's *docstring*.\n" '\n' - '[3] A string literal appearing as the first statement in the ' + '[4] A string literal appearing as the first statement in the ' 'class\n' - ' body is transformed into the namespace’s "__doc__" item and\n' - ' therefore the class’s *docstring*.\n', - 'context-managers': 'With Statement Context Managers\n' + ' body is transformed into the namespace\'s "__doc__" item ' + 'and\n' + " therefore the class's *docstring*.\n", + 'context-managers': '\n' + 'With Statement Context Managers\n' '*******************************\n' '\n' + 'New in version 2.5.\n' + '\n' 'A *context manager* is an object that defines the ' 'runtime context to\n' 'be established when executing a "with" statement. The ' @@ -3031,7 +2828,7 @@ topics = {'assert': 'The "assert" statement\n' '\n' ' Enter the runtime context related to this object. The ' '"with"\n' - ' statement will bind this method’s return value to the ' + " statement will bind this method's return value to the " 'target(s)\n' ' specified in the "as" clause of the statement, if ' 'any.\n' @@ -3056,39 +2853,45 @@ topics = {'assert': 'The "assert" statement\n' '\n' ' Note that "__exit__()" methods should not reraise the ' 'passed-in\n' - ' exception; this is the caller’s responsibility.\n' + " exception; this is the caller's responsibility.\n" '\n' 'See also:\n' '\n' - ' **PEP 343** - The “with” statement\n' + ' **PEP 343** - The "with" statement\n' ' The specification, background, and examples for the ' 'Python "with"\n' ' statement.\n', - 'continue': 'The "continue" statement\n' + 'continue': '\n' + 'The "continue" statement\n' '************************\n' '\n' ' continue_stmt ::= "continue"\n' '\n' '"continue" may only occur syntactically nested in a "for" or ' '"while"\n' - 'loop, but not nested in a function or class definition within ' - 'that\n' - 'loop. It continues with the next cycle of the nearest enclosing ' - 'loop.\n' + 'loop, but not nested in a function or class definition or ' + '"finally"\n' + 'clause within that loop. It continues with the next cycle of ' + 'the\n' + 'nearest enclosing loop.\n' '\n' 'When "continue" passes control out of a "try" statement with a\n' '"finally" clause, that "finally" clause is executed before ' 'really\n' 'starting the next loop cycle.\n', - 'conversions': 'Arithmetic conversions\n' + 'conversions': '\n' + 'Arithmetic conversions\n' '**********************\n' '\n' 'When a description of an arithmetic operator below uses the ' 'phrase\n' - '“the numeric arguments are converted to a common type,” this ' - 'means\n' - 'that the operator implementation for built-in types works as ' - 'follows:\n' + '"the numeric arguments are converted to a common type," the ' + 'arguments\n' + 'are coerced using the coercion rules listed at Coercion ' + 'rules. If\n' + 'both arguments are standard numeric types, the following ' + 'coercions are\n' + 'applied:\n' '\n' '* If either argument is a complex number, the other is ' 'converted to\n' @@ -3098,15 +2901,21 @@ topics = {'assert': 'The "assert" statement\n' 'the\n' ' other is converted to floating point;\n' '\n' - '* otherwise, both must be integers and no conversion is ' - 'necessary.\n' + '* otherwise, if either argument is a long integer, the other ' + 'is\n' + ' converted to long integer;\n' + '\n' + '* otherwise, both must be plain integers and no conversion ' + 'is\n' + ' necessary.\n' '\n' 'Some additional rules apply for certain operators (e.g., a ' - 'string as a\n' - 'left argument to the ‘%’ operator). Extensions must define ' - 'their own\n' - 'conversion behavior.\n', - 'customization': 'Basic customization\n' + 'string left\n' + "argument to the '%' operator). Extensions can define their " + 'own\n' + 'coercions.\n', + 'customization': '\n' + 'Basic customization\n' '*******************\n' '\n' 'object.__new__(cls[, ...])\n' @@ -3127,26 +2936,24 @@ topics = {'assert': 'The "assert" statement\n' '\n' ' Typical implementations create a new instance of the ' 'class by\n' - ' invoking the superclass’s "__new__()" method using\n' - ' "super().__new__(cls[, ...])" with appropriate arguments ' - 'and then\n' - ' modifying the newly-created instance as necessary before ' - 'returning\n' - ' it.\n' - '\n' - ' If "__new__()" is invoked during object construction and ' - 'it returns\n' - ' an instance or subclass of *cls*, then the new ' - 'instance’s\n' - ' "__init__()" method will be invoked like ' - '"__init__(self[, ...])",\n' - ' where *self* is the new instance and the remaining ' - 'arguments are\n' - ' the same as were passed to the object constructor.\n' + ' invoking the superclass\'s "__new__()" method using\n' + ' "super(currentclass, cls).__new__(cls[, ...])" with ' + 'appropriate\n' + ' arguments and then modifying the newly-created instance ' + 'as\n' + ' necessary before returning it.\n' + '\n' + ' If "__new__()" returns an instance of *cls*, then the ' + 'new\n' + ' instance\'s "__init__()" method will be invoked like\n' + ' "__init__(self[, ...])", where *self* is the new ' + 'instance and the\n' + ' remaining arguments are the same as were passed to ' + '"__new__()".\n' '\n' ' If "__new__()" does not return an instance of *cls*, ' 'then the new\n' - ' instance’s "__init__()" method will not be invoked.\n' + ' instance\'s "__init__()" method will not be invoked.\n' '\n' ' "__new__()" is intended mainly to allow subclasses of ' 'immutable\n' @@ -3164,17 +2971,17 @@ topics = {'assert': 'The "assert" statement\n' 'those\n' ' passed to the class constructor expression. If a base ' 'class has an\n' - ' "__init__()" method, the derived class’s "__init__()" ' + ' "__init__()" method, the derived class\'s "__init__()" ' 'method, if\n' ' any, must explicitly call it to ensure proper ' 'initialization of the\n' ' base class part of the instance; for example:\n' - ' "super().__init__([args...])".\n' + ' "BaseClass.__init__(self, [args...])".\n' '\n' ' Because "__new__()" and "__init__()" work together in ' 'constructing\n' ' objects ("__new__()" to create it, and "__init__()" to ' - 'customize\n' + 'customise\n' ' it), no non-"None" value may be returned by ' '"__init__()"; doing so\n' ' will cause a "TypeError" to be raised at runtime.\n' @@ -3183,52 +2990,65 @@ topics = {'assert': 'The "assert" statement\n' '\n' ' Called when the instance is about to be destroyed. This ' 'is also\n' - ' called a finalizer or (improperly) a destructor. If a ' - 'base class\n' - ' has a "__del__()" method, the derived class’s ' - '"__del__()" method,\n' - ' if any, must explicitly call it to ensure proper ' - 'deletion of the\n' - ' base class part of the instance.\n' - '\n' - ' It is possible (though not recommended!) for the ' - '"__del__()" method\n' - ' to postpone destruction of the instance by creating a ' - 'new reference\n' - ' to it. This is called object *resurrection*. It is\n' - ' implementation-dependent whether "__del__()" is called a ' - 'second\n' - ' time when a resurrected object is about to be destroyed; ' + ' called a destructor. If a base class has a "__del__()" ' + 'method, the\n' + ' derived class\'s "__del__()" method, if any, must ' + 'explicitly call it\n' + ' to ensure proper deletion of the base class part of the ' + 'instance.\n' + ' Note that it is possible (though not recommended!) for ' 'the\n' - ' current *CPython* implementation only calls it once.\n' - '\n' - ' It is not guaranteed that "__del__()" methods are called ' - 'for\n' - ' objects that still exist when the interpreter exits.\n' - '\n' - ' Note: "del x" doesn’t directly call "x.__del__()" — the ' - 'former\n' + ' "__del__()" method to postpone destruction of the ' + 'instance by\n' + ' creating a new reference to it. It may then be called ' + 'at a later\n' + ' time when this new reference is deleted. It is not ' + 'guaranteed that\n' + ' "__del__()" methods are called for objects that still ' + 'exist when\n' + ' the interpreter exits.\n' + '\n' + ' Note: "del x" doesn\'t directly call "x.__del__()" --- ' + 'the former\n' ' decrements the reference count for "x" by one, and the ' 'latter is\n' - ' only called when "x"’s reference count reaches zero.\n' - '\n' - ' **CPython implementation detail:** It is possible for a ' + ' only called when "x"\'s reference count reaches zero. ' + 'Some common\n' + ' situations that may prevent the reference count of an ' + 'object from\n' + ' going to zero include: circular references between ' + 'objects (e.g.,\n' + ' a doubly-linked list or a tree data structure with ' + 'parent and\n' + ' child pointers); a reference to the object on the ' + 'stack frame of\n' + ' a function that caught an exception (the traceback ' + 'stored in\n' + ' "sys.exc_traceback" keeps the stack frame alive); or a ' 'reference\n' - ' cycle to prevent the reference count of an object from ' - 'going to\n' - ' zero. In this case, the cycle will be later detected ' - 'and deleted\n' - ' by the *cyclic garbage collector*. A common cause of ' - 'reference\n' - ' cycles is when an exception has been caught in a local ' - 'variable.\n' - ' The frame’s locals then reference the exception, which ' + ' to the object on the stack frame that raised an ' + 'unhandled\n' + ' exception in interactive mode (the traceback stored ' + 'in\n' + ' "sys.last_traceback" keeps the stack frame alive). ' + 'The first\n' + ' situation can only be remedied by explicitly breaking ' + 'the cycles;\n' + ' the latter two situations can be resolved by storing ' + '"None" in\n' + ' "sys.exc_traceback" or "sys.last_traceback". Circular ' 'references\n' - ' its own traceback, which references the locals of all ' - 'frames caught\n' - ' in the traceback.\n' - '\n' - ' See also: Documentation for the "gc" module.\n' + ' which are garbage are detected when the option cycle ' + 'detector is\n' + " enabled (it's on by default), but can only be cleaned " + 'up if there\n' + ' are no Python-level "__del__()" methods involved. ' + 'Refer to the\n' + ' documentation for the "gc" module for more information ' + 'about how\n' + ' "__del__()" methods are handled by the cycle ' + 'detector,\n' + ' particularly the description of the "garbage" value.\n' '\n' ' Warning: Due to the precarious circumstances under ' 'which\n' @@ -3236,56 +3056,53 @@ topics = {'assert': 'The "assert" statement\n' 'during\n' ' their execution are ignored, and a warning is printed ' 'to\n' - ' "sys.stderr" instead. In particular:\n' - '\n' - ' * "__del__()" can be invoked when arbitrary code is ' - 'being\n' - ' executed, including from any arbitrary thread. If ' + ' "sys.stderr" instead. Also, when "__del__()" is ' + 'invoked in\n' + ' response to a module being deleted (e.g., when ' + 'execution of the\n' + ' program is done), other globals referenced by the ' '"__del__()"\n' - ' needs to take a lock or invoke any other blocking ' - 'resource, it\n' - ' may deadlock as the resource may already be taken by ' - 'the code\n' - ' that gets interrupted to execute "__del__()".\n' - '\n' - ' * "__del__()" can be executed during interpreter ' - 'shutdown. As\n' - ' a consequence, the global variables it needs to ' - 'access\n' - ' (including other modules) may already have been ' - 'deleted or set\n' - ' to "None". Python guarantees that globals whose name ' - 'begins\n' - ' with a single underscore are deleted from their ' - 'module before\n' - ' other globals are deleted; if no other references to ' - 'such\n' - ' globals exist, this may help in assuring that ' - 'imported modules\n' - ' are still available at the time when the "__del__()" ' - 'method is\n' - ' called.\n' + ' method may already have been deleted or in the process ' + 'of being\n' + ' torn down (e.g. the import machinery shutting down). ' + 'For this\n' + ' reason, "__del__()" methods should do the absolute ' + 'minimum needed\n' + ' to maintain external invariants. Starting with ' + 'version 1.5,\n' + ' Python guarantees that globals whose name begins with ' + 'a single\n' + ' underscore are deleted from their module before other ' + 'globals are\n' + ' deleted; if no other references to such globals exist, ' + 'this may\n' + ' help in assuring that imported modules are still ' + 'available at the\n' + ' time when the "__del__()" method is called.\n' + '\n' + ' See also the "-R" command-line option.\n' '\n' 'object.__repr__(self)\n' '\n' - ' Called by the "repr()" built-in function to compute the ' - '“official”\n' - ' string representation of an object. If at all possible, ' - 'this\n' - ' should look like a valid Python expression that could be ' - 'used to\n' - ' recreate an object with the same value (given an ' - 'appropriate\n' - ' environment). If this is not possible, a string of the ' - 'form\n' - ' "<...some useful description...>" should be returned. ' - 'The return\n' - ' value must be a string object. If a class defines ' - '"__repr__()" but\n' - ' not "__str__()", then "__repr__()" is also used when an ' - '“informal”\n' - ' string representation of instances of that class is ' - 'required.\n' + ' Called by the "repr()" built-in function and by string ' + 'conversions\n' + ' (reverse quotes) to compute the "official" string ' + 'representation of\n' + ' an object. If at all possible, this should look like a ' + 'valid\n' + ' Python expression that could be used to recreate an ' + 'object with the\n' + ' same value (given an appropriate environment). If this ' + 'is not\n' + ' possible, a string of the form "<...some useful ' + 'description...>"\n' + ' should be returned. The return value must be a string ' + 'object. If a\n' + ' class defines "__repr__()" but not "__str__()", then ' + '"__repr__()"\n' + ' is also used when an "informal" string representation of ' + 'instances\n' + ' of that class is required.\n' '\n' ' This is typically used for debugging, so it is important ' 'that the\n' @@ -3293,64 +3110,17 @@ topics = {'assert': 'The "assert" statement\n' '\n' 'object.__str__(self)\n' '\n' - ' Called by "str(object)" and the built-in functions ' - '"format()" and\n' - ' "print()" to compute the “informal” or nicely printable ' - 'string\n' - ' representation of an object. The return value must be a ' - 'string\n' - ' object.\n' - '\n' - ' This method differs from "object.__repr__()" in that ' - 'there is no\n' - ' expectation that "__str__()" return a valid Python ' - 'expression: a\n' - ' more convenient or concise representation can be used.\n' - '\n' - ' The default implementation defined by the built-in type ' - '"object"\n' - ' calls "object.__repr__()".\n' - '\n' - 'object.__bytes__(self)\n' - '\n' - ' Called by bytes to compute a byte-string representation ' - 'of an\n' - ' object. This should return a "bytes" object.\n' - '\n' - 'object.__format__(self, format_spec)\n' - '\n' - ' Called by the "format()" built-in function, and by ' - 'extension,\n' - ' evaluation of formatted string literals and the ' - '"str.format()"\n' - ' method, to produce a “formatted” string representation ' - 'of an\n' - ' object. The *format_spec* argument is a string that ' - 'contains a\n' - ' description of the formatting options desired. The ' - 'interpretation\n' - ' of the *format_spec* argument is up to the type ' - 'implementing\n' - ' "__format__()", however most classes will either ' - 'delegate\n' - ' formatting to one of the built-in types, or use a ' - 'similar\n' - ' formatting option syntax.\n' - '\n' - ' See Format Specification Mini-Language for a description ' - 'of the\n' - ' standard formatting syntax.\n' - '\n' - ' The return value must be a string object.\n' - '\n' - ' Changed in version 3.4: The __format__ method of ' - '"object" itself\n' - ' raises a "TypeError" if passed any non-empty string.\n' - '\n' - ' Changed in version 3.7: "object.__format__(x, \'\')" is ' - 'now\n' - ' equivalent to "str(x)" rather than "format(str(self), ' - '\'\')".\n' + ' Called by the "str()" built-in function and by the ' + '"print"\n' + ' statement to compute the "informal" string ' + 'representation of an\n' + ' object. This differs from "__repr__()" in that it does ' + 'not have to\n' + ' be a valid Python expression: a more convenient or ' + 'concise\n' + ' representation may be used instead. The return value ' + 'must be a\n' + ' string object.\n' '\n' 'object.__lt__(self, other)\n' 'object.__le__(self, other)\n' @@ -3359,14 +3129,20 @@ topics = {'assert': 'The "assert" statement\n' 'object.__gt__(self, other)\n' 'object.__ge__(self, other)\n' '\n' - ' These are the so-called “rich comparison” methods. The\n' + ' New in version 2.1.\n' + '\n' + ' These are the so-called "rich comparison" methods, and ' + 'are called\n' + ' for comparison operators in preference to "__cmp__()" ' + 'below. The\n' ' correspondence between operator symbols and method names ' 'is as\n' ' follows: "x<y" calls "x.__lt__(y)", "x<=y" calls ' '"x.__le__(y)",\n' - ' "x==y" calls "x.__eq__(y)", "x!=y" calls "x.__ne__(y)", ' - '"x>y" calls\n' - ' "x.__gt__(y)", and "x>=y" calls "x.__ge__(y)".\n' + ' "x==y" calls "x.__eq__(y)", "x!=y" and "x<>y" call ' + '"x.__ne__(y)",\n' + ' "x>y" calls "x.__gt__(y)", and "x>=y" calls ' + '"x.__ge__(y)".\n' '\n' ' A rich comparison method may return the singleton ' '"NotImplemented"\n' @@ -3383,43 +3159,61 @@ topics = {'assert': 'The "assert" statement\n' ' on the value to determine if the result is true or ' 'false.\n' '\n' - ' By default, "__ne__()" delegates to "__eq__()" and ' - 'inverts the\n' - ' result unless it is "NotImplemented". There are no ' - 'other implied\n' - ' relationships among the comparison operators, for ' - 'example, the\n' - ' truth of "(x<y or x==y)" does not imply "x<=y". To ' - 'automatically\n' - ' generate ordering operations from a single root ' - 'operation, see\n' - ' "functools.total_ordering()".\n' - '\n' - ' See the paragraph on "__hash__()" for some important ' - 'notes on\n' - ' creating *hashable* objects which support custom ' - 'comparison\n' - ' operations and are usable as dictionary keys.\n' + ' There are no implied relationships among the comparison ' + 'operators.\n' + ' The truth of "x==y" does not imply that "x!=y" is ' + 'false.\n' + ' Accordingly, when defining "__eq__()", one should also ' + 'define\n' + ' "__ne__()" so that the operators will behave as ' + 'expected. See the\n' + ' paragraph on "__hash__()" for some important notes on ' + 'creating\n' + ' *hashable* objects which support custom comparison ' + 'operations and\n' + ' are usable as dictionary keys.\n' '\n' ' There are no swapped-argument versions of these methods ' '(to be used\n' ' when the left argument does not support the operation ' 'but the right\n' ' argument does); rather, "__lt__()" and "__gt__()" are ' - 'each other’s\n' - ' reflection, "__le__()" and "__ge__()" are each other’s ' + "each other's\n" + ' reflection, "__le__()" and "__ge__()" are each other\'s ' 'reflection,\n' - ' and "__eq__()" and "__ne__()" are their own reflection. ' - 'If the\n' - ' operands are of different types, and right operand’s ' - 'type is a\n' - ' direct or indirect subclass of the left operand’s type, ' + ' and "__eq__()" and "__ne__()" are their own reflection.\n' + '\n' + ' Arguments to rich comparison methods are never coerced.\n' + '\n' + ' To automatically generate ordering operations from a ' + 'single root\n' + ' operation, see "functools.total_ordering()".\n' + '\n' + 'object.__cmp__(self, other)\n' + '\n' + ' Called by comparison operations if rich comparison (see ' + 'above) is\n' + ' not defined. Should return a negative integer if "self ' + '< other",\n' + ' zero if "self == other", a positive integer if "self > ' + 'other". If\n' + ' no "__cmp__()", "__eq__()" or "__ne__()" operation is ' + 'defined,\n' + ' class instances are compared by object identity ' + '("address"). See\n' + ' also the description of "__hash__()" for some important ' + 'notes on\n' + ' creating *hashable* objects which support custom ' + 'comparison\n' + ' operations and are usable as dictionary keys. (Note: ' 'the\n' - ' reflected method of the right operand has priority, ' - 'otherwise the\n' - ' left operand’s method has priority. Virtual subclassing ' - 'is not\n' - ' considered.\n' + ' restriction that exceptions are not propagated by ' + '"__cmp__()" has\n' + ' been removed since Python 1.5.)\n' + '\n' + 'object.__rcmp__(self, other)\n' + '\n' + ' Changed in version 2.1: No longer supported.\n' '\n' 'object.__hash__(self)\n' '\n' @@ -3427,8 +3221,8 @@ topics = {'assert': 'The "assert" statement\n' 'on members\n' ' of hashed collections including "set", "frozenset", and ' '"dict".\n' - ' "__hash__()" should return an integer. The only required ' - 'property\n' + ' "__hash__()" should return an integer. The only ' + 'required property\n' ' is that objects which compare equal have the same hash ' 'value; it is\n' ' advised to mix together the hash values of the ' @@ -3440,118 +3234,94 @@ topics = {'assert': 'The "assert" statement\n' ' def __hash__(self):\n' ' return hash((self.name, self.nick, self.color))\n' '\n' - ' Note: "hash()" truncates the value returned from an ' - 'object’s\n' - ' custom "__hash__()" method to the size of a ' - '"Py_ssize_t". This\n' - ' is typically 8 bytes on 64-bit builds and 4 bytes on ' - '32-bit\n' - ' builds. If an object’s "__hash__()" must ' - 'interoperate on builds\n' - ' of different bit sizes, be sure to check the width on ' - 'all\n' - ' supported builds. An easy way to do this is with ' - '"python -c\n' - ' "import sys; print(sys.hash_info.width)"".\n' - '\n' - ' If a class does not define an "__eq__()" method it ' - 'should not\n' - ' define a "__hash__()" operation either; if it defines ' - '"__eq__()"\n' - ' but not "__hash__()", its instances will not be usable ' - 'as items in\n' - ' hashable collections. If a class defines mutable ' - 'objects and\n' - ' implements an "__eq__()" method, it should not ' - 'implement\n' - ' "__hash__()", since the implementation of hashable ' - 'collections\n' - ' requires that a key’s hash value is immutable (if the ' - 'object’s hash\n' - ' value changes, it will be in the wrong hash bucket).\n' - '\n' - ' User-defined classes have "__eq__()" and "__hash__()" ' + ' If a class does not define a "__cmp__()" or "__eq__()" ' + 'method it\n' + ' should not define a "__hash__()" operation either; if it ' + 'defines\n' + ' "__cmp__()" or "__eq__()" but not "__hash__()", its ' + 'instances will\n' + ' not be usable in hashed collections. If a class defines ' + 'mutable\n' + ' objects and implements a "__cmp__()" or "__eq__()" ' + 'method, it\n' + ' should not implement "__hash__()", since hashable ' + 'collection\n' + " implementations require that an object's hash value is " + 'immutable\n' + " (if the object's hash value changes, it will be in the " + 'wrong hash\n' + ' bucket).\n' + '\n' + ' User-defined classes have "__cmp__()" and "__hash__()" ' 'methods by\n' ' default; with them, all objects compare unequal (except ' 'with\n' - ' themselves) and "x.__hash__()" returns an appropriate ' - 'value such\n' - ' that "x == y" implies both that "x is y" and "hash(x) == ' - 'hash(y)".\n' - '\n' - ' A class that overrides "__eq__()" and does not define ' - '"__hash__()"\n' - ' will have its "__hash__()" implicitly set to "None". ' - 'When the\n' - ' "__hash__()" method of a class is "None", instances of ' - 'the class\n' - ' will raise an appropriate "TypeError" when a program ' - 'attempts to\n' - ' retrieve their hash value, and will also be correctly ' - 'identified as\n' - ' unhashable when checking "isinstance(obj,\n' - ' collections.abc.Hashable)".\n' - '\n' - ' If a class that overrides "__eq__()" needs to retain ' - 'the\n' - ' implementation of "__hash__()" from a parent class, the ' - 'interpreter\n' - ' must be told this explicitly by setting "__hash__ =\n' - ' <ParentClass>.__hash__".\n' - '\n' - ' If a class that does not override "__eq__()" wishes to ' - 'suppress\n' - ' hash support, it should include "__hash__ = None" in the ' - 'class\n' - ' definition. A class which defines its own "__hash__()" ' - 'that\n' - ' explicitly raises a "TypeError" would be incorrectly ' - 'identified as\n' - ' hashable by an "isinstance(obj, ' - 'collections.abc.Hashable)" call.\n' - '\n' - ' Note: By default, the "__hash__()" values of str and ' - 'bytes\n' - ' objects are “salted” with an unpredictable random ' - 'value.\n' - ' Although they remain constant within an individual ' - 'Python\n' - ' process, they are not predictable between repeated ' - 'invocations of\n' - ' Python.This is intended to provide protection against ' - 'a denial-\n' - ' of-service caused by carefully-chosen inputs that ' - 'exploit the\n' - ' worst case performance of a dict insertion, O(n^2) ' - 'complexity.\n' - ' See ' - 'http://www.ocert.org/advisories/ocert-2011-003.html for\n' - ' details.Changing hash values affects the iteration ' - 'order of sets.\n' - ' Python has never made guarantees about this ordering ' - '(and it\n' - ' typically varies between 32-bit and 64-bit builds).See ' - 'also\n' - ' "PYTHONHASHSEED".\n' - '\n' - ' Changed in version 3.3: Hash randomization is enabled by ' - 'default.\n' - '\n' - 'object.__bool__(self)\n' + ' themselves) and "x.__hash__()" returns a result derived ' + 'from\n' + ' "id(x)".\n' + '\n' + ' Classes which inherit a "__hash__()" method from a ' + 'parent class but\n' + ' change the meaning of "__cmp__()" or "__eq__()" such ' + 'that the hash\n' + ' value returned is no longer appropriate (e.g. by ' + 'switching to a\n' + ' value-based concept of equality instead of the default ' + 'identity\n' + ' based equality) can explicitly flag themselves as being ' + 'unhashable\n' + ' by setting "__hash__ = None" in the class definition. ' + 'Doing so\n' + ' means that not only will instances of the class raise ' + 'an\n' + ' appropriate "TypeError" when a program attempts to ' + 'retrieve their\n' + ' hash value, but they will also be correctly identified ' + 'as\n' + ' unhashable when checking "isinstance(obj, ' + 'collections.Hashable)"\n' + ' (unlike classes which define their own "__hash__()" to ' + 'explicitly\n' + ' raise "TypeError").\n' + '\n' + ' Changed in version 2.5: "__hash__()" may now also return ' + 'a long\n' + ' integer object; the 32-bit integer is then derived from ' + 'the hash of\n' + ' that object.\n' + '\n' + ' Changed in version 2.6: "__hash__" may now be set to ' + '"None" to\n' + ' explicitly flag instances of a class as unhashable.\n' + '\n' + 'object.__nonzero__(self)\n' '\n' ' Called to implement truth value testing and the built-in ' 'operation\n' - ' "bool()"; should return "False" or "True". When this ' - 'method is not\n' - ' defined, "__len__()" is called, if it is defined, and ' - 'the object is\n' - ' considered true if its result is nonzero. If a class ' + ' "bool()"; should return "False" or "True", or their ' + 'integer\n' + ' equivalents "0" or "1". When this method is not ' + 'defined,\n' + ' "__len__()" is called, if it is defined, and the object ' + 'is\n' + ' considered true if its result is nonzero. If a class ' 'defines\n' - ' neither "__len__()" nor "__bool__()", all its instances ' - 'are\n' - ' considered true.\n', - 'debugger': '"pdb" — The Python Debugger\n' - '***************************\n' + ' neither "__len__()" nor "__nonzero__()", all its ' + 'instances are\n' + ' considered true.\n' + '\n' + 'object.__unicode__(self)\n' + '\n' + ' Called to implement "unicode()" built-in; should return ' + 'a Unicode\n' + ' object. When this method is not defined, string ' + 'conversion is\n' + ' attempted, and the result of string conversion is ' + 'converted to\n' + ' Unicode using the system default encoding.\n', + 'debugger': '\n' + '"pdb" --- The Python Debugger\n' + '*****************************\n' '\n' '**Source code:** Lib/pdb.py\n' '\n' @@ -3569,15 +3339,15 @@ topics = {'assert': 'The "assert" statement\n' 'debugging\n' 'and can be called under program control.\n' '\n' - 'The debugger is extensible – it is actually defined as the ' + 'The debugger is extensible --- it is actually defined as the ' 'class\n' '"Pdb". This is currently undocumented but easily understood by ' 'reading\n' 'the source. The extension interface uses the modules "bdb" and ' '"cmd".\n' '\n' - 'The debugger’s prompt is "(Pdb)". Typical usage to run a program ' - 'under\n' + 'The debugger\'s prompt is "(Pdb)". Typical usage to run a ' + 'program under\n' 'control of the debugger is:\n' '\n' ' >>> import pdb\n' @@ -3591,40 +3361,25 @@ topics = {'assert': 'The "assert" statement\n' ' > <string>(1)?()\n' ' (Pdb)\n' '\n' - 'Changed in version 3.3: Tab-completion via the "readline" module ' - 'is\n' - 'available for commands and command arguments, e.g. the current ' - 'global\n' - 'and local names are offered as arguments of the "p" command.\n' - '\n' '"pdb.py" can also be invoked as a script to debug other ' 'scripts. For\n' 'example:\n' '\n' - ' python3 -m pdb myscript.py\n' + ' python -m pdb myscript.py\n' '\n' 'When invoked as a script, pdb will automatically enter ' 'post-mortem\n' - 'debugging if the program being debugged exits abnormally. After ' + 'debugging if the program being debugged exits abnormally. After ' 'post-\n' 'mortem debugging (or after normal exit of the program), pdb ' 'will\n' - 'restart the program. Automatic restarting preserves pdb’s state ' + "restart the program. Automatic restarting preserves pdb's state " '(such\n' 'as breakpoints) and in most cases is more useful than quitting ' 'the\n' - 'debugger upon program’s exit.\n' + "debugger upon program's exit.\n" '\n' - 'New in version 3.2: "pdb.py" now accepts a "-c" option that ' - 'executes\n' - 'commands as if given in a ".pdbrc" file, see Debugger Commands.\n' - '\n' - 'New in version 3.7: "pdb.py" now accepts a "-m" option that ' - 'execute\n' - 'modules similar to the way "python3 -m" does. As with a script, ' - 'the\n' - 'debugger will pause execution just before the first line of the\n' - 'module.\n' + 'New in version 2.4: Restarting post-mortem behavior added.\n' '\n' 'The typical usage to break into the debugger from a running ' 'program is\n' @@ -3636,11 +3391,7 @@ topics = {'assert': 'The "assert" statement\n' 'then\n' 'step through the code following this statement, and continue ' 'running\n' - 'without the debugger using the "continue" command.\n' - '\n' - 'New in version 3.7: The built-in "breakpoint()", when called ' - 'with\n' - 'defaults, can be used instead of "import pdb; pdb.set_trace()".\n' + 'without the debugger using the "c" command.\n' '\n' 'The typical usage to inspect a crashed program is:\n' '\n' @@ -3652,45 +3403,42 @@ topics = {'assert': 'The "assert" statement\n' ' File "./mymodule.py", line 4, in test\n' ' test2()\n' ' File "./mymodule.py", line 3, in test2\n' - ' print(spam)\n' + ' print spam\n' ' NameError: spam\n' ' >>> pdb.pm()\n' ' > ./mymodule.py(3)test2()\n' - ' -> print(spam)\n' + ' -> print spam\n' ' (Pdb)\n' '\n' 'The module defines the following functions; each enters the ' 'debugger\n' 'in a slightly different way:\n' '\n' - 'pdb.run(statement, globals=None, locals=None)\n' + 'pdb.run(statement[, globals[, locals]])\n' '\n' - ' Execute the *statement* (given as a string or a code object) ' - 'under\n' - ' debugger control. The debugger prompt appears before any ' - 'code is\n' - ' executed; you can set breakpoints and type "continue", or you ' + ' Execute the *statement* (given as a string) under debugger ' + 'control.\n' + ' The debugger prompt appears before any code is executed; you ' 'can\n' - ' step through the statement using "step" or "next" (all these\n' - ' commands are explained below). The optional *globals* and ' - '*locals*\n' - ' arguments specify the environment in which the code is ' - 'executed; by\n' - ' default the dictionary of the module "__main__" is used. ' - '(See the\n' - ' explanation of the built-in "exec()" or "eval()" functions.)\n' - '\n' - 'pdb.runeval(expression, globals=None, locals=None)\n' - '\n' - ' Evaluate the *expression* (given as a string or a code ' - 'object)\n' - ' under debugger control. When "runeval()" returns, it returns ' + ' set breakpoints and type "continue", or you can step through ' 'the\n' - ' value of the expression. Otherwise this function is similar ' - 'to\n' - ' "run()".\n' + ' statement using "step" or "next" (all these commands are ' + 'explained\n' + ' below). The optional *globals* and *locals* arguments ' + 'specify the\n' + ' environment in which the code is executed; by default the\n' + ' dictionary of the module "__main__" is used. (See the ' + 'explanation\n' + ' of the "exec" statement or the "eval()" built-in function.)\n' + '\n' + 'pdb.runeval(expression[, globals[, locals]])\n' + '\n' + ' Evaluate the *expression* (given as a string) under debugger\n' + ' control. When "runeval()" returns, it returns the value of ' + 'the\n' + ' expression. Otherwise this function is similar to "run()".\n' '\n' - 'pdb.runcall(function, *args, **kwds)\n' + 'pdb.runcall(function[, argument, ...])\n' '\n' ' Call the *function* (a function or method object, not a ' 'string)\n' @@ -3700,20 +3448,16 @@ topics = {'assert': 'The "assert" statement\n' 'appears\n' ' as soon as the function is entered.\n' '\n' - 'pdb.set_trace(*, header=None)\n' + 'pdb.set_trace()\n' '\n' ' Enter the debugger at the calling stack frame. This is ' 'useful to\n' ' hard-code a breakpoint at a given point in a program, even if ' 'the\n' ' code is not otherwise being debugged (e.g. when an assertion\n' - ' fails). If given, *header* is printed to the console just ' - 'before\n' - ' debugging begins.\n' + ' fails).\n' '\n' - ' Changed in version 3.7: The keyword-only argument *header*.\n' - '\n' - 'pdb.post_mortem(traceback=None)\n' + 'pdb.post_mortem([traceback])\n' '\n' ' Enter post-mortem debugging of the given *traceback* object. ' 'If no\n' @@ -3735,7 +3479,7 @@ topics = {'assert': 'The "assert" statement\n' 'to access further features, you have to do this yourself:\n' '\n' "class pdb.Pdb(completekey='tab', stdin=None, stdout=None, " - 'skip=None, nosigint=False, readrc=True)\n' + 'skip=None)\n' '\n' ' "Pdb" is the debugger class.\n' '\n' @@ -3750,486 +3494,20 @@ topics = {'assert': 'The "assert" statement\n' ' originate in a module that matches one of these patterns. ' '[1]\n' '\n' - ' By default, Pdb sets a handler for the SIGINT signal (which ' - 'is sent\n' - ' when the user presses "Ctrl-C" on the console) when you give ' - 'a\n' - ' "continue" command. This allows you to break into the ' - 'debugger\n' - ' again by pressing "Ctrl-C". If you want Pdb not to touch ' - 'the\n' - ' SIGINT handler, set *nosigint* to true.\n' - '\n' - ' The *readrc* argument defaults to true and controls whether ' - 'Pdb\n' - ' will load .pdbrc files from the filesystem.\n' - '\n' ' Example call to enable tracing with *skip*:\n' '\n' " import pdb; pdb.Pdb(skip=['django.*']).set_trace()\n" '\n' - ' Raises an auditing event "pdb.Pdb" with no arguments.\n' + ' New in version 2.7: The *skip* argument.\n' '\n' - ' New in version 3.1: The *skip* argument.\n' - '\n' - ' New in version 3.2: The *nosigint* argument. Previously, a ' - 'SIGINT\n' - ' handler was never set by Pdb.\n' - '\n' - ' Changed in version 3.6: The *readrc* argument.\n' - '\n' - ' run(statement, globals=None, locals=None)\n' - ' runeval(expression, globals=None, locals=None)\n' - ' runcall(function, *args, **kwds)\n' + ' run(statement[, globals[, locals]])\n' + ' runeval(expression[, globals[, locals]])\n' + ' runcall(function[, argument, ...])\n' ' set_trace()\n' '\n' - ' See the documentation for the functions explained above.\n' - '\n' - '\n' - 'Debugger Commands\n' - '=================\n' - '\n' - 'The commands recognized by the debugger are listed below. Most\n' - 'commands can be abbreviated to one or two letters as indicated; ' - 'e.g.\n' - '"h(elp)" means that either "h" or "help" can be used to enter ' - 'the help\n' - 'command (but not "he" or "hel", nor "H" or "Help" or "HELP").\n' - 'Arguments to commands must be separated by whitespace (spaces ' - 'or\n' - 'tabs). Optional arguments are enclosed in square brackets ' - '("[]") in\n' - 'the command syntax; the square brackets must not be typed.\n' - 'Alternatives in the command syntax are separated by a vertical ' - 'bar\n' - '("|").\n' - '\n' - 'Entering a blank line repeats the last command entered. ' - 'Exception: if\n' - 'the last command was a "list" command, the next 11 lines are ' - 'listed.\n' - '\n' - 'Commands that the debugger doesn’t recognize are assumed to be ' - 'Python\n' - 'statements and are executed in the context of the program being\n' - 'debugged. Python statements can also be prefixed with an ' - 'exclamation\n' - 'point ("!"). This is a powerful way to inspect the program ' - 'being\n' - 'debugged; it is even possible to change a variable or call a ' - 'function.\n' - 'When an exception occurs in such a statement, the exception name ' - 'is\n' - 'printed but the debugger’s state is not changed.\n' - '\n' - 'The debugger supports aliases. Aliases can have parameters ' - 'which\n' - 'allows one a certain level of adaptability to the context under\n' - 'examination.\n' - '\n' - 'Multiple commands may be entered on a single line, separated by ' - '";;".\n' - '(A single ";" is not used as it is the separator for multiple ' - 'commands\n' - 'in a line that is passed to the Python parser.) No intelligence ' - 'is\n' - 'applied to separating the commands; the input is split at the ' - 'first\n' - '";;" pair, even if it is in the middle of a quoted string.\n' - '\n' - 'If a file ".pdbrc" exists in the user’s home directory or in ' - 'the\n' - 'current directory, it is read in and executed as if it had been ' - 'typed\n' - 'at the debugger prompt. This is particularly useful for ' - 'aliases. If\n' - 'both files exist, the one in the home directory is read first ' - 'and\n' - 'aliases defined there can be overridden by the local file.\n' - '\n' - 'Changed in version 3.2: ".pdbrc" can now contain commands that\n' - 'continue debugging, such as "continue" or "next". Previously, ' - 'these\n' - 'commands had no effect.\n' - '\n' - 'h(elp) [command]\n' - '\n' - ' Without argument, print the list of available commands. With ' - 'a\n' - ' *command* as argument, print help about that command. "help ' - 'pdb"\n' - ' displays the full documentation (the docstring of the "pdb"\n' - ' module). Since the *command* argument must be an identifier, ' - '"help\n' - ' exec" must be entered to get help on the "!" command.\n' - '\n' - 'w(here)\n' - '\n' - ' Print a stack trace, with the most recent frame at the ' - 'bottom. An\n' - ' arrow indicates the current frame, which determines the ' - 'context of\n' - ' most commands.\n' - '\n' - 'd(own) [count]\n' - '\n' - ' Move the current frame *count* (default one) levels down in ' - 'the\n' - ' stack trace (to a newer frame).\n' - '\n' - 'u(p) [count]\n' - '\n' - ' Move the current frame *count* (default one) levels up in the ' - 'stack\n' - ' trace (to an older frame).\n' - '\n' - 'b(reak) [([filename:]lineno | function) [, condition]]\n' - '\n' - ' With a *lineno* argument, set a break there in the current ' - 'file.\n' - ' With a *function* argument, set a break at the first ' - 'executable\n' - ' statement within that function. The line number may be ' - 'prefixed\n' - ' with a filename and a colon, to specify a breakpoint in ' - 'another\n' - ' file (probably one that hasn’t been loaded yet). The file ' - 'is\n' - ' searched on "sys.path". Note that each breakpoint is ' - 'assigned a\n' - ' number to which all the other breakpoint commands refer.\n' - '\n' - ' If a second argument is present, it is an expression which ' - 'must\n' - ' evaluate to true before the breakpoint is honored.\n' - '\n' - ' Without argument, list all breaks, including for each ' - 'breakpoint,\n' - ' the number of times that breakpoint has been hit, the ' - 'current\n' - ' ignore count, and the associated condition if any.\n' - '\n' - 'tbreak [([filename:]lineno | function) [, condition]]\n' - '\n' - ' Temporary breakpoint, which is removed automatically when it ' - 'is\n' - ' first hit. The arguments are the same as for "break".\n' - '\n' - 'cl(ear) [filename:lineno | bpnumber ...]\n' - '\n' - ' With a *filename:lineno* argument, clear all the breakpoints ' - 'at\n' - ' this line. With a space separated list of breakpoint numbers, ' - 'clear\n' - ' those breakpoints. Without argument, clear all breaks (but ' - 'first\n' - ' ask confirmation).\n' - '\n' - 'disable [bpnumber ...]\n' - '\n' - ' Disable the breakpoints given as a space separated list of\n' - ' breakpoint numbers. Disabling a breakpoint means it cannot ' - 'cause\n' - ' the program to stop execution, but unlike clearing a ' - 'breakpoint, it\n' - ' remains in the list of breakpoints and can be (re-)enabled.\n' - '\n' - 'enable [bpnumber ...]\n' - '\n' - ' Enable the breakpoints specified.\n' - '\n' - 'ignore bpnumber [count]\n' - '\n' - ' Set the ignore count for the given breakpoint number. If ' - 'count is\n' - ' omitted, the ignore count is set to 0. A breakpoint becomes ' - 'active\n' - ' when the ignore count is zero. When non-zero, the count is\n' - ' decremented each time the breakpoint is reached and the ' - 'breakpoint\n' - ' is not disabled and any associated condition evaluates to ' - 'true.\n' - '\n' - 'condition bpnumber [condition]\n' - '\n' - ' Set a new *condition* for the breakpoint, an expression which ' - 'must\n' - ' evaluate to true before the breakpoint is honored. If ' - '*condition*\n' - ' is absent, any existing condition is removed; i.e., the ' - 'breakpoint\n' - ' is made unconditional.\n' - '\n' - 'commands [bpnumber]\n' - '\n' - ' Specify a list of commands for breakpoint number *bpnumber*. ' - 'The\n' - ' commands themselves appear on the following lines. Type a ' - 'line\n' - ' containing just "end" to terminate the commands. An example:\n' - '\n' - ' (Pdb) commands 1\n' - ' (com) p some_variable\n' - ' (com) end\n' - ' (Pdb)\n' - '\n' - ' To remove all commands from a breakpoint, type "commands" ' - 'and\n' - ' follow it immediately with "end"; that is, give no commands.\n' - '\n' - ' With no *bpnumber* argument, "commands" refers to the last\n' - ' breakpoint set.\n' - '\n' - ' You can use breakpoint commands to start your program up ' - 'again.\n' - ' Simply use the "continue" command, or "step", or any other ' - 'command\n' - ' that resumes execution.\n' - '\n' - ' Specifying any command resuming execution (currently ' - '"continue",\n' - ' "step", "next", "return", "jump", "quit" and their ' - 'abbreviations)\n' - ' terminates the command list (as if that command was ' - 'immediately\n' - ' followed by end). This is because any time you resume ' - 'execution\n' - ' (even with a simple next or step), you may encounter another\n' - ' breakpoint—which could have its own command list, leading to\n' - ' ambiguities about which list to execute.\n' - '\n' - ' If you use the ‘silent’ command in the command list, the ' - 'usual\n' - ' message about stopping at a breakpoint is not printed. This ' - 'may be\n' - ' desirable for breakpoints that are to print a specific ' - 'message and\n' - ' then continue. If none of the other commands print anything, ' - 'you\n' - ' see no sign that the breakpoint was reached.\n' - '\n' - 's(tep)\n' - '\n' - ' Execute the current line, stop at the first possible ' - 'occasion\n' - ' (either in a function that is called or on the next line in ' - 'the\n' - ' current function).\n' - '\n' - 'n(ext)\n' - '\n' - ' Continue execution until the next line in the current ' - 'function is\n' - ' reached or it returns. (The difference between "next" and ' - '"step"\n' - ' is that "step" stops inside a called function, while "next"\n' - ' executes called functions at (nearly) full speed, only ' - 'stopping at\n' - ' the next line in the current function.)\n' - '\n' - 'unt(il) [lineno]\n' - '\n' - ' Without argument, continue execution until the line with a ' - 'number\n' - ' greater than the current one is reached.\n' - '\n' - ' With a line number, continue execution until a line with a ' - 'number\n' - ' greater or equal to that is reached. In both cases, also ' - 'stop when\n' - ' the current frame returns.\n' - '\n' - ' Changed in version 3.2: Allow giving an explicit line ' - 'number.\n' - '\n' - 'r(eturn)\n' - '\n' - ' Continue execution until the current function returns.\n' - '\n' - 'c(ont(inue))\n' - '\n' - ' Continue execution, only stop when a breakpoint is ' - 'encountered.\n' - '\n' - 'j(ump) lineno\n' - '\n' - ' Set the next line that will be executed. Only available in ' - 'the\n' - ' bottom-most frame. This lets you jump back and execute code ' - 'again,\n' - ' or jump forward to skip code that you don’t want to run.\n' - '\n' - ' It should be noted that not all jumps are allowed – for ' - 'instance it\n' - ' is not possible to jump into the middle of a "for" loop or ' - 'out of a\n' - ' "finally" clause.\n' - '\n' - 'l(ist) [first[, last]]\n' - '\n' - ' List source code for the current file. Without arguments, ' - 'list 11\n' - ' lines around the current line or continue the previous ' - 'listing.\n' - ' With "." as argument, list 11 lines around the current line. ' - 'With\n' - ' one argument, list 11 lines around at that line. With two\n' - ' arguments, list the given range; if the second argument is ' - 'less\n' - ' than the first, it is interpreted as a count.\n' - '\n' - ' The current line in the current frame is indicated by "->". ' - 'If an\n' - ' exception is being debugged, the line where the exception ' - 'was\n' - ' originally raised or propagated is indicated by ">>", if it ' - 'differs\n' - ' from the current line.\n' - '\n' - ' New in version 3.2: The ">>" marker.\n' - '\n' - 'll | longlist\n' - '\n' - ' List all source code for the current function or frame.\n' - ' Interesting lines are marked as for "list".\n' - '\n' - ' New in version 3.2.\n' - '\n' - 'a(rgs)\n' - '\n' - ' Print the argument list of the current function.\n' - '\n' - 'p expression\n' - '\n' - ' Evaluate the *expression* in the current context and print ' - 'its\n' - ' value.\n' - '\n' - ' Note: "print()" can also be used, but is not a debugger ' - 'command —\n' - ' this executes the Python "print()" function.\n' - '\n' - 'pp expression\n' - '\n' - ' Like the "p" command, except the value of the expression is ' - 'pretty-\n' - ' printed using the "pprint" module.\n' - '\n' - 'whatis expression\n' - '\n' - ' Print the type of the *expression*.\n' - '\n' - 'source expression\n' - '\n' - ' Try to get source code for the given object and display it.\n' - '\n' - ' New in version 3.2.\n' - '\n' - 'display [expression]\n' - '\n' - ' Display the value of the expression if it changed, each time\n' - ' execution stops in the current frame.\n' - '\n' - ' Without expression, list all display expressions for the ' - 'current\n' - ' frame.\n' - '\n' - ' New in version 3.2.\n' - '\n' - 'undisplay [expression]\n' - '\n' - ' Do not display the expression any more in the current frame.\n' - ' Without expression, clear all display expressions for the ' - 'current\n' - ' frame.\n' - '\n' - ' New in version 3.2.\n' - '\n' - 'interact\n' - '\n' - ' Start an interactive interpreter (using the "code" module) ' - 'whose\n' - ' global namespace contains all the (global and local) names ' - 'found in\n' - ' the current scope.\n' - '\n' - ' New in version 3.2.\n' - '\n' - 'alias [name [command]]\n' - '\n' - ' Create an alias called *name* that executes *command*. The ' - 'command\n' - ' must *not* be enclosed in quotes. Replaceable parameters can ' - 'be\n' - ' indicated by "%1", "%2", and so on, while "%*" is replaced by ' - 'all\n' - ' the parameters. If no command is given, the current alias ' - 'for\n' - ' *name* is shown. If no arguments are given, all aliases are ' - 'listed.\n' - '\n' - ' Aliases may be nested and can contain anything that can be ' - 'legally\n' - ' typed at the pdb prompt. Note that internal pdb commands ' - '*can* be\n' - ' overridden by aliases. Such a command is then hidden until ' - 'the\n' - ' alias is removed. Aliasing is recursively applied to the ' - 'first\n' - ' word of the command line; all other words in the line are ' - 'left\n' - ' alone.\n' - '\n' - ' As an example, here are two useful aliases (especially when ' - 'placed\n' - ' in the ".pdbrc" file):\n' - '\n' - ' # Print instance variables (usage "pi classInst")\n' - ' alias pi for k in %1.__dict__.keys(): ' - 'print("%1.",k,"=",%1.__dict__[k])\n' - ' # Print instance variables in self\n' - ' alias ps pi self\n' - '\n' - 'unalias name\n' - '\n' - ' Delete the specified alias.\n' - '\n' - '! statement\n' - '\n' - ' Execute the (one-line) *statement* in the context of the ' - 'current\n' - ' stack frame. The exclamation point can be omitted unless the ' - 'first\n' - ' word of the statement resembles a debugger command. To set ' - 'a\n' - ' global variable, you can prefix the assignment command with ' - 'a\n' - ' "global" statement on the same line, e.g.:\n' - '\n' - " (Pdb) global list_options; list_options = ['-l']\n" - ' (Pdb)\n' - '\n' - 'run [args ...]\n' - 'restart [args ...]\n' - '\n' - ' Restart the debugged Python program. If an argument is ' - 'supplied,\n' - ' it is split with "shlex" and the result is used as the new\n' - ' "sys.argv". History, breakpoints, actions and debugger ' - 'options are\n' - ' preserved. "restart" is an alias for "run".\n' - '\n' - 'q(uit)\n' - '\n' - ' Quit from the debugger. The program being executed is ' - 'aborted.\n' - '\n' - '-[ Footnotes ]-\n' - '\n' - '[1] Whether a frame is considered to originate in a certain ' - 'module\n' - ' is determined by the "__name__" in the frame globals.\n', - 'del': 'The "del" statement\n' + ' See the documentation for the functions explained above.\n', + 'del': '\n' + 'The "del" statement\n' '*******************\n' '\n' ' del_stmt ::= "del" target_list\n' @@ -4242,23 +3520,23 @@ topics = {'assert': 'The "assert" statement\n' 'Deletion of a target list recursively deletes each target, from left\n' 'to right.\n' '\n' - 'Deletion of a name removes the binding of that name from the local ' + 'Deletion of a name removes the binding of that name from the local ' 'or\n' 'global namespace, depending on whether the name occurs in a "global"\n' 'statement in the same code block. If the name is unbound, a\n' '"NameError" exception will be raised.\n' '\n' + 'It is illegal to delete a name from the local namespace if it occurs\n' + 'as a free variable in a nested block.\n' + '\n' 'Deletion of attribute references, subscriptions and slicings is ' 'passed\n' 'to the primary object involved; deletion of a slicing is in general\n' 'equivalent to assignment of an empty slice of the right type (but ' 'even\n' - 'this is determined by the sliced object).\n' - '\n' - 'Changed in version 3.2: Previously it was illegal to delete a name\n' - 'from the local namespace if it occurs as a free variable in a nested\n' - 'block.\n', - 'dict': 'Dictionary displays\n' + 'this is determined by the sliced object).\n', + 'dict': '\n' + 'Dictionary displays\n' '*******************\n' '\n' 'A dictionary display is a possibly empty series of key/datum pairs\n' @@ -4267,7 +3545,7 @@ topics = {'assert': 'The "assert" statement\n' ' dict_display ::= "{" [key_datum_list | dict_comprehension] ' '"}"\n' ' key_datum_list ::= key_datum ("," key_datum)* [","]\n' - ' key_datum ::= expression ":" expression | "**" or_expr\n' + ' key_datum ::= expression ":" expression\n' ' dict_comprehension ::= expression ":" expression comp_for\n' '\n' 'A dictionary display yields a new dictionary object.\n' @@ -4277,21 +3555,13 @@ topics = {'assert': 'The "assert" statement\n' 'dictionary:\n' 'each key object is used as a key into the dictionary to store the\n' 'corresponding datum. This means that you can specify the same key\n' - 'multiple times in the key/datum list, and the final dictionary’s ' + "multiple times in the key/datum list, and the final dictionary's " 'value\n' 'for that key will be the last one given.\n' '\n' - 'A double asterisk "**" denotes *dictionary unpacking*. Its operand\n' - 'must be a *mapping*. Each mapping item is added to the new\n' - 'dictionary. Later values replace values already set by earlier\n' - 'key/datum pairs and earlier dictionary unpackings.\n' - '\n' - 'New in version 3.5: Unpacking into dictionary displays, originally\n' - 'proposed by **PEP 448**.\n' - '\n' 'A dict comprehension, in contrast to list and set comprehensions,\n' 'needs two expressions separated with a colon followed by the usual\n' - '“for” and “if” clauses. When the comprehension is run, the ' + '"for" and "if" clauses. When the comprehension is run, the ' 'resulting\n' 'key and value elements are inserted in the new dictionary in the ' 'order\n' @@ -4301,47 +3571,60 @@ topics = {'assert': 'The "assert" statement\n' 'section The standard type hierarchy. (To summarize, the key type\n' 'should be *hashable*, which excludes all mutable objects.) Clashes\n' 'between duplicate keys are not detected; the last datum (textually\n' - 'rightmost in the display) stored for a given key value prevails.\n' - '\n' - 'Changed in version 3.8: Prior to Python 3.8, in dict ' - 'comprehensions,\n' - 'the evaluation order of key and value was not well-defined. In\n' - 'CPython, the value was evaluated before the key. Starting with ' - '3.8,\n' - 'the key is evaluated before the value, as proposed by **PEP 572**.\n', - 'dynamic-features': 'Interaction with dynamic features\n' + 'rightmost in the display) stored for a given key value prevails.\n', + 'dynamic-features': '\n' + 'Interaction with dynamic features\n' '*********************************\n' '\n' - 'Name resolution of free variables occurs at runtime, not ' - 'at compile\n' - 'time. This means that the following code will print 42:\n' + 'There are several cases where Python statements are ' + 'illegal when used\n' + 'in conjunction with nested scopes that contain free ' + 'variables.\n' '\n' - ' i = 10\n' - ' def f():\n' - ' print(i)\n' - ' i = 42\n' - ' f()\n' + 'If a variable is referenced in an enclosing scope, it is ' + 'illegal to\n' + 'delete the name. An error will be reported at compile ' + 'time.\n' '\n' - 'The "eval()" and "exec()" functions do not have access ' - 'to the full\n' - 'environment for resolving names. Names may be resolved ' - 'in the local\n' - 'and global namespaces of the caller. Free variables are ' - 'not resolved\n' - 'in the nearest enclosing namespace, but in the global ' - 'namespace. [1]\n' - 'The "exec()" and "eval()" functions have optional ' + 'If the wild card form of import --- "import *" --- is ' + 'used in a\n' + 'function and the function contains or is a nested block ' + 'with free\n' + 'variables, the compiler will raise a "SyntaxError".\n' + '\n' + 'If "exec" is used in a function and the function ' + 'contains or is a\n' + 'nested block with free variables, the compiler will ' + 'raise a\n' + '"SyntaxError" unless the exec explicitly specifies the ' + 'local namespace\n' + 'for the "exec". (In other words, "exec obj" would be ' + 'illegal, but\n' + '"exec obj in ns" would be legal.)\n' + '\n' + 'The "eval()", "execfile()", and "input()" functions and ' + 'the "exec"\n' + 'statement do not have access to the full environment for ' + 'resolving\n' + 'names. Names may be resolved in the local and global ' + 'namespaces of\n' + 'the caller. Free variables are not resolved in the ' + 'nearest enclosing\n' + 'namespace, but in the global namespace. [1] The "exec" ' + 'statement and\n' + 'the "eval()" and "execfile()" functions have optional ' 'arguments to\n' 'override the global and local namespace. If only one ' 'namespace is\n' 'specified, it is used for both.\n', - 'else': 'The "if" statement\n' + 'else': '\n' + 'The "if" statement\n' '******************\n' '\n' 'The "if" statement is used for conditional execution:\n' '\n' ' if_stmt ::= "if" expression ":" suite\n' - ' ("elif" expression ":" suite)*\n' + ' ( "elif" expression ":" suite )*\n' ' ["else" ":" suite]\n' '\n' 'It selects exactly one of the suites by evaluating the expressions ' @@ -4352,7 +3635,8 @@ topics = {'assert': 'The "assert" statement\n' '(and no other part of the "if" statement is executed or evaluated).\n' 'If all expressions are false, the suite of the "else" clause, if\n' 'present, is executed.\n', - 'exceptions': 'Exceptions\n' + 'exceptions': '\n' + 'Exceptions\n' '**********\n' '\n' 'Exceptions are a means of breaking out of the normal flow of ' @@ -4372,7 +3656,7 @@ topics = {'assert': 'The "assert" statement\n' 'error (such as division by zero). A Python program can also\n' 'explicitly raise an exception with the "raise" statement. ' 'Exception\n' - 'handlers are specified with the "try" … "except" statement. ' + 'handlers are specified with the "try" ... "except" statement. ' 'The\n' '"finally" clause of such a statement can be used to specify ' 'cleanup\n' @@ -4380,7 +3664,7 @@ topics = {'assert': 'The "assert" statement\n' 'whether an\n' 'exception occurred or not in the preceding code.\n' '\n' - 'Python uses the “termination” model of error handling: an ' + 'Python uses the "termination" model of error handling: an ' 'exception\n' 'handler can find out what happened and continue execution at ' 'an outer\n' @@ -4394,7 +3678,7 @@ topics = {'assert': 'The "assert" statement\n' 'terminates\n' 'execution of the program, or returns to its interactive main ' 'loop. In\n' - 'either case, it prints a stack traceback, except when the ' + 'either case, it prints a stack backtrace, except when the ' 'exception is\n' '"SystemExit".\n' '\n' @@ -4408,7 +3692,15 @@ topics = {'assert': 'The "assert" statement\n' 'about the\n' 'exceptional condition.\n' '\n' - 'Note: Exception messages are not part of the Python API. ' + 'Exceptions can also be identified by strings, in which case ' + 'the\n' + '"except" clause is selected by object identity. An arbitrary ' + 'value\n' + 'can be raised along with the identifying string which can be ' + 'passed to\n' + 'the handler.\n' + '\n' + 'Note: Messages to exceptions are not part of the Python API. ' 'Their\n' ' contents may change from one version of Python to the next ' 'without\n' @@ -4428,54 +3720,171 @@ topics = {'assert': 'The "assert" statement\n' ' these operations is not available at the time the module ' 'is\n' ' compiled.\n', - 'execmodel': 'Execution model\n' + 'exec': '\n' + 'The "exec" statement\n' + '********************\n' + '\n' + ' exec_stmt ::= "exec" or_expr ["in" expression ["," expression]]\n' + '\n' + 'This statement supports dynamic execution of Python code. The ' + 'first\n' + 'expression should evaluate to either a Unicode string, a *Latin-1*\n' + 'encoded string, an open file object, a code object, or a tuple. If ' + 'it\n' + 'is a string, the string is parsed as a suite of Python statements\n' + 'which is then executed (unless a syntax error occurs). [1] If it is ' + 'an\n' + 'open file, the file is parsed until EOF and executed. If it is a ' + 'code\n' + 'object, it is simply executed. For the interpretation of a tuple, ' + 'see\n' + "below. In all cases, the code that's executed is expected to be " + 'valid\n' + 'as file input (see section File input). Be aware that the "return"\n' + 'and "yield" statements may not be used outside of function ' + 'definitions\n' + 'even within the context of code passed to the "exec" statement.\n' + '\n' + 'In all cases, if the optional parts are omitted, the code is ' + 'executed\n' + 'in the current scope. If only the first expression after "in" is\n' + 'specified, it should be a dictionary, which will be used for both ' + 'the\n' + 'global and the local variables. If two expressions are given, they\n' + 'are used for the global and local variables, respectively. If\n' + 'provided, *locals* can be any mapping object. Remember that at ' + 'module\n' + 'level, globals and locals are the same dictionary. If two separate\n' + 'objects are given as *globals* and *locals*, the code will be ' + 'executed\n' + 'as if it were embedded in a class definition.\n' + '\n' + 'The first expression may also be a tuple of length 2 or 3. In this\n' + 'case, the optional parts must be omitted. The form "exec(expr,\n' + 'globals)" is equivalent to "exec expr in globals", while the form\n' + '"exec(expr, globals, locals)" is equivalent to "exec expr in ' + 'globals,\n' + 'locals". The tuple form of "exec" provides compatibility with ' + 'Python\n' + '3, where "exec" is a function rather than a statement.\n' + '\n' + 'Changed in version 2.4: Formerly, *locals* was required to be a\n' + 'dictionary.\n' + '\n' + 'As a side effect, an implementation may insert additional keys into\n' + 'the dictionaries given besides those corresponding to variable ' + 'names\n' + 'set by the executed code. For example, the current implementation ' + 'may\n' + 'add a reference to the dictionary of the built-in module ' + '"__builtin__"\n' + 'under the key "__builtins__" (!).\n' + '\n' + "**Programmer's hints:** dynamic evaluation of expressions is " + 'supported\n' + 'by the built-in function "eval()". The built-in functions ' + '"globals()"\n' + 'and "locals()" return the current global and local dictionary,\n' + 'respectively, which may be useful to pass around for use by "exec".\n' + '\n' + '-[ Footnotes ]-\n' + '\n' + '[1] Note that the parser only accepts the Unix-style end of line\n' + ' convention. If you are reading the code from a file, make sure ' + 'to\n' + ' use *universal newlines* mode to convert Windows or Mac-style\n' + ' newlines.\n', + 'execmodel': '\n' + 'Execution model\n' '***************\n' '\n' '\n' - 'Structure of a program\n' - '======================\n' + 'Naming and binding\n' + '==================\n' '\n' - 'A Python program is constructed from code blocks. A *block* is ' - 'a piece\n' - 'of Python program text that is executed as a unit. The ' - 'following are\n' - 'blocks: a module, a function body, and a class definition. ' - 'Each\n' - 'command typed interactively is a block. A script file (a file ' - 'given\n' - 'as standard input to the interpreter or specified as a command ' - 'line\n' - 'argument to the interpreter) is a code block. A script command ' - '(a\n' - 'command specified on the interpreter command line with the ' - '"-c"\n' - 'option) is a code block. A module run as a top level script (as ' - 'module\n' - '"__main__") from the command line using a "-m" argument is also ' - 'a code\n' - 'block. The string argument passed to the built-in functions ' - '"eval()"\n' - 'and "exec()" is a code block.\n' + '*Names* refer to objects. Names are introduced by name ' + 'binding\n' + 'operations. Each occurrence of a name in the program text ' + 'refers to\n' + 'the *binding* of that name established in the innermost ' + 'function block\n' + 'containing the use.\n' + '\n' + 'A *block* is a piece of Python program text that is executed as ' + 'a\n' + 'unit. The following are blocks: a module, a function body, and ' + 'a class\n' + 'definition. Each command typed interactively is a block. A ' + 'script\n' + 'file (a file given as standard input to the interpreter or ' + 'specified\n' + 'on the interpreter command line the first argument) is a code ' + 'block.\n' + 'A script command (a command specified on the interpreter ' + 'command line\n' + "with the '**-c**' option) is a code block. The file read by " + 'the\n' + 'built-in function "execfile()" is a code block. The string ' + 'argument\n' + 'passed to the built-in function "eval()" and to the "exec" ' + 'statement\n' + 'is a code block. The expression read and evaluated by the ' + 'built-in\n' + 'function "input()" is a code block.\n' '\n' 'A code block is executed in an *execution frame*. A frame ' 'contains\n' 'some administrative information (used for debugging) and ' 'determines\n' - 'where and how execution continues after the code block’s ' + "where and how execution continues after the code block's " 'execution has\n' 'completed.\n' '\n' + 'A *scope* defines the visibility of a name within a block. If ' + 'a local\n' + 'variable is defined in a block, its scope includes that block. ' + 'If the\n' + 'definition occurs in a function block, the scope extends to any ' + 'blocks\n' + 'contained within the defining one, unless a contained block ' + 'introduces\n' + 'a different binding for the name. The scope of names defined ' + 'in a\n' + 'class block is limited to the class block; it does not extend ' + 'to the\n' + 'code blocks of methods -- this includes generator expressions ' + 'since\n' + 'they are implemented using a function scope. This means that ' + 'the\n' + 'following will fail:\n' '\n' - 'Naming and binding\n' - '==================\n' + ' class A:\n' + ' a = 42\n' + ' b = list(a + i for i in range(10))\n' '\n' + 'When a name is used in a code block, it is resolved using the ' + 'nearest\n' + 'enclosing scope. The set of all such scopes visible to a code ' + 'block\n' + "is called the block's *environment*.\n" '\n' - 'Binding of names\n' - '----------------\n' + 'If a name is bound in a block, it is a local variable of that ' + 'block.\n' + 'If a name is bound at the module level, it is a global ' + 'variable. (The\n' + 'variables of the module code block are local and global.) If ' + 'a\n' + 'variable is used in a code block but not defined there, it is a ' + '*free\n' + 'variable*.\n' '\n' - '*Names* refer to objects. Names are introduced by name ' - 'binding\n' - 'operations.\n' + 'When a name is not found at all, a "NameError" exception is ' + 'raised.\n' + 'If the name refers to a local variable that has not been bound, ' + 'a\n' + '"UnboundLocalError" exception is raised. "UnboundLocalError" ' + 'is a\n' + 'subclass of "NameError".\n' '\n' 'The following constructs bind names: formal parameters to ' 'functions,\n' @@ -4484,18 +3893,23 @@ topics = {'assert': 'The "assert" statement\n' 'class or function name in the defining block), and targets that ' 'are\n' 'identifiers if occurring in an assignment, "for" loop header, ' - 'or after\n' - '"as" in a "with" statement or "except" clause. The "import" ' - 'statement\n' - 'of the form "from ... import *" binds all names defined in the\n' - 'imported module, except those beginning with an underscore. ' - 'This form\n' - 'may only be used at the module level.\n' + 'in the\n' + 'second position of an "except" clause header or after "as" in a ' + '"with"\n' + 'statement. The "import" statement of the form "from ... import ' + '*"\n' + 'binds all names defined in the imported module, except those ' + 'beginning\n' + 'with an underscore. This form may only be used at the module ' + 'level.\n' '\n' 'A target occurring in a "del" statement is also considered ' 'bound for\n' 'this purpose (though the actual semantics are to unbind the ' - 'name).\n' + 'name). It\n' + 'is illegal to unbind a name that is referenced by an enclosing ' + 'scope;\n' + 'the compiler will report a "SyntaxError".\n' '\n' 'Each assignment or import statement occurs within a block ' 'defined by a\n' @@ -4503,57 +3917,13 @@ topics = {'assert': 'The "assert" statement\n' 'top-level\n' 'code block).\n' '\n' - 'If a name is bound in a block, it is a local variable of that ' - 'block,\n' - 'unless declared as "nonlocal" or "global". If a name is bound ' - 'at the\n' - 'module level, it is a global variable. (The variables of the ' - 'module\n' - 'code block are local and global.) If a variable is used in a ' - 'code\n' - 'block but not defined there, it is a *free variable*.\n' - '\n' - 'Each occurrence of a name in the program text refers to the ' - '*binding*\n' - 'of that name established by the following name resolution ' - 'rules.\n' - '\n' - '\n' - 'Resolution of names\n' - '-------------------\n' - '\n' - 'A *scope* defines the visibility of a name within a block. If ' - 'a local\n' - 'variable is defined in a block, its scope includes that block. ' - 'If the\n' - 'definition occurs in a function block, the scope extends to any ' - 'blocks\n' - 'contained within the defining one, unless a contained block ' - 'introduces\n' - 'a different binding for the name.\n' - '\n' - 'When a name is used in a code block, it is resolved using the ' - 'nearest\n' - 'enclosing scope. The set of all such scopes visible to a code ' - 'block\n' - 'is called the block’s *environment*.\n' - '\n' - 'When a name is not found at all, a "NameError" exception is ' - 'raised. If\n' - 'the current scope is a function scope, and the name refers to a ' - 'local\n' - 'variable that has not yet been bound to a value at the point ' - 'where the\n' - 'name is used, an "UnboundLocalError" exception is raised.\n' - '"UnboundLocalError" is a subclass of "NameError".\n' - '\n' 'If a name binding operation occurs anywhere within a code ' 'block, all\n' 'uses of the name within the block are treated as references to ' 'the\n' 'current block. This can lead to errors when a name is used ' 'within a\n' - 'block before it is bound. This rule is subtle. Python lacks\n' + 'block before it is bound. This rule is subtle. Python lacks\n' 'declarations and allows name binding operations to occur ' 'anywhere\n' 'within a code block. The local variables of a code block can ' @@ -4562,36 +3932,47 @@ topics = {'assert': 'The "assert" statement\n' 'binding\n' 'operations.\n' '\n' - 'If the "global" statement occurs within a block, all uses of ' - 'the name\n' + 'If the global statement occurs within a block, all uses of the ' + 'name\n' 'specified in the statement refer to the binding of that name in ' 'the\n' - 'top-level namespace. Names are resolved in the top-level ' + 'top-level namespace. Names are resolved in the top-level ' 'namespace by\n' 'searching the global namespace, i.e. the namespace of the ' 'module\n' 'containing the code block, and the builtins namespace, the ' 'namespace\n' - 'of the module "builtins". The global namespace is searched ' - 'first. If\n' - 'the name is not found there, the builtins namespace is ' - 'searched. The\n' - '"global" statement must precede all uses of the name.\n' + 'of the module "__builtin__". The global namespace is searched ' + 'first.\n' + 'If the name is not found there, the builtins namespace is ' + 'searched.\n' + 'The global statement must precede all uses of the name.\n' '\n' - 'The "global" statement has the same scope as a name binding ' - 'operation\n' - 'in the same block. If the nearest enclosing scope for a free ' - 'variable\n' - 'contains a global statement, the free variable is treated as a ' - 'global.\n' + 'The builtins namespace associated with the execution of a code ' + 'block\n' + 'is actually found by looking up the name "__builtins__" in its ' + 'global\n' + 'namespace; this should be a dictionary or a module (in the ' + 'latter case\n' + "the module's dictionary is used). By default, when in the " + '"__main__"\n' + 'module, "__builtins__" is the built-in module "__builtin__" ' + '(note: no\n' + '\'s\'); when in any other module, "__builtins__" is an alias ' + 'for the\n' + 'dictionary of the "__builtin__" module itself. "__builtins__" ' + 'can be\n' + 'set to a user-created dictionary to create a weak form of ' + 'restricted\n' + 'execution.\n' '\n' - 'The "nonlocal" statement causes corresponding names to refer ' - 'to\n' - 'previously bound variables in the nearest enclosing function ' - 'scope.\n' - '"SyntaxError" is raised at compile time if the given name does ' - 'not\n' - 'exist in any enclosing function scope.\n' + '**CPython implementation detail:** Users should not touch\n' + '"__builtins__"; it is strictly an implementation detail. ' + 'Users\n' + 'wanting to override values in the builtins namespace should ' + '"import"\n' + 'the "__builtin__" (no \'s\') module and modify its attributes\n' + 'appropriately.\n' '\n' 'The namespace for a module is automatically created the first ' 'time a\n' @@ -4599,80 +3980,62 @@ topics = {'assert': 'The "assert" statement\n' 'called\n' '"__main__".\n' '\n' - 'Class definition blocks and arguments to "exec()" and "eval()" ' - 'are\n' - 'special in the context of name resolution. A class definition ' - 'is an\n' - 'executable statement that may use and define names. These ' - 'references\n' - 'follow the normal rules for name resolution with an exception ' - 'that\n' - 'unbound local variables are looked up in the global namespace. ' - 'The\n' - 'namespace of the class definition becomes the attribute ' - 'dictionary of\n' - 'the class. The scope of names defined in a class block is ' - 'limited to\n' - 'the class block; it does not extend to the code blocks of ' - 'methods –\n' - 'this includes comprehensions and generator expressions since ' - 'they are\n' - 'implemented using a function scope. This means that the ' - 'following\n' - 'will fail:\n' + 'The "global" statement has the same scope as a name binding ' + 'operation\n' + 'in the same block. If the nearest enclosing scope for a free ' + 'variable\n' + 'contains a global statement, the free variable is treated as a ' + 'global.\n' '\n' - ' class A:\n' - ' a = 42\n' - ' b = list(a + i for i in range(10))\n' + 'A class definition is an executable statement that may use and ' + 'define\n' + 'names. These references follow the normal rules for name ' + 'resolution.\n' + 'The namespace of the class definition becomes the attribute ' + 'dictionary\n' + 'of the class. Names defined at the class scope are not visible ' + 'in\n' + 'methods.\n' '\n' '\n' - 'Builtins and restricted execution\n' + 'Interaction with dynamic features\n' '---------------------------------\n' '\n' - '**CPython implementation detail:** Users should not touch\n' - '"__builtins__"; it is strictly an implementation detail. ' - 'Users\n' - 'wanting to override values in the builtins namespace should ' - '"import"\n' - 'the "builtins" module and modify its attributes appropriately.\n' - '\n' - 'The builtins namespace associated with the execution of a code ' - 'block\n' - 'is actually found by looking up the name "__builtins__" in its ' - 'global\n' - 'namespace; this should be a dictionary or a module (in the ' - 'latter case\n' - 'the module’s dictionary is used). By default, when in the ' - '"__main__"\n' - 'module, "__builtins__" is the built-in module "builtins"; when ' - 'in any\n' - 'other module, "__builtins__" is an alias for the dictionary of ' - 'the\n' - '"builtins" module itself.\n' - '\n' + 'There are several cases where Python statements are illegal ' + 'when used\n' + 'in conjunction with nested scopes that contain free variables.\n' '\n' - 'Interaction with dynamic features\n' - '---------------------------------\n' + 'If a variable is referenced in an enclosing scope, it is ' + 'illegal to\n' + 'delete the name. An error will be reported at compile time.\n' '\n' - 'Name resolution of free variables occurs at runtime, not at ' - 'compile\n' - 'time. This means that the following code will print 42:\n' + 'If the wild card form of import --- "import *" --- is used in ' + 'a\n' + 'function and the function contains or is a nested block with ' + 'free\n' + 'variables, the compiler will raise a "SyntaxError".\n' '\n' - ' i = 10\n' - ' def f():\n' - ' print(i)\n' - ' i = 42\n' - ' f()\n' + 'If "exec" is used in a function and the function contains or is ' + 'a\n' + 'nested block with free variables, the compiler will raise a\n' + '"SyntaxError" unless the exec explicitly specifies the local ' + 'namespace\n' + 'for the "exec". (In other words, "exec obj" would be illegal, ' + 'but\n' + '"exec obj in ns" would be legal.)\n' '\n' - 'The "eval()" and "exec()" functions do not have access to the ' - 'full\n' - 'environment for resolving names. Names may be resolved in the ' - 'local\n' - 'and global namespaces of the caller. Free variables are not ' - 'resolved\n' - 'in the nearest enclosing namespace, but in the global ' - 'namespace. [1]\n' - 'The "exec()" and "eval()" functions have optional arguments to\n' + 'The "eval()", "execfile()", and "input()" functions and the ' + '"exec"\n' + 'statement do not have access to the full environment for ' + 'resolving\n' + 'names. Names may be resolved in the local and global ' + 'namespaces of\n' + 'the caller. Free variables are not resolved in the nearest ' + 'enclosing\n' + 'namespace, but in the global namespace. [1] The "exec" ' + 'statement and\n' + 'the "eval()" and "execfile()" functions have optional arguments ' + 'to\n' 'override the global and local namespace. If only one namespace ' 'is\n' 'specified, it is used for both.\n' @@ -4697,7 +4060,7 @@ topics = {'assert': 'The "assert" statement\n' 'error (such as division by zero). A Python program can also\n' 'explicitly raise an exception with the "raise" statement. ' 'Exception\n' - 'handlers are specified with the "try" … "except" statement. ' + 'handlers are specified with the "try" ... "except" statement. ' 'The\n' '"finally" clause of such a statement can be used to specify ' 'cleanup\n' @@ -4705,7 +4068,7 @@ topics = {'assert': 'The "assert" statement\n' 'whether an\n' 'exception occurred or not in the preceding code.\n' '\n' - 'Python uses the “termination” model of error handling: an ' + 'Python uses the "termination" model of error handling: an ' 'exception\n' 'handler can find out what happened and continue execution at an ' 'outer\n' @@ -4719,7 +4082,7 @@ topics = {'assert': 'The "assert" statement\n' 'terminates\n' 'execution of the program, or returns to its interactive main ' 'loop. In\n' - 'either case, it prints a stack traceback, except when the ' + 'either case, it prints a stack backtrace, except when the ' 'exception is\n' '"SystemExit".\n' '\n' @@ -4733,7 +4096,15 @@ topics = {'assert': 'The "assert" statement\n' 'about the\n' 'exceptional condition.\n' '\n' - 'Note: Exception messages are not part of the Python API. ' + 'Exceptions can also be identified by strings, in which case ' + 'the\n' + '"except" clause is selected by object identity. An arbitrary ' + 'value\n' + 'can be raised along with the identifying string which can be ' + 'passed to\n' + 'the handler.\n' + '\n' + 'Note: Messages to exceptions are not part of the Python API. ' 'Their\n' ' contents may change from one version of Python to the next ' 'without\n' @@ -4753,74 +4124,59 @@ topics = {'assert': 'The "assert" statement\n' ' these operations is not available at the time the module ' 'is\n' ' compiled.\n', - 'exprlists': 'Expression lists\n' + 'exprlists': '\n' + 'Expression lists\n' '****************\n' '\n' - ' expression_list ::= expression ("," expression)* [","]\n' - ' starred_list ::= starred_item ("," starred_item)* ' - '[","]\n' - ' starred_expression ::= expression | (starred_item ",")* ' - '[starred_item]\n' - ' starred_item ::= expression | "*" or_expr\n' - '\n' - 'Except when part of a list or set display, an expression list\n' - 'containing at least one comma yields a tuple. The length of ' - 'the tuple\n' - 'is the number of expressions in the list. The expressions are\n' - 'evaluated from left to right.\n' + ' expression_list ::= expression ( "," expression )* [","]\n' '\n' - 'An asterisk "*" denotes *iterable unpacking*. Its operand must ' - 'be an\n' - '*iterable*. The iterable is expanded into a sequence of items, ' - 'which\n' - 'are included in the new tuple, list, or set, at the site of ' - 'the\n' - 'unpacking.\n' - '\n' - 'New in version 3.5: Iterable unpacking in expression lists, ' - 'originally\n' - 'proposed by **PEP 448**.\n' + 'An expression list containing at least one comma yields a ' + 'tuple. The\n' + 'length of the tuple is the number of expressions in the list. ' + 'The\n' + 'expressions are evaluated from left to right.\n' '\n' 'The trailing comma is required only to create a single tuple ' '(a.k.a. a\n' '*singleton*); it is optional in all other cases. A single ' 'expression\n' - 'without a trailing comma doesn’t create a tuple, but rather ' + "without a trailing comma doesn't create a tuple, but rather " 'yields the\n' 'value of that expression. (To create an empty tuple, use an ' 'empty pair\n' 'of parentheses: "()".)\n', - 'floating': 'Floating point literals\n' + 'floating': '\n' + 'Floating point literals\n' '***********************\n' '\n' 'Floating point literals are described by the following lexical\n' 'definitions:\n' '\n' ' floatnumber ::= pointfloat | exponentfloat\n' - ' pointfloat ::= [digitpart] fraction | digitpart "."\n' - ' exponentfloat ::= (digitpart | pointfloat) exponent\n' - ' digitpart ::= digit (["_"] digit)*\n' - ' fraction ::= "." digitpart\n' - ' exponent ::= ("e" | "E") ["+" | "-"] digitpart\n' - '\n' - 'Note that the integer and exponent parts are always interpreted ' - 'using\n' - 'radix 10. For example, "077e010" is legal, and denotes the same ' - 'number\n' - 'as "77e10". The allowed range of floating point literals is\n' - 'implementation-dependent. As in integer literals, underscores ' - 'are\n' - 'supported for digit grouping.\n' - '\n' - 'Some examples of floating point literals:\n' - '\n' - ' 3.14 10. .001 1e100 3.14e-10 0e0 ' - '3.14_15_93\n' - '\n' - 'Changed in version 3.6: Underscores are now allowed for ' - 'grouping\n' - 'purposes in literals.\n', - 'for': 'The "for" statement\n' + ' pointfloat ::= [intpart] fraction | intpart "."\n' + ' exponentfloat ::= (intpart | pointfloat) exponent\n' + ' intpart ::= digit+\n' + ' fraction ::= "." digit+\n' + ' exponent ::= ("e" | "E") ["+" | "-"] digit+\n' + '\n' + 'Note that the integer and exponent parts of floating point ' + 'numbers can\n' + 'look like octal integers, but are interpreted using radix 10. ' + 'For\n' + 'example, "077e010" is legal, and denotes the same number as ' + '"77e10".\n' + 'The allowed range of floating point literals is implementation-\n' + 'dependent. Some examples of floating point literals:\n' + '\n' + ' 3.14 10. .001 1e100 3.14e-10 0e0\n' + '\n' + 'Note that numeric literals do not include a sign; a phrase like ' + '"-1"\n' + 'is actually an expression composed of the unary operator "-" and ' + 'the\n' + 'literal "1".\n', + 'for': '\n' + 'The "for" statement\n' '*******************\n' '\n' 'The "for" statement is used to iterate over the elements of a ' @@ -4833,46 +4189,35 @@ topics = {'assert': 'The "assert" statement\n' 'The expression list is evaluated once; it should yield an iterable\n' 'object. An iterator is created for the result of the\n' '"expression_list". The suite is then executed once for each item\n' - 'provided by the iterator, in the order returned by the iterator. ' - 'Each\n' + 'provided by the iterator, in the order of ascending indices. Each\n' 'item in turn is assigned to the target list using the standard rules\n' - 'for assignments (see Assignment statements), and then the suite is\n' - 'executed. When the items are exhausted (which is immediately when ' - 'the\n' - 'sequence is empty or an iterator raises a "StopIteration" ' - 'exception),\n' - 'the suite in the "else" clause, if present, is executed, and the ' - 'loop\n' + 'for assignments, and then the suite is executed. When the items are\n' + 'exhausted (which is immediately when the sequence is empty), the ' + 'suite\n' + 'in the "else" clause, if present, is executed, and the loop\n' 'terminates.\n' '\n' 'A "break" statement executed in the first suite terminates the loop\n' - 'without executing the "else" clause’s suite. A "continue" statement\n' + 'without executing the "else" clause\'s suite. A "continue" ' + 'statement\n' 'executed in the first suite skips the rest of the suite and ' 'continues\n' - 'with the next item, or with the "else" clause if there is no next\n' + 'with the next item, or with the "else" clause if there was no next\n' 'item.\n' '\n' - 'The for-loop makes assignments to the variables in the target list.\n' - 'This overwrites all previous assignments to those variables ' - 'including\n' - 'those made in the suite of the for-loop:\n' - '\n' - ' for i in range(10):\n' - ' print(i)\n' - ' i = 5 # this will not affect the for-loop\n' - ' # because i will be overwritten with the ' - 'next\n' - ' # index in the range\n' + 'The suite may assign to the variable(s) in the target list; this ' + 'does\n' + 'not affect the next item assigned to it.\n' '\n' - 'Names in the target list are not deleted when the loop is finished,\n' - 'but if the sequence is empty, they will not have been assigned to at\n' - 'all by the loop. Hint: the built-in function "range()" returns an\n' - 'iterator of integers suitable to emulate the effect of Pascal’s "for ' - 'i\n' - ':= a to b do"; e.g., "list(range(3))" returns the list "[0, 1, 2]".\n' + 'The target list is not deleted when the loop is finished, but if the\n' + 'sequence is empty, it will not have been assigned to at all by the\n' + 'loop. Hint: the built-in function "range()" returns a sequence of\n' + 'integers suitable to emulate the effect of Pascal\'s "for i := a to ' + 'b\n' + 'do"; e.g., "range(3)" returns the list "[0, 1, 2]".\n' '\n' 'Note: There is a subtlety when the sequence is being modified by the\n' - ' loop (this can only occur for mutable sequences, e.g. lists). An\n' + ' loop (this can only occur for mutable sequences, i.e. lists). An\n' ' internal counter is used to keep track of which item is used next,\n' ' and this is incremented on each iteration. When this counter has\n' ' reached the length of the sequence the loop terminates. This ' @@ -4890,20 +4235,17 @@ topics = {'assert': 'The "assert" statement\n' '\n' ' for x in a[:]:\n' ' if x < 0: a.remove(x)\n', - 'formatstrings': 'Format String Syntax\n' + 'formatstrings': '\n' + 'Format String Syntax\n' '********************\n' '\n' 'The "str.format()" method and the "Formatter" class share ' 'the same\n' 'syntax for format strings (although in the case of ' '"Formatter",\n' - 'subclasses can define their own format string syntax). The ' - 'syntax is\n' - 'related to that of formatted string literals, but there ' - 'are\n' - 'differences.\n' + 'subclasses can define their own format string syntax).\n' '\n' - 'Format strings contain “replacement fields” surrounded by ' + 'Format strings contain "replacement fields" surrounded by ' 'curly braces\n' '"{}". Anything that is not contained in braces is ' 'considered literal\n' @@ -4919,12 +4261,12 @@ topics = {'assert': 'The "assert" statement\n' 'conversion] [":" format_spec] "}"\n' ' field_name ::= arg_name ("." attribute_name | ' '"[" element_index "]")*\n' - ' arg_name ::= [identifier | digit+]\n' + ' arg_name ::= [identifier | integer]\n' ' attribute_name ::= identifier\n' - ' element_index ::= digit+ | index_string\n' + ' element_index ::= integer | index_string\n' ' index_string ::= <any source character except ' '"]"> +\n' - ' conversion ::= "r" | "s" | "a"\n' + ' conversion ::= "r" | "s"\n' ' format_spec ::= <described in the next ' 'section>\n' '\n' @@ -4946,37 +4288,33 @@ topics = {'assert': 'The "assert" statement\n' '\n' 'The *field_name* itself begins with an *arg_name* that is ' 'either a\n' - 'number or a keyword. If it’s a number, it refers to a ' + "number or a keyword. If it's a number, it refers to a " 'positional\n' - 'argument, and if it’s a keyword, it refers to a named ' + "argument, and if it's a keyword, it refers to a named " 'keyword\n' 'argument. If the numerical arg_names in a format string ' 'are 0, 1, 2,\n' - '… in sequence, they can all be omitted (not just some) and ' - 'the numbers\n' - '0, 1, 2, … will be automatically inserted in that order. ' - 'Because\n' - '*arg_name* is not quote-delimited, it is not possible to ' - 'specify\n' - 'arbitrary dictionary keys (e.g., the strings "\'10\'" or ' - '"\':-]\'") within\n' - 'a format string. The *arg_name* can be followed by any ' - 'number of index\n' - 'or attribute expressions. An expression of the form ' - '"\'.name\'" selects\n' - 'the named attribute using "getattr()", while an expression ' - 'of the form\n' - '"\'[index]\'" does an index lookup using "__getitem__()".\n' - '\n' - 'Changed in version 3.1: The positional argument specifiers ' - 'can be\n' - 'omitted for "str.format()", so "\'{} {}\'.format(a, b)" is ' - 'equivalent to\n' - '"\'{0} {1}\'.format(a, b)".\n' + '... in sequence, they can all be omitted (not just some) ' + 'and the\n' + 'numbers 0, 1, 2, ... will be automatically inserted in that ' + 'order.\n' + 'Because *arg_name* is not quote-delimited, it is not ' + 'possible to\n' + 'specify arbitrary dictionary keys (e.g., the strings ' + '"\'10\'" or\n' + '"\':-]\'") within a format string. The *arg_name* can be ' + 'followed by any\n' + 'number of index or attribute expressions. An expression of ' + 'the form\n' + '"\'.name\'" selects the named attribute using "getattr()", ' + 'while an\n' + 'expression of the form "\'[index]\'" does an index lookup ' + 'using\n' + '"__getitem__()".\n' '\n' - 'Changed in version 3.4: The positional argument specifiers ' + 'Changed in version 2.7: The positional argument specifiers ' 'can be\n' - 'omitted for "Formatter".\n' + 'omitted, so "\'{} {}\'" is equivalent to "\'{0} {1}\'".\n' '\n' 'Some simple format string examples:\n' '\n' @@ -5006,11 +4344,9 @@ topics = {'assert': 'The "assert" statement\n' 'calling "__format__()", the normal formatting logic is ' 'bypassed.\n' '\n' - 'Three conversion flags are currently supported: "\'!s\'" ' + 'Two conversion flags are currently supported: "\'!s\'" ' 'which calls\n' - '"str()" on the value, "\'!r\'" which calls "repr()" and ' - '"\'!a\'" which\n' - 'calls "ascii()".\n' + '"str()" on the value, and "\'!r\'" which calls "repr()".\n' '\n' 'Some examples:\n' '\n' @@ -5018,8 +4354,6 @@ topics = {'assert': 'The "assert" statement\n' 'argument first\n' ' "Bring out the holy {name!r}" # Calls repr() on the ' 'argument first\n' - ' "More {!a}" # Calls ascii() on the ' - 'argument first\n' '\n' 'The *format_spec* field contains a specification of how the ' 'value\n' @@ -5027,7 +4361,7 @@ topics = {'assert': 'The "assert" statement\n' 'alignment,\n' 'padding, decimal precision and so on. Each value type can ' 'define its\n' - 'own “formatting mini-language” or interpretation of the ' + 'own "formatting mini-language" or interpretation of the ' '*format_spec*.\n' '\n' 'Most built-in types support a common formatting ' @@ -5053,17 +4387,15 @@ topics = {'assert': 'The "assert" statement\n' 'Format Specification Mini-Language\n' '==================================\n' '\n' - '“Format specifications” are used within replacement fields ' + '"Format specifications" are used within replacement fields ' 'contained\n' 'within a format string to define how individual values are ' 'presented\n' - '(see Format String Syntax and Formatted string literals). ' - 'They can\n' - 'also be passed directly to the built-in "format()" ' - 'function. Each\n' - 'formattable type may define how the format specification is ' - 'to be\n' - 'interpreted.\n' + '(see Format String Syntax). They can also be passed ' + 'directly to the\n' + 'built-in "format()" function. Each formattable type may ' + 'define how\n' + 'the format specification is to be interpreted.\n' '\n' 'Most built-in types implement the following options for ' 'format\n' @@ -5079,30 +4411,29 @@ topics = {'assert': 'The "assert" statement\n' '\n' 'The general form of a *standard format specifier* is:\n' '\n' - ' format_spec ::= ' - '[[fill]align][sign][#][0][width][grouping_option][.precision][type]\n' - ' fill ::= <any character>\n' - ' align ::= "<" | ">" | "=" | "^"\n' - ' sign ::= "+" | "-" | " "\n' - ' width ::= digit+\n' - ' grouping_option ::= "_" | ","\n' - ' precision ::= digit+\n' - ' type ::= "b" | "c" | "d" | "e" | "E" | "f" | ' - '"F" | "g" | "G" | "n" | "o" | "s" | "x" | "X" | "%"\n' + ' format_spec ::= ' + '[[fill]align][sign][#][0][width][,][.precision][type]\n' + ' fill ::= <any character>\n' + ' align ::= "<" | ">" | "=" | "^"\n' + ' sign ::= "+" | "-" | " "\n' + ' width ::= integer\n' + ' precision ::= integer\n' + ' type ::= "b" | "c" | "d" | "e" | "E" | "f" | "F" ' + '| "g" | "G" | "n" | "o" | "s" | "x" | "X" | "%"\n' '\n' 'If a valid *align* value is specified, it can be preceded ' 'by a *fill*\n' 'character that can be any character and defaults to a space ' 'if\n' 'omitted. It is not possible to use a literal curly brace ' - '(“"{"” or\n' - '“"}"”) as the *fill* character in a formatted string ' - 'literal or when\n' - 'using the "str.format()" method. However, it is possible ' - 'to insert a\n' - 'curly brace with a nested replacement field. This ' - 'limitation doesn’t\n' - 'affect the "format()" function.\n' + '(""{"" or\n' + '""}"") as the *fill* character when using the ' + '"str.format()" method.\n' + 'However, it is possible to insert a curly brace with a ' + 'nested\n' + "replacement field. This limitation doesn't affect the " + '"format()"\n' + 'function.\n' '\n' 'The meaning of the various alignment options is as ' 'follows:\n' @@ -5113,7 +4444,7 @@ topics = {'assert': 'The "assert" statement\n' 'Meaning ' '|\n' ' ' - '|===========|============================================================|\n' + '+===========+============================================================+\n' ' | "\'<\'" | Forces the field to be left-aligned ' 'within the available |\n' ' | | space (this is the default for most ' @@ -5130,10 +4461,10 @@ topics = {'assert': 'The "assert" statement\n' 'the sign (if any) |\n' ' | | but before the digits. This is used for ' 'printing fields |\n' - ' | | in the form ‘+000000120’. This alignment ' + " | | in the form '+000000120'. This alignment " 'option is only |\n' ' | | valid for numeric types. It becomes the ' - 'default when ‘0’ |\n' + "default when '0' |\n" ' | | immediately precedes the field ' 'width. |\n' ' ' @@ -5162,7 +4493,7 @@ topics = {'assert': 'The "assert" statement\n' 'Meaning ' '|\n' ' ' - '|===========|============================================================|\n' + '+===========+============================================================+\n' ' | "\'+\'" | indicates that a sign should be used for ' 'both positive as |\n' ' | | well as negative ' @@ -5182,28 +4513,12 @@ topics = {'assert': 'The "assert" statement\n' ' ' '+-----------+------------------------------------------------------------+\n' '\n' - 'The "\'#\'" option causes the “alternate form” to be used ' - 'for the\n' - 'conversion. The alternate form is defined differently for ' - 'different\n' - 'types. This option is only valid for integer, float, ' - 'complex and\n' - 'Decimal types. For integers, when binary, octal, or ' - 'hexadecimal output\n' - 'is used, this option adds the prefix respective "\'0b\'", ' - '"\'0o\'", or\n' - '"\'0x\'" to the output value. For floats, complex and ' - 'Decimal the\n' - 'alternate form causes the result of the conversion to ' - 'always contain a\n' - 'decimal-point character, even if no digits follow it. ' - 'Normally, a\n' - 'decimal-point character appears in the result of these ' - 'conversions\n' - 'only if a digit follows it. In addition, for "\'g\'" and ' - '"\'G\'"\n' - 'conversions, trailing zeros are not removed from the ' - 'result.\n' + 'The "\'#\'" option is only valid for integers, and only for ' + 'binary,\n' + 'octal, or hexadecimal output. If present, it specifies ' + 'that the\n' + 'output will be prefixed by "\'0b\'", "\'0o\'", or "\'0x\'", ' + 'respectively.\n' '\n' 'The "\',\'" option signals the use of a comma for a ' 'thousands separator.\n' @@ -5211,23 +4526,9 @@ topics = {'assert': 'The "assert" statement\n' 'presentation type\n' 'instead.\n' '\n' - 'Changed in version 3.1: Added the "\',\'" option (see also ' + 'Changed in version 2.7: Added the "\',\'" option (see also ' '**PEP 378**).\n' '\n' - 'The "\'_\'" option signals the use of an underscore for a ' - 'thousands\n' - 'separator for floating point presentation types and for ' - 'integer\n' - 'presentation type "\'d\'". For integer presentation types ' - '"\'b\'", "\'o\'",\n' - '"\'x\'", and "\'X\'", underscores will be inserted every 4 ' - 'digits. For\n' - 'other presentation types, specifying this option is an ' - 'error.\n' - '\n' - 'Changed in version 3.6: Added the "\'_\'" option (see also ' - '**PEP 515**).\n' - '\n' '*width* is a decimal integer defining the minimum field ' 'width. If not\n' 'specified, then the field width will be determined by the ' @@ -5266,7 +4567,7 @@ topics = {'assert': 'The "assert" statement\n' 'Meaning ' '|\n' ' ' - '|===========|============================================================|\n' + '+===========+============================================================+\n' ' | "\'s\'" | String format. This is the default type ' 'for strings and |\n' ' | | may be ' @@ -5286,7 +4587,7 @@ topics = {'assert': 'The "assert" statement\n' 'Meaning ' '|\n' ' ' - '|===========|============================================================|\n' + '+===========+============================================================+\n' ' | "\'b\'" | Binary format. Outputs the number in ' 'base 2. |\n' ' ' @@ -5348,10 +4649,10 @@ topics = {'assert': 'The "assert" statement\n' 'Meaning ' '|\n' ' ' - '|===========|============================================================|\n' + '+===========+============================================================+\n' ' | "\'e\'" | Exponent notation. Prints the number in ' 'scientific |\n' - ' | | notation using the letter ‘e’ to indicate ' + " | | notation using the letter 'e' to indicate " 'the exponent. |\n' ' | | The default precision is ' '"6". |\n' @@ -5359,20 +4660,18 @@ topics = {'assert': 'The "assert" statement\n' '+-----------+------------------------------------------------------------+\n' ' | "\'E\'" | Exponent notation. Same as "\'e\'" ' 'except it uses an upper |\n' - ' | | case ‘E’ as the separator ' + " | | case 'E' as the separator " 'character. |\n' ' ' '+-----------+------------------------------------------------------------+\n' - ' | "\'f\'" | Fixed-point notation. Displays the ' - 'number as a fixed-point |\n' - ' | | number. The default precision is ' - '"6". |\n' + ' | "\'f\'" | Fixed point. Displays the number as a ' + 'fixed-point number. |\n' + ' | | The default precision is ' + '"6". |\n' ' ' '+-----------+------------------------------------------------------------+\n' - ' | "\'F\'" | Fixed-point notation. Same as "\'f\'", ' - 'but converts "nan" to |\n' - ' | | "NAN" and "inf" to ' - '"INF". |\n' + ' | "\'F\'" | Fixed point. Same as ' + '"\'f\'". |\n' ' ' '+-----------+------------------------------------------------------------+\n' ' | "\'g\'" | General format. For a given precision ' @@ -5387,34 +4686,30 @@ topics = {'assert': 'The "assert" statement\n' 'the result |\n' ' | | formatted with presentation type "\'e\'" ' 'and precision "p-1" |\n' - ' | | would have exponent "exp". Then, if "m <= ' - 'exp < p", where |\n' - ' | | "m" is -4 for floats and -6 for ' - '"Decimals", the number is |\n' - ' | | formatted with presentation type "\'f\'" ' - 'and precision |\n' - ' | | "p-1-exp". Otherwise, the number is ' - 'formatted with |\n' - ' | | presentation type "\'e\'" and precision ' - '"p-1". In both cases |\n' - ' | | insignificant trailing zeros are removed ' - 'from the |\n' + ' | | would have exponent "exp". Then if "-4 <= ' + 'exp < p", the |\n' + ' | | number is formatted with presentation type ' + '"\'f\'" and |\n' + ' | | precision "p-1-exp". Otherwise, the ' + 'number is formatted |\n' + ' | | with presentation type "\'e\'" and ' + 'precision "p-1". In both |\n' + ' | | cases insignificant trailing zeros are ' + 'removed from the |\n' ' | | significand, and the decimal point is also ' 'removed if |\n' ' | | there are no remaining digits following ' - 'it, unless the |\n' - ' | | "\'#\'" option is used. Positive and ' - 'negative infinity, |\n' - ' | | positive and negative zero, and nans, are ' - 'formatted as |\n' - ' | | "inf", "-inf", "0", "-0" and "nan" ' - 'respectively, |\n' - ' | | regardless of the precision. A precision ' - 'of "0" is |\n' - ' | | treated as equivalent to a precision of ' - '"1". The default |\n' - ' | | precision is ' - '"6". |\n' + 'it. Positive and |\n' + ' | | negative infinity, positive and negative ' + 'zero, and nans, |\n' + ' | | are formatted as "inf", "-inf", "0", "-0" ' + 'and "nan" |\n' + ' | | respectively, regardless of the ' + 'precision. A precision of |\n' + ' | | "0" is treated as equivalent to a ' + 'precision of "1". The |\n' + ' | | default precision is ' + '"6". |\n' ' ' '+-----------+------------------------------------------------------------+\n' ' | "\'G\'" | General format. Same as "\'g\'" except ' @@ -5439,19 +4734,8 @@ topics = {'assert': 'The "assert" statement\n' 'percent sign. |\n' ' ' '+-----------+------------------------------------------------------------+\n' - ' | None | Similar to "\'g\'", except that ' - 'fixed-point notation, when |\n' - ' | | used, has at least one digit past the ' - 'decimal point. The |\n' - ' | | default precision is as high as needed to ' - 'represent the |\n' - ' | | particular value. The overall effect is to ' - 'match the |\n' - ' | | output of "str()" as altered by the other ' - 'format |\n' - ' | | ' - 'modifiers. ' - '|\n' + ' | None | The same as ' + '"\'g\'". |\n' ' ' '+-----------+------------------------------------------------------------+\n' '\n' @@ -5471,13 +4755,13 @@ topics = {'assert': 'The "assert" statement\n' '\n' 'The new format syntax also supports new and different ' 'options, shown\n' - 'in the following examples.\n' + 'in the follow examples.\n' '\n' 'Accessing arguments by position:\n' '\n' " >>> '{0}, {1}, {2}'.format('a', 'b', 'c')\n" " 'a, b, c'\n" - " >>> '{}, {}, {}'.format('a', 'b', 'c') # 3.1+ only\n" + " >>> '{}, {}, {}'.format('a', 'b', 'c') # 2.7+ only\n" " 'a, b, c'\n" " >>> '{2}, {1}, {0}'.format('a', 'b', 'c')\n" " 'c, b, a'\n" @@ -5500,7 +4784,7 @@ topics = {'assert': 'The "assert" statement\n' "{longitude}'.format(**coord)\n" " 'Coordinates: 37.24N, -115.81W'\n" '\n' - 'Accessing arguments’ attributes:\n' + "Accessing arguments' attributes:\n" '\n' ' >>> c = 3-5j\n' " >>> ('The complex number {0} is formed from the real " @@ -5508,7 +4792,7 @@ topics = {'assert': 'The "assert" statement\n' " ... 'and the imaginary part {0.imag}.').format(c)\n" " 'The complex number (3-5j) is formed from the real part " "3.0 and the imaginary part -5.0.'\n" - ' >>> class Point:\n' + ' >>> class Point(object):\n' ' ... def __init__(self, x, y):\n' ' ... self.x, self.y = x, y\n' ' ... def __str__(self):\n' @@ -5518,7 +4802,7 @@ topics = {'assert': 'The "assert" statement\n' ' >>> str(Point(4, 2))\n' " 'Point(4, 2)'\n" '\n' - 'Accessing arguments’ items:\n' + "Accessing arguments' items:\n" '\n' ' >>> coord = (3, 5)\n' " >>> 'X: {0[0]}; Y: {0[1]}'.format(coord)\n" @@ -5573,10 +4857,10 @@ topics = {'assert': 'The "assert" statement\n' '\n' 'Expressing a percentage:\n' '\n' - ' >>> points = 19\n' + ' >>> points = 19.5\n' ' >>> total = 22\n' " >>> 'Correct answers: {:.2%}'.format(points/total)\n" - " 'Correct answers: 86.36%'\n" + " 'Correct answers: 88.64%'\n" '\n' 'Using type-specific formatting:\n' '\n' @@ -5603,11 +4887,11 @@ topics = {'assert': 'The "assert" statement\n' ' 3232235521\n' ' >>>\n' ' >>> width = 5\n' - ' >>> for num in range(5,12): \n' + ' >>> for num in range(5,12):\n' " ... for base in 'dXob':\n" - " ... print('{0:{width}{base}}'.format(num, " - "base=base, width=width), end=' ')\n" - ' ... print()\n' + " ... print '{0:{width}{base}}'.format(num, " + 'base=base, width=width),\n' + ' ... print\n' ' ...\n' ' 5 5 5 101\n' ' 6 6 6 110\n' @@ -5616,32 +4900,29 @@ topics = {'assert': 'The "assert" statement\n' ' 9 9 11 1001\n' ' 10 A 12 1010\n' ' 11 B 13 1011\n', - 'function': 'Function definitions\n' + 'function': '\n' + 'Function definitions\n' '********************\n' '\n' 'A function definition defines a user-defined function object ' '(see\n' 'section The standard type hierarchy):\n' '\n' - ' funcdef ::= [decorators] "def" funcname "(" ' - '[parameter_list] ")"\n' - ' ["->" expression] ":" suite\n' - ' decorators ::= decorator+\n' - ' decorator ::= "@" dotted_name ["(" ' - '[argument_list [","]] ")"] NEWLINE\n' - ' dotted_name ::= identifier ("." identifier)*\n' - ' parameter_list ::= defparameter ("," ' - 'defparameter)* "," "/" ["," [parameter_list_no_posonly]]\n' - ' | parameter_list_no_posonly\n' - ' parameter_list_no_posonly ::= defparameter ("," ' - 'defparameter)* ["," [parameter_list_starargs]]\n' - ' | parameter_list_starargs\n' - ' parameter_list_starargs ::= "*" [parameter] ("," ' - 'defparameter)* ["," ["**" parameter [","]]]\n' - ' | "**" parameter [","]\n' - ' parameter ::= identifier [":" expression]\n' - ' defparameter ::= parameter ["=" expression]\n' - ' funcname ::= identifier\n' + ' decorated ::= decorators (classdef | funcdef)\n' + ' decorators ::= decorator+\n' + ' decorator ::= "@" dotted_name ["(" [argument_list [","]] ' + '")"] NEWLINE\n' + ' funcdef ::= "def" funcname "(" [parameter_list] ")" ' + '":" suite\n' + ' dotted_name ::= identifier ("." identifier)*\n' + ' parameter_list ::= (defparameter ",")*\n' + ' ( "*" identifier ["," "**" identifier]\n' + ' | "**" identifier\n' + ' | defparameter [","] )\n' + ' defparameter ::= parameter ["=" expression]\n' + ' sublist ::= parameter ("," parameter)* [","]\n' + ' parameter ::= identifier | "(" sublist ")"\n' + ' funcname ::= identifier\n' '\n' 'A function definition is an executable statement. Its execution ' 'binds\n' @@ -5654,7 +4935,7 @@ topics = {'assert': 'The "assert" statement\n' '\n' 'The function definition does not execute the function body; this ' 'gets\n' - 'executed only when the function is called. [2]\n' + 'executed only when the function is called. [3]\n' '\n' 'A function definition may be wrapped by one or more *decorator*\n' 'expressions. Decorator expressions are evaluated when the ' @@ -5667,52 +4948,47 @@ topics = {'assert': 'The "assert" statement\n' 'function name\n' 'instead of the function object. Multiple decorators are applied ' 'in\n' - 'nested fashion. For example, the following code\n' + 'nested fashion. For example, the following code:\n' '\n' ' @f1(arg)\n' ' @f2\n' ' def func(): pass\n' '\n' - 'is roughly equivalent to\n' + 'is equivalent to:\n' '\n' ' def func(): pass\n' ' func = f1(arg)(f2(func))\n' '\n' - 'except that the original function is not temporarily bound to ' - 'the name\n' - '"func".\n' - '\n' - 'When one or more *parameters* have the form *parameter* "="\n' - '*expression*, the function is said to have “default parameter ' - 'values.”\n' + 'When one or more top-level *parameters* have the form ' + '*parameter* "="\n' + '*expression*, the function is said to have "default parameter ' + 'values."\n' 'For a parameter with a default value, the corresponding ' '*argument* may\n' - 'be omitted from a call, in which case the parameter’s default ' + "be omitted from a call, in which case the parameter's default " 'value is\n' 'substituted. If a parameter has a default value, all following\n' - 'parameters up until the “"*"” must also have a default value — ' - 'this is\n' - 'a syntactic restriction that is not expressed by the grammar.\n' - '\n' - '**Default parameter values are evaluated from left to right when ' - 'the\n' - 'function definition is executed.** This means that the ' - 'expression is\n' - 'evaluated once, when the function is defined, and that the same ' - '“pre-\n' - 'computed” value is used for each call. This is especially ' - 'important\n' - 'to understand when a default parameter is a mutable object, such ' - 'as a\n' - 'list or a dictionary: if the function modifies the object (e.g. ' - 'by\n' - 'appending an item to a list), the default value is in effect ' - 'modified.\n' - 'This is generally not what was intended. A way around this is ' - 'to use\n' - '"None" as the default, and explicitly test for it in the body of ' - 'the\n' - 'function, e.g.:\n' + 'parameters must also have a default value --- this is a ' + 'syntactic\n' + 'restriction that is not expressed by the grammar.\n' + '\n' + '**Default parameter values are evaluated when the function ' + 'definition\n' + 'is executed.** This means that the expression is evaluated ' + 'once, when\n' + 'the function is defined, and that the same "pre-computed" value ' + 'is\n' + 'used for each call. This is especially important to understand ' + 'when a\n' + 'default parameter is a mutable object, such as a list or a ' + 'dictionary:\n' + 'if the function modifies the object (e.g. by appending an item ' + 'to a\n' + 'list), the default value is in effect modified. This is ' + 'generally not\n' + 'what was intended. A way around this is to use "None" as the\n' + 'default, and explicitly test for it in the body of the function, ' + 'e.g.:\n' '\n' ' def whats_on_the_telly(penguin=None):\n' ' if penguin is None:\n' @@ -5726,44 +5002,16 @@ topics = {'assert': 'The "assert" statement\n' 'mentioned in\n' 'the parameter list, either from position arguments, from ' 'keyword\n' - 'arguments, or from default values. If the form “"*identifier"” ' + 'arguments, or from default values. If the form ""*identifier"" ' 'is\n' 'present, it is initialized to a tuple receiving any excess ' 'positional\n' - 'parameters, defaulting to the empty tuple. If the form\n' - '“"**identifier"” is present, it is initialized to a new ordered\n' - 'mapping receiving any excess keyword arguments, defaulting to a ' - 'new\n' - 'empty mapping of the same type. Parameters after “"*"” or\n' - '“"*identifier"” are keyword-only parameters and may only be ' - 'passed\n' - 'used keyword arguments.\n' - '\n' - 'Parameters may have an *annotation* of the form “": ' - 'expression"”\n' - 'following the parameter name. Any parameter may have an ' - 'annotation,\n' - 'even those of the form "*identifier" or "**identifier". ' - 'Functions may\n' - 'have “return” annotation of the form “"-> expression"” after ' - 'the\n' - 'parameter list. These annotations can be any valid Python ' - 'expression.\n' - 'The presence of annotations does not change the semantics of a\n' - 'function. The annotation values are available as values of a\n' - 'dictionary keyed by the parameters’ names in the ' - '"__annotations__"\n' - 'attribute of the function object. If the "annotations" import ' - 'from\n' - '"__future__" is used, annotations are preserved as strings at ' - 'runtime\n' - 'which enables postponed evaluation. Otherwise, they are ' - 'evaluated\n' - 'when the function definition is executed. In this case ' - 'annotations\n' - 'may be evaluated in a different order than they appear in the ' - 'source\n' - 'code.\n' + 'parameters, defaulting to the empty tuple. If the form\n' + '""**identifier"" is present, it is initialized to a new ' + 'dictionary\n' + 'receiving any excess keyword arguments, defaulting to a new ' + 'empty\n' + 'dictionary.\n' '\n' 'It is also possible to create anonymous functions (functions not ' 'bound\n' @@ -5772,44 +5020,25 @@ topics = {'assert': 'The "assert" statement\n' 'lambda\n' 'expression is merely a shorthand for a simplified function ' 'definition;\n' - 'a function defined in a “"def"” statement can be passed around ' + 'a function defined in a ""def"" statement can be passed around ' 'or\n' 'assigned to another name just like a function defined by a ' 'lambda\n' - 'expression. The “"def"” form is actually more powerful since ' + 'expression. The ""def"" form is actually more powerful since ' 'it\n' - 'allows the execution of multiple statements and annotations.\n' + 'allows the execution of multiple statements.\n' '\n' - '**Programmer’s note:** Functions are first-class objects. A ' - '“"def"”\n' - 'statement executed inside a function definition defines a local\n' - 'function that can be returned or passed around. Free variables ' - 'used\n' - 'in the nested function can access the local variables of the ' + "**Programmer's note:** Functions are first-class objects. A " + '""def""\n' + 'form executed inside a function definition defines a local ' 'function\n' + 'that can be returned or passed around. Free variables used in ' + 'the\n' + 'nested function can access the local variables of the function\n' 'containing the def. See section Naming and binding for ' - 'details.\n' - '\n' - 'See also:\n' - '\n' - ' **PEP 3107** - Function Annotations\n' - ' The original specification for function annotations.\n' - '\n' - ' **PEP 484** - Type Hints\n' - ' Definition of a standard meaning for annotations: type ' - 'hints.\n' - '\n' - ' **PEP 526** - Syntax for Variable Annotations\n' - ' Ability to type hint variable declarations, including ' - 'class\n' - ' variables and instance variables\n' - '\n' - ' **PEP 563** - Postponed Evaluation of Annotations\n' - ' Support for forward references within annotations by ' - 'preserving\n' - ' annotations in a string form at runtime instead of eager\n' - ' evaluation.\n', - 'global': 'The "global" statement\n' + 'details.\n', + 'global': '\n' + 'The "global" statement\n' '**********************\n' '\n' ' global_stmt ::= "global" identifier ("," identifier)*\n' @@ -5830,29 +5059,30 @@ topics = {'assert': 'The "assert" statement\n' 'Names listed in a "global" statement must not be defined as ' 'formal\n' 'parameters or in a "for" loop control target, "class" definition,\n' - 'function definition, "import" statement, or variable annotation.\n' + 'function definition, or "import" statement.\n' '\n' '**CPython implementation detail:** The current implementation does ' 'not\n' - 'enforce some of these restrictions, but programs should not abuse ' - 'this\n' - 'freedom, as future implementations may enforce them or silently ' - 'change\n' - 'the meaning of the program.\n' + 'enforce the latter two restrictions, but programs should not ' + 'abuse\n' + 'this freedom, as future implementations may enforce them or ' + 'silently\n' + 'change the meaning of the program.\n' '\n' - '**Programmer’s note:** "global" is a directive to the parser. It\n' + '**Programmer\'s note:** "global" is a directive to the parser. ' + 'It\n' 'applies only to code parsed at the same time as the "global"\n' - 'statement. In particular, a "global" statement contained in a ' - 'string\n' - 'or code object supplied to the built-in "exec()" function does ' - 'not\n' - 'affect the code block *containing* the function call, and code\n' - 'contained in such a string is unaffected by "global" statements in ' - 'the\n' - 'code containing the function call. The same applies to the ' - '"eval()"\n' - 'and "compile()" functions.\n', - 'id-classes': 'Reserved classes of identifiers\n' + 'statement. In particular, a "global" statement contained in an ' + '"exec"\n' + 'statement does not affect the code block *containing* the "exec"\n' + 'statement, and code contained in an "exec" statement is unaffected ' + 'by\n' + '"global" statements in the code containing the "exec" statement. ' + 'The\n' + 'same applies to the "eval()", "execfile()" and "compile()" ' + 'functions.\n', + 'id-classes': '\n' + 'Reserved classes of identifiers\n' '*******************************\n' '\n' 'Certain classes of identifiers (besides keywords) have ' @@ -5866,11 +5096,11 @@ topics = {'assert': 'The "assert" statement\n' 'identifier "_"\n' ' is used in the interactive interpreter to store the result ' 'of the\n' - ' last evaluation; it is stored in the "builtins" module. ' - 'When not\n' - ' in interactive mode, "_" has no special meaning and is not ' - 'defined.\n' - ' See section The import statement.\n' + ' last evaluation; it is stored in the "__builtin__" module. ' + 'When\n' + ' not in interactive mode, "_" has no special meaning and is ' + 'not\n' + ' defined. See section The import statement.\n' '\n' ' Note: The name "_" is often used in conjunction with\n' ' internationalization; refer to the documentation for the\n' @@ -5897,89 +5127,25 @@ topics = {'assert': 'The "assert" statement\n' 'within the\n' ' context of a class definition, are re-written to use a ' 'mangled form\n' - ' to help avoid name clashes between “private” attributes of ' + ' to help avoid name clashes between "private" attributes of ' 'base and\n' ' derived classes. See section Identifiers (Names).\n', - 'identifiers': 'Identifiers and keywords\n' + 'identifiers': '\n' + 'Identifiers and keywords\n' '************************\n' '\n' 'Identifiers (also referred to as *names*) are described by ' 'the\n' - 'following lexical definitions.\n' - '\n' - 'The syntax of identifiers in Python is based on the Unicode ' - 'standard\n' - 'annex UAX-31, with elaboration and changes as defined below; ' - 'see also\n' - '**PEP 3131** for further details.\n' + 'following lexical definitions:\n' '\n' - 'Within the ASCII range (U+0001..U+007F), the valid characters ' - 'for\n' - 'identifiers are the same as in Python 2.x: the uppercase and ' - 'lowercase\n' - 'letters "A" through "Z", the underscore "_" and, except for ' - 'the first\n' - 'character, the digits "0" through "9".\n' - '\n' - 'Python 3.0 introduces additional characters from outside the ' - 'ASCII\n' - 'range (see **PEP 3131**). For these characters, the ' - 'classification\n' - 'uses the version of the Unicode Character Database as ' - 'included in the\n' - '"unicodedata" module.\n' + ' identifier ::= (letter|"_") (letter | digit | "_")*\n' + ' letter ::= lowercase | uppercase\n' + ' lowercase ::= "a"..."z"\n' + ' uppercase ::= "A"..."Z"\n' + ' digit ::= "0"..."9"\n' '\n' 'Identifiers are unlimited in length. Case is significant.\n' '\n' - ' identifier ::= xid_start xid_continue*\n' - ' id_start ::= <all characters in general categories Lu, ' - 'Ll, Lt, Lm, Lo, Nl, the underscore, and characters with the ' - 'Other_ID_Start property>\n' - ' id_continue ::= <all characters in id_start, plus ' - 'characters in the categories Mn, Mc, Nd, Pc and others with ' - 'the Other_ID_Continue property>\n' - ' xid_start ::= <all characters in id_start whose NFKC ' - 'normalization is in "id_start xid_continue*">\n' - ' xid_continue ::= <all characters in id_continue whose NFKC ' - 'normalization is in "id_continue*">\n' - '\n' - 'The Unicode category codes mentioned above stand for:\n' - '\n' - '* *Lu* - uppercase letters\n' - '\n' - '* *Ll* - lowercase letters\n' - '\n' - '* *Lt* - titlecase letters\n' - '\n' - '* *Lm* - modifier letters\n' - '\n' - '* *Lo* - other letters\n' - '\n' - '* *Nl* - letter numbers\n' - '\n' - '* *Mn* - nonspacing marks\n' - '\n' - '* *Mc* - spacing combining marks\n' - '\n' - '* *Nd* - decimal numbers\n' - '\n' - '* *Pc* - connector punctuations\n' - '\n' - '* *Other_ID_Start* - explicit list of characters in ' - 'PropList.txt to\n' - ' support backwards compatibility\n' - '\n' - '* *Other_ID_Continue* - likewise\n' - '\n' - 'All identifiers are converted into the normal form NFKC while ' - 'parsing;\n' - 'comparison of identifiers is based on NFKC.\n' - '\n' - 'A non-normative HTML file listing all valid identifier ' - 'characters for\n' - 'Unicode 4.1 can be found at https://www.dcl.hpi.uni-\n' - 'potsdam.de/home/loewis/table-3131.html.\n' - '\n' '\n' 'Keywords\n' '========\n' @@ -5990,13 +5156,28 @@ topics = {'assert': 'The "assert" statement\n' 'They must\n' 'be spelled exactly as written here:\n' '\n' - ' False await else import pass\n' - ' None break except in raise\n' - ' True class finally is return\n' - ' and continue for lambda try\n' - ' as def from nonlocal while\n' - ' assert del global not with\n' - ' async elif if or yield\n' + ' and del from not while\n' + ' as elif global or with\n' + ' assert else if pass yield\n' + ' break except import print\n' + ' class exec in raise\n' + ' continue finally is return\n' + ' def for lambda try\n' + '\n' + 'Changed in version 2.4: "None" became a constant and is now ' + 'recognized\n' + 'by the compiler as a name for the built-in object "None". ' + 'Although it\n' + 'is not a keyword, you cannot assign a different object to ' + 'it.\n' + '\n' + 'Changed in version 2.5: Using "as" and "with" as identifiers ' + 'triggers\n' + 'a warning. To use them as keywords, enable the ' + '"with_statement"\n' + 'future feature .\n' + '\n' + 'Changed in version 2.6: "as" and "with" are full keywords.\n' '\n' '\n' 'Reserved classes of identifiers\n' @@ -6013,11 +5194,11 @@ topics = {'assert': 'The "assert" statement\n' 'identifier "_"\n' ' is used in the interactive interpreter to store the result ' 'of the\n' - ' last evaluation; it is stored in the "builtins" module. ' - 'When not\n' - ' in interactive mode, "_" has no special meaning and is not ' - 'defined.\n' - ' See section The import statement.\n' + ' last evaluation; it is stored in the "__builtin__" ' + 'module. When\n' + ' not in interactive mode, "_" has no special meaning and is ' + 'not\n' + ' defined. See section The import statement.\n' '\n' ' Note: The name "_" is often used in conjunction with\n' ' internationalization; refer to the documentation for ' @@ -6045,16 +5226,17 @@ topics = {'assert': 'The "assert" statement\n' 'within the\n' ' context of a class definition, are re-written to use a ' 'mangled form\n' - ' to help avoid name clashes between “private” attributes of ' + ' to help avoid name clashes between "private" attributes of ' 'base and\n' ' derived classes. See section Identifiers (Names).\n', - 'if': 'The "if" statement\n' + 'if': '\n' + 'The "if" statement\n' '******************\n' '\n' 'The "if" statement is used for conditional execution:\n' '\n' ' if_stmt ::= "if" expression ":" suite\n' - ' ("elif" expression ":" suite)*\n' + ' ( "elif" expression ":" suite )*\n' ' ["else" ":" suite]\n' '\n' 'It selects exactly one of the suites by evaluating the expressions ' @@ -6064,13 +5246,14 @@ topics = {'assert': 'The "assert" statement\n' '(and no other part of the "if" statement is executed or evaluated).\n' 'If all expressions are false, the suite of the "else" clause, if\n' 'present, is executed.\n', - 'imaginary': 'Imaginary literals\n' + 'imaginary': '\n' + 'Imaginary literals\n' '******************\n' '\n' 'Imaginary literals are described by the following lexical ' 'definitions:\n' '\n' - ' imagnumber ::= (floatnumber | digitpart) ("j" | "J")\n' + ' imagnumber ::= (floatnumber | intpart) ("j" | "J")\n' '\n' 'An imaginary literal yields a complex number with a real part ' 'of 0.0.\n' @@ -6082,114 +5265,191 @@ topics = {'assert': 'The "assert" statement\n' 'it,\n' 'e.g., "(3+4j)". Some examples of imaginary literals:\n' '\n' - ' 3.14j 10.j 10j .001j 1e100j 3.14e-10j ' - '3.14_15_93j\n', - 'import': 'The "import" statement\n' + ' 3.14j 10.j 10j .001j 1e100j 3.14e-10j\n', + 'import': '\n' + 'The "import" statement\n' '**********************\n' '\n' - ' import_stmt ::= "import" module ["as" identifier] ("," ' - 'module ["as" identifier])*\n' + ' import_stmt ::= "import" module ["as" name] ( "," module ' + '["as" name] )*\n' ' | "from" relative_module "import" identifier ' - '["as" identifier]\n' - ' ("," identifier ["as" identifier])*\n' + '["as" name]\n' + ' ( "," identifier ["as" name] )*\n' ' | "from" relative_module "import" "(" ' - 'identifier ["as" identifier]\n' - ' ("," identifier ["as" identifier])* [","] ")"\n' + 'identifier ["as" name]\n' + ' ( "," identifier ["as" name] )* [","] ")"\n' ' | "from" module "import" "*"\n' ' module ::= (identifier ".")* identifier\n' ' relative_module ::= "."* module | "."+\n' + ' name ::= identifier\n' '\n' - 'The basic import statement (no "from" clause) is executed in two\n' - 'steps:\n' - '\n' - '1. find a module, loading and initializing it if necessary\n' - '\n' - '2. define a name or names in the local namespace for the scope\n' - ' where the "import" statement occurs.\n' + 'Import statements are executed in two steps: (1) find a module, ' + 'and\n' + 'initialize it if necessary; (2) define a name or names in the ' + 'local\n' + 'namespace (of the scope where the "import" statement occurs). The\n' + 'statement comes in two forms differing on whether it uses the ' + '"from"\n' + 'keyword. The first form (without "from") repeats these steps for ' + 'each\n' + 'identifier in the list. The form with "from" performs step (1) ' + 'once,\n' + 'and then performs step (2) repeatedly.\n' '\n' - 'When the statement contains multiple clauses (separated by commas) ' - 'the\n' - 'two steps are carried out separately for each clause, just as ' - 'though\n' - 'the clauses had been separated out into individual import ' - 'statements.\n' + 'To understand how step (1) occurs, one must first understand how\n' + 'Python handles hierarchical naming of modules. To help organize\n' + 'modules and provide a hierarchy in naming, Python has a concept ' + 'of\n' + 'packages. A package can contain other packages and modules while\n' + 'modules cannot contain other modules or packages. From a file ' + 'system\n' + 'perspective, packages are directories and modules are files.\n' '\n' - 'The details of the first step, finding and loading modules are\n' - 'described in greater detail in the section on the import system, ' - 'which\n' - 'also describes the various types of packages and modules that can ' - 'be\n' - 'imported, as well as all the hooks that can be used to customize ' + 'Once the name of the module is known (unless otherwise specified, ' 'the\n' - 'import system. Note that failures in this step may indicate ' - 'either\n' - 'that the module could not be located, *or* that an error occurred\n' - 'while initializing the module, which includes execution of the\n' - 'module’s code.\n' - '\n' - 'If the requested module is retrieved successfully, it will be ' - 'made\n' - 'available in the local namespace in one of three ways:\n' - '\n' - '* If the module name is followed by "as", then the name following\n' - ' "as" is bound directly to the imported module.\n' - '\n' - '* If no other name is specified, and the module being imported is ' - 'a\n' - ' top level module, the module’s name is bound in the local ' - 'namespace\n' - ' as a reference to the imported module\n' + 'term "module" will refer to both packages and modules), searching ' + 'for\n' + 'the module or package can begin. The first place checked is\n' + '"sys.modules", the cache of all modules that have been imported\n' + 'previously. If the module is found there then it is used in step ' + '(2)\n' + 'of import.\n' '\n' - '* If the module being imported is *not* a top level module, then ' - 'the\n' - ' name of the top level package that contains the module is bound ' + 'If the module is not found in the cache, then "sys.meta_path" is\n' + 'searched (the specification for "sys.meta_path" can be found in ' + '**PEP\n' + '302**). The object is a list of *finder* objects which are queried ' 'in\n' - ' the local namespace as a reference to the top level package. ' - 'The\n' - ' imported module must be accessed using its full qualified name\n' - ' rather than directly\n' - '\n' - 'The "from" form uses a slightly more complex process:\n' + 'order as to whether they know how to load the module by calling ' + 'their\n' + '"find_module()" method with the name of the module. If the module\n' + 'happens to be contained within a package (as denoted by the ' + 'existence\n' + 'of a dot in the name), then a second argument to "find_module()" ' + 'is\n' + 'given as the value of the "__path__" attribute from the parent ' + 'package\n' + '(everything up to the last dot in the name of the module being\n' + 'imported). If a finder can find the module it returns a *loader*\n' + '(discussed later) or returns "None".\n' '\n' - '1. find the module specified in the "from" clause, loading and\n' - ' initializing it if necessary;\n' + 'If none of the finders on "sys.meta_path" are able to find the ' + 'module\n' + 'then some implicitly defined finders are queried. Implementations ' + 'of\n' + 'Python vary in what implicit meta path finders are defined. The ' + 'one\n' + 'they all do define, though, is one that handles "sys.path_hooks",\n' + '"sys.path_importer_cache", and "sys.path".\n' '\n' - '2. for each of the identifiers specified in the "import" clauses:\n' + 'The implicit finder searches for the requested module in the ' + '"paths"\n' + 'specified in one of two places ("paths" do not have to be file ' + 'system\n' + 'paths). If the module being imported is supposed to be contained\n' + 'within a package then the second argument passed to ' + '"find_module()",\n' + '"__path__" on the parent package, is used as the source of paths. ' + 'If\n' + 'the module is not contained in a package then "sys.path" is used ' + 'as\n' + 'the source of paths.\n' '\n' - ' 1. check if the imported module has an attribute by that name\n' + 'Once the source of paths is chosen it is iterated over to find a\n' + 'finder that can handle that path. The dict at\n' + '"sys.path_importer_cache" caches finders for paths and is checked ' + 'for\n' + 'a finder. If the path does not have a finder cached then\n' + '"sys.path_hooks" is searched by calling each object in the list ' + 'with a\n' + 'single argument of the path, returning a finder or raises\n' + '"ImportError". If a finder is returned then it is cached in\n' + '"sys.path_importer_cache" and then used for that path entry. If ' + 'no\n' + 'finder can be found but the path exists then a value of "None" is\n' + 'stored in "sys.path_importer_cache" to signify that an implicit, ' + 'file-\n' + 'based finder that handles modules stored as individual files ' + 'should be\n' + 'used for that path. If the path does not exist then a finder ' + 'which\n' + 'always returns "None" is placed in the cache for the path.\n' '\n' - ' 2. if not, attempt to import a submodule with that name and ' - 'then\n' - ' check the imported module again for that attribute\n' + 'If no finder can find the module then "ImportError" is raised.\n' + 'Otherwise some finder returned a loader whose "load_module()" ' + 'method\n' + 'is called with the name of the module to load (see **PEP 302** for ' + 'the\n' + 'original definition of loaders). A loader has several ' + 'responsibilities\n' + 'to perform on a module it loads. First, if the module already ' + 'exists\n' + 'in "sys.modules" (a possibility if the loader is called outside of ' + 'the\n' + 'import machinery) then it is to use that module for initialization ' + 'and\n' + 'not a new module. But if the module does not exist in ' + '"sys.modules"\n' + 'then it is to be added to that dict before initialization begins. ' + 'If\n' + 'an error occurs during loading of the module and it was added to\n' + '"sys.modules" it is to be removed from the dict. If an error ' + 'occurs\n' + 'but the module was already in "sys.modules" it is left in the ' + 'dict.\n' '\n' - ' 3. if the attribute is not found, "ImportError" is raised.\n' + 'The loader must set several attributes on the module. "__name__" ' + 'is to\n' + 'be set to the name of the module. "__file__" is to be the "path" ' + 'to\n' + 'the file unless the module is built-in (and thus listed in\n' + '"sys.builtin_module_names") in which case the attribute is not ' + 'set. If\n' + 'what is being imported is a package then "__path__" is to be set ' + 'to a\n' + 'list of paths to be searched when looking for modules and ' + 'packages\n' + 'contained within the package being imported. "__package__" is ' + 'optional\n' + 'but should be set to the name of package that contains the module ' + 'or\n' + 'package (the empty string is used for module not contained in a\n' + 'package). "__loader__" is also optional but should be set to the\n' + 'loader object that is loading the module.\n' '\n' - ' 4. otherwise, a reference to that value is stored in the local\n' - ' namespace, using the name in the "as" clause if it is ' - 'present,\n' - ' otherwise using the attribute name\n' + 'If an error occurs during loading then the loader raises ' + '"ImportError"\n' + 'if some other exception is not already being propagated. Otherwise ' + 'the\n' + 'loader returns the module that was loaded and initialized.\n' '\n' - 'Examples:\n' + 'When step (1) finishes without raising an exception, step (2) can\n' + 'begin.\n' '\n' - ' import foo # foo imported and bound locally\n' - ' import foo.bar.baz # foo.bar.baz imported, foo bound ' - 'locally\n' - ' import foo.bar.baz as fbb # foo.bar.baz imported and bound as ' - 'fbb\n' - ' from foo.bar import baz # foo.bar.baz imported and bound as ' - 'baz\n' - ' from foo import attr # foo imported and foo.attr bound as ' - 'attr\n' + 'The first form of "import" statement binds the module name in the\n' + 'local namespace to the module object, and then goes on to import ' + 'the\n' + 'next identifier, if any. If the module name is followed by "as", ' + 'the\n' + 'name following "as" is used as the local name for the module.\n' '\n' - 'If the list of identifiers is replaced by a star ("\'*\'"), all ' - 'public\n' - 'names defined in the module are bound in the local namespace for ' + 'The "from" form does not bind the module name: it goes through ' 'the\n' - 'scope where the "import" statement occurs.\n' + 'list of identifiers, looks each one of them up in the module found ' + 'in\n' + 'step (1), and binds the name in the local namespace to the object ' + 'thus\n' + 'found. As with the first form of "import", an alternate local ' + 'name\n' + 'can be supplied by specifying ""as" localname". If a name is not\n' + 'found, "ImportError" is raised. If the list of identifiers is\n' + 'replaced by a star ("\'*\'"), all public names defined in the ' + 'module are\n' + 'bound in the local namespace of the "import" statement..\n' '\n' 'The *public names* defined by a module are determined by checking ' 'the\n' - 'module’s namespace for a variable named "__all__"; if defined, it ' + 'module\'s namespace for a variable named "__all__"; if defined, it ' 'must\n' 'be a sequence of strings which are names defined or imported by ' 'that\n' @@ -6197,9 +5457,9 @@ topics = {'assert': 'The "assert" statement\n' 'and\n' 'are required to exist. If "__all__" is not defined, the set of ' 'public\n' - 'names includes all names found in the module’s namespace which do ' + "names includes all names found in the module's namespace which do " 'not\n' - 'begin with an underscore character ("\'_\'"). "__all__" should ' + 'begin with an underscore character ("\'_\'"). "__all__" should ' 'contain\n' 'the entire public API. It is intended to avoid accidentally ' 'exporting\n' @@ -6207,9 +5467,13 @@ topics = {'assert': 'The "assert" statement\n' 'were\n' 'imported and used within the module).\n' '\n' - 'The wild card form of import — "from module import *" — is only\n' - 'allowed at the module level. Attempting to use it in class or\n' - 'function definitions will raise a "SyntaxError".\n' + 'The "from" form with "*" may only occur in a module scope. If ' + 'the\n' + 'wild card form of import --- "import *" --- is used in a function ' + 'and\n' + 'the function contains or is a nested block with free variables, ' + 'the\n' + 'compiler will raise a "SyntaxError".\n' '\n' 'When specifying what module to import you do not have to specify ' 'the\n' @@ -6232,16 +5496,12 @@ topics = {'assert': 'The "assert" statement\n' 'end up importing "pkg.mod". If you execute "from ..subpkg2 import ' 'mod"\n' 'from within "pkg.subpkg1" you will import "pkg.subpkg2.mod". The\n' - 'specification for relative imports is contained in the Package\n' - 'Relative Imports section.\n' + 'specification for relative imports is contained within **PEP ' + '328**.\n' '\n' '"importlib.import_module()" is provided to support applications ' 'that\n' - 'determine dynamically the modules to be loaded.\n' - '\n' - 'Raises an auditing event "import" with arguments "module", ' - '"filename",\n' - '"sys.path", "sys.meta_path", "sys.path_hooks".\n' + 'determine which modules need to be loaded dynamically.\n' '\n' '\n' 'Future statements\n' @@ -6250,24 +5510,23 @@ topics = {'assert': 'The "assert" statement\n' 'A *future statement* is a directive to the compiler that a ' 'particular\n' 'module should be compiled using syntax or semantics that will be\n' - 'available in a specified future release of Python where the ' - 'feature\n' - 'becomes standard.\n' - '\n' - 'The future statement is intended to ease migration to future ' - 'versions\n' - 'of Python that introduce incompatible changes to the language. ' - 'It\n' - 'allows use of the new features on a per-module basis before the\n' - 'release in which the feature becomes standard.\n' + 'available in a specified future release of Python. The future\n' + 'statement is intended to ease migration to future versions of ' + 'Python\n' + 'that introduce incompatible changes to the language. It allows ' + 'use of\n' + 'the new features on a per-module basis before the release in which ' + 'the\n' + 'feature becomes standard.\n' '\n' - ' future_stmt ::= "from" "__future__" "import" feature ["as" ' - 'identifier]\n' - ' ("," feature ["as" identifier])*\n' - ' | "from" "__future__" "import" "(" feature ' - '["as" identifier]\n' - ' ("," feature ["as" identifier])* [","] ")"\n' - ' feature ::= identifier\n' + ' future_statement ::= "from" "__future__" "import" feature ["as" ' + 'name]\n' + ' ("," feature ["as" name])*\n' + ' | "from" "__future__" "import" "(" feature ' + '["as" name]\n' + ' ("," feature ["as" name])* [","] ")"\n' + ' feature ::= identifier\n' + ' name ::= identifier\n' '\n' 'A future statement must appear near the top of the module. The ' 'only\n' @@ -6281,17 +5540,13 @@ topics = {'assert': 'The "assert" statement\n' '\n' '* other future statements.\n' '\n' - 'The only feature in Python 3.7 that requires using the future\n' - 'statement is "annotations".\n' - '\n' - 'All historical features enabled by the future statement are still\n' - 'recognized by Python 3. The list includes "absolute_import",\n' - '"division", "generators", "generator_stop", "unicode_literals",\n' - '"print_function", "nested_scopes" and "with_statement". They are ' - 'all\n' - 'redundant because they are always enabled, and only kept for ' - 'backwards\n' - 'compatibility.\n' + 'The features recognized by Python 2.6 are "unicode_literals",\n' + '"print_function", "absolute_import", "division", "generators",\n' + '"nested_scopes" and "with_statement". "generators", ' + '"with_statement",\n' + '"nested_scopes" are redundant in Python version 2.6 and above ' + 'because\n' + 'they are always enabled.\n' '\n' 'A future statement is recognized and treated specially at compile\n' 'time: Changes to the semantics of core constructs are often\n' @@ -6323,18 +5578,19 @@ topics = {'assert': 'The "assert" statement\n' '\n' ' import __future__ [as name]\n' '\n' - 'That is not a future statement; it’s an ordinary import statement ' + "That is not a future statement; it's an ordinary import statement " 'with\n' 'no special semantics or syntax restrictions.\n' '\n' - 'Code compiled by calls to the built-in functions "exec()" and\n' - '"compile()" that occur in a module "M" containing a future ' - 'statement\n' - 'will, by default, use the new syntax or semantics associated with ' - 'the\n' - 'future statement. This can be controlled by optional arguments ' - 'to\n' - '"compile()" — see the documentation of that function for details.\n' + 'Code compiled by an "exec" statement or calls to the built-in\n' + 'functions "compile()" and "execfile()" that occur in a module "M"\n' + 'containing a future statement will, by default, use the new ' + 'syntax or\n' + 'semantics associated with the future statement. This can, ' + 'starting\n' + 'with Python 2.2 be controlled by optional arguments to "compile()" ' + '---\n' + 'see the documentation of that function for details.\n' '\n' 'A future statement typed at an interactive interpreter prompt ' 'will\n' @@ -6350,7 +5606,8 @@ topics = {'assert': 'The "assert" statement\n' '\n' ' **PEP 236** - Back to the __future__\n' ' The original proposal for the __future__ mechanism.\n', - 'in': 'Membership test operations\n' + 'in': '\n' + 'Membership test operations\n' '**************************\n' '\n' 'The operators "in" and "not in" test for membership. "x in s"\n' @@ -6374,160 +5631,161 @@ topics = {'assert': 'The "assert" statement\n' '"False" otherwise.\n' '\n' 'For user-defined classes which do not define "__contains__()" but do\n' - 'define "__iter__()", "x in y" is "True" if some value "z", for which\n' - 'the expression "x is z or x == z" is true, is produced while ' - 'iterating\n' - 'over "y". If an exception is raised during the iteration, it is as if\n' - '"in" raised that exception.\n' + 'define "__iter__()", "x in y" is "True" if some value "z" with "x ==\n' + 'z" is produced while iterating over "y". If an exception is raised\n' + 'during the iteration, it is as if "in" raised that exception.\n' '\n' 'Lastly, the old-style iteration protocol is tried: if a class defines\n' '"__getitem__()", "x in y" is "True" if and only if there is a non-\n' - 'negative integer index *i* such that "x is y[i] or x == y[i]", and no\n' - 'lower integer index raises the "IndexError" exception. (If any other\n' + 'negative integer index *i* such that "x == y[i]", and all lower\n' + 'integer indices do not raise "IndexError" exception. (If any other\n' 'exception is raised, it is as if "in" raised that exception).\n' '\n' - 'The operator "not in" is defined to have the inverse truth value of\n' + 'The operator "not in" is defined to have the inverse true value of\n' '"in".\n', - 'integers': 'Integer literals\n' - '****************\n' - '\n' - 'Integer literals are described by the following lexical ' - 'definitions:\n' - '\n' - ' integer ::= decinteger | bininteger | octinteger | ' - 'hexinteger\n' - ' decinteger ::= nonzerodigit (["_"] digit)* | "0"+ (["_"] ' - '"0")*\n' - ' bininteger ::= "0" ("b" | "B") (["_"] bindigit)+\n' - ' octinteger ::= "0" ("o" | "O") (["_"] octdigit)+\n' - ' hexinteger ::= "0" ("x" | "X") (["_"] hexdigit)+\n' - ' nonzerodigit ::= "1"..."9"\n' - ' digit ::= "0"..."9"\n' - ' bindigit ::= "0" | "1"\n' - ' octdigit ::= "0"..."7"\n' - ' hexdigit ::= digit | "a"..."f" | "A"..."F"\n' - '\n' - 'There is no limit for the length of integer literals apart from ' - 'what\n' - 'can be stored in available memory.\n' - '\n' - 'Underscores are ignored for determining the numeric value of ' - 'the\n' - 'literal. They can be used to group digits for enhanced ' - 'readability.\n' - 'One underscore can occur between digits, and after base ' - 'specifiers\n' - 'like "0x".\n' - '\n' - 'Note that leading zeros in a non-zero decimal number are not ' - 'allowed.\n' - 'This is for disambiguation with C-style octal literals, which ' - 'Python\n' - 'used before version 3.0.\n' - '\n' - 'Some examples of integer literals:\n' - '\n' - ' 7 2147483647 0o177 0b100110111\n' - ' 3 79228162514264337593543950336 0o377 0xdeadbeef\n' - ' 100_000_000_000 0b_1110_0101\n' - '\n' - 'Changed in version 3.6: Underscores are now allowed for ' - 'grouping\n' - 'purposes in literals.\n', - 'lambda': 'Lambdas\n' + 'integers': '\n' + 'Integer and long integer literals\n' + '*********************************\n' + '\n' + 'Integer and long integer literals are described by the ' + 'following\n' + 'lexical definitions:\n' + '\n' + ' longinteger ::= integer ("l" | "L")\n' + ' integer ::= decimalinteger | octinteger | hexinteger | ' + 'bininteger\n' + ' decimalinteger ::= nonzerodigit digit* | "0"\n' + ' octinteger ::= "0" ("o" | "O") octdigit+ | "0" octdigit+\n' + ' hexinteger ::= "0" ("x" | "X") hexdigit+\n' + ' bininteger ::= "0" ("b" | "B") bindigit+\n' + ' nonzerodigit ::= "1"..."9"\n' + ' octdigit ::= "0"..."7"\n' + ' bindigit ::= "0" | "1"\n' + ' hexdigit ::= digit | "a"..."f" | "A"..."F"\n' + '\n' + 'Although both lower case "\'l\'" and upper case "\'L\'" are ' + 'allowed as\n' + 'suffix for long integers, it is strongly recommended to always ' + 'use\n' + '"\'L\'", since the letter "\'l\'" looks too much like the digit ' + '"\'1\'".\n' + '\n' + 'Plain integer literals that are above the largest representable ' + 'plain\n' + 'integer (e.g., 2147483647 when using 32-bit arithmetic) are ' + 'accepted\n' + 'as if they were long integers instead. [1] There is no limit ' + 'for long\n' + 'integer literals apart from what can be stored in available ' + 'memory.\n' + '\n' + 'Some examples of plain integer literals (first row) and long ' + 'integer\n' + 'literals (second and third rows):\n' + '\n' + ' 7 2147483647 0177\n' + ' 3L 79228162514264337593543950336L 0377L 0x100000000L\n' + ' 79228162514264337593543950336 0xdeadbeef\n', + 'lambda': '\n' + 'Lambdas\n' '*******\n' '\n' - ' lambda_expr ::= "lambda" [parameter_list] ":" ' - 'expression\n' - ' lambda_expr_nocond ::= "lambda" [parameter_list] ":" ' - 'expression_nocond\n' + ' lambda_expr ::= "lambda" [parameter_list]: expression\n' + ' old_lambda_expr ::= "lambda" [parameter_list]: old_expression\n' '\n' - 'Lambda expressions (sometimes called lambda forms) are used to ' + 'Lambda expressions (sometimes called lambda forms) have the same\n' + 'syntactic position as expressions. They are a shorthand to ' 'create\n' - 'anonymous functions. The expression "lambda parameters: ' + 'anonymous functions; the expression "lambda arguments: ' 'expression"\n' 'yields a function object. The unnamed object behaves like a ' 'function\n' - 'object defined with:\n' + 'object defined with\n' '\n' - ' def <lambda>(parameters):\n' + ' def name(arguments):\n' ' return expression\n' '\n' 'See section Function definitions for the syntax of parameter ' 'lists.\n' 'Note that functions created with lambda expressions cannot ' 'contain\n' - 'statements or annotations.\n', - 'lists': 'List displays\n' + 'statements.\n', + 'lists': '\n' + 'List displays\n' '*************\n' '\n' 'A list display is a possibly empty series of expressions enclosed ' 'in\n' 'square brackets:\n' '\n' - ' list_display ::= "[" [starred_list | comprehension] "]"\n' - '\n' - 'A list display yields a new list object, the contents being ' + ' list_display ::= "[" [expression_list | ' + 'list_comprehension] "]"\n' + ' list_comprehension ::= expression list_for\n' + ' list_for ::= "for" target_list "in" ' + 'old_expression_list [list_iter]\n' + ' old_expression_list ::= old_expression [("," old_expression)+ ' + '[","]]\n' + ' old_expression ::= or_test | old_lambda_expr\n' + ' list_iter ::= list_for | list_if\n' + ' list_if ::= "if" old_expression [list_iter]\n' + '\n' + 'A list display yields a new list object. Its contents are ' 'specified\n' - 'by either a list of expressions or a comprehension. When a comma-\n' - 'separated list of expressions is supplied, its elements are ' - 'evaluated\n' - 'from left to right and placed into the list object in that order.\n' - 'When a comprehension is supplied, the list is constructed from the\n' - 'elements resulting from the comprehension.\n', - 'naming': 'Naming and binding\n' + 'by providing either a list of expressions or a list comprehension.\n' + 'When a comma-separated list of expressions is supplied, its ' + 'elements\n' + 'are evaluated from left to right and placed into the list object ' + 'in\n' + 'that order. When a list comprehension is supplied, it consists of ' + 'a\n' + 'single expression followed by at least one "for" clause and zero ' + 'or\n' + 'more "for" or "if" clauses. In this case, the elements of the new\n' + 'list are those that would be produced by considering each of the ' + '"for"\n' + 'or "if" clauses a block, nesting from left to right, and ' + 'evaluating\n' + 'the expression to produce a list element each time the innermost ' + 'block\n' + 'is reached [1].\n', + 'naming': '\n' + 'Naming and binding\n' '******************\n' '\n' - '\n' - 'Binding of names\n' - '================\n' - '\n' '*Names* refer to objects. Names are introduced by name binding\n' - 'operations.\n' + 'operations. Each occurrence of a name in the program text refers ' + 'to\n' + 'the *binding* of that name established in the innermost function ' + 'block\n' + 'containing the use.\n' '\n' - 'The following constructs bind names: formal parameters to ' - 'functions,\n' - '"import" statements, class and function definitions (these bind ' - 'the\n' - 'class or function name in the defining block), and targets that ' - 'are\n' - 'identifiers if occurring in an assignment, "for" loop header, or ' - 'after\n' - '"as" in a "with" statement or "except" clause. The "import" ' + 'A *block* is a piece of Python program text that is executed as a\n' + 'unit. The following are blocks: a module, a function body, and a ' + 'class\n' + 'definition. Each command typed interactively is a block. A ' + 'script\n' + 'file (a file given as standard input to the interpreter or ' + 'specified\n' + 'on the interpreter command line the first argument) is a code ' + 'block.\n' + 'A script command (a command specified on the interpreter command ' + 'line\n' + "with the '**-c**' option) is a code block. The file read by the\n" + 'built-in function "execfile()" is a code block. The string ' + 'argument\n' + 'passed to the built-in function "eval()" and to the "exec" ' 'statement\n' - 'of the form "from ... import *" binds all names defined in the\n' - 'imported module, except those beginning with an underscore. This ' - 'form\n' - 'may only be used at the module level.\n' - '\n' - 'A target occurring in a "del" statement is also considered bound ' - 'for\n' - 'this purpose (though the actual semantics are to unbind the ' - 'name).\n' - '\n' - 'Each assignment or import statement occurs within a block defined ' - 'by a\n' - 'class or function definition or at the module level (the ' - 'top-level\n' - 'code block).\n' - '\n' - 'If a name is bound in a block, it is a local variable of that ' - 'block,\n' - 'unless declared as "nonlocal" or "global". If a name is bound at ' - 'the\n' - 'module level, it is a global variable. (The variables of the ' - 'module\n' - 'code block are local and global.) If a variable is used in a ' - 'code\n' - 'block but not defined there, it is a *free variable*.\n' - '\n' - 'Each occurrence of a name in the program text refers to the ' - '*binding*\n' - 'of that name established by the following name resolution rules.\n' - '\n' + 'is a code block. The expression read and evaluated by the ' + 'built-in\n' + 'function "input()" is a code block.\n' '\n' - 'Resolution of names\n' - '===================\n' + 'A code block is executed in an *execution frame*. A frame ' + 'contains\n' + 'some administrative information (used for debugging) and ' + 'determines\n' + "where and how execution continues after the code block's execution " + 'has\n' + 'completed.\n' '\n' 'A *scope* defines the visibility of a name within a block. If a ' 'local\n' @@ -6537,22 +5795,71 @@ topics = {'assert': 'The "assert" statement\n' 'blocks\n' 'contained within the defining one, unless a contained block ' 'introduces\n' - 'a different binding for the name.\n' + 'a different binding for the name. The scope of names defined in ' + 'a\n' + 'class block is limited to the class block; it does not extend to ' + 'the\n' + 'code blocks of methods -- this includes generator expressions ' + 'since\n' + 'they are implemented using a function scope. This means that the\n' + 'following will fail:\n' + '\n' + ' class A:\n' + ' a = 42\n' + ' b = list(a + i for i in range(10))\n' '\n' 'When a name is used in a code block, it is resolved using the ' 'nearest\n' 'enclosing scope. The set of all such scopes visible to a code ' 'block\n' - 'is called the block’s *environment*.\n' + "is called the block's *environment*.\n" + '\n' + 'If a name is bound in a block, it is a local variable of that ' + 'block.\n' + 'If a name is bound at the module level, it is a global variable. ' + '(The\n' + 'variables of the module code block are local and global.) If a\n' + 'variable is used in a code block but not defined there, it is a ' + '*free\n' + 'variable*.\n' '\n' 'When a name is not found at all, a "NameError" exception is ' - 'raised. If\n' - 'the current scope is a function scope, and the name refers to a ' - 'local\n' - 'variable that has not yet been bound to a value at the point where ' + 'raised.\n' + 'If the name refers to a local variable that has not been bound, a\n' + '"UnboundLocalError" exception is raised. "UnboundLocalError" is ' + 'a\n' + 'subclass of "NameError".\n' + '\n' + 'The following constructs bind names: formal parameters to ' + 'functions,\n' + '"import" statements, class and function definitions (these bind ' 'the\n' - 'name is used, an "UnboundLocalError" exception is raised.\n' - '"UnboundLocalError" is a subclass of "NameError".\n' + 'class or function name in the defining block), and targets that ' + 'are\n' + 'identifiers if occurring in an assignment, "for" loop header, in ' + 'the\n' + 'second position of an "except" clause header or after "as" in a ' + '"with"\n' + 'statement. The "import" statement of the form "from ... import ' + '*"\n' + 'binds all names defined in the imported module, except those ' + 'beginning\n' + 'with an underscore. This form may only be used at the module ' + 'level.\n' + '\n' + 'A target occurring in a "del" statement is also considered bound ' + 'for\n' + 'this purpose (though the actual semantics are to unbind the ' + 'name). It\n' + 'is illegal to unbind a name that is referenced by an enclosing ' + 'scope;\n' + 'the compiler will report a "SyntaxError".\n' + '\n' + 'Each assignment or import statement occurs within a block defined ' + 'by a\n' + 'class or function definition or at the module level (the ' + 'top-level\n' + 'code block).\n' '\n' 'If a name binding operation occurs anywhere within a code block, ' 'all\n' @@ -6560,41 +5867,52 @@ topics = {'assert': 'The "assert" statement\n' 'the\n' 'current block. This can lead to errors when a name is used within ' 'a\n' - 'block before it is bound. This rule is subtle. Python lacks\n' + 'block before it is bound. This rule is subtle. Python lacks\n' 'declarations and allows name binding operations to occur anywhere\n' 'within a code block. The local variables of a code block can be\n' 'determined by scanning the entire text of the block for name ' 'binding\n' 'operations.\n' '\n' - 'If the "global" statement occurs within a block, all uses of the ' + 'If the global statement occurs within a block, all uses of the ' 'name\n' 'specified in the statement refer to the binding of that name in ' 'the\n' - 'top-level namespace. Names are resolved in the top-level ' - 'namespace by\n' + 'top-level namespace. Names are resolved in the top-level namespace ' + 'by\n' 'searching the global namespace, i.e. the namespace of the module\n' 'containing the code block, and the builtins namespace, the ' 'namespace\n' - 'of the module "builtins". The global namespace is searched ' - 'first. If\n' - 'the name is not found there, the builtins namespace is searched. ' - 'The\n' - '"global" statement must precede all uses of the name.\n' + 'of the module "__builtin__". The global namespace is searched ' + 'first.\n' + 'If the name is not found there, the builtins namespace is ' + 'searched.\n' + 'The global statement must precede all uses of the name.\n' '\n' - 'The "global" statement has the same scope as a name binding ' - 'operation\n' - 'in the same block. If the nearest enclosing scope for a free ' - 'variable\n' - 'contains a global statement, the free variable is treated as a ' - 'global.\n' + 'The builtins namespace associated with the execution of a code ' + 'block\n' + 'is actually found by looking up the name "__builtins__" in its ' + 'global\n' + 'namespace; this should be a dictionary or a module (in the latter ' + 'case\n' + "the module's dictionary is used). By default, when in the " + '"__main__"\n' + 'module, "__builtins__" is the built-in module "__builtin__" (note: ' + 'no\n' + '\'s\'); when in any other module, "__builtins__" is an alias for ' + 'the\n' + 'dictionary of the "__builtin__" module itself. "__builtins__" can ' + 'be\n' + 'set to a user-created dictionary to create a weak form of ' + 'restricted\n' + 'execution.\n' '\n' - 'The "nonlocal" statement causes corresponding names to refer to\n' - 'previously bound variables in the nearest enclosing function ' - 'scope.\n' - '"SyntaxError" is raised at compile time if the given name does ' - 'not\n' - 'exist in any enclosing function scope.\n' + '**CPython implementation detail:** Users should not touch\n' + '"__builtins__"; it is strictly an implementation detail. Users\n' + 'wanting to override values in the builtins namespace should ' + '"import"\n' + 'the "__builtin__" (no \'s\') module and modify its attributes\n' + 'appropriately.\n' '\n' 'The namespace for a module is automatically created the first time ' 'a\n' @@ -6602,128 +5920,79 @@ topics = {'assert': 'The "assert" statement\n' 'called\n' '"__main__".\n' '\n' - 'Class definition blocks and arguments to "exec()" and "eval()" ' - 'are\n' - 'special in the context of name resolution. A class definition is ' - 'an\n' - 'executable statement that may use and define names. These ' - 'references\n' - 'follow the normal rules for name resolution with an exception ' - 'that\n' - 'unbound local variables are looked up in the global namespace. ' - 'The\n' - 'namespace of the class definition becomes the attribute dictionary ' - 'of\n' - 'the class. The scope of names defined in a class block is limited ' - 'to\n' - 'the class block; it does not extend to the code blocks of methods ' - '–\n' - 'this includes comprehensions and generator expressions since they ' - 'are\n' - 'implemented using a function scope. This means that the ' - 'following\n' - 'will fail:\n' + 'The "global" statement has the same scope as a name binding ' + 'operation\n' + 'in the same block. If the nearest enclosing scope for a free ' + 'variable\n' + 'contains a global statement, the free variable is treated as a ' + 'global.\n' '\n' - ' class A:\n' - ' a = 42\n' - ' b = list(a + i for i in range(10))\n' + 'A class definition is an executable statement that may use and ' + 'define\n' + 'names. These references follow the normal rules for name ' + 'resolution.\n' + 'The namespace of the class definition becomes the attribute ' + 'dictionary\n' + 'of the class. Names defined at the class scope are not visible ' + 'in\n' + 'methods.\n' '\n' '\n' - 'Builtins and restricted execution\n' + 'Interaction with dynamic features\n' '=================================\n' '\n' - '**CPython implementation detail:** Users should not touch\n' - '"__builtins__"; it is strictly an implementation detail. Users\n' - 'wanting to override values in the builtins namespace should ' - '"import"\n' - 'the "builtins" module and modify its attributes appropriately.\n' - '\n' - 'The builtins namespace associated with the execution of a code ' - 'block\n' - 'is actually found by looking up the name "__builtins__" in its ' - 'global\n' - 'namespace; this should be a dictionary or a module (in the latter ' - 'case\n' - 'the module’s dictionary is used). By default, when in the ' - '"__main__"\n' - 'module, "__builtins__" is the built-in module "builtins"; when in ' - 'any\n' - 'other module, "__builtins__" is an alias for the dictionary of ' - 'the\n' - '"builtins" module itself.\n' + 'There are several cases where Python statements are illegal when ' + 'used\n' + 'in conjunction with nested scopes that contain free variables.\n' '\n' + 'If a variable is referenced in an enclosing scope, it is illegal ' + 'to\n' + 'delete the name. An error will be reported at compile time.\n' '\n' - 'Interaction with dynamic features\n' - '=================================\n' - '\n' - 'Name resolution of free variables occurs at runtime, not at ' - 'compile\n' - 'time. This means that the following code will print 42:\n' + 'If the wild card form of import --- "import *" --- is used in a\n' + 'function and the function contains or is a nested block with free\n' + 'variables, the compiler will raise a "SyntaxError".\n' '\n' - ' i = 10\n' - ' def f():\n' - ' print(i)\n' - ' i = 42\n' - ' f()\n' + 'If "exec" is used in a function and the function contains or is a\n' + 'nested block with free variables, the compiler will raise a\n' + '"SyntaxError" unless the exec explicitly specifies the local ' + 'namespace\n' + 'for the "exec". (In other words, "exec obj" would be illegal, ' + 'but\n' + '"exec obj in ns" would be legal.)\n' '\n' - 'The "eval()" and "exec()" functions do not have access to the ' - 'full\n' - 'environment for resolving names. Names may be resolved in the ' - 'local\n' - 'and global namespaces of the caller. Free variables are not ' - 'resolved\n' - 'in the nearest enclosing namespace, but in the global namespace. ' - '[1]\n' - 'The "exec()" and "eval()" functions have optional arguments to\n' + 'The "eval()", "execfile()", and "input()" functions and the ' + '"exec"\n' + 'statement do not have access to the full environment for ' + 'resolving\n' + 'names. Names may be resolved in the local and global namespaces ' + 'of\n' + 'the caller. Free variables are not resolved in the nearest ' + 'enclosing\n' + 'namespace, but in the global namespace. [1] The "exec" statement ' + 'and\n' + 'the "eval()" and "execfile()" functions have optional arguments ' + 'to\n' 'override the global and local namespace. If only one namespace ' 'is\n' 'specified, it is used for both.\n', - 'nonlocal': 'The "nonlocal" statement\n' - '************************\n' - '\n' - ' nonlocal_stmt ::= "nonlocal" identifier ("," identifier)*\n' - '\n' - 'The "nonlocal" statement causes the listed identifiers to refer ' - 'to\n' - 'previously bound variables in the nearest enclosing scope ' - 'excluding\n' - 'globals. This is important because the default behavior for ' - 'binding is\n' - 'to search the local namespace first. The statement allows\n' - 'encapsulated code to rebind variables outside of the local ' - 'scope\n' - 'besides the global (module) scope.\n' - '\n' - 'Names listed in a "nonlocal" statement, unlike those listed in ' - 'a\n' - '"global" statement, must refer to pre-existing bindings in an\n' - 'enclosing scope (the scope in which a new binding should be ' - 'created\n' - 'cannot be determined unambiguously).\n' - '\n' - 'Names listed in a "nonlocal" statement must not collide with ' - 'pre-\n' - 'existing bindings in the local scope.\n' - '\n' - 'See also:\n' - '\n' - ' **PEP 3104** - Access to Names in Outer Scopes\n' - ' The specification for the "nonlocal" statement.\n', - 'numbers': 'Numeric literals\n' + 'numbers': '\n' + 'Numeric literals\n' '****************\n' '\n' - 'There are three types of numeric literals: integers, floating ' - 'point\n' - 'numbers, and imaginary numbers. There are no complex literals\n' - '(complex numbers can be formed by adding a real number and an\n' - 'imaginary number).\n' + 'There are four types of numeric literals: plain integers, long\n' + 'integers, floating point numbers, and imaginary numbers. There ' + 'are no\n' + 'complex literals (complex numbers can be formed by adding a real\n' + 'number and an imaginary number).\n' '\n' 'Note that numeric literals do not include a sign; a phrase like ' '"-1"\n' - 'is actually an expression composed of the unary operator ‘"-"‘ ' + 'is actually an expression composed of the unary operator \'"-"\' ' 'and the\n' 'literal "1".\n', - 'numeric-types': 'Emulating numeric types\n' + 'numeric-types': '\n' + 'Emulating numeric types\n' '***********************\n' '\n' 'The following methods can be defined to emulate numeric ' @@ -6737,8 +6006,6 @@ topics = {'assert': 'The "assert" statement\n' 'object.__add__(self, other)\n' 'object.__sub__(self, other)\n' 'object.__mul__(self, other)\n' - 'object.__matmul__(self, other)\n' - 'object.__truediv__(self, other)\n' 'object.__floordiv__(self, other)\n' 'object.__mod__(self, other)\n' 'object.__divmod__(self, other)\n' @@ -6751,21 +6018,21 @@ topics = {'assert': 'The "assert" statement\n' '\n' ' These methods are called to implement the binary ' 'arithmetic\n' - ' operations ("+", "-", "*", "@", "/", "//", "%", ' - '"divmod()",\n' - ' "pow()", "**", "<<", ">>", "&", "^", "|"). For ' - 'instance, to\n' - ' evaluate the expression "x + y", where *x* is an ' - 'instance of a\n' - ' class that has an "__add__()" method, "x.__add__(y)" is ' - 'called.\n' - ' The "__divmod__()" method should be the equivalent to ' - 'using\n' - ' "__floordiv__()" and "__mod__()"; it should not be ' - 'related to\n' - ' "__truediv__()". Note that "__pow__()" should be ' - 'defined to accept\n' - ' an optional third argument if the ternary version of the ' + ' operations ("+", "-", "*", "//", "%", "divmod()", ' + '"pow()", "**",\n' + ' "<<", ">>", "&", "^", "|"). For instance, to evaluate ' + 'the\n' + ' expression "x + y", where *x* is an instance of a class ' + 'that has an\n' + ' "__add__()" method, "x.__add__(y)" is called. The ' + '"__divmod__()"\n' + ' method should be the equivalent to using ' + '"__floordiv__()" and\n' + ' "__mod__()"; it should not be related to "__truediv__()" ' + '(described\n' + ' below). Note that "__pow__()" should be defined to ' + 'accept an\n' + ' optional third argument if the ternary version of the ' 'built-in\n' ' "pow()" function is to be supported.\n' '\n' @@ -6773,10 +6040,23 @@ topics = {'assert': 'The "assert" statement\n' 'with the\n' ' supplied arguments, it should return "NotImplemented".\n' '\n' + 'object.__div__(self, other)\n' + 'object.__truediv__(self, other)\n' + '\n' + ' The division operator ("/") is implemented by these ' + 'methods. The\n' + ' "__truediv__()" method is used when ' + '"__future__.division" is in\n' + ' effect, otherwise "__div__()" is used. If only one of ' + 'these two\n' + ' methods is defined, the object will not support division ' + 'in the\n' + ' alternate context; "TypeError" will be raised instead.\n' + '\n' 'object.__radd__(self, other)\n' 'object.__rsub__(self, other)\n' 'object.__rmul__(self, other)\n' - 'object.__rmatmul__(self, other)\n' + 'object.__rdiv__(self, other)\n' 'object.__rtruediv__(self, other)\n' 'object.__rfloordiv__(self, other)\n' 'object.__rmod__(self, other)\n' @@ -6790,15 +6070,15 @@ topics = {'assert': 'The "assert" statement\n' '\n' ' These methods are called to implement the binary ' 'arithmetic\n' - ' operations ("+", "-", "*", "@", "/", "//", "%", ' - '"divmod()",\n' - ' "pow()", "**", "<<", ">>", "&", "^", "|") with reflected ' - '(swapped)\n' - ' operands. These functions are only called if the left ' - 'operand does\n' - ' not support the corresponding operation [3] and the ' - 'operands are of\n' - ' different types. [4] For instance, to evaluate the ' + ' operations ("+", "-", "*", "/", "%", "divmod()", ' + '"pow()", "**",\n' + ' "<<", ">>", "&", "^", "|") with reflected (swapped) ' + 'operands.\n' + ' These functions are only called if the left operand does ' + 'not\n' + ' support the corresponding operation and the operands are ' + 'of\n' + ' different types. [2] For instance, to evaluate the ' 'expression "x -\n' ' y", where *y* is an instance of a class that has an ' '"__rsub__()"\n' @@ -6810,20 +6090,20 @@ topics = {'assert': 'The "assert" statement\n' '"__rpow__()" (the\n' ' coercion rules would become too complicated).\n' '\n' - ' Note: If the right operand’s type is a subclass of the ' + " Note: If the right operand's type is a subclass of the " 'left\n' - ' operand’s type and that subclass provides the ' + " operand's type and that subclass provides the " 'reflected method\n' ' for the operation, this method will be called before ' 'the left\n' - ' operand’s non-reflected method. This behavior allows ' + " operand's non-reflected method. This behavior allows " 'subclasses\n' - ' to override their ancestors’ operations.\n' + " to override their ancestors' operations.\n" '\n' 'object.__iadd__(self, other)\n' 'object.__isub__(self, other)\n' 'object.__imul__(self, other)\n' - 'object.__imatmul__(self, other)\n' + 'object.__idiv__(self, other)\n' 'object.__itruediv__(self, other)\n' 'object.__ifloordiv__(self, other)\n' 'object.__imod__(self, other)\n' @@ -6836,31 +6116,26 @@ topics = {'assert': 'The "assert" statement\n' '\n' ' These methods are called to implement the augmented ' 'arithmetic\n' - ' assignments ("+=", "-=", "*=", "@=", "/=", "//=", "%=", ' - '"**=",\n' - ' "<<=", ">>=", "&=", "^=", "|="). These methods should ' - 'attempt to\n' - ' do the operation in-place (modifying *self*) and return ' - 'the result\n' - ' (which could be, but does not have to be, *self*). If a ' - 'specific\n' - ' method is not defined, the augmented assignment falls ' - 'back to the\n' - ' normal methods. For instance, if *x* is an instance of ' - 'a class\n' - ' with an "__iadd__()" method, "x += y" is equivalent to ' - '"x =\n' - ' x.__iadd__(y)" . Otherwise, "x.__add__(y)" and ' - '"y.__radd__(x)" are\n' - ' considered, as with the evaluation of "x + y". In ' - 'certain\n' - ' situations, augmented assignment can result in ' - 'unexpected errors\n' - ' (see Why does a_tuple[i] += [‘item’] raise an exception ' - 'when the\n' - ' addition works?), but this behavior is in fact part of ' - 'the data\n' - ' model.\n' + ' assignments ("+=", "-=", "*=", "/=", "//=", "%=", "**=", ' + '"<<=",\n' + ' ">>=", "&=", "^=", "|="). These methods should attempt ' + 'to do the\n' + ' operation in-place (modifying *self*) and return the ' + 'result (which\n' + ' could be, but does not have to be, *self*). If a ' + 'specific method\n' + ' is not defined, the augmented assignment falls back to ' + 'the normal\n' + ' methods. For instance, to execute the statement "x += ' + 'y", where\n' + ' *x* is an instance of a class that has an "__iadd__()" ' + 'method,\n' + ' "x.__iadd__(y)" is called. If *x* is an instance of a ' + 'class that\n' + ' does not define a "__iadd__()" method, "x.__add__(y)" ' + 'and\n' + ' "y.__radd__(x)" are considered, as with the evaluation ' + 'of "x + y".\n' '\n' 'object.__neg__(self)\n' 'object.__pos__(self)\n' @@ -6873,94 +6148,93 @@ topics = {'assert': 'The "assert" statement\n' '\n' 'object.__complex__(self)\n' 'object.__int__(self)\n' + 'object.__long__(self)\n' 'object.__float__(self)\n' '\n' ' Called to implement the built-in functions "complex()", ' - '"int()" and\n' - ' "float()". Should return a value of the appropriate ' - 'type.\n' + '"int()",\n' + ' "long()", and "float()". Should return a value of the ' + 'appropriate\n' + ' type.\n' + '\n' + 'object.__oct__(self)\n' + 'object.__hex__(self)\n' + '\n' + ' Called to implement the built-in functions "oct()" and ' + '"hex()".\n' + ' Should return a string value.\n' '\n' 'object.__index__(self)\n' '\n' - ' Called to implement "operator.index()", and whenever ' - 'Python needs\n' - ' to losslessly convert the numeric object to an integer ' - 'object (such\n' - ' as in slicing, or in the built-in "bin()", "hex()" and ' - '"oct()"\n' - ' functions). Presence of this method indicates that the ' - 'numeric\n' - ' object is an integer type. Must return an integer.\n' - '\n' - ' If "__int__()", "__float__()" and "__complex__()" are ' - 'not defined\n' - ' then corresponding built-in functions "int()", "float()" ' - 'and\n' - ' "complex()" fall back to "__index__()".\n' - '\n' - 'object.__round__(self[, ndigits])\n' - 'object.__trunc__(self)\n' - 'object.__floor__(self)\n' - 'object.__ceil__(self)\n' - '\n' - ' Called to implement the built-in function "round()" and ' - '"math"\n' - ' functions "trunc()", "floor()" and "ceil()". Unless ' - '*ndigits* is\n' - ' passed to "__round__()" all these methods should return ' - 'the value\n' - ' of the object truncated to an "Integral" (typically an ' - '"int").\n' - '\n' - ' If "__int__()" is not defined then the built-in function ' - '"int()"\n' - ' falls back to "__trunc__()".\n', - 'objects': 'Objects, values and types\n' + ' Called to implement "operator.index()". Also called ' + 'whenever\n' + ' Python needs an integer object (such as in slicing). ' + 'Must return\n' + ' an integer (int or long).\n' + '\n' + ' New in version 2.5.\n' + '\n' + 'object.__coerce__(self, other)\n' + '\n' + ' Called to implement "mixed-mode" numeric arithmetic. ' + 'Should either\n' + ' return a 2-tuple containing *self* and *other* converted ' + 'to a\n' + ' common numeric type, or "None" if conversion is ' + 'impossible. When\n' + ' the common type would be the type of "other", it is ' + 'sufficient to\n' + ' return "None", since the interpreter will also ask the ' + 'other object\n' + ' to attempt a coercion (but sometimes, if the ' + 'implementation of the\n' + ' other type cannot be changed, it is useful to do the ' + 'conversion to\n' + ' the other type here). A return value of ' + '"NotImplemented" is\n' + ' equivalent to returning "None".\n', + 'objects': '\n' + 'Objects, values and types\n' '*************************\n' '\n' - '*Objects* are Python’s abstraction for data. All data in a ' + "*Objects* are Python's abstraction for data. All data in a " 'Python\n' 'program is represented by objects or by relations between ' 'objects. (In\n' - 'a sense, and in conformance to Von Neumann’s model of a “stored\n' - 'program computer,” code is also represented by objects.)\n' + 'a sense, and in conformance to Von Neumann\'s model of a "stored\n' + 'program computer," code is also represented by objects.)\n' '\n' - 'Every object has an identity, a type and a value. An object’s\n' + "Every object has an identity, a type and a value. An object's\n" '*identity* never changes once it has been created; you may think ' 'of it\n' - 'as the object’s address in memory. The ‘"is"’ operator compares ' - 'the\n' + 'as the object\'s address in memory. The \'"is"\' operator ' + 'compares the\n' 'identity of two objects; the "id()" function returns an integer\n' - 'representing its identity.\n' - '\n' - '**CPython implementation detail:** For CPython, "id(x)" is the ' - 'memory\n' - 'address where "x" is stored.\n' - '\n' - 'An object’s type determines the operations that the object ' - 'supports\n' - '(e.g., “does it have a length?”) and also defines the possible ' - 'values\n' - 'for objects of that type. The "type()" function returns an ' - 'object’s\n' - 'type (which is an object itself). Like its identity, an ' - 'object’s\n' - '*type* is also unchangeable. [1]\n' - '\n' - 'The *value* of some objects can change. Objects whose value can\n' - 'change are said to be *mutable*; objects whose value is ' - 'unchangeable\n' - 'once they are created are called *immutable*. (The value of an\n' - 'immutable container object that contains a reference to a ' - 'mutable\n' - 'object can change when the latter’s value is changed; however ' - 'the\n' - 'container is still considered immutable, because the collection ' - 'of\n' + 'representing its identity (currently implemented as its address). ' + 'An\n' + "object's *type* is also unchangeable. [1] An object's type " + 'determines\n' + 'the operations that the object supports (e.g., "does it have a\n' + 'length?") and also defines the possible values for objects of ' + 'that\n' + 'type. The "type()" function returns an object\'s type (which is ' + 'an\n' + 'object itself). The *value* of some objects can change. ' + 'Objects\n' + 'whose value can change are said to be *mutable*; objects whose ' + 'value\n' + 'is unchangeable once they are created are called *immutable*. ' + '(The\n' + 'value of an immutable container object that contains a reference ' + 'to a\n' + "mutable object can change when the latter's value is changed; " + 'however\n' + 'the container is still considered immutable, because the ' + 'collection of\n' 'objects it contains cannot be changed. So, immutability is not\n' 'strictly the same as having an unchangeable value, it is more ' 'subtle.)\n' - 'An object’s mutability is determined by its type; for instance,\n' + "An object's mutability is determined by its type; for instance,\n" 'numbers, strings and tuples are immutable, while dictionaries ' 'and\n' 'lists are mutable.\n' @@ -6968,9 +6242,9 @@ topics = {'assert': 'The "assert" statement\n' 'Objects are never explicitly destroyed; however, when they ' 'become\n' 'unreachable they may be garbage-collected. An implementation is\n' - 'allowed to postpone garbage collection or omit it altogether — it ' - 'is a\n' - 'matter of implementation quality how garbage collection is\n' + 'allowed to postpone garbage collection or omit it altogether --- ' + 'it is\n' + 'a matter of implementation quality how garbage collection is\n' 'implemented, as long as no objects are collected that are still\n' 'reachable.\n' '\n' @@ -6987,17 +6261,16 @@ topics = {'assert': 'The "assert" statement\n' 'implementations act differently and CPython may change. Do not ' 'depend\n' 'on immediate finalization of objects when they become unreachable ' - '(so\n' - 'you should always close files explicitly).\n' + '(ex:\n' + 'always close files).\n' '\n' - 'Note that the use of the implementation’s tracing or debugging\n' + "Note that the use of the implementation's tracing or debugging\n" 'facilities may keep objects alive that would normally be ' 'collectable.\n' - 'Also note that catching an exception with a ‘"try"…"except"’ ' - 'statement\n' - 'may keep objects alive.\n' + 'Also note that catching an exception with a \'"try"..."except"\'\n' + 'statement may keep objects alive.\n' '\n' - 'Some objects contain references to “external” resources such as ' + 'Some objects contain references to "external" resources such as ' 'open\n' 'files or windows. It is understood that these resources are ' 'freed\n' @@ -7008,13 +6281,13 @@ topics = {'assert': 'The "assert" statement\n' 'release the external resource, usually a "close()" method. ' 'Programs\n' 'are strongly recommended to explicitly close such objects. The\n' - '‘"try"…"finally"’ statement and the ‘"with"’ statement provide\n' - 'convenient ways to do this.\n' + '\'"try"..."finally"\' statement provides a convenient way to do ' + 'this.\n' '\n' 'Some objects contain references to other objects; these are ' 'called\n' '*containers*. Examples of containers are tuples, lists and\n' - 'dictionaries. The references are part of a container’s value. ' + "dictionaries. The references are part of a container's value. " 'In\n' 'most cases, when we talk about the value of a container, we imply ' 'the\n' @@ -7043,38 +6316,34 @@ topics = {'assert': 'The "assert" statement\n' 'created empty lists. (Note that "c = d = []" assigns the same ' 'object\n' 'to both "c" and "d".)\n', - 'operator-summary': 'Operator precedence\n' + 'operator-summary': '\n' + 'Operator precedence\n' '*******************\n' '\n' - 'The following table summarizes the operator precedence ' - 'in Python, from\n' - 'lowest precedence (least binding) to highest precedence ' - '(most\n' - 'binding). Operators in the same box have the same ' + 'The following table summarizes the operator precedences ' + 'in Python,\n' + 'from lowest precedence (least binding) to highest ' + 'precedence (most\n' + 'binding). Operators in the same box have the same ' 'precedence. Unless\n' 'the syntax is explicitly given, operators are binary. ' 'Operators in\n' 'the same box group left to right (except for ' - 'exponentiation, which\n' - 'groups from right to left).\n' - '\n' - 'Note that comparisons, membership tests, and identity ' - 'tests, all have\n' - 'the same precedence and have a left-to-right chaining ' - 'feature as\n' - 'described in the Comparisons section.\n' + 'comparisons, including\n' + 'tests, which all have the same precedence and chain from ' + 'left to right\n' + '--- see section Comparisons --- and exponentiation, ' + 'which groups from\n' + 'right to left).\n' '\n' '+-------------------------------------------------+---------------------------------------+\n' '| Operator | ' 'Description |\n' - '|=================================================|=======================================|\n' - '| ":=" | ' - 'Assignment expression |\n' - '+-------------------------------------------------+---------------------------------------+\n' + '+=================================================+=======================================+\n' '| "lambda" | ' 'Lambda expression |\n' '+-------------------------------------------------+---------------------------------------+\n' - '| "if" – "else" | ' + '| "if" -- "else" | ' 'Conditional expression |\n' '+-------------------------------------------------+---------------------------------------+\n' '| "or" | ' @@ -7088,7 +6357,7 @@ topics = {'assert': 'The "assert" statement\n' '+-------------------------------------------------+---------------------------------------+\n' '| "in", "not in", "is", "is not", "<", "<=", ">", | ' 'Comparisons, including membership |\n' - '| ">=", "!=", "==" | ' + '| ">=", "<>", "!=", "==" | ' 'tests and identity tests |\n' '+-------------------------------------------------+---------------------------------------+\n' '| "|" | ' @@ -7106,38 +6375,41 @@ topics = {'assert': 'The "assert" statement\n' '| "+", "-" | ' 'Addition and subtraction |\n' '+-------------------------------------------------+---------------------------------------+\n' - '| "*", "@", "/", "//", "%" | ' - 'Multiplication, matrix |\n' - '| | ' - 'multiplication, division, floor |\n' + '| "*", "/", "//", "%" | ' + 'Multiplication, division, remainder |\n' '| | ' - 'division, remainder [5] |\n' + '[7] |\n' '+-------------------------------------------------+---------------------------------------+\n' '| "+x", "-x", "~x" | ' 'Positive, negative, bitwise NOT |\n' '+-------------------------------------------------+---------------------------------------+\n' '| "**" | ' - 'Exponentiation [6] |\n' - '+-------------------------------------------------+---------------------------------------+\n' - '| "await" "x" | ' - 'Await expression |\n' + 'Exponentiation [8] |\n' '+-------------------------------------------------+---------------------------------------+\n' '| "x[index]", "x[index:index]", | ' 'Subscription, slicing, call, |\n' '| "x(arguments...)", "x.attribute" | ' 'attribute reference |\n' '+-------------------------------------------------+---------------------------------------+\n' - '| "(expressions...)", "[expressions...]", "{key: | ' - 'Binding or parenthesized expression, |\n' - '| value...}", "{expressions...}" | list ' - 'display, dictionary display, set |\n' + '| "(expressions...)", "[expressions...]", "{key: | ' + 'Binding or tuple display, list |\n' + '| value...}", "`expressions...`" | ' + 'display, dictionary display, string |\n' '| | ' - 'display |\n' + 'conversion |\n' '+-------------------------------------------------+---------------------------------------+\n' '\n' '-[ Footnotes ]-\n' '\n' - '[1] While "abs(x%y) < abs(y)" is true mathematically, ' + '[1] In Python 2.3 and later releases, a list ' + 'comprehension "leaks"\n' + ' the control variables of each "for" it contains into ' + 'the\n' + ' containing scope. However, this behavior is ' + 'deprecated, and\n' + ' relying on it will not work in Python 3.\n' + '\n' + '[2] While "abs(x%y) < abs(y)" is true mathematically, ' 'for floats\n' ' it may not be true numerically due to roundoff. For ' 'example, and\n' @@ -7156,20 +6428,20 @@ topics = {'assert': 'The "assert" statement\n' ' Which approach is more appropriate depends on the ' 'application.\n' '\n' - '[2] If x is very close to an exact integer multiple of ' - 'y, it’s\n' - ' possible for "x//y" to be one larger than ' - '"(x-x%y)//y" due to\n' + '[3] If x is very close to an exact integer multiple of ' + "y, it's\n" + ' possible for "floor(x/y)" to be one larger than ' + '"(x-x%y)/y" due to\n' ' rounding. In such cases, Python returns the latter ' 'result, in\n' ' order to preserve that "divmod(x,y)[0] * y + x % y" ' 'be very close\n' ' to "x".\n' '\n' - '[3] The Unicode standard distinguishes between *code ' + '[4] The Unicode standard distinguishes between *code ' 'points* (e.g.\n' - ' U+0041) and *abstract characters* (e.g. “LATIN ' - 'CAPITAL LETTER A”).\n' + ' U+0041) and *abstract characters* (e.g. "LATIN ' + 'CAPITAL LETTER A").\n' ' While most abstract characters in Unicode are only ' 'represented\n' ' using one code point, there is a number of abstract ' @@ -7177,8 +6449,8 @@ topics = {'assert': 'The "assert" statement\n' ' that can in addition be represented using a sequence ' 'of more than\n' ' one code point. For example, the abstract character ' - '“LATIN\n' - ' CAPITAL LETTER C WITH CEDILLA” can be represented as ' + '"LATIN\n' + ' CAPITAL LETTER C WITH CEDILLA" can be represented as ' 'a single\n' ' *precomposed character* at code position U+00C7, or ' 'as a sequence\n' @@ -7188,22 +6460,34 @@ topics = {'assert': 'The "assert" statement\n' 'code position\n' ' U+0327 (COMBINING CEDILLA).\n' '\n' - ' The comparison operators on strings compare at the ' - 'level of\n' - ' Unicode code points. This may be counter-intuitive ' - 'to humans. For\n' - ' example, ""\\u00C7" == "\\u0043\\u0327"" is "False", ' - 'even though both\n' - ' strings represent the same abstract character “LATIN ' - 'CAPITAL\n' - ' LETTER C WITH CEDILLA”.\n' + ' The comparison operators on unicode strings compare ' + 'at the level\n' + ' of Unicode code points. This may be ' + 'counter-intuitive to humans.\n' + ' For example, "u"\\u00C7" == u"\\u0043\\u0327"" is ' + '"False", even\n' + ' though both strings represent the same abstract ' + 'character "LATIN\n' + ' CAPITAL LETTER C WITH CEDILLA".\n' '\n' ' To compare strings at the level of abstract ' 'characters (that is,\n' ' in a way intuitive to humans), use ' '"unicodedata.normalize()".\n' '\n' - '[4] Due to automatic garbage-collection, free lists, and ' + '[5] Earlier versions of Python used lexicographic ' + 'comparison of\n' + ' the sorted (key, value) lists, but this was very ' + 'expensive for the\n' + ' common case of comparing for equality. An even ' + 'earlier version of\n' + ' Python compared dictionaries by identity only, but ' + 'this caused\n' + ' surprises because people expected to be able to test ' + 'a dictionary\n' + ' for emptiness by comparing it to "{}".\n' + '\n' + '[6] Due to automatic garbage-collection, free lists, and ' 'the\n' ' dynamic nature of descriptors, you may notice ' 'seemingly unusual\n' @@ -7213,29 +6497,30 @@ topics = {'assert': 'The "assert" statement\n' 'constants.\n' ' Check their documentation for more info.\n' '\n' - '[5] The "%" operator is also used for string formatting; ' + '[7] The "%" operator is also used for string formatting; ' 'the same\n' ' precedence applies.\n' '\n' - '[6] The power operator "**" binds less tightly than an ' + '[8] The power operator "**" binds less tightly than an ' 'arithmetic\n' ' or bitwise unary operator on its right, that is, ' '"2**-1" is "0.5".\n', - 'pass': 'The "pass" statement\n' + 'pass': '\n' + 'The "pass" statement\n' '********************\n' '\n' ' pass_stmt ::= "pass"\n' '\n' - '"pass" is a null operation — when it is executed, nothing happens. ' - 'It\n' - 'is useful as a placeholder when a statement is required ' - 'syntactically,\n' - 'but no code needs to be executed, for example:\n' + '"pass" is a null operation --- when it is executed, nothing ' + 'happens.\n' + 'It is useful as a placeholder when a statement is required\n' + 'syntactically, but no code needs to be executed, for example:\n' '\n' ' def f(arg): pass # a function that does nothing (yet)\n' '\n' ' class C: pass # a class with no methods (yet)\n', - 'power': 'The power operator\n' + 'power': '\n' + 'The power operator\n' '******************\n' '\n' 'The power operator binds more tightly than unary operators on its\n' @@ -7243,7 +6528,7 @@ topics = {'assert': 'The "assert" statement\n' 'The\n' 'syntax is:\n' '\n' - ' power ::= (await_expr | primary) ["**" u_expr]\n' + ' power ::= primary ["**" u_expr]\n' '\n' 'Thus, in an unparenthesized sequence of power and unary operators, ' 'the\n' @@ -7256,125 +6541,146 @@ topics = {'assert': 'The "assert" statement\n' 'argument\n' 'raised to the power of its right argument. The numeric arguments ' 'are\n' - 'first converted to a common type, and the result is of that type.\n' + 'first converted to a common type. The result type is that of the\n' + 'arguments after coercion.\n' '\n' - 'For int operands, the result has the same type as the operands ' - 'unless\n' - 'the second argument is negative; in that case, all arguments are\n' - 'converted to float and a float result is delivered. For example,\n' - '"10**2" returns "100", but "10**-2" returns "0.01".\n' + 'With mixed operand types, the coercion rules for binary arithmetic\n' + 'operators apply. For int and long int operands, the result has the\n' + 'same type as the operands (after coercion) unless the second ' + 'argument\n' + 'is negative; in that case, all arguments are converted to float and ' + 'a\n' + 'float result is delivered. For example, "10**2" returns "100", but\n' + '"10**-2" returns "0.01". (This last feature was added in Python ' + '2.2.\n' + 'In Python 2.1 and before, if both arguments were of integer types ' + 'and\n' + 'the second argument was negative, an exception was raised).\n' '\n' 'Raising "0.0" to a negative power results in a ' '"ZeroDivisionError".\n' - 'Raising a negative number to a fractional power results in a ' - '"complex"\n' - 'number. (In earlier versions it raised a "ValueError".)\n', - 'raise': 'The "raise" statement\n' + 'Raising a negative number to a fractional power results in a\n' + '"ValueError".\n', + 'print': '\n' + 'The "print" statement\n' '*********************\n' '\n' - ' raise_stmt ::= "raise" [expression ["from" expression]]\n' - '\n' - 'If no expressions are present, "raise" re-raises the last ' - 'exception\n' - 'that was active in the current scope. If no exception is active ' - 'in\n' - 'the current scope, a "RuntimeError" exception is raised indicating\n' - 'that this is an error.\n' - '\n' - 'Otherwise, "raise" evaluates the first expression as the exception\n' - 'object. It must be either a subclass or an instance of\n' - '"BaseException". If it is a class, the exception instance will be\n' - 'obtained when needed by instantiating the class with no arguments.\n' + ' print_stmt ::= "print" ([expression ("," expression)* [","]]\n' + ' | ">>" expression [("," expression)+ [","]])\n' '\n' - 'The *type* of the exception is the exception instance’s class, the\n' - '*value* is the instance itself.\n' - '\n' - 'A traceback object is normally created automatically when an ' - 'exception\n' - 'is raised and attached to it as the "__traceback__" attribute, ' - 'which\n' - 'is writable. You can create an exception and set your own traceback ' - 'in\n' - 'one step using the "with_traceback()" exception method (which ' - 'returns\n' - 'the same exception instance, with its traceback set to its ' - 'argument),\n' - 'like so:\n' + '"print" evaluates each expression in turn and writes the resulting\n' + 'object to standard output (see below). If an object is not a ' + 'string,\n' + 'it is first converted to a string using the rules for string\n' + 'conversions. The (resulting or original) string is then written. ' + 'A\n' + 'space is written before each object is (converted and) written, ' + 'unless\n' + 'the output system believes it is positioned at the beginning of a\n' + 'line. This is the case (1) when no characters have yet been ' + 'written\n' + 'to standard output, (2) when the last character written to ' + 'standard\n' + 'output is a whitespace character except "\' \'", or (3) when the ' + 'last\n' + 'write operation on standard output was not a "print" statement. ' + '(In\n' + 'some cases it may be functional to write an empty string to ' + 'standard\n' + 'output for this reason.)\n' '\n' - ' raise Exception("foo occurred").with_traceback(tracebackobj)\n' + 'Note: Objects which act like file objects but which are not the\n' + ' built-in file objects often do not properly emulate this aspect ' + 'of\n' + " the file object's behavior, so it is best not to rely on this.\n" '\n' - 'The "from" clause is used for exception chaining: if given, the ' - 'second\n' - '*expression* must be another exception class or instance, which ' - 'will\n' - 'then be attached to the raised exception as the "__cause__" ' - 'attribute\n' - '(which is writable). If the raised exception is not handled, both\n' - 'exceptions will be printed:\n' + 'A "\'\\n\'" character is written at the end, unless the "print" ' + 'statement\n' + 'ends with a comma. This is the only action if the statement ' + 'contains\n' + 'just the keyword "print".\n' '\n' - ' >>> try:\n' - ' ... print(1 / 0)\n' - ' ... except Exception as exc:\n' - ' ... raise RuntimeError("Something bad happened") from exc\n' - ' ...\n' - ' Traceback (most recent call last):\n' - ' File "<stdin>", line 2, in <module>\n' - ' ZeroDivisionError: division by zero\n' + 'Standard output is defined as the file object named "stdout" in ' + 'the\n' + 'built-in module "sys". If no such object exists, or if it does ' + 'not\n' + 'have a "write()" method, a "RuntimeError" exception is raised.\n' '\n' - ' The above exception was the direct cause of the following ' - 'exception:\n' + '"print" also has an extended form, defined by the second portion ' + 'of\n' + 'the syntax described above. This form is sometimes referred to as\n' + '""print" chevron." In this form, the first expression after the ' + '">>"\n' + 'must evaluate to a "file-like" object, specifically an object that ' + 'has\n' + 'a "write()" method as described above. With this extended form, ' + 'the\n' + 'subsequent expressions are printed to this file object. If the ' + 'first\n' + 'expression evaluates to "None", then "sys.stdout" is used as the ' + 'file\n' + 'for output.\n', + 'raise': '\n' + 'The "raise" statement\n' + '*********************\n' '\n' - ' Traceback (most recent call last):\n' - ' File "<stdin>", line 4, in <module>\n' - ' RuntimeError: Something bad happened\n' + ' raise_stmt ::= "raise" [expression ["," expression ["," ' + 'expression]]]\n' '\n' - 'A similar mechanism works implicitly if an exception is raised ' - 'inside\n' - 'an exception handler or a "finally" clause: the previous exception ' + 'If no expressions are present, "raise" re-raises the last ' + 'exception\n' + 'that was active in the current scope. If no exception is active ' + 'in\n' + 'the current scope, a "TypeError" exception is raised indicating ' + 'that\n' + 'this is an error (if running under IDLE, a "Queue.Empty" exception ' 'is\n' - 'then attached as the new exception’s "__context__" attribute:\n' + 'raised instead).\n' '\n' - ' >>> try:\n' - ' ... print(1 / 0)\n' - ' ... except:\n' - ' ... raise RuntimeError("Something bad happened")\n' - ' ...\n' - ' Traceback (most recent call last):\n' - ' File "<stdin>", line 2, in <module>\n' - ' ZeroDivisionError: division by zero\n' + 'Otherwise, "raise" evaluates the expressions to get three objects,\n' + 'using "None" as the value of omitted expressions. The first two\n' + 'objects are used to determine the *type* and *value* of the ' + 'exception.\n' '\n' - ' During handling of the above exception, another exception ' - 'occurred:\n' - '\n' - ' Traceback (most recent call last):\n' - ' File "<stdin>", line 4, in <module>\n' - ' RuntimeError: Something bad happened\n' - '\n' - 'Exception chaining can be explicitly suppressed by specifying ' - '"None"\n' - 'in the "from" clause:\n' + 'If the first object is an instance, the type of the exception is ' + 'the\n' + 'class of the instance, the instance itself is the value, and the\n' + 'second object must be "None".\n' '\n' - ' >>> try:\n' - ' ... print(1 / 0)\n' - ' ... except:\n' - ' ... raise RuntimeError("Something bad happened") from None\n' - ' ...\n' - ' Traceback (most recent call last):\n' - ' File "<stdin>", line 4, in <module>\n' - ' RuntimeError: Something bad happened\n' + 'If the first object is a class, it becomes the type of the ' + 'exception.\n' + 'The second object is used to determine the exception value: If it ' + 'is\n' + 'an instance of the class, the instance becomes the exception value. ' + 'If\n' + 'the second object is a tuple, it is used as the argument list for ' + 'the\n' + 'class constructor; if it is "None", an empty argument list is ' + 'used,\n' + 'and any other object is treated as a single argument to the\n' + 'constructor. The instance so created by calling the constructor ' + 'is\n' + 'used as the exception value.\n' + '\n' + 'If a third object is present and not "None", it must be a ' + 'traceback\n' + 'object (see section The standard type hierarchy), and it is\n' + 'substituted instead of the current location as the place where the\n' + 'exception occurred. If the third object is present and not a\n' + 'traceback object or "None", a "TypeError" exception is raised. ' + 'The\n' + 'three-expression form of "raise" is useful to re-raise an ' + 'exception\n' + 'transparently in an except clause, but "raise" with no expressions\n' + 'should be preferred if the exception to be re-raised was the most\n' + 'recently active exception in the current scope.\n' '\n' 'Additional information on exceptions can be found in section\n' 'Exceptions, and information about handling exceptions is in ' 'section\n' - 'The try statement.\n' - '\n' - 'Changed in version 3.3: "None" is now permitted as "Y" in "raise X\n' - 'from Y".\n' - '\n' - 'New in version 3.3: The "__suppress_context__" attribute to ' - 'suppress\n' - 'automatic display of the exception context.\n', - 'return': 'The "return" statement\n' + 'The try statement.\n', + 'return': '\n' + 'The "return" statement\n' '**********************\n' '\n' ' return_stmt ::= "return" [expression_list]\n' @@ -7396,20 +6702,13 @@ topics = {'assert': 'The "assert" statement\n' 'the\n' 'function.\n' '\n' - 'In a generator function, the "return" statement indicates that ' - 'the\n' - 'generator is done and will cause "StopIteration" to be raised. ' - 'The\n' - 'returned value (if any) is used as an argument to construct\n' - '"StopIteration" and becomes the "StopIteration.value" attribute.\n' - '\n' - 'In an asynchronous generator function, an empty "return" ' - 'statement\n' - 'indicates that the asynchronous generator is done and will cause\n' - '"StopAsyncIteration" to be raised. A non-empty "return" statement ' - 'is\n' - 'a syntax error in an asynchronous generator function.\n', - 'sequence-types': 'Emulating container types\n' + 'In a generator function, the "return" statement is not allowed to\n' + 'include an "expression_list". In that context, a bare "return"\n' + 'indicates that the generator is done and will cause ' + '"StopIteration" to\n' + 'be raised.\n', + 'sequence-types': '\n' + 'Emulating container types\n' '*************************\n' '\n' 'The following methods can be defined to implement ' @@ -7426,49 +6725,53 @@ topics = {'assert': 'The "assert" statement\n' 'k < N" where\n' '*N* is the length of the sequence, or slice objects, which ' 'define a\n' - 'range of items. It is also recommended that mappings ' + 'range of items. (For backwards compatibility, the method\n' + '"__getslice__()" (see below) can also be defined to handle ' + 'simple, but\n' + 'not extended slices.) It is also recommended that mappings ' 'provide the\n' - 'methods "keys()", "values()", "items()", "get()", ' - '"clear()",\n' - '"setdefault()", "pop()", "popitem()", "copy()", and ' - '"update()"\n' - 'behaving similar to those for Python’s standard dictionary ' - 'objects.\n' - 'The "collections.abc" module provides a "MutableMapping" ' - 'abstract base\n' - 'class to help create those methods from a base set of ' - '"__getitem__()",\n' - '"__setitem__()", "__delitem__()", and "keys()". Mutable ' - 'sequences\n' - 'should provide methods "append()", "count()", "index()", ' - '"extend()",\n' - '"insert()", "pop()", "remove()", "reverse()" and "sort()", ' - 'like Python\n' - 'standard list objects. Finally, sequence types should ' - 'implement\n' - 'addition (meaning concatenation) and multiplication ' - '(meaning\n' - 'repetition) by defining the methods "__add__()", ' - '"__radd__()",\n' - '"__iadd__()", "__mul__()", "__rmul__()" and "__imul__()" ' - 'described\n' - 'below; they should not define other numerical operators. ' - 'It is\n' + 'methods "keys()", "values()", "items()", "has_key()", ' + '"get()",\n' + '"clear()", "setdefault()", "iterkeys()", "itervalues()",\n' + '"iteritems()", "pop()", "popitem()", "copy()", and ' + '"update()" behaving\n' + "similar to those for Python's standard dictionary " + 'objects. The\n' + '"UserDict" module provides a "DictMixin" class to help ' + 'create those\n' + 'methods from a base set of "__getitem__()", ' + '"__setitem__()",\n' + '"__delitem__()", and "keys()". Mutable sequences should ' + 'provide\n' + 'methods "append()", "count()", "index()", "extend()", ' + '"insert()",\n' + '"pop()", "remove()", "reverse()" and "sort()", like Python ' + 'standard\n' + 'list objects. Finally, sequence types should implement ' + 'addition\n' + '(meaning concatenation) and multiplication (meaning ' + 'repetition) by\n' + 'defining the methods "__add__()", "__radd__()", ' + '"__iadd__()",\n' + '"__mul__()", "__rmul__()" and "__imul__()" described ' + 'below; they\n' + 'should not define "__coerce__()" or other numerical ' + 'operators. It is\n' 'recommended that both mappings and sequences implement ' 'the\n' '"__contains__()" method to allow efficient use of the "in" ' 'operator;\n' - 'for mappings, "in" should search the mapping’s keys; for ' - 'sequences, it\n' - 'should search through the values. It is further ' - 'recommended that both\n' - 'mappings and sequences implement the "__iter__()" method ' - 'to allow\n' + 'for mappings, "in" should be equivalent of "has_key()"; ' + 'for sequences,\n' + 'it should search through the values. It is further ' + 'recommended that\n' + 'both mappings and sequences implement the "__iter__()" ' + 'method to allow\n' 'efficient iteration through the container; for mappings, ' '"__iter__()"\n' - 'should iterate through the object’s keys; for sequences, ' - 'it should\n' - 'iterate through the values.\n' + 'should be the same as "iterkeys()"; for sequences, it ' + 'should iterate\n' + 'through the values.\n' '\n' 'object.__len__(self)\n' '\n' @@ -7476,10 +6779,10 @@ topics = {'assert': 'The "assert" statement\n' 'Should return\n' ' the length of the object, an integer ">=" 0. Also, an ' 'object that\n' - ' doesn’t define a "__bool__()" method and whose ' - '"__len__()" method\n' - ' returns zero is considered to be false in a Boolean ' - 'context.\n' + ' doesn\'t define a "__nonzero__()" method and whose ' + '"__len__()"\n' + ' method returns zero is considered to be false in a ' + 'Boolean context.\n' '\n' ' **CPython implementation detail:** In CPython, the ' 'length is\n' @@ -7489,38 +6792,8 @@ topics = {'assert': 'The "assert" statement\n' 'raise\n' ' "OverflowError". To prevent raising "OverflowError" by ' 'truth value\n' - ' testing, an object must define a "__bool__()" method.\n' - '\n' - 'object.__length_hint__(self)\n' - '\n' - ' Called to implement "operator.length_hint()". Should ' - 'return an\n' - ' estimated length for the object (which may be greater ' - 'or less than\n' - ' the actual length). The length must be an integer ">=" ' - '0. The\n' - ' return value may also be "NotImplemented", which is ' - 'treated the\n' - ' same as if the "__length_hint__" method didn’t exist at ' - 'all. This\n' - ' method is purely an optimization and is never required ' - 'for\n' - ' correctness.\n' - '\n' - ' New in version 3.4.\n' - '\n' - 'Note: Slicing is done exclusively with the following three ' - 'methods.\n' - ' A call like\n' - '\n' - ' a[1:2] = b\n' - '\n' - ' is translated to\n' - '\n' - ' a[slice(1, 2, None)] = b\n' - '\n' - ' and so forth. Missing slice items are always filled in ' - 'with "None".\n' + ' testing, an object must define a "__nonzero__()" ' + 'method.\n' '\n' 'object.__getitem__(self, key)\n' '\n' @@ -7548,6 +6821,12 @@ topics = {'assert': 'The "assert" statement\n' 'of the\n' ' sequence.\n' '\n' + 'object.__missing__(self, key)\n' + '\n' + ' Called by "dict"."__getitem__()" to implement ' + '"self[key]" for dict\n' + ' subclasses when key is not in the dictionary.\n' + '\n' 'object.__setitem__(self, key, value)\n' '\n' ' Called to implement assignment to "self[key]". Same ' @@ -7575,12 +6854,6 @@ topics = {'assert': 'The "assert" statement\n' ' raised for improper *key* values as for the ' '"__getitem__()" method.\n' '\n' - 'object.__missing__(self, key)\n' - '\n' - ' Called by "dict"."__getitem__()" to implement ' - '"self[key]" for dict\n' - ' subclasses when key is not in the dictionary.\n' - '\n' 'object.__iter__(self)\n' '\n' ' This method is called when an iterator is required for ' @@ -7589,7 +6862,9 @@ topics = {'assert': 'The "assert" statement\n' 'can iterate\n' ' over all the objects in the container. For mappings, ' 'it should\n' - ' iterate over the keys of the container.\n' + ' iterate over the keys of the container, and should also ' + 'be made\n' + ' available as the method "iterkeys()".\n' '\n' ' Iterator objects also need to implement this method; ' 'they are\n' @@ -7618,14 +6893,16 @@ topics = {'assert': 'The "assert" statement\n' 'provided by\n' ' "reversed()".\n' '\n' + ' New in version 2.6.\n' + '\n' 'The membership test operators ("in" and "not in") are ' 'normally\n' - 'implemented as an iteration through a container. However, ' + 'implemented as an iteration through a sequence. However, ' 'container\n' 'objects can supply the following special method with a ' 'more efficient\n' 'implementation, which also does not require the object be ' - 'iterable.\n' + 'a sequence.\n' '\n' 'object.__contains__(self, item)\n' '\n' @@ -7637,32 +6914,42 @@ topics = {'assert': 'The "assert" statement\n' 'values or\n' ' the key-item pairs.\n' '\n' - ' For objects that don’t define "__contains__()", the ' + ' For objects that don\'t define "__contains__()", the ' 'membership test\n' ' first tries iteration via "__iter__()", then the old ' 'sequence\n' ' iteration protocol via "__getitem__()", see this ' 'section in the\n' ' language reference.\n', - 'shifting': 'Shifting operations\n' + 'shifting': '\n' + 'Shifting operations\n' '*******************\n' '\n' 'The shifting operations have lower priority than the arithmetic\n' 'operations:\n' '\n' - ' shift_expr ::= a_expr | shift_expr ("<<" | ">>") a_expr\n' + ' shift_expr ::= a_expr | shift_expr ( "<<" | ">>" ) a_expr\n' '\n' - 'These operators accept integers as arguments. They shift the ' - 'first\n' + 'These operators accept plain or long integers as arguments. ' + 'The\n' + 'arguments are converted to a common type. They shift the first\n' 'argument to the left or right by the number of bits given by ' 'the\n' 'second argument.\n' '\n' - 'A right shift by *n* bits is defined as floor division by ' - '"pow(2,n)".\n' - 'A left shift by *n* bits is defined as multiplication with ' - '"pow(2,n)".\n', - 'slicings': 'Slicings\n' + 'A right shift by *n* bits is defined as division by "pow(2, ' + 'n)". A\n' + 'left shift by *n* bits is defined as multiplication with "pow(2, ' + 'n)".\n' + 'Negative shift counts raise a "ValueError" exception.\n' + '\n' + 'Note: In the current implementation, the right-hand operand is\n' + ' required to be at most "sys.maxsize". If the right-hand ' + 'operand is\n' + ' larger than "sys.maxsize" an "OverflowError" exception is ' + 'raised.\n', + 'slicings': '\n' + 'Slicings\n' '********\n' '\n' 'A slicing selects a range of items in a sequence object (e.g., ' @@ -7672,14 +6959,18 @@ topics = {'assert': 'The "assert" statement\n' 'targets in assignment or "del" statements. The syntax for a ' 'slicing:\n' '\n' - ' slicing ::= primary "[" slice_list "]"\n' - ' slice_list ::= slice_item ("," slice_item)* [","]\n' - ' slice_item ::= expression | proper_slice\n' - ' proper_slice ::= [lower_bound] ":" [upper_bound] [ ":" ' - '[stride] ]\n' - ' lower_bound ::= expression\n' - ' upper_bound ::= expression\n' - ' stride ::= expression\n' + ' slicing ::= simple_slicing | extended_slicing\n' + ' simple_slicing ::= primary "[" short_slice "]"\n' + ' extended_slicing ::= primary "[" slice_list "]"\n' + ' slice_list ::= slice_item ("," slice_item)* [","]\n' + ' slice_item ::= expression | proper_slice | ellipsis\n' + ' proper_slice ::= short_slice | long_slice\n' + ' short_slice ::= [lower_bound] ":" [upper_bound]\n' + ' long_slice ::= short_slice ":" [stride]\n' + ' lower_bound ::= expression\n' + ' upper_bound ::= expression\n' + ' stride ::= expression\n' + ' ellipsis ::= "..."\n' '\n' 'There is ambiguity in the formal syntax here: anything that ' 'looks like\n' @@ -7690,30 +6981,52 @@ topics = {'assert': 'The "assert" statement\n' 'syntax, this is disambiguated by defining that in this case the\n' 'interpretation as a subscription takes priority over the\n' 'interpretation as a slicing (this is the case if the slice list\n' - 'contains no proper slice).\n' - '\n' - 'The semantics for a slicing are as follows. The primary is ' - 'indexed\n' - '(using the same "__getitem__()" method as normal subscription) ' - 'with a\n' - 'key that is constructed from the slice list, as follows. If the ' + 'contains no proper slice nor ellipses). Similarly, when the ' 'slice\n' - 'list contains at least one comma, the key is a tuple containing ' - 'the\n' + 'list has exactly one short slice and no trailing comma, the\n' + 'interpretation as a simple slicing takes priority over that as ' + 'an\n' + 'extended slicing.\n' + '\n' + 'The semantics for a simple slicing are as follows. The primary ' + 'must\n' + 'evaluate to a sequence object. The lower and upper bound ' + 'expressions,\n' + 'if present, must evaluate to plain integers; defaults are zero ' + 'and the\n' + '"sys.maxint", respectively. If either bound is negative, the\n' + "sequence's length is added to it. The slicing now selects all " + 'items\n' + 'with index *k* such that "i <= k < j" where *i* and *j* are the\n' + 'specified lower and upper bounds. This may be an empty ' + 'sequence. It\n' + 'is not an error if *i* or *j* lie outside the range of valid ' + 'indexes\n' + "(such items don't exist so they aren't selected).\n" + '\n' + 'The semantics for an extended slicing are as follows. The ' + 'primary\n' + 'must evaluate to a mapping object, and it is indexed with a key ' + 'that\n' + 'is constructed from the slice list, as follows. If the slice ' + 'list\n' + 'contains at least one comma, the key is a tuple containing the\n' 'conversion of the slice items; otherwise, the conversion of the ' 'lone\n' 'slice item is the key. The conversion of a slice item that is ' 'an\n' - 'expression is that expression. The conversion of a proper slice ' - 'is a\n' - 'slice object (see section The standard type hierarchy) whose ' - '"start",\n' - '"stop" and "step" attributes are the values of the expressions ' - 'given\n' - 'as lower bound, upper bound and stride, respectively, ' - 'substituting\n' - '"None" for missing expressions.\n', - 'specialattrs': 'Special Attributes\n' + 'expression is that expression. The conversion of an ellipsis ' + 'slice\n' + 'item is the built-in "Ellipsis" object. The conversion of a ' + 'proper\n' + 'slice is a slice object (see section The standard type ' + 'hierarchy)\n' + 'whose "start", "stop" and "step" attributes are the values of ' + 'the\n' + 'expressions given as lower bound, upper bound and stride,\n' + 'respectively, substituting "None" for missing expressions.\n', + 'specialattrs': '\n' + 'Special Attributes\n' '******************\n' '\n' 'The implementation adds a few special read-only attributes ' @@ -7725,9 +7038,25 @@ topics = {'assert': 'The "assert" statement\n' 'object.__dict__\n' '\n' ' A dictionary or other mapping object used to store an ' - 'object’s\n' + "object's\n" ' (writable) attributes.\n' '\n' + 'object.__methods__\n' + '\n' + ' Deprecated since version 2.2: Use the built-in function ' + '"dir()" to\n' + " get a list of an object's attributes. This attribute is " + 'no longer\n' + ' available.\n' + '\n' + 'object.__members__\n' + '\n' + ' Deprecated since version 2.2: Use the built-in function ' + '"dir()" to\n' + " get a list of an object's attributes. This attribute is " + 'no longer\n' + ' available.\n' + '\n' 'instance.__class__\n' '\n' ' The class to which a class instance belongs.\n' @@ -7738,17 +7067,12 @@ topics = {'assert': 'The "assert" statement\n' '\n' 'definition.__name__\n' '\n' - ' The name of the class, function, method, descriptor, or ' - 'generator\n' - ' instance.\n' - '\n' - 'definition.__qualname__\n' - '\n' - ' The *qualified name* of the class, function, method, ' + ' The name of the class, type, function, method, ' 'descriptor, or\n' ' generator instance.\n' '\n' - ' New in version 3.3.\n' + 'The following attributes are only supported by *new-style ' + 'class*es.\n' '\n' 'class.__mro__\n' '\n' @@ -7766,14 +7090,14 @@ topics = {'assert': 'The "assert" statement\n' '\n' 'class.__subclasses__()\n' '\n' - ' Each class keeps a list of weak references to its ' - 'immediate\n' - ' subclasses. This method returns a list of all those ' - 'references\n' - ' still alive. Example:\n' + ' Each new-style class keeps a list of weak references to ' + 'its\n' + ' immediate subclasses. This method returns a list of all ' + 'those\n' + ' references still alive. Example:\n' '\n' ' >>> int.__subclasses__()\n' - " [<class 'bool'>]\n" + " [<type 'bool'>]\n" '\n' '-[ Footnotes ]-\n' '\n' @@ -7785,27 +7109,40 @@ topics = {'assert': 'The "assert" statement\n' 'to\n' ' "[1.0, 2.0]", and similarly for tuples.\n' '\n' - '[3] They must have since the parser can’t tell the type of ' + "[3] They must have since the parser can't tell the type of " 'the\n' ' operands.\n' '\n' '[4] Cased characters are those with general category ' 'property\n' - ' being one of “Lu” (Letter, uppercase), “Ll” (Letter, ' + ' being one of "Lu" (Letter, uppercase), "Ll" (Letter, ' 'lowercase),\n' - ' or “Lt” (Letter, titlecase).\n' + ' or "Lt" (Letter, titlecase).\n' '\n' '[5] To format only a tuple you should therefore provide a\n' ' singleton tuple whose only element is the tuple to be ' - 'formatted.\n', - 'specialnames': 'Special method names\n' + 'formatted.\n' + '\n' + '[6] The advantage of leaving the newline on is that ' + 'returning an\n' + ' empty string is then an unambiguous EOF indication. It ' + 'is also\n' + ' possible (in cases where it might matter, for example, ' + 'if you want\n' + ' to make an exact copy of a file while scanning its ' + 'lines) to tell\n' + ' whether the last line of a file ended in a newline or ' + 'not (yes\n' + ' this happens!).\n', + 'specialnames': '\n' + 'Special method names\n' '********************\n' '\n' 'A class can implement certain operations that are invoked by ' 'special\n' 'syntax (such as arithmetic operations or subscripting and ' 'slicing) by\n' - 'defining methods with special names. This is Python’s ' + "defining methods with special names. This is Python's " 'approach to\n' '*operator overloading*, allowing classes to define their own ' 'behavior\n' @@ -7813,21 +7150,15 @@ topics = {'assert': 'The "assert" statement\n' 'class defines\n' 'a method named "__getitem__()", and "x" is an instance of ' 'this class,\n' - 'then "x[i]" is roughly equivalent to "type(x).__getitem__(x, ' - 'i)".\n' - 'Except where mentioned, attempts to execute an operation ' - 'raise an\n' - 'exception when no appropriate method is defined (typically\n' - '"AttributeError" or "TypeError").\n' - '\n' - 'Setting a special method to "None" indicates that the ' - 'corresponding\n' - 'operation is not available. For example, if a class sets ' - '"__iter__()"\n' - 'to "None", the class is not iterable, so calling "iter()" on ' - 'its\n' - 'instances will raise a "TypeError" (without falling back to\n' - '"__getitem__()"). [2]\n' + 'then "x[i]" is roughly equivalent to "x.__getitem__(i)" for ' + 'old-style\n' + 'classes and "type(x).__getitem__(x, i)" for new-style ' + 'classes. Except\n' + 'where mentioned, attempts to execute an operation raise an ' + 'exception\n' + 'when no appropriate method is defined (typically ' + '"AttributeError" or\n' + '"TypeError").\n' '\n' 'When implementing a class that emulates any built-in type, ' 'it is\n' @@ -7839,7 +7170,7 @@ topics = {'assert': 'The "assert" statement\n' 'elements, but\n' 'extracting a slice may not make sense. (One example of this ' 'is the\n' - '"NodeList" interface in the W3C’s Document Object Model.)\n' + '"NodeList" interface in the W3C\'s Document Object Model.)\n' '\n' '\n' 'Basic customization\n' @@ -7863,26 +7194,24 @@ topics = {'assert': 'The "assert" statement\n' '\n' ' Typical implementations create a new instance of the ' 'class by\n' - ' invoking the superclass’s "__new__()" method using\n' - ' "super().__new__(cls[, ...])" with appropriate arguments ' - 'and then\n' - ' modifying the newly-created instance as necessary before ' - 'returning\n' - ' it.\n' - '\n' - ' If "__new__()" is invoked during object construction and ' - 'it returns\n' - ' an instance or subclass of *cls*, then the new ' - 'instance’s\n' - ' "__init__()" method will be invoked like "__init__(self[, ' - '...])",\n' - ' where *self* is the new instance and the remaining ' - 'arguments are\n' - ' the same as were passed to the object constructor.\n' + ' invoking the superclass\'s "__new__()" method using\n' + ' "super(currentclass, cls).__new__(cls[, ...])" with ' + 'appropriate\n' + ' arguments and then modifying the newly-created instance ' + 'as\n' + ' necessary before returning it.\n' + '\n' + ' If "__new__()" returns an instance of *cls*, then the ' + 'new\n' + ' instance\'s "__init__()" method will be invoked like\n' + ' "__init__(self[, ...])", where *self* is the new instance ' + 'and the\n' + ' remaining arguments are the same as were passed to ' + '"__new__()".\n' '\n' ' If "__new__()" does not return an instance of *cls*, then ' 'the new\n' - ' instance’s "__init__()" method will not be invoked.\n' + ' instance\'s "__init__()" method will not be invoked.\n' '\n' ' "__new__()" is intended mainly to allow subclasses of ' 'immutable\n' @@ -7900,17 +7229,17 @@ topics = {'assert': 'The "assert" statement\n' 'those\n' ' passed to the class constructor expression. If a base ' 'class has an\n' - ' "__init__()" method, the derived class’s "__init__()" ' + ' "__init__()" method, the derived class\'s "__init__()" ' 'method, if\n' ' any, must explicitly call it to ensure proper ' 'initialization of the\n' ' base class part of the instance; for example:\n' - ' "super().__init__([args...])".\n' + ' "BaseClass.__init__(self, [args...])".\n' '\n' ' Because "__new__()" and "__init__()" work together in ' 'constructing\n' ' objects ("__new__()" to create it, and "__init__()" to ' - 'customize\n' + 'customise\n' ' it), no non-"None" value may be returned by "__init__()"; ' 'doing so\n' ' will cause a "TypeError" to be raised at runtime.\n' @@ -7919,108 +7248,116 @@ topics = {'assert': 'The "assert" statement\n' '\n' ' Called when the instance is about to be destroyed. This ' 'is also\n' - ' called a finalizer or (improperly) a destructor. If a ' - 'base class\n' - ' has a "__del__()" method, the derived class’s "__del__()" ' - 'method,\n' - ' if any, must explicitly call it to ensure proper deletion ' - 'of the\n' - ' base class part of the instance.\n' - '\n' - ' It is possible (though not recommended!) for the ' - '"__del__()" method\n' - ' to postpone destruction of the instance by creating a new ' - 'reference\n' - ' to it. This is called object *resurrection*. It is\n' - ' implementation-dependent whether "__del__()" is called a ' - 'second\n' - ' time when a resurrected object is about to be destroyed; ' + ' called a destructor. If a base class has a "__del__()" ' + 'method, the\n' + ' derived class\'s "__del__()" method, if any, must ' + 'explicitly call it\n' + ' to ensure proper deletion of the base class part of the ' + 'instance.\n' + ' Note that it is possible (though not recommended!) for ' 'the\n' - ' current *CPython* implementation only calls it once.\n' - '\n' - ' It is not guaranteed that "__del__()" methods are called ' - 'for\n' - ' objects that still exist when the interpreter exits.\n' - '\n' - ' Note: "del x" doesn’t directly call "x.__del__()" — the ' - 'former\n' + ' "__del__()" method to postpone destruction of the ' + 'instance by\n' + ' creating a new reference to it. It may then be called at ' + 'a later\n' + ' time when this new reference is deleted. It is not ' + 'guaranteed that\n' + ' "__del__()" methods are called for objects that still ' + 'exist when\n' + ' the interpreter exits.\n' + '\n' + ' Note: "del x" doesn\'t directly call "x.__del__()" --- ' + 'the former\n' ' decrements the reference count for "x" by one, and the ' 'latter is\n' - ' only called when "x"’s reference count reaches zero.\n' - '\n' - ' **CPython implementation detail:** It is possible for a ' + ' only called when "x"\'s reference count reaches zero. ' + 'Some common\n' + ' situations that may prevent the reference count of an ' + 'object from\n' + ' going to zero include: circular references between ' + 'objects (e.g.,\n' + ' a doubly-linked list or a tree data structure with ' + 'parent and\n' + ' child pointers); a reference to the object on the stack ' + 'frame of\n' + ' a function that caught an exception (the traceback ' + 'stored in\n' + ' "sys.exc_traceback" keeps the stack frame alive); or a ' 'reference\n' - ' cycle to prevent the reference count of an object from ' - 'going to\n' - ' zero. In this case, the cycle will be later detected and ' - 'deleted\n' - ' by the *cyclic garbage collector*. A common cause of ' - 'reference\n' - ' cycles is when an exception has been caught in a local ' - 'variable.\n' - ' The frame’s locals then reference the exception, which ' + ' to the object on the stack frame that raised an ' + 'unhandled\n' + ' exception in interactive mode (the traceback stored in\n' + ' "sys.last_traceback" keeps the stack frame alive). The ' + 'first\n' + ' situation can only be remedied by explicitly breaking ' + 'the cycles;\n' + ' the latter two situations can be resolved by storing ' + '"None" in\n' + ' "sys.exc_traceback" or "sys.last_traceback". Circular ' 'references\n' - ' its own traceback, which references the locals of all ' - 'frames caught\n' - ' in the traceback.\n' - '\n' - ' See also: Documentation for the "gc" module.\n' + ' which are garbage are detected when the option cycle ' + 'detector is\n' + " enabled (it's on by default), but can only be cleaned " + 'up if there\n' + ' are no Python-level "__del__()" methods involved. Refer ' + 'to the\n' + ' documentation for the "gc" module for more information ' + 'about how\n' + ' "__del__()" methods are handled by the cycle detector,\n' + ' particularly the description of the "garbage" value.\n' '\n' ' Warning: Due to the precarious circumstances under which\n' ' "__del__()" methods are invoked, exceptions that occur ' 'during\n' ' their execution are ignored, and a warning is printed ' 'to\n' - ' "sys.stderr" instead. In particular:\n' - '\n' - ' * "__del__()" can be invoked when arbitrary code is ' - 'being\n' - ' executed, including from any arbitrary thread. If ' + ' "sys.stderr" instead. Also, when "__del__()" is invoked ' + 'in\n' + ' response to a module being deleted (e.g., when ' + 'execution of the\n' + ' program is done), other globals referenced by the ' '"__del__()"\n' - ' needs to take a lock or invoke any other blocking ' - 'resource, it\n' - ' may deadlock as the resource may already be taken by ' - 'the code\n' - ' that gets interrupted to execute "__del__()".\n' - '\n' - ' * "__del__()" can be executed during interpreter ' - 'shutdown. As\n' - ' a consequence, the global variables it needs to ' - 'access\n' - ' (including other modules) may already have been ' - 'deleted or set\n' - ' to "None". Python guarantees that globals whose name ' - 'begins\n' - ' with a single underscore are deleted from their ' - 'module before\n' - ' other globals are deleted; if no other references to ' - 'such\n' - ' globals exist, this may help in assuring that ' - 'imported modules\n' - ' are still available at the time when the "__del__()" ' - 'method is\n' - ' called.\n' + ' method may already have been deleted or in the process ' + 'of being\n' + ' torn down (e.g. the import machinery shutting down). ' + 'For this\n' + ' reason, "__del__()" methods should do the absolute ' + 'minimum needed\n' + ' to maintain external invariants. Starting with version ' + '1.5,\n' + ' Python guarantees that globals whose name begins with a ' + 'single\n' + ' underscore are deleted from their module before other ' + 'globals are\n' + ' deleted; if no other references to such globals exist, ' + 'this may\n' + ' help in assuring that imported modules are still ' + 'available at the\n' + ' time when the "__del__()" method is called.\n' + '\n' + ' See also the "-R" command-line option.\n' '\n' 'object.__repr__(self)\n' '\n' - ' Called by the "repr()" built-in function to compute the ' - '“official”\n' - ' string representation of an object. If at all possible, ' - 'this\n' - ' should look like a valid Python expression that could be ' - 'used to\n' - ' recreate an object with the same value (given an ' - 'appropriate\n' - ' environment). If this is not possible, a string of the ' - 'form\n' - ' "<...some useful description...>" should be returned. The ' - 'return\n' - ' value must be a string object. If a class defines ' - '"__repr__()" but\n' - ' not "__str__()", then "__repr__()" is also used when an ' - '“informal”\n' - ' string representation of instances of that class is ' - 'required.\n' + ' Called by the "repr()" built-in function and by string ' + 'conversions\n' + ' (reverse quotes) to compute the "official" string ' + 'representation of\n' + ' an object. If at all possible, this should look like a ' + 'valid\n' + ' Python expression that could be used to recreate an ' + 'object with the\n' + ' same value (given an appropriate environment). If this ' + 'is not\n' + ' possible, a string of the form "<...some useful ' + 'description...>"\n' + ' should be returned. The return value must be a string ' + 'object. If a\n' + ' class defines "__repr__()" but not "__str__()", then ' + '"__repr__()"\n' + ' is also used when an "informal" string representation of ' + 'instances\n' + ' of that class is required.\n' '\n' ' This is typically used for debugging, so it is important ' 'that the\n' @@ -8028,64 +7365,17 @@ topics = {'assert': 'The "assert" statement\n' '\n' 'object.__str__(self)\n' '\n' - ' Called by "str(object)" and the built-in functions ' - '"format()" and\n' - ' "print()" to compute the “informal” or nicely printable ' - 'string\n' - ' representation of an object. The return value must be a ' - 'string\n' - ' object.\n' - '\n' - ' This method differs from "object.__repr__()" in that ' - 'there is no\n' - ' expectation that "__str__()" return a valid Python ' - 'expression: a\n' - ' more convenient or concise representation can be used.\n' - '\n' - ' The default implementation defined by the built-in type ' - '"object"\n' - ' calls "object.__repr__()".\n' - '\n' - 'object.__bytes__(self)\n' - '\n' - ' Called by bytes to compute a byte-string representation ' + ' Called by the "str()" built-in function and by the ' + '"print"\n' + ' statement to compute the "informal" string representation ' 'of an\n' - ' object. This should return a "bytes" object.\n' - '\n' - 'object.__format__(self, format_spec)\n' - '\n' - ' Called by the "format()" built-in function, and by ' - 'extension,\n' - ' evaluation of formatted string literals and the ' - '"str.format()"\n' - ' method, to produce a “formatted” string representation of ' - 'an\n' - ' object. The *format_spec* argument is a string that ' - 'contains a\n' - ' description of the formatting options desired. The ' - 'interpretation\n' - ' of the *format_spec* argument is up to the type ' - 'implementing\n' - ' "__format__()", however most classes will either ' - 'delegate\n' - ' formatting to one of the built-in types, or use a ' - 'similar\n' - ' formatting option syntax.\n' - '\n' - ' See Format Specification Mini-Language for a description ' - 'of the\n' - ' standard formatting syntax.\n' - '\n' - ' The return value must be a string object.\n' - '\n' - ' Changed in version 3.4: The __format__ method of "object" ' - 'itself\n' - ' raises a "TypeError" if passed any non-empty string.\n' - '\n' - ' Changed in version 3.7: "object.__format__(x, \'\')" is ' - 'now\n' - ' equivalent to "str(x)" rather than "format(str(self), ' - '\'\')".\n' + ' object. This differs from "__repr__()" in that it does ' + 'not have to\n' + ' be a valid Python expression: a more convenient or ' + 'concise\n' + ' representation may be used instead. The return value must ' + 'be a\n' + ' string object.\n' '\n' 'object.__lt__(self, other)\n' 'object.__le__(self, other)\n' @@ -8094,14 +7384,20 @@ topics = {'assert': 'The "assert" statement\n' 'object.__gt__(self, other)\n' 'object.__ge__(self, other)\n' '\n' - ' These are the so-called “rich comparison” methods. The\n' + ' New in version 2.1.\n' + '\n' + ' These are the so-called "rich comparison" methods, and ' + 'are called\n' + ' for comparison operators in preference to "__cmp__()" ' + 'below. The\n' ' correspondence between operator symbols and method names ' 'is as\n' ' follows: "x<y" calls "x.__lt__(y)", "x<=y" calls ' '"x.__le__(y)",\n' - ' "x==y" calls "x.__eq__(y)", "x!=y" calls "x.__ne__(y)", ' - '"x>y" calls\n' - ' "x.__gt__(y)", and "x>=y" calls "x.__ge__(y)".\n' + ' "x==y" calls "x.__eq__(y)", "x!=y" and "x<>y" call ' + '"x.__ne__(y)",\n' + ' "x>y" calls "x.__gt__(y)", and "x>=y" calls ' + '"x.__ge__(y)".\n' '\n' ' A rich comparison method may return the singleton ' '"NotImplemented"\n' @@ -8118,43 +7414,59 @@ topics = {'assert': 'The "assert" statement\n' ' on the value to determine if the result is true or ' 'false.\n' '\n' - ' By default, "__ne__()" delegates to "__eq__()" and ' - 'inverts the\n' - ' result unless it is "NotImplemented". There are no other ' - 'implied\n' - ' relationships among the comparison operators, for ' - 'example, the\n' - ' truth of "(x<y or x==y)" does not imply "x<=y". To ' - 'automatically\n' - ' generate ordering operations from a single root ' - 'operation, see\n' - ' "functools.total_ordering()".\n' - '\n' - ' See the paragraph on "__hash__()" for some important ' - 'notes on\n' - ' creating *hashable* objects which support custom ' - 'comparison\n' - ' operations and are usable as dictionary keys.\n' + ' There are no implied relationships among the comparison ' + 'operators.\n' + ' The truth of "x==y" does not imply that "x!=y" is false.\n' + ' Accordingly, when defining "__eq__()", one should also ' + 'define\n' + ' "__ne__()" so that the operators will behave as ' + 'expected. See the\n' + ' paragraph on "__hash__()" for some important notes on ' + 'creating\n' + ' *hashable* objects which support custom comparison ' + 'operations and\n' + ' are usable as dictionary keys.\n' '\n' ' There are no swapped-argument versions of these methods ' '(to be used\n' ' when the left argument does not support the operation but ' 'the right\n' ' argument does); rather, "__lt__()" and "__gt__()" are ' - 'each other’s\n' - ' reflection, "__le__()" and "__ge__()" are each other’s ' + "each other's\n" + ' reflection, "__le__()" and "__ge__()" are each other\'s ' 'reflection,\n' - ' and "__eq__()" and "__ne__()" are their own reflection. ' - 'If the\n' - ' operands are of different types, and right operand’s type ' - 'is a\n' - ' direct or indirect subclass of the left operand’s type, ' - 'the\n' - ' reflected method of the right operand has priority, ' - 'otherwise the\n' - ' left operand’s method has priority. Virtual subclassing ' - 'is not\n' - ' considered.\n' + ' and "__eq__()" and "__ne__()" are their own reflection.\n' + '\n' + ' Arguments to rich comparison methods are never coerced.\n' + '\n' + ' To automatically generate ordering operations from a ' + 'single root\n' + ' operation, see "functools.total_ordering()".\n' + '\n' + 'object.__cmp__(self, other)\n' + '\n' + ' Called by comparison operations if rich comparison (see ' + 'above) is\n' + ' not defined. Should return a negative integer if "self < ' + 'other",\n' + ' zero if "self == other", a positive integer if "self > ' + 'other". If\n' + ' no "__cmp__()", "__eq__()" or "__ne__()" operation is ' + 'defined,\n' + ' class instances are compared by object identity ' + '("address"). See\n' + ' also the description of "__hash__()" for some important ' + 'notes on\n' + ' creating *hashable* objects which support custom ' + 'comparison\n' + ' operations and are usable as dictionary keys. (Note: the\n' + ' restriction that exceptions are not propagated by ' + '"__cmp__()" has\n' + ' been removed since Python 1.5.)\n' + '\n' + 'object.__rcmp__(self, other)\n' + '\n' + ' Changed in version 2.1: No longer supported.\n' '\n' 'object.__hash__(self)\n' '\n' @@ -8162,7 +7474,7 @@ topics = {'assert': 'The "assert" statement\n' 'on members\n' ' of hashed collections including "set", "frozenset", and ' '"dict".\n' - ' "__hash__()" should return an integer. The only required ' + ' "__hash__()" should return an integer. The only required ' 'property\n' ' is that objects which compare equal have the same hash ' 'value; it is\n' @@ -8175,115 +7487,91 @@ topics = {'assert': 'The "assert" statement\n' ' def __hash__(self):\n' ' return hash((self.name, self.nick, self.color))\n' '\n' - ' Note: "hash()" truncates the value returned from an ' - 'object’s\n' - ' custom "__hash__()" method to the size of a ' - '"Py_ssize_t". This\n' - ' is typically 8 bytes on 64-bit builds and 4 bytes on ' - '32-bit\n' - ' builds. If an object’s "__hash__()" must interoperate ' - 'on builds\n' - ' of different bit sizes, be sure to check the width on ' - 'all\n' - ' supported builds. An easy way to do this is with ' - '"python -c\n' - ' "import sys; print(sys.hash_info.width)"".\n' - '\n' - ' If a class does not define an "__eq__()" method it should ' - 'not\n' - ' define a "__hash__()" operation either; if it defines ' - '"__eq__()"\n' - ' but not "__hash__()", its instances will not be usable as ' - 'items in\n' - ' hashable collections. If a class defines mutable objects ' - 'and\n' - ' implements an "__eq__()" method, it should not implement\n' - ' "__hash__()", since the implementation of hashable ' - 'collections\n' - ' requires that a key’s hash value is immutable (if the ' - 'object’s hash\n' - ' value changes, it will be in the wrong hash bucket).\n' - '\n' - ' User-defined classes have "__eq__()" and "__hash__()" ' + ' If a class does not define a "__cmp__()" or "__eq__()" ' + 'method it\n' + ' should not define a "__hash__()" operation either; if it ' + 'defines\n' + ' "__cmp__()" or "__eq__()" but not "__hash__()", its ' + 'instances will\n' + ' not be usable in hashed collections. If a class defines ' + 'mutable\n' + ' objects and implements a "__cmp__()" or "__eq__()" ' + 'method, it\n' + ' should not implement "__hash__()", since hashable ' + 'collection\n' + " implementations require that an object's hash value is " + 'immutable\n' + " (if the object's hash value changes, it will be in the " + 'wrong hash\n' + ' bucket).\n' + '\n' + ' User-defined classes have "__cmp__()" and "__hash__()" ' 'methods by\n' ' default; with them, all objects compare unequal (except ' 'with\n' - ' themselves) and "x.__hash__()" returns an appropriate ' - 'value such\n' - ' that "x == y" implies both that "x is y" and "hash(x) == ' - 'hash(y)".\n' - '\n' - ' A class that overrides "__eq__()" and does not define ' - '"__hash__()"\n' - ' will have its "__hash__()" implicitly set to "None". ' - 'When the\n' - ' "__hash__()" method of a class is "None", instances of ' - 'the class\n' - ' will raise an appropriate "TypeError" when a program ' - 'attempts to\n' - ' retrieve their hash value, and will also be correctly ' - 'identified as\n' - ' unhashable when checking "isinstance(obj,\n' - ' collections.abc.Hashable)".\n' - '\n' - ' If a class that overrides "__eq__()" needs to retain the\n' - ' implementation of "__hash__()" from a parent class, the ' - 'interpreter\n' - ' must be told this explicitly by setting "__hash__ =\n' - ' <ParentClass>.__hash__".\n' - '\n' - ' If a class that does not override "__eq__()" wishes to ' - 'suppress\n' - ' hash support, it should include "__hash__ = None" in the ' - 'class\n' - ' definition. A class which defines its own "__hash__()" ' - 'that\n' - ' explicitly raises a "TypeError" would be incorrectly ' - 'identified as\n' - ' hashable by an "isinstance(obj, ' - 'collections.abc.Hashable)" call.\n' - '\n' - ' Note: By default, the "__hash__()" values of str and ' - 'bytes\n' - ' objects are “salted” with an unpredictable random ' - 'value.\n' - ' Although they remain constant within an individual ' - 'Python\n' - ' process, they are not predictable between repeated ' - 'invocations of\n' - ' Python.This is intended to provide protection against a ' - 'denial-\n' - ' of-service caused by carefully-chosen inputs that ' - 'exploit the\n' - ' worst case performance of a dict insertion, O(n^2) ' - 'complexity.\n' - ' See http://www.ocert.org/advisories/ocert-2011-003.html ' - 'for\n' - ' details.Changing hash values affects the iteration ' - 'order of sets.\n' - ' Python has never made guarantees about this ordering ' - '(and it\n' - ' typically varies between 32-bit and 64-bit builds).See ' - 'also\n' - ' "PYTHONHASHSEED".\n' + ' themselves) and "x.__hash__()" returns a result derived ' + 'from\n' + ' "id(x)".\n' + '\n' + ' Classes which inherit a "__hash__()" method from a parent ' + 'class but\n' + ' change the meaning of "__cmp__()" or "__eq__()" such that ' + 'the hash\n' + ' value returned is no longer appropriate (e.g. by ' + 'switching to a\n' + ' value-based concept of equality instead of the default ' + 'identity\n' + ' based equality) can explicitly flag themselves as being ' + 'unhashable\n' + ' by setting "__hash__ = None" in the class definition. ' + 'Doing so\n' + ' means that not only will instances of the class raise an\n' + ' appropriate "TypeError" when a program attempts to ' + 'retrieve their\n' + ' hash value, but they will also be correctly identified ' + 'as\n' + ' unhashable when checking "isinstance(obj, ' + 'collections.Hashable)"\n' + ' (unlike classes which define their own "__hash__()" to ' + 'explicitly\n' + ' raise "TypeError").\n' + '\n' + ' Changed in version 2.5: "__hash__()" may now also return ' + 'a long\n' + ' integer object; the 32-bit integer is then derived from ' + 'the hash of\n' + ' that object.\n' '\n' - ' Changed in version 3.3: Hash randomization is enabled by ' - 'default.\n' + ' Changed in version 2.6: "__hash__" may now be set to ' + '"None" to\n' + ' explicitly flag instances of a class as unhashable.\n' '\n' - 'object.__bool__(self)\n' + 'object.__nonzero__(self)\n' '\n' ' Called to implement truth value testing and the built-in ' 'operation\n' - ' "bool()"; should return "False" or "True". When this ' - 'method is not\n' - ' defined, "__len__()" is called, if it is defined, and the ' - 'object is\n' - ' considered true if its result is nonzero. If a class ' + ' "bool()"; should return "False" or "True", or their ' + 'integer\n' + ' equivalents "0" or "1". When this method is not ' + 'defined,\n' + ' "__len__()" is called, if it is defined, and the object ' + 'is\n' + ' considered true if its result is nonzero. If a class ' 'defines\n' - ' neither "__len__()" nor "__bool__()", all its instances ' - 'are\n' + ' neither "__len__()" nor "__nonzero__()", all its ' + 'instances are\n' ' considered true.\n' '\n' + 'object.__unicode__(self)\n' + '\n' + ' Called to implement "unicode()" built-in; should return a ' + 'Unicode\n' + ' object. When this method is not defined, string ' + 'conversion is\n' + ' attempted, and the result of string conversion is ' + 'converted to\n' + ' Unicode using the system default encoding.\n' + '\n' '\n' 'Customizing attribute access\n' '============================\n' @@ -8296,17 +7584,15 @@ topics = {'assert': 'The "assert" statement\n' '\n' 'object.__getattr__(self, name)\n' '\n' - ' Called when the default attribute access fails with an\n' - ' "AttributeError" (either "__getattribute__()" raises an\n' - ' "AttributeError" because *name* is not an instance ' - 'attribute or an\n' - ' attribute in the class tree for "self"; or "__get__()" of ' - 'a *name*\n' - ' property raises "AttributeError"). This method should ' - 'either\n' - ' return the (computed) attribute value or raise an ' - '"AttributeError"\n' - ' exception.\n' + ' Called when an attribute lookup has not found the ' + 'attribute in the\n' + ' usual places (i.e. it is not an instance attribute nor is ' + 'it found\n' + ' in the class tree for "self"). "name" is the attribute ' + 'name. This\n' + ' method should return the (computed) attribute value or ' + 'raise an\n' + ' "AttributeError" exception.\n' '\n' ' Note that if the attribute is found through the normal ' 'mechanism,\n' @@ -8325,32 +7611,7 @@ topics = {'assert': 'The "assert" statement\n' ' instead inserting them in another object). See the\n' ' "__getattribute__()" method below for a way to actually ' 'get total\n' - ' control over attribute access.\n' - '\n' - 'object.__getattribute__(self, name)\n' - '\n' - ' Called unconditionally to implement attribute accesses ' - 'for\n' - ' instances of the class. If the class also defines ' - '"__getattr__()",\n' - ' the latter will not be called unless "__getattribute__()" ' - 'either\n' - ' calls it explicitly or raises an "AttributeError". This ' - 'method\n' - ' should return the (computed) attribute value or raise an\n' - ' "AttributeError" exception. In order to avoid infinite ' - 'recursion in\n' - ' this method, its implementation should always call the ' - 'base class\n' - ' method with the same name to access any attributes it ' - 'needs, for\n' - ' example, "object.__getattribute__(self, name)".\n' - '\n' - ' Note: This method may still be bypassed when looking up ' - 'special\n' - ' methods as the result of implicit invocation via ' - 'language syntax\n' - ' or built-in functions. See Special method lookup.\n' + ' control in new-style classes.\n' '\n' 'object.__setattr__(self, name, value)\n' '\n' @@ -8358,15 +7619,24 @@ topics = {'assert': 'The "assert" statement\n' 'is called\n' ' instead of the normal mechanism (i.e. store the value in ' 'the\n' - ' instance dictionary). *name* is the attribute name, ' + ' instance dictionary). *name* is the attribute name, ' '*value* is the\n' ' value to be assigned to it.\n' '\n' ' If "__setattr__()" wants to assign to an instance ' 'attribute, it\n' - ' should call the base class method with the same name, for ' - 'example,\n' - ' "object.__setattr__(self, name, value)".\n' + ' should not simply execute "self.name = value" --- this ' + 'would cause\n' + ' a recursive call to itself. Instead, it should insert ' + 'the value in\n' + ' the dictionary of instance attributes, e.g., ' + '"self.__dict__[name] =\n' + ' value". For new-style classes, rather than accessing the ' + 'instance\n' + ' dictionary, it should call the base class method with the ' + 'same\n' + ' name, for example, "object.__setattr__(self, name, ' + 'value)".\n' '\n' 'object.__delattr__(self, name)\n' '\n' @@ -8376,85 +7646,38 @@ topics = {'assert': 'The "assert" statement\n' 'obj.name" is\n' ' meaningful for the object.\n' '\n' - 'object.__dir__(self)\n' - '\n' - ' Called when "dir()" is called on the object. A sequence ' - 'must be\n' - ' returned. "dir()" converts the returned sequence to a ' - 'list and\n' - ' sorts it.\n' - '\n' - '\n' - 'Customizing module attribute access\n' - '-----------------------------------\n' - '\n' - 'Special names "__getattr__" and "__dir__" can be also used ' - 'to\n' - 'customize access to module attributes. The "__getattr__" ' - 'function at\n' - 'the module level should accept one argument which is the ' - 'name of an\n' - 'attribute and return the computed value or raise an ' - '"AttributeError".\n' - 'If an attribute is not found on a module object through the ' - 'normal\n' - 'lookup, i.e. "object.__getattribute__()", then "__getattr__" ' - 'is\n' - 'searched in the module "__dict__" before raising an ' - '"AttributeError".\n' - 'If found, it is called with the attribute name and the ' - 'result is\n' - 'returned.\n' - '\n' - 'The "__dir__" function should accept no arguments, and ' - 'return a\n' - 'sequence of strings that represents the names accessible on ' - 'module. If\n' - 'present, this function overrides the standard "dir()" search ' - 'on a\n' - 'module.\n' - '\n' - 'For a more fine grained customization of the module behavior ' - '(setting\n' - 'attributes, properties, etc.), one can set the "__class__" ' - 'attribute\n' - 'of a module object to a subclass of "types.ModuleType". For ' - 'example:\n' - '\n' - ' import sys\n' - ' from types import ModuleType\n' - '\n' - ' class VerboseModule(ModuleType):\n' - ' def __repr__(self):\n' - " return f'Verbose {self.__name__}'\n" '\n' - ' def __setattr__(self, attr, value):\n' - " print(f'Setting {attr}...')\n" - ' super().__setattr__(attr, value)\n' + 'More attribute access for new-style classes\n' + '-------------------------------------------\n' '\n' - ' sys.modules[__name__].__class__ = VerboseModule\n' + 'The following methods only apply to new-style classes.\n' '\n' - 'Note: Defining module "__getattr__" and setting module ' - '"__class__"\n' - ' only affect lookups made using the attribute access syntax ' - '–\n' - ' directly accessing the module globals (whether by code ' - 'within the\n' - ' module, or via a reference to the module’s globals ' - 'dictionary) is\n' - ' unaffected.\n' - '\n' - 'Changed in version 3.5: "__class__" module attribute is now ' - 'writable.\n' - '\n' - 'New in version 3.7: "__getattr__" and "__dir__" module ' - 'attributes.\n' + 'object.__getattribute__(self, name)\n' '\n' - 'See also:\n' + ' Called unconditionally to implement attribute accesses ' + 'for\n' + ' instances of the class. If the class also defines ' + '"__getattr__()",\n' + ' the latter will not be called unless "__getattribute__()" ' + 'either\n' + ' calls it explicitly or raises an "AttributeError". This ' + 'method\n' + ' should return the (computed) attribute value or raise an\n' + ' "AttributeError" exception. In order to avoid infinite ' + 'recursion in\n' + ' this method, its implementation should always call the ' + 'base class\n' + ' method with the same name to access any attributes it ' + 'needs, for\n' + ' example, "object.__getattribute__(self, name)".\n' '\n' - ' **PEP 562** - Module __getattr__ and __dir__\n' - ' Describes the "__getattr__" and "__dir__" functions on ' - 'modules.\n' + ' Note: This method may still be bypassed when looking up ' + 'special\n' + ' methods as the result of implicit invocation via ' + 'language syntax\n' + ' or built-in functions. See Special method lookup for ' + 'new-style\n' + ' classes.\n' '\n' '\n' 'Implementing Descriptors\n' @@ -8464,42 +7687,29 @@ topics = {'assert': 'The "assert" statement\n' 'class\n' 'containing the method (a so-called *descriptor* class) ' 'appears in an\n' - '*owner* class (the descriptor must be in either the owner’s ' + "*owner* class (the descriptor must be in either the owner's " 'class\n' 'dictionary or in the class dictionary for one of its ' 'parents). In the\n' - 'examples below, “the attribute” refers to the attribute ' + 'examples below, "the attribute" refers to the attribute ' 'whose name is\n' - 'the key of the property in the owner class’ "__dict__".\n' + 'the key of the property in the owner class\' "__dict__".\n' '\n' - 'object.__get__(self, instance, owner=None)\n' + 'object.__get__(self, instance, owner)\n' '\n' ' Called to get the attribute of the owner class (class ' 'attribute\n' ' access) or of an instance of that class (instance ' 'attribute\n' - ' access). The optional *owner* argument is the owner ' - 'class, while\n' - ' *instance* is the instance that the attribute was ' - 'accessed through,\n' - ' or "None" when the attribute is accessed through the ' - '*owner*.\n' - '\n' - ' This method should return the computed attribute value or ' - 'raise an\n' - ' "AttributeError" exception.\n' - '\n' - ' **PEP 252** specifies that "__get__()" is callable with ' - 'one or two\n' - ' arguments. Python’s own built-in descriptors support ' - 'this\n' - ' specification; however, it is likely that some ' - 'third-party tools\n' - ' have descriptors that require both arguments. Python’s ' - 'own\n' - ' "__getattribute__()" implementation always passes in both ' - 'arguments\n' - ' whether they are required or not.\n' + ' access). *owner* is always the owner class, while ' + '*instance* is the\n' + ' instance that the attribute was accessed through, or ' + '"None" when\n' + ' the attribute is accessed through the *owner*. This ' + 'method should\n' + ' return the (computed) attribute value or raise an ' + '"AttributeError"\n' + ' exception.\n' '\n' 'object.__set__(self, instance, value)\n' '\n' @@ -8507,47 +7717,19 @@ topics = {'assert': 'The "assert" statement\n' 'the owner\n' ' class to a new value, *value*.\n' '\n' - ' Note, adding "__set__()" or "__delete__()" changes the ' - 'kind of\n' - ' descriptor to a “data descriptor”. See Invoking ' - 'Descriptors for\n' - ' more details.\n' - '\n' 'object.__delete__(self, instance)\n' '\n' ' Called to delete the attribute on an instance *instance* ' 'of the\n' ' owner class.\n' '\n' - 'object.__set_name__(self, owner, name)\n' - '\n' - ' Called at the time the owning class *owner* is created. ' - 'The\n' - ' descriptor has been assigned to *name*.\n' - '\n' - ' New in version 3.6.\n' - '\n' - 'The attribute "__objclass__" is interpreted by the "inspect" ' - 'module as\n' - 'specifying the class where this object was defined (setting ' - 'this\n' - 'appropriately can assist in runtime introspection of dynamic ' - 'class\n' - 'attributes). For callables, it may indicate that an instance ' - 'of the\n' - 'given type (or a subclass) is expected or required as the ' - 'first\n' - 'positional argument (for example, CPython sets this ' - 'attribute for\n' - 'unbound methods that are implemented in C).\n' - '\n' '\n' 'Invoking Descriptors\n' '--------------------\n' '\n' 'In general, a descriptor is an object attribute with ' - '“binding\n' - 'behavior”, one whose attribute access has been overridden by ' + '"binding\n' + 'behavior", one whose attribute access has been overridden by ' 'methods\n' 'in the descriptor protocol: "__get__()", "__set__()", and\n' '"__delete__()". If any of those methods are defined for an ' @@ -8556,7 +7738,7 @@ topics = {'assert': 'The "assert" statement\n' '\n' 'The default behavior for attribute access is to get, set, or ' 'delete\n' - 'the attribute from an object’s dictionary. For instance, ' + "the attribute from an object's dictionary. For instance, " '"a.x" has a\n' 'lookup chain starting with "a.__dict__[\'x\']", then\n' '"type(a).__dict__[\'x\']", and continuing through the base ' @@ -8571,7 +7753,10 @@ topics = {'assert': 'The "assert" statement\n' 'the\n' 'precedence chain depends on which descriptor methods were ' 'defined and\n' - 'how they were called.\n' + 'how they were called. Note that descriptors are only ' + 'invoked for new\n' + 'style objects or classes (ones that subclass "object()" or ' + '"type()").\n' '\n' 'The starting point for descriptor invocation is a binding, ' '"a.x". How\n' @@ -8583,14 +7768,15 @@ topics = {'assert': 'The "assert" statement\n' ' invokes a descriptor method: "x.__get__(a)".\n' '\n' 'Instance Binding\n' - ' If binding to an object instance, "a.x" is transformed ' - 'into the\n' - ' call: "type(a).__dict__[\'x\'].__get__(a, type(a))".\n' + ' If binding to a new-style object instance, "a.x" is ' + 'transformed\n' + ' into the call: "type(a).__dict__[\'x\'].__get__(a, ' + 'type(a))".\n' '\n' 'Class Binding\n' - ' If binding to a class, "A.x" is transformed into the ' - 'call:\n' - ' "A.__dict__[\'x\'].__get__(None, A)".\n' + ' If binding to a new-style class, "A.x" is transformed ' + 'into the\n' + ' call: "A.__dict__[\'x\'].__get__(None, A)".\n' '\n' 'Super Binding\n' ' If "a" is an instance of "super", then the binding ' @@ -8610,7 +7796,7 @@ topics = {'assert': 'The "assert" statement\n' 'does not define "__get__()", then accessing the attribute ' 'will return\n' 'the descriptor object itself unless there is a value in the ' - 'object’s\n' + "object's\n" 'instance dictionary. If the descriptor defines "__set__()" ' 'and/or\n' '"__delete__()", it is a data descriptor; if it defines ' @@ -8619,13 +7805,12 @@ topics = {'assert': 'The "assert" statement\n' 'both\n' '"__get__()" and "__set__()", while non-data descriptors have ' 'just the\n' - '"__get__()" method. Data descriptors with "__get__()" and ' - '"__set__()"\n' - '(and/or "__delete__()") defined always override a ' - 'redefinition in an\n' - 'instance dictionary. In contrast, non-data descriptors can ' - 'be\n' - 'overridden by instances.\n' + '"__get__()" method. Data descriptors with "__set__()" and ' + '"__get__()"\n' + 'defined always override a redefinition in an instance ' + 'dictionary. In\n' + 'contrast, non-data descriptors can be overridden by ' + 'instances.\n' '\n' 'Python methods (including "staticmethod()" and ' '"classmethod()") are\n' @@ -8645,38 +7830,45 @@ topics = {'assert': 'The "assert" statement\n' '__slots__\n' '---------\n' '\n' - '*__slots__* allow us to explicitly declare data members ' - '(like\n' - 'properties) and deny the creation of *__dict__* and ' - '*__weakref__*\n' - '(unless explicitly declared in *__slots__* or available in a ' - 'parent.)\n' - '\n' - 'The space saved over using *__dict__* can be significant. ' - 'Attribute\n' - 'lookup speed can be significantly improved as well.\n' + 'By default, instances of both old and new-style classes have ' + 'a\n' + 'dictionary for attribute storage. This wastes space for ' + 'objects\n' + 'having very few instance variables. The space consumption ' + 'can become\n' + 'acute when creating large numbers of instances.\n' + '\n' + 'The default can be overridden by defining *__slots__* in a ' + 'new-style\n' + 'class definition. The *__slots__* declaration takes a ' + 'sequence of\n' + 'instance variables and reserves just enough space in each ' + 'instance to\n' + 'hold a value for each variable. Space is saved because ' + '*__dict__* is\n' + 'not created for each instance.\n' '\n' - 'object.__slots__\n' + '__slots__\n' '\n' ' This class variable can be assigned a string, iterable, ' 'or sequence\n' - ' of strings with variable names used by instances. ' - '*__slots__*\n' - ' reserves space for the declared variables and prevents ' - 'the\n' - ' automatic creation of *__dict__* and *__weakref__* for ' - 'each\n' - ' instance.\n' + ' of strings with variable names used by instances. If ' + 'defined in a\n' + ' new-style class, *__slots__* reserves space for the ' + 'declared\n' + ' variables and prevents the automatic creation of ' + '*__dict__* and\n' + ' *__weakref__* for each instance.\n' '\n' + ' New in version 2.2.\n' '\n' 'Notes on using *__slots__*\n' - '~~~~~~~~~~~~~~~~~~~~~~~~~~\n' '\n' '* When inheriting from a class without *__slots__*, the ' '*__dict__*\n' - ' and *__weakref__* attribute of the instances will always ' - 'be\n' - ' accessible.\n' + ' attribute of that class will always be accessible, so a ' + '*__slots__*\n' + ' definition in the subclass is meaningless.\n' '\n' '* Without a *__dict__* variable, instances cannot be ' 'assigned new\n' @@ -8689,6 +7881,14 @@ topics = {'assert': 'The "assert" statement\n' '*__slots__*\n' ' declaration.\n' '\n' + ' Changed in version 2.3: Previously, adding "\'__dict__\'" ' + 'to the\n' + ' *__slots__* declaration would not enable the assignment of ' + 'new\n' + ' attributes not specifically listed in the sequence of ' + 'instance\n' + ' variable names.\n' + '\n' '* Without a *__weakref__* variable for each instance, ' 'classes\n' ' defining *__slots__* do not support weak references to ' @@ -8698,6 +7898,11 @@ topics = {'assert': 'The "assert" statement\n' '*__slots__*\n' ' declaration.\n' '\n' + ' Changed in version 2.3: Previously, adding ' + '"\'__weakref__\'" to the\n' + ' *__slots__* declaration would not enable support for weak\n' + ' references.\n' + '\n' '* *__slots__* are implemented at the class level by ' 'creating\n' ' descriptors (Implementing Descriptors) for each variable ' @@ -8708,16 +7913,13 @@ topics = {'assert': 'The "assert" statement\n' 'class\n' ' attribute would overwrite the descriptor assignment.\n' '\n' - '* The action of a *__slots__* declaration is not limited to ' - 'the\n' - ' class where it is defined. *__slots__* declared in ' - 'parents are\n' - ' available in child classes. However, child subclasses will ' - 'get a\n' - ' *__dict__* and *__weakref__* unless they also define ' - '*__slots__*\n' - ' (which should only contain names of any *additional* ' - 'slots).\n' + '* The action of a *__slots__* declaration is limited to the ' + 'class\n' + ' where it is defined. As a result, subclasses will have a ' + '*__dict__*\n' + ' unless they also define *__slots__* (which must only ' + 'contain names\n' + ' of any *additional* slots).\n' '\n' '* If a class defines a slot also defined in a base class, ' 'the\n' @@ -8731,8 +7933,8 @@ topics = {'assert': 'The "assert" statement\n' '\n' '* Nonempty *__slots__* does not work for classes derived ' 'from\n' - ' “variable-length” built-in types such as "int", "bytes" ' - 'and "tuple".\n' + ' "variable-length" built-in types such as "long", "str" and ' + '"tuple".\n' '\n' '* Any non-string iterable may be assigned to *__slots__*. ' 'Mappings\n' @@ -8744,312 +7946,89 @@ topics = {'assert': 'The "assert" statement\n' 'same\n' ' *__slots__*.\n' '\n' - '* Multiple inheritance with multiple slotted parent classes ' - 'can be\n' - ' used, but only one parent is allowed to have attributes ' - 'created by\n' - ' slots (the other bases must have empty slot layouts) - ' - 'violations\n' - ' raise "TypeError".\n' - '\n' - '* If an iterator is used for *__slots__* then a descriptor ' - 'is\n' - ' created for each of the iterator’s values. However, the ' - '*__slots__*\n' - ' attribute will be an empty iterator.\n' + ' Changed in version 2.6: Previously, *__class__* assignment ' + 'raised an\n' + ' error if either new or old class had *__slots__*.\n' '\n' '\n' 'Customizing class creation\n' '==========================\n' '\n' - 'Whenever a class inherits from another class, ' - '*__init_subclass__* is\n' - 'called on that class. This way, it is possible to write ' - 'classes which\n' - 'change the behavior of subclasses. This is closely related ' - 'to class\n' - 'decorators, but where class decorators only affect the ' - 'specific class\n' - 'they’re applied to, "__init_subclass__" solely applies to ' - 'future\n' - 'subclasses of the class defining the method.\n' - '\n' - 'classmethod object.__init_subclass__(cls)\n' - '\n' - ' This method is called whenever the containing class is ' - 'subclassed.\n' - ' *cls* is then the new subclass. If defined as a normal ' - 'instance\n' - ' method, this method is implicitly converted to a class ' - 'method.\n' - '\n' - ' Keyword arguments which are given to a new class are ' - 'passed to the\n' - ' parent’s class "__init_subclass__". For compatibility ' - 'with other\n' - ' classes using "__init_subclass__", one should take out ' - 'the needed\n' - ' keyword arguments and pass the others over to the base ' - 'class, as\n' - ' in:\n' - '\n' - ' class Philosopher:\n' - ' def __init_subclass__(cls, /, default_name, ' - '**kwargs):\n' - ' super().__init_subclass__(**kwargs)\n' - ' cls.default_name = default_name\n' - '\n' - ' class AustralianPhilosopher(Philosopher, ' - 'default_name="Bruce"):\n' - ' pass\n' - '\n' - ' The default implementation "object.__init_subclass__" ' - 'does nothing,\n' - ' but raises an error if it is called with any arguments.\n' - '\n' - ' Note: The metaclass hint "metaclass" is consumed by the ' - 'rest of\n' - ' the type machinery, and is never passed to ' - '"__init_subclass__"\n' - ' implementations. The actual metaclass (rather than the ' - 'explicit\n' - ' hint) can be accessed as "type(cls)".\n' - '\n' - ' New in version 3.6.\n' - '\n' - '\n' - 'Metaclasses\n' - '-----------\n' - '\n' - 'By default, classes are constructed using "type()". The ' - 'class body is\n' - 'executed in a new namespace and the class name is bound ' - 'locally to the\n' - 'result of "type(name, bases, namespace)".\n' - '\n' - 'The class creation process can be customized by passing the\n' - '"metaclass" keyword argument in the class definition line, ' - 'or by\n' - 'inheriting from an existing class that included such an ' - 'argument. In\n' - 'the following example, both "MyClass" and "MySubclass" are ' - 'instances\n' - 'of "Meta":\n' - '\n' - ' class Meta(type):\n' - ' pass\n' - '\n' - ' class MyClass(metaclass=Meta):\n' - ' pass\n' - '\n' - ' class MySubclass(MyClass):\n' - ' pass\n' - '\n' - 'Any other keyword arguments that are specified in the class ' - 'definition\n' - 'are passed through to all metaclass operations described ' - 'below.\n' - '\n' - 'When a class definition is executed, the following steps ' - 'occur:\n' - '\n' - '* MRO entries are resolved;\n' - '\n' - '* the appropriate metaclass is determined;\n' - '\n' - '* the class namespace is prepared;\n' - '\n' - '* the class body is executed;\n' - '\n' - '* the class object is created.\n' - '\n' - '\n' - 'Resolving MRO entries\n' - '---------------------\n' - '\n' - 'If a base that appears in class definition is not an ' - 'instance of\n' - '"type", then an "__mro_entries__" method is searched on it. ' - 'If found,\n' - 'it is called with the original bases tuple. This method must ' - 'return a\n' - 'tuple of classes that will be used instead of this base. The ' - 'tuple may\n' - 'be empty, in such case the original base is ignored.\n' - '\n' - 'See also: **PEP 560** - Core support for typing module and ' - 'generic\n' - ' types\n' - '\n' - '\n' - 'Determining the appropriate metaclass\n' - '-------------------------------------\n' - '\n' - 'The appropriate metaclass for a class definition is ' - 'determined as\n' - 'follows:\n' - '\n' - '* if no bases and no explicit metaclass are given, then ' - '"type()" is\n' - ' used;\n' - '\n' - '* if an explicit metaclass is given and it is *not* an ' - 'instance of\n' - ' "type()", then it is used directly as the metaclass;\n' - '\n' - '* if an instance of "type()" is given as the explicit ' - 'metaclass, or\n' - ' bases are defined, then the most derived metaclass is ' - 'used.\n' - '\n' - 'The most derived metaclass is selected from the explicitly ' - 'specified\n' - 'metaclass (if any) and the metaclasses (i.e. "type(cls)") of ' - 'all\n' - 'specified base classes. The most derived metaclass is one ' - 'which is a\n' - 'subtype of *all* of these candidate metaclasses. If none of ' - 'the\n' - 'candidate metaclasses meets that criterion, then the class ' - 'definition\n' - 'will fail with "TypeError".\n' - '\n' - '\n' - 'Preparing the class namespace\n' - '-----------------------------\n' - '\n' - 'Once the appropriate metaclass has been identified, then the ' - 'class\n' - 'namespace is prepared. If the metaclass has a "__prepare__" ' - 'attribute,\n' - 'it is called as "namespace = metaclass.__prepare__(name, ' - 'bases,\n' - '**kwds)" (where the additional keyword arguments, if any, ' - 'come from\n' - 'the class definition).\n' - '\n' - 'If the metaclass has no "__prepare__" attribute, then the ' - 'class\n' - 'namespace is initialised as an empty ordered mapping.\n' - '\n' - 'See also:\n' - '\n' - ' **PEP 3115** - Metaclasses in Python 3000\n' - ' Introduced the "__prepare__" namespace hook\n' - '\n' - '\n' - 'Executing the class body\n' - '------------------------\n' - '\n' - 'The class body is executed (approximately) as "exec(body, ' - 'globals(),\n' - 'namespace)". The key difference from a normal call to ' - '"exec()" is that\n' - 'lexical scoping allows the class body (including any ' - 'methods) to\n' - 'reference names from the current and outer scopes when the ' - 'class\n' - 'definition occurs inside a function.\n' - '\n' - 'However, even when the class definition occurs inside the ' - 'function,\n' - 'methods defined inside the class still cannot see names ' - 'defined at the\n' - 'class scope. Class variables must be accessed through the ' - 'first\n' - 'parameter of instance or class methods, or through the ' - 'implicit\n' - 'lexically scoped "__class__" reference described in the next ' - 'section.\n' - '\n' + 'By default, new-style classes are constructed using ' + '"type()". A class\n' + 'definition is read into a separate namespace and the value ' + 'of class\n' + 'name is bound to the result of "type(name, bases, dict)".\n' + '\n' + 'When the class definition is read, if *__metaclass__* is ' + 'defined then\n' + 'the callable assigned to it will be called instead of ' + '"type()". This\n' + 'allows classes or functions to be written which monitor or ' + 'alter the\n' + 'class creation process:\n' + '\n' + '* Modifying the class dictionary prior to the class being ' + 'created.\n' + '\n' + '* Returning an instance of another class -- essentially ' + 'performing\n' + ' the role of a factory function.\n' + '\n' + "These steps will have to be performed in the metaclass's " + '"__new__()"\n' + 'method -- "type.__new__()" can then be called from this ' + 'method to\n' + 'create a class with different properties. This example adds ' + 'a new\n' + 'element to the class dictionary before creating the class:\n' + '\n' + ' class metacls(type):\n' + ' def __new__(mcs, name, bases, dict):\n' + " dict['foo'] = 'metacls was here'\n" + ' return type.__new__(mcs, name, bases, dict)\n' + '\n' + 'You can of course also override other class methods (or add ' + 'new\n' + 'methods); for example defining a custom "__call__()" method ' + 'in the\n' + 'metaclass allows custom behavior when the class is called, ' + 'e.g. not\n' + 'always creating a new instance.\n' '\n' - 'Creating the class object\n' - '-------------------------\n' + '__metaclass__\n' '\n' - 'Once the class namespace has been populated by executing the ' - 'class\n' - 'body, the class object is created by calling ' - '"metaclass(name, bases,\n' - 'namespace, **kwds)" (the additional keywords passed here are ' - 'the same\n' - 'as those passed to "__prepare__").\n' - '\n' - 'This class object is the one that will be referenced by the ' - 'zero-\n' - 'argument form of "super()". "__class__" is an implicit ' - 'closure\n' - 'reference created by the compiler if any methods in a class ' - 'body refer\n' - 'to either "__class__" or "super". This allows the zero ' - 'argument form\n' - 'of "super()" to correctly identify the class being defined ' - 'based on\n' - 'lexical scoping, while the class or instance that was used ' - 'to make the\n' - 'current call is identified based on the first argument ' - 'passed to the\n' - 'method.\n' + ' This variable can be any callable accepting arguments for ' + '"name",\n' + ' "bases", and "dict". Upon class creation, the callable ' + 'is used\n' + ' instead of the built-in "type()".\n' '\n' - '**CPython implementation detail:** In CPython 3.6 and later, ' - 'the\n' - '"__class__" cell is passed to the metaclass as a ' - '"__classcell__" entry\n' - 'in the class namespace. If present, this must be propagated ' - 'up to the\n' - '"type.__new__" call in order for the class to be ' - 'initialised\n' - 'correctly. Failing to do so will result in a "RuntimeError" ' - 'in Python\n' - '3.8.\n' - '\n' - 'When using the default metaclass "type", or any metaclass ' - 'that\n' - 'ultimately calls "type.__new__", the following additional\n' - 'customisation steps are invoked after creating the class ' - 'object:\n' + ' New in version 2.2.\n' '\n' - '* first, "type.__new__" collects all of the descriptors in ' - 'the class\n' - ' namespace that define a "__set_name__()" method;\n' + 'The appropriate metaclass is determined by the following ' + 'precedence\n' + 'rules:\n' '\n' - '* second, all of these "__set_name__" methods are called ' - 'with the\n' - ' class being defined and the assigned name of that ' - 'particular\n' - ' descriptor;\n' + '* If "dict[\'__metaclass__\']" exists, it is used.\n' '\n' - '* finally, the "__init_subclass__()" hook is called on the ' - 'immediate\n' - ' parent of the new class in its method resolution order.\n' + '* Otherwise, if there is at least one base class, its ' + 'metaclass is\n' + ' used (this looks for a *__class__* attribute first and if ' + 'not found,\n' + ' uses its type).\n' '\n' - 'After the class object is created, it is passed to the ' - 'class\n' - 'decorators included in the class definition (if any) and the ' - 'resulting\n' - 'object is bound in the local namespace as the defined ' - 'class.\n' + '* Otherwise, if a global variable named __metaclass__ ' + 'exists, it is\n' + ' used.\n' '\n' - 'When a new class is created by "type.__new__", the object ' - 'provided as\n' - 'the namespace parameter is copied to a new ordered mapping ' - 'and the\n' - 'original object is discarded. The new copy is wrapped in a ' - 'read-only\n' - 'proxy, which becomes the "__dict__" attribute of the class ' - 'object.\n' - '\n' - 'See also:\n' - '\n' - ' **PEP 3135** - New super\n' - ' Describes the implicit "__class__" closure reference\n' - '\n' - '\n' - 'Uses for metaclasses\n' - '--------------------\n' + '* Otherwise, the old-style, classic metaclass ' + '(types.ClassType) is\n' + ' used.\n' '\n' 'The potential uses for metaclasses are boundless. Some ideas ' 'that have\n' - 'been explored include enum, logging, interface checking, ' + 'been explored including logging, interface checking, ' 'automatic\n' 'delegation, automatic property creation, proxies, ' 'frameworks, and\n' @@ -9059,6 +8038,8 @@ topics = {'assert': 'The "assert" statement\n' 'Customizing instance and subclass checks\n' '========================================\n' '\n' + 'New in version 2.6.\n' + '\n' 'The following methods are used to override the default ' 'behavior of the\n' '"isinstance()" and "issubclass()" built-in functions.\n' @@ -9067,7 +8048,7 @@ topics = {'assert': 'The "assert" statement\n' 'methods in\n' 'order to allow the addition of Abstract Base Classes (ABCs) ' 'as\n' - '“virtual base classes” to any class or type (including ' + '"virtual base classes" to any class or type (including ' 'built-in\n' 'types), including other ABCs.\n' '\n' @@ -9110,38 +8091,12 @@ topics = {'assert': 'The "assert" statement\n' ' module) to the language.\n' '\n' '\n' - 'Emulating generic types\n' - '=======================\n' - '\n' - 'One can implement the generic class syntax as specified by ' - '**PEP 484**\n' - '(for example "List[int]") by defining a special method:\n' - '\n' - 'classmethod object.__class_getitem__(cls, key)\n' - '\n' - ' Return an object representing the specialization of a ' - 'generic class\n' - ' by type arguments found in *key*.\n' - '\n' - 'This method is looked up on the class object itself, and ' - 'when defined\n' - 'in the class body, this method is implicitly a class ' - 'method. Note,\n' - 'this mechanism is primarily reserved for use with static ' - 'type hints,\n' - 'other usage is discouraged.\n' - '\n' - 'See also: **PEP 560** - Core support for typing module and ' - 'generic\n' - ' types\n' - '\n' - '\n' 'Emulating callable objects\n' '==========================\n' '\n' 'object.__call__(self[, args...])\n' '\n' - ' Called when the instance is “called” as a function; if ' + ' Called when the instance is "called" as a function; if ' 'this method\n' ' is defined, "x(arg1, arg2, ...)" is a shorthand for\n' ' "x.__call__(arg1, arg2, ...)".\n' @@ -9164,48 +8119,52 @@ topics = {'assert': 'The "assert" statement\n' '< N" where\n' '*N* is the length of the sequence, or slice objects, which ' 'define a\n' - 'range of items. It is also recommended that mappings ' + 'range of items. (For backwards compatibility, the method\n' + '"__getslice__()" (see below) can also be defined to handle ' + 'simple, but\n' + 'not extended slices.) It is also recommended that mappings ' 'provide the\n' - 'methods "keys()", "values()", "items()", "get()", ' - '"clear()",\n' - '"setdefault()", "pop()", "popitem()", "copy()", and ' - '"update()"\n' - 'behaving similar to those for Python’s standard dictionary ' - 'objects.\n' - 'The "collections.abc" module provides a "MutableMapping" ' - 'abstract base\n' - 'class to help create those methods from a base set of ' - '"__getitem__()",\n' - '"__setitem__()", "__delitem__()", and "keys()". Mutable ' - 'sequences\n' - 'should provide methods "append()", "count()", "index()", ' - '"extend()",\n' - '"insert()", "pop()", "remove()", "reverse()" and "sort()", ' - 'like Python\n' - 'standard list objects. Finally, sequence types should ' - 'implement\n' - 'addition (meaning concatenation) and multiplication ' - '(meaning\n' - 'repetition) by defining the methods "__add__()", ' - '"__radd__()",\n' - '"__iadd__()", "__mul__()", "__rmul__()" and "__imul__()" ' - 'described\n' - 'below; they should not define other numerical operators. It ' - 'is\n' + 'methods "keys()", "values()", "items()", "has_key()", ' + '"get()",\n' + '"clear()", "setdefault()", "iterkeys()", "itervalues()",\n' + '"iteritems()", "pop()", "popitem()", "copy()", and ' + '"update()" behaving\n' + "similar to those for Python's standard dictionary objects. " + 'The\n' + '"UserDict" module provides a "DictMixin" class to help ' + 'create those\n' + 'methods from a base set of "__getitem__()", ' + '"__setitem__()",\n' + '"__delitem__()", and "keys()". Mutable sequences should ' + 'provide\n' + 'methods "append()", "count()", "index()", "extend()", ' + '"insert()",\n' + '"pop()", "remove()", "reverse()" and "sort()", like Python ' + 'standard\n' + 'list objects. Finally, sequence types should implement ' + 'addition\n' + '(meaning concatenation) and multiplication (meaning ' + 'repetition) by\n' + 'defining the methods "__add__()", "__radd__()", ' + '"__iadd__()",\n' + '"__mul__()", "__rmul__()" and "__imul__()" described below; ' + 'they\n' + 'should not define "__coerce__()" or other numerical ' + 'operators. It is\n' 'recommended that both mappings and sequences implement the\n' '"__contains__()" method to allow efficient use of the "in" ' 'operator;\n' - 'for mappings, "in" should search the mapping’s keys; for ' - 'sequences, it\n' - 'should search through the values. It is further recommended ' - 'that both\n' - 'mappings and sequences implement the "__iter__()" method to ' - 'allow\n' + 'for mappings, "in" should be equivalent of "has_key()"; for ' + 'sequences,\n' + 'it should search through the values. It is further ' + 'recommended that\n' + 'both mappings and sequences implement the "__iter__()" ' + 'method to allow\n' 'efficient iteration through the container; for mappings, ' '"__iter__()"\n' - 'should iterate through the object’s keys; for sequences, it ' - 'should\n' - 'iterate through the values.\n' + 'should be the same as "iterkeys()"; for sequences, it should ' + 'iterate\n' + 'through the values.\n' '\n' 'object.__len__(self)\n' '\n' @@ -9213,10 +8172,10 @@ topics = {'assert': 'The "assert" statement\n' 'Should return\n' ' the length of the object, an integer ">=" 0. Also, an ' 'object that\n' - ' doesn’t define a "__bool__()" method and whose ' - '"__len__()" method\n' - ' returns zero is considered to be false in a Boolean ' - 'context.\n' + ' doesn\'t define a "__nonzero__()" method and whose ' + '"__len__()"\n' + ' method returns zero is considered to be false in a ' + 'Boolean context.\n' '\n' ' **CPython implementation detail:** In CPython, the length ' 'is\n' @@ -9225,38 +8184,7 @@ topics = {'assert': 'The "assert" statement\n' ' "sys.maxsize" some features (such as "len()") may raise\n' ' "OverflowError". To prevent raising "OverflowError" by ' 'truth value\n' - ' testing, an object must define a "__bool__()" method.\n' - '\n' - 'object.__length_hint__(self)\n' - '\n' - ' Called to implement "operator.length_hint()". Should ' - 'return an\n' - ' estimated length for the object (which may be greater or ' - 'less than\n' - ' the actual length). The length must be an integer ">=" 0. ' - 'The\n' - ' return value may also be "NotImplemented", which is ' - 'treated the\n' - ' same as if the "__length_hint__" method didn’t exist at ' - 'all. This\n' - ' method is purely an optimization and is never required ' - 'for\n' - ' correctness.\n' - '\n' - ' New in version 3.4.\n' - '\n' - 'Note: Slicing is done exclusively with the following three ' - 'methods.\n' - ' A call like\n' - '\n' - ' a[1:2] = b\n' - '\n' - ' is translated to\n' - '\n' - ' a[slice(1, 2, None)] = b\n' - '\n' - ' and so forth. Missing slice items are always filled in ' - 'with "None".\n' + ' testing, an object must define a "__nonzero__()" method.\n' '\n' 'object.__getitem__(self, key)\n' '\n' @@ -9284,6 +8212,12 @@ topics = {'assert': 'The "assert" statement\n' 'the\n' ' sequence.\n' '\n' + 'object.__missing__(self, key)\n' + '\n' + ' Called by "dict"."__getitem__()" to implement "self[key]" ' + 'for dict\n' + ' subclasses when key is not in the dictionary.\n' + '\n' 'object.__setitem__(self, key, value)\n' '\n' ' Called to implement assignment to "self[key]". Same note ' @@ -9311,12 +8245,6 @@ topics = {'assert': 'The "assert" statement\n' ' raised for improper *key* values as for the ' '"__getitem__()" method.\n' '\n' - 'object.__missing__(self, key)\n' - '\n' - ' Called by "dict"."__getitem__()" to implement "self[key]" ' - 'for dict\n' - ' subclasses when key is not in the dictionary.\n' - '\n' 'object.__iter__(self)\n' '\n' ' This method is called when an iterator is required for a ' @@ -9325,7 +8253,9 @@ topics = {'assert': 'The "assert" statement\n' 'iterate\n' ' over all the objects in the container. For mappings, it ' 'should\n' - ' iterate over the keys of the container.\n' + ' iterate over the keys of the container, and should also ' + 'be made\n' + ' available as the method "iterkeys()".\n' '\n' ' Iterator objects also need to implement this method; they ' 'are\n' @@ -9354,14 +8284,16 @@ topics = {'assert': 'The "assert" statement\n' 'provided by\n' ' "reversed()".\n' '\n' + ' New in version 2.6.\n' + '\n' 'The membership test operators ("in" and "not in") are ' 'normally\n' - 'implemented as an iteration through a container. However, ' + 'implemented as an iteration through a sequence. However, ' 'container\n' 'objects can supply the following special method with a more ' 'efficient\n' - 'implementation, which also does not require the object be ' - 'iterable.\n' + 'implementation, which also does not require the object be a ' + 'sequence.\n' '\n' 'object.__contains__(self, item)\n' '\n' @@ -9373,7 +8305,7 @@ topics = {'assert': 'The "assert" statement\n' 'values or\n' ' the key-item pairs.\n' '\n' - ' For objects that don’t define "__contains__()", the ' + ' For objects that don\'t define "__contains__()", the ' 'membership test\n' ' first tries iteration via "__iter__()", then the old ' 'sequence\n' @@ -9382,6 +8314,141 @@ topics = {'assert': 'The "assert" statement\n' ' language reference.\n' '\n' '\n' + 'Additional methods for emulation of sequence types\n' + '==================================================\n' + '\n' + 'The following optional methods can be defined to further ' + 'emulate\n' + 'sequence objects. Immutable sequences methods should at ' + 'most only\n' + 'define "__getslice__()"; mutable sequences might define all ' + 'three\n' + 'methods.\n' + '\n' + 'object.__getslice__(self, i, j)\n' + '\n' + ' Deprecated since version 2.0: Support slice objects as ' + 'parameters\n' + ' to the "__getitem__()" method. (However, built-in types ' + 'in CPython\n' + ' currently still implement "__getslice__()". Therefore, ' + 'you have to\n' + ' override it in derived classes when implementing ' + 'slicing.)\n' + '\n' + ' Called to implement evaluation of "self[i:j]". The ' + 'returned object\n' + ' should be of the same type as *self*. Note that missing ' + '*i* or *j*\n' + ' in the slice expression are replaced by zero or ' + '"sys.maxsize",\n' + ' respectively. If negative indexes are used in the slice, ' + 'the\n' + ' length of the sequence is added to that index. If the ' + 'instance does\n' + ' not implement the "__len__()" method, an "AttributeError" ' + 'is\n' + ' raised. No guarantee is made that indexes adjusted this ' + 'way are not\n' + ' still negative. Indexes which are greater than the ' + 'length of the\n' + ' sequence are not modified. If no "__getslice__()" is ' + 'found, a slice\n' + ' object is created instead, and passed to "__getitem__()" ' + 'instead.\n' + '\n' + 'object.__setslice__(self, i, j, sequence)\n' + '\n' + ' Called to implement assignment to "self[i:j]". Same notes ' + 'for *i*\n' + ' and *j* as for "__getslice__()".\n' + '\n' + ' This method is deprecated. If no "__setslice__()" is ' + 'found, or for\n' + ' extended slicing of the form "self[i:j:k]", a slice ' + 'object is\n' + ' created, and passed to "__setitem__()", instead of ' + '"__setslice__()"\n' + ' being called.\n' + '\n' + 'object.__delslice__(self, i, j)\n' + '\n' + ' Called to implement deletion of "self[i:j]". Same notes ' + 'for *i* and\n' + ' *j* as for "__getslice__()". This method is deprecated. ' + 'If no\n' + ' "__delslice__()" is found, or for extended slicing of the ' + 'form\n' + ' "self[i:j:k]", a slice object is created, and passed to\n' + ' "__delitem__()", instead of "__delslice__()" being ' + 'called.\n' + '\n' + 'Notice that these methods are only invoked when a single ' + 'slice with a\n' + 'single colon is used, and the slice method is available. ' + 'For slice\n' + 'operations involving extended slice notation, or in absence ' + 'of the\n' + 'slice methods, "__getitem__()", "__setitem__()" or ' + '"__delitem__()" is\n' + 'called with a slice object as argument.\n' + '\n' + 'The following example demonstrate how to make your program ' + 'or module\n' + 'compatible with earlier versions of Python (assuming that ' + 'methods\n' + '"__getitem__()", "__setitem__()" and "__delitem__()" support ' + 'slice\n' + 'objects as arguments):\n' + '\n' + ' class MyClass:\n' + ' ...\n' + ' def __getitem__(self, index):\n' + ' ...\n' + ' def __setitem__(self, index, value):\n' + ' ...\n' + ' def __delitem__(self, index):\n' + ' ...\n' + '\n' + ' if sys.version_info < (2, 0):\n' + " # They won't be defined if version is at least " + '2.0 final\n' + '\n' + ' def __getslice__(self, i, j):\n' + ' return self[max(0, i):max(0, j):]\n' + ' def __setslice__(self, i, j, seq):\n' + ' self[max(0, i):max(0, j):] = seq\n' + ' def __delslice__(self, i, j):\n' + ' del self[max(0, i):max(0, j):]\n' + ' ...\n' + '\n' + 'Note the calls to "max()"; these are necessary because of ' + 'the handling\n' + 'of negative indices before the "__*slice__()" methods are ' + 'called.\n' + 'When negative indexes are used, the "__*item__()" methods ' + 'receive them\n' + 'as provided, but the "__*slice__()" methods get a "cooked" ' + 'form of the\n' + 'index values. For each negative index value, the length of ' + 'the\n' + 'sequence is added to the index before calling the method ' + '(which may\n' + 'still result in a negative index); this is the customary ' + 'handling of\n' + 'negative indexes by the built-in sequence types, and the ' + '"__*item__()"\n' + 'methods are expected to do this as well. However, since ' + 'they should\n' + 'already be doing that, negative indexes cannot be passed in; ' + 'they must\n' + 'be constrained to the bounds of the sequence before being ' + 'passed to\n' + 'the "__*item__()" methods. Calling "max(0, i)" conveniently ' + 'returns\n' + 'the proper value.\n' + '\n' + '\n' 'Emulating numeric types\n' '=======================\n' '\n' @@ -9396,8 +8463,6 @@ topics = {'assert': 'The "assert" statement\n' 'object.__add__(self, other)\n' 'object.__sub__(self, other)\n' 'object.__mul__(self, other)\n' - 'object.__matmul__(self, other)\n' - 'object.__truediv__(self, other)\n' 'object.__floordiv__(self, other)\n' 'object.__mod__(self, other)\n' 'object.__divmod__(self, other)\n' @@ -9410,21 +8475,21 @@ topics = {'assert': 'The "assert" statement\n' '\n' ' These methods are called to implement the binary ' 'arithmetic\n' - ' operations ("+", "-", "*", "@", "/", "//", "%", ' - '"divmod()",\n' - ' "pow()", "**", "<<", ">>", "&", "^", "|"). For instance, ' - 'to\n' - ' evaluate the expression "x + y", where *x* is an instance ' - 'of a\n' - ' class that has an "__add__()" method, "x.__add__(y)" is ' - 'called.\n' - ' The "__divmod__()" method should be the equivalent to ' - 'using\n' - ' "__floordiv__()" and "__mod__()"; it should not be ' - 'related to\n' - ' "__truediv__()". Note that "__pow__()" should be defined ' - 'to accept\n' - ' an optional third argument if the ternary version of the ' + ' operations ("+", "-", "*", "//", "%", "divmod()", ' + '"pow()", "**",\n' + ' "<<", ">>", "&", "^", "|"). For instance, to evaluate ' + 'the\n' + ' expression "x + y", where *x* is an instance of a class ' + 'that has an\n' + ' "__add__()" method, "x.__add__(y)" is called. The ' + '"__divmod__()"\n' + ' method should be the equivalent to using "__floordiv__()" ' + 'and\n' + ' "__mod__()"; it should not be related to "__truediv__()" ' + '(described\n' + ' below). Note that "__pow__()" should be defined to ' + 'accept an\n' + ' optional third argument if the ternary version of the ' 'built-in\n' ' "pow()" function is to be supported.\n' '\n' @@ -9432,10 +8497,23 @@ topics = {'assert': 'The "assert" statement\n' 'with the\n' ' supplied arguments, it should return "NotImplemented".\n' '\n' + 'object.__div__(self, other)\n' + 'object.__truediv__(self, other)\n' + '\n' + ' The division operator ("/") is implemented by these ' + 'methods. The\n' + ' "__truediv__()" method is used when "__future__.division" ' + 'is in\n' + ' effect, otherwise "__div__()" is used. If only one of ' + 'these two\n' + ' methods is defined, the object will not support division ' + 'in the\n' + ' alternate context; "TypeError" will be raised instead.\n' + '\n' 'object.__radd__(self, other)\n' 'object.__rsub__(self, other)\n' 'object.__rmul__(self, other)\n' - 'object.__rmatmul__(self, other)\n' + 'object.__rdiv__(self, other)\n' 'object.__rtruediv__(self, other)\n' 'object.__rfloordiv__(self, other)\n' 'object.__rmod__(self, other)\n' @@ -9449,15 +8527,15 @@ topics = {'assert': 'The "assert" statement\n' '\n' ' These methods are called to implement the binary ' 'arithmetic\n' - ' operations ("+", "-", "*", "@", "/", "//", "%", ' - '"divmod()",\n' - ' "pow()", "**", "<<", ">>", "&", "^", "|") with reflected ' - '(swapped)\n' - ' operands. These functions are only called if the left ' - 'operand does\n' - ' not support the corresponding operation [3] and the ' - 'operands are of\n' - ' different types. [4] For instance, to evaluate the ' + ' operations ("+", "-", "*", "/", "%", "divmod()", "pow()", ' + '"**",\n' + ' "<<", ">>", "&", "^", "|") with reflected (swapped) ' + 'operands.\n' + ' These functions are only called if the left operand does ' + 'not\n' + ' support the corresponding operation and the operands are ' + 'of\n' + ' different types. [2] For instance, to evaluate the ' 'expression "x -\n' ' y", where *y* is an instance of a class that has an ' '"__rsub__()"\n' @@ -9469,20 +8547,20 @@ topics = {'assert': 'The "assert" statement\n' '"__rpow__()" (the\n' ' coercion rules would become too complicated).\n' '\n' - ' Note: If the right operand’s type is a subclass of the ' + " Note: If the right operand's type is a subclass of the " 'left\n' - ' operand’s type and that subclass provides the reflected ' + " operand's type and that subclass provides the reflected " 'method\n' ' for the operation, this method will be called before ' 'the left\n' - ' operand’s non-reflected method. This behavior allows ' + " operand's non-reflected method. This behavior allows " 'subclasses\n' - ' to override their ancestors’ operations.\n' + " to override their ancestors' operations.\n" '\n' 'object.__iadd__(self, other)\n' 'object.__isub__(self, other)\n' 'object.__imul__(self, other)\n' - 'object.__imatmul__(self, other)\n' + 'object.__idiv__(self, other)\n' 'object.__itruediv__(self, other)\n' 'object.__ifloordiv__(self, other)\n' 'object.__imod__(self, other)\n' @@ -9495,31 +8573,26 @@ topics = {'assert': 'The "assert" statement\n' '\n' ' These methods are called to implement the augmented ' 'arithmetic\n' - ' assignments ("+=", "-=", "*=", "@=", "/=", "//=", "%=", ' - '"**=",\n' - ' "<<=", ">>=", "&=", "^=", "|="). These methods should ' - 'attempt to\n' - ' do the operation in-place (modifying *self*) and return ' - 'the result\n' - ' (which could be, but does not have to be, *self*). If a ' - 'specific\n' - ' method is not defined, the augmented assignment falls ' - 'back to the\n' - ' normal methods. For instance, if *x* is an instance of a ' - 'class\n' - ' with an "__iadd__()" method, "x += y" is equivalent to "x ' - '=\n' - ' x.__iadd__(y)" . Otherwise, "x.__add__(y)" and ' - '"y.__radd__(x)" are\n' - ' considered, as with the evaluation of "x + y". In ' - 'certain\n' - ' situations, augmented assignment can result in unexpected ' - 'errors\n' - ' (see Why does a_tuple[i] += [‘item’] raise an exception ' - 'when the\n' - ' addition works?), but this behavior is in fact part of ' - 'the data\n' - ' model.\n' + ' assignments ("+=", "-=", "*=", "/=", "//=", "%=", "**=", ' + '"<<=",\n' + ' ">>=", "&=", "^=", "|="). These methods should attempt ' + 'to do the\n' + ' operation in-place (modifying *self*) and return the ' + 'result (which\n' + ' could be, but does not have to be, *self*). If a ' + 'specific method\n' + ' is not defined, the augmented assignment falls back to ' + 'the normal\n' + ' methods. For instance, to execute the statement "x += ' + 'y", where\n' + ' *x* is an instance of a class that has an "__iadd__()" ' + 'method,\n' + ' "x.__iadd__(y)" is called. If *x* is an instance of a ' + 'class that\n' + ' does not define a "__iadd__()" method, "x.__add__(y)" ' + 'and\n' + ' "y.__radd__(x)" are considered, as with the evaluation of ' + '"x + y".\n' '\n' 'object.__neg__(self)\n' 'object.__pos__(self)\n' @@ -9532,53 +8605,188 @@ topics = {'assert': 'The "assert" statement\n' '\n' 'object.__complex__(self)\n' 'object.__int__(self)\n' + 'object.__long__(self)\n' 'object.__float__(self)\n' '\n' ' Called to implement the built-in functions "complex()", ' - '"int()" and\n' - ' "float()". Should return a value of the appropriate ' - 'type.\n' + '"int()",\n' + ' "long()", and "float()". Should return a value of the ' + 'appropriate\n' + ' type.\n' + '\n' + 'object.__oct__(self)\n' + 'object.__hex__(self)\n' + '\n' + ' Called to implement the built-in functions "oct()" and ' + '"hex()".\n' + ' Should return a string value.\n' '\n' 'object.__index__(self)\n' '\n' - ' Called to implement "operator.index()", and whenever ' - 'Python needs\n' - ' to losslessly convert the numeric object to an integer ' - 'object (such\n' - ' as in slicing, or in the built-in "bin()", "hex()" and ' - '"oct()"\n' - ' functions). Presence of this method indicates that the ' - 'numeric\n' - ' object is an integer type. Must return an integer.\n' - '\n' - ' If "__int__()", "__float__()" and "__complex__()" are not ' - 'defined\n' - ' then corresponding built-in functions "int()", "float()" ' - 'and\n' - ' "complex()" fall back to "__index__()".\n' + ' Called to implement "operator.index()". Also called ' + 'whenever\n' + ' Python needs an integer object (such as in slicing). ' + 'Must return\n' + ' an integer (int or long).\n' + '\n' + ' New in version 2.5.\n' + '\n' + 'object.__coerce__(self, other)\n' + '\n' + ' Called to implement "mixed-mode" numeric arithmetic. ' + 'Should either\n' + ' return a 2-tuple containing *self* and *other* converted ' + 'to a\n' + ' common numeric type, or "None" if conversion is ' + 'impossible. When\n' + ' the common type would be the type of "other", it is ' + 'sufficient to\n' + ' return "None", since the interpreter will also ask the ' + 'other object\n' + ' to attempt a coercion (but sometimes, if the ' + 'implementation of the\n' + ' other type cannot be changed, it is useful to do the ' + 'conversion to\n' + ' the other type here). A return value of "NotImplemented" ' + 'is\n' + ' equivalent to returning "None".\n' + '\n' + '\n' + 'Coercion rules\n' + '==============\n' + '\n' + 'This section used to document the rules for coercion. As ' + 'the language\n' + 'has evolved, the coercion rules have become hard to ' + 'document\n' + 'precisely; documenting what one version of one particular\n' + 'implementation does is undesirable. Instead, here are some ' + 'informal\n' + 'guidelines regarding coercion. In Python 3, coercion will ' + 'not be\n' + 'supported.\n' + '\n' + '* If the left operand of a % operator is a string or Unicode ' + 'object,\n' + ' no coercion takes place and the string formatting ' + 'operation is\n' + ' invoked instead.\n' + '\n' + '* It is no longer recommended to define a coercion ' + 'operation. Mixed-\n' + " mode operations on types that don't define coercion pass " + 'the\n' + ' original arguments to the operation.\n' + '\n' + '* New-style classes (those derived from "object") never ' + 'invoke the\n' + ' "__coerce__()" method in response to a binary operator; ' + 'the only\n' + ' time "__coerce__()" is invoked is when the built-in ' + 'function\n' + ' "coerce()" is called.\n' + '\n' + '* For most intents and purposes, an operator that returns\n' + ' "NotImplemented" is treated the same as one that is not ' + 'implemented\n' + ' at all.\n' + '\n' + '* Below, "__op__()" and "__rop__()" are used to signify the ' + 'generic\n' + ' method names corresponding to an operator; "__iop__()" is ' + 'used for\n' + ' the corresponding in-place operator. For example, for the ' + 'operator\n' + ' \'"+"\', "__add__()" and "__radd__()" are used for the ' + 'left and right\n' + ' variant of the binary operator, and "__iadd__()" for the ' + 'in-place\n' + ' variant.\n' + '\n' + '* For objects *x* and *y*, first "x.__op__(y)" is tried. If ' + 'this is\n' + ' not implemented or returns "NotImplemented", ' + '"y.__rop__(x)" is\n' + ' tried. If this is also not implemented or returns ' + '"NotImplemented",\n' + ' a "TypeError" exception is raised. But see the following ' + 'exception:\n' + '\n' + '* Exception to the previous item: if the left operand is an ' + 'instance\n' + ' of a built-in type or a new-style class, and the right ' + 'operand is an\n' + ' instance of a proper subclass of that type or class and ' + 'overrides\n' + ' the base\'s "__rop__()" method, the right operand\'s ' + '"__rop__()"\n' + ' method is tried *before* the left operand\'s "__op__()" ' + 'method.\n' '\n' - 'object.__round__(self[, ndigits])\n' - 'object.__trunc__(self)\n' - 'object.__floor__(self)\n' - 'object.__ceil__(self)\n' + ' This is done so that a subclass can completely override ' + 'binary\n' + ' operators. Otherwise, the left operand\'s "__op__()" ' + 'method would\n' + ' always accept the right operand: when an instance of a ' + 'given class\n' + ' is expected, an instance of a subclass of that class is ' + 'always\n' + ' acceptable.\n' + '\n' + '* When either operand type defines a coercion, this coercion ' + 'is\n' + ' called before that type\'s "__op__()" or "__rop__()" ' + 'method is\n' + ' called, but no sooner. If the coercion returns an object ' + 'of a\n' + ' different type for the operand whose coercion is invoked, ' + 'part of\n' + ' the process is redone using the new object.\n' '\n' - ' Called to implement the built-in function "round()" and ' - '"math"\n' - ' functions "trunc()", "floor()" and "ceil()". Unless ' - '*ndigits* is\n' - ' passed to "__round__()" all these methods should return ' - 'the value\n' - ' of the object truncated to an "Integral" (typically an ' - '"int").\n' + '* When an in-place operator (like \'"+="\') is used, if the ' + 'left\n' + ' operand implements "__iop__()", it is invoked without any ' + 'coercion.\n' + ' When the operation falls back to "__op__()" and/or ' + '"__rop__()", the\n' + ' normal coercion rules apply.\n' '\n' - ' If "__int__()" is not defined then the built-in function ' - '"int()"\n' - ' falls back to "__trunc__()".\n' + '* In "x + y", if *x* is a sequence that implements sequence\n' + ' concatenation, sequence concatenation is invoked.\n' + '\n' + '* In "x * y", if one operand is a sequence that implements ' + 'sequence\n' + ' repetition, and the other is an integer ("int" or "long"), ' + 'sequence\n' + ' repetition is invoked.\n' + '\n' + '* Rich comparisons (implemented by methods "__eq__()" and so ' + 'on)\n' + ' never use coercion. Three-way comparison (implemented by\n' + ' "__cmp__()") does use coercion under the same conditions ' + 'as other\n' + ' binary operations use it.\n' + '\n' + '* In the current implementation, the built-in numeric types ' + '"int",\n' + ' "long", "float", and "complex" do not use coercion. All ' + 'these types\n' + ' implement a "__coerce__()" method, for use by the ' + 'built-in\n' + ' "coerce()" function.\n' + '\n' + ' Changed in version 2.7: The complex type no longer makes ' + 'implicit\n' + ' calls to the "__coerce__()" method for mixed-type binary ' + 'arithmetic\n' + ' operations.\n' '\n' '\n' 'With Statement Context Managers\n' '===============================\n' '\n' + 'New in version 2.5.\n' + '\n' 'A *context manager* is an object that defines the runtime ' 'context to\n' 'be established when executing a "with" statement. The ' @@ -9605,7 +8813,7 @@ topics = {'assert': 'The "assert" statement\n' '\n' ' Enter the runtime context related to this object. The ' '"with"\n' - ' statement will bind this method’s return value to the ' + " statement will bind this method's return value to the " 'target(s)\n' ' specified in the "as" clause of the statement, if any.\n' '\n' @@ -9629,30 +8837,62 @@ topics = {'assert': 'The "assert" statement\n' '\n' ' Note that "__exit__()" methods should not reraise the ' 'passed-in\n' - ' exception; this is the caller’s responsibility.\n' + " exception; this is the caller's responsibility.\n" '\n' 'See also:\n' '\n' - ' **PEP 343** - The “with” statement\n' + ' **PEP 343** - The "with" statement\n' ' The specification, background, and examples for the ' 'Python "with"\n' ' statement.\n' '\n' '\n' - 'Special method lookup\n' - '=====================\n' + 'Special method lookup for old-style classes\n' + '===========================================\n' '\n' - 'For custom classes, implicit invocations of special methods ' - 'are only\n' - 'guaranteed to work correctly if defined on an object’s type, ' - 'not in\n' - 'the object’s instance dictionary. That behaviour is the ' - 'reason why\n' - 'the following code raises an exception:\n' + 'For old-style classes, special methods are always looked up ' + 'in exactly\n' + 'the same way as any other method or attribute. This is the ' + 'case\n' + 'regardless of whether the method is being looked up ' + 'explicitly as in\n' + '"x.__getitem__(i)" or implicitly as in "x[i]".\n' + '\n' + 'This behaviour means that special methods may exhibit ' + 'different\n' + 'behaviour for different instances of a single old-style ' + 'class if the\n' + 'appropriate special attributes are set differently:\n' '\n' ' >>> class C:\n' ' ... pass\n' ' ...\n' + ' >>> c1 = C()\n' + ' >>> c2 = C()\n' + ' >>> c1.__len__ = lambda: 5\n' + ' >>> c2.__len__ = lambda: 9\n' + ' >>> len(c1)\n' + ' 5\n' + ' >>> len(c2)\n' + ' 9\n' + '\n' + '\n' + 'Special method lookup for new-style classes\n' + '===========================================\n' + '\n' + 'For new-style classes, implicit invocations of special ' + 'methods are\n' + "only guaranteed to work correctly if defined on an object's " + 'type, not\n' + "in the object's instance dictionary. That behaviour is the " + 'reason why\n' + 'the following code raises an exception (unlike the ' + 'equivalent example\n' + 'with old-style classes):\n' + '\n' + ' >>> class C(object):\n' + ' ... pass\n' + ' ...\n' ' >>> c = C()\n' ' >>> c.__len__ = lambda: 5\n' ' >>> len(c)\n' @@ -9680,7 +8920,7 @@ topics = {'assert': 'The "assert" statement\n' '\n' 'Incorrectly attempting to invoke an unbound method of a ' 'class in this\n' - 'way is sometimes referred to as ‘metaclass confusion’, and ' + "way is sometimes referred to as 'metaclass confusion', and " 'is avoided\n' 'by bypassing the instance when looking up special methods:\n' '\n' @@ -9693,19 +8933,20 @@ topics = {'assert': 'The "assert" statement\n' 'interest of\n' 'correctness, implicit special method lookup generally also ' 'bypasses\n' - 'the "__getattribute__()" method even of the object’s ' + 'the "__getattribute__()" method even of the object\'s ' 'metaclass:\n' '\n' ' >>> class Meta(type):\n' - ' ... def __getattribute__(*args):\n' - ' ... print("Metaclass getattribute invoked")\n' - ' ... return type.__getattribute__(*args)\n' + ' ... def __getattribute__(*args):\n' + ' ... print "Metaclass getattribute invoked"\n' + ' ... return type.__getattribute__(*args)\n' ' ...\n' - ' >>> class C(object, metaclass=Meta):\n' + ' >>> class C(object):\n' + ' ... __metaclass__ = Meta\n' ' ... def __len__(self):\n' ' ... return 10\n' ' ... def __getattribute__(*args):\n' - ' ... print("Class getattribute invoked")\n' + ' ... print "Class getattribute invoked"\n' ' ... return object.__getattribute__(*args)\n' ' ...\n' ' >>> c = C()\n' @@ -9728,32 +8969,45 @@ topics = {'assert': 'The "assert" statement\n' 'methods (the\n' 'special method *must* be set on the class object itself in ' 'order to be\n' - 'consistently invoked by the interpreter).\n', - 'string-methods': 'String Methods\n' + 'consistently invoked by the interpreter).\n' + '\n' + '-[ Footnotes ]-\n' + '\n' + "[1] It *is* possible in some cases to change an object's " + 'type,\n' + " under certain controlled conditions. It generally isn't " + 'a good\n' + ' idea though, since it can lead to some very strange ' + 'behaviour if\n' + ' it is handled incorrectly.\n' + '\n' + '[2] For operands of the same type, it is assumed that if the ' + 'non-\n' + ' reflected method (such as "__add__()") fails the ' + 'operation is not\n' + ' supported, which is why the reflected method is not ' + 'called.\n', + 'string-methods': '\n' + 'String Methods\n' '**************\n' '\n' - 'Strings implement all of the common sequence operations, ' - 'along with\n' - 'the additional methods described below.\n' - '\n' - 'Strings also support two styles of string formatting, one ' - 'providing a\n' - 'large degree of flexibility and customization (see ' - '"str.format()",\n' - 'Format String Syntax and Custom String Formatting) and the ' - 'other based\n' - 'on C "printf" style formatting that handles a narrower ' - 'range of types\n' - 'and is slightly harder to use correctly, but is often ' - 'faster for the\n' - 'cases it can handle (printf-style String Formatting).\n' - '\n' - 'The Text Processing Services section of the standard ' - 'library covers a\n' - 'number of other modules that provide various text related ' - 'utilities\n' - '(including regular expression support in the "re" ' - 'module).\n' + 'Below are listed the string methods which both 8-bit ' + 'strings and\n' + 'Unicode objects support. Some of them are also available ' + 'on\n' + '"bytearray" objects.\n' + '\n' + "In addition, Python's strings support the sequence type " + 'methods\n' + 'described in the Sequence Types --- str, unicode, list, ' + 'tuple,\n' + 'bytearray, buffer, xrange section. To output formatted ' + 'strings use\n' + 'template strings or the "%" operator described in the ' + 'String\n' + 'Formatting Operations section. Also, see the "re" module ' + 'for string\n' + 'functions based on regular expressions.\n' '\n' 'str.capitalize()\n' '\n' @@ -9761,45 +9015,16 @@ topics = {'assert': 'The "assert" statement\n' 'capitalized\n' ' and the rest lowercased.\n' '\n' - ' Changed in version 3.8: The first character is now put ' - 'into\n' - ' titlecase rather than uppercase. This means that ' - 'characters like\n' - ' digraphs will only have their first letter capitalized, ' - 'instead of\n' - ' the full character.\n' - '\n' - 'str.casefold()\n' - '\n' - ' Return a casefolded copy of the string. Casefolded ' - 'strings may be\n' - ' used for caseless matching.\n' - '\n' - ' Casefolding is similar to lowercasing but more ' - 'aggressive because\n' - ' it is intended to remove all case distinctions in a ' - 'string. For\n' - ' example, the German lowercase letter "\'ß\'" is ' - 'equivalent to ""ss"".\n' - ' Since it is already lowercase, "lower()" would do ' - 'nothing to "\'ß\'";\n' - ' "casefold()" converts it to ""ss"".\n' - '\n' - ' The casefolding algorithm is described in section 3.13 ' - 'of the\n' - ' Unicode Standard.\n' - '\n' - ' New in version 3.3.\n' + ' For 8-bit strings, this method is locale-dependent.\n' '\n' 'str.center(width[, fillchar])\n' '\n' ' Return centered in a string of length *width*. Padding ' 'is done\n' - ' using the specified *fillchar* (default is an ASCII ' - 'space). The\n' - ' original string is returned if *width* is less than or ' - 'equal to\n' - ' "len(s)".\n' + ' using the specified *fillchar* (default is a space).\n' + '\n' + ' Changed in version 2.4: Support for the *fillchar* ' + 'argument.\n' '\n' 'str.count(sub[, start[, end]])\n' '\n' @@ -9809,38 +9034,59 @@ topics = {'assert': 'The "assert" statement\n' '*start* and\n' ' *end* are interpreted as in slice notation.\n' '\n' - 'str.encode(encoding="utf-8", errors="strict")\n' - '\n' - ' Return an encoded version of the string as a bytes ' - 'object. Default\n' - ' encoding is "\'utf-8\'". *errors* may be given to set a ' - 'different\n' - ' error handling scheme. The default for *errors* is ' - '"\'strict\'",\n' - ' meaning that encoding errors raise a "UnicodeError". ' - 'Other possible\n' - ' values are "\'ignore\'", "\'replace\'", ' - '"\'xmlcharrefreplace\'",\n' - ' "\'backslashreplace\'" and any other name registered ' - 'via\n' - ' "codecs.register_error()", see section Error Handlers. ' - 'For a list\n' - ' of possible encodings, see section Standard Encodings.\n' - '\n' - ' By default, the *errors* argument is not checked for ' - 'best\n' - ' performances, but only used at the first encoding ' - 'error. Enable the\n' - ' development mode ("-X" "dev" option), or use a debug ' - 'build, to\n' - ' check *errors*.\n' - '\n' - ' Changed in version 3.1: Support for keyword arguments ' + 'str.decode([encoding[, errors]])\n' + '\n' + ' Decodes the string using the codec registered for ' + '*encoding*.\n' + ' *encoding* defaults to the default string encoding. ' + '*errors* may\n' + ' be given to set a different error handling scheme. The ' + 'default is\n' + ' "\'strict\'", meaning that encoding errors raise ' + '"UnicodeError".\n' + ' Other possible values are "\'ignore\'", "\'replace\'" ' + 'and any other\n' + ' name registered via "codecs.register_error()", see ' + 'section Codec\n' + ' Base Classes.\n' + '\n' + ' New in version 2.2.\n' + '\n' + ' Changed in version 2.3: Support for other error ' + 'handling schemes\n' + ' added.\n' + '\n' + ' Changed in version 2.7: Support for keyword arguments ' 'added.\n' '\n' - ' Changed in version 3.9: The *errors* is now checked in ' - 'development\n' - ' mode and in debug mode.\n' + 'str.encode([encoding[, errors]])\n' + '\n' + ' Return an encoded version of the string. Default ' + 'encoding is the\n' + ' current default string encoding. *errors* may be given ' + 'to set a\n' + ' different error handling scheme. The default for ' + '*errors* is\n' + ' "\'strict\'", meaning that encoding errors raise a ' + '"UnicodeError".\n' + ' Other possible values are "\'ignore\'", "\'replace\'",\n' + ' "\'xmlcharrefreplace\'", "\'backslashreplace\'" and any ' + 'other name\n' + ' registered via "codecs.register_error()", see section ' + 'Codec Base\n' + ' Classes. For a list of possible encodings, see section ' + 'Standard\n' + ' Encodings.\n' + '\n' + ' New in version 2.0.\n' + '\n' + ' Changed in version 2.3: Support for ' + '"\'xmlcharrefreplace\'" and\n' + ' "\'backslashreplace\'" and other error handling schemes ' + 'added.\n' + '\n' + ' Changed in version 2.7: Support for keyword arguments ' + 'added.\n' '\n' 'str.endswith(suffix[, start[, end]])\n' '\n' @@ -9853,7 +9099,9 @@ topics = {'assert': 'The "assert" statement\n' ' position. With optional *end*, stop comparing at that ' 'position.\n' '\n' - 'str.expandtabs(tabsize=8)\n' + ' Changed in version 2.5: Accept tuples as *suffix*.\n' + '\n' + 'str.expandtabs([tabsize])\n' '\n' ' Return a copy of the string where all tab characters ' 'are replaced\n' @@ -9929,45 +9177,13 @@ topics = {'assert': 'The "assert" statement\n' ' formatting options that can be specified in format ' 'strings.\n' '\n' - ' Note: When formatting a number ("int", "float", ' - '"complex",\n' - ' "decimal.Decimal" and subclasses) with the "n" type ' - '(ex:\n' - ' "\'{:n}\'.format(1234)"), the function temporarily ' - 'sets the\n' - ' "LC_CTYPE" locale to the "LC_NUMERIC" locale to ' - 'decode\n' - ' "decimal_point" and "thousands_sep" fields of ' - '"localeconv()" if\n' - ' they are non-ASCII or longer than 1 byte, and the ' - '"LC_NUMERIC"\n' - ' locale is different than the "LC_CTYPE" locale. This ' - 'temporary\n' - ' change affects other threads.\n' - '\n' - ' Changed in version 3.7: When formatting a number with ' - 'the "n" type,\n' - ' the function sets temporarily the "LC_CTYPE" locale to ' - 'the\n' - ' "LC_NUMERIC" locale in some cases.\n' + ' This method of string formatting is the new standard in ' + 'Python 3,\n' + ' and should be preferred to the "%" formatting described ' + 'in String\n' + ' Formatting Operations in new code.\n' '\n' - 'str.format_map(mapping)\n' - '\n' - ' Similar to "str.format(**mapping)", except that ' - '"mapping" is used\n' - ' directly and not copied to a "dict". This is useful if ' - 'for example\n' - ' "mapping" is a dict subclass:\n' - '\n' - ' >>> class Default(dict):\n' - ' ... def __missing__(self, key):\n' - ' ... return key\n' - ' ...\n' - " >>> '{name} was born in " - "{country}'.format_map(Default(name='Guido'))\n" - " 'Guido was born in country'\n" - '\n' - ' New in version 3.2.\n' + ' New in version 2.6.\n' '\n' 'str.index(sub[, start[, end]])\n' '\n' @@ -9977,172 +9193,65 @@ topics = {'assert': 'The "assert" statement\n' '\n' 'str.isalnum()\n' '\n' - ' Return "True" if all characters in the string are ' + ' Return true if all characters in the string are ' 'alphanumeric and\n' - ' there is at least one character, "False" otherwise. A ' - 'character\n' - ' "c" is alphanumeric if one of the following returns ' - '"True":\n' - ' "c.isalpha()", "c.isdecimal()", "c.isdigit()", or ' - '"c.isnumeric()".\n' + ' there is at least one character, false otherwise.\n' + '\n' + ' For 8-bit strings, this method is locale-dependent.\n' '\n' 'str.isalpha()\n' '\n' - ' Return "True" if all characters in the string are ' + ' Return true if all characters in the string are ' 'alphabetic and\n' - ' there is at least one character, "False" otherwise. ' - 'Alphabetic\n' - ' characters are those characters defined in the Unicode ' - 'character\n' - ' database as “Letter”, i.e., those with general category ' - 'property\n' - ' being one of “Lm”, “Lt”, “Lu”, “Ll”, or “Lo”. Note ' - 'that this is\n' - ' different from the “Alphabetic” property defined in the ' - 'Unicode\n' - ' Standard.\n' - '\n' - 'str.isascii()\n' - '\n' - ' Return "True" if the string is empty or all characters ' - 'in the\n' - ' string are ASCII, "False" otherwise. ASCII characters ' - 'have code\n' - ' points in the range U+0000-U+007F.\n' - '\n' - ' New in version 3.7.\n' + ' there is at least one character, false otherwise.\n' '\n' - 'str.isdecimal()\n' - '\n' - ' Return "True" if all characters in the string are ' - 'decimal\n' - ' characters and there is at least one character, "False" ' - 'otherwise.\n' - ' Decimal characters are those that can be used to form ' - 'numbers in\n' - ' base 10, e.g. U+0660, ARABIC-INDIC DIGIT ZERO. ' - 'Formally a decimal\n' - ' character is a character in the Unicode General ' - 'Category “Nd”.\n' + ' For 8-bit strings, this method is locale-dependent.\n' '\n' 'str.isdigit()\n' '\n' - ' Return "True" if all characters in the string are ' - 'digits and there\n' - ' is at least one character, "False" otherwise. Digits ' - 'include\n' - ' decimal characters and digits that need special ' - 'handling, such as\n' - ' the compatibility superscript digits. This covers ' - 'digits which\n' - ' cannot be used to form numbers in base 10, like the ' - 'Kharosthi\n' - ' numbers. Formally, a digit is a character that has the ' - 'property\n' - ' value Numeric_Type=Digit or Numeric_Type=Decimal.\n' - '\n' - 'str.isidentifier()\n' - '\n' - ' Return "True" if the string is a valid identifier ' - 'according to the\n' - ' language definition, section Identifiers and keywords.\n' - '\n' - ' Call "keyword.iskeyword()" to test whether string "s" ' - 'is a reserved\n' - ' identifier, such as "def" and "class".\n' + ' Return true if all characters in the string are digits ' + 'and there is\n' + ' at least one character, false otherwise.\n' '\n' - ' Example:\n' - '\n' - ' >>> from keyword import iskeyword\n' - '\n' - " >>> 'hello'.isidentifier(), iskeyword('hello')\n" - ' True, False\n' - " >>> 'def'.isidentifier(), iskeyword('def')\n" - ' True, True\n' + ' For 8-bit strings, this method is locale-dependent.\n' '\n' 'str.islower()\n' '\n' - ' Return "True" if all cased characters [4] in the string ' - 'are\n' - ' lowercase and there is at least one cased character, ' - '"False"\n' - ' otherwise.\n' + ' Return true if all cased characters [4] in the string ' + 'are lowercase\n' + ' and there is at least one cased character, false ' + 'otherwise.\n' '\n' - 'str.isnumeric()\n' - '\n' - ' Return "True" if all characters in the string are ' - 'numeric\n' - ' characters, and there is at least one character, ' - '"False" otherwise.\n' - ' Numeric characters include digit characters, and all ' - 'characters\n' - ' that have the Unicode numeric value property, e.g. ' - 'U+2155, VULGAR\n' - ' FRACTION ONE FIFTH. Formally, numeric characters are ' - 'those with\n' - ' the property value Numeric_Type=Digit, ' - 'Numeric_Type=Decimal or\n' - ' Numeric_Type=Numeric.\n' - '\n' - 'str.isprintable()\n' - '\n' - ' Return "True" if all characters in the string are ' - 'printable or the\n' - ' string is empty, "False" otherwise. Nonprintable ' - 'characters are\n' - ' those characters defined in the Unicode character ' - 'database as\n' - ' “Other” or “Separator”, excepting the ASCII space ' - '(0x20) which is\n' - ' considered printable. (Note that printable characters ' - 'in this\n' - ' context are those which should not be escaped when ' - '"repr()" is\n' - ' invoked on a string. It has no bearing on the handling ' - 'of strings\n' - ' written to "sys.stdout" or "sys.stderr".)\n' + ' For 8-bit strings, this method is locale-dependent.\n' '\n' 'str.isspace()\n' '\n' - ' Return "True" if there are only whitespace characters ' - 'in the string\n' - ' and there is at least one character, "False" ' - 'otherwise.\n' + ' Return true if there are only whitespace characters in ' + 'the string\n' + ' and there is at least one character, false otherwise.\n' '\n' - ' A character is *whitespace* if in the Unicode character ' - 'database\n' - ' (see "unicodedata"), either its general category is ' - '"Zs"\n' - ' (“Separator, space”), or its bidirectional class is one ' - 'of "WS",\n' - ' "B", or "S".\n' + ' For 8-bit strings, this method is locale-dependent.\n' '\n' 'str.istitle()\n' '\n' - ' Return "True" if the string is a titlecased string and ' + ' Return true if the string is a titlecased string and ' 'there is at\n' ' least one character, for example uppercase characters ' 'may only\n' ' follow uncased characters and lowercase characters only ' 'cased ones.\n' - ' Return "False" otherwise.\n' + ' Return false otherwise.\n' + '\n' + ' For 8-bit strings, this method is locale-dependent.\n' '\n' 'str.isupper()\n' '\n' - ' Return "True" if all cased characters [4] in the string ' - 'are\n' - ' uppercase and there is at least one cased character, ' - '"False"\n' - ' otherwise.\n' - '\n' - " >>> 'BANANA'.isupper()\n" - ' True\n' - " >>> 'banana'.isupper()\n" - ' False\n' - " >>> 'baNana'.isupper()\n" - ' False\n' - " >>> ' '.isupper()\n" - ' False\n' + ' Return true if all cased characters [4] in the string ' + 'are uppercase\n' + ' and there is at least one cased character, false ' + 'otherwise.\n' + '\n' + ' For 8-bit strings, this method is locale-dependent.\n' '\n' 'str.join(iterable)\n' '\n' @@ -10160,20 +9269,21 @@ topics = {'assert': 'The "assert" statement\n' ' Return the string left justified in a string of length ' '*width*.\n' ' Padding is done using the specified *fillchar* (default ' - 'is an ASCII\n' - ' space). The original string is returned if *width* is ' + 'is a\n' + ' space). The original string is returned if *width* is ' 'less than or\n' ' equal to "len(s)".\n' '\n' + ' Changed in version 2.4: Support for the *fillchar* ' + 'argument.\n' + '\n' 'str.lower()\n' '\n' ' Return a copy of the string with all the cased ' 'characters [4]\n' ' converted to lowercase.\n' '\n' - ' The lowercasing algorithm used is described in section ' - '3.13 of the\n' - ' Unicode Standard.\n' + ' For 8-bit strings, this method is locale-dependent.\n' '\n' 'str.lstrip([chars])\n' '\n' @@ -10187,34 +9297,13 @@ topics = {'assert': 'The "assert" statement\n' 'prefix; rather,\n' ' all combinations of its values are stripped:\n' '\n' - " >>> ' spacious '.lstrip()\n" - " 'spacious '\n" - " >>> 'www.example.com'.lstrip('cmowz.')\n" - " 'example.com'\n" - '\n' - 'static str.maketrans(x[, y[, z]])\n' - '\n' - ' This static method returns a translation table usable ' - 'for\n' - ' "str.translate()".\n' - '\n' - ' If there is only one argument, it must be a dictionary ' - 'mapping\n' - ' Unicode ordinals (integers) or characters (strings of ' - 'length 1) to\n' - ' Unicode ordinals, strings (of arbitrary lengths) or ' - '"None".\n' - ' Character keys will then be converted to ordinals.\n' - '\n' - ' If there are two arguments, they must be strings of ' - 'equal length,\n' - ' and in the resulting dictionary, each character in x ' - 'will be mapped\n' - ' to the character at the same position in y. If there ' - 'is a third\n' - ' argument, it must be a string, whose characters will be ' - 'mapped to\n' - ' "None" in the result.\n' + " >>> ' spacious '.lstrip()\n" + " 'spacious '\n" + " >>> 'www.example.com'.lstrip('cmowz.')\n" + " 'example.com'\n" + '\n' + ' Changed in version 2.2.2: Support for the *chars* ' + 'argument.\n' '\n' 'str.partition(sep)\n' '\n' @@ -10228,6 +9317,8 @@ topics = {'assert': 'The "assert" statement\n' 'followed by\n' ' two empty strings.\n' '\n' + ' New in version 2.5.\n' + '\n' 'str.replace(old, new[, count])\n' '\n' ' Return a copy of the string with all occurrences of ' @@ -10257,11 +9348,14 @@ topics = {'assert': 'The "assert" statement\n' ' Return the string right justified in a string of length ' '*width*.\n' ' Padding is done using the specified *fillchar* (default ' - 'is an ASCII\n' + 'is a\n' ' space). The original string is returned if *width* is ' 'less than or\n' ' equal to "len(s)".\n' '\n' + ' Changed in version 2.4: Support for the *fillchar* ' + 'argument.\n' + '\n' 'str.rpartition(sep)\n' '\n' ' Split the string at the last occurrence of *sep*, and ' @@ -10274,7 +9368,9 @@ topics = {'assert': 'The "assert" statement\n' 'followed by\n' ' the string itself.\n' '\n' - 'str.rsplit(sep=None, maxsplit=-1)\n' + ' New in version 2.5.\n' + '\n' + 'str.rsplit([sep[, maxsplit]])\n' '\n' ' Return a list of the words in the string, using *sep* ' 'as the\n' @@ -10288,6 +9384,8 @@ topics = {'assert': 'The "assert" statement\n' 'is\n' ' described in detail below.\n' '\n' + ' New in version 2.4.\n' + '\n' 'str.rstrip([chars])\n' '\n' ' Return a copy of the string with trailing characters ' @@ -10300,12 +9398,15 @@ topics = {'assert': 'The "assert" statement\n' 'suffix; rather,\n' ' all combinations of its values are stripped:\n' '\n' - " >>> ' spacious '.rstrip()\n" - " ' spacious'\n" - " >>> 'mississippi'.rstrip('ipz')\n" - " 'mississ'\n" + " >>> ' spacious '.rstrip()\n" + " ' spacious'\n" + " >>> 'mississippi'.rstrip('ipz')\n" + " 'mississ'\n" + '\n' + ' Changed in version 2.2.2: Support for the *chars* ' + 'argument.\n' '\n' - 'str.split(sep=None, maxsplit=-1)\n' + 'str.split([sep[, maxsplit]])\n' '\n' ' Return a list of the words in the string, using *sep* ' 'as the\n' @@ -10329,15 +9430,6 @@ topics = {'assert': 'The "assert" statement\n' ' empty string with a specified separator returns ' '"[\'\']".\n' '\n' - ' For example:\n' - '\n' - " >>> '1,2,3'.split(',')\n" - " ['1', '2', '3']\n" - " >>> '1,2,3'.split(',', maxsplit=1)\n" - " ['1', '2,3']\n" - " >>> '1,2,,3,'.split(',')\n" - " ['1', '2', '', '3', '']\n" - '\n' ' If *sep* is not specified or is "None", a different ' 'splitting\n' ' algorithm is applied: runs of consecutive whitespace ' @@ -10351,34 +9443,66 @@ topics = {'assert': 'The "assert" statement\n' ' consisting of just whitespace with a "None" separator ' 'returns "[]".\n' '\n' - ' For example:\n' - '\n' - " >>> '1 2 3'.split()\n" - " ['1', '2', '3']\n" - " >>> '1 2 3'.split(maxsplit=1)\n" - " ['1', '2 3']\n" - " >>> ' 1 2 3 '.split()\n" - " ['1', '2', '3']\n" + ' For example, "\' 1 2 3 \'.split()" returns "[\'1\', ' + '\'2\', \'3\']", and\n' + ' "\' 1 2 3 \'.split(None, 1)" returns "[\'1\', ' + '\'2 3 \']".\n' '\n' 'str.splitlines([keepends])\n' '\n' ' Return a list of the lines in the string, breaking at ' 'line\n' - ' boundaries. Line breaks are not included in the ' + ' boundaries. This method uses the *universal newlines* ' + 'approach to\n' + ' splitting lines. Line breaks are not included in the ' 'resulting list\n' ' unless *keepends* is given and true.\n' '\n' - ' This method splits on the following line boundaries. ' - 'In\n' - ' particular, the boundaries are a superset of *universal ' - 'newlines*.\n' + ' Python recognizes ""\\r"", ""\\n"", and ""\\r\\n"" as ' + 'line boundaries\n' + ' for 8-bit strings.\n' + '\n' + ' For example:\n' + '\n' + " >>> 'ab c\\n\\nde fg\\rkl\\r\\n'.splitlines()\n" + " ['ab c', '', 'de fg', 'kl']\n" + " >>> 'ab c\\n\\nde fg\\rkl\\r\\n'.splitlines(True)\n" + " ['ab c\\n', '\\n', 'de fg\\r', 'kl\\r\\n']\n" + '\n' + ' Unlike "split()" when a delimiter string *sep* is ' + 'given, this\n' + ' method returns an empty list for the empty string, and ' + 'a terminal\n' + ' line break does not result in an extra line:\n' + '\n' + ' >>> "".splitlines()\n' + ' []\n' + ' >>> "One line\\n".splitlines()\n' + " ['One line']\n" + '\n' + ' For comparison, "split(\'\\n\')" gives:\n' + '\n' + " >>> ''.split('\\n')\n" + " ['']\n" + " >>> 'Two lines\\n'.split('\\n')\n" + " ['Two lines', '']\n" + '\n' + 'unicode.splitlines([keepends])\n' + '\n' + ' Return a list of the lines in the string, like ' + '"str.splitlines()".\n' + ' However, the Unicode method splits on the following ' + 'line\n' + ' boundaries, which are a superset of the *universal ' + 'newlines*\n' + ' recognized for 8-bit strings.\n' '\n' ' ' '+-------------------------+-------------------------------+\n' ' | Representation | ' 'Description |\n' ' ' - '|=========================|===============================|\n' + '+=========================+===============================+\n' ' | "\\n" | Line ' 'Feed |\n' ' ' @@ -10424,36 +9548,10 @@ topics = {'assert': 'The "assert" statement\n' ' ' '+-------------------------+-------------------------------+\n' '\n' - ' Changed in version 3.2: "\\v" and "\\f" added to list ' + ' Changed in version 2.7: "\\v" and "\\f" added to list ' 'of line\n' ' boundaries.\n' '\n' - ' For example:\n' - '\n' - " >>> 'ab c\\n\\nde fg\\rkl\\r\\n'.splitlines()\n" - " ['ab c', '', 'de fg', 'kl']\n" - " >>> 'ab c\\n\\nde " - "fg\\rkl\\r\\n'.splitlines(keepends=True)\n" - " ['ab c\\n', '\\n', 'de fg\\r', 'kl\\r\\n']\n" - '\n' - ' Unlike "split()" when a delimiter string *sep* is ' - 'given, this\n' - ' method returns an empty list for the empty string, and ' - 'a terminal\n' - ' line break does not result in an extra line:\n' - '\n' - ' >>> "".splitlines()\n' - ' []\n' - ' >>> "One line\\n".splitlines()\n' - " ['One line']\n" - '\n' - ' For comparison, "split(\'\\n\')" gives:\n' - '\n' - " >>> ''.split('\\n')\n" - " ['']\n" - " >>> 'Two lines\\n'.split('\\n')\n" - " ['Two lines', '']\n" - '\n' 'str.startswith(prefix[, start[, end]])\n' '\n' ' Return "True" if string starts with the *prefix*, ' @@ -10465,6 +9563,8 @@ topics = {'assert': 'The "assert" statement\n' ' With optional *end*, stop comparing string at that ' 'position.\n' '\n' + ' Changed in version 2.5: Accept tuples as *prefix*.\n' + '\n' 'str.strip([chars])\n' '\n' ' Return a copy of the string with the leading and ' @@ -10479,33 +9579,21 @@ topics = {'assert': 'The "assert" statement\n' 'values are\n' ' stripped:\n' '\n' - " >>> ' spacious '.strip()\n" - " 'spacious'\n" - " >>> 'www.example.com'.strip('cmowz.')\n" - " 'example'\n" + " >>> ' spacious '.strip()\n" + " 'spacious'\n" + " >>> 'www.example.com'.strip('cmowz.')\n" + " 'example'\n" '\n' - ' The outermost leading and trailing *chars* argument ' - 'values are\n' - ' stripped from the string. Characters are removed from ' - 'the leading\n' - ' end until reaching a string character that is not ' - 'contained in the\n' - ' set of characters in *chars*. A similar action takes ' - 'place on the\n' - ' trailing end. For example:\n' - '\n' - " >>> comment_string = '#....... Section 3.2.1 Issue " - "#32 .......'\n" - " >>> comment_string.strip('.#! ')\n" - " 'Section 3.2.1 Issue #32'\n" + ' Changed in version 2.2.2: Support for the *chars* ' + 'argument.\n' '\n' 'str.swapcase()\n' '\n' ' Return a copy of the string with uppercase characters ' 'converted to\n' - ' lowercase and vice versa. Note that it is not ' - 'necessarily true that\n' - ' "s.swapcase().swapcase() == s".\n' + ' lowercase and vice versa.\n' + '\n' + ' For 8-bit strings, this method is locale-dependent.\n' '\n' 'str.title()\n' '\n' @@ -10514,11 +9602,6 @@ topics = {'assert': 'The "assert" statement\n' ' uppercase character and the remaining characters are ' 'lowercase.\n' '\n' - ' For example:\n' - '\n' - " >>> 'Hello world'.title()\n" - " 'Hello World'\n" - '\n' ' The algorithm uses a simple language-independent ' 'definition of a\n' ' word as groups of consecutive letters. The definition ' @@ -10540,185 +9623,184 @@ topics = {'assert': 'The "assert" statement\n' ' >>> def titlecase(s):\n' ' ... return re.sub(r"[A-Za-z]+(\'[A-Za-z]+)?",\n' ' ... lambda mo: ' - 'mo.group(0).capitalize(),\n' + 'mo.group(0)[0].upper() +\n' + ' ... ' + 'mo.group(0)[1:].lower(),\n' ' ... s)\n' ' ...\n' ' >>> titlecase("they\'re bill\'s friends.")\n' ' "They\'re Bill\'s Friends."\n' '\n' - 'str.translate(table)\n' - '\n' - ' Return a copy of the string in which each character has ' - 'been mapped\n' - ' through the given translation table. The table must be ' - 'an object\n' - ' that implements indexing via "__getitem__()", typically ' - 'a *mapping*\n' - ' or *sequence*. When indexed by a Unicode ordinal (an ' - 'integer), the\n' - ' table object can do any of the following: return a ' - 'Unicode ordinal\n' - ' or a string, to map the character to one or more other ' - 'characters;\n' - ' return "None", to delete the character from the return ' - 'string; or\n' - ' raise a "LookupError" exception, to map the character ' - 'to itself.\n' - '\n' - ' You can use "str.maketrans()" to create a translation ' - 'map from\n' - ' character-to-character mappings in different formats.\n' - '\n' - ' See also the "codecs" module for a more flexible ' - 'approach to custom\n' - ' character mappings.\n' + ' For 8-bit strings, this method is locale-dependent.\n' + '\n' + 'str.translate(table[, deletechars])\n' + '\n' + ' Return a copy of the string where all characters ' + 'occurring in the\n' + ' optional argument *deletechars* are removed, and the ' + 'remaining\n' + ' characters have been mapped through the given ' + 'translation table,\n' + ' which must be a string of length 256.\n' + '\n' + ' You can use the "maketrans()" helper function in the ' + '"string"\n' + ' module to create a translation table. For string ' + 'objects, set the\n' + ' *table* argument to "None" for translations that only ' + 'delete\n' + ' characters:\n' + '\n' + " >>> 'read this short text'.translate(None, 'aeiou')\n" + " 'rd ths shrt txt'\n" + '\n' + ' New in version 2.6: Support for a "None" *table* ' + 'argument.\n' + '\n' + ' For Unicode objects, the "translate()" method does not ' + 'accept the\n' + ' optional *deletechars* argument. Instead, it returns a ' + 'copy of the\n' + ' *s* where all characters have been mapped through the ' + 'given\n' + ' translation table which must be a mapping of Unicode ' + 'ordinals to\n' + ' Unicode ordinals, Unicode strings or "None". Unmapped ' + 'characters\n' + ' are left untouched. Characters mapped to "None" are ' + 'deleted. Note,\n' + ' a more flexible approach is to create a custom ' + 'character mapping\n' + ' codec using the "codecs" module (see "encodings.cp1251" ' + 'for an\n' + ' example).\n' '\n' 'str.upper()\n' '\n' ' Return a copy of the string with all the cased ' 'characters [4]\n' ' converted to uppercase. Note that ' - '"s.upper().isupper()" might be\n' + '"str.upper().isupper()" might be\n' ' "False" if "s" contains uncased characters or if the ' 'Unicode\n' - ' category of the resulting character(s) is not “Lu” ' + ' category of the resulting character(s) is not "Lu" ' '(Letter,\n' - ' uppercase), but e.g. “Lt” (Letter, titlecase).\n' + ' uppercase), but e.g. "Lt" (Letter, titlecase).\n' '\n' - ' The uppercasing algorithm used is described in section ' - '3.13 of the\n' - ' Unicode Standard.\n' + ' For 8-bit strings, this method is locale-dependent.\n' '\n' 'str.zfill(width)\n' '\n' - ' Return a copy of the string left filled with ASCII ' - '"\'0\'" digits to\n' - ' make a string of length *width*. A leading sign prefix\n' - ' ("\'+\'"/"\'-\'") is handled by inserting the padding ' - '*after* the sign\n' - ' character rather than before. The original string is ' - 'returned if\n' - ' *width* is less than or equal to "len(s)".\n' - '\n' - ' For example:\n' - '\n' - ' >>> "42".zfill(5)\n' - " '00042'\n" - ' >>> "-42".zfill(5)\n' - " '-0042'\n", - 'strings': 'String and Bytes literals\n' - '*************************\n' + ' Return the numeric string left filled with zeros in a ' + 'string of\n' + ' length *width*. A sign prefix is handled correctly. ' + 'The original\n' + ' string is returned if *width* is less than or equal to ' + '"len(s)".\n' + '\n' + ' New in version 2.2.2.\n' + '\n' + 'The following methods are present only on unicode ' + 'objects:\n' + '\n' + 'unicode.isnumeric()\n' + '\n' + ' Return "True" if there are only numeric characters in ' + 'S, "False"\n' + ' otherwise. Numeric characters include digit characters, ' + 'and all\n' + ' characters that have the Unicode numeric value ' + 'property, e.g.\n' + ' U+2155, VULGAR FRACTION ONE FIFTH.\n' + '\n' + 'unicode.isdecimal()\n' + '\n' + ' Return "True" if there are only decimal characters in ' + 'S, "False"\n' + ' otherwise. Decimal characters include digit characters, ' + 'and all\n' + ' characters that can be used to form decimal-radix ' + 'numbers, e.g.\n' + ' U+0660, ARABIC-INDIC DIGIT ZERO.\n', + 'strings': '\n' + 'String literals\n' + '***************\n' '\n' 'String literals are described by the following lexical ' 'definitions:\n' '\n' ' stringliteral ::= [stringprefix](shortstring | longstring)\n' - ' stringprefix ::= "r" | "u" | "R" | "U" | "f" | "F"\n' - ' | "fr" | "Fr" | "fR" | "FR" | "rf" | "rF" | ' - '"Rf" | "RF"\n' + ' stringprefix ::= "r" | "u" | "ur" | "R" | "U" | "UR" | "Ur" ' + '| "uR"\n' + ' | "b" | "B" | "br" | "Br" | "bR" | "BR"\n' ' shortstring ::= "\'" shortstringitem* "\'" | \'"\' ' 'shortstringitem* \'"\'\n' - ' longstring ::= "\'\'\'" longstringitem* "\'\'\'" | ' - '\'"""\' longstringitem* \'"""\'\n' - ' shortstringitem ::= shortstringchar | stringescapeseq\n' - ' longstringitem ::= longstringchar | stringescapeseq\n' + ' longstring ::= "\'\'\'" longstringitem* "\'\'\'"\n' + ' | \'"""\' longstringitem* \'"""\'\n' + ' shortstringitem ::= shortstringchar | escapeseq\n' + ' longstringitem ::= longstringchar | escapeseq\n' ' shortstringchar ::= <any source character except "\\" or ' 'newline or the quote>\n' ' longstringchar ::= <any source character except "\\">\n' - ' stringescapeseq ::= "\\" <any source character>\n' - '\n' - ' bytesliteral ::= bytesprefix(shortbytes | longbytes)\n' - ' bytesprefix ::= "b" | "B" | "br" | "Br" | "bR" | "BR" | ' - '"rb" | "rB" | "Rb" | "RB"\n' - ' shortbytes ::= "\'" shortbytesitem* "\'" | \'"\' ' - 'shortbytesitem* \'"\'\n' - ' longbytes ::= "\'\'\'" longbytesitem* "\'\'\'" | \'"""\' ' - 'longbytesitem* \'"""\'\n' - ' shortbytesitem ::= shortbyteschar | bytesescapeseq\n' - ' longbytesitem ::= longbyteschar | bytesescapeseq\n' - ' shortbyteschar ::= <any ASCII character except "\\" or newline ' - 'or the quote>\n' - ' longbyteschar ::= <any ASCII character except "\\">\n' - ' bytesescapeseq ::= "\\" <any ASCII character>\n' + ' escapeseq ::= "\\" <any ASCII character>\n' '\n' 'One syntactic restriction not indicated by these productions is ' 'that\n' - 'whitespace is not allowed between the "stringprefix" or ' - '"bytesprefix"\n' - 'and the rest of the literal. The source character set is defined ' - 'by\n' - 'the encoding declaration; it is UTF-8 if no encoding declaration ' - 'is\n' - 'given in the source file; see section Encoding declarations.\n' + 'whitespace is not allowed between the "stringprefix" and the rest ' + 'of\n' + 'the string literal. The source character set is defined by the\n' + 'encoding declaration; it is ASCII if no encoding declaration is ' + 'given\n' + 'in the source file; see section Encoding declarations.\n' '\n' - 'In plain English: Both types of literals can be enclosed in ' - 'matching\n' - 'single quotes ("\'") or double quotes ("""). They can also be ' - 'enclosed\n' - 'in matching groups of three single or double quotes (these are\n' - 'generally referred to as *triple-quoted strings*). The ' - 'backslash\n' - '("\\") character is used to escape characters that otherwise have ' - 'a\n' - 'special meaning, such as newline, backslash itself, or the quote\n' + 'In plain English: String literals can be enclosed in matching ' + 'single\n' + 'quotes ("\'") or double quotes ("""). They can also be enclosed ' + 'in\n' + 'matching groups of three single or double quotes (these are ' + 'generally\n' + 'referred to as *triple-quoted strings*). The backslash ("\\")\n' + 'character is used to escape characters that otherwise have a ' + 'special\n' + 'meaning, such as newline, backslash itself, or the quote ' 'character.\n' - '\n' - 'Bytes literals are always prefixed with "\'b\'" or "\'B\'"; they ' - 'produce\n' - 'an instance of the "bytes" type instead of the "str" type. They ' - 'may\n' - 'only contain ASCII characters; bytes with a numeric value of 128 ' + 'String literals may optionally be prefixed with a letter "\'r\'" ' 'or\n' - 'greater must be expressed with escapes.\n' - '\n' - 'Both string and bytes literals may optionally be prefixed with a\n' - 'letter "\'r\'" or "\'R\'"; such strings are called *raw strings* ' - 'and treat\n' - 'backslashes as literal characters. As a result, in string ' - 'literals,\n' - '"\'\\U\'" and "\'\\u\'" escapes in raw strings are not treated ' - 'specially.\n' - 'Given that Python 2.x’s raw unicode literals behave differently ' - 'than\n' - 'Python 3.x’s the "\'ur\'" syntax is not supported.\n' - '\n' - 'New in version 3.3: The "\'rb\'" prefix of raw bytes literals has ' - 'been\n' - 'added as a synonym of "\'br\'".\n' - '\n' - 'New in version 3.3: Support for the unicode legacy literal\n' - '("u\'value\'") was reintroduced to simplify the maintenance of ' - 'dual\n' - 'Python 2.x and 3.x codebases. See **PEP 414** for more ' - 'information.\n' - '\n' - 'A string literal with "\'f\'" or "\'F\'" in its prefix is a ' - '*formatted\n' - 'string literal*; see Formatted string literals. The "\'f\'" may ' - 'be\n' - 'combined with "\'r\'", but not with "\'b\'" or "\'u\'", therefore ' - 'raw\n' - 'formatted strings are possible, but formatted bytes literals are ' - 'not.\n' + '"\'R\'"; such strings are called *raw strings* and use different ' + 'rules\n' + 'for interpreting backslash escape sequences. A prefix of "\'u\'" ' + 'or\n' + '"\'U\'" makes the string a Unicode string. Unicode strings use ' + 'the\n' + 'Unicode character set as defined by the Unicode Consortium and ' + 'ISO\n' + '10646. Some additional escape sequences, described below, are\n' + 'available in Unicode strings. A prefix of "\'b\'" or "\'B\'" is ' + 'ignored in\n' + 'Python 2; it indicates that the literal should become a bytes ' + 'literal\n' + 'in Python 3 (e.g. when code is automatically converted with ' + '2to3). A\n' + '"\'u\'" or "\'b\'" prefix may be followed by an "\'r\'" prefix.\n' '\n' - 'In triple-quoted literals, unescaped newlines and quotes are ' + 'In triple-quoted strings, unescaped newlines and quotes are ' 'allowed\n' '(and are retained), except that three unescaped quotes in a row\n' - 'terminate the literal. (A “quote” is the character used to open ' + 'terminate the string. (A "quote" is the character used to open ' 'the\n' - 'literal, i.e. either "\'" or """.)\n' + 'string, i.e. either "\'" or """.)\n' '\n' 'Unless an "\'r\'" or "\'R\'" prefix is present, escape sequences ' - 'in string\n' - 'and bytes literals are interpreted according to rules similar to ' - 'those\n' - 'used by Standard C. The recognized escape sequences are:\n' + 'in\n' + 'strings are interpreted according to rules similar to those used ' + 'by\n' + 'Standard C. The recognized escape sequences are:\n' '\n' '+-------------------+-----------------------------------+---------+\n' '| Escape Sequence | Meaning | Notes ' '|\n' - '|===================|===================================|=========|\n' - '| "\\newline" | Backslash and newline ignored ' + '+===================+===================================+=========+\n' + '| "\\newline" | Ignored ' '| |\n' '+-------------------+-----------------------------------+---------+\n' '| "\\\\" | Backslash ("\\") ' @@ -10742,100 +9824,117 @@ topics = {'assert': 'The "assert" statement\n' '| "\\n" | ASCII Linefeed (LF) ' '| |\n' '+-------------------+-----------------------------------+---------+\n' + '| "\\N{name}" | Character named *name* in the ' + '| |\n' + '| | Unicode database (Unicode only) | ' + '|\n' + '+-------------------+-----------------------------------+---------+\n' '| "\\r" | ASCII Carriage Return (CR) ' '| |\n' '+-------------------+-----------------------------------+---------+\n' '| "\\t" | ASCII Horizontal Tab (TAB) ' '| |\n' '+-------------------+-----------------------------------+---------+\n' + '| "\\uxxxx" | Character with 16-bit hex value | ' + '(1) |\n' + '| | *xxxx* (Unicode only) | ' + '|\n' + '+-------------------+-----------------------------------+---------+\n' + '| "\\Uxxxxxxxx" | Character with 32-bit hex value | ' + '(2) |\n' + '| | *xxxxxxxx* (Unicode only) | ' + '|\n' + '+-------------------+-----------------------------------+---------+\n' '| "\\v" | ASCII Vertical Tab (VT) ' '| |\n' '+-------------------+-----------------------------------+---------+\n' '| "\\ooo" | Character with octal value *ooo* | ' - '(1,3) |\n' + '(3,5) |\n' '+-------------------+-----------------------------------+---------+\n' '| "\\xhh" | Character with hex value *hh* | ' - '(2,3) |\n' - '+-------------------+-----------------------------------+---------+\n' - '\n' - 'Escape sequences only recognized in string literals are:\n' - '\n' - '+-------------------+-----------------------------------+---------+\n' - '| Escape Sequence | Meaning | Notes ' - '|\n' - '|===================|===================================|=========|\n' - '| "\\N{name}" | Character named *name* in the | ' - '(4) |\n' - '| | Unicode database | ' - '|\n' - '+-------------------+-----------------------------------+---------+\n' - '| "\\uxxxx" | Character with 16-bit hex value | ' - '(5) |\n' - '| | *xxxx* | ' - '|\n' - '+-------------------+-----------------------------------+---------+\n' - '| "\\Uxxxxxxxx" | Character with 32-bit hex value | ' - '(6) |\n' - '| | *xxxxxxxx* | ' - '|\n' + '(4,5) |\n' '+-------------------+-----------------------------------+---------+\n' '\n' 'Notes:\n' '\n' - '1. As in Standard C, up to three octal digits are accepted.\n' + '1. Individual code units which form parts of a surrogate pair ' + 'can\n' + ' be encoded using this escape sequence.\n' '\n' - '2. Unlike in Standard C, exactly two hex digits are required.\n' + '2. Any Unicode character can be encoded this way, but characters\n' + ' outside the Basic Multilingual Plane (BMP) will be encoded ' + 'using a\n' + ' surrogate pair if Python is compiled to use 16-bit code units ' + '(the\n' + ' default).\n' '\n' - '3. In a bytes literal, hexadecimal and octal escapes denote the\n' - ' byte with the given value. In a string literal, these escapes\n' - ' denote a Unicode character with the given value.\n' + '3. As in Standard C, up to three octal digits are accepted.\n' '\n' - '4. Changed in version 3.3: Support for name aliases [1] has been\n' - ' added.\n' + '4. Unlike in Standard C, exactly two hex digits are required.\n' '\n' - '5. Exactly four hex digits are required.\n' - '\n' - '6. Any Unicode character can be encoded this way. Exactly eight\n' - ' hex digits are required.\n' + '5. In a string literal, hexadecimal and octal escapes denote the\n' + ' byte with the given value; it is not necessary that the byte\n' + ' encodes a character in the source character set. In a Unicode\n' + ' literal, these escapes denote a Unicode character with the ' + 'given\n' + ' value.\n' '\n' 'Unlike Standard C, all unrecognized escape sequences are left in ' 'the\n' - 'string unchanged, i.e., *the backslash is left in the result*. ' + 'string unchanged, i.e., *the backslash is left in the string*. ' '(This\n' 'behavior is useful when debugging: if an escape sequence is ' 'mistyped,\n' 'the resulting output is more easily recognized as broken.) It is ' 'also\n' - 'important to note that the escape sequences only recognized in ' - 'string\n' - 'literals fall into the category of unrecognized escapes for ' - 'bytes\n' - 'literals.\n' + 'important to note that the escape sequences marked as "(Unicode ' + 'only)"\n' + 'in the table above fall into the category of unrecognized escapes ' + 'for\n' + 'non-Unicode string literals.\n' '\n' - ' Changed in version 3.6: Unrecognized escape sequences produce ' - 'a\n' - ' "DeprecationWarning". In a future Python version they will be ' + 'When an "\'r\'" or "\'R\'" prefix is present, a character ' + 'following a\n' + 'backslash is included in the string without change, and *all\n' + 'backslashes are left in the string*. For example, the string ' + 'literal\n' + '"r"\\n"" consists of two characters: a backslash and a lowercase ' + '"\'n\'".\n' + 'String quotes can be escaped with a backslash, but the backslash\n' + 'remains in the string; for example, "r"\\""" is a valid string ' + 'literal\n' + 'consisting of two characters: a backslash and a double quote; ' + '"r"\\""\n' + 'is not a valid string literal (even a raw string cannot end in an ' + 'odd\n' + 'number of backslashes). Specifically, *a raw string cannot end ' + 'in a\n' + 'single backslash* (since the backslash would escape the ' + 'following\n' + 'quote character). Note also that a single backslash followed by ' 'a\n' - ' "SyntaxWarning" and eventually a "SyntaxError".\n' + 'newline is interpreted as those two characters as part of the ' + 'string,\n' + '*not* as a line continuation.\n' '\n' - 'Even in a raw literal, quotes can be escaped with a backslash, ' - 'but the\n' - 'backslash remains in the result; for example, "r"\\""" is a ' - 'valid\n' - 'string literal consisting of two characters: a backslash and a ' - 'double\n' - 'quote; "r"\\"" is not a valid string literal (even a raw string ' - 'cannot\n' - 'end in an odd number of backslashes). Specifically, *a raw ' - 'literal\n' - 'cannot end in a single backslash* (since the backslash would ' - 'escape\n' - 'the following quote character). Note also that a single ' - 'backslash\n' - 'followed by a newline is interpreted as those two characters as ' - 'part\n' - 'of the literal, *not* as a line continuation.\n', - 'subscriptions': 'Subscriptions\n' + 'When an "\'r\'" or "\'R\'" prefix is used in conjunction with a ' + '"\'u\'" or\n' + '"\'U\'" prefix, then the "\\uXXXX" and "\\UXXXXXXXX" escape ' + 'sequences are\n' + 'processed while *all other backslashes are left in the string*. ' + 'For\n' + 'example, the string literal "ur"\\u0062\\n"" consists of three ' + 'Unicode\n' + "characters: 'LATIN SMALL LETTER B', 'REVERSE SOLIDUS', and " + "'LATIN\n" + "SMALL LETTER N'. Backslashes can be escaped with a preceding\n" + 'backslash; however, both remain in the string. As a result, ' + '"\\uXXXX"\n' + 'escape sequences are only recognized when there are an odd number ' + 'of\n' + 'backslashes.\n', + 'subscriptions': '\n' + 'Subscriptions\n' '*************\n' '\n' 'A subscription selects an item of a sequence (string, tuple ' @@ -10844,15 +9943,8 @@ topics = {'assert': 'The "assert" statement\n' '\n' ' subscription ::= primary "[" expression_list "]"\n' '\n' - 'The primary must evaluate to an object that supports ' - 'subscription\n' - '(lists or dictionaries for example). User-defined objects ' - 'can support\n' - 'subscription by defining a "__getitem__()" method.\n' - '\n' - 'For built-in objects, there are two types of objects that ' - 'support\n' - 'subscription:\n' + 'The primary must evaluate to an object of a sequence or ' + 'mapping type.\n' '\n' 'If the primary is a mapping, the expression list must ' 'evaluate to an\n' @@ -10864,54 +9956,48 @@ topics = {'assert': 'The "assert" statement\n' 'exactly one\n' 'item.)\n' '\n' - 'If the primary is a sequence, the expression list must ' - 'evaluate to an\n' - 'integer or a slice (as discussed in the following ' - 'section).\n' - '\n' - 'The formal syntax makes no special provision for negative ' - 'indices in\n' - 'sequences; however, built-in sequences all provide a ' - '"__getitem__()"\n' - 'method that interprets negative indices by adding the ' - 'length of the\n' - 'sequence to the index (so that "x[-1]" selects the last ' - 'item of "x").\n' + 'If the primary is a sequence, the expression (list) must ' + 'evaluate to a\n' + 'plain integer. If this value is negative, the length of ' + 'the sequence\n' + 'is added to it (so that, e.g., "x[-1]" selects the last ' + 'item of "x".)\n' 'The resulting value must be a nonnegative integer less than ' 'the number\n' 'of items in the sequence, and the subscription selects the ' 'item whose\n' - 'index is that value (counting from zero). Since the support ' - 'for\n' - 'negative indices and slicing occurs in the object’s ' - '"__getitem__()"\n' - 'method, subclasses overriding this method will need to ' - 'explicitly add\n' - 'that support.\n' - '\n' - 'A string’s items are characters. A character is not a ' + 'index is that value (counting from zero).\n' + '\n' + "A string's items are characters. A character is not a " 'separate data\n' 'type but a string of exactly one character.\n', - 'truth': 'Truth Value Testing\n' + 'truth': '\n' + 'Truth Value Testing\n' '*******************\n' '\n' 'Any object can be tested for truth value, for use in an "if" or\n' - '"while" condition or as operand of the Boolean operations below.\n' + '"while" condition or as operand of the Boolean operations below. ' + 'The\n' + 'following values are considered false:\n' '\n' - 'By default, an object is considered true unless its class defines\n' - 'either a "__bool__()" method that returns "False" or a "__len__()"\n' - 'method that returns zero, when called with the object. [1] Here ' - 'are\n' - 'most of the built-in objects considered false:\n' + '* "None"\n' '\n' - '* constants defined to be false: "None" and "False".\n' + '* "False"\n' '\n' - '* zero of any numeric type: "0", "0.0", "0j", "Decimal(0)",\n' - ' "Fraction(0, 1)"\n' + '* zero of any numeric type, for example, "0", "0L", "0.0", "0j".\n' '\n' - '* empty sequences and collections: "\'\'", "()", "[]", "{}", ' - '"set()",\n' - ' "range(0)"\n' + '* any empty sequence, for example, "\'\'", "()", "[]".\n' + '\n' + '* any empty mapping, for example, "{}".\n' + '\n' + '* instances of user-defined classes, if the class defines a\n' + ' "__nonzero__()" or "__len__()" method, when that method returns ' + 'the\n' + ' integer zero or "bool" value "False". [1]\n' + '\n' + 'All other values are considered true --- so objects of many types ' + 'are\n' + 'always true.\n' '\n' 'Operations and built-in functions that have a Boolean result ' 'always\n' @@ -10919,7 +10005,8 @@ topics = {'assert': 'The "assert" statement\n' 'otherwise stated. (Important exception: the Boolean operations ' '"or"\n' 'and "and" always return one of their operands.)\n', - 'try': 'The "try" statement\n' + 'try': '\n' + 'The "try" statement\n' '*******************\n' '\n' 'The "try" statement specifies exception handlers and/or cleanup code\n' @@ -10927,13 +10014,18 @@ topics = {'assert': 'The "assert" statement\n' '\n' ' try_stmt ::= try1_stmt | try2_stmt\n' ' try1_stmt ::= "try" ":" suite\n' - ' ("except" [expression ["as" identifier]] ":" ' + ' ("except" [expression [("as" | ",") identifier]] ":" ' 'suite)+\n' ' ["else" ":" suite]\n' ' ["finally" ":" suite]\n' ' try2_stmt ::= "try" ":" suite\n' ' "finally" ":" suite\n' '\n' + 'Changed in version 2.5: In previous versions of Python,\n' + '"try"..."except"..."finally" did not work. "try"..."except" had to ' + 'be\n' + 'nested in "try"..."finally".\n' + '\n' 'The "except" clause(s) specify one or more exception handlers. When ' 'no\n' 'exception occurs in the "try" clause, no exception handler is\n' @@ -10946,10 +10038,10 @@ topics = {'assert': 'The "assert" statement\n' 'less except clause, if present, must be last; it matches any\n' 'exception. For an except clause with an expression, that expression\n' 'is evaluated, and the clause matches the exception if the resulting\n' - 'object is “compatible” with the exception. An object is compatible\n' + 'object is "compatible" with the exception. An object is compatible\n' 'with an exception if it is the class or a base class of the ' 'exception\n' - 'object or a tuple containing an item compatible with the exception.\n' + 'object, or a tuple containing an item compatible with the exception.\n' '\n' 'If no except clause matches the exception, the search for an ' 'exception\n' @@ -10966,70 +10058,48 @@ topics = {'assert': 'The "assert" statement\n' 'the exception).\n' '\n' 'When a matching except clause is found, the exception is assigned to\n' - 'the target specified after the "as" keyword in that except clause, ' - 'if\n' - 'present, and the except clause’s suite is executed. All except\n' - 'clauses must have an executable block. When the end of this block ' - 'is\n' - 'reached, execution continues normally after the entire try ' - 'statement.\n' - '(This means that if two nested handlers exist for the same ' - 'exception,\n' - 'and the exception occurs in the try clause of the inner handler, the\n' - 'outer handler will not handle the exception.)\n' - '\n' - 'When an exception has been assigned using "as target", it is cleared\n' - 'at the end of the except clause. This is as if\n' - '\n' - ' except E as N:\n' - ' foo\n' - '\n' - 'was translated to\n' - '\n' - ' except E as N:\n' - ' try:\n' - ' foo\n' - ' finally:\n' - ' del N\n' - '\n' - 'This means the exception must be assigned to a different name to be\n' - 'able to refer to it after the except clause. Exceptions are cleared\n' - 'because with the traceback attached to them, they form a reference\n' - 'cycle with the stack frame, keeping all locals in that frame alive\n' - 'until the next garbage collection occurs.\n' + 'the target specified in that except clause, if present, and the ' + 'except\n' + "clause's suite is executed. All except clauses must have an\n" + 'executable block. When the end of this block is reached, execution\n' + 'continues normally after the entire try statement. (This means that\n' + 'if two nested handlers exist for the same exception, and the ' + 'exception\n' + 'occurs in the try clause of the inner handler, the outer handler ' + 'will\n' + 'not handle the exception.)\n' '\n' - 'Before an except clause’s suite is executed, details about the\n' - 'exception are stored in the "sys" module and can be accessed via\n' - '"sys.exc_info()". "sys.exc_info()" returns a 3-tuple consisting of ' - 'the\n' - 'exception class, the exception instance and a traceback object (see\n' - 'section The standard type hierarchy) identifying the point in the\n' - 'program where the exception occurred. "sys.exc_info()" values are\n' - 'restored to their previous values (before the call) when returning\n' - 'from a function that handled an exception.\n' + "Before an except clause's suite is executed, details about the\n" + 'exception are assigned to three variables in the "sys" module:\n' + '"sys.exc_type" receives the object identifying the exception;\n' + '"sys.exc_value" receives the exception\'s parameter;\n' + '"sys.exc_traceback" receives a traceback object (see section The\n' + 'standard type hierarchy) identifying the point in the program where\n' + 'the exception occurred. These details are also available through the\n' + '"sys.exc_info()" function, which returns a tuple "(exc_type,\n' + 'exc_value, exc_traceback)". Use of the corresponding variables is\n' + 'deprecated in favor of this function, since their use is unsafe in a\n' + 'threaded program. As of Python 1.5, the variables are restored to\n' + 'their previous values (before the call) when returning from a ' + 'function\n' + 'that handled an exception.\n' '\n' - 'The optional "else" clause is executed if the control flow leaves ' - 'the\n' - '"try" suite, no exception was raised, and no "return", "continue", ' - 'or\n' - '"break" statement was executed. Exceptions in the "else" clause are\n' + 'The optional "else" clause is executed if and when control flows off\n' + 'the end of the "try" clause. [2] Exceptions in the "else" clause are\n' 'not handled by the preceding "except" clauses.\n' '\n' - 'If "finally" is present, it specifies a ‘cleanup’ handler. The ' + 'If "finally" is present, it specifies a \'cleanup\' handler. The ' '"try"\n' 'clause is executed, including any "except" and "else" clauses. If ' 'an\n' 'exception occurs in any of the clauses and is not handled, the\n' 'exception is temporarily saved. The "finally" clause is executed. ' 'If\n' - 'there is a saved exception it is re-raised at the end of the ' - '"finally"\n' - 'clause. If the "finally" clause raises another exception, the saved\n' - 'exception is set as the context of the new exception. If the ' - '"finally"\n' - 'clause executes a "return", "break" or "continue" statement, the ' - 'saved\n' - 'exception is discarded:\n' + 'there is a saved exception, it is re-raised at the end of the\n' + '"finally" clause. If the "finally" clause raises another exception ' + 'or\n' + 'executes a "return" or "break" statement, the saved exception is\n' + 'discarded:\n' '\n' ' >>> def f():\n' ' ... try:\n' @@ -11044,8 +10114,12 @@ topics = {'assert': 'The "assert" statement\n' 'execution of the "finally" clause.\n' '\n' 'When a "return", "break" or "continue" statement is executed in the\n' - '"try" suite of a "try"…"finally" statement, the "finally" clause is\n' - 'also executed ‘on the way out.’\n' + '"try" suite of a "try"..."finally" statement, the "finally" clause ' + 'is\n' + 'also executed \'on the way out.\' A "continue" statement is illegal ' + 'in\n' + 'the "finally" clause. (The reason is a problem with the current\n' + 'implementation --- this restriction may be lifted in the future).\n' '\n' 'The return value of a function is determined by the last "return"\n' 'statement executed. Since the "finally" clause always executes, a\n' @@ -11065,12 +10139,9 @@ topics = {'assert': 'The "assert" statement\n' 'Additional information on exceptions can be found in section\n' 'Exceptions, and information on using the "raise" statement to ' 'generate\n' - 'exceptions may be found in section The raise statement.\n' - '\n' - 'Changed in version 3.8: Prior to Python 3.8, a "continue" statement\n' - 'was illegal in the "finally" clause due to a problem with the\n' - 'implementation.\n', - 'types': 'The standard type hierarchy\n' + 'exceptions may be found in section The raise statement.\n', + 'types': '\n' + 'The standard type hierarchy\n' '***************************\n' '\n' 'Below is a list of the types that are built into Python. ' @@ -11079,12 +10150,10 @@ topics = {'assert': 'The "assert" statement\n' 'implementation) can define additional types. Future versions of\n' 'Python may add types to the type hierarchy (e.g., rational ' 'numbers,\n' - 'efficiently stored arrays of integers, etc.), although such ' - 'additions\n' - 'will often be provided via the standard library instead.\n' + 'efficiently stored arrays of integers, etc.).\n' '\n' 'Some of the type descriptions below contain a paragraph listing\n' - '‘special attributes.’ These are attributes that provide access to ' + "'special attributes.' These are attributes that provide access to " 'the\n' 'implementation and are not intended for general use. Their ' 'definition\n' @@ -11097,27 +10166,30 @@ topics = {'assert': 'The "assert" statement\n' 'It\n' ' is used to signify the absence of a value in many situations, ' 'e.g.,\n' - ' it is returned from functions that don’t explicitly return\n' + " it is returned from functions that don't explicitly return\n" ' anything. Its truth value is false.\n' '\n' 'NotImplemented\n' ' This type has a single value. There is a single object with ' 'this\n' ' value. This object is accessed through the built-in name\n' - ' "NotImplemented". Numeric methods and rich comparison methods\n' - ' should return this value if they do not implement the operation ' - 'for\n' - ' the operands provided. (The interpreter will then try the\n' - ' reflected operation, or some other fallback, depending on the\n' - ' operator.) Its truth value is true.\n' - '\n' - ' See Implementing the arithmetic operations for more details.\n' + ' "NotImplemented". Numeric methods and rich comparison methods ' + 'may\n' + ' return this value if they do not implement the operation for ' + 'the\n' + ' operands provided. (The interpreter will then try the ' + 'reflected\n' + ' operation, or some other fallback, depending on the operator.) ' + 'Its\n' + ' truth value is true.\n' '\n' 'Ellipsis\n' ' This type has a single value. There is a single object with ' 'this\n' - ' value. This object is accessed through the literal "..." or the\n' - ' built-in name "Ellipsis". Its truth value is true.\n' + ' value. This object is accessed through the built-in name\n' + ' "Ellipsis". It is used to indicate the presence of the "..." ' + 'syntax\n' + ' in a slice. Its truth value is true.\n' '\n' '"numbers.Number"\n' ' These are created by numeric literals and returned as results ' @@ -11139,37 +10211,59 @@ topics = {'assert': 'The "assert" statement\n' 'integers\n' ' (positive and negative).\n' '\n' - ' There are two types of integers:\n' + ' There are three types of integers:\n' '\n' - ' Integers ("int")\n' + ' Plain integers\n' + ' These represent numbers in the range -2147483648 through\n' + ' 2147483647. (The range may be larger on machines with a\n' + ' larger natural word size, but not smaller.) When the ' + 'result\n' + ' of an operation would fall outside this range, the result ' + 'is\n' + ' normally returned as a long integer (in some cases, the\n' + ' exception "OverflowError" is raised instead). For the\n' + ' purpose of shift and mask operations, integers are assumed ' + 'to\n' + " have a binary, 2's complement notation using 32 or more " + 'bits,\n' + ' and hiding no bits from the user (i.e., all 4294967296\n' + ' different bit patterns correspond to different values).\n' '\n' + ' Long integers\n' ' These represent numbers in an unlimited range, subject to\n' ' available (virtual) memory only. For the purpose of ' 'shift\n' ' and mask operations, a binary representation is assumed, ' 'and\n' - ' negative numbers are represented in a variant of 2’s\n' + " negative numbers are represented in a variant of 2's\n" ' complement which gives the illusion of an infinite string ' 'of\n' ' sign bits extending to the left.\n' '\n' - ' Booleans ("bool")\n' + ' Booleans\n' ' These represent the truth values False and True. The two\n' ' objects representing the values "False" and "True" are ' 'the\n' ' only Boolean objects. The Boolean type is a subtype of ' - 'the\n' - ' integer type, and Boolean values behave like the values 0 ' - 'and\n' - ' 1, respectively, in almost all contexts, the exception ' - 'being\n' + 'plain\n' + ' integers, and Boolean values behave like the values 0 and ' + '1,\n' + ' respectively, in almost all contexts, the exception being\n' ' that when converted to a string, the strings ""False"" or\n' ' ""True"" are returned, respectively.\n' '\n' ' The rules for integer representation are intended to give ' 'the\n' ' most meaningful interpretation of shift and mask operations\n' - ' involving negative integers.\n' + ' involving negative integers and the least surprises when\n' + ' switching between the plain and long integer domains. Any\n' + ' operation, if it yields a result in the plain integer ' + 'domain,\n' + ' will yield the same result in the long integer domain or ' + 'when\n' + ' using mixed operands. The switch between domains is ' + 'transparent\n' + ' to the programmer.\n' '\n' ' "numbers.Real" ("float")\n' ' These represent machine-level double precision floating ' @@ -11187,7 +10281,7 @@ topics = {'assert': 'The "assert" statement\n' 'floating\n' ' point numbers.\n' '\n' - ' "numbers.Complex" ("complex")\n' + ' "numbers.Complex"\n' ' These represent complex numbers as a pair of machine-level\n' ' double precision floating point numbers. The same caveats ' 'apply\n' @@ -11202,7 +10296,7 @@ topics = {'assert': 'The "assert" statement\n' 'items\n' ' of a sequence. When the length of a sequence is *n*, the index ' 'set\n' - ' contains the numbers 0, 1, …, *n*-1. Item *i* of sequence *a* ' + ' contains the numbers 0, 1, ..., *n*-1. Item *i* of sequence *a* ' 'is\n' ' selected by "a[i]".\n' '\n' @@ -11212,8 +10306,8 @@ topics = {'assert': 'The "assert" statement\n' 'implies\n' ' that the index set is renumbered so that it starts at 0.\n' '\n' - ' Some sequences also support “extended slicing” with a third ' - '“step”\n' + ' Some sequences also support "extended slicing" with a third ' + '"step"\n' ' parameter: "a[i:j:k]" selects all items of *a* with index *x* ' 'where\n' ' "x = i + n*k", *n* ">=" "0" and *i* "<=" *x* "<" *j*.\n' @@ -11234,30 +10328,57 @@ topics = {'assert': 'The "assert" statement\n' ' The following types are immutable sequences:\n' '\n' ' Strings\n' - ' A string is a sequence of values that represent Unicode ' - 'code\n' - ' points. All the code points in the range "U+0000 - ' - 'U+10FFFF"\n' - ' can be represented in a string. Python doesn’t have a ' - '"char"\n' - ' type; instead, every code point in the string is ' - 'represented\n' - ' as a string object with length "1". The built-in ' - 'function\n' - ' "ord()" converts a code point from its string form to an\n' - ' integer in the range "0 - 10FFFF"; "chr()" converts an\n' - ' integer in the range "0 - 10FFFF" to the corresponding ' - 'length\n' - ' "1" string object. "str.encode()" can be used to convert ' - 'a\n' - ' "str" to "bytes" using the given text encoding, and\n' - ' "bytes.decode()" can be used to achieve the opposite.\n' + ' The items of a string are characters. There is no ' + 'separate\n' + ' character type; a character is represented by a string of ' + 'one\n' + ' item. Characters represent (at least) 8-bit bytes. The\n' + ' built-in functions "chr()" and "ord()" convert between\n' + ' characters and nonnegative integers representing the byte\n' + ' values. Bytes with the values 0--127 usually represent ' + 'the\n' + ' corresponding ASCII values, but the interpretation of ' + 'values\n' + ' is up to the program. The string data type is also used ' + 'to\n' + ' represent arrays of bytes, e.g., to hold data read from a\n' + ' file.\n' + '\n' + ' (On systems whose native character set is not ASCII, ' + 'strings\n' + ' may use EBCDIC in their internal representation, provided ' + 'the\n' + ' functions "chr()" and "ord()" implement a mapping between\n' + ' ASCII and EBCDIC, and string comparison preserves the ' + 'ASCII\n' + ' order. Or perhaps someone can propose a better rule?)\n' + '\n' + ' Unicode\n' + ' The items of a Unicode object are Unicode code units. A\n' + ' Unicode code unit is represented by a Unicode object of ' + 'one\n' + ' item and can hold either a 16-bit or 32-bit value\n' + ' representing a Unicode ordinal (the maximum value for the\n' + ' ordinal is given in "sys.maxunicode", and depends on how\n' + ' Python is configured at compile time). Surrogate pairs ' + 'may\n' + ' be present in the Unicode object, and will be reported as ' + 'two\n' + ' separate items. The built-in functions "unichr()" and\n' + ' "ord()" convert between code units and nonnegative ' + 'integers\n' + ' representing the Unicode ordinals as defined in the ' + 'Unicode\n' + ' Standard 3.0. Conversion from and to other encodings are\n' + ' possible through the Unicode method "encode()" and the ' + 'built-\n' + ' in function "unicode()".\n' '\n' ' Tuples\n' ' The items of a tuple are arbitrary Python objects. Tuples ' 'of\n' ' two or more items are formed by comma-separated lists of\n' - ' expressions. A tuple of one item (a ‘singleton’) can be\n' + " expressions. A tuple of one item (a 'singleton') can be\n" ' formed by affixing a comma to an expression (an expression ' 'by\n' ' itself does not create a tuple, since parentheses must be\n' @@ -11265,17 +10386,6 @@ topics = {'assert': 'The "assert" statement\n' 'be\n' ' formed by an empty pair of parentheses.\n' '\n' - ' Bytes\n' - ' A bytes object is an immutable array. The items are ' - '8-bit\n' - ' bytes, represented by integers in the range 0 <= x < 256.\n' - ' Bytes literals (like "b\'abc\'") and the built-in ' - '"bytes()"\n' - ' constructor can be used to create bytes objects. Also, ' - 'bytes\n' - ' objects can be decoded to strings via the "decode()" ' - 'method.\n' - '\n' ' Mutable sequences\n' ' Mutable sequences can be changed after they are created. ' 'The\n' @@ -11300,12 +10410,12 @@ topics = {'assert': 'The "assert" statement\n' ' the built-in "bytearray()" constructor. Aside from being\n' ' mutable (and hence unhashable), byte arrays otherwise ' 'provide\n' - ' the same interface and functionality as immutable "bytes"\n' + ' the same interface and functionality as immutable bytes\n' ' objects.\n' '\n' ' The extension module "array" provides an additional example ' 'of a\n' - ' mutable sequence type, as does the "collections" module.\n' + ' mutable sequence type.\n' '\n' 'Set types\n' ' These represent unordered, finite sets of unique, immutable\n' @@ -11363,7 +10473,7 @@ topics = {'assert': 'The "assert" statement\n' 'object\n' ' identity, the reason being that the efficient implementation ' 'of\n' - ' dictionaries requires a key’s hash value to remain constant.\n' + " dictionaries requires a key's hash value to remain constant.\n" ' Numeric types used for keys obey the normal rules for ' 'numeric\n' ' comparison: if two numbers compare equal (e.g., "1" and ' @@ -11374,10 +10484,8 @@ topics = {'assert': 'The "assert" statement\n' ' Dictionaries are mutable; they can be created by the "{...}"\n' ' notation (see section Dictionary displays).\n' '\n' - ' The extension modules "dbm.ndbm" and "dbm.gnu" provide\n' - ' additional examples of mapping types, as does the ' - '"collections"\n' - ' module.\n' + ' The extension modules "dbm", "gdbm", and "bsddb" provide\n' + ' additional examples of mapping types.\n' '\n' 'Callable types\n' ' These are the types to which the function call operation (see\n' @@ -11388,115 +10496,92 @@ topics = {'assert': 'The "assert" statement\n' ' definition (see section Function definitions). It should be\n' ' called with an argument list containing the same number of ' 'items\n' - ' as the function’s formal parameter list.\n' + " as the function's formal parameter list.\n" '\n' ' Special attributes:\n' '\n' ' ' - '+---------------------------+---------------------------------+-------------+\n' - ' | Attribute | Meaning ' + '+-------------------------+---------------------------------+-------------+\n' + ' | Attribute | Meaning ' '| |\n' ' ' - '|===========================|=================================|=============|\n' - ' | "__doc__" | The function’s documentation ' + '+=========================+=================================+=============+\n' + ' | "__doc__" "func_doc" | The function\'s documentation ' '| Writable |\n' - ' | | string, or "None" if ' + ' | | string, or "None" if ' '| |\n' - ' | | unavailable; not inherited by ' - '| |\n' - ' | | subclasses. ' + ' | | unavailable. ' '| |\n' ' ' - '+---------------------------+---------------------------------+-------------+\n' - ' | "__name__" | The function’s name. ' + '+-------------------------+---------------------------------+-------------+\n' + ' | "__name__" "func_name" | The function\'s name ' '| Writable |\n' ' ' - '+---------------------------+---------------------------------+-------------+\n' - ' | "__qualname__" | The function’s *qualified ' - '| Writable |\n' - ' | | name*. New in version 3.3. ' + '+-------------------------+---------------------------------+-------------+\n' + ' | "__module__" | The name of the module the | ' + 'Writable |\n' + ' | | function was defined in, or ' '| |\n' - ' ' - '+---------------------------+---------------------------------+-------------+\n' - ' | "__module__" | The name of the module the ' - '| Writable |\n' - ' | | function was defined in, or ' - '| |\n' - ' | | "None" if unavailable. ' + ' | | "None" if unavailable. ' '| |\n' ' ' - '+---------------------------+---------------------------------+-------------+\n' - ' | "__defaults__" | A tuple containing default ' - '| Writable |\n' - ' | | argument values for those ' + '+-------------------------+---------------------------------+-------------+\n' + ' | "__defaults__" | A tuple containing default | ' + 'Writable |\n' + ' | "func_defaults" | argument values for those ' '| |\n' - ' | | arguments that have defaults, ' + ' | | arguments that have defaults, ' '| |\n' - ' | | or "None" if no arguments have ' + ' | | or "None" if no arguments have ' '| |\n' - ' | | a default value. ' + ' | | a default value. ' '| |\n' ' ' - '+---------------------------+---------------------------------+-------------+\n' - ' | "__code__" | The code object representing ' - '| Writable |\n' - ' | | the compiled function body. ' + '+-------------------------+---------------------------------+-------------+\n' + ' | "__code__" "func_code" | The code object representing | ' + 'Writable |\n' + ' | | the compiled function body. ' '| |\n' ' ' - '+---------------------------+---------------------------------+-------------+\n' - ' | "__globals__" | A reference to the dictionary ' - '| Read-only |\n' - ' | | that holds the function’s ' + '+-------------------------+---------------------------------+-------------+\n' + ' | "__globals__" | A reference to the dictionary | ' + 'Read-only |\n' + ' | "func_globals" | that holds the function\'s ' '| |\n' - ' | | global variables — the global ' + ' | | global variables --- the global ' '| |\n' - ' | | namespace of the module in ' + ' | | namespace of the module in ' '| |\n' - ' | | which the function was defined. ' + ' | | which the function was defined. ' '| |\n' ' ' - '+---------------------------+---------------------------------+-------------+\n' - ' | "__dict__" | The namespace supporting ' - '| Writable |\n' - ' | | arbitrary function attributes. ' + '+-------------------------+---------------------------------+-------------+\n' + ' | "__dict__" "func_dict" | The namespace supporting | ' + 'Writable |\n' + ' | | arbitrary function attributes. ' '| |\n' ' ' - '+---------------------------+---------------------------------+-------------+\n' - ' | "__closure__" | "None" or a tuple of cells that ' - '| Read-only |\n' - ' | | contain bindings for the ' - '| |\n' - ' | | function’s free variables. See ' - '| |\n' - ' | | below for information on the ' - '| |\n' - ' | | "cell_contents" attribute. ' - '| |\n' - ' ' - '+---------------------------+---------------------------------+-------------+\n' - ' | "__annotations__" | A dict containing annotations ' - '| Writable |\n' - ' | | of parameters. The keys of the ' - '| |\n' - ' | | dict are the parameter names, ' + '+-------------------------+---------------------------------+-------------+\n' + ' | "__closure__" | "None" or a tuple of cells that | ' + 'Read-only |\n' + ' | "func_closure" | contain bindings for the ' '| |\n' - ' | | and "\'return\'" for the ' - 'return | |\n' - ' | | annotation, if provided. ' + " | | function's free variables. " '| |\n' ' ' - '+---------------------------+---------------------------------+-------------+\n' - ' | "__kwdefaults__" | A dict containing defaults for ' - '| Writable |\n' - ' | | keyword-only parameters. ' - '| |\n' - ' ' - '+---------------------------+---------------------------------+-------------+\n' + '+-------------------------+---------------------------------+-------------+\n' '\n' - ' Most of the attributes labelled “Writable” check the type of ' + ' Most of the attributes labelled "Writable" check the type of ' 'the\n' ' assigned value.\n' '\n' + ' Changed in version 2.4: "func_name" is now writable.\n' + '\n' + ' Changed in version 2.6: The double-underscore attributes\n' + ' "__closure__", "__code__", "__defaults__", and "__globals__"\n' + ' were introduced as aliases for the corresponding "func_*"\n' + ' attributes for forwards compatibility with Python 3.\n' + '\n' ' Function objects also support getting and setting arbitrary\n' ' attributes, which can be used, for example, to attach ' 'metadata\n' @@ -11509,30 +10594,35 @@ topics = {'assert': 'The "assert" statement\n' ' attributes on built-in functions may be supported in the\n' ' future.*\n' '\n' - ' A cell object has the attribute "cell_contents". This can be\n' - ' used to get the value of the cell, as well as set the value.\n' - '\n' - ' Additional information about a function’s definition can be\n' + " Additional information about a function's definition can be\n" ' retrieved from its code object; see the description of ' 'internal\n' - ' types below. The "cell" type can be accessed in the "types"\n' - ' module.\n' + ' types below.\n' '\n' - ' Instance methods\n' - ' An instance method object combines a class, a class instance ' - 'and\n' - ' any callable object (normally a user-defined function).\n' + ' User-defined methods\n' + ' A user-defined method object combines a class, a class ' + 'instance\n' + ' (or "None") and any callable object (normally a user-defined\n' + ' function).\n' '\n' - ' Special read-only attributes: "__self__" is the class ' + ' Special read-only attributes: "im_self" is the class ' 'instance\n' - ' object, "__func__" is the function object; "__doc__" is the\n' - ' method’s documentation (same as "__func__.__doc__"); ' - '"__name__"\n' - ' is the method name (same as "__func__.__name__"); ' - '"__module__"\n' - ' is the name of the module the method was defined in, or ' - '"None"\n' - ' if unavailable.\n' + ' object, "im_func" is the function object; "im_class" is the\n' + ' class of "im_self" for bound methods or the class that asked ' + 'for\n' + ' the method for unbound methods; "__doc__" is the method\'s\n' + ' documentation (same as "im_func.__doc__"); "__name__" is the\n' + ' method name (same as "im_func.__name__"); "__module__" is ' + 'the\n' + ' name of the module the method was defined in, or "None" if\n' + ' unavailable.\n' + '\n' + ' Changed in version 2.2: "im_self" used to refer to the class\n' + ' that defined the method.\n' + '\n' + ' Changed in version 2.6: For Python 3 forward-compatibility,\n' + ' "im_func" is also available as "__func__", and "im_self" as\n' + ' "__self__".\n' '\n' ' Methods also support accessing (but not setting) the ' 'arbitrary\n' @@ -11541,40 +10631,67 @@ topics = {'assert': 'The "assert" statement\n' ' User-defined method objects may be created when getting an\n' ' attribute of a class (perhaps via an instance of that class), ' 'if\n' - ' that attribute is a user-defined function object or a class\n' - ' method object.\n' - '\n' - ' When an instance method object is created by retrieving a ' - 'user-\n' - ' defined function object from a class via one of its ' - 'instances,\n' - ' its "__self__" attribute is the instance, and the method ' + ' that attribute is a user-defined function object, an unbound\n' + ' user-defined method object, or a class method object. When ' + 'the\n' + ' attribute is a user-defined method object, a new method ' 'object\n' - ' is said to be bound. The new method’s "__func__" attribute ' + ' is only created if the class from which it is being retrieved ' 'is\n' - ' the original function object.\n' + ' the same as, or a derived class of, the class stored in the\n' + ' original method object; otherwise, the original method object ' + 'is\n' + ' used as it is.\n' '\n' - ' When an instance method object is created by retrieving a ' - 'class\n' - ' method object from a class or instance, its "__self__" ' + ' When a user-defined method object is created by retrieving a\n' + ' user-defined function object from a class, its "im_self"\n' + ' attribute is "None" and the method object is said to be ' + 'unbound.\n' + ' When one is created by retrieving a user-defined function ' + 'object\n' + ' from a class via one of its instances, its "im_self" ' 'attribute\n' - ' is the class itself, and its "__func__" attribute is the\n' - ' function object underlying the class method.\n' + ' is the instance, and the method object is said to be bound. ' + 'In\n' + ' either case, the new method\'s "im_class" attribute is the ' + 'class\n' + ' from which the retrieval takes place, and its "im_func"\n' + ' attribute is the original function object.\n' '\n' - ' When an instance method object is called, the underlying\n' - ' function ("__func__") is called, inserting the class ' - 'instance\n' - ' ("__self__") in front of the argument list. For instance, ' - 'when\n' - ' "C" is a class which contains a definition for a function ' - '"f()",\n' - ' and "x" is an instance of "C", calling "x.f(1)" is equivalent ' - 'to\n' - ' calling "C.f(x, 1)".\n' + ' When a user-defined method object is created by retrieving\n' + ' another method object from a class or instance, the behaviour ' + 'is\n' + ' the same as for a function object, except that the "im_func"\n' + ' attribute of the new instance is not the original method ' + 'object\n' + ' but its "im_func" attribute.\n' + '\n' + ' When a user-defined method object is created by retrieving a\n' + ' class method object from a class or instance, its "im_self"\n' + ' attribute is the class itself, and its "im_func" attribute ' + 'is\n' + ' the function object underlying the class method.\n' + '\n' + ' When an unbound user-defined method object is called, the\n' + ' underlying function ("im_func") is called, with the ' + 'restriction\n' + ' that the first argument must be an instance of the proper ' + 'class\n' + ' ("im_class") or of a derived class thereof.\n' '\n' - ' When an instance method object is derived from a class ' + ' When a bound user-defined method object is called, the\n' + ' underlying function ("im_func") is called, inserting the ' + 'class\n' + ' instance ("im_self") in front of the argument list. For\n' + ' instance, when "C" is a class which contains a definition for ' + 'a\n' + ' function "f()", and "x" is an instance of "C", calling ' + '"x.f(1)"\n' + ' is equivalent to calling "C.f(x, 1)".\n' + '\n' + ' When a user-defined method object is derived from a class ' 'method\n' - ' object, the “class instance” stored in "__self__" will ' + ' object, the "class instance" stored in "im_self" will ' 'actually\n' ' be the class itself, so that calling either "x.f(1)" or ' '"C.f(1)"\n' @@ -11582,22 +10699,23 @@ topics = {'assert': 'The "assert" statement\n' 'underlying\n' ' function.\n' '\n' - ' Note that the transformation from function object to ' - 'instance\n' - ' method object happens each time the attribute is retrieved ' - 'from\n' - ' the instance. In some cases, a fruitful optimization is to\n' - ' assign the attribute to a local variable and call that local\n' - ' variable. Also notice that this transformation only happens ' - 'for\n' - ' user-defined functions; other callable objects (and all non-\n' - ' callable objects) are retrieved without transformation. It ' - 'is\n' - ' also important to note that user-defined functions which are\n' - ' attributes of a class instance are not converted to bound\n' - ' methods; this *only* happens when the function is an ' - 'attribute\n' - ' of the class.\n' + ' Note that the transformation from function object to (unbound ' + 'or\n' + ' bound) method object happens each time the attribute is\n' + ' retrieved from the class or instance. In some cases, a ' + 'fruitful\n' + ' optimization is to assign the attribute to a local variable ' + 'and\n' + ' call that local variable. Also notice that this ' + 'transformation\n' + ' only happens for user-defined functions; other callable ' + 'objects\n' + ' (and all non-callable objects) are retrieved without\n' + ' transformation. It is also important to note that ' + 'user-defined\n' + ' functions which are attributes of a class instance are not\n' + ' converted to bound methods; this *only* happens when the\n' + ' function is an attribute of the class.\n' '\n' ' Generator functions\n' ' A function or method which uses the "yield" statement (see\n' @@ -11607,46 +10725,14 @@ topics = {'assert': 'The "assert" statement\n' 'object\n' ' which can be used to execute the body of the function: ' 'calling\n' - ' the iterator’s "iterator.__next__()" method will cause the\n' - ' function to execute until it provides a value using the ' - '"yield"\n' - ' statement. When the function executes a "return" statement ' - 'or\n' - ' falls off the end, a "StopIteration" exception is raised and ' - 'the\n' - ' iterator will have reached the end of the set of values to ' - 'be\n' - ' returned.\n' - '\n' - ' Coroutine functions\n' - ' A function or method which is defined using "async def" is\n' - ' called a *coroutine function*. Such a function, when ' - 'called,\n' - ' returns a *coroutine* object. It may contain "await"\n' - ' expressions, as well as "async with" and "async for" ' - 'statements.\n' - ' See also the Coroutine Objects section.\n' - '\n' - ' Asynchronous generator functions\n' - ' A function or method which is defined using "async def" and\n' - ' which uses the "yield" statement is called a *asynchronous\n' - ' generator function*. Such a function, when called, returns ' - 'an\n' - ' asynchronous iterator object which can be used in an "async ' - 'for"\n' - ' statement to execute the body of the function.\n' - '\n' - ' Calling the asynchronous iterator’s "aiterator.__anext__()"\n' - ' method will return an *awaitable* which when awaited will\n' + ' the iterator\'s "next()" method will cause the function to\n' ' execute until it provides a value using the "yield" ' - 'expression.\n' - ' When the function executes an empty "return" statement or ' - 'falls\n' - ' off the end, a "StopAsyncIteration" exception is raised and ' + 'statement.\n' + ' When the function executes a "return" statement or falls off ' 'the\n' - ' asynchronous iterator will have reached the end of the set ' - 'of\n' - ' values to be yielded.\n' + ' end, a "StopIteration" exception is raised and the iterator ' + 'will\n' + ' have reached the end of the set of values to be returned.\n' '\n' ' Built-in functions\n' ' A built-in function object is a wrapper around a C function.\n' @@ -11655,9 +10741,9 @@ topics = {'assert': 'The "assert" statement\n' 'of\n' ' the arguments are determined by the C function. Special ' 'read-\n' - ' only attributes: "__doc__" is the function’s documentation\n' + ' only attributes: "__doc__" is the function\'s documentation\n' ' string, or "None" if unavailable; "__name__" is the ' - 'function’s\n' + "function's\n" ' name; "__self__" is set to "None" (but see the next item);\n' ' "__module__" is the name of the module the function was ' 'defined\n' @@ -11673,56 +10759,47 @@ topics = {'assert': 'The "assert" statement\n' 'the\n' ' object denoted by *alist*.\n' '\n' - ' Classes\n' - ' Classes are callable. These objects normally act as ' - 'factories\n' - ' for new instances of themselves, but variations are possible ' - 'for\n' - ' class types that override "__new__()". The arguments of the\n' - ' call are passed to "__new__()" and, in the typical case, to\n' - ' "__init__()" to initialize the new instance.\n' + ' Class Types\n' + ' Class types, or "new-style classes," are callable. These\n' + ' objects normally act as factories for new instances of\n' + ' themselves, but variations are possible for class types that\n' + ' override "__new__()". The arguments of the call are passed ' + 'to\n' + ' "__new__()" and, in the typical case, to "__init__()" to\n' + ' initialize the new instance.\n' + '\n' + ' Classic Classes\n' + ' Class objects are described below. When a class object is\n' + ' called, a new class instance (also described below) is ' + 'created\n' + " and returned. This implies a call to the class's " + '"__init__()"\n' + ' method if it has one. Any arguments are passed on to the\n' + ' "__init__()" method. If there is no "__init__()" method, ' + 'the\n' + ' class must be called without arguments.\n' '\n' - ' Class Instances\n' - ' Instances of arbitrary classes can be made callable by ' - 'defining\n' - ' a "__call__()" method in their class.\n' + ' Class instances\n' + ' Class instances are described below. Class instances are\n' + ' callable only when the class has a "__call__()" method;\n' + ' "x(arguments)" is a shorthand for "x.__call__(arguments)".\n' '\n' 'Modules\n' - ' Modules are a basic organizational unit of Python code, and are\n' - ' created by the import system as invoked either by the "import"\n' - ' statement, or by calling functions such as\n' - ' "importlib.import_module()" and built-in "__import__()". A ' - 'module\n' - ' object has a namespace implemented by a dictionary object (this ' - 'is\n' - ' the dictionary referenced by the "__globals__" attribute of\n' - ' functions defined in the module). Attribute references are\n' - ' translated to lookups in this dictionary, e.g., "m.x" is ' - 'equivalent\n' - ' to "m.__dict__["x"]". A module object does not contain the code\n' - ' object used to initialize the module (since it isn’t needed ' - 'once\n' - ' the initialization is done).\n' - '\n' - ' Attribute assignment updates the module’s namespace dictionary,\n' + ' Modules are imported by the "import" statement (see section The\n' + ' import statement). A module object has a namespace implemented ' + 'by a\n' + ' dictionary object (this is the dictionary referenced by the\n' + ' func_globals attribute of functions defined in the module).\n' + ' Attribute references are translated to lookups in this ' + 'dictionary,\n' + ' e.g., "m.x" is equivalent to "m.__dict__["x"]". A module object\n' + ' does not contain the code object used to initialize the module\n' + " (since it isn't needed once the initialization is done).\n" + '\n' + " Attribute assignment updates the module's namespace dictionary,\n" ' e.g., "m.x = 1" is equivalent to "m.__dict__["x"] = 1".\n' '\n' - ' Predefined (writable) attributes: "__name__" is the module’s ' - 'name;\n' - ' "__doc__" is the module’s documentation string, or "None" if\n' - ' unavailable; "__annotations__" (optional) is a dictionary\n' - ' containing *variable annotations* collected during module body\n' - ' execution; "__file__" is the pathname of the file from which ' - 'the\n' - ' module was loaded, if it was loaded from a file. The "__file__"\n' - ' attribute may be missing for certain types of modules, such as ' - 'C\n' - ' modules that are statically linked into the interpreter; for\n' - ' extension modules loaded dynamically from a shared library, it ' - 'is\n' - ' the pathname of the shared library file.\n' - '\n' - ' Special read-only attribute: "__dict__" is the module’s ' + ' Special read-only attribute: "__dict__" is the module\'s ' 'namespace\n' ' as a dictionary object.\n' '\n' @@ -11735,42 +10812,66 @@ topics = {'assert': 'The "assert" statement\n' 'the\n' ' module around while using its dictionary directly.\n' '\n' - 'Custom classes\n' - ' Custom class types are typically created by class definitions ' - '(see\n' - ' section Class definitions). A class has a namespace implemented ' - 'by\n' - ' a dictionary object. Class attribute references are translated ' - 'to\n' - ' lookups in this dictionary, e.g., "C.x" is translated to\n' - ' "C.__dict__["x"]" (although there are a number of hooks which ' - 'allow\n' - ' for other means of locating attributes). When the attribute name ' - 'is\n' - ' not found there, the attribute search continues in the base\n' - ' classes. This search of the base classes uses the C3 method\n' - ' resolution order which behaves correctly even in the presence ' + ' Predefined (writable) attributes: "__name__" is the module\'s ' + 'name;\n' + ' "__doc__" is the module\'s documentation string, or "None" if\n' + ' unavailable; "__file__" is the pathname of the file from which ' + 'the\n' + ' module was loaded, if it was loaded from a file. The "__file__"\n' + ' attribute is not present for C modules that are statically ' + 'linked\n' + ' into the interpreter; for extension modules loaded dynamically ' + 'from\n' + ' a shared library, it is the pathname of the shared library ' + 'file.\n' + '\n' + 'Classes\n' + ' Both class types (new-style classes) and class objects (old-\n' + ' style/classic classes) are typically created by class ' + 'definitions\n' + ' (see section Class definitions). A class has a namespace\n' + ' implemented by a dictionary object. Class attribute references ' + 'are\n' + ' translated to lookups in this dictionary, e.g., "C.x" is ' + 'translated\n' + ' to "C.__dict__["x"]" (although for new-style classes in ' + 'particular\n' + ' there are a number of hooks which allow for other means of ' + 'locating\n' + ' attributes). When the attribute name is not found there, the\n' + ' attribute search continues in the base classes. For old-style\n' + ' classes, the search is depth-first, left-to-right in the order ' 'of\n' - ' ‘diamond’ inheritance structures where there are multiple\n' - ' inheritance paths leading back to a common ancestor. Additional\n' - ' details on the C3 MRO used by Python can be found in the\n' - ' documentation accompanying the 2.3 release at\n' + ' occurrence in the base class list. New-style classes use the ' + 'more\n' + ' complex C3 method resolution order which behaves correctly even ' + 'in\n' + " the presence of 'diamond' inheritance structures where there " + 'are\n' + ' multiple inheritance paths leading back to a common ancestor.\n' + ' Additional details on the C3 MRO used by new-style classes can ' + 'be\n' + ' found in the documentation accompanying the 2.3 release at\n' ' https://www.python.org/download/releases/2.3/mro/.\n' '\n' ' When a class attribute reference (for class "C", say) would ' 'yield a\n' - ' class method object, it is transformed into an instance method\n' - ' object whose "__self__" attribute is "C". When it would yield ' + ' user-defined function object or an unbound user-defined method\n' + ' object whose associated class is either "C" or one of its base\n' + ' classes, it is transformed into an unbound user-defined method\n' + ' object whose "im_class" attribute is "C". When it would yield a\n' + ' class method object, it is transformed into a bound ' + 'user-defined\n' + ' method object whose "im_self" attribute is "C". When it would\n' + ' yield a static method object, it is transformed into the object\n' + ' wrapped by the static method object. See section Implementing\n' + ' Descriptors for another way in which attributes retrieved from ' 'a\n' - ' static method object, it is transformed into the object wrapped ' - 'by\n' - ' the static method object. See section Implementing Descriptors ' - 'for\n' - ' another way in which attributes retrieved from a class may ' - 'differ\n' - ' from those actually contained in its "__dict__".\n' + ' class may differ from those actually contained in its ' + '"__dict__"\n' + ' (note that only new-style classes support descriptors).\n' '\n' - ' Class attribute assignments update the class’s dictionary, ' + " Class attribute assignments update the class's dictionary, " 'never\n' ' the dictionary of a base class.\n' '\n' @@ -11782,16 +10883,13 @@ topics = {'assert': 'The "assert" statement\n' 'is\n' ' the module name in which the class was defined; "__dict__" is ' 'the\n' - ' dictionary containing the class’s namespace; "__bases__" is a ' + ' dictionary containing the class\'s namespace; "__bases__" is a ' 'tuple\n' - ' containing the base classes, in the order of their occurrence ' - 'in\n' - ' the base class list; "__doc__" is the class’s documentation ' - 'string,\n' - ' or "None" if undefined; "__annotations__" (optional) is a\n' - ' dictionary containing *variable annotations* collected during ' - 'class\n' - ' body execution.\n' + ' (possibly empty or a singleton) containing the base classes, in ' + 'the\n' + ' order of their occurrence in the base class list; "__doc__" is ' + 'the\n' + ' class\'s documentation string, or "None" if undefined.\n' '\n' 'Class instances\n' ' A class instance is created by calling a class object (see ' @@ -11799,26 +10897,29 @@ topics = {'assert': 'The "assert" statement\n' ' A class instance has a namespace implemented as a dictionary ' 'which\n' ' is the first place in which attribute references are searched.\n' - ' When an attribute is not found there, and the instance’s class ' + " When an attribute is not found there, and the instance's class " 'has\n' ' an attribute by that name, the search continues with the class\n' ' attributes. If a class attribute is found that is a ' 'user-defined\n' - ' function object, it is transformed into an instance method ' - 'object\n' - ' whose "__self__" attribute is the instance. Static method and\n' - ' class method objects are also transformed; see above under\n' - ' “Classes”. See section Implementing Descriptors for another way ' - 'in\n' - ' which attributes of a class retrieved via its instances may ' - 'differ\n' - ' from the objects actually stored in the class’s "__dict__". If ' - 'no\n' - ' class attribute is found, and the object’s class has a\n' - ' "__getattr__()" method, that is called to satisfy the lookup.\n' - '\n' - ' Attribute assignments and deletions update the instance’s\n' - ' dictionary, never a class’s dictionary. If the class has a\n' + ' function object or an unbound user-defined method object whose\n' + ' associated class is the class (call it "C") of the instance for\n' + ' which the attribute reference was initiated or one of its bases, ' + 'it\n' + ' is transformed into a bound user-defined method object whose\n' + ' "im_class" attribute is "C" and whose "im_self" attribute is ' + 'the\n' + ' instance. Static method and class method objects are also\n' + ' transformed, as if they had been retrieved from class "C"; see\n' + ' above under "Classes". See section Implementing Descriptors for\n' + ' another way in which attributes of a class retrieved via its\n' + ' instances may differ from the objects actually stored in the\n' + ' class\'s "__dict__". If no class attribute is found, and the\n' + ' object\'s class has a "__getattr__()" method, that is called to\n' + ' satisfy the lookup.\n' + '\n' + " Attribute assignments and deletions update the instance's\n" + " dictionary, never a class's dictionary. If the class has a\n" ' "__setattr__()" or "__delattr__()" method, this is called ' 'instead\n' ' of updating the instance dictionary directly.\n' @@ -11829,23 +10930,21 @@ topics = {'assert': 'The "assert" statement\n' ' Special method names.\n' '\n' ' Special attributes: "__dict__" is the attribute dictionary;\n' - ' "__class__" is the instance’s class.\n' - '\n' - 'I/O objects (also known as file objects)\n' - ' A *file object* represents an open file. Various shortcuts are\n' - ' available to create file objects: the "open()" built-in ' - 'function,\n' - ' and also "os.popen()", "os.fdopen()", and the "makefile()" ' - 'method\n' - ' of socket objects (and perhaps by other functions or methods\n' - ' provided by extension modules).\n' + ' "__class__" is the instance\'s class.\n' '\n' - ' The objects "sys.stdin", "sys.stdout" and "sys.stderr" are\n' - ' initialized to file objects corresponding to the interpreter’s\n' - ' standard input, output and error streams; they are all open in ' - 'text\n' - ' mode and therefore follow the interface defined by the\n' - ' "io.TextIOBase" abstract class.\n' + 'Files\n' + ' A file object represents an open file. File objects are created ' + 'by\n' + ' the "open()" built-in function, and also by "os.popen()",\n' + ' "os.fdopen()", and the "makefile()" method of socket objects ' + '(and\n' + ' perhaps by other functions or methods provided by extension\n' + ' modules). The objects "sys.stdin", "sys.stdout" and ' + '"sys.stderr"\n' + ' are initialized to file objects corresponding to the ' + "interpreter's\n" + ' standard input, output and error streams. See File Objects for\n' + ' complete documentation of file objects.\n' '\n' 'Internal types\n' ' A few types used internally by the interpreter are exposed to ' @@ -11859,7 +10958,7 @@ topics = {'assert': 'The "assert" statement\n' ' or *bytecode*. The difference between a code object and a\n' ' function object is that the function object contains an ' 'explicit\n' - ' reference to the function’s globals (the module in which it ' + " reference to the function's globals (the module in which it " 'was\n' ' defined), while a code object contains no context; also the\n' ' default argument values are stored in the function object, ' @@ -11874,36 +10973,33 @@ topics = {'assert': 'The "assert" statement\n' '\n' ' Special read-only attributes: "co_name" gives the function ' 'name;\n' - ' "co_argcount" is the total number of positional arguments\n' - ' (including positional-only arguments and arguments with ' - 'default\n' - ' values); "co_posonlyargcount" is the number of ' - 'positional-only\n' - ' arguments (including arguments with default values);\n' - ' "co_kwonlyargcount" is the number of keyword-only arguments\n' - ' (including arguments with default values); "co_nlocals" is ' - 'the\n' - ' number of local variables used by the function (including\n' - ' arguments); "co_varnames" is a tuple containing the names of ' - 'the\n' - ' local variables (starting with the argument names);\n' - ' "co_cellvars" is a tuple containing the names of local ' - 'variables\n' - ' that are referenced by nested functions; "co_freevars" is a\n' - ' tuple containing the names of free variables; "co_code" is a\n' - ' string representing the sequence of bytecode instructions;\n' - ' "co_consts" is a tuple containing the literals used by the\n' - ' bytecode; "co_names" is a tuple containing the names used by ' + ' "co_argcount" is the number of positional arguments ' + '(including\n' + ' arguments with default values); "co_nlocals" is the number ' + 'of\n' + ' local variables used by the function (including arguments);\n' + ' "co_varnames" is a tuple containing the names of the local\n' + ' variables (starting with the argument names); "co_cellvars" ' + 'is a\n' + ' tuple containing the names of local variables that are\n' + ' referenced by nested functions; "co_freevars" is a tuple\n' + ' containing the names of free variables; "co_code" is a ' + 'string\n' + ' representing the sequence of bytecode instructions; ' + '"co_consts"\n' + ' is a tuple containing the literals used by the bytecode;\n' + ' "co_names" is a tuple containing the names used by the ' + 'bytecode;\n' + ' "co_filename" is the filename from which the code was ' + 'compiled;\n' + ' "co_firstlineno" is the first line number of the function;\n' + ' "co_lnotab" is a string encoding the mapping from bytecode\n' + ' offsets to line numbers (for details see the source code of ' 'the\n' - ' bytecode; "co_filename" is the filename from which the code ' - 'was\n' - ' compiled; "co_firstlineno" is the first line number of the\n' - ' function; "co_lnotab" is a string encoding the mapping from\n' - ' bytecode offsets to line numbers (for details see the source\n' - ' code of the interpreter); "co_stacksize" is the required ' - 'stack\n' - ' size (including local variables); "co_flags" is an integer\n' - ' encoding a number of flags for the interpreter.\n' + ' interpreter); "co_stacksize" is the required stack size\n' + ' (including local variables); "co_flags" is an integer ' + 'encoding a\n' + ' number of flags for the interpreter.\n' '\n' ' The following flag bits are defined for "co_flags": bit ' '"0x04"\n' @@ -11935,9 +11031,7 @@ topics = {'assert': 'The "assert" statement\n' '\n' ' Frame objects\n' ' Frame objects represent execution frames. They may occur in\n' - ' traceback objects (see below), and are also passed to ' - 'registered\n' - ' trace functions.\n' + ' traceback objects (see below).\n' '\n' ' Special read-only attributes: "f_back" is to the previous ' 'stack\n' @@ -11946,68 +11040,49 @@ topics = {'assert': 'The "assert" statement\n' 'this\n' ' frame; "f_locals" is the dictionary used to look up local\n' ' variables; "f_globals" is used for global variables;\n' - ' "f_builtins" is used for built-in (intrinsic) names; ' - '"f_lasti"\n' - ' gives the precise instruction (this is an index into the\n' - ' bytecode string of the code object).\n' + ' "f_builtins" is used for built-in (intrinsic) names;\n' + ' "f_restricted" is a flag indicating whether the function is\n' + ' executing in restricted execution mode; "f_lasti" gives the\n' + ' precise instruction (this is an index into the bytecode ' + 'string\n' + ' of the code object).\n' '\n' ' Special writable attributes: "f_trace", if not "None", is a\n' - ' function called for various events during code execution ' - '(this\n' - ' is used by the debugger). Normally an event is triggered for\n' - ' each new source line - this can be disabled by setting\n' - ' "f_trace_lines" to "False".\n' - '\n' - ' Implementations *may* allow per-opcode events to be requested ' - 'by\n' - ' setting "f_trace_opcodes" to "True". Note that this may lead ' - 'to\n' - ' undefined interpreter behaviour if exceptions raised by the\n' - ' trace function escape to the function being traced.\n' - '\n' - ' "f_lineno" is the current line number of the frame — writing ' - 'to\n' - ' this from within a trace function jumps to the given line ' - '(only\n' - ' for the bottom-most frame). A debugger can implement a Jump\n' - ' command (aka Set Next Statement) by writing to f_lineno.\n' - '\n' - ' Frame objects support one method:\n' - '\n' - ' frame.clear()\n' - '\n' - ' This method clears all references to local variables held ' - 'by\n' - ' the frame. Also, if the frame belonged to a generator, ' + ' function called at the start of each source code line (this ' + 'is\n' + ' used by the debugger); "f_exc_type", "f_exc_value",\n' + ' "f_exc_traceback" represent the last exception raised in the\n' + ' parent frame provided another exception was ever raised in ' 'the\n' - ' generator is finalized. This helps break reference ' - 'cycles\n' - ' involving frame objects (for example when catching an\n' - ' exception and storing its traceback for later use).\n' - '\n' - ' "RuntimeError" is raised if the frame is currently ' - 'executing.\n' - '\n' - ' New in version 3.4.\n' + ' current frame (in all other cases they are "None"); ' + '"f_lineno"\n' + ' is the current line number of the frame --- writing to this ' + 'from\n' + ' within a trace function jumps to the given line (only for ' + 'the\n' + ' bottom-most frame). A debugger can implement a Jump command\n' + ' (aka Set Next Statement) by writing to f_lineno.\n' '\n' ' Traceback objects\n' ' Traceback objects represent a stack trace of an exception. ' 'A\n' - ' traceback object is implicitly created when an exception ' - 'occurs,\n' - ' and may also be explicitly created by calling\n' - ' "types.TracebackType".\n' - '\n' - ' For implicitly created tracebacks, when the search for an\n' - ' exception handler unwinds the execution stack, at each ' - 'unwound\n' - ' level a traceback object is inserted in front of the current\n' - ' traceback. When an exception handler is entered, the stack\n' - ' trace is made available to the program. (See section The try\n' - ' statement.) It is accessible as the third item of the tuple\n' - ' returned by "sys.exc_info()", and as the "__traceback__"\n' - ' attribute of the caught exception.\n' - '\n' + ' traceback object is created when an exception occurs. When ' + 'the\n' + ' search for an exception handler unwinds the execution stack, ' + 'at\n' + ' each unwound level a traceback object is inserted in front ' + 'of\n' + ' the current traceback. When an exception handler is ' + 'entered,\n' + ' the stack trace is made available to the program. (See ' + 'section\n' + ' The try statement.) It is accessible as "sys.exc_traceback", ' + 'and\n' + ' also as the third item of the tuple returned by\n' + ' "sys.exc_info()". The latter is the preferred interface, ' + 'since\n' + ' it works correctly when the program is using multiple ' + 'threads.\n' ' When the program contains no suitable handler, the stack ' 'trace\n' ' is written (nicely formatted) to the standard error stream; ' @@ -12016,41 +11091,31 @@ topics = {'assert': 'The "assert" statement\n' 'the\n' ' user as "sys.last_traceback".\n' '\n' - ' For explicitly created tracebacks, it is up to the creator ' - 'of\n' - ' the traceback to determine how the "tb_next" attributes ' - 'should\n' - ' be linked to form a full stack trace.\n' - '\n' - ' Special read-only attributes: "tb_frame" points to the ' - 'execution\n' - ' frame of the current level; "tb_lineno" gives the line ' - 'number\n' - ' where the exception occurred; "tb_lasti" indicates the ' - 'precise\n' - ' instruction. The line number and last instruction in the\n' - ' traceback may differ from the line number of its frame object ' - 'if\n' - ' the exception occurred in a "try" statement with no matching\n' - ' except clause or with a finally clause.\n' - '\n' - ' Special writable attribute: "tb_next" is the next level in ' + ' Special read-only attributes: "tb_next" is the next level in ' 'the\n' ' stack trace (towards the frame where the exception occurred), ' 'or\n' - ' "None" if there is no next level.\n' - '\n' - ' Changed in version 3.7: Traceback objects can now be ' - 'explicitly\n' - ' instantiated from Python code, and the "tb_next" attribute ' - 'of\n' - ' existing instances can be updated.\n' + ' "None" if there is no next level; "tb_frame" points to the\n' + ' execution frame of the current level; "tb_lineno" gives the ' + 'line\n' + ' number where the exception occurred; "tb_lasti" indicates ' + 'the\n' + ' precise instruction. The line number and last instruction ' + 'in\n' + ' the traceback may differ from the line number of its frame\n' + ' object if the exception occurred in a "try" statement with ' + 'no\n' + ' matching except clause or with a finally clause.\n' '\n' ' Slice objects\n' - ' Slice objects are used to represent slices for ' - '"__getitem__()"\n' - ' methods. They are also created by the built-in "slice()"\n' - ' function.\n' + ' Slice objects are used to represent slices when *extended ' + 'slice\n' + ' syntax* is used. This is a slice using two colons, or ' + 'multiple\n' + ' slices or ellipses separated by commas, e.g., "a[i:j:step]",\n' + ' "a[i:j, k:l]", or "a[..., i:j]". They are also created by ' + 'the\n' + ' built-in "slice()" function.\n' '\n' ' Special read-only attributes: "start" is the lower bound; ' '"stop"\n' @@ -12063,15 +11128,19 @@ topics = {'assert': 'The "assert" statement\n' ' slice.indices(self, length)\n' '\n' ' This method takes a single integer argument *length* and\n' - ' computes information about the slice that the slice ' - 'object\n' - ' would describe if applied to a sequence of *length* ' - 'items.\n' - ' It returns a tuple of three integers; respectively these ' - 'are\n' - ' the *start* and *stop* indices and the *step* or stride\n' - ' length of the slice. Missing or out-of-bounds indices are\n' - ' handled in a manner consistent with regular slices.\n' + ' computes information about the extended slice that the ' + 'slice\n' + ' object would describe if applied to a sequence of ' + '*length*\n' + ' items. It returns a tuple of three integers; ' + 'respectively\n' + ' these are the *start* and *stop* indices and the *step* ' + 'or\n' + ' stride length of the slice. Missing or out-of-bounds ' + 'indices\n' + ' are handled in a manner consistent with regular slices.\n' + '\n' + ' New in version 2.3.\n' '\n' ' Static method objects\n' ' Static method objects provide a way of defeating the\n' @@ -12097,10 +11166,11 @@ topics = {'assert': 'The "assert" statement\n' ' is retrieved from classes and class instances. The behaviour ' 'of\n' ' class method objects upon such retrieval is described above,\n' - ' under “User-defined methods”. Class method objects are ' + ' under "User-defined methods". Class method objects are ' 'created\n' ' by the built-in "classmethod()" constructor.\n', - 'typesfunctions': 'Functions\n' + 'typesfunctions': '\n' + 'Functions\n' '*********\n' '\n' 'Function objects are created by function definitions. The ' @@ -12117,19 +11187,20 @@ topics = {'assert': 'The "assert" statement\n' 'different object types.\n' '\n' 'See Function definitions for more information.\n', - 'typesmapping': 'Mapping Types — "dict"\n' - '**********************\n' + 'typesmapping': '\n' + 'Mapping Types --- "dict"\n' + '************************\n' '\n' 'A *mapping* object maps *hashable* values to arbitrary ' 'objects.\n' 'Mappings are mutable objects. There is currently only one ' 'standard\n' 'mapping type, the *dictionary*. (For other containers see ' - 'the built-\n' + 'the built\n' 'in "list", "set", and "tuple" classes, and the "collections" ' 'module.)\n' '\n' - 'A dictionary’s keys are *almost* arbitrary values. Values ' + "A dictionary's keys are *almost* arbitrary values. Values " 'that are\n' 'not *hashable*, that is, values containing lists, ' 'dictionaries or\n' @@ -12200,8 +11271,7 @@ topics = {'assert': 'The "assert" statement\n' " >>> c = dict(zip(['one', 'two', 'three'], [1, 2, 3]))\n" " >>> d = dict([('two', 2), ('one', 1), ('three', 3)])\n" " >>> e = dict({'three': 3, 'one': 1, 'two': 2})\n" - " >>> f = dict({'one': 1, 'three': 3}, two=2)\n" - ' >>> a == b == c == d == e == f\n' + ' >>> a == b == c == d == e\n' ' True\n' '\n' ' Providing keyword arguments as in the first example only ' @@ -12210,15 +11280,16 @@ topics = {'assert': 'The "assert" statement\n' 'valid keys\n' ' can be used.\n' '\n' + ' New in version 2.2.\n' + '\n' + ' Changed in version 2.3: Support for building a dictionary ' + 'from\n' + ' keyword arguments added.\n' + '\n' ' These are the operations that dictionaries support (and ' 'therefore,\n' ' custom mapping types should support too):\n' '\n' - ' list(d)\n' - '\n' - ' Return a list of all the keys used in the dictionary ' - '*d*.\n' - '\n' ' len(d)\n' '\n' ' Return the number of items in the dictionary *d*.\n' @@ -12259,6 +11330,10 @@ topics = {'assert': 'The "assert" statement\n' 'method is used\n' ' by "collections.defaultdict".\n' '\n' + ' New in version 2.5: Recognition of __missing__ methods ' + 'of dict\n' + ' subclasses.\n' + '\n' ' d[key] = value\n' '\n' ' Set "d[key]" to *value*.\n' @@ -12273,15 +11348,19 @@ topics = {'assert': 'The "assert" statement\n' '\n' ' Return "True" if *d* has a key *key*, else "False".\n' '\n' + ' New in version 2.2.\n' + '\n' ' key not in d\n' '\n' ' Equivalent to "not key in d".\n' '\n' + ' New in version 2.2.\n' + '\n' ' iter(d)\n' '\n' ' Return an iterator over the keys of the dictionary. ' 'This is a\n' - ' shortcut for "iter(d.keys())".\n' + ' shortcut for "iterkeys()".\n' '\n' ' clear()\n' '\n' @@ -12291,21 +11370,17 @@ topics = {'assert': 'The "assert" statement\n' '\n' ' Return a shallow copy of the dictionary.\n' '\n' - ' classmethod fromkeys(iterable[, value])\n' + ' fromkeys(seq[, value])\n' '\n' - ' Create a new dictionary with keys from *iterable* and ' - 'values set\n' - ' to *value*.\n' + ' Create a new dictionary with keys from *seq* and ' + 'values set to\n' + ' *value*.\n' '\n' ' "fromkeys()" is a class method that returns a new ' 'dictionary.\n' - ' *value* defaults to "None". All of the values refer ' - 'to just a\n' - ' single instance, so it generally doesn’t make sense ' - 'for *value*\n' - ' to be a mutable object such as an empty list. To get ' - 'distinct\n' - ' values, use a dict comprehension instead.\n' + ' *value* defaults to "None".\n' + '\n' + ' New in version 2.3.\n' '\n' ' get(key[, default])\n' '\n' @@ -12315,16 +11390,90 @@ topics = {'assert': 'The "assert" statement\n' '"None", so\n' ' that this method never raises a "KeyError".\n' '\n' + ' has_key(key)\n' + '\n' + ' Test for the presence of *key* in the dictionary. ' + '"has_key()"\n' + ' is deprecated in favor of "key in d".\n' + '\n' ' items()\n' '\n' - ' Return a new view of the dictionary’s items ("(key, ' - 'value)"\n' - ' pairs). See the documentation of view objects.\n' + ' Return a copy of the dictionary\'s list of "(key, ' + 'value)" pairs.\n' + '\n' + ' **CPython implementation detail:** Keys and values are ' + 'listed in\n' + ' an arbitrary order which is non-random, varies across ' + 'Python\n' + " implementations, and depends on the dictionary's " + 'history of\n' + ' insertions and deletions.\n' + '\n' + ' If "items()", "keys()", "values()", "iteritems()", ' + '"iterkeys()",\n' + ' and "itervalues()" are called with no intervening ' + 'modifications\n' + ' to the dictionary, the lists will directly ' + 'correspond. This\n' + ' allows the creation of "(value, key)" pairs using ' + '"zip()":\n' + ' "pairs = zip(d.values(), d.keys())". The same ' + 'relationship\n' + ' holds for the "iterkeys()" and "itervalues()" methods: ' + '"pairs =\n' + ' zip(d.itervalues(), d.iterkeys())" provides the same ' + 'value for\n' + ' "pairs". Another way to create the same list is "pairs ' + '= [(v, k)\n' + ' for (k, v) in d.iteritems()]".\n' + '\n' + ' iteritems()\n' + '\n' + ' Return an iterator over the dictionary\'s "(key, ' + 'value)" pairs.\n' + ' See the note for "dict.items()".\n' + '\n' + ' Using "iteritems()" while adding or deleting entries ' + 'in the\n' + ' dictionary may raise a "RuntimeError" or fail to ' + 'iterate over\n' + ' all entries.\n' + '\n' + ' New in version 2.2.\n' + '\n' + ' iterkeys()\n' + '\n' + " Return an iterator over the dictionary's keys. See " + 'the note for\n' + ' "dict.items()".\n' + '\n' + ' Using "iterkeys()" while adding or deleting entries in ' + 'the\n' + ' dictionary may raise a "RuntimeError" or fail to ' + 'iterate over\n' + ' all entries.\n' + '\n' + ' New in version 2.2.\n' + '\n' + ' itervalues()\n' + '\n' + " Return an iterator over the dictionary's values. See " + 'the note\n' + ' for "dict.items()".\n' + '\n' + ' Using "itervalues()" while adding or deleting entries ' + 'in the\n' + ' dictionary may raise a "RuntimeError" or fail to ' + 'iterate over\n' + ' all entries.\n' + '\n' + ' New in version 2.2.\n' '\n' ' keys()\n' '\n' - ' Return a new view of the dictionary’s keys. See the\n' - ' documentation of view objects.\n' + " Return a copy of the dictionary's list of keys. See " + 'the note\n' + ' for "dict.items()".\n' '\n' ' pop(key[, default])\n' '\n' @@ -12334,29 +11483,19 @@ topics = {'assert': 'The "assert" statement\n' '*key* is\n' ' not in the dictionary, a "KeyError" is raised.\n' '\n' + ' New in version 2.3.\n' + '\n' ' popitem()\n' '\n' - ' Remove and return a "(key, value)" pair from the ' - 'dictionary.\n' - ' Pairs are returned in LIFO (last-in, first-out) ' - 'order.\n' + ' Remove and return an arbitrary "(key, value)" pair ' + 'from the\n' + ' dictionary.\n' '\n' ' "popitem()" is useful to destructively iterate over a\n' ' dictionary, as often used in set algorithms. If the ' 'dictionary\n' ' is empty, calling "popitem()" raises a "KeyError".\n' '\n' - ' Changed in version 3.7: LIFO order is now guaranteed. ' - 'In prior\n' - ' versions, "popitem()" would return an arbitrary ' - 'key/value pair.\n' - '\n' - ' reversed(d)\n' - '\n' - ' Return a reverse iterator over the keys of the ' - 'dictionary. This\n' - ' is a shortcut for "reversed(d.keys())".\n' - '\n' ' setdefault(key[, default])\n' '\n' ' If *key* is in the dictionary, return its value. If ' @@ -12381,83 +11520,55 @@ topics = {'assert': 'The "assert" statement\n' '"d.update(red=1,\n' ' blue=2)".\n' '\n' + ' Changed in version 2.4: Allowed the argument to be an ' + 'iterable\n' + ' of key/value pairs and allowed keyword arguments.\n' + '\n' ' values()\n' '\n' - ' Return a new view of the dictionary’s values. See ' - 'the\n' + " Return a copy of the dictionary's list of values. See " + 'the note\n' + ' for "dict.items()".\n' + '\n' + ' viewitems()\n' + '\n' + ' Return a new view of the dictionary\'s items ("(key, ' + 'value)"\n' + ' pairs). See below for documentation of view objects.\n' + '\n' + ' New in version 2.7.\n' + '\n' + ' viewkeys()\n' + '\n' + " Return a new view of the dictionary's keys. See below " + 'for\n' ' documentation of view objects.\n' '\n' - ' An equality comparison between one "dict.values()" ' - 'view and\n' - ' another will always return "False". This also applies ' - 'when\n' - ' comparing "dict.values()" to itself:\n' + ' New in version 2.7.\n' + '\n' + ' viewvalues()\n' '\n' - " >>> d = {'a': 1}\n" - ' >>> d.values() == d.values()\n' - ' False\n' + " Return a new view of the dictionary's values. See " + 'below for\n' + ' documentation of view objects.\n' + '\n' + ' New in version 2.7.\n' '\n' ' Dictionaries compare equal if and only if they have the ' 'same "(key,\n' - ' value)" pairs (regardless of ordering). Order comparisons ' - '(‘<’,\n' - ' ‘<=’, ‘>=’, ‘>’) raise "TypeError".\n' - '\n' - ' Dictionaries preserve insertion order. Note that ' - 'updating a key\n' - ' does not affect the order. Keys added after deletion are ' - 'inserted\n' - ' at the end.\n' - '\n' - ' >>> d = {"one": 1, "two": 2, "three": 3, "four": 4}\n' - ' >>> d\n' - " {'one': 1, 'two': 2, 'three': 3, 'four': 4}\n" - ' >>> list(d)\n' - " ['one', 'two', 'three', 'four']\n" - ' >>> list(d.values())\n' - ' [1, 2, 3, 4]\n' - ' >>> d["one"] = 42\n' - ' >>> d\n' - " {'one': 42, 'two': 2, 'three': 3, 'four': 4}\n" - ' >>> del d["two"]\n' - ' >>> d["two"] = None\n' - ' >>> d\n' - " {'one': 42, 'three': 3, 'four': 4, 'two': None}\n" - '\n' - ' Changed in version 3.7: Dictionary order is guaranteed to ' - 'be\n' - ' insertion order. This behavior was an implementation ' - 'detail of\n' - ' CPython from 3.6.\n' - '\n' - ' Dictionaries and dictionary views are reversible.\n' - '\n' - ' >>> d = {"one": 1, "two": 2, "three": 3, "four": 4}\n' - ' >>> d\n' - " {'one': 1, 'two': 2, 'three': 3, 'four': 4}\n" - ' >>> list(reversed(d))\n' - " ['four', 'three', 'two', 'one']\n" - ' >>> list(reversed(d.values()))\n' - ' [4, 3, 2, 1]\n' - ' >>> list(reversed(d.items()))\n' - " [('four', 4), ('three', 3), ('two', 2), ('one', 1)]\n" - '\n' - ' Changed in version 3.8: Dictionaries are now reversible.\n' - '\n' - 'See also: "types.MappingProxyType" can be used to create a ' - 'read-only\n' - ' view of a "dict".\n' + ' value)" pairs.\n' '\n' '\n' 'Dictionary view objects\n' '=======================\n' '\n' - 'The objects returned by "dict.keys()", "dict.values()" and\n' - '"dict.items()" are *view objects*. They provide a dynamic ' - 'view on the\n' - 'dictionary’s entries, which means that when the dictionary ' - 'changes,\n' - 'the view reflects these changes.\n' + 'The objects returned by "dict.viewkeys()", ' + '"dict.viewvalues()" and\n' + '"dict.viewitems()" are *view objects*. They provide a ' + 'dynamic view on\n' + "the dictionary's entries, which means that when the " + 'dictionary\n' + 'changes, the view reflects these changes.\n' '\n' 'Dictionary views can be iterated over to yield their ' 'respective data,\n' @@ -12473,62 +11584,80 @@ topics = {'assert': 'The "assert" statement\n' '(represented as\n' ' tuples of "(key, value)") in the dictionary.\n' '\n' - ' Keys and values are iterated over in insertion order. ' - 'This allows\n' - ' the creation of "(value, key)" pairs using "zip()": ' - '"pairs =\n' - ' zip(d.values(), d.keys())". Another way to create the ' - 'same list is\n' - ' "pairs = [(v, k) for (k, v) in d.items()]".\n' + ' Keys and values are iterated over in an arbitrary order ' + 'which is\n' + ' non-random, varies across Python implementations, and ' + 'depends on\n' + " the dictionary's history of insertions and deletions. If " + 'keys,\n' + ' values and items views are iterated over with no ' + 'intervening\n' + ' modifications to the dictionary, the order of items will ' + 'directly\n' + ' correspond. This allows the creation of "(value, key)" ' + 'pairs using\n' + ' "zip()": "pairs = zip(d.values(), d.keys())". Another ' + 'way to\n' + ' create the same list is "pairs = [(v, k) for (k, v) in ' + 'd.items()]".\n' '\n' ' Iterating views while adding or deleting entries in the ' 'dictionary\n' ' may raise a "RuntimeError" or fail to iterate over all ' 'entries.\n' '\n' - ' Changed in version 3.7: Dictionary order is guaranteed to ' - 'be\n' - ' insertion order.\n' - '\n' 'x in dictview\n' '\n' - ' Return "True" if *x* is in the underlying dictionary’s ' + ' Return "True" if *x* is in the underlying dictionary\'s ' 'keys, values\n' ' or items (in the latter case, *x* should be a "(key, ' 'value)"\n' ' tuple).\n' '\n' - 'reversed(dictview)\n' + 'Keys views are set-like since their entries are unique and ' + 'hashable.\n' + 'If all values are hashable, so that (key, value) pairs are ' + 'unique and\n' + 'hashable, then the items view is also set-like. (Values ' + 'views are not\n' + 'treated as set-like since the entries are generally not ' + 'unique.) Then\n' + 'these set operations are available ("other" refers either to ' + 'another\n' + 'view or a set):\n' '\n' - ' Return a reverse iterator over the keys, values or items ' - 'of the\n' - ' dictionary. The view will be iterated in reverse order of ' - 'the\n' - ' insertion.\n' + 'dictview & other\n' '\n' - ' Changed in version 3.8: Dictionary views are now ' - 'reversible.\n' + ' Return the intersection of the dictview and the other ' + 'object as a\n' + ' new set.\n' '\n' - 'Keys views are set-like since their entries are unique and ' - 'hashable.\n' - 'If all values are hashable, so that "(key, value)" pairs are ' - 'unique\n' - 'and hashable, then the items view is also set-like. (Values ' - 'views are\n' - 'not treated as set-like since the entries are generally not ' - 'unique.)\n' - 'For set-like views, all of the operations defined for the ' - 'abstract\n' - 'base class "collections.abc.Set" are available (for example, ' - '"==",\n' - '"<", or "^").\n' + 'dictview | other\n' + '\n' + ' Return the union of the dictview and the other object as ' + 'a new set.\n' + '\n' + 'dictview - other\n' + '\n' + ' Return the difference between the dictview and the other ' + 'object\n' + " (all elements in *dictview* that aren't in *other*) as a " + 'new set.\n' + '\n' + 'dictview ^ other\n' + '\n' + ' Return the symmetric difference (all elements either in ' + '*dictview*\n' + ' or *other*, but not in both) of the dictview and the ' + 'other object\n' + ' as a new set.\n' '\n' 'An example of dictionary view usage:\n' '\n' " >>> dishes = {'eggs': 2, 'sausage': 1, 'bacon': 1, " "'spam': 500}\n" - ' >>> keys = dishes.keys()\n' - ' >>> values = dishes.values()\n' + ' >>> keys = dishes.viewkeys()\n' + ' >>> values = dishes.viewvalues()\n' '\n' ' >>> # iteration\n' ' >>> n = 0\n' @@ -12537,10 +11666,10 @@ topics = {'assert': 'The "assert" statement\n' ' >>> print(n)\n' ' 504\n' '\n' - ' >>> # keys and values are iterated over in the same order ' - '(insertion order)\n' + ' >>> # keys and values are iterated over in the same ' + 'order\n' ' >>> list(keys)\n' - " ['eggs', 'sausage', 'bacon', 'spam']\n" + " ['eggs', 'bacon', 'sausage', 'spam']\n" ' >>> list(values)\n' ' [2, 1, 1, 500]\n' '\n' @@ -12548,14 +11677,13 @@ topics = {'assert': 'The "assert" statement\n' " >>> del dishes['eggs']\n" " >>> del dishes['sausage']\n" ' >>> list(keys)\n' - " ['bacon', 'spam']\n" + " ['spam', 'bacon']\n" '\n' ' >>> # set operations\n' " >>> keys & {'eggs', 'bacon', 'salad'}\n" - " {'bacon'}\n" - " >>> keys ^ {'sausage', 'juice'}\n" - " {'juice', 'sausage', 'bacon', 'spam'}\n", - 'typesmethods': 'Methods\n' + " {'bacon'}\n", + 'typesmethods': '\n' + 'Methods\n' '*******\n' '\n' 'Methods are functions that are called using the attribute ' @@ -12566,35 +11694,43 @@ topics = {'assert': 'The "assert" statement\n' 'with the\n' 'types that support them.\n' '\n' - 'If you access a method (a function defined in a class ' - 'namespace)\n' - 'through an instance, you get a special object: a *bound ' - 'method* (also\n' - 'called *instance method*) object. When called, it will add ' - 'the "self"\n' - 'argument to the argument list. Bound methods have two ' - 'special read-\n' - 'only attributes: "m.__self__" is the object on which the ' + 'The implementation adds two special read-only attributes to ' + 'class\n' + 'instance methods: "m.im_self" is the object on which the ' 'method\n' - 'operates, and "m.__func__" is the function implementing the ' + 'operates, and "m.im_func" is the function implementing the ' 'method.\n' 'Calling "m(arg-1, arg-2, ..., arg-n)" is completely ' 'equivalent to\n' - 'calling "m.__func__(m.__self__, arg-1, arg-2, ..., arg-n)".\n' - '\n' - 'Like function objects, bound method objects support getting ' + 'calling "m.im_func(m.im_self, arg-1, arg-2, ..., arg-n)".\n' + '\n' + 'Class instance methods are either *bound* or *unbound*, ' + 'referring to\n' + 'whether the method was accessed through an instance or a ' + 'class,\n' + 'respectively. When a method is unbound, its "im_self" ' + 'attribute will\n' + 'be "None" and if called, an explicit "self" object must be ' + 'passed as\n' + 'the first argument. In this case, "self" must be an ' + 'instance of the\n' + "unbound method's class (or a subclass of that class), " + 'otherwise a\n' + '"TypeError" is raised.\n' + '\n' + 'Like function objects, methods objects support getting ' 'arbitrary\n' - 'attributes. However, since method attributes are actually ' + 'attributes. However, since method attributes are actually ' 'stored on\n' - 'the underlying function object ("meth.__func__"), setting ' + 'the underlying function object ("meth.im_func"), setting ' 'method\n' - 'attributes on bound methods is disallowed. Attempting to ' - 'set an\n' - 'attribute on a method results in an "AttributeError" being ' - 'raised. In\n' - 'order to set a method attribute, you need to explicitly set ' - 'it on the\n' - 'underlying function object:\n' + 'attributes on either bound or unbound methods is ' + 'disallowed.\n' + 'Attempting to set an attribute on a method results in an\n' + '"AttributeError" being raised. In order to set a method ' + 'attribute,\n' + 'you need to explicitly set it on the underlying function ' + 'object:\n' '\n' ' >>> class C:\n' ' ... def method(self):\n' @@ -12605,20 +11741,21 @@ topics = {'assert': 'The "assert" statement\n' 'the method\n' ' Traceback (most recent call last):\n' ' File "<stdin>", line 1, in <module>\n' - " AttributeError: 'method' object has no attribute " + " AttributeError: 'instancemethod' object has no attribute " "'whoami'\n" - " >>> c.method.__func__.whoami = 'my name is method'\n" + " >>> c.method.im_func.whoami = 'my name is method'\n" ' >>> c.method.whoami\n' " 'my name is method'\n" '\n' 'See The standard type hierarchy for more information.\n', - 'typesmodules': 'Modules\n' + 'typesmodules': '\n' + 'Modules\n' '*******\n' '\n' 'The only special operation on a module is attribute access: ' '"m.name",\n' 'where *m* is a module and *name* accesses a name defined in ' - '*m*’s\n' + "*m*'s\n" 'symbol table. Module attributes can be assigned to. (Note ' 'that the\n' '"import" statement is not, strictly speaking, an operation ' @@ -12631,14 +11768,14 @@ topics = {'assert': 'The "assert" statement\n' '\n' 'A special attribute of every module is "__dict__". This is ' 'the\n' - 'dictionary containing the module’s symbol table. Modifying ' + "dictionary containing the module's symbol table. Modifying " 'this\n' - 'dictionary will actually change the module’s symbol table, ' + "dictionary will actually change the module's symbol table, " 'but direct\n' 'assignment to the "__dict__" attribute is not possible (you ' 'can write\n' '"m.__dict__[\'a\'] = 1", which defines "m.a" to be "1", but ' - 'you can’t\n' + "you can't\n" 'write "m.__dict__ = {}"). Modifying "__dict__" directly is ' 'not\n' 'recommended.\n' @@ -12649,117 +11786,145 @@ topics = {'assert': 'The "assert" statement\n' 'written as\n' '"<module \'os\' from ' '\'/usr/local/lib/pythonX.Y/os.pyc\'>".\n', - 'typesseq': 'Sequence Types — "list", "tuple", "range"\n' - '*****************************************\n' - '\n' - 'There are three basic sequence types: lists, tuples, and range\n' - 'objects. Additional sequence types tailored for processing of ' - 'binary\n' - 'data and text strings are described in dedicated sections.\n' + 'typesseq': '\n' + 'Sequence Types --- "str", "unicode", "list", "tuple", ' + '"bytearray", "buffer", "xrange"\n' + '*************************************************************************************\n' '\n' + 'There are seven sequence types: strings, Unicode strings, ' + 'lists,\n' + 'tuples, bytearrays, buffers, and xrange objects.\n' '\n' - 'Common Sequence Operations\n' - '==========================\n' + 'For other containers see the built in "dict" and "set" classes, ' + 'and\n' + 'the "collections" module.\n' + '\n' + 'String literals are written in single or double quotes: ' + '"\'xyzzy\'",\n' + '""frobozz"". See String literals for more about string ' + 'literals.\n' + 'Unicode strings are much like strings, but are specified in the ' + 'syntax\n' + 'using a preceding "\'u\'" character: "u\'abc\'", "u"def"". In ' + 'addition to\n' + 'the functionality described here, there are also ' + 'string-specific\n' + 'methods described in the String Methods section. Lists are ' + 'constructed\n' + 'with square brackets, separating items with commas: "[a, b, ' + 'c]".\n' + 'Tuples are constructed by the comma operator (not within square\n' + 'brackets), with or without enclosing parentheses, but an empty ' + 'tuple\n' + 'must have the enclosing parentheses, such as "a, b, c" or "()". ' + 'A\n' + 'single item tuple must have a trailing comma, such as "(d,)".\n' + '\n' + 'Bytearray objects are created with the built-in function\n' + '"bytearray()".\n' + '\n' + 'Buffer objects are not directly supported by Python syntax, but ' + 'can be\n' + 'created by calling the built-in function "buffer()". They ' + "don't\n" + 'support concatenation or repetition.\n' + '\n' + 'Objects of type xrange are similar to buffers in that there is ' + 'no\n' + 'specific syntax to create them, but they are created using the\n' + '"xrange()" function. They don\'t support slicing, concatenation ' + 'or\n' + 'repetition, and using "in", "not in", "min()" or "max()" on them ' + 'is\n' + 'inefficient.\n' '\n' - 'The operations in the following table are supported by most ' - 'sequence\n' - 'types, both mutable and immutable. The ' - '"collections.abc.Sequence" ABC\n' - 'is provided to make it easier to correctly implement these ' - 'operations\n' - 'on custom sequence types.\n' + 'Most sequence types support the following operations. The "in" ' + 'and\n' + '"not in" operations have the same priorities as the comparison\n' + 'operations. The "+" and "*" operations have the same priority ' + 'as the\n' + 'corresponding numeric operations. [3] Additional methods are ' + 'provided\n' + 'for Mutable Sequence Types.\n' '\n' 'This table lists the sequence operations sorted in ascending ' 'priority.\n' - 'In the table, *s* and *t* are sequences of the same type, *n*, ' - '*i*,\n' - '*j* and *k* are integers and *x* is an arbitrary object that ' - 'meets any\n' - 'type and value restrictions imposed by *s*.\n' - '\n' - 'The "in" and "not in" operations have the same priorities as ' - 'the\n' - 'comparison operations. The "+" (concatenation) and "*" ' - '(repetition)\n' - 'operations have the same priority as the corresponding numeric\n' - 'operations. [3]\n' - '\n' - '+----------------------------+----------------------------------+------------+\n' - '| Operation | Result ' - '| Notes |\n' - '|============================|==================================|============|\n' - '| "x in s" | "True" if an item of *s* is ' - '| (1) |\n' - '| | equal to *x*, else "False" ' + 'In the table, *s* and *t* are sequences of the same type; *n*, ' + '*i* and\n' + '*j* are integers:\n' + '\n' + '+--------------------+----------------------------------+------------+\n' + '| Operation | Result | ' + 'Notes |\n' + '+====================+==================================+============+\n' + '| "x in s" | "True" if an item of *s* is | ' + '(1) |\n' + '| | equal to *x*, else "False" ' '| |\n' - '+----------------------------+----------------------------------+------------+\n' - '| "x not in s" | "False" if an item of *s* is ' - '| (1) |\n' - '| | equal to *x*, else "True" ' + '+--------------------+----------------------------------+------------+\n' + '| "x not in s" | "False" if an item of *s* is | ' + '(1) |\n' + '| | equal to *x*, else "True" ' '| |\n' - '+----------------------------+----------------------------------+------------+\n' - '| "s + t" | the concatenation of *s* and *t* ' - '| (6)(7) |\n' - '+----------------------------+----------------------------------+------------+\n' - '| "s * n" or "n * s" | equivalent to adding *s* to ' - '| (2)(7) |\n' - '| | itself *n* times ' + '+--------------------+----------------------------------+------------+\n' + '| "s + t" | the concatenation of *s* and *t* | ' + '(6) |\n' + '+--------------------+----------------------------------+------------+\n' + '| "s * n, n * s" | equivalent to adding *s* to | ' + '(2) |\n' + '| | itself *n* times ' '| |\n' - '+----------------------------+----------------------------------+------------+\n' - '| "s[i]" | *i*th item of *s*, origin 0 ' - '| (3) |\n' - '+----------------------------+----------------------------------+------------+\n' - '| "s[i:j]" | slice of *s* from *i* to *j* ' - '| (3)(4) |\n' - '+----------------------------+----------------------------------+------------+\n' - '| "s[i:j:k]" | slice of *s* from *i* to *j* ' - '| (3)(5) |\n' - '| | with step *k* ' + '+--------------------+----------------------------------+------------+\n' + '| "s[i]" | *i*th item of *s*, origin 0 | ' + '(3) |\n' + '+--------------------+----------------------------------+------------+\n' + '| "s[i:j]" | slice of *s* from *i* to *j* | ' + '(3)(4) |\n' + '+--------------------+----------------------------------+------------+\n' + '| "s[i:j:k]" | slice of *s* from *i* to *j* | ' + '(3)(5) |\n' + '| | with step *k* ' '| |\n' - '+----------------------------+----------------------------------+------------+\n' - '| "len(s)" | length of *s* ' + '+--------------------+----------------------------------+------------+\n' + '| "len(s)" | length of *s* ' '| |\n' - '+----------------------------+----------------------------------+------------+\n' - '| "min(s)" | smallest item of *s* ' + '+--------------------+----------------------------------+------------+\n' + '| "min(s)" | smallest item of *s* ' '| |\n' - '+----------------------------+----------------------------------+------------+\n' - '| "max(s)" | largest item of *s* ' + '+--------------------+----------------------------------+------------+\n' + '| "max(s)" | largest item of *s* ' '| |\n' - '+----------------------------+----------------------------------+------------+\n' - '| "s.index(x[, i[, j]])" | index of the first occurrence of ' - '| (8) |\n' - '| | *x* in *s* (at or after index ' + '+--------------------+----------------------------------+------------+\n' + '| "s.index(x)" | index of the first occurrence of ' '| |\n' - '| | *i* and before index *j*) ' + '| | *x* in *s* ' '| |\n' - '+----------------------------+----------------------------------+------------+\n' - '| "s.count(x)" | total number of occurrences of ' + '+--------------------+----------------------------------+------------+\n' + '| "s.count(x)" | total number of occurrences of ' '| |\n' - '| | *x* in *s* ' + '| | *x* in *s* ' '| |\n' - '+----------------------------+----------------------------------+------------+\n' - '\n' - 'Sequences of the same type also support comparisons. In ' - 'particular,\n' - 'tuples and lists are compared lexicographically by comparing\n' - 'corresponding elements. This means that to compare equal, every\n' - 'element must compare equal and the two sequences must be of the ' - 'same\n' - 'type and have the same length. (For full details see ' - 'Comparisons in\n' - 'the language reference.)\n' + '+--------------------+----------------------------------+------------+\n' '\n' - 'Notes:\n' + 'Sequence types also support comparisons. In particular, tuples ' + 'and\n' + 'lists are compared lexicographically by comparing corresponding\n' + 'elements. This means that to compare equal, every element must ' + 'compare\n' + 'equal and the two sequences must be of the same type and have ' + 'the same\n' + 'length. (For full details see Comparisons in the language ' + 'reference.)\n' '\n' - '1. While the "in" and "not in" operations are used only for ' - 'simple\n' - ' containment testing in the general case, some specialised ' - 'sequences\n' - ' (such as "str", "bytes" and "bytearray") also use them for\n' - ' subsequence testing:\n' + 'Notes:\n' '\n' - ' >>> "gg" in "eggs"\n' - ' True\n' + '1. When *s* is a string or Unicode string object the "in" and ' + '"not\n' + ' in" operations act like a substring test. In Python ' + 'versions\n' + ' before 2.3, *x* had to be a string of length 1. In Python 2.3 ' + 'and\n' + ' beyond, *x* may be a string of any length.\n' '\n' '2. Values of *n* less than "0" are treated as "0" (which yields ' 'an\n' @@ -12769,12 +11934,12 @@ topics = {'assert': 'The "assert" statement\n' 'times.\n' ' This often haunts new Python programmers; consider:\n' '\n' - ' >>> lists = [[]] * 3\n' - ' >>> lists\n' - ' [[], [], []]\n' - ' >>> lists[0].append(3)\n' - ' >>> lists\n' - ' [[3], [3], [3]]\n' + ' >>> lists = [[]] * 3\n' + ' >>> lists\n' + ' [[], [], []]\n' + ' >>> lists[0].append(3)\n' + ' >>> lists\n' + ' [[3], [3], [3]]\n' '\n' ' What has happened is that "[[]]" is a one-element list ' 'containing\n' @@ -12784,12 +11949,12 @@ topics = {'assert': 'The "assert" statement\n' ' "lists" modifies this single list. You can create a list of\n' ' different lists this way:\n' '\n' - ' >>> lists = [[] for i in range(3)]\n' - ' >>> lists[0].append(3)\n' - ' >>> lists[1].append(5)\n' - ' >>> lists[2].append(7)\n' - ' >>> lists\n' - ' [[3], [5], [7]]\n' + ' >>> lists = [[] for i in range(3)]\n' + ' >>> lists[0].append(3)\n' + ' >>> lists[1].append(5)\n' + ' >>> lists[2].append(7)\n' + ' >>> lists\n' + ' [[3], [5], [7]]\n' '\n' ' Further explanation is available in the FAQ entry How do I ' 'create a\n' @@ -12824,99 +11989,981 @@ topics = {'assert': 'The "assert" statement\n' '*j* are\n' ' reduced to "len(s) - 1" if they are greater. If *i* or *j* ' 'are\n' - ' omitted or "None", they become “end” values (which end ' + ' omitted or "None", they become "end" values (which end ' 'depends on\n' ' the sign of *k*). Note, *k* cannot be zero. If *k* is ' '"None", it\n' ' is treated like "1".\n' '\n' - '6. Concatenating immutable sequences always results in a new\n' - ' object. This means that building up a sequence by repeated\n' - ' concatenation will have a quadratic runtime cost in the ' - 'total\n' - ' sequence length. To get a linear runtime cost, you must ' - 'switch to\n' - ' one of the alternatives below:\n' + '6. **CPython implementation detail:** If *s* and *t* are both\n' + ' strings, some Python implementations such as CPython can ' + 'usually\n' + ' perform an in-place optimization for assignments of the form ' + '"s = s\n' + ' + t" or "s += t". When applicable, this optimization makes\n' + ' quadratic run-time much less likely. This optimization is ' + 'both\n' + ' version and implementation dependent. For performance ' + 'sensitive\n' + ' code, it is preferable to use the "str.join()" method which ' + 'assures\n' + ' consistent linear concatenation performance across versions ' + 'and\n' + ' implementations.\n' + '\n' + ' Changed in version 2.4: Formerly, string concatenation never\n' + ' occurred in-place.\n' + '\n' '\n' - ' * if concatenating "str" objects, you can build a list and ' + 'String Methods\n' + '==============\n' + '\n' + 'Below are listed the string methods which both 8-bit strings ' + 'and\n' + 'Unicode objects support. Some of them are also available on\n' + '"bytearray" objects.\n' + '\n' + "In addition, Python's strings support the sequence type methods\n" + 'described in the Sequence Types --- str, unicode, list, tuple,\n' + 'bytearray, buffer, xrange section. To output formatted strings ' 'use\n' - ' "str.join()" at the end or else write to an "io.StringIO"\n' - ' instance and retrieve its value when complete\n' - '\n' - ' * if concatenating "bytes" objects, you can similarly use\n' - ' "bytes.join()" or "io.BytesIO", or you can do in-place\n' - ' concatenation with a "bytearray" object. "bytearray" ' - 'objects are\n' - ' mutable and have an efficient overallocation mechanism\n' - '\n' - ' * if concatenating "tuple" objects, extend a "list" instead\n' - '\n' - ' * for other types, investigate the relevant class ' - 'documentation\n' - '\n' - '7. Some sequence types (such as "range") only support item\n' - ' sequences that follow specific patterns, and hence don’t ' - 'support\n' - ' sequence concatenation or repetition.\n' - '\n' - '8. "index" raises "ValueError" when *x* is not found in *s*. ' - 'Not\n' - ' all implementations support passing the additional arguments ' - '*i*\n' - ' and *j*. These arguments allow efficient searching of ' - 'subsections\n' - ' of the sequence. Passing the extra arguments is roughly ' - 'equivalent\n' - ' to using "s[i:j].index(x)", only without copying any data and ' - 'with\n' - ' the returned index being relative to the start of the ' + 'template strings or the "%" operator described in the String\n' + 'Formatting Operations section. Also, see the "re" module for ' + 'string\n' + 'functions based on regular expressions.\n' + '\n' + 'str.capitalize()\n' + '\n' + ' Return a copy of the string with its first character ' + 'capitalized\n' + ' and the rest lowercased.\n' + '\n' + ' For 8-bit strings, this method is locale-dependent.\n' + '\n' + 'str.center(width[, fillchar])\n' + '\n' + ' Return centered in a string of length *width*. Padding is ' + 'done\n' + ' using the specified *fillchar* (default is a space).\n' + '\n' + ' Changed in version 2.4: Support for the *fillchar* argument.\n' + '\n' + 'str.count(sub[, start[, end]])\n' + '\n' + ' Return the number of non-overlapping occurrences of substring ' + '*sub*\n' + ' in the range [*start*, *end*]. Optional arguments *start* ' + 'and\n' + ' *end* are interpreted as in slice notation.\n' + '\n' + 'str.decode([encoding[, errors]])\n' + '\n' + ' Decodes the string using the codec registered for ' + '*encoding*.\n' + ' *encoding* defaults to the default string encoding. *errors* ' + 'may\n' + ' be given to set a different error handling scheme. The ' + 'default is\n' + ' "\'strict\'", meaning that encoding errors raise ' + '"UnicodeError".\n' + ' Other possible values are "\'ignore\'", "\'replace\'" and any ' + 'other\n' + ' name registered via "codecs.register_error()", see section ' + 'Codec\n' + ' Base Classes.\n' + '\n' + ' New in version 2.2.\n' + '\n' + ' Changed in version 2.3: Support for other error handling ' + 'schemes\n' + ' added.\n' + '\n' + ' Changed in version 2.7: Support for keyword arguments added.\n' + '\n' + 'str.encode([encoding[, errors]])\n' + '\n' + ' Return an encoded version of the string. Default encoding is ' + 'the\n' + ' current default string encoding. *errors* may be given to ' + 'set a\n' + ' different error handling scheme. The default for *errors* ' + 'is\n' + ' "\'strict\'", meaning that encoding errors raise a ' + '"UnicodeError".\n' + ' Other possible values are "\'ignore\'", "\'replace\'",\n' + ' "\'xmlcharrefreplace\'", "\'backslashreplace\'" and any other ' + 'name\n' + ' registered via "codecs.register_error()", see section Codec ' + 'Base\n' + ' Classes. For a list of possible encodings, see section ' + 'Standard\n' + ' Encodings.\n' + '\n' + ' New in version 2.0.\n' + '\n' + ' Changed in version 2.3: Support for "\'xmlcharrefreplace\'" ' + 'and\n' + ' "\'backslashreplace\'" and other error handling schemes ' + 'added.\n' + '\n' + ' Changed in version 2.7: Support for keyword arguments added.\n' + '\n' + 'str.endswith(suffix[, start[, end]])\n' + '\n' + ' Return "True" if the string ends with the specified ' + '*suffix*,\n' + ' otherwise return "False". *suffix* can also be a tuple of ' + 'suffixes\n' + ' to look for. With optional *start*, test beginning at that\n' + ' position. With optional *end*, stop comparing at that ' + 'position.\n' + '\n' + ' Changed in version 2.5: Accept tuples as *suffix*.\n' + '\n' + 'str.expandtabs([tabsize])\n' + '\n' + ' Return a copy of the string where all tab characters are ' + 'replaced\n' + ' by one or more spaces, depending on the current column and ' + 'the\n' + ' given tab size. Tab positions occur every *tabsize* ' + 'characters\n' + ' (default is 8, giving tab positions at columns 0, 8, 16 and ' + 'so on).\n' + ' To expand the string, the current column is set to zero and ' + 'the\n' + ' string is examined character by character. If the character ' + 'is a\n' + ' tab ("\\t"), one or more space characters are inserted in the ' + 'result\n' + ' until the current column is equal to the next tab position. ' + '(The\n' + ' tab character itself is not copied.) If the character is a ' + 'newline\n' + ' ("\\n") or return ("\\r"), it is copied and the current ' + 'column is\n' + ' reset to zero. Any other character is copied unchanged and ' + 'the\n' + ' current column is incremented by one regardless of how the\n' + ' character is represented when printed.\n' + '\n' + " >>> '01\\t012\\t0123\\t01234'.expandtabs()\n" + " '01 012 0123 01234'\n" + " >>> '01\\t012\\t0123\\t01234'.expandtabs(4)\n" + " '01 012 0123 01234'\n" + '\n' + 'str.find(sub[, start[, end]])\n' + '\n' + ' Return the lowest index in the string where substring *sub* ' + 'is\n' + ' found within the slice "s[start:end]". Optional arguments ' + '*start*\n' + ' and *end* are interpreted as in slice notation. Return "-1" ' + 'if\n' + ' *sub* is not found.\n' + '\n' + ' Note: The "find()" method should be used only if you need to ' + 'know\n' + ' the position of *sub*. To check if *sub* is a substring or ' + 'not,\n' + ' use the "in" operator:\n' + '\n' + " >>> 'Py' in 'Python'\n" + ' True\n' + '\n' + 'str.format(*args, **kwargs)\n' + '\n' + ' Perform a string formatting operation. The string on which ' + 'this\n' + ' method is called can contain literal text or replacement ' + 'fields\n' + ' delimited by braces "{}". Each replacement field contains ' + 'either\n' + ' the numeric index of a positional argument, or the name of a\n' + ' keyword argument. Returns a copy of the string where each\n' + ' replacement field is replaced with the string value of the\n' + ' corresponding argument.\n' + '\n' + ' >>> "The sum of 1 + 2 is {0}".format(1+2)\n' + " 'The sum of 1 + 2 is 3'\n" + '\n' + ' See Format String Syntax for a description of the various\n' + ' formatting options that can be specified in format strings.\n' + '\n' + ' This method of string formatting is the new standard in ' + 'Python 3,\n' + ' and should be preferred to the "%" formatting described in ' + 'String\n' + ' Formatting Operations in new code.\n' + '\n' + ' New in version 2.6.\n' + '\n' + 'str.index(sub[, start[, end]])\n' + '\n' + ' Like "find()", but raise "ValueError" when the substring is ' + 'not\n' + ' found.\n' + '\n' + 'str.isalnum()\n' + '\n' + ' Return true if all characters in the string are alphanumeric ' + 'and\n' + ' there is at least one character, false otherwise.\n' + '\n' + ' For 8-bit strings, this method is locale-dependent.\n' + '\n' + 'str.isalpha()\n' + '\n' + ' Return true if all characters in the string are alphabetic ' + 'and\n' + ' there is at least one character, false otherwise.\n' + '\n' + ' For 8-bit strings, this method is locale-dependent.\n' + '\n' + 'str.isdigit()\n' + '\n' + ' Return true if all characters in the string are digits and ' + 'there is\n' + ' at least one character, false otherwise.\n' + '\n' + ' For 8-bit strings, this method is locale-dependent.\n' + '\n' + 'str.islower()\n' + '\n' + ' Return true if all cased characters [4] in the string are ' + 'lowercase\n' + ' and there is at least one cased character, false otherwise.\n' + '\n' + ' For 8-bit strings, this method is locale-dependent.\n' + '\n' + 'str.isspace()\n' + '\n' + ' Return true if there are only whitespace characters in the ' + 'string\n' + ' and there is at least one character, false otherwise.\n' + '\n' + ' For 8-bit strings, this method is locale-dependent.\n' + '\n' + 'str.istitle()\n' + '\n' + ' Return true if the string is a titlecased string and there is ' + 'at\n' + ' least one character, for example uppercase characters may ' + 'only\n' + ' follow uncased characters and lowercase characters only cased ' + 'ones.\n' + ' Return false otherwise.\n' + '\n' + ' For 8-bit strings, this method is locale-dependent.\n' + '\n' + 'str.isupper()\n' + '\n' + ' Return true if all cased characters [4] in the string are ' + 'uppercase\n' + ' and there is at least one cased character, false otherwise.\n' + '\n' + ' For 8-bit strings, this method is locale-dependent.\n' + '\n' + 'str.join(iterable)\n' + '\n' + ' Return a string which is the concatenation of the strings in\n' + ' *iterable*. A "TypeError" will be raised if there are any ' + 'non-\n' + ' string values in *iterable*, including "bytes" objects. The\n' + ' separator between elements is the string providing this ' + 'method.\n' + '\n' + 'str.ljust(width[, fillchar])\n' + '\n' + ' Return the string left justified in a string of length ' + '*width*.\n' + ' Padding is done using the specified *fillchar* (default is a\n' + ' space). The original string is returned if *width* is less ' + 'than or\n' + ' equal to "len(s)".\n' + '\n' + ' Changed in version 2.4: Support for the *fillchar* argument.\n' + '\n' + 'str.lower()\n' + '\n' + ' Return a copy of the string with all the cased characters ' + '[4]\n' + ' converted to lowercase.\n' + '\n' + ' For 8-bit strings, this method is locale-dependent.\n' + '\n' + 'str.lstrip([chars])\n' + '\n' + ' Return a copy of the string with leading characters removed. ' + 'The\n' + ' *chars* argument is a string specifying the set of characters ' + 'to be\n' + ' removed. If omitted or "None", the *chars* argument defaults ' + 'to\n' + ' removing whitespace. The *chars* argument is not a prefix; ' + 'rather,\n' + ' all combinations of its values are stripped:\n' + '\n' + " >>> ' spacious '.lstrip()\n" + " 'spacious '\n" + " >>> 'www.example.com'.lstrip('cmowz.')\n" + " 'example.com'\n" + '\n' + ' Changed in version 2.2.2: Support for the *chars* argument.\n' + '\n' + 'str.partition(sep)\n' + '\n' + ' Split the string at the first occurrence of *sep*, and return ' + 'a\n' + ' 3-tuple containing the part before the separator, the ' + 'separator\n' + ' itself, and the part after the separator. If the separator ' + 'is not\n' + ' found, return a 3-tuple containing the string itself, ' + 'followed by\n' + ' two empty strings.\n' + '\n' + ' New in version 2.5.\n' + '\n' + 'str.replace(old, new[, count])\n' + '\n' + ' Return a copy of the string with all occurrences of substring ' + '*old*\n' + ' replaced by *new*. If the optional argument *count* is ' + 'given, only\n' + ' the first *count* occurrences are replaced.\n' + '\n' + 'str.rfind(sub[, start[, end]])\n' + '\n' + ' Return the highest index in the string where substring *sub* ' + 'is\n' + ' found, such that *sub* is contained within "s[start:end]".\n' + ' Optional arguments *start* and *end* are interpreted as in ' + 'slice\n' + ' notation. Return "-1" on failure.\n' + '\n' + 'str.rindex(sub[, start[, end]])\n' + '\n' + ' Like "rfind()" but raises "ValueError" when the substring ' + '*sub* is\n' + ' not found.\n' + '\n' + 'str.rjust(width[, fillchar])\n' + '\n' + ' Return the string right justified in a string of length ' + '*width*.\n' + ' Padding is done using the specified *fillchar* (default is a\n' + ' space). The original string is returned if *width* is less ' + 'than or\n' + ' equal to "len(s)".\n' + '\n' + ' Changed in version 2.4: Support for the *fillchar* argument.\n' + '\n' + 'str.rpartition(sep)\n' + '\n' + ' Split the string at the last occurrence of *sep*, and return ' + 'a\n' + ' 3-tuple containing the part before the separator, the ' + 'separator\n' + ' itself, and the part after the separator. If the separator ' + 'is not\n' + ' found, return a 3-tuple containing two empty strings, ' + 'followed by\n' + ' the string itself.\n' + '\n' + ' New in version 2.5.\n' + '\n' + 'str.rsplit([sep[, maxsplit]])\n' + '\n' + ' Return a list of the words in the string, using *sep* as the\n' + ' delimiter string. If *maxsplit* is given, at most *maxsplit* ' + 'splits\n' + ' are done, the *rightmost* ones. If *sep* is not specified ' + 'or\n' + ' "None", any whitespace string is a separator. Except for ' + 'splitting\n' + ' from the right, "rsplit()" behaves like "split()" which is\n' + ' described in detail below.\n' + '\n' + ' New in version 2.4.\n' + '\n' + 'str.rstrip([chars])\n' + '\n' + ' Return a copy of the string with trailing characters ' + 'removed. The\n' + ' *chars* argument is a string specifying the set of characters ' + 'to be\n' + ' removed. If omitted or "None", the *chars* argument defaults ' + 'to\n' + ' removing whitespace. The *chars* argument is not a suffix; ' + 'rather,\n' + ' all combinations of its values are stripped:\n' + '\n' + " >>> ' spacious '.rstrip()\n" + " ' spacious'\n" + " >>> 'mississippi'.rstrip('ipz')\n" + " 'mississ'\n" + '\n' + ' Changed in version 2.2.2: Support for the *chars* argument.\n' + '\n' + 'str.split([sep[, maxsplit]])\n' + '\n' + ' Return a list of the words in the string, using *sep* as the\n' + ' delimiter string. If *maxsplit* is given, at most ' + '*maxsplit*\n' + ' splits are done (thus, the list will have at most ' + '"maxsplit+1"\n' + ' elements). If *maxsplit* is not specified or "-1", then ' + 'there is\n' + ' no limit on the number of splits (all possible splits are ' + 'made).\n' + '\n' + ' If *sep* is given, consecutive delimiters are not grouped ' + 'together\n' + ' and are deemed to delimit empty strings (for example,\n' + ' "\'1,,2\'.split(\',\')" returns "[\'1\', \'\', \'2\']"). The ' + '*sep* argument\n' + ' may consist of multiple characters (for example,\n' + ' "\'1<>2<>3\'.split(\'<>\')" returns "[\'1\', \'2\', \'3\']"). ' + 'Splitting an\n' + ' empty string with a specified separator returns "[\'\']".\n' + '\n' + ' If *sep* is not specified or is "None", a different ' + 'splitting\n' + ' algorithm is applied: runs of consecutive whitespace are ' + 'regarded\n' + ' as a single separator, and the result will contain no empty ' + 'strings\n' + ' at the start or end if the string has leading or trailing\n' + ' whitespace. Consequently, splitting an empty string or a ' + 'string\n' + ' consisting of just whitespace with a "None" separator returns ' + '"[]".\n' + '\n' + ' For example, "\' 1 2 3 \'.split()" returns "[\'1\', ' + '\'2\', \'3\']", and\n' + ' "\' 1 2 3 \'.split(None, 1)" returns "[\'1\', \'2 3 ' + '\']".\n' + '\n' + 'str.splitlines([keepends])\n' + '\n' + ' Return a list of the lines in the string, breaking at line\n' + ' boundaries. This method uses the *universal newlines* ' + 'approach to\n' + ' splitting lines. Line breaks are not included in the ' + 'resulting list\n' + ' unless *keepends* is given and true.\n' + '\n' + ' Python recognizes ""\\r"", ""\\n"", and ""\\r\\n"" as line ' + 'boundaries\n' + ' for 8-bit strings.\n' + '\n' + ' For example:\n' + '\n' + " >>> 'ab c\\n\\nde fg\\rkl\\r\\n'.splitlines()\n" + " ['ab c', '', 'de fg', 'kl']\n" + " >>> 'ab c\\n\\nde fg\\rkl\\r\\n'.splitlines(True)\n" + " ['ab c\\n', '\\n', 'de fg\\r', 'kl\\r\\n']\n" + '\n' + ' Unlike "split()" when a delimiter string *sep* is given, ' + 'this\n' + ' method returns an empty list for the empty string, and a ' + 'terminal\n' + ' line break does not result in an extra line:\n' + '\n' + ' >>> "".splitlines()\n' + ' []\n' + ' >>> "One line\\n".splitlines()\n' + " ['One line']\n" + '\n' + ' For comparison, "split(\'\\n\')" gives:\n' + '\n' + " >>> ''.split('\\n')\n" + " ['']\n" + " >>> 'Two lines\\n'.split('\\n')\n" + " ['Two lines', '']\n" + '\n' + 'unicode.splitlines([keepends])\n' + '\n' + ' Return a list of the lines in the string, like ' + '"str.splitlines()".\n' + ' However, the Unicode method splits on the following line\n' + ' boundaries, which are a superset of the *universal newlines*\n' + ' recognized for 8-bit strings.\n' + '\n' + ' +-------------------------+-------------------------------+\n' + ' | Representation | Description |\n' + ' +=========================+===============================+\n' + ' | "\\n" | Line Feed |\n' + ' +-------------------------+-------------------------------+\n' + ' | "\\r" | Carriage Return |\n' + ' +-------------------------+-------------------------------+\n' + ' | "\\r\\n" | Carriage Return + Line Feed ' + '|\n' + ' +-------------------------+-------------------------------+\n' + ' | "\\v" or "\\x0b" | Line Tabulation ' + '|\n' + ' +-------------------------+-------------------------------+\n' + ' | "\\f" or "\\x0c" | Form Feed ' + '|\n' + ' +-------------------------+-------------------------------+\n' + ' | "\\x1c" | File Separator |\n' + ' +-------------------------+-------------------------------+\n' + ' | "\\x1d" | Group Separator |\n' + ' +-------------------------+-------------------------------+\n' + ' | "\\x1e" | Record Separator |\n' + ' +-------------------------+-------------------------------+\n' + ' | "\\x85" | Next Line (C1 Control Code) |\n' + ' +-------------------------+-------------------------------+\n' + ' | "\\u2028" | Line Separator |\n' + ' +-------------------------+-------------------------------+\n' + ' | "\\u2029" | Paragraph Separator |\n' + ' +-------------------------+-------------------------------+\n' + '\n' + ' Changed in version 2.7: "\\v" and "\\f" added to list of ' + 'line\n' + ' boundaries.\n' + '\n' + 'str.startswith(prefix[, start[, end]])\n' + '\n' + ' Return "True" if string starts with the *prefix*, otherwise ' + 'return\n' + ' "False". *prefix* can also be a tuple of prefixes to look ' + 'for.\n' + ' With optional *start*, test string beginning at that ' + 'position.\n' + ' With optional *end*, stop comparing string at that position.\n' + '\n' + ' Changed in version 2.5: Accept tuples as *prefix*.\n' + '\n' + 'str.strip([chars])\n' + '\n' + ' Return a copy of the string with the leading and trailing\n' + ' characters removed. The *chars* argument is a string ' + 'specifying the\n' + ' set of characters to be removed. If omitted or "None", the ' + '*chars*\n' + ' argument defaults to removing whitespace. The *chars* ' + 'argument is\n' + ' not a prefix or suffix; rather, all combinations of its ' + 'values are\n' + ' stripped:\n' + '\n' + " >>> ' spacious '.strip()\n" + " 'spacious'\n" + " >>> 'www.example.com'.strip('cmowz.')\n" + " 'example'\n" + '\n' + ' Changed in version 2.2.2: Support for the *chars* argument.\n' + '\n' + 'str.swapcase()\n' + '\n' + ' Return a copy of the string with uppercase characters ' + 'converted to\n' + ' lowercase and vice versa.\n' + '\n' + ' For 8-bit strings, this method is locale-dependent.\n' + '\n' + 'str.title()\n' + '\n' + ' Return a titlecased version of the string where words start ' + 'with an\n' + ' uppercase character and the remaining characters are ' + 'lowercase.\n' + '\n' + ' The algorithm uses a simple language-independent definition ' + 'of a\n' + ' word as groups of consecutive letters. The definition works ' + 'in\n' + ' many contexts but it means that apostrophes in contractions ' + 'and\n' + ' possessives form word boundaries, which may not be the ' + 'desired\n' + ' result:\n' + '\n' + ' >>> "they\'re bill\'s friends from the UK".title()\n' + ' "They\'Re Bill\'S Friends From The Uk"\n' + '\n' + ' A workaround for apostrophes can be constructed using ' + 'regular\n' + ' expressions:\n' + '\n' + ' >>> import re\n' + ' >>> def titlecase(s):\n' + ' ... return re.sub(r"[A-Za-z]+(\'[A-Za-z]+)?",\n' + ' ... lambda mo: mo.group(0)[0].upper() +\n' + ' ... mo.group(0)[1:].lower(),\n' + ' ... s)\n' + ' ...\n' + ' >>> titlecase("they\'re bill\'s friends.")\n' + ' "They\'re Bill\'s Friends."\n' + '\n' + ' For 8-bit strings, this method is locale-dependent.\n' + '\n' + 'str.translate(table[, deletechars])\n' + '\n' + ' Return a copy of the string where all characters occurring in ' + 'the\n' + ' optional argument *deletechars* are removed, and the ' + 'remaining\n' + ' characters have been mapped through the given translation ' + 'table,\n' + ' which must be a string of length 256.\n' + '\n' + ' You can use the "maketrans()" helper function in the ' + '"string"\n' + ' module to create a translation table. For string objects, set ' + 'the\n' + ' *table* argument to "None" for translations that only delete\n' + ' characters:\n' + '\n' + " >>> 'read this short text'.translate(None, 'aeiou')\n" + " 'rd ths shrt txt'\n" + '\n' + ' New in version 2.6: Support for a "None" *table* argument.\n' + '\n' + ' For Unicode objects, the "translate()" method does not accept ' + 'the\n' + ' optional *deletechars* argument. Instead, it returns a copy ' + 'of the\n' + ' *s* where all characters have been mapped through the given\n' + ' translation table which must be a mapping of Unicode ordinals ' + 'to\n' + ' Unicode ordinals, Unicode strings or "None". Unmapped ' + 'characters\n' + ' are left untouched. Characters mapped to "None" are deleted. ' + 'Note,\n' + ' a more flexible approach is to create a custom character ' + 'mapping\n' + ' codec using the "codecs" module (see "encodings.cp1251" for ' + 'an\n' + ' example).\n' + '\n' + 'str.upper()\n' + '\n' + ' Return a copy of the string with all the cased characters ' + '[4]\n' + ' converted to uppercase. Note that "str.upper().isupper()" ' + 'might be\n' + ' "False" if "s" contains uncased characters or if the Unicode\n' + ' category of the resulting character(s) is not "Lu" (Letter,\n' + ' uppercase), but e.g. "Lt" (Letter, titlecase).\n' + '\n' + ' For 8-bit strings, this method is locale-dependent.\n' + '\n' + 'str.zfill(width)\n' + '\n' + ' Return the numeric string left filled with zeros in a string ' + 'of\n' + ' length *width*. A sign prefix is handled correctly. The ' + 'original\n' + ' string is returned if *width* is less than or equal to ' + '"len(s)".\n' + '\n' + ' New in version 2.2.2.\n' + '\n' + 'The following methods are present only on unicode objects:\n' + '\n' + 'unicode.isnumeric()\n' + '\n' + ' Return "True" if there are only numeric characters in S, ' + '"False"\n' + ' otherwise. Numeric characters include digit characters, and ' + 'all\n' + ' characters that have the Unicode numeric value property, ' + 'e.g.\n' + ' U+2155, VULGAR FRACTION ONE FIFTH.\n' + '\n' + 'unicode.isdecimal()\n' + '\n' + ' Return "True" if there are only decimal characters in S, ' + '"False"\n' + ' otherwise. Decimal characters include digit characters, and ' + 'all\n' + ' characters that can be used to form decimal-radix numbers, ' + 'e.g.\n' + ' U+0660, ARABIC-INDIC DIGIT ZERO.\n' + '\n' + '\n' + 'String Formatting Operations\n' + '============================\n' + '\n' + 'String and Unicode objects have one unique built-in operation: ' + 'the "%"\n' + 'operator (modulo). This is also known as the string ' + '*formatting* or\n' + '*interpolation* operator. Given "format % values" (where ' + '*format* is\n' + 'a string or Unicode object), "%" conversion specifications in ' + '*format*\n' + 'are replaced with zero or more elements of *values*. The effect ' + 'is\n' + 'similar to the using "sprintf()" in the C language. If *format* ' + 'is a\n' + 'Unicode object, or if any of the objects being converted using ' + 'the\n' + '"%s" conversion are Unicode objects, the result will also be a ' + 'Unicode\n' + 'object.\n' + '\n' + 'If *format* requires a single argument, *values* may be a single ' + 'non-\n' + 'tuple object. [5] Otherwise, *values* must be a tuple with ' + 'exactly\n' + 'the number of items specified by the format string, or a single\n' + 'mapping object (for example, a dictionary).\n' + '\n' + 'A conversion specifier contains two or more characters and has ' + 'the\n' + 'following components, which must occur in this order:\n' + '\n' + '1. The "\'%\'" character, which marks the start of the ' + 'specifier.\n' + '\n' + '2. Mapping key (optional), consisting of a parenthesised ' 'sequence\n' - ' rather than the start of the slice.\n' + ' of characters (for example, "(somename)").\n' '\n' + '3. Conversion flags (optional), which affect the result of some\n' + ' conversion types.\n' '\n' - 'Immutable Sequence Types\n' - '========================\n' + '4. Minimum field width (optional). If specified as an "\'*\'"\n' + ' (asterisk), the actual width is read from the next element of ' + 'the\n' + ' tuple in *values*, and the object to convert comes after the\n' + ' minimum field width and optional precision.\n' + '\n' + '5. Precision (optional), given as a "\'.\'" (dot) followed by ' + 'the\n' + ' precision. If specified as "\'*\'" (an asterisk), the actual ' + 'width\n' + ' is read from the next element of the tuple in *values*, and ' + 'the\n' + ' value to convert comes after the precision.\n' '\n' - 'The only operation that immutable sequence types generally ' - 'implement\n' - 'that is not also implemented by mutable sequence types is ' - 'support for\n' - 'the "hash()" built-in.\n' + '6. Length modifier (optional).\n' + '\n' + '7. Conversion type.\n' + '\n' + 'When the right argument is a dictionary (or other mapping type), ' + 'then\n' + 'the formats in the string *must* include a parenthesised mapping ' + 'key\n' + 'into that dictionary inserted immediately after the "\'%\'" ' + 'character.\n' + 'The mapping key selects the value to be formatted from the ' + 'mapping.\n' + 'For example:\n' + '\n' + ">>> print '%(language)s has %(number)03d quote types.' % \\\n" + '... {"language": "Python", "number": 2}\n' + 'Python has 002 quote types.\n' + '\n' + 'In this case no "*" specifiers may occur in a format (since ' + 'they\n' + 'require a sequential parameter list).\n' + '\n' + 'The conversion flag characters are:\n' + '\n' + '+-----------+-----------------------------------------------------------------------+\n' + '| Flag | ' + 'Meaning ' + '|\n' + '+===========+=======================================================================+\n' + '| "\'#\'" | The value conversion will use the "alternate ' + 'form" (where defined |\n' + '| | ' + 'below). ' + '|\n' + '+-----------+-----------------------------------------------------------------------+\n' + '| "\'0\'" | The conversion will be zero padded for numeric ' + 'values. |\n' + '+-----------+-----------------------------------------------------------------------+\n' + '| "\'-\'" | The converted value is left adjusted (overrides ' + 'the "\'0\'" conversion |\n' + '| | if both are ' + 'given). |\n' + '+-----------+-----------------------------------------------------------------------+\n' + '| "\' \'" | (a space) A blank should be left before a ' + 'positive number (or empty |\n' + '| | string) produced by a signed ' + 'conversion. |\n' + '+-----------+-----------------------------------------------------------------------+\n' + '| "\'+\'" | A sign character ("\'+\'" or "\'-\'") will ' + 'precede the conversion |\n' + '| | (overrides a "space" ' + 'flag). |\n' + '+-----------+-----------------------------------------------------------------------+\n' + '\n' + 'A length modifier ("h", "l", or "L") may be present, but is ' + 'ignored as\n' + 'it is not necessary for Python -- so e.g. "%ld" is identical to ' + '"%d".\n' + '\n' + 'The conversion types are:\n' + '\n' + '+--------------+-------------------------------------------------------+---------+\n' + '| Conversion | ' + 'Meaning | Notes ' + '|\n' + '+==============+=======================================================+=========+\n' + '| "\'d\'" | Signed integer ' + 'decimal. | |\n' + '+--------------+-------------------------------------------------------+---------+\n' + '| "\'i\'" | Signed integer ' + 'decimal. | |\n' + '+--------------+-------------------------------------------------------+---------+\n' + '| "\'o\'" | Signed octal ' + 'value. | (1) |\n' + '+--------------+-------------------------------------------------------+---------+\n' + '| "\'u\'" | Obsolete type -- it is identical to ' + '"\'d\'". | (7) |\n' + '+--------------+-------------------------------------------------------+---------+\n' + '| "\'x\'" | Signed hexadecimal ' + '(lowercase). | (2) |\n' + '+--------------+-------------------------------------------------------+---------+\n' + '| "\'X\'" | Signed hexadecimal ' + '(uppercase). | (2) |\n' + '+--------------+-------------------------------------------------------+---------+\n' + '| "\'e\'" | Floating point exponential format ' + '(lowercase). | (3) |\n' + '+--------------+-------------------------------------------------------+---------+\n' + '| "\'E\'" | Floating point exponential format ' + '(uppercase). | (3) |\n' + '+--------------+-------------------------------------------------------+---------+\n' + '| "\'f\'" | Floating point decimal ' + 'format. | (3) |\n' + '+--------------+-------------------------------------------------------+---------+\n' + '| "\'F\'" | Floating point decimal ' + 'format. | (3) |\n' + '+--------------+-------------------------------------------------------+---------+\n' + '| "\'g\'" | Floating point format. Uses lowercase ' + 'exponential | (4) |\n' + '| | format if exponent is less than -4 or not less ' + 'than | |\n' + '| | precision, decimal format ' + 'otherwise. | |\n' + '+--------------+-------------------------------------------------------+---------+\n' + '| "\'G\'" | Floating point format. Uses uppercase ' + 'exponential | (4) |\n' + '| | format if exponent is less than -4 or not less ' + 'than | |\n' + '| | precision, decimal format ' + 'otherwise. | |\n' + '+--------------+-------------------------------------------------------+---------+\n' + '| "\'c\'" | Single character (accepts integer or single ' + 'character | |\n' + '| | ' + 'string). | ' + '|\n' + '+--------------+-------------------------------------------------------+---------+\n' + '| "\'r\'" | String (converts any Python object using ' + 'repr()). | (5) |\n' + '+--------------+-------------------------------------------------------+---------+\n' + '| "\'s\'" | String (converts any Python object using ' + '"str()"). | (6) |\n' + '+--------------+-------------------------------------------------------+---------+\n' + '| "\'%\'" | No argument is converted, results in a ' + '"\'%\'" | |\n' + '| | character in the ' + 'result. | |\n' + '+--------------+-------------------------------------------------------+---------+\n' + '\n' + 'Notes:\n' + '\n' + '1. The alternate form causes a leading zero ("\'0\'") to be ' + 'inserted\n' + ' between left-hand padding and the formatting of the number if ' + 'the\n' + ' leading character of the result is not already a zero.\n' '\n' - 'This support allows immutable sequences, such as "tuple" ' - 'instances, to\n' - 'be used as "dict" keys and stored in "set" and "frozenset" ' - 'instances.\n' + '2. The alternate form causes a leading "\'0x\'" or "\'0X\'" ' + '(depending\n' + ' on whether the "\'x\'" or "\'X\'" format was used) to be ' + 'inserted\n' + ' before the first digit.\n' '\n' - 'Attempting to hash an immutable sequence that contains ' - 'unhashable\n' - 'values will result in "TypeError".\n' + '3. The alternate form causes the result to always contain a ' + 'decimal\n' + ' point, even if no digits follow it.\n' + '\n' + ' The precision determines the number of digits after the ' + 'decimal\n' + ' point and defaults to 6.\n' + '\n' + '4. The alternate form causes the result to always contain a ' + 'decimal\n' + ' point, and trailing zeroes are not removed as they would ' + 'otherwise\n' + ' be.\n' + '\n' + ' The precision determines the number of significant digits ' + 'before\n' + ' and after the decimal point and defaults to 6.\n' + '\n' + '5. The "%r" conversion was added in Python 2.0.\n' + '\n' + ' The precision determines the maximal number of characters ' + 'used.\n' + '\n' + '6. If the object or format provided is a "unicode" string, the\n' + ' resulting string will also be "unicode".\n' + '\n' + ' The precision determines the maximal number of characters ' + 'used.\n' + '\n' + '7. See **PEP 237**.\n' + '\n' + 'Since Python strings have an explicit length, "%s" conversions ' + 'do not\n' + 'assume that "\'\\0\'" is the end of the string.\n' + '\n' + 'Changed in version 2.7: "%f" conversions for numbers whose ' + 'absolute\n' + 'value is over 1e50 are no longer replaced by "%g" conversions.\n' + '\n' + 'Additional string operations are defined in standard modules ' + '"string"\n' + 'and "re".\n' + '\n' + '\n' + 'XRange Type\n' + '===========\n' + '\n' + 'The "xrange" type is an immutable sequence which is commonly ' + 'used for\n' + 'looping. The advantage of the "xrange" type is that an ' + '"xrange"\n' + 'object will always take the same amount of memory, no matter the ' + 'size\n' + 'of the range it represents. There are no consistent ' + 'performance\n' + 'advantages.\n' + '\n' + 'XRange objects have very little behavior: they only support ' + 'indexing,\n' + 'iteration, and the "len()" function.\n' '\n' '\n' 'Mutable Sequence Types\n' '======================\n' '\n' - 'The operations in the following table are defined on mutable ' - 'sequence\n' - 'types. The "collections.abc.MutableSequence" ABC is provided to ' - 'make\n' - 'it easier to correctly implement these operations on custom ' - 'sequence\n' - 'types.\n' - '\n' - 'In the table *s* is an instance of a mutable sequence type, *t* ' - 'is any\n' - 'iterable object and *x* is an arbitrary object that meets any ' - 'type and\n' - 'value restrictions imposed by *s* (for example, "bytearray" ' - 'only\n' - 'accepts integers that meet the value restriction "0 <= x <= ' - '255").\n' + 'List and "bytearray" objects support additional operations that ' + 'allow\n' + 'in-place modification of the object. Other mutable sequence ' + 'types\n' + '(when added to the language) should also support these ' + 'operations.\n' + 'Strings and tuples are immutable sequence types: such objects ' + 'cannot\n' + 'be modified once created. The following operations are defined ' + 'on\n' + 'mutable sequence types (where *x* is an arbitrary object):\n' '\n' '+--------------------------------+----------------------------------+-----------------------+\n' '| Operation | ' 'Result | Notes |\n' - '|================================|==================================|=======================|\n' + '+================================+==================================+=======================+\n' '| "s[i] = x" | item *i* of *s* is replaced ' 'by | |\n' '| | ' @@ -12942,443 +12989,192 @@ topics = {'assert': 'The "assert" statement\n' '| | "s[i:j:k]" from the ' 'list | |\n' '+--------------------------------+----------------------------------+-----------------------+\n' - '| "s.append(x)" | appends *x* to the end of ' - 'the | |\n' - '| | sequence (same ' - 'as | |\n' - '| | "s[len(s):len(s)] = ' - '[x]") | |\n' - '+--------------------------------+----------------------------------+-----------------------+\n' - '| "s.clear()" | removes all items from *s* ' - '(same | (5) |\n' - '| | as "del ' - 's[:]") | |\n' + '| "s.append(x)" | same as "s[len(s):len(s)] = ' + '[x]" | (2) |\n' '+--------------------------------+----------------------------------+-----------------------+\n' - '| "s.copy()" | creates a shallow copy of ' - '*s* | (5) |\n' - '| | (same as ' - '"s[:]") | |\n' - '+--------------------------------+----------------------------------+-----------------------+\n' - '| "s.extend(t)" or "s += t" | extends *s* with the contents ' - 'of | |\n' - '| | *t* (for the most part the ' - 'same | |\n' - '| | as "s[len(s):len(s)] = ' - 't") | |\n' + '| "s.extend(t)" or "s += t" | for the most part the same ' + 'as | (3) |\n' + '| | "s[len(s):len(s)] = ' + 't" | |\n' '+--------------------------------+----------------------------------+-----------------------+\n' '| "s *= n" | updates *s* with its ' - 'contents | (6) |\n' + 'contents | (11) |\n' '| | repeated *n* ' 'times | |\n' '+--------------------------------+----------------------------------+-----------------------+\n' - '| "s.insert(i, x)" | inserts *x* into *s* at ' - 'the | |\n' - '| | index given by *i* (same ' - 'as | |\n' - '| | "s[i:i] = ' - '[x]") | |\n' + '| "s.count(x)" | return number of *i*\'s for ' + 'which | |\n' + '| | "s[i] == ' + 'x" | |\n' + '+--------------------------------+----------------------------------+-----------------------+\n' + '| "s.index(x[, i[, j]])" | return smallest *k* such ' + 'that | (4) |\n' + '| | "s[k] == x" and "i <= k < ' + 'j" | |\n' + '+--------------------------------+----------------------------------+-----------------------+\n' + '| "s.insert(i, x)" | same as "s[i:i] = ' + '[x]" | (5) |\n' '+--------------------------------+----------------------------------+-----------------------+\n' - '| "s.pop([i])" | retrieves the item at *i* ' - 'and | (2) |\n' - '| | also removes it from ' - '*s* | |\n' + '| "s.pop([i])" | same as "x = s[i]; del ' + 's[i]; | (6) |\n' + '| | return ' + 'x" | |\n' '+--------------------------------+----------------------------------+-----------------------+\n' - '| "s.remove(x)" | remove the first item from ' - '*s* | (3) |\n' - '| | where "s[i]" is equal to ' - '*x* | |\n' + '| "s.remove(x)" | same as "del ' + 's[s.index(x)]" | (4) |\n' '+--------------------------------+----------------------------------+-----------------------+\n' '| "s.reverse()" | reverses the items of *s* ' - 'in | (4) |\n' + 'in | (7) |\n' '| | ' 'place | |\n' '+--------------------------------+----------------------------------+-----------------------+\n' + '| "s.sort([cmp[, key[, | sort the items of *s* in ' + 'place | (7)(8)(9)(10) |\n' + '| reverse]]])" ' + '| | |\n' + '+--------------------------------+----------------------------------+-----------------------+\n' '\n' 'Notes:\n' '\n' - '1. *t* must have the same length as the slice it is replacing.\n' - '\n' - '2. The optional argument *i* defaults to "-1", so that by ' - 'default\n' - ' the last item is removed and returned.\n' - '\n' - '3. "remove()" raises "ValueError" when *x* is not found in *s*.\n' - '\n' - '4. The "reverse()" method modifies the sequence in place for\n' - ' economy of space when reversing a large sequence. To remind ' - 'users\n' - ' that it operates by side effect, it does not return the ' - 'reversed\n' - ' sequence.\n' - '\n' - '5. "clear()" and "copy()" are included for consistency with the\n' - ' interfaces of mutable containers that don’t support slicing\n' - ' operations (such as "dict" and "set"). "copy()" is not part ' - 'of the\n' - ' "collections.abc.MutableSequence" ABC, but most concrete ' - 'mutable\n' - ' sequence classes provide it.\n' - '\n' - ' New in version 3.3: "clear()" and "copy()" methods.\n' - '\n' - '6. The value *n* is an integer, or an object implementing\n' - ' "__index__()". Zero and negative values of *n* clear the ' - 'sequence.\n' - ' Items in the sequence are not copied; they are referenced ' - 'multiple\n' - ' times, as explained for "s * n" under Common Sequence ' - 'Operations.\n' + '1. *t* must have the same length as the slice it is replacing.\n' '\n' + '2. The C implementation of Python has historically accepted\n' + ' multiple parameters and implicitly joined them into a tuple; ' + 'this\n' + ' no longer works in Python 2.0. Use of this misfeature has ' + 'been\n' + ' deprecated since Python 1.4.\n' '\n' - 'Lists\n' - '=====\n' - '\n' - 'Lists are mutable sequences, typically used to store collections ' - 'of\n' - 'homogeneous items (where the precise degree of similarity will ' - 'vary by\n' - 'application).\n' - '\n' - 'class list([iterable])\n' - '\n' - ' Lists may be constructed in several ways:\n' - '\n' - ' * Using a pair of square brackets to denote the empty list: ' - '"[]"\n' - '\n' - ' * Using square brackets, separating items with commas: ' - '"[a]",\n' - ' "[a, b, c]"\n' - '\n' - ' * Using a list comprehension: "[x for x in iterable]"\n' - '\n' - ' * Using the type constructor: "list()" or "list(iterable)"\n' + '3. *t* can be any iterable object.\n' '\n' - ' The constructor builds a list whose items are the same and in ' + '4. Raises "ValueError" when *x* is not found in *s*. When a\n' + ' negative index is passed as the second or third parameter to ' 'the\n' - ' same order as *iterable*’s items. *iterable* may be either ' - 'a\n' - ' sequence, a container that supports iteration, or an ' - 'iterator\n' - ' object. If *iterable* is already a list, a copy is made and\n' - ' returned, similar to "iterable[:]". For example, ' - '"list(\'abc\')"\n' - ' returns "[\'a\', \'b\', \'c\']" and "list( (1, 2, 3) )" ' - 'returns "[1, 2,\n' - ' 3]". If no argument is given, the constructor creates a new ' - 'empty\n' - ' list, "[]".\n' - '\n' - ' Many other operations also produce lists, including the ' - '"sorted()"\n' - ' built-in.\n' - '\n' - ' Lists implement all of the common and mutable sequence ' - 'operations.\n' - ' Lists also provide the following additional method:\n' + ' "index()" method, the list length is added, as for slice ' + 'indices.\n' + ' If it is still negative, it is truncated to zero, as for ' + 'slice\n' + ' indices.\n' '\n' - ' sort(*, key=None, reverse=False)\n' + ' Changed in version 2.3: Previously, "index()" didn\'t have ' + 'arguments\n' + ' for specifying start and stop positions.\n' '\n' - ' This method sorts the list in place, using only "<" ' - 'comparisons\n' - ' between items. Exceptions are not suppressed - if any ' - 'comparison\n' - ' operations fail, the entire sort operation will fail (and ' + '5. When a negative index is passed as the first parameter to ' 'the\n' - ' list will likely be left in a partially modified state).\n' - '\n' - ' "sort()" accepts two arguments that can only be passed by\n' - ' keyword (keyword-only arguments):\n' - '\n' - ' *key* specifies a function of one argument that is used ' - 'to\n' - ' extract a comparison key from each list element (for ' - 'example,\n' - ' "key=str.lower"). The key corresponding to each item in ' - 'the list\n' - ' is calculated once and then used for the entire sorting ' - 'process.\n' - ' The default value of "None" means that list items are ' - 'sorted\n' - ' directly without calculating a separate key value.\n' - '\n' - ' The "functools.cmp_to_key()" utility is available to ' - 'convert a\n' - ' 2.x style *cmp* function to a *key* function.\n' - '\n' - ' *reverse* is a boolean value. If set to "True", then the ' - 'list\n' - ' elements are sorted as if each comparison were reversed.\n' - '\n' - ' This method modifies the sequence in place for economy of ' - 'space\n' - ' when sorting a large sequence. To remind users that it ' - 'operates\n' - ' by side effect, it does not return the sorted sequence ' - '(use\n' - ' "sorted()" to explicitly request a new sorted list ' - 'instance).\n' - '\n' - ' The "sort()" method is guaranteed to be stable. A sort ' - 'is\n' - ' stable if it guarantees not to change the relative order ' - 'of\n' - ' elements that compare equal — this is helpful for sorting ' - 'in\n' - ' multiple passes (for example, sort by department, then by ' - 'salary\n' - ' grade).\n' - '\n' - ' For sorting examples and a brief sorting tutorial, see ' - 'Sorting\n' - ' HOW TO.\n' - '\n' - ' **CPython implementation detail:** While a list is being ' - 'sorted,\n' - ' the effect of attempting to mutate, or even inspect, the ' - 'list is\n' - ' undefined. The C implementation of Python makes the list ' - 'appear\n' - ' empty for the duration, and raises "ValueError" if it can ' - 'detect\n' - ' that the list has been mutated during a sort.\n' - '\n' - '\n' - 'Tuples\n' - '======\n' - '\n' - 'Tuples are immutable sequences, typically used to store ' - 'collections of\n' - 'heterogeneous data (such as the 2-tuples produced by the ' - '"enumerate()"\n' - 'built-in). Tuples are also used for cases where an immutable ' - 'sequence\n' - 'of homogeneous data is needed (such as allowing storage in a ' - '"set" or\n' - '"dict" instance).\n' - '\n' - 'class tuple([iterable])\n' - '\n' - ' Tuples may be constructed in a number of ways:\n' - '\n' - ' * Using a pair of parentheses to denote the empty tuple: ' - '"()"\n' - '\n' - ' * Using a trailing comma for a singleton tuple: "a," or ' - '"(a,)"\n' + ' "insert()" method, the list length is added, as for slice ' + 'indices.\n' + ' If it is still negative, it is truncated to zero, as for ' + 'slice\n' + ' indices.\n' '\n' - ' * Separating items with commas: "a, b, c" or "(a, b, c)"\n' + ' Changed in version 2.3: Previously, all negative indices ' + 'were\n' + ' truncated to zero.\n' '\n' - ' * Using the "tuple()" built-in: "tuple()" or ' - '"tuple(iterable)"\n' + '6. The "pop()" method\'s optional argument *i* defaults to "-1", ' + 'so\n' + ' that by default the last item is removed and returned.\n' '\n' - ' The constructor builds a tuple whose items are the same and ' - 'in the\n' - ' same order as *iterable*’s items. *iterable* may be either ' - 'a\n' - ' sequence, a container that supports iteration, or an ' - 'iterator\n' - ' object. If *iterable* is already a tuple, it is returned\n' - ' unchanged. For example, "tuple(\'abc\')" returns "(\'a\', ' - '\'b\', \'c\')"\n' - ' and "tuple( [1, 2, 3] )" returns "(1, 2, 3)". If no argument ' - 'is\n' - ' given, the constructor creates a new empty tuple, "()".\n' + '7. The "sort()" and "reverse()" methods modify the list in ' + 'place\n' + ' for economy of space when sorting or reversing a large list. ' + 'To\n' + " remind you that they operate by side effect, they don't " + 'return the\n' + ' sorted or reversed list.\n' '\n' - ' Note that it is actually the comma which makes a tuple, not ' + '8. The "sort()" method takes optional arguments for controlling ' 'the\n' - ' parentheses. The parentheses are optional, except in the ' - 'empty\n' - ' tuple case, or when they are needed to avoid syntactic ' - 'ambiguity.\n' - ' For example, "f(a, b, c)" is a function call with three ' - 'arguments,\n' - ' while "f((a, b, c))" is a function call with a 3-tuple as the ' - 'sole\n' - ' argument.\n' - '\n' - ' Tuples implement all of the common sequence operations.\n' - '\n' - 'For heterogeneous collections of data where access by name is ' - 'clearer\n' - 'than access by index, "collections.namedtuple()" may be a more\n' - 'appropriate choice than a simple tuple object.\n' + ' comparisons.\n' '\n' + ' *cmp* specifies a custom comparison function of two arguments ' + '(list\n' + ' items) which should return a negative, zero or positive ' + 'number\n' + ' depending on whether the first argument is considered smaller ' + 'than,\n' + ' equal to, or larger than the second argument: "cmp=lambda ' + 'x,y:\n' + ' cmp(x.lower(), y.lower())". The default value is "None".\n' + '\n' + ' *key* specifies a function of one argument that is used to ' + 'extract\n' + ' a comparison key from each list element: "key=str.lower". ' + 'The\n' + ' default value is "None".\n' '\n' - 'Ranges\n' - '======\n' + ' *reverse* is a boolean value. If set to "True", then the ' + 'list\n' + ' elements are sorted as if each comparison were reversed.\n' '\n' - 'The "range" type represents an immutable sequence of numbers and ' + ' In general, the *key* and *reverse* conversion processes are ' + 'much\n' + ' faster than specifying an equivalent *cmp* function. This ' 'is\n' - 'commonly used for looping a specific number of times in "for" ' - 'loops.\n' - '\n' - 'class range(stop)\n' - 'class range(start, stop[, step])\n' - '\n' - ' The arguments to the range constructor must be integers ' - '(either\n' - ' built-in "int" or any object that implements the "__index__"\n' - ' special method). If the *step* argument is omitted, it ' - 'defaults to\n' - ' "1". If the *start* argument is omitted, it defaults to "0". ' - 'If\n' - ' *step* is zero, "ValueError" is raised.\n' - '\n' - ' For a positive *step*, the contents of a range "r" are ' - 'determined\n' - ' by the formula "r[i] = start + step*i" where "i >= 0" and ' - '"r[i] <\n' - ' stop".\n' - '\n' - ' For a negative *step*, the contents of the range are still\n' - ' determined by the formula "r[i] = start + step*i", but the\n' - ' constraints are "i >= 0" and "r[i] > stop".\n' - '\n' - ' A range object will be empty if "r[0]" does not meet the ' - 'value\n' - ' constraint. Ranges do support negative indices, but these ' - 'are\n' - ' interpreted as indexing from the end of the sequence ' - 'determined by\n' - ' the positive indices.\n' - '\n' - ' Ranges containing absolute values larger than "sys.maxsize" ' - 'are\n' - ' permitted but some features (such as "len()") may raise\n' - ' "OverflowError".\n' - '\n' - ' Range examples:\n' - '\n' - ' >>> list(range(10))\n' - ' [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]\n' - ' >>> list(range(1, 11))\n' - ' [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]\n' - ' >>> list(range(0, 30, 5))\n' - ' [0, 5, 10, 15, 20, 25]\n' - ' >>> list(range(0, 10, 3))\n' - ' [0, 3, 6, 9]\n' - ' >>> list(range(0, -10, -1))\n' - ' [0, -1, -2, -3, -4, -5, -6, -7, -8, -9]\n' - ' >>> list(range(0))\n' - ' []\n' - ' >>> list(range(1, 0))\n' - ' []\n' - '\n' - ' Ranges implement all of the common sequence operations ' - 'except\n' - ' concatenation and repetition (due to the fact that range ' - 'objects\n' - ' can only represent sequences that follow a strict pattern ' - 'and\n' - ' repetition and concatenation will usually violate that ' - 'pattern).\n' - '\n' - ' start\n' - '\n' - ' The value of the *start* parameter (or "0" if the ' - 'parameter was\n' - ' not supplied)\n' - '\n' - ' stop\n' - '\n' - ' The value of the *stop* parameter\n' - '\n' - ' step\n' - '\n' - ' The value of the *step* parameter (or "1" if the parameter ' - 'was\n' - ' not supplied)\n' + ' because *cmp* is called multiple times for each list element ' + 'while\n' + ' *key* and *reverse* touch each element only once. Use\n' + ' "functools.cmp_to_key()" to convert an old-style *cmp* ' + 'function to\n' + ' a *key* function.\n' + '\n' + ' Changed in version 2.3: Support for "None" as an equivalent ' + 'to\n' + ' omitting *cmp* was added.\n' '\n' - 'The advantage of the "range" type over a regular "list" or ' - '"tuple" is\n' - 'that a "range" object will always take the same (small) amount ' - 'of\n' - 'memory, no matter the size of the range it represents (as it ' - 'only\n' - 'stores the "start", "stop" and "step" values, calculating ' - 'individual\n' - 'items and subranges as needed).\n' - '\n' - 'Range objects implement the "collections.abc.Sequence" ABC, and\n' - 'provide features such as containment tests, element index ' - 'lookup,\n' - 'slicing and support for negative indices (see Sequence Types — ' - 'list,\n' - 'tuple, range):\n' - '\n' - '>>> r = range(0, 20, 2)\n' - '>>> r\n' - 'range(0, 20, 2)\n' - '>>> 11 in r\n' - 'False\n' - '>>> 10 in r\n' - 'True\n' - '>>> r.index(10)\n' - '5\n' - '>>> r[5]\n' - '10\n' - '>>> r[:5]\n' - 'range(0, 10, 2)\n' - '>>> r[-1]\n' - '18\n' - '\n' - 'Testing range objects for equality with "==" and "!=" compares ' - 'them as\n' - 'sequences. That is, two range objects are considered equal if ' - 'they\n' - 'represent the same sequence of values. (Note that two range ' - 'objects\n' - 'that compare equal might have different "start", "stop" and ' - '"step"\n' - 'attributes, for example "range(0) == range(2, 1, 3)" or ' - '"range(0, 3,\n' - '2) == range(0, 4, 2)".)\n' - '\n' - 'Changed in version 3.2: Implement the Sequence ABC. Support ' - 'slicing\n' - 'and negative indices. Test "int" objects for membership in ' - 'constant\n' - 'time instead of iterating through all items.\n' - '\n' - 'Changed in version 3.3: Define ‘==’ and ‘!=’ to compare range ' - 'objects\n' - 'based on the sequence of values they define (instead of ' - 'comparing\n' - 'based on object identity).\n' - '\n' - 'New in version 3.3: The "start", "stop" and "step" attributes.\n' + ' Changed in version 2.4: Support for *key* and *reverse* was ' + 'added.\n' '\n' - 'See also:\n' - '\n' - ' * The linspace recipe shows how to implement a lazy version ' - 'of\n' - ' range suitable for floating point applications.\n', - 'typesseq-mutable': 'Mutable Sequence Types\n' + '9. Starting with Python 2.3, the "sort()" method is guaranteed ' + 'to\n' + ' be stable. A sort is stable if it guarantees not to change ' + 'the\n' + ' relative order of elements that compare equal --- this is ' + 'helpful\n' + ' for sorting in multiple passes (for example, sort by ' + 'department,\n' + ' then by salary grade).\n' + '\n' + '10. **CPython implementation detail:** While a list is being\n' + ' sorted, the effect of attempting to mutate, or even inspect, ' + 'the\n' + ' list is undefined. The C implementation of Python 2.3 and ' + 'newer\n' + ' makes the list appear empty for the duration, and raises\n' + ' "ValueError" if it can detect that the list has been ' + 'mutated\n' + ' during a sort.\n' + '\n' + '11. The value *n* is an integer, or an object implementing\n' + ' "__index__()". Zero and negative values of *n* clear the\n' + ' sequence. Items in the sequence are not copied; they are\n' + ' referenced multiple times, as explained for "s * n" under ' + 'Sequence\n' + ' Types --- str, unicode, list, tuple, bytearray, buffer, ' + 'xrange.\n', + 'typesseq-mutable': '\n' + 'Mutable Sequence Types\n' '**********************\n' '\n' - 'The operations in the following table are defined on ' - 'mutable sequence\n' - 'types. The "collections.abc.MutableSequence" ABC is ' - 'provided to make\n' - 'it easier to correctly implement these operations on ' - 'custom sequence\n' - 'types.\n' - '\n' - 'In the table *s* is an instance of a mutable sequence ' - 'type, *t* is any\n' - 'iterable object and *x* is an arbitrary object that ' - 'meets any type and\n' - 'value restrictions imposed by *s* (for example, ' - '"bytearray" only\n' - 'accepts integers that meet the value restriction "0 <= x ' - '<= 255").\n' + 'List and "bytearray" objects support additional ' + 'operations that allow\n' + 'in-place modification of the object. Other mutable ' + 'sequence types\n' + '(when added to the language) should also support these ' + 'operations.\n' + 'Strings and tuples are immutable sequence types: such ' + 'objects cannot\n' + 'be modified once created. The following operations are ' + 'defined on\n' + 'mutable sequence types (where *x* is an arbitrary ' + 'object):\n' '\n' '+--------------------------------+----------------------------------+-----------------------+\n' '| Operation | ' 'Result | Notes ' '|\n' - '|================================|==================================|=======================|\n' + '+================================+==================================+=======================+\n' '| "s[i] = x" | item *i* of *s* is ' 'replaced by | |\n' '| | ' @@ -13405,100 +13201,186 @@ topics = {'assert': 'The "assert" statement\n' '| | "s[i:j:k]" from the ' 'list | |\n' '+--------------------------------+----------------------------------+-----------------------+\n' - '| "s.append(x)" | appends *x* to the ' - 'end of the | |\n' - '| | sequence (same ' - 'as | |\n' - '| | "s[len(s):len(s)] = ' - '[x]") | |\n' - '+--------------------------------+----------------------------------+-----------------------+\n' - '| "s.clear()" | removes all items ' - 'from *s* (same | (5) |\n' - '| | as "del ' - 's[:]") | |\n' + '| "s.append(x)" | same as ' + '"s[len(s):len(s)] = [x]" | (2) |\n' '+--------------------------------+----------------------------------+-----------------------+\n' - '| "s.copy()" | creates a shallow ' - 'copy of *s* | (5) |\n' - '| | (same as ' - '"s[:]") | |\n' - '+--------------------------------+----------------------------------+-----------------------+\n' - '| "s.extend(t)" or "s += t" | extends *s* with the ' - 'contents of | |\n' - '| | *t* (for the most ' - 'part the same | |\n' - '| | as "s[len(s):len(s)] ' - '= t") | |\n' + '| "s.extend(t)" or "s += t" | for the most part the ' + 'same as | (3) |\n' + '| | "s[len(s):len(s)] = ' + 't" | |\n' '+--------------------------------+----------------------------------+-----------------------+\n' '| "s *= n" | updates *s* with its ' - 'contents | (6) |\n' + 'contents | (11) |\n' '| | repeated *n* ' 'times | |\n' '+--------------------------------+----------------------------------+-----------------------+\n' - '| "s.insert(i, x)" | inserts *x* into *s* ' - 'at the | |\n' - '| | index given by *i* ' - '(same as | |\n' - '| | "s[i:i] = ' - '[x]") | |\n' + '| "s.count(x)" | return number of ' + "*i*'s for which | |\n" + '| | "s[i] == ' + 'x" | |\n' + '+--------------------------------+----------------------------------+-----------------------+\n' + '| "s.index(x[, i[, j]])" | return smallest *k* ' + 'such that | (4) |\n' + '| | "s[k] == x" and "i <= ' + 'k < j" | |\n' + '+--------------------------------+----------------------------------+-----------------------+\n' + '| "s.insert(i, x)" | same as "s[i:i] = ' + '[x]" | (5) |\n' '+--------------------------------+----------------------------------+-----------------------+\n' - '| "s.pop([i])" | retrieves the item at ' - '*i* and | (2) |\n' - '| | also removes it from ' - '*s* | |\n' + '| "s.pop([i])" | same as "x = s[i]; ' + 'del s[i]; | (6) |\n' + '| | return ' + 'x" | |\n' '+--------------------------------+----------------------------------+-----------------------+\n' - '| "s.remove(x)" | remove the first item ' - 'from *s* | (3) |\n' - '| | where "s[i]" is equal ' - 'to *x* | |\n' + '| "s.remove(x)" | same as "del ' + 's[s.index(x)]" | (4) |\n' '+--------------------------------+----------------------------------+-----------------------+\n' '| "s.reverse()" | reverses the items of ' - '*s* in | (4) |\n' + '*s* in | (7) |\n' '| | ' 'place | ' '|\n' '+--------------------------------+----------------------------------+-----------------------+\n' + '| "s.sort([cmp[, key[, | sort the items of *s* ' + 'in place | (7)(8)(9)(10) |\n' + '| reverse]]])" ' + '| ' + '| |\n' + '+--------------------------------+----------------------------------+-----------------------+\n' '\n' 'Notes:\n' '\n' - '1. *t* must have the same length as the slice it is ' + '1. *t* must have the same length as the slice it is ' 'replacing.\n' '\n' - '2. The optional argument *i* defaults to "-1", so that ' - 'by default\n' - ' the last item is removed and returned.\n' + '2. The C implementation of Python has historically ' + 'accepted\n' + ' multiple parameters and implicitly joined them into a ' + 'tuple; this\n' + ' no longer works in Python 2.0. Use of this ' + 'misfeature has been\n' + ' deprecated since Python 1.4.\n' + '\n' + '3. *t* can be any iterable object.\n' + '\n' + '4. Raises "ValueError" when *x* is not found in *s*. ' + 'When a\n' + ' negative index is passed as the second or third ' + 'parameter to the\n' + ' "index()" method, the list length is added, as for ' + 'slice indices.\n' + ' If it is still negative, it is truncated to zero, as ' + 'for slice\n' + ' indices.\n' + '\n' + ' Changed in version 2.3: Previously, "index()" didn\'t ' + 'have arguments\n' + ' for specifying start and stop positions.\n' + '\n' + '5. When a negative index is passed as the first ' + 'parameter to the\n' + ' "insert()" method, the list length is added, as for ' + 'slice indices.\n' + ' If it is still negative, it is truncated to zero, as ' + 'for slice\n' + ' indices.\n' + '\n' + ' Changed in version 2.3: Previously, all negative ' + 'indices were\n' + ' truncated to zero.\n' + '\n' + '6. The "pop()" method\'s optional argument *i* defaults ' + 'to "-1", so\n' + ' that by default the last item is removed and ' + 'returned.\n' + '\n' + '7. The "sort()" and "reverse()" methods modify the list ' + 'in place\n' + ' for economy of space when sorting or reversing a ' + 'large list. To\n' + ' remind you that they operate by side effect, they ' + "don't return the\n" + ' sorted or reversed list.\n' '\n' - '3. "remove()" raises "ValueError" when *x* is not found ' - 'in *s*.\n' + '8. The "sort()" method takes optional arguments for ' + 'controlling the\n' + ' comparisons.\n' '\n' - '4. The "reverse()" method modifies the sequence in place ' - 'for\n' - ' economy of space when reversing a large sequence. To ' - 'remind users\n' - ' that it operates by side effect, it does not return ' - 'the reversed\n' - ' sequence.\n' + ' *cmp* specifies a custom comparison function of two ' + 'arguments (list\n' + ' items) which should return a negative, zero or ' + 'positive number\n' + ' depending on whether the first argument is considered ' + 'smaller than,\n' + ' equal to, or larger than the second argument: ' + '"cmp=lambda x,y:\n' + ' cmp(x.lower(), y.lower())". The default value is ' + '"None".\n' '\n' - '5. "clear()" and "copy()" are included for consistency ' - 'with the\n' - ' interfaces of mutable containers that don’t support ' - 'slicing\n' - ' operations (such as "dict" and "set"). "copy()" is ' - 'not part of the\n' - ' "collections.abc.MutableSequence" ABC, but most ' - 'concrete mutable\n' - ' sequence classes provide it.\n' + ' *key* specifies a function of one argument that is ' + 'used to extract\n' + ' a comparison key from each list element: ' + '"key=str.lower". The\n' + ' default value is "None".\n' '\n' - ' New in version 3.3: "clear()" and "copy()" methods.\n' + ' *reverse* is a boolean value. If set to "True", then ' + 'the list\n' + ' elements are sorted as if each comparison were ' + 'reversed.\n' '\n' - '6. The value *n* is an integer, or an object ' + ' In general, the *key* and *reverse* conversion ' + 'processes are much\n' + ' faster than specifying an equivalent *cmp* function. ' + 'This is\n' + ' because *cmp* is called multiple times for each list ' + 'element while\n' + ' *key* and *reverse* touch each element only once. ' + 'Use\n' + ' "functools.cmp_to_key()" to convert an old-style ' + '*cmp* function to\n' + ' a *key* function.\n' + '\n' + ' Changed in version 2.3: Support for "None" as an ' + 'equivalent to\n' + ' omitting *cmp* was added.\n' + '\n' + ' Changed in version 2.4: Support for *key* and ' + '*reverse* was added.\n' + '\n' + '9. Starting with Python 2.3, the "sort()" method is ' + 'guaranteed to\n' + ' be stable. A sort is stable if it guarantees not to ' + 'change the\n' + ' relative order of elements that compare equal --- ' + 'this is helpful\n' + ' for sorting in multiple passes (for example, sort by ' + 'department,\n' + ' then by salary grade).\n' + '\n' + '10. **CPython implementation detail:** While a list is ' + 'being\n' + ' sorted, the effect of attempting to mutate, or even ' + 'inspect, the\n' + ' list is undefined. The C implementation of Python ' + '2.3 and newer\n' + ' makes the list appear empty for the duration, and ' + 'raises\n' + ' "ValueError" if it can detect that the list has been ' + 'mutated\n' + ' during a sort.\n' + '\n' + '11. The value *n* is an integer, or an object ' 'implementing\n' - ' "__index__()". Zero and negative values of *n* clear ' - 'the sequence.\n' - ' Items in the sequence are not copied; they are ' - 'referenced multiple\n' - ' times, as explained for "s * n" under Common Sequence ' - 'Operations.\n', - 'unary': 'Unary arithmetic and bitwise operations\n' + ' "__index__()". Zero and negative values of *n* ' + 'clear the\n' + ' sequence. Items in the sequence are not copied; ' + 'they are\n' + ' referenced multiple times, as explained for "s * n" ' + 'under Sequence\n' + ' Types --- str, unicode, list, tuple, bytearray, ' + 'buffer, xrange.\n', + 'unary': '\n' + 'Unary arithmetic and bitwise operations\n' '***************************************\n' '\n' 'All unary arithmetic and bitwise operations have the same ' @@ -13514,13 +13396,14 @@ topics = {'assert': 'The "assert" statement\n' '\n' 'The unary "~" (invert) operator yields the bitwise inversion of ' 'its\n' - 'integer argument. The bitwise inversion of "x" is defined as\n' - '"-(x+1)". It only applies to integral numbers.\n' + 'plain or long integer argument. The bitwise inversion of "x" is\n' + 'defined as "-(x+1)". It only applies to integral numbers.\n' '\n' 'In all three cases, if the argument does not have the proper type, ' 'a\n' '"TypeError" exception is raised.\n', - 'while': 'The "while" statement\n' + 'while': '\n' + 'The "while" statement\n' '*********************\n' '\n' 'The "while" statement is used for repeated execution as long as an\n' @@ -13539,32 +13422,34 @@ topics = {'assert': 'The "assert" statement\n' '\n' 'A "break" statement executed in the first suite terminates the ' 'loop\n' - 'without executing the "else" clause’s suite. A "continue" ' + 'without executing the "else" clause\'s suite. A "continue" ' 'statement\n' 'executed in the first suite skips the rest of the suite and goes ' 'back\n' 'to testing the expression.\n', - 'with': 'The "with" statement\n' + 'with': '\n' + 'The "with" statement\n' '********************\n' '\n' + 'New in version 2.5.\n' + '\n' 'The "with" statement is used to wrap the execution of a block with\n' 'methods defined by a context manager (see section With Statement\n' - 'Context Managers). This allows common "try"…"except"…"finally" ' - 'usage\n' - 'patterns to be encapsulated for convenient reuse.\n' + 'Context Managers). This allows common "try"..."except"..."finally"\n' + 'usage patterns to be encapsulated for convenient reuse.\n' '\n' ' with_stmt ::= "with" with_item ("," with_item)* ":" suite\n' ' with_item ::= expression ["as" target]\n' '\n' - 'The execution of the "with" statement with one “item” proceeds as\n' + 'The execution of the "with" statement with one "item" proceeds as\n' 'follows:\n' '\n' '1. The context expression (the expression given in the "with_item")\n' ' is evaluated to obtain a context manager.\n' '\n' - '2. The context manager’s "__exit__()" is loaded for later use.\n' + '2. The context manager\'s "__exit__()" is loaded for later use.\n' '\n' - '3. The context manager’s "__enter__()" method is invoked.\n' + '3. The context manager\'s "__enter__()" method is invoked.\n' '\n' '4. If a target was included in the "with" statement, the return\n' ' value from "__enter__()" is assigned to it.\n' @@ -13578,7 +13463,7 @@ topics = {'assert': 'The "assert" statement\n' '\n' '5. The suite is executed.\n' '\n' - '6. The context manager’s "__exit__()" method is invoked. If an\n' + '6. The context manager\'s "__exit__()" method is invoked. If an\n' ' exception caused the suite to be exited, its type, value, and\n' ' traceback are passed as arguments to "__exit__()". Otherwise, ' 'three\n' @@ -13610,42 +13495,84 @@ topics = {'assert': 'The "assert" statement\n' ' with B() as b:\n' ' suite\n' '\n' - 'Changed in version 3.1: Support for multiple context expressions.\n' + 'Note: In Python 2.5, the "with" statement is only allowed when the\n' + ' "with_statement" feature has been enabled. It is always enabled ' + 'in\n' + ' Python 2.6.\n' + '\n' + 'Changed in version 2.7: Support for multiple context expressions.\n' '\n' 'See also:\n' '\n' - ' **PEP 343** - The “with” statement\n' + ' **PEP 343** - The "with" statement\n' ' The specification, background, and examples for the Python ' '"with"\n' ' statement.\n', - 'yield': 'The "yield" statement\n' + 'yield': '\n' + 'The "yield" statement\n' '*********************\n' '\n' ' yield_stmt ::= yield_expression\n' '\n' - 'A "yield" statement is semantically equivalent to a yield ' - 'expression.\n' - 'The yield statement can be used to omit the parentheses that would\n' - 'otherwise be required in the equivalent yield expression ' - 'statement.\n' - 'For example, the yield statements\n' - '\n' - ' yield <expr>\n' - ' yield from <expr>\n' + 'The "yield" statement is only used when defining a generator ' + 'function,\n' + 'and is only used in the body of the generator function. Using a\n' + '"yield" statement in a function definition is sufficient to cause ' + 'that\n' + 'definition to create a generator function instead of a normal\n' + 'function.\n' '\n' - 'are equivalent to the yield expression statements\n' + 'When a generator function is called, it returns an iterator known ' + 'as a\n' + 'generator iterator, or more commonly, a generator. The body of ' + 'the\n' + "generator function is executed by calling the generator's " + '"next()"\n' + 'method repeatedly until it raises an exception.\n' '\n' - ' (yield <expr>)\n' - ' (yield from <expr>)\n' + 'When a "yield" statement is executed, the state of the generator ' + 'is\n' + 'frozen and the value of "expression_list" is returned to ' + '"next()"\'s\n' + 'caller. By "frozen" we mean that all local state is retained,\n' + 'including the current bindings of local variables, the instruction\n' + 'pointer, and the internal evaluation stack: enough information is\n' + 'saved so that the next time "next()" is invoked, the function can\n' + 'proceed exactly as if the "yield" statement were just another ' + 'external\n' + 'call.\n' '\n' - 'Yield expressions and statements are only used when defining a\n' - '*generator* function, and are only used in the body of the ' - 'generator\n' - 'function. Using yield in a function definition is sufficient to ' - 'cause\n' - 'that definition to create a generator function instead of a normal\n' - 'function.\n' + 'As of Python version 2.5, the "yield" statement is now allowed in ' + 'the\n' + '"try" clause of a "try" ... "finally" construct. If the generator ' + 'is\n' + 'not resumed before it is finalized (by reaching a zero reference ' + 'count\n' + "or by being garbage collected), the generator-iterator's " + '"close()"\n' + 'method will be called, allowing any pending "finally" clauses to\n' + 'execute.\n' '\n' 'For full details of "yield" semantics, refer to the Yield ' 'expressions\n' - 'section.\n'} + 'section.\n' + '\n' + 'Note: In Python 2.2, the "yield" statement was only allowed when ' + 'the\n' + ' "generators" feature has been enabled. This "__future__" import\n' + ' statement was used to enable the feature:\n' + '\n' + ' from __future__ import generators\n' + '\n' + 'See also:\n' + '\n' + ' **PEP 255** - Simple Generators\n' + ' The proposal for adding generators and the "yield" statement ' + 'to\n' + ' Python.\n' + '\n' + ' **PEP 342** - Coroutines via Enhanced Generators\n' + ' The proposal that, among other generator enhancements, ' + 'proposed\n' + ' allowing "yield" to appear inside a "try" ... "finally" ' + 'block.\n'} |