Curso de Python / Definir funções, receber argumentos e retornar valores

Uma função em Python reúne uma tarefa sob um nome, recebe argumentos e pode devolver um resultado com return. Retornar um valor permite usá-lo em outro cálculo; exibi-lo com print() serve para mostrar uma informação e não substitui esse retorno.

Entender parâmetros, argumentos e retorno

A instrução def associa um nome a uma função e define seu corpo indentado. Os parâmetros são os nomes escritos na definição, como amount e fee; os argumentos são os valores fornecidos na chamada, como 8000 e 500. Executar a definição prepara a função, mas não executa seu corpo. O cálculo acontece quando a função é chamada.

Ao alcançar return expressão, a função entrega o valor da expressão a quem a chamou e encerra aquela chamada. Um return sem expressão, ou chegar ao fim do corpo sem executar um retorno explícito, produz None, o objeto usado para representar a ausência de um valor. A documentação oficial mostra esse mecanismo em definição de funções.

É útil manter a conta separada de decisões sobre apresentação: o mesmo resultado pode ser exibido no terminal, comparado num teste ou usado por outro componente. Isso não obriga toda função a fazer apenas contas; a divisão deve deixar claro o que cada função faz e quais efeitos produz.

Executar a função e reutilizar os resultados

Salve o programa completo abaixo em functions.py, com codificação UTF-8, numa pasta de prática. No terminal com o ambiente virtual do projeto selecionado, execute python functions.py. Se usar macOS ou Ubuntu sem ambiente virtual e seu interpretador responder por python3, execute python3 functions.py. Não há dependências externas.

def total_with_fee(amount, fee):
    """Return the sum of the amount and fee."""
    return amount + fee

first = total_with_fee(8000, 500)
second = total_with_fee(3500, 0)
print(first, second)
print(first + second)

A saída esperada é:

8500 3500
12000

A primeira chamada associa 8000 a amount e 500 a fee, devolvendo 8500, que é atribuído a first. A segunda devolve 3500, atribuído a second. O programa exibe os dois valores e depois soma os resultados, obtendo 12000. O retorno disponibiliza os números para essa soma, sem precisar ler o que apareceu na tela.

A frase em inglês entre aspas triplas é a docstring, uma string de documentação. Ela significa “Retorna a soma do valor e da taxa”. Não é uma mensagem impressa pelo programa. A indentação coloca a documentação e o retorno dentro da função; as atribuições a first e second, sem essa indentação, ficam no código que faz as chamadas.

Separar cálculo, apresentação e regras de entrada

return fornece um resultado ao chamador. print() envia uma representação textual à saída padrão, normalmente o terminal, e sua própria chamada devolve None. É possível imprimir e também retornar dentro de uma função, mas, para reutilizar este cálculo sem produzir mensagens a cada uso, mantenha o retorno na função e a impressão no trecho que a chama.

A função apresentada não valida valores monetários: apenas aplica + aos dois argumentos. Com inteiros, faz uma soma; dois textos como "8000" e "500" seriam concatenados como "8000500". Um inteiro e um texto causariam TypeError. Nem o nome da função nem a docstring impõem tipos ou proíbem números negativos. Se o programa exigir valores inteiros não negativos, valide essa condição ao receber os dados, antes de chamar a função, e documente a premissa.

Uma docstring deve descrever o que o código realmente faz e as condições que espera. Evite anunciar conversão, arredondamento ou rejeição de dados que não foram implementados. A prática de validação de notas mostra por que verificar um intervalo e verificar um tipo são decisões diferentes.

Experimentar alterações e identificar falhas de chamada

1. Na primeira chamada, altere somente a taxa de 500 para 1000. A primeira linha deve ser 9000 3500 e a soma deve ser 12500. Restaure 500 e confirme a saída original.
2. Dentro da função, substitua temporariamente return amount + fee por print(amount + fee). As chamadas exibem 8500 e 3500, mas atribuem None a first e second. A impressão seguinte mostra None None e a tentativa de somá-los provoca TypeError. Restaure o retorno para recuperar o funcionamento original.
3. Num teste separado, tente executar total_with_fee(8000, 500) antes de a instrução def ser executada. Sem uma definição anterior desse nome, ocorre NameError. O ponto decisivo é a ordem de execução, não simplesmente a posição visual de uma chamada dentro de outro corpo de função.
4. Depois da definição, tente chamar total_with_fee(8000). Como fee é obrigatório, ocorre TypeError. Compare os dois parâmetros com os argumentos fornecidos; neste exemplo, zero pode ser passado explicitamente quando não há taxa.

Os nomes dos parâmetros pertencem ao contexto da chamada e não criam automaticamente variáveis globais com esses nomes. Para obter o resultado, use o valor retornado e atribua-o a uma variável no chamador. Evite depender de alterações escondidas em variáveis externas para transmitir essa informação.

O comportamento de return e as opções de print() estão documentados separadamente porque suas responsabilidades são diferentes. Ao investigar um resultado ausente, confira primeiro se o caminho executado alcança um retorno com valor e só depois examine a impressão feita pelo chamador.