*args e **kwargs: quantidade variável

Quando você não sabe quantos vêm

Até aqui, toda função tinha um número fixo de parâmetros. Mas pense na função print: ela aceita um valor, dois, dez, quantos você quiser. Como isso é possível? Com *args. Um parâmetro escrito com um asterisco recolhe todos os argumentos posicionais que sobrarem e os entrega dentro da função como uma tupla. Assim a função não precisa saber, de antemão, quantos valores vai receber. Ela lida com o que chegar.

def somar(*args):
    total = 0
    for numero in args:
        total += numero
    return total

print(somar(2, 3))          # 5
print(somar(2, 3, 4, 5))    # 14
print(somar())              # 0
print(type(somar.__name__)) # <class 'str'>

args é uma tupla com todos os posicionais que chegaram, de zero a muitos.

Dentro de somar, args é uma tupla comum: dá para percorrer com um laço, medir com len, indexar. A mesma função somou dois números, quatro números e até nenhum, devolvendo zero. Esse é o ponto de *args: uma única definição atende a chamadas de tamanhos diferentes. Vale reforçar que o nome args é só tradição da comunidade; você poderia escrever *numeros e funcionaria igual. O asterisco é que carrega o significado.

**kwargs: nomeados em quantidade variável

Assim como *args recolhe posicionais, **kwargs recolhe argumentos nomeados extras, e os entrega como um dicionário. A chave é o nome que você usou na chamada; o valor é o que você passou. Isso é ótimo para funções que aceitam opções variadas sem listar cada uma como parâmetro. Um bom exemplo é montar uma configuração ou um perfil em que os campos mudam de caso para caso.

def criar_perfil(nome, **kwargs):
    perfil = {"nome": nome}
    for chave, valor in kwargs.items():
        perfil[chave] = valor
    return perfil

print(criar_perfil("Ana", cidade="Recife", idade=30))
# {'nome': 'Ana', 'cidade': 'Recife', 'idade': 30}

print(criar_perfil("Bruno"))
# {'nome': 'Bruno'}

kwargs é um dicionário: cada argumento nomeado extra vira uma chave e um valor.

A ordem na definição precisa ser respeitada: primeiro os parâmetros normais (com ou sem padrão), depois *args, e por último **kwargs. Essa sequência não é arbitrária. O Python precisa saber onde param os valores fixos, onde começam os posicionais extras e onde entram os nomeados extras. Inverter a ordem gera erro de sintaxe. Guardando a sequência normal, *args, **kwargs, você monta funções bem flexíveis sem confundir o interpretador.

def registrar(evento, *args, **kwargs):
    print("evento:", evento)
    print("extras posicionais:", args)
    print("extras nomeados:", kwargs)

registrar("login", "10:05", "ok", usuario="ana", ip="1.2.3.4")
# evento: login
# extras posicionais: ('10:05', 'ok')
# extras nomeados: {'usuario': 'ana', 'ip': '1.2.3.4'}

Parâmetro normal, depois *args (tupla), depois **kwargs (dicionário).

Fixando *args e **kwargs

Vale usar *args e **kwargs com parcimônia. Eles brilham quando a função é genuinamente aberta, como uma que registra eventos ou repassa opções para outra função. Mas, quando os argumentos são conhecidos, parâmetros nomeados explícitos deixam a função mais clara e mais fácil de usar corretamente, porque o editor e a documentação mostram o que ela espera. Na dúvida, prefira nomes explícitos; recorra a *args e **kwargs quando a variação for real.