Funções Python

Uma função é um bloco de código nomeado e reutilizável que executa uma tarefa específica. As funções permitem que você escreva a lógica uma vez e a chame de qualquer lugar no seu programa — tornando o código mais curto, mais fácil de ler e mais simples de testar. Este capítulo aborda tudo o que você precisa para trabalhar com confiança com funções Python: definição, parâmetros, valores de retorno, argumentos padrão, *args e **kwargs, escopo, docstrings, dicas de tipo, recursão e uso de funções como objetos de primeira classe.

Definindo uma Função

Use a palavra-chave def, um nome, parênteses e dois-pontos. O corpo é indentado um nível.

def greet(name):
    print("Hello, " + name)

A função não é executada até que você a chame. Nada acontece no momento da definição, exceto que Python armazena o objeto de função com o nome fornecido.

Chamando uma Função

Passe argumentos dentro dos parênteses correspondendo aos nomes dos parâmetros na definição.

Valores de Retorno

Uma função pode enviar um resultado de volta ao chamador com a instrução return. Sem return, Python retorna None.

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

result = add(3, 5)
print(result)  # 8

Assim que return é executado, a função para imediatamente — qualquer código após ele no mesmo corpo da função se torna inalcançável.

Retornando Múltiplos Valores

Python permite que você retorne vários valores como uma tupla, que você pode desempacotar no lado do chamador.

import math

def circle_stats(radius):
    area = math.pi * radius ** 2
    circumference = 2 * math.pi * radius
    return area, circumference

area, circ = circle_stats(5)
print(round(area, 2))   # 78.54
print(round(circ, 2))   # 31.42

Parâmetros e Argumentos

Python suporta várias formas de passar argumentos.

Argumentos Posicionais

Os argumentos são correspondidos aos parâmetros em ordem.

def describe(name, age):
    print(name, "is", age, "years old")

describe("Bob", 25)   # Bob is 25 years old

Argumentos por Palavra-chave

Você pode passar argumentos pelo nome, em qualquer ordem.

describe(age=25, name="Bob")   # Bob is 25 years old

Valores Padrão de Parâmetros

Forneça um valor de fallback que é usado quando o chamador omite esse argumento.

def greet(name="World"):
    print("Hello, " + name)

greet()         # Hello, World
greet("Alice")  # Hello, Alice

Atenção: nunca use um objeto mutável (lista, dict) como valor padrão — ele é criado uma vez no momento da definição e compartilhado entre todas as chamadas. Use None como padrão e crie o objeto dentro do corpo da função.

# Correct pattern for a mutable default
def append_item(item, lst=None):
    if lst is None:
        lst = []
    lst.append(item)
    return lst

Argumentos Posicionais Arbitrários (*args)

Prefixe um nome de parâmetro com * para coletar qualquer número de argumentos posicionais em uma tupla.

def total(*numbers):
    return sum(numbers)

print(total(1, 2, 3))    # 6
print(total(10, 20))     # 30

Argumentos por Palavra-chave Arbitrários (**kwargs)

Prefixe com ** para coletar qualquer número de argumentos por palavra-chave em um dicionário.

def describe_person(**info):
    for key, value in info.items():
        print(key + ": " + str(value))

describe_person(name="Alice", age=30, city="Paris")
# name: Alice
# age: 30
# city: Paris

Combinando Tipos de Parâmetros

Quando você mistura tipos de parâmetros, a ordem deve ser: posicionais, *args, somente por palavra-chave, **kwargs.

def log(level, *messages, separator=" | ", **meta):
    print(level.upper(), separator.join(messages), meta)

log("info", "started", "ready", separator=" — ", version="1.0")
# INFO started — ready {'version': '1.0'}

Escopo de Variáveis

As regras de escopo do Python seguem a regra LEGB: Local → Abrangente → Global → Integrado.

Uma variável definida dentro de uma função é local — ela não pode ser acessada fora da função.

def my_func():
    x = 10          # local to my_func
    print(x)

my_func()
# print(x)  # NameError: name 'x' is not defined

Para ler ou modificar uma variável global dentro de uma função, declare-a com global.

x = 10

def change_x():
    global x
    x = 20

change_x()
print(x)   # 20

Use global com moderação — funções que dependem de estado global são mais difíceis de testar e reutilizar. Veja Python Variables e Global Variables para uma análise mais aprofundada do escopo.

Docstrings

Uma docstring é uma string literal colocada imediatamente após a linha def. Ela documenta o que a função faz, o que ela aceita e o que retorna. Python a armazena no atributo __doc__ da função e ferramentas como help() a exibem.

def add(a, b):
    """Return the sum of a and b.

    Args:
        a: First number.
        b: Second number.

    Returns:
        The sum as a number.
    """
    return a + b

print(add.__doc__)
# Return the sum of a and b.
# ...

Dicas de Tipo

As dicas de tipo (PEP 484) permitem anotar tipos de parâmetros e de retorno. Python não as impõe em tempo de execução, mas editores, linters e mypy as utilizam para detectar bugs antecipadamente.

def multiply(a: float, b: float) -> float:
    return a * b

print(multiply(3, 4))      # 12
print(multiply(2.5, 2.0))  # 5.0

Recursão

Uma função pode chamar a si mesma. Isso é chamado de recursão e é útil para problemas com uma estrutura naturalmente recursiva (árvores, fatoriais, etc.). Toda função recursiva precisa de um caso base que interrompa a recursão.

def factorial(n):
    if n == 0 or n == 1:   # base case
        return 1
    return n * factorial(n - 1)

print(factorial(5))   # 120
print(factorial(0))   # 1

Python limita a profundidade de recursão (padrão 1000) para evitar estouro de pilha. Para recursão profunda, prefira uma abordagem iterativa ou use sys.setrecursionlimit.

Funções como Objetos de Primeira Classe

Em Python, funções são objetos. Você pode armazená-las em variáveis, passá-las como argumentos e retorná-las de outras funções.

def apply(func, value):
    return func(value)

def double(n):
    return n * 2

print(apply(double, 7))   # 14

Esta é a base para funções lambda, funções de ordem superior e decoradores.

Funções Integradas vs. Funções Definidas pelo Usuário

Python vem com muitas funções integradas — print(), len(), range(), sum(), sorted() — que estão sempre disponíveis sem uma importação. Funções definidas pelo usuário são as que você escreve com def. Ambas seguem sintaxe de chamada idêntica.

Boas Práticas

• Nomeie funções como verbos: calculate_tax() é mais claro que tax().
• Faça uma coisa: uma função que valida, salva e envia um e-mail são três funções esperando para nascer.
• Escreva uma docstring: mesmo uma única frase descrevendo o propósito é valiosa.
• Evite efeitos colaterais sempre que possível: funções que retornam valores e não alteram nenhum estado global são mais fáceis de testar.
• Mantenha as assinaturas curtas: mais de três ou quatro parâmetros é um sinal para agrupar dados relacionados em uma classe ou dict.
• Use dicas de tipo: elas servem como documentação leve e habilitam análise estática.

Prática