Prima o poi leggerete una funzione come def handler(*args, **kwargs) e vi chiederete cosa accetta. Python *args e **kwargs consentono a una funzione di accettare un numero flessibile di argomenti. Alimentano decoratori, wrapper e molte API di libreria.

Questa guida spiega come funzionano in entrambe le direzioni, insieme ai nuovi modi in cui Python ti consente di controllare come viene chiamata una funzione. Abbiamo eseguito ogni esempio su Python 3.13 e l’output mostrato proviene da quell’esecuzione.

Cosa fa *args

Un parametro scritto con una stella raccoglie eventuali argomenti posizionali aggiuntivi in una 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

Senza argomenti, ottieni semplicemente una tupla vuota, quindi la funzione funziona ancora. Il nome args è una convenzione. *numbers si comporterebbe allo stesso modo e un nome più descrittivo è spesso migliore.

Cosa fa **kwargs

Due stelle raccolgono eventuali argomenti di parole chiave aggiuntivi in un dizionario:

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

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

Poiché è un normale dizionario, puoi scorrerlo, cercare le chiavi con get() e trasmetterlo. Le chiavi mantengono l’ordine in cui sono state passate.

Ordine dei parametri

Quando mescoli tipi di parametri, Python richiede un ordine specifico:

1. Parametri posizionali regolari
2. *arg
3. Parametri relativi solo alle parole chiave
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'}

Avviso priority. Poiché viene dopo *extras, può essere impostato solo per nome, quindi un argomento posizionale vagante non potrebbe mai impostarlo per sbaglio. Non è consentito inserire **kwargs prima e il nostro test ha sollevato un SyntaxError: ​​”gli argomenti non possono seguire l’argomento var-parola chiave”.

Disimballaggio durante la chiamata

Le stesse stelle funzionano al contrario nel luogo della chiamata. Una stella distribuisce una lista o una tupla in argomenti posizionali e due stelle distribuiscono un dizionario in argomenti di parole chiave:

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

Il disimballaggio funziona con qualsiasi funzione, non solo con quelle che utilizzano *args e **kwargs. Ciò è utile quando la configurazione arriva come dizionario:

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'

Questo errore è utile. Una funzione senza **kwargs rifiuta le opzioni sconosciute, quindi un errore di battitura nel nome di un’impostazione fallisce rumorosamente invece di essere ignorato silenziosamente.

Argomenti basati solo su parole chiave

Un semplice * nella firma, senza nome, significa “tutto ciò che segue deve essere passato per parola chiave”:

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

Questo è un ottimo modo per proteggere le bandiere booleane. Una chiamata come make_user("Asha", True) costringe i lettori a indovinare cosa significa True. La richiesta di admin=True rende ogni chiamata autoesplicativa.

Argomenti solo posizionali

A partire da Python 3.8, un / contrassegna i parametri che possono essere passati solo per posizione:

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'

Ciò consente a una libreria di rinominare tali parametri in un secondo momento senza violare il codice di nessuno, poiché nessuno può dipendere dai nomi. Diversi built-in funzionano in questo modo. Ad esempio, len(obj=[1]) non funziona.

Decoratori e involucri

Questo è il motivo principale nel mondo reale per usarli entrambi insieme. Un wrapper spesso deve accettare qualunque argomento venga accettato dalla funzione originale e trasmetterlo senza modifiche:

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

Non è necessario che il wrapper conosca affatto i parametri di slow_add, quindi funziona per qualsiasi funzione. La cifra temporale sarà leggermente diversa. La nostra guida ai decoratori Python spiega functools.wraps e altri dettagli.

Opzioni di fusione

** funziona anche all’interno di un dizionario letterale, che fornisce un modo accurato per applicare sostituzioni oltre alle impostazioni predefinite:

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

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

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

Le chiavi successive prevalgono, quindi l’override sostituisce l’impostazione predefinita. Anche le sottoclassi utilizzano questo modello, come in super().__init__(*args, **kwargs), per passare argomenti aggiuntivi alla classe genitore. Vedi Classi e oggetti Python per ulteriori informazioni su super().

Foglio informativo

Quando evitarli

La flessibilità ha un prezzo. Una funzione definita come def create(**kwargs) non dice ai lettori quali opzioni esistono e gli editor non possono completarle automaticamente. Gli errori di battitura possono passare silenziosamente attraverso diversi livelli prima che qualcosa fallisca.

Quindi preferisci i parametri espliciti quando sai di cosa ha bisogno una funzione. Usa *args e **kwargs quando hai veramente bisogno di flessibilità: wrapper, decoratori, inoltro di argomenti a un’altra funzione o un vero input di lunghezza variabile come total(*numbers). Se una funzione necessita di molte opzioni con nome, anche un dataclass può essere più chiaro.

Errori comuni

Utilizzando un valore predefinito modificabile

Non si tratta delle stelle, ma spesso appare vicino a loro. Un valore predefinito viene creato una volta, quando la funzione viene definita, e quindi condiviso tra le chiamate:

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

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

Entrambe le chiamate restituirono lo stesso elenco, che a quel punto conteneva due elementi. Utilizzare items=None e creare un nuovo elenco all’interno della funzione.

Altri errori

• Dimenticarsi di disfare i bagagli. Chiamando total(nums) si passa un elenco anziché tre numeri. Scrivi total(*nums).
• Errore di battitura. Una funzione che accetta **kwargs ma ignora i tasti sconosciuti nasconde le opzioni con errori di ortografia. Convalidarli o evitarli **kwargs.
• Passando lo stesso argomento due volte. f(1, **{"a": 2}), dove a è il primo parametro, genera un errore di “valori multipli”.
• Non inoltrato in un wrapper. La chiamata a func(args, kwargs) passa una tupla e un dict. La forma corretta è func(*args, **kwargs).

Digita suggerimenti per *args e **kwargs

I suggerimenti di tipo su *args e **kwargs descrivono ogni singolo valore, non l’intera raccolta. Ciò sorprende molte persone:

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"

Qui prices viene trattato come una tupla di numeri in virgola mobile e attrs come un dizionario di stringhe. Quando gli argomenti delle parole chiave hanno tipi diversi, Python 3.12 ha aggiunto un’opzione precisa: a TypedDict combinato con Unpack.

from typing import TypedDict, Unpack

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

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

Un controllore di tipo come mypy o Pyright può quindi rifiutare fetch(url, retries="3") o un nome di opzione scritto in modo errato, cosa che un semplice **kwargs non potrà mai fare. Il comportamento in fase di esecuzione, tuttavia, non cambia. Quando abbiamo eseguito fetch("u", retries="3") con Python 3.13, è stato eseguito senza problemi, perché Python stesso non applica i suggerimenti sul tipo.

Se ti ritrovi a documentare un lungo elenco di chiavi accettate per **kwargs, valuta la possibilità di sostituirle con parametri espliciti composti solo da parole chiave. Gli editor possono quindi completarli automaticamente e gli errori vengono rilevati immediatamente.

Considerazioni finali

Ricorda le due direzioni. In una definizione, le stelle si raccolgono. Durante una chiamata, disfano le valigie. Aggiungi argomenti composti solo da parole chiave per rendere le chiamate più chiare e riserva **kwargs per il codice che inoltra realmente gli argomenti. Per esercitarti, scrivi un piccolo decoratore che registri gli argomenti di ogni chiamata e usalo su alcune funzioni diverse.

Domande frequenti

Continua a imparare