topics.py

             '"()"\n'
             '\n'
             '   * Using a trailing comma for a singleton tuple: "a," or '
             '"(a,)"\n'
             '\n'
             '   * Separating items with commas: "a, b, c" or "(a, b, c)"\n'
             '\n'
             '   * Using the "tuple()" built-in: "tuple()" or '
             '"tuple(iterable)"\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'
             '\n'
             '   Note that it is actually the comma which makes a tuple, not '
             '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'
             '\n'
             '\n'
             'Ranges\n'
             '======\n'
             '\n'
             'The "range" type represents an immutable sequence of numbers and '
             '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'
             '\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'
             '\n'
             'See also:\n'
             '\n'
             '  * The linspace recipe shows how to implement a lazy version of '
             'range\n'
             '    suitable for floating point applications.\n',
 'typesseq-mutable': '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'
                     '\n'
                     '+--------------------------------+----------------------------------+-----------------------+\n'
                     '| Operation                      | '
                     'Result                           | Notes                 '
                     '|\n'
                     '|================================|==================================|=======================|\n'
                     '| "s[i] = x"                     | item *i* of *s* is '
                     'replaced by   |                       |\n'
                     '|                                | '
                     '*x*                              |                       '
                     '|\n'
                     '+--------------------------------+----------------------------------+-----------------------+\n'
                     '| "s[i:j] = t"                   | slice of *s* from *i* '
                     'to *j* is  |                       |\n'
                     '|                                | replaced by the '
                     'contents of the  |                       |\n'
                     '|                                | iterable '
                     '*t*                     |                       |\n'
                     '+--------------------------------+----------------------------------+-----------------------+\n'
                     '| "del s[i:j]"                   | same as "s[i:j] = '
                     '[]"            |                       |\n'
                     '+--------------------------------+----------------------------------+-----------------------+\n'
                     '| "s[i:j:k] = t"                 | the elements of '
                     '"s[i:j:k]" are   | (1)                   |\n'
                     '|                                | replaced by those of '
                     '*t*         |                       |\n'
                     '+--------------------------------+----------------------------------+-----------------------+\n'
                     '| "del s[i:j:k]"                 | removes the elements '
                     'of          |                       |\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'
                     '+--------------------------------+----------------------------------+-----------------------+\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'
                     '+--------------------------------+----------------------------------+-----------------------+\n'
                     '| "s *= n"                       | updates *s* with its '
                     'contents    | (6)                   |\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'
                     '+--------------------------------+----------------------------------+-----------------------+\n'
                     '| "s.pop()" or "s.pop(i)"        | retrieves the item at '
                     '*i* and    | (2)                   |\n'
                     '|                                | also removes it from '
                     '*s*         |                       |\n'
                     '+--------------------------------+----------------------------------+-----------------------+\n'
                     '| "s.remove(x)"                  | remove the first item '
                     'from *s*   | (3)                   |\n'
                     '|                                | where "s[i]" is equal '
                     'to *x*     |                       |\n'
                     '+--------------------------------+----------------------------------+-----------------------+\n'
                     '| "s.reverse()"                  | reverses the items of '
                     '*s* in     | (4)                   |\n'
                     '|                                | '
                     'place                            |                       '
                     '|\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 the\n'
                     '   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 economy\n'
                     '   of space when reversing a large sequence.  To remind '
                     'users that it\n'
                     '   operates by side effect, it does not return the '
                     'reversed 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',
 'unary': 'Unary arithmetic and bitwise operations\n'
          '***************************************\n'
          '\n'
          'All unary arithmetic and bitwise operations have the same '
          'priority:\n'
          '\n'
          '   u_expr ::= power | "-" u_expr | "+" u_expr | "~" u_expr\n'
          '\n'
          'The unary "-" (minus) operator yields the negation of its numeric\n'
          'argument; the operation can be overridden with the "__neg__()" '
          'special\n'
          'method.\n'
          '\n'
          'The unary "+" (plus) operator yields its numeric argument '
          'unchanged;\n'
          'the operation can be overridden with the "__pos__()" special '
          'method.\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 or to custom '
          'objects\n'
          'that override the "__invert__()" special method.\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'
          '*********************\n'
          '\n'
          'The "while" statement is used for repeated execution as long as an\n'
          'expression is true:\n'
          '\n'
          '   while_stmt ::= "while" assignment_expression ":" suite\n'
          '                  ["else" ":" suite]\n'
          '\n'
          'This repeatedly tests the expression and, if it is true, executes '
          'the\n'
          'first suite; if the expression is false (which may be the first '
          'time\n'
          'it is tested) the suite of the "else" clause, if present, is '
          'executed\n'
          'and the loop 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'
          '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'
         '********************\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'
         '\n'
         '   with_stmt          ::= "with" ( "(" with_stmt_contents ","? ")" | '
         'with_stmt_contents ) ":" suite\n'
         '   with_stmt_contents ::= with_item ("," with_item)*\n'
         '   with_item          ::= expression ["as" target]\n'
         '\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") '
         'is\n'
         '   evaluated to obtain a context manager.\n'
         '\n'
         '2. The context manager’s "__enter__()" is loaded for later use.\n'
         '\n'
         '3. The context manager’s "__exit__()" is loaded for later use.\n'
         '\n'
         '4. The context manager’s "__enter__()" method is invoked.\n'
         '\n'
         '5. If a target was included in the "with" statement, the return '
         'value\n'
         '   from "__enter__()" is assigned to it.\n'
         '\n'
         '   Note:\n'
         '\n'
         '     The "with" statement guarantees that if the "__enter__()" '
         'method\n'
         '     returns without an error, then "__exit__()" will always be\n'
         '     called. Thus, if an error occurs during the assignment to the\n'
         '     target list, it will be treated the same as an error occurring\n'
         '     within the suite would be. See step 6 below.\n'
         '\n'
         '6. The suite is executed.\n'
         '\n'
         '7. 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'
         '   "None" arguments are supplied.\n'
         '\n'
         '   If the suite was exited due to an exception, and the return '
         'value\n'
         '   from the "__exit__()" method was false, the exception is '
         'reraised.\n'
         '   If the return value was true, the exception is suppressed, and\n'
         '   execution continues with the statement following the "with"\n'
         '   statement.\n'
         '\n'
         '   If the suite was exited for any reason other than an exception, '
         'the\n'
         '   return value from "__exit__()" is ignored, and execution '
         'proceeds\n'
         '   at the normal location for the kind of exit that was taken.\n'
         '\n'
         'The following code:\n'
         '\n'
         '   with EXPRESSION as TARGET:\n'
         '       SUITE\n'
         '\n'
         'is semantically equivalent to:\n'
         '\n'
         '   manager = (EXPRESSION)\n'
         '   enter = type(manager).__enter__\n'
         '   exit = type(manager).__exit__\n'
         '   value = enter(manager)\n'
         '   hit_except = False\n'
         '\n'
         '   try:\n'
         '       TARGET = value\n'
         '       SUITE\n'
         '   except:\n'
         '       hit_except = True\n'
         '       if not exit(manager, *sys.exc_info()):\n'
         '           raise\n'
         '   finally:\n'
         '       if not hit_except:\n'
         '           exit(manager, None, None, None)\n'
         '\n'
         'With more than one item, the context managers are processed as if\n'
         'multiple "with" statements were nested:\n'
         '\n'
         '   with A() as a, B() as b:\n'
         '       SUITE\n'
         '\n'
         'is semantically equivalent to:\n'
         '\n'
         '   with A() as a:\n'
         '       with B() as b:\n'
         '           SUITE\n'
         '\n'
         'You can also write multi-item context managers in multiple lines if\n'
         'the items are surrounded by parentheses. For example:\n'
         '\n'
         '   with (\n'
         '       A() as a,\n'
         '       B() as b,\n'
         '   ):\n'
         '       SUITE\n'
         '\n'
         'Changed in version 3.1: Support for multiple context expressions.\n'
         '\n'
         'Changed in version 3.10: Support for using grouping parentheses to\n'
         'break the statement in multiple lines.\n'
         '\n'
         'See also:\n'
         '\n'
         '  **PEP 343** - The “with” statement\n'
         '     The specification, background, and examples for the Python '
         '"with"\n'
         '     statement.\n',
 'yield': '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'
          '\n'
          'are equivalent to the yield expression statements\n'
          '\n'
          '   (yield <expr>)\n'
          '   (yield from <expr>)\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'
          '\n'
          'For full details of "yield" semantics, refer to the Yield '
          'expressions\n'
          'section.\n'}