Controlar o escopo e o estado das funções

Escopo é o contexto em que um nome pode ser consultado. Nos exemplos deste tutorial, com funções definidas diretamente no nível superior de um arquivo, observe três categorias:

• Local: parâmetros e nomes que recebem valores dentro do corpo da função.
• Global do arquivo: nomes definidos no nível superior, fora das funções. “Global” aqui se refere ao arquivo atual, não a todos os arquivos de um programa.
• Embutido: nomes fornecidos pelo Python, como len e print, que você pode usar sem defini-los.

O corpo da função forma o contexto local; o restante do arquivo contém os nomes globais desse arquivo; e o Python disponibiliza nomes embutidos.

Observe onde cada nome é definido ou de onde ele vem.

No nível superior do arquivo são definidos prefixo, resumir e resultado. Dentro da função, o parâmetro nomes e os alvos de atribuição quantidade e mensagem são locais. Já len e print são nomes embutidos fornecidos pelo Python.

Nas funções não aninhadas deste tutorial, o Python procura um nome nesta ordem: local → global do arquivo → embutido. A busca termina na primeira associação encontrada.

Um parâmetro ou outro nome local pode ocultar um global de mesmo nome. Se não houver associação local, a função pode consultar o global. Se também não houver global, nomes embutidos como print e len continuam disponíveis.

Observe os valores exibidos dentro e fora da função.

Dentro de mostrar, o parâmetro local tema é encontrado antes do global de mesmo nome. Fora da função, tema continua associado a "global".

O nome print não foi definido local nem globalmente, então a busca chega à função embutida.

A associação local não substitui a associação global de mesmo nome.

Neste exemplo, a associação global chamada len é encontrada antes do recurso embutido de mesmo nome.

Cada chamada de uma função estabelece suas próprias associações locais. Os parâmetros recebem os objetos enviados como argumentos naquela chamada, e as atribuições do corpo criam valores locais para essa execução.

Por isso, um contador inicializado dentro da função começa novamente do valor definido no corpo. A chamada seguinte não continua automaticamente o contador da chamada anterior.

Em cada chamada, etiqueta recebe o argumento atual e contador começa em 0.

Observe que passos é inicializado dentro da função.

Se o corpo de uma função atribui a um nome, esse nome é considerado local em toda a função nos exemplos deste tutorial. Isso vale até para as linhas anteriores à atribuição.

Ao tentar ler esse nome antes que ele receba um valor na chamada atual, Python gera UnboundLocalError. Um nome global com o mesmo texto não é usado como alternativa: a busca já determinou que o nome é local.

A primeira instrução do corpo tenta ler saldo. Porém, a atribuição posterior faz saldo ser local em toda a função.

O nome é classificado como local por causa da atribuição presente no corpo. Durante a execução, a leitura chega antes de esse espaço local receber um valor.

Uma variável local precisa receber um valor antes da leitura em cada caminho que possa chegar a essa leitura. No código abaixo, valor é atribuído quando ativo é verdadeiro, mas permanece sem valor quando o argumento é False.

A falha acontece em print(valor) na chamada com False.

A primeira função garante uma atribuição antes da condição. A segunda usa nomes diferentes para o global consultado e para o resultado local.

Um parâmetro é um nome local associado ao objeto fornecido como argumento. Se o argumento for uma lista, a função não cria uma cópia automática.

Por isso, duas operações têm efeitos diferentes:

• itens = ["novo"] faz o parâmetro apontar para outra lista. O nome do chamador continua apontando para a lista original.
• itens.append("novo") ou itens[0] = "novo" modifica a lista compartilhada. O chamador observa a alteração.

Compare os caminhos das referências antes e depois de cada operação.

Execute o código no seu ambiente e compare as duas listas exibidas.

Em substituir, a reatribuição afeta somente o parâmetro local. O return permite obter a nova lista, mas não altera a lista original.

Em acrescentar, não há return explícito, mas a mutação permanece visível no chamador. Da mesma forma, adicionar um return depois de append não desfaria a alteração já feita.

