2.14. Definindo funções

Uma função empacota um bloco de código sob um nome para que possa ser chamado de vários lugares. Sempre que um cálculo, uma ação ou um trecho de trabalho estruturado aparece mais de uma vez, uma função o transforma em uma única coisa nomeada.

A palavra-chave é def:

def greet(name):
    print("hello,", name)

greet("Alice")
greet("Bob")

Saída:

hello, Alice
hello, Bob

A linha que começa com def é a definição – ela cria a função, mas não executa o corpo. Chamar greet("Alice") é o que executa o bloco indentado.

2.14.1. Parâmetros e argumentos

Os nomes entre parênteses na linha def são parâmetros – espaços reservados para os valores que quem chama irá fornecer. Os valores reais passados são os argumentos. Uma função pode receber zero ou mais parâmetros:

def square(x):
    return x * x

def add(a, b):
    return a + b

def is_even(n):
    return n % 2 == 0

Uma chamada com o número errado de argumentos lança TypeError imediatamente.

2.14.2. return

Uma instrução return encerra a função imediatamente e devolve um valor a quem a chamou:

def absolute(x):
    if x < 0:
        return -x
    return x

Uma função que nunca chega a um return (ou que tem um return sem valor) retorna None:

>>> def shout(text):
...     print(text.upper())
...
>>> result = shout("hi")
HI
>>> print(result)
None

Uma função pode ter várias instruções return; a primeira alcançada prevalece, e o restante do corpo é ignorado.

2.14.2.1. Retornando múltiplos valores

O Python retorna um objeto por chamada, mas esse objeto pode ser uma tuple – e quem chama pode desempacotá-la na hora:

def minmax(values):
    return (min(values), max(values))

lo, hi = minmax([3, 1, 4, 1, 5, 9])

Os parênteses ao redor do valor de retorno são opcionais; return a, b e return (a, b) são equivalentes.

2.14.3. Docstrings

Um literal de string colocado como a primeira instrução do corpo de uma função é uma docstring. Ela é armazenada no objeto da função e é o que help() exibe:

def scale(value, factor):
    """Multiply ``value`` by ``factor`` and return the result."""
    return value * factor

O IDE mostra as docstrings em tooltips quando o cursor passa sobre o nome da função, então até um resumo de uma linha já compensa. Strings com aspas triplas permitem que a docstring se estenda por várias linhas quando mais detalhes forem úteis.

2.14.4. Convenções de nomenclatura

Os nomes de funções usam snake_case – palavras em minúsculas separadas por underscores. O nome deve descrever o que a função faz:

• Bom: read_temperature, parse_header, is_valid.

• Evite: do_stuff, handle1, temp_func.

Um underscore inicial (_helper) marca uma função como interna ao seu módulo. A convenção é amplamente respeitada, mas não é imposta pelo Python.