Tôt ou tard, vous lirez une fonction comme def handler(*args, **kwargs) et vous vous demanderez ce qu’elle accepte. Python *args et **kwargs permettent à une fonction de prendre un nombre flexible d’arguments. Ils alimentent les décorateurs, les wrappers et de nombreuses API de bibliothèque.

Ce guide explique comment ils fonctionnent dans les deux sens, ainsi que les nouvelles façons dont Python vous permet de contrôler la façon dont une fonction est appelée. Nous avons exécuté chaque exemple sur Python 3.13 et le résultat affiché provient de cette exécution.

Que fait *args

Un paramètre écrit avec une étoile collecte tous les arguments de position supplémentaires dans un tuple :

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

Sans arguments, vous obtenez simplement un tuple vide, donc la fonction fonctionne toujours. Le nom args est une convention. *numbers se comporterait de la même manière, et un nom plus descriptif est souvent préférable.

Que fait **kwargs

Deux étoiles collectent tous les arguments de mots-clés supplémentaires dans un dictionnaire :

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

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

Parce qu’il s’agit d’un dictionnaire normal, vous pouvez le parcourir, rechercher des clés avec get() et le transmettre. Les clés conservent l’ordre dans lequel elles ont été transmises.

Ordre des paramètres

Lorsque vous mélangez différents types de paramètres, Python nécessite un ordre spécifique :

1. Paramètres de position réguliers
2. *arguments
3. Paramètres de mots clés uniquement
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'}

Remarquez priority. Parce qu’il vient après *extras, il ne peut être défini que par son nom, donc un argument de position parasite ne pourrait jamais le définir par accident. Mettre **kwargs plus tôt n’est pas autorisé, et notre test a généré un SyntaxError : “les arguments ne peuvent pas suivre l’argument var-keyword”.

Déballage lors d’un appel

Les mêmes étoiles fonctionnent en sens inverse sur le site d’appel. Une étoile répartit une liste ou un tuple en arguments de position, et deux étoiles répartissent un dictionnaire en arguments de mots-clés :

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")

Le déballage fonctionne avec n’importe quelle fonction, pas seulement celles qui utilisent *args et **kwargs. C’est pratique lorsque la configuration arrive sous forme de dictionnaire :

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'

Cette erreur est utile. Une fonction sans **kwargs rejette les options inconnues, donc une faute de frappe dans le nom d’un paramètre échoue bruyamment au lieu d’être ignorée en silence.

Arguments de mots clés uniquement

Un * nu dans la signature, sans nom, signifie « tout ce qui suit doit être passé par mot-clé » :

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

C’est un excellent moyen de protéger les drapeaux booléens. Un appel comme make_user("Asha", True) oblige les lecteurs à deviner ce que signifie True. Exiger admin=True rend chaque appel explicite.

Arguments de position uniquement

Depuis Python 3.8, un / marque les paramètres qui ne peuvent être transmis que par position :

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'

Cela permet à une bibliothèque de renommer ces paramètres ultérieurement sans casser le code de qui que ce soit, puisque personne ne peut dépendre de leurs noms. Plusieurs éléments intégrés fonctionnent de cette façon. Par exemple, len(obj=[1]) ne fonctionne pas.

Décorateurs et emballages

C’est la principale raison réelle d’utiliser les deux ensemble. Un wrapper doit souvent accepter tous les arguments pris par la fonction d’origine et les transmettre tels quels :

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

Le wrapper n’a pas du tout besoin de connaître les paramètres de slow_add, il fonctionne donc pour n’importe quelle fonction. Votre chiffre de timing sera légèrement différent. Notre guide des décorateurs Python explique functools.wraps et d’autres détails.

Options de fusion

** fonctionne également dans un littéral de dictionnaire, ce qui offre un moyen pratique d’appliquer des remplacements en plus des valeurs par défaut :

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

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

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

Les clés ultérieures gagnent, donc le remplacement remplace la valeur par défaut. Les sous-classes utilisent également ce modèle, comme dans super().__init__(*args, **kwargs), pour transmettre des arguments supplémentaires à une classe parent. Voir Classes et objets Python pour en savoir plus sur super().

Aide-mémoire

Quand les éviter

La flexibilité a un prix. Une fonction définie comme def create(**kwargs) ne dit rien aux lecteurs sur les options existantes et les éditeurs ne peuvent pas les compléter automatiquement. Les fautes de frappe peuvent traverser silencieusement plusieurs couches avant que quelque chose échoue.

Préférez donc les paramètres explicites lorsque vous savez ce dont une fonction a besoin. Utilisez *args et **kwargs lorsque vous avez réellement besoin de flexibilité : wrappers, décorateurs, transfert d’arguments vers une autre fonction ou une véritable entrée de longueur variable comme total(*numbers). Si une fonction nécessite de nombreuses options nommées, un dataclass peut également être plus clair.

Erreurs courantes

Utiliser une valeur par défaut mutable

Il ne s’agit pas ici d’étoiles, mais elle apparaît souvent à proximité d’elles. Une valeur par défaut est créée une fois, lorsque la fonction est définie, puis partagée entre les appels :

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

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

Les deux appels ont renvoyé la même liste, qui contenait alors deux éléments. Utilisez items=None et créez une nouvelle liste dans la fonction.

Autres erreurs

• Oublier de déballer. L’appel de total(nums) transmet une liste plutôt que trois nombres. Écrivez total(*nums).
• Avaler des fautes de frappe. Une fonction qui accepte **kwargs mais ignore les clés inconnues masque les options mal orthographiées. Validez-les, ou évitez **kwargs.
• Passer le même argument deux fois. f(1, **{"a": 2}), où a est le premier paramètre, génère une erreur « valeurs multiples ».
• Pas de transfert dans un wrapper. L’appel de func(args, kwargs) transmet un tuple et un dict. La forme correcte est func(*args, **kwargs).

Tapez des indices pour *args et **kwargs

Les indications de type sur *args et **kwargs décrivent chaque valeur individuelle, pas la collection entière. Cela surprend beaucoup de gens :

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"

Ici, prices est traité comme un tuple de flottants et attrs comme un dictionnaire de chaînes. Lorsque les arguments de mots-clés ont des types différents, Python 3.12 a ajouté une option précise : un TypedDict combiné avec Unpack.

from typing import TypedDict, Unpack

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

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

Un vérificateur de type tel que mypy ou Pyright peut alors rejeter fetch(url, retries="3") ou un nom d’option mal orthographié, ce qu’un simple **kwargs ne pourra jamais faire. Le comportement d’exécution ne change cependant pas. Lorsque nous avons exécuté fetch("u", retries="3") sous Python 3.13, il s’est exécuté sans problème, car Python lui-même n’applique pas les indications de type.

Si vous documentez une longue liste de clés acceptées pour **kwargs, envisagez de les remplacer par des paramètres explicites réservés aux mots clés. Les éditeurs peuvent ensuite les compléter automatiquement et les erreurs sont immédiatement détectées.

Pour conclure

Rappelez-vous les deux directions. Dans une définition, les étoiles collectionnent. Lors d’un appel, ils déballent. Ajoutez des arguments de mots-clés uniquement pour rendre les appels plus clairs et réservez **kwargs pour le code qui transmet véritablement les arguments. Pour vous entraîner, écrivez un petit décorateur qui enregistre les arguments de chaque appel et utilisez-le sur quelques fonctions différentes.

Questions fréquentes

Continuez à apprendre