Python Sequence Types

The basic sequence types are lists, tuples, and range objects.

Python Lists

Lists are mutable sequences. Lists are usually used to store collections of homogeneous elements of the same kind. class list([iterable])

Python List Constructor

Lists may be constructed by:

using a pair of square brackets to denote an empty list, []
using a pair of square brackets to enclose comma-delimited elements. e.g. ~~[𝑎]~~,~~[𝑎,𝑏,𝑐]~~
using a list comprehension. e.g. ~~[𝑥 for 𝑥 in iterable]~~
using the type constructor. e.g. ~~list()~~ or ~~list(iterable)~~

The constructor builds a list whose items are the same and in the same order as iterable’s items. iterable may be either a sequence, a container that supports iteration, or an iterator object. If iterable is already a list, a copy is made and returned, similar to iterable[:]. For example, list('abc') returns ['a', 'b', 'c'] and list( (1, 2, 3) ) returns [1, 2, 3]. If no argument is given, the constructor creates a new empty list, [].

Many other operations also produce lists, including the sorted() built-in.

Python List Operations

Python support all common and mutable sequence operations. Additional list operations are:

sort(*, key=None, reverse=False)

    This method sorts the list in place, using only < comparisons between items. Exceptions are not suppressed - if any comparison operations fail, the entire sort operation will fail (and the list will likely be left in a partially modified state).

    sort() accepts two arguments that can only be passed by keyword (keyword-only arguments):

    key specifies a function of one argument that is used to extract a comparison key from each list element (for example, key=str.lower). The key corresponding to each item in the list is calculated once and then used for the entire sorting process. The default value of None means that list items are sorted directly without calculating a separate key value.

    The functools.cmp_to_key() utility is available to convert a 2.x style cmp function to a key function.

    reverse is a boolean value. If set to True, then the list elements are sorted as if each comparison were reversed.

    This method modifies the sequence in place for economy of space when sorting a large sequence. To remind users that it operates by side effect, it does not return the sorted sequence (use sorted() to explicitly request a new sorted list instance).

    The sort() method is guaranteed to be stable. A sort is stable if it guarantees not to change the relative order of elements that compare equal — this is helpful for sorting in multiple passes (for example, sort by department, then by salary grade).

    For sorting examples and a brief sorting tutorial, see Sorting HOW TO.

    CPython implementation detail: While a list is being sorted, the effect of attempting to mutate, or even inspect, the list is undefined. The C implementation of Python makes the list appear empty for the duration, and raises ValueError if it can detect that the list has been mutated during a sort.

Python Tuples

Tuples are immutable sequences. Tuples are usually used to store collections of heterogeneous elements of not necessary the same kind. class tuple([iterable])

Python Tuple Constructor

Tuples may be constructed by:

using a pair of parentheses to denote an empty tuple, ()
using a trailing comma for a singleton tuple. e.g. 𝑎, or ~~(𝑎,)~~
using a sequence of comma-delimited elements with a pair of optional parentheses to eliminate ambiguous. e.g. ~~𝑎,𝑏,𝑐~~,~~(𝑎,𝑏,𝑐)~~
using the type constructor. e.g. ~~tuple()~~ or ~~tuple(iterable)~~

The constructor builds a tuple whose items are the same and in the same order as iterable’s items. iterable may be either a sequence, a container that supports iteration, or an iterator object. If iterable is already a tuple, it is returned unchanged. For example, tuple('abc') returns ('a', 'b', 'c') and tuple( [1, 2, 3] ) returns (1, 2, 3). If no argument is given, the constructor creates a new empty tuple, ().

Note that it is actually the comma which makes a tuple, not the parentheses. The parentheses are optional, except in the empty tuple case, or when they are needed to avoid syntactic ambiguity. For example, f(a, b, c) is a function call with three arguments, while f((a, b, c)) is a function call with a 3-tuple as the sole argument.

Python Tuple Operations

Python support all common sequence operations.

For heterogeneous collections of data where access by name is clearer than access by index, collections.namedtuple() may be a more appropriate choice than a simple tuple object.

Python Range Objects

Range objects are immutable sequences of numbers. Range Objects are usually used for looping a specific number of times in ~~for~~ loops.

class range(stop)

    class range(start, stop[, step])

    The arguments to the range constructor must be integers (either built-in int or any object that implements the __index__ special method). If the step argument is omitted, it defaults to 1. If the start argument is omitted, it defaults to 0. If step is zero, ValueError is raised.

    For a positive step, the contents of a range r are determined by the formula r[i] = start + step*i where i >= 0 and r[i] < stop.

    For a negative step, the contents of the range are still determined by the formula r[i] = start + step*i, but the constraints are i >= 0 and r[i] > stop.

    A range object will be empty if r[0] does not meet the value constraint. Ranges do support negative indices, but these are interpreted as indexing from the end of the sequence determined by the positive indices.

    Ranges containing absolute values larger than sys.maxsize are permitted but some features (such as len()) may raise OverflowError.

    Range examples:
    >>>

    >>> list(range(10))
    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
    >>> list(range(1, 11))
    [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
    >>> list(range(0, 30, 5))
    [0, 5, 10, 15, 20, 25]
    >>> list(range(0, 10, 3))
    [0, 3, 6, 9]
    >>> list(range(0, -10, -1))
    [0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
    >>> list(range(0))
    []
    >>> list(range(1, 0))
    []

    Ranges implement all of the common sequence operations except concatenation and repetition (due to the fact that range objects can only represent sequences that follow a strict pattern and repetition and concatenation will usually violate that pattern).

    start

        The value of the start parameter (or 0 if the parameter was not supplied)

    stop

        The value of the stop parameter

    step

        The value of the step parameter (or 1 if the parameter was not supplied)

The advantage of the range type over a regular list or tuple is that a range object will always take the same (small) amount of memory, no matter the size of the range it represents (as it only stores the start, stop and step values, calculating individual items and subranges as needed).

Range objects implement the collections.abc.Sequence ABC, and provide features such as containment tests, element index lookup, slicing and support for negative indices (see Sequence Types — list, tuple, range):
>>>

>>> r = range(0, 20, 2)
>>> r
range(0, 20, 2)
>>> 11 in r
False
>>> 10 in r
True
>>> r.index(10)
5
>>> r[5]
10
>>> r[:5]
range(0, 10, 2)
>>> r[-1]
18

Testing range objects for equality with == and != compares them as sequences. That is, two range objects are considered equal if they represent the same sequence of values. (Note that two range objects that compare equal might have different start, stop and step attributes, for example range(0) == range(2, 1, 3) or range(0, 3, 2) == range(0, 4, 2).)

Changed in version 3.2: Implement the Sequence ABC. Support slicing and negative indices. Test int objects for membership in constant time instead of iterating through all items.

Changed in version 3.3: Define ‘==’ and ‘!=’ to compare range objects based on the sequence of values they define (instead of comparing based on object identity).

New in version 3.3: The start, stop and step attributes.

See also

    The linspace recipe shows how to implement a lazy version of range suitable for floating point applications.

Content