Funções, Argumentos e Escopo

Funções agrupam lógica reutilizável com vinculação flexível de parâmetros. As regras de escopo LEGB do Python, os parâmetros variádicos *args/**kwargs e os parâmetros somente por palavra-chave permitem que você projete APIs que são expressivas e seguras.

Receita

def greet(name: str, *, excited: bool = False) -> str:
    msg = f"Olá, {name}"
    return msg + "!" if excited else msg
 
def connect(host: str, port: int = 443, **options: object) -> dict:
    return {"host": host, "port": port, **options}
 
def total(*amounts: float, tax: float = 0.0) -> float:
    return sum(amounts) * (1 + tax)

Quando usar isso:

• Projetando APIs de biblioteca com configuração opcional
• Envolvendo chamáveis com decoradores (veja a seção de iteradores)
• Implementando closures que lembram estado
• Evitando estado mutável global em módulos

Exemplo de Trabalho

from collections.abc import Callable
 
def make_multiplier(factor: int) -> Callable[[int], int]:
    def multiply(value: int) -> int:
        return value * factor
    return multiply
 
def append_item(item: object, bucket: list | None = None) -> list:
    if bucket is None:
        bucket = []
    bucket.append(item)
    return bucket
 
def call_with_retry(fn: Callable[[], object], retries: int = 3) -> object:
    last_error: Exception | None = None
    for attempt in range(retries):
        try:
            return fn()
        except Exception as exc:
            last_error = exc
    raise RuntimeError("falha") from last_error
 
counter = 0
 
def increment_global() -> int:
    global counter
    counter += 1
    return counter
 
def make_counter() -> Callable[[], int]:
    count = 0
    def inc() -> int:
        nonlocal count
        count += 1
        return count
    return inc
 
if __name__ == "__main__":
    double = make_multiplier(2)
    print(double(21))
    print(append_item("a"))
    print(append_item("b"))  # lista nova - padrão compartilhado não usado
    inc = make_counter()
    print(inc(), inc())

O que isso demonstra:

• Closure captura factor do escopo envolvente
• None como sentinela evita o bug do argumento padrão mutável
• nonlocal atualiza count dentro da função aninhada
• global modifica explicitamente counter no nível do módulo

Mergulho Profundo

Como Funciona

• LEGB - Local (função), Enclosing (aninhado), Global (módulo), Built-in (embutido - len, print).
• Tipos de parâmetros - Posicionais, por palavra-chave, somente posicionais (/), somente por palavra-chave (*).
• *args - Tupla de argumentos posicionais extras.
• **kwargs - Dicionário de argumentos por palavra-chave extras.
• Anotações - Armazenadas em __annotations__; avaliadas no momento da definição da função.

Ordem dos Parâmetros

def f(pos_only, /, standard, *, kw_only, **kwargs): ...

Notas Python

# Desempacotamento no local da chamada
args = (1, 2)
kwargs = {"excited": True}
greet("Ada", **kwargs)
 
# functools.partial adia a vinculação de argumentos
from functools import partial
double = partial(make_multiplier, 2)

Armadilhas

• Padrões mutáveis - def f(x=[]) compartilha uma lista entre chamadas. Correção: Padrão None e atribuição interna.
• Closures com vinculação tardia - funcs = [lambda: i for i in range(3)] captura a variável, não o valor. Correção: Argumento padrão lambda i=i: i.
• Sobrescrita de built-ins - def len(x): quebra len(). Correção: Renomear parâmetros.
• global para estado do módulo - Dificulta os testes. Correção: Preferir classes ou objetos de configuração explícitos.
• Muitos *args/**kwargs - Oculta a superfície da API. Correção: Nomear parâmetros importantes explicitamente.

Alternativas

FAQs

Relacionados

• Closures e Captura de Escopo - variáveis livres e fábricas
• Escrevendo Decoradores - envolvendo funções
• functools - partial e wraps
• Noções Básicas de Dicas de Tipo - anotando assinaturas

Versões do Stack: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, e uv 0.6+.