Mais cedo ou mais tarde, você lerá uma função como def handler(*args, **kwargs) e se perguntará o que ela aceita. Python *args e **kwargs permitem que uma função receba um número flexível de argumentos. Eles potencializam decoradores, wrappers e muitas APIs de biblioteca.

Este guia aborda como eles funcionam em ambas as direções, juntamente com as novas maneiras pelas quais o Python permite controlar como uma função é chamada. Executamos cada exemplo no Python 3.13 e a saída mostrada vem dessa execução.

O que *args faz

Um parâmetro escrito com um asterisco coleta quaisquer argumentos posicionais extras em uma tupla:

def total(*args):
    print(type(args).__name__, args)
    return sum(args)

print(total(1, 2, 3))
# tuple (1, 2, 3)
# 6

print(total())
# tuple ()
# 0

Sem argumentos, você simplesmente obtém uma tupla vazia, então a função ainda funciona. O nome args é uma convenção. *numbers se comportaria da mesma forma, e um nome mais descritivo geralmente é melhor.

O que **kwargs faz

Duas estrelas coletam quaisquer argumentos extras de palavras-chave em um dicionário:

def describe(**kwargs):
    print(type(kwargs).__name__, kwargs)

describe(name="Asha", city="Pune")
# dict {'name': 'Asha', 'city': 'Pune'}

Por ser um dicionário normal, você pode fazer um loop nele, procurar chaves com get() e passá-lo adiante. As chaves mantêm a ordem em que foram passadas.

Ordem dos parâmetros

Quando você mistura tipos de parâmetros, o Python requer uma ordem específica:

1. Parâmetros posicionais regulares
2. *argumentos
3. Parâmetros somente de palavras-chave
4. **kwargs

def order(item, qty=1, *extras, priority=False, **notes):
    print(item, qty, extras, priority, notes)

order("pen")
# pen 1 () False {}

order("pen", 2, "gift wrap", "card", priority=True, note="leave at door")
# pen 2 ('gift wrap', 'card') True {'note': 'leave at door'}

Observe priority. Como vem depois de *extras, ele só pode ser definido pelo nome, portanto, um argumento posicional perdido nunca poderia defini-lo por acidente. Colocar **kwargs antes não é permitido, e nosso teste gerou um SyntaxError: ​​”os argumentos não podem seguir o argumento var-keyword”.

Desempacotando ao ligar

As mesmas estrelas funcionam ao contrário no local da chamada. Uma estrela espalha uma lista ou tupla em argumentos posicionais e duas estrelas espalham um dicionário em argumentos de palavras-chave:

nums = [4, 5, 6]
total(*nums)            # same as total(4, 5, 6) -> 15

settings = {"name": "Ben", "city": "Delhi"}
describe(**settings)    # same as describe(name="Ben", city="Delhi")

A descompactação funciona com qualquer função, não apenas aquelas que usam *args e **kwargs. Isso é útil quando a configuração chega como um dicionário:

def connect(host, port, timeout=5):
    return f"{host}:{port} (timeout {timeout})"

connect(**{"host": "db.local", "port": 5432})
# 'db.local:5432 (timeout 5)'

connect(**{"host": "db.local", "port": 5432, "ssl": True})
# TypeError: connect() got an unexpected keyword argument 'ssl'

Esse erro é útil. Uma função sem **kwargs rejeita opções desconhecidas, portanto, um erro de digitação no nome de uma configuração falha ruidosamente em vez de ser ignorado silenciosamente.

Argumentos somente de palavras-chave

Um simples * na assinatura, sem nome, significa “tudo depois disso deve ser passado por palavra-chave”:

def make_user(name, *, admin=False):
    return name, admin

make_user("Asha", admin=True)
# ('Asha', True)

make_user("Asha", True)
# TypeError: make_user() takes 1 positional argument but 2 were given

Esta é uma ótima maneira de proteger sinalizadores booleanos. Uma chamada como make_user("Asha", True) força os leitores a adivinhar o que True significa. Exigir admin=True torna cada chamada autoexplicativa.

Argumentos apenas posicionais

Desde o Python 3.8, um / marca parâmetros que só podem ser passados por posição:

def area(width, height, /):
    return width * height

area(3, 4)                 # 12
area(width=3, height=4)
# TypeError: area() got some positional-only arguments
#   passed as keyword arguments: 'width, height'

Isso permite que uma biblioteca renomeie esses parâmetros posteriormente sem quebrar o código de ninguém, já que ninguém pode depender dos nomes. Vários integrados funcionam dessa maneira. Por exemplo, len(obj=[1]) não funciona.

Decoradores e embalagens

Esta é a principal razão do mundo real para usar os dois juntos. Um wrapper geralmente precisa aceitar quaisquer argumentos que a função original receba e transmiti-los inalterados:

import functools, time

