Built-in functions on iterables

Python includes a number of built-in functions that work on iterables.

These functions generally work with any iterable, either a lazy iterable (as returned by a generator or a range function), or a data structure such as a list or tuple. There are a few exceptions, noted in the descriptions below.

Most of these functions are described below. The exceptions are:

• map and filter are described in the section on higher order functions.
• reversed and sorted don't work with every type of iterator. They are covered in the section on Changing the loop order.

Reducing iterables

These functions "reduce" the contents of an iterable to a single value.

all

Checks each value of an iterable, and returns True if all the elements evaluate to true, False otherwise:

k = [1, 5, 0, 3]
x = all(k)       #False

In this case, the result will be False because k[2] is zero, which evaluates to False. As soon as all encounters a False value, it stops evaluating the iterable - the result is already known, there is no need to continue.

any

Checks each value of an iterable, and returns True if any of the elements evaluate to true, False otherwise:

k = [1, 5, 0, 3]
x = any(k)       #True

In this case, the result will be True because k[1] is 1, which evaluates to True (any non-zero integer counts as True). As soon as any, encounters a True value, it stops evaluating the iterable.

max

Returns the maximum of all the values in the iterable:

k = [1, 5, 0, 3]
x = max(k)       #5

This will return the value 5, as it is the largest value in the list.

max doesn't just work with numbers. For example, if you had a list of strings, it would return the "greatest" string, using normal Python string comparison:

colors = ['red', 'green', 'blue']
x = max(colors)       #red

In a similar way, you can compare a sequence of lists or tuples.

You can also apply max to a single string. Python will treat the string as a sequence of characters, and find the greatest character (in Unicode terms):

s= 'xyzabc'
x = max(s)       #'z'

min

min behaves in exactly the same way as max, except that it finds the minimum value of the iterable.

sum

Returns the sum of all the values in the iterable:

k = [1, 5, 0, 3]
x = sum(k)

This will return the value 9 (1 + 5 + 0 + 3).

It is possible to use sum with other objects (for example, a list of lists rather than a list of numbers). However, it is usually best to use the itertools.chain function to join iterables, as it works equally well with sequences or lazy iterables. For joining strings, it is best to use the string.join function, as it is optimised for strings.

Converting iterables

These functions convert any iterable into a list, tuple or set.

list

The list function will convert any iterable to a list. It does this by creating a new list and adding the elements of the iterable.

Here are some examples:

k = [1, 2, 3, 4]
a = list(k)         #[1, 2, 3, 4]
t = (10, 20, 30)
b = list(t)         #[10, 20, 30]
c = list(range(4))  #[0, 1, 2, 3]

In the first case, k is a list. The list function makes a new list a that is a copy of k.

In the second case, t is a tuple. The list function creates a new list whose elements are the same as the tuple.

In the final case, range creates a lazy iterable. The list function evaluates the iterable and creates a list of the values.

tuple

The tuple function is similar to the list function, except that it creates a tuple from any iterable.

set

The set function is similar to the list function, except that it creates a set from any iterable. Since the same value cannot appear more than once in a set, this is a good we to remove duplicates from a sequence:

k = [5, 7, 5, 3, 3, 2]
s = set(k)         #{2, 3, 5, 7}

However, a set does not guarantee to preserve the original order of the list.

Transforming iterables

This set of functions transform one iterable into another. Most of these functions operate lazily - only obtaining the next result as it is needed. The exceptions are reversed and sorted, as described below.

enumerate

enumerate transforms an iterable by adding a count value, like this:

k = ['a', 'b', 'c']
e = enumerate(k)

e now contains the sequence:

(0, 'a'), (1, 'b'), (2, 'c')

That is, each new element is a tuple containing a count, and the original value. This is often used in a loop where you might need to loop index, for example:

k = ['a', 'b', 'c']
for i, s in enumerate(k):
    print(i, s)

Prints:

0 a
1 b
2 c

For more details on how to use this function in a loop, see Looping over multiple items.

You can also use enumerate with a second optional start parameter (and int), which specifies the initial count value (which is zero by default):

k = ['a', 'b', 'c']
e = enumerate(k, 2)

e now contains the sequence:

(2, 'a'), (3, 'b'), (4, 'c')

zip

zip transforms two or more iterables into a single iterator, like this:

p = ['a', 'b', 'c', 'd']
q = [1, 2, 3, 4]
r = ['W', 'X', 'Y', 'Z']
z = zip(p, q, r)

The iterable z now contains the following elements:

('a', 1, 'W'), ('b', 2, 'X'), ('c', 3, 'Y'), ('d', 4, 'Z')

This is a sequence of tuples. The first tuple contains the first element of each of the original iterables. The second tuple contains the second element of each of the original iterables, etc.

In this case, since there are 3 input iterables, p, q and r, each output tuple has 3 elements.

zip is often used to loop over several sequences together. See the example in looping over multiple items.

Primitives

Most of the time you will process iterables using for loops, generators, or using predefined Python functions like the ones above. For other cases, sometimes these primitive functions can be useful.

iter

iter accepts an iterable and returns a corresponding iterator. It is described in detail in iterators vs iterables.

next

next returns the next value from an iterator. It is also described in iterators vs iterables.

See also

• Introduction to Functional Programming
• Functions
• Pure functions
• Lambda functions
• Iterators
• Iterators vs iterables
• Transforming iterables
• Map/reduce example
• Generators
• Functional design patterns
• Recursion and the lru_cache in Python
• Partial application
• Closures
• Monads
• Failure monad
• List monad
• Maybe monad