A montanha-russa colossal da Chaitana

Uma list é uma coleção mutável de itens em sequência. Como a maioria das coleções (veja os tipos tuple, dict e set embutidos), as listas podem conter referências a qualquer tipo de dado, ou a vários deles, inclusive outras listas. As listas podem ser copiadas por inteiro ou em parte com a notação de fatia ou com <list>.copy(). Como qualquer sequência, os elementos dentro de 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 listas aceitam tanto operações de sequência comuns quanto operações de sequência mutáveis, como min(<list>)/max(<list>), <list>.index(), <list>.append() e <list>.reverse(). Os elementos dentro de uma list podem ser percorridos com a construção for item in <list>. Já for index, item in enumerate(<list>) pode ser usado quando você precisa tanto do índice quanto do valor do elemento.

O Python também oferece vários métodos de lista úteis para trabalhar com listas. Alguns desses list methods são apresentados abaixo.

Note que, quando você manipula uma list com um list-method, você altera o objeto de lista que foi passado. Se você não quiser modificar a list original, vai precisar pelo menos fazer uma shallow copy dela com uma fatia ou com <list>.copy().

Adicionando itens

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

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

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

Em vez de apenas acrescentar, <list>.insert() permite adicionar o item a um índice específico da lista. Ele aceita 2 parâmetros:

1. o <index> no qual você quer que o item seja inserido.
2. o <item> a ser inserido.

Nota: Se o index informado for 0, o item será adicionado ao início ("lado esquerdo") da list. Se o index informado for maior que o último index da list, o item será 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]

<list>.extend(<item>) pode ser usado para combinar uma lista 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 em ordem (usar <list>.append(<item>) nessa 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]]

Removendo itens

Para excluir um item de uma lista, use <list>.remove(<item>), passando como argumento o item a ser removido. <list>.remove(<item>) lançará 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

Como alternativa, usar o método <list>.pop(<index>) remove e return um elemento, deixando-o disponível para uso.

<list>.pop(<index>) aceita um parâmetro opcional: o index do item a ser removido e retornado. Se o argumento index (opcional) não for especificado, o último elemento da list será removido e retornado. Se o index especificado for maior que o index do último item, um IndexError é levantado.

>>> 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(). Ele não aceita nenhum parâmetro.

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

>>> numbers
[]

Invertendo e reordenando

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 lista pode ser reordenada no próprio local com a ajuda de <list>.sort(). A ordem padrão de ordenação é crescente, a partir da esquerda. A documentação do Python traz 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 você quiser uma ordem decrescente, passe o argumento reverse=True:

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

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

Nos casos em que modificar a lista original não é desejável, a função embutida sorted(<iterable>) pode ser usada para retornar uma cópia ordenada.

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

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

Ocorrências de um item em uma lista

O número de ocorrências de um elemento em uma lista pode ser calculado com a ajuda de list.count(<item>). Ele recebe como argumento o item a ser contado e retorna 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

Encontrando o índice dos itens

<list>.index(<item>) retorna o número do index da primeira ocorrência de um item passado. Se não houver nenhuma ocorrência, um ValueError é lançado. Se a posição exata de um item não for necessária, o operador in embutido é mais eficiente para verificar se uma lista contém um determinado valor.

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

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

>>> items.index(4)
1

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

Os índices start e end também podem ser informados para restringir a busca a uma seção específica da list:

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

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

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