Desempacotamento de Tuplas em Python: Guia Completo

Desempacotamento de tuplas (também chamado de desempacotamento de iteráveis) permite atribuir os elementos de uma tupla — ou qualquer iterável — a variáveis individuais em uma única instrução. Esta página abrange tudo, desde a sintaxe básica até padrões avançados como expressões com asterisco, desempacotamento aninhado e desempacotamento em loops.

O Que é Desempacotamento de Tuplas?

Quando você desempacota uma tupla, o Python mapeia cada elemento para uma variável correspondente no lado esquerdo do =. O número de variáveis deve corresponder exatamente ao número de elementos (a menos que você use uma expressão com asterisco, abordada abaixo).

Os parênteses ao redor da tupla são opcionais — 1, 2, 3 também é uma tupla. As duas linhas a seguir são equivalentes:

a, b, c = (1, 2, 3)
a, b, c = 1, 2, 3   # same result

Por Que Usar Desempacotamento de Tuplas?

Atribuição concisa de variáveis

Sem desempacotamento, você precisa de uma linha por elemento:

Troca de variáveis

O desempacotamento torna a troca de dois valores uma operação de uma linha. O Python avalia completamente o lado direito antes de atribuir, portanto nenhuma variável temporária é necessária:

Leitura de valores retornados por funções

Funções que retornam múltiplos valores, na verdade, retornam uma tupla. O desempacotamento atribui um nome significativo a cada valor imediatamente:

def min_max(numbers):
    return min(numbers), max(numbers)

lo, hi = min_max([3, 1, 4, 1, 5, 9, 2, 6])

print(lo)  # 1
print(hi)  # 9

Sem desempacotamento, você escreveria result[0] e result[1], o que é menos legível.

Desempacotamento Estendido com o Operador Asterisco

Quando você não sabe (ou não se preocupa com) o número de elementos intermediários, prefixe uma variável com * para capturar tudo o que não corresponde a um slot nomeado. A variável com asterisco sempre recebe uma lista, mesmo que capture zero elementos.

Capturar o final

first, *rest = (1, 2, 3, 4, 5)

print(first)  # 1
print(rest)   # [2, 3, 4, 5]

Capturar o início

*start, last = (1, 2, 3, 4, 5)

print(start)  # [1, 2, 3, 4]
print(last)   # 5

Capturar uma seção intermediária

first, *middle, last = (10, 20, 30, 40, 50)

print(first)   # 10
print(middle)  # [20, 30, 40]
print(last)    # 50

Apenas uma variável com asterisco é permitida por instrução de desempacotamento. Usar duas ou mais gera um SyntaxError.

Ignorando Elementos com _

A convenção Python usa _ como nome de variável descartável. É um identificador válido — o Python simplesmente atribui a ele — mas, por convenção, sinaliza "não preciso deste valor."

x, _, z = (10, 99, 30)

print(x)  # 10
print(z)  # 30
# _ holds 99 but we do not use it

Combine _ com uma expressão com asterisco para descartar muitos elementos:

first, *_ = (10, 20, 30, 40)

print(first)  # 10
# *_ swallows 20, 30, 40

Desempacotamento Aninhado de Tuplas

Se uma tupla contém outra tupla, você pode desempacotar ambos os níveis em uma única instrução, espelhando o aninhamento com parênteses:

Isso funciona em qualquer profundidade, mas aninhamentos profundos prejudicam a legibilidade — considere desempacotar em etapas.

Desempacotamento em Loops for

Você pode desempacotar cada elemento de um iterável diretamente na instrução for. Isso é particularmente útil com listas de tuplas:

pairs = [(1, 'one'), (2, 'two'), (3, 'three')]

for num, word in pairs:
    print(num, word)

# 1 one
# 2 two
# 3 three

Desempacotamento com enumerate()

enumerate() retorna pares (índice, valor), que você pode desempacotar diretamente:

fruits = ('apple', 'banana', 'cherry')

for i, fruit in enumerate(fruits):
    print(i, fruit)

# 0 apple
# 1 banana
# 2 cherry

Isso evita o rastreamento manual de índices e é o padrão idiomático do Python para iterar sobre uma sequência quando você precisa tanto da posição quanto do valor.

Desempacotamento com zip()

zip() combina elementos de dois iteráveis em pares, e você pode desempacotar cada par no loop:

names = ('Alice', 'Bob', 'Carol')
scores = (92, 87, 95)

for name, score in zip(names, scores):
    print(name, score)

# Alice 92
# Bob 87
# Carol 95

Erros Comuns

Valores em excesso ou insuficientes

O Python lança ValueError se o número de variáveis não corresponder ao número de elementos (e nenhuma expressão com asterisco estiver presente):

a, b = (1, 2, 3)
# ValueError: too many values to unpack (expected 2)

a, b, c = (1, 2)
# ValueError: not enough values to unpack (expected 3, got 2)

Corrija a incompatibilidade ou use uma expressão com asterisco para absorver elementos extras.

Duas variáveis com asterisco

first, *middle, *last = (1, 2, 3, 4)
# SyntaxError: multiple starred expressions in assignment

Apenas uma variável com * é permitida por instrução de desempacotamento.

Referência Rápida

Capítulos Relacionados

• Python Tuples — criação, indexação e fatiamento de tuplas
• Access Tuples — leitura de elementos individuais por índice
• Loop Tuples — iteração sobre elementos de tuplas
• Join Tuples — combinação de múltiplas tuplas
• Tuple Methods — count() e index()
• Update Tuples — como contornar a imutabilidade

Prática