Antes de executar, preveja as duas linhas produzidas pelos print.

Dentro de uma função, global contador indica que o nome contador se refere ao nome definido no nível superior do arquivo. Isso permite reatribuir esse nome, em vez de criar uma associação local.

A declaração deve aparecer antes das leituras e atribuições a esse nome no corpo da função.

Execute o código e observe que as duas chamadas atualizam o mesmo nome global.

Um contador local inicializado no corpo recomeça em cada chamada. Já o contador declarado como global referencia uma única associação compartilhada pelas chamadas feitas naquele arquivo. Por isso, cada atualização global parte do estado deixado anteriormente.

Compare as referências: no modelo local, cada chamada possui seu próprio contador; no global, todas chegam ao mesmo contador externo.

Apenas consultar um nome global não exige global. Também não é necessário declarar global para modificar um objeto mutável encontrado por esse nome, desde que o próprio nome não seja reatribuído.

No exemplo, taxa é somente lido e a lista encontrada por historico é modificada. Nenhum dos dois nomes recebe uma nova associação dentro das funções.

Nesta versão, vender lê o valor anterior de estoque e reatribui esse mesmo nome global. Embora a chamada mostre apenas quantidade, o resultado também depende do estado deixado pelas chamadas anteriores.

Para tornar essa dependência explícita, o valor atual do estoque deve entrar como argumento, e o novo valor deve sair pelo return.

A função lê e reatribui estoque, mesmo que esse estado não apareça em sua lista de parâmetros.

Na versão refatorada, estoque_atual recebe o estado usado naquela chamada. A função calcula novo_estoque e o retorna, mas não decide onde esse resultado será guardado. Essa atribuição fica visível no chamador: estoque_a = vender(3, estoque_a).

Como não existe um único contador global compartilhado, a mesma função pode atualizar estoque_a e estoque_b de forma independente.

À esquerda, várias chamadas alcançam diretamente um único estado externo. À direita, cada valor entra na função como argumento e retorna ao respectivo nome no chamador.

Copie e execute este código no seu ambiente. A definição completa de vender funciona com qualquer estoque fornecido pelo chamador.

Ao analisar uma função, verifique: 1) onde cada nome foi definido; 2) se um nome local recebe valor antes de ser lido; 3) se a operação reatribui um nome ou modifica um objeto; 4) se o resultado depende de estado global.

No programa abaixo, tarefas, total_tarefas e registrar são nomes globais do arquivo. titulo e registros são parâmetros locais. A declaração global faz total_tarefas, dentro da função, referir-se ao nome global. Já print é um nome embutido.

A função produz dois efeitos diferentes: reatribui o contador global e modifica, por meio de registros, a mesma lista encontrada pelo nome tarefas no código chamador.

Copie este programa completo para um arquivo Python no seu computador. Antes de executá-lo, preveja as duas linhas finais.

No seu editor, refatore o programa antes de consultar a solução de referência. Sua versão deve atender a todos estes critérios:

1. Remover a declaração global.
2. Adicionar à função um parâmetro que receba o total atual.
3. Calcular o novo total em um nome local.
4. Retornar esse novo total.
5. No código chamador, guardar em total_tarefas o retorno de cada chamada.
6. Manter registros.append(titulo), pois a alteração da lista é intencional.

Execute a versão refatorada com as mesmas duas tarefas e confira as linhas exibidas.

Compare esta solução com a sua. Aqui, total_atual e novo_total são nomes locais, assim como os parâmetros titulo e registros.

O contador percorre um fluxo explícito de entrada e retorno. A lista, por sua vez, é um objeto compartilhado que recebe novos elementos.

Na primeira chamada, o contador entra como 0 e o retorno 1 é guardado em total_tarefas. Na segunda, esse 1 entra como argumento e o retorno 2 é guardado novamente.

Nas duas chamadas, registros permite alcançar a mesma lista. Cada append altera esse objeto. Portanto, retirar o estado global do contador não elimina a mutação intencional da lista — apenas torna explícito como o contador é atualizado.