Escopo local e global

Variável local e variável global

Toda variável nasce em um lugar, e esse lugar define onde ela pode ser usada. Uma variável criada dentro de uma função vive apenas durante a execução daquela função: quando a função termina, a variável some. Ela é local. Já uma variável definida no nível do arquivo, fora de qualquer função, é global e pode ser lida de qualquer ponto do módulo. Essa separação é ótima: cada função tem o seu espaço próprio, e o que acontece dentro dela não bagunça o resto do programa.

taxa = 0.1  # global, definida no nivel do arquivo

def aplicar(valor):
    desconto = valor * taxa  # le a global taxa; desconto e local
    return valor - desconto

print(aplicar(100))  # 90.0
print(desconto)      # NameError: name 'desconto' is not defined
# desconto so existia dentro de aplicar; aqui fora, nao existe.

aplicar lê a global taxa, mas desconto é local e não existe fora da função.

No exemplo, taxa é global e a função consegue lê-la sem cerimônia. Já desconto nasceu dentro de aplicar, então é local: tentar usá-la fora dá NameError, porque ela deixou de existir quando a função retornou. Esse comportamento é uma proteção, não um obstáculo. Ele garante que uma variável temporária de uma função não colida com outra de mesmo nome em outra função. Sem escopo, programas grandes virariam um campo minado de nomes se atropelando.

Atribuir dentro da função cria uma local

Aqui mora uma confusão comum. Ler uma global dentro da função funciona direto. Mas, no momento em que você atribui a um nome dentro da função, o Python passa a considerar esse nome local, mesmo que exista uma global com o mesmo nome. Isso pode gerar um erro que assusta quem não conhece a regra: a função parece usar a global antes de defini-la, e o Python reclama.

contador = 0

# Errado: atribuir torna contador local, e ai a leitura falha
def incrementar():
    contador = contador + 1  # local no lado esquerdo, mas usado antes
    return contador

incrementar()
# UnboundLocalError: cannot access local variable 'contador'
# O Python viu a atribuicao e tratou contador como local o tempo todo.

A atribuição torna contador local; usá-lo antes de definir dá UnboundLocalError.

Para de fato reatribuir a global de dentro da função, existe o comando global. Ele avisa ao Python que aquele nome se refere à variável global, não a uma nova local. Funciona, mas use com muita parcimônia. Mexer em variáveis globais de dentro de funções deixa o programa difícil de acompanhar, porque qualquer função pode alterar o estado compartilhado sem deixar rastro na sua assinatura. O caminho mais limpo quase sempre é receber o valor por parâmetro e devolver o novo valor com return.

contador = 0

def incrementar():
    global contador       # avisa: contador aqui e a global
    contador = contador + 1
    return contador

print(incrementar())  # 1
print(incrementar())  # 2

# Melhor design: sem global, valor entra e sai
def proximo(n):
    return n + 1
contador = proximo(contador)  # 3

global resolve, mas passar o valor e devolver com return costuma ser mais limpo.

A regra LEGB, em visão simples

Quando você usa um nome, como print ou taxa, o Python precisa descobrir a qual variável ele se refere. Ele procura em uma ordem fixa, resumida na sigla LEGB. Primeiro no escopo Local, dentro da função atual. Se não achar, sobe para o Enclosing, o escopo de uma função que envolve a atual (útil em funções dentro de funções). Depois no Global, o nível do arquivo. Por fim no Built-in, o conjunto de nomes que já vêm com o Python, como print, len e range. O primeiro que ele encontrar nessa sequência é o que vale.

Você não precisa decorar LEGB para programar bem, mas conhecer a ordem explica muitos comportamentos. Por exemplo, por que uma variável local com o mesmo nome de uma global sombreia a global dentro da função: o Python acha a local primeiro e nem chega na global. Ou por que dá para chamar print em qualquer lugar: ele mora no escopo Built-in, o último e mais amplo. Entender a busca de nomes tira o mistério de erros como o UnboundLocalError que você acabou de ver.