Skip to content
Snippets Groups Projects
topics.py 669 KiB
Newer Older
  • Learn to ignore specific revisions
  •              '+----------------------------+----------------------------------+------------+\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'
                 '+----------------------------+----------------------------------+------------+\n'
                 '| "min(s)"                   | smallest item of *s*             '
                 '|            |\n'
                 '+----------------------------+----------------------------------+------------+\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'
                 '|                            | *i* and before index *j*)        '
                 '|            |\n'
                 '+----------------------------+----------------------------------+------------+\n'
                 '| "s.count(x)"               | total number of occurrences of   '
                 '|            |\n'
                 '|                            | *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'
                 'Notes:\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'
                 '\n'
                 '      >>> "gg" in "eggs"\n'
                 '      True\n'
                 '\n'
                 '2. Values of *n* less than "0" are treated as "0" (which yields '
                 'an\n'
                 '   empty sequence of the same type as *s*).  Note that items in '
                 'the\n'
                 '   sequence *s* are not copied; they are referenced multiple '
                 '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'
                 '\n'
                 '   What has happened is that "[[]]" is a one-element list '
                 'containing\n'
                 '   an empty list, so all three elements of "[[]] * 3" are '
                 'references\n'
                 '   to this single empty list.  Modifying any of the elements of\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'
                 '\n'
                 '   Further explanation is available in the FAQ entry How do I '
                 'create a\n'
                 '   multidimensional list?.\n'
                 '\n'
                 '3. If *i* or *j* is negative, the index is relative to the end '
                 'of\n'
    
                 '   sequence *s*: "len(s) + i" or "len(s) + j" is substituted.  '
                 'But\n'
                 '   note that "-0" is still "0".\n'
    
                 '\n'
                 '4. The slice of *s* from *i* to *j* is defined as the sequence '
                 'of\n'
                 '   items with index *k* such that "i <= k < j".  If *i* or *j* '
                 'is\n'
                 '   greater than "len(s)", use "len(s)".  If *i* is omitted or '
                 '"None",\n'
                 '   use "0".  If *j* is omitted or "None", use "len(s)".  If *i* '
                 'is\n'
                 '   greater than or equal to *j*, the slice is empty.\n'
                 '\n'
                 '5. The slice of *s* from *i* to *j* with step *k* is defined as '
                 'the\n'
                 '   sequence of items with index  "x = i + n*k" such that "0 <= n '
                 '<\n'
                 '   (j-i)/k".  In other words, the indices are "i", "i+k", '
                 '"i+2*k",\n'
                 '   "i+3*k" and so on, stopping when *j* is reached (but never\n'
    
                 '   including *j*).  When *k* is positive, *i* and *j* are '
                 'reduced to\n'
                 '   "len(s)" if they are greater. When *k* is negative, *i* and '
                 '*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 '
    
                 'depends on\n'
                 '   the sign of *k*).  Note, *k* cannot be zero. If *k* is '
                 '"None", it\n'
                 '   is treated like "1".\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 '6. Concatenating immutable sequences always results in a new '
                 'object.\n'
                 '   This means that building up a sequence by repeated '
                 'concatenation\n'
                 '   will have a quadratic runtime cost in the total sequence '
                 'length.\n'
                 '   To get a linear runtime cost, you must switch to one of the\n'
                 '   alternatives below:\n'
    
                 '\n'
                 '   * if concatenating "str" objects, you can build a list and '
                 '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'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 '7. Some sequence types (such as "range") only support item '
                 'sequences\n'
                 '   that follow specific patterns, and hence don’t support '
    
    Ned Deily's avatar
    Ned Deily committed
                 'sequence\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 '   concatenation or repetition.\n'
                 '\n'
                 '8. "index" raises "ValueError" when *x* is not found in *s*. Not '
                 'all\n'
                 '   implementations support passing the additional arguments *i* '
                 'and\n'
                 '   *j*. These arguments allow efficient searching of subsections '
                 'of\n'
                 '   the sequence. Passing the extra arguments is roughly '
                 'equivalent to\n'
                 '   using "s[i:j].index(x)", only without copying any data and '
                 'with the\n'
                 '   returned index being relative to the start of the sequence '
                 'rather\n'
                 '   than the start of the slice.\n'
    
                 '\n'
                 '\n'
                 'Immutable Sequence Types\n'
                 '========================\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'
                 '\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'
                 '\n'
                 'Attempting to hash an immutable sequence that contains '
                 'unhashable\n'
                 'values will result in "TypeError".\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'
                 '\n'
                 '+--------------------------------+----------------------------------+-----------------------+\n'
                 '| Operation                      | '
                 'Result                           | Notes                 |\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 '|================================|==================================|=======================|\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'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 '| "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 '
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 'default the\n'
                 '   last item is removed and returned.\n'
    
                 '3. "remove()" raises "ValueError" when *x* is not found in *s*.\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 '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'
                 '\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'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 '   * Using square brackets, separating items with commas: "[a]", '
                 '"[a,\n'
                 '     b, c]"\n'
    
                 '\n'
                 '   * Using a list comprehension: "[x for x in iterable]"\n'
                 '\n'
                 '   * Using the type constructor: "list()" or "list(iterable)"\n'
                 '\n'
                 '   The constructor builds a list 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 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'
                 '\n'
    
                 '   sort(*, key=None, reverse=False)\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 '
                 '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'
                 '\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'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 '  * 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'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                         '|================================|==================================|=======================|\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'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                         '| "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 '
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                         'by default the\n'
                         '   last item is removed and returned.\n'
    
                         '3. "remove()" raises "ValueError" when *x* is not found '
                         'in *s*.\n'
    
                         '\n'
                         '4. The "reverse()" method modifies the sequence in place '
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                         '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.\n'
              '\n'
              'The unary "+" (plus) operator yields its numeric argument '
              'unchanged.\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'
              '\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'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
              '   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_item ("," with_item)* ":" suite\n'
             '   with_item ::= expression ["as" target]\n'
             '\n'
    
             'The execution of the "with" statement with one “item” proceeds as\n'
    
             'follows:\n'
             '\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
             '1. The context expression (the expression given in the "with_item") '
             'is\n'
             '   evaluated to obtain a context manager.\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
             '2. The context manager’s "__enter__()" is loaded for later use.\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
             '3. The context manager’s "__exit__()" is loaded for later use.\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
             '4. The context manager’s "__enter__()" method is invoked.\n'
             '\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
             '5. If a target was included in the "with" statement, the return '
             'value\n'
             '   from "__enter__()" is assigned to it.\n'
             '\n'
             '   Note:\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
             '     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'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
             '6. The suite is executed.\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
             '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'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
             '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'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
             '       SUITE\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
             'is semantically equivalent to:\n'
    
             '\n'
             '   with A() as a:\n'
             '       with B() as b:\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
             '           SUITE\n'
    
             '\n'
             'Changed in version 3.1: Support for multiple context expressions.\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'}