Módulo 3 - Funções avançadas

Argumentos nomeados e posicionais

10 min de leitura · por Cesar Gargiulo, revisado pela equipe ValorFinal e GuardiaSec · Atualizado em 01/07/2026

O que você vai aprender

  • Diferenciar argumentos posicionais de argumentos nomeados.
  • Chamar uma função nomeando parâmetros para ganhar clareza.
  • Respeitar a regra de posicionais antes de nomeados na chamada.
  • Usar nomes para tornar legíveis chamadas com True, False e números soltos.

Duas formas de passar o mesmo valor

Toda função pode ser chamada de duas maneiras, e você já usou as duas sem reparar. A forma posicional é a mais direta: você passa os valores na ordem dos parâmetros e o Python confia nessa ordem. A forma nomeada é mais explícita: você diz, para cada valor, a qual parâmetro ele pertence, escrevendo o nome seguido de igual. As duas produzem o mesmo resultado; a diferença está na clareza de quem lê a chamada depois.

def criar_conta(nome, saldo, ativo):
    return f"{nome}: R$ {saldo:.2f}, ativa={ativo}"

# Posicional: casa pela ordem
print(criar_conta("Ana", 100.0, True))
# Ana: R$ 100.00, ativa=True

# Nomeado: casa pelo nome, ordem livre
print(criar_conta(saldo=100.0, nome="Ana", ativo=True))
# Ana: R$ 100.00, ativa=True

As duas chamadas fazem a mesma coisa. Na nomeada, a ordem dos argumentos é livre.

Na chamada nomeada, repare que saldo veio antes de nome e o resultado saiu igual. Como cada valor traz o nome do seu parâmetro, o Python não depende mais da ordem. Isso é útil quando você não lembra a sequência exata, e é ainda mais útil para quem lê o código: a chamada vira quase uma frase, dizendo o papel de cada valor.

Quando nomear vale muito a pena

O caso em que nomear mais ajuda é o dos valores sem contexto, os famosos True, False e números soltos. Uma chamada como enviar(email, True, False) não diz nada: o que é o primeiro True? E o False? Quem lê precisa correr até a definição da função para descobrir. Com nomes, a mesma chamada se explica sozinha. Não custa nada e economiza a confusão de quem for manter o código, inclusive você mesmo daqui a alguns meses.

Só posicional (confuso)

  • enviar("oi", True, False)
  • Não se sabe o que é cada True/False
  • Precisa abrir a função para entender
  • Fácil trocar a ordem por engano

Nomeado (claro)

  • enviar("oi", copia=True, urgente=False)
  • Cada valor diz o que representa
  • A chamada se explica sozinha
  • A ordem trocada não muda nada
# Errado na PRATICA (roda, mas ilegivel)
def enviar(texto, copia, urgente):
    return (texto, copia, urgente)
enviar("oi", True, False)  # o que e True? o que e False?

# Errado de verdade: nomeado antes de posicional
enviar(copia=True, "oi", urgente=False)
# SyntaxError: positional argument follows keyword argument

Nomear evita ambiguidade. E lembre: posicional sempre antes de nomeado na chamada.

Fixando posicional e nomeado

Recapitulando: posicional é rápido e casa pela ordem; nomeado é explícito e casa pelo nome, liberando a ordem. Você pode misturar os dois numa mesma chamada, desde que os posicionais venham primeiro. Na dúvida entre os dois estilos, nomeie quando o valor sozinho não deixa claro o que representa, especialmente com True, False e números que não falam por si. Clareza para quem lê é o critério que resolve quase toda decisão neste módulo.

Teste rápido

Qual é a principal vantagem de usar argumentos nomeados na chamada?

Perguntas frequentes

Posso misturar argumentos posicionais e nomeados na mesma chamada?
Pode, desde que os posicionais venham antes dos nomeados. Por exemplo, criar_conta("Ana", ativo=True, saldo=100.0) é válido. Já colocar um posicional depois de um nomeado dá SyntaxError, porque o Python perderia a referência da posição.
O nome do argumento precisa ser igual ao do parâmetro?
Sim, exatamente igual. Se o parâmetro se chama saldo, você escreve saldo=100.0. Um nome diferente, como valor=100.0, causa um TypeError dizendo que a função não recebeu esse argumento. Por isso vale dar nomes de parâmetro claros e estáveis.
Argumento nomeado é a mesma coisa que argumento por palavra-chave?
Sim. Na documentação em inglês o termo é keyword argument, às vezes abreviado como kwarg. Em português dizemos argumento nomeado ou por palavra-chave. É esse conceito que dá nome ao **kwargs, que você verá na próxima aula.
Nomear os argumentos deixa o programa mais lento?
Não de forma perceptível. A diferença de desempenho entre posicional e nomeado é irrelevante para praticamente qualquer programa. A escolha deve ser guiada pela clareza, não pela velocidade. Prefira nomear sempre que isso tornar a chamada mais fácil de entender.
Existe como obrigar que um argumento seja sempre nomeado?
Existe, colocando um asterisco sozinho na lista de parâmetros: def f(a, *, b) obriga b a ser passado como nomeado. É um recurso mais avançado, útil quando você quer evitar chamadas confusas com muitos valores posicionais. Vale conhecer, mesmo que use pouco no começo.
Quando prefiro posicional em vez de nomeado?
Quando a função tem um ou dois parâmetros óbvios e a ordem é natural, como somar(2, 3) ou abrir(caminho). Nesses casos, nomear seria verboso sem ganho. A regra prática é: nomeie quando o valor sozinho não deixa claro o que ele representa.

Fontes

Seu progresso fica salvo neste aparelho. Assinantes sincronizam entre os aparelhos.