def timed(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        start = time.perf_counter()
        result = func(*args, **kwargs)
        print(f"{func.__name__} took {time.perf_counter() - start:.4f}s")
        return result
    return wrapper

@timed
def slow_add(a, b, delay=0.01):
    time.sleep(delay)
    return a + b

print(slow_add(2, 3, delay=0.02))
# slow_add took 0.0205s
# 5

O wrapper não precisa conhecer os parâmetros de slow_add, portanto funciona para qualquer função. Seu valor de tempo será um pouco diferente. Nosso guia para decoradores Python explica functools.wraps e outros detalhes.

Mesclando opções

** também funciona dentro de um literal de dicionário, o que oferece uma maneira elegante de aplicar substituições sobre os padrões:

defaults = {"theme": "light", "lang": "en"}

def build(**overrides):
    return {**defaults, **overrides}

build(theme="dark")
# {'theme': 'dark', 'lang': 'en'}

As chaves posteriores vencem, portanto a substituição substitui o padrão. As subclasses também usam esse padrão, como em super().__init__(*args, **kwargs), para passar argumentos extras para uma classe pai. Consulte Classes e objetos Python para obter mais informações sobre super().

Folha de dicas

Quando evitá-los

A flexibilidade tem um preço. Uma função definida como def create(**kwargs) não informa aos leitores quais opções existem e os editores não podem completá-las automaticamente. Os erros de digitação podem passar silenciosamente por várias camadas antes que algo falhe.

Portanto, prefira parâmetros explícitos quando souber o que uma função precisa. Use *args e **kwargs quando você realmente precisar de flexibilidade: wrappers, decoradores, encaminhamento de argumentos para outra função ou uma entrada verdadeira de comprimento variável como total(*numbers). Se uma função precisar de muitas opções nomeadas, um dataclass também poderá ser mais claro.

Erros comuns

Usando um padrão mutável

Não se trata de estrelas, mas muitas vezes aparece perto delas. Um valor padrão é criado uma vez, quando a função é definida, e então compartilhado entre chamadas:

def bad(items=[]):
    items.append(1)
    return items

print(bad(), bad())
# [1, 1] [1, 1]

Ambas as chamadas retornaram a mesma lista, que até então continha dois itens. Use items=None e crie uma nova lista dentro da função.

Outros erros

• Esquecendo de desempacotar. Ligar para total(nums) passa uma lista em vez de três números. Escreva total(*nums).
• Engolindo erros de digitação. Uma função que aceita **kwargs, mas ignora chaves desconhecidas, oculta opções com erros ortográficos. Valide-os ou evite **kwargs.
• Passar o mesmo argumento duas vezes. f(1, **{"a": 2}), onde a é o primeiro parâmetro, gera um erro de “valores múltiplos”.
• Não encaminhando em um wrapper. Chamar func(args, kwargs) passa uma tupla e um ditado. A forma correta é func(*args, **kwargs).

Digite dicas para *args e **kwargs

As dicas de tipo em *args e **kwargs descrevem cada valor individual, não a coleção inteira. Isso surpreende muitas pessoas:

def total(*prices: float) -> float:
    return sum(prices)      # prices is tuple[float, ...]

def tag(**attrs: str) -> str:
    return " ".join(f'{k}="{v}"' for k, v in attrs.items())   # dict[str, str]

total(1.5, 2.5)                  # 4.0
tag(id="x", role="button")       # id="x" role="button"

Aqui prices é tratado como uma tupla de pontos flutuantes e attrs como um dicionário de strings. Quando os argumentos de palavras-chave têm tipos diferentes, o Python 3.12 adicionou uma opção precisa: um TypedDict combinado com Unpack.

from typing import TypedDict, Unpack

class Options(TypedDict, total=False):
    timeout: float
    retries: int

def fetch(url: str, **opts: Unpack[Options]) -> None: ...

Um verificador de tipo como mypy ou Pyright pode então rejeitar fetch(url, retries="3") ou um nome de opção com erro ortográfico, o que um simples **kwargs nunca pode fazer. O comportamento do tempo de execução não muda, no entanto. Quando executamos fetch("u", retries="3") no Python 3.13, ele foi executado sem reclamações, porque o próprio Python não impõe dicas de tipo.

Se você estiver documentando uma longa lista de chaves aceitas para **kwargs, considere substituí-las por parâmetros explícitos apenas de palavras-chave. Os editores podem então preenchê-los automaticamente e os erros são detectados imediatamente.

Considerações finais

Lembre-se das duas direções. Numa definição, as estrelas se acumulam. Em uma ligação, eles desfazem as malas. Adicione argumentos somente de palavras-chave para tornar as chamadas mais claras e reserve **kwargs para código que encaminhe argumentos genuinamente. Para praticar, escreva um pequeno decorador que registre os argumentos de cada chamada e use-o em algumas funções diferentes.

Perguntas frequentes

Continue aprendendo