Variáveis Globais em Python

Variáveis globais em Python são variáveis declaradas fora de qualquer função. Elas existem durante todo o tempo de vida do programa e podem ser lidas em qualquer lugar — mas modificá-las dentro de uma função exige a palavra-chave global. Esta página aborda como as variáveis globais funcionam, as armadilhas a evitar e quando buscar alternativas melhores.

O que são Variáveis Globais?

Uma variável global é criada no escopo do módulo (nível superior) — fora de qualquer função ou classe. Qualquer código no mesmo módulo pode lê-la sem nenhuma declaração especial.

Python usa a regra LEGB para resolver nomes: ela pesquisa nos escopos Local → Envolvente → Global → Embutido, nessa ordem. Uma variável global fica no nível "G", portanto toda função pode encontrá-la após esgotar seus próprios escopos local e envolvente. Veja Python Scope para uma explicação completa dos quatro níveis.

Leitura vs. Modificação de Variáveis Globais

Lendo uma variável global (sempre funciona)

Por padrão, uma função pode ler qualquer variável global sem nenhuma sintaxe especial:

language = "Python"

def print_language():
    print(language)  # reads the global

print_language()  # Output: Python

A palavra-chave global — necessária para modificação

Se você tentar atribuir a uma variável dentro de uma função, Python cria uma nova variável local em vez de atualizar a global. Para modificar a global, você deve declará-la com a palavra-chave global:

counter = 0

def increment():
    global counter   # tell Python we mean the global 'counter'
    counter += 1
    print("Counter:", counter)

increment()  # Output: Counter: 1
increment()  # Output: Counter: 2
print(counter)  # Output: 2

Sem global counter, a linha counter += 1 geraria um UnboundLocalError porque Python tentaria ler uma variável local chamada counter antes de ela ser atribuída.

A Armadilha do UnboundLocalError

Este é o erro mais comum com variáveis globais. No momento em que Python vê qualquer atribuição a um nome dentro de uma função, ele trata esse nome como local em toda a função — inclusive nas linhas anteriores à atribuição:

x = 10

def broken():
    print(x)   # ERROR — Python sees the assignment below and marks x as local
    x = 20

broken()
# UnboundLocalError: local variable 'x' referenced before assignment

Corrija adicionando global x no início da função se você realmente precisa modificar a global, ou renomeando a variável local se quiser uma cópia independente.

Sombreamento de Variáveis

Atribuir a um nome dentro de uma função sem a palavra-chave global cria uma variável local que sombreia a global — a global não é alterada:

count = 100

def show_count():
    count = 5   # local variable — shadows the global 'count'
    print("Inside function:", count)   # 5

show_count()
print("Outside function:", count)  # 100 — global is unchanged

O sombreamento não é um erro, mas pode ser confuso. Use nomes distintos para tornar a intenção clara.

global Dentro de Funções Aninhadas

Se você precisar acessar um global no nível do módulo a partir de uma função interna (aninhada), use global — não nonlocal. nonlocal acessa apenas o escopo da função imediatamente envolvente, não o nível do módulo:

total = 0

def outer():
    def inner():
        global total   # reaches module scope
        total += 10
    inner()

outer()
outer()
print("total:", total)  # Output: total: 20

Compare isso com nonlocal, que modifica a variável da função envolvente, mas deixa o global no nível do módulo intocado:

x = "global"

def outer():
    x = "outer"
    def inner():
        nonlocal x   # modifies outer()'s x, not the module-level x
        x = "inner"
    inner()
    print("outer x after inner():", x)  # inner

outer()
print("global x after outer():", x)   # global — unchanged

Para uma análise mais aprofundada de nonlocal, veja Python Scope.

Constantes no Nível do Módulo — O Bom Caso de Uso

O uso mais legítimo de globais no nível do módulo é para constantes — valores definidos uma vez e nunca alterados em tempo de execução. Por convenção, escreva-os em UPPER_SNAKE_CASE:

MAX_RETRIES = 3
DEFAULT_TIMEOUT = 30

def connect(host, retries=MAX_RETRIES, timeout=DEFAULT_TIMEOUT):
    print(f"Connecting to {host} with {retries} retries, timeout={timeout}s")

connect("db.example.com")
# Output: Connecting to db.example.com with 3 retries, timeout=30s

Constantes nunca precisam da palavra-chave global porque você apenas as lê, nunca as reatribui.

Boas Práticas

1. Prefira argumentos de função e valores de retorno

Passar dados por meio de assinaturas de função torna o código mais fácil de testar e de entender. Esta função pura é mais simples do que usar um counter global mutável:

def increment(counter):
    return counter + 1

counter = 0
counter = increment(counter)
counter = increment(counter)
print("counter:", counter)  # Output: counter: 2

2. Reserve globais para constantes verdadeiramente do módulo

Use globais para valores genuinamente fixos durante toda a execução do programa (MAX_CONNECTIONS, APP_VERSION, configuração carregada uma vez na inicialização). Evite globais mutáveis que mudam ao longo do tempo.

3. Use nomes descritivos em UPPER_SNAKE_CASE para constantes

Um nome como MAX_RETRIES é imediatamente reconhecível como uma constante do módulo. Um nome como r não é.

4. Inicialize antes de usar

Declare todas as variáveis globais no topo do módulo, antes de qualquer função que as utilize. Isso evita NameError caso uma função seja chamada antes de a variável ser definida.

5. Cuidado com threads

Se múltiplas threads chamarem funções que modificam a mesma variável global, você terá uma condição de corrida. Proteja o estado mutável compartilhado com um threading.Lock, ou redesenhe para evitar o estado compartilhado completamente. Veja Python Variables para uma visão geral mais ampla dos tipos de variáveis em Python.

Resumo

Prática