A montanha-russa colossal da Chaitana

Uma list é uma coleção mutável de itens em sequência. Tal como a maioria das coleções (vê os tipos incorporados tuple, dict e set), as lists podem conter referências a qualquer tipo de dados (ou a vários) - incluindo outras lists. As lists podem ser copiadas no todo ou em parte através da notação de fatiamento ou com recurso a <list>.copy(). Tal como qualquer sequência, os elementos dentro das lists são referenciados por um número 0-based index a partir da esquerda, ou por um número -1-based index a partir da direita.

As lists suportam tanto operações de sequência comuns como mutáveis, tais como min(<list>)/max(<list>), <list>.index(), <list>.append() e <list>.reverse(). Os elementos dentro de uma list podem ser iterados com a construção for item in <list>. Podes usar for index, item in enumerate(<list>) quando precisares tanto do índice como do valor do elemento.

O Python também disponibiliza muitos métodos de list úteis para trabalhar com lists. Abaixo apresentamos uma seleção desses list methods.

Tem em atenção que, quando manipulas uma list com um list-method, alteras o objeto list que foi passado. Se não quiseres alterar a list original, tens de fazer pelo menos uma shallow copy dela, através de fatiamento ou de <list>.copy().

Adicionar itens

Para adicionar um item ao fim, ou ao "lado direito", de uma list existente, usa <list>.append(<item>):

>>> numbers = [1, 2, 3]
>>> numbers.append(9)

>>> numbers
[1, 2, 3, 9]

Em vez de fazer append, <list>.insert() dá-te a possibilidade de adicionar o item a um índice específico da list. Aceita 2 parâmetros:

1. o <index> onde queres que o item seja inserido.
2. o <item> a inserir.

Nota: se o index indicado for 0, o item é adicionado ao início ("lado esquerdo") da list. Se o index indicado for maior do que o último index da list, o item é adicionado na posição final, o equivalente a usar <list>.append(<item>).

>>> numbers = [1, 2, 3]
>>> numbers.insert(0, -2)

>>> numbers
[-2, 1, 2, 3]

>>> numbers.insert(1, 0)

>>> numbers
[-2, 0, 1, 2, 3]

Podes usar <list>.extend(<item>) para combinar uma list existente com os elementos de outro iterável (por exemplo, um set, tuple, str ou list). O iterável é desempacotado e os elementos são acrescentados por ordem (usar <list>.append(<item>) nesta situação adicionaria o iterável inteiro como um único item.).

>>> numbers = [1, 2, 3]
>>> other_numbers = [5, 6, 7]

>>> numbers.extend(other_numbers)

>>> numbers
[1, 2, 3, 5, 6, 7]

>>> numbers.extend([8, 9])

>>> numbers
[1, 2, 3, 5, 6, 7, 8, 9]

>>> numbers.append([8,9])

>>> numbers
[1, 2, 3, 5, 6, 7, 8, 9, [8, 9]]

Remover itens

Para eliminar um item de uma list, usa <list>.remove(<item>), passando como argumento o item a remover. <list>.remove(<item>) lança um ValueError se o item não estiver presente na list.

>>> numbers = [1, 2, 3]
>>> numbers.remove(2)

>>> numbers
[1, 3]

# Trying to remove a value that is not in the list throws a ValueError
>>> numbers.remove(0)
ValueError: list.remove(x): x not in list

Em alternativa, usar o método <list>.pop(<index>) remove e faz return de um elemento, para o poderes usar.

<list>.pop(<index>) aceita um parâmetro opcional: o index do item a remover e a devolver. Se o argumento index (opcional) não for indicado, o elemento final da list é removido e devolvido. Se o index indicado for superior ao index do último item, é lançado um IndexError.

>>> numbers = [1, 2, 3]

>>> numbers.pop(0)
1

>>> numbers
[2, 3]

>>> numbers.pop()
3

>>> numbers
[2]

>>> numbers.pop(1)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
IndexError: pop index out of range

Todos os elementos podem ser removidos de uma list com list.clear(). Não aceita parâmetros.

>>> numbers = [1, 2, 3]
>>> numbers.clear()

>>> numbers
[]

Inverter e reordenar

O método <list>.reverse() inverte a ordem dos elementos no próprio local.

>>> numbers = [1, 2, 3]
>>> numbers.reverse()

>>> numbers
[3, 2, 1]

Uma list pode ser reordenada no próprio local com a ajuda de <list>.sort(). A ordem de ordenação predefinida é crescente a partir da esquerda. A documentação do Python apresenta dicas e técnicas adicionais de ordenação.

>>> names = ["Tony", "Natasha", "Thor", "Bruce"]

# The default sort order is *ascending*.
>>> names.sort()

>>> names
["Bruce", "Natasha", "Thor", "Tony"]

Se quiseres uma ordem decrescente, passa o argumento reverse=True:

>>> names = ["Tony", "Natasha", "Thor", "Bruce"]
>>> names.sort(reverse=True)

>>> names
["Tony", "Thor", "Natasha", "Bruce"]

Nos casos em que não queres alterar a list original, podes usar a função incorporada sorted(<iterable>) para devolver uma cópia ordenada.

>>> names = ["Tony", "Natasha", "Thor", "Bruce"]

>>> sorted(names)
['Bruce', 'Natasha', 'Thor', 'Tony']

Ocorrências de um item numa list

O número de ocorrências de um elemento numa list pode ser calculado com a ajuda de list.count(<item>). Aceita como argumento o item a contar e devolve o número total de vezes que esse elemento aparece na list.

>>> items = [1, 4, 7, 8, 2, 9, 2, 1, 1, 0, 4, 3]

>>> items.count(1)
3

Encontrar o índice de itens

<list>.index(<item>) devolve o número index da primeira ocorrência de um item passado. Se não houver ocorrências, é lançado um ValueError. Se não precisares da posição exata de um item, o operador in incorporado é mais eficiente para verificar se uma list contém um determinado valor.

A indexação tem base zero a partir da esquerda, por isso a posição do item "primeiro" é 0. A indexação também funciona a partir da direita, começando em -1.

>>> items = [7, 4, 1, 0, 2, 5]

>>> items.index(4)
1

>>> items.index(10)
ValueError: 10 is not in list

Também podes indicar os índices start e end para restringir a pesquisa a uma secção específica da list:

>>> names = ["Tina", "Leo", "Thomas", "Tina", "Emily", "Justin"]

>>> names.index("Tina")
0

>>> names.index("Tina", 2, 5)
3