Decoratori in Python: che cosa sono, come funzionano e come scriverne uno

Un decoratore in Python è una funzione che riceve un'altra funzione e ne restituisce una nuova, di solito un involucro intorno a quella originale. In questo modo si aggiunge un comportamento — logging, misura del tempo, cache, ripetizione dei tentativi — senza cambiare il codice della funzione. I decoratori si scrivono con la riga @nome sopra la dichiarazione della funzione e si incontrano ovunque: in Flask e FastAPI, in pytest, nella libreria standard.

Che cos'è un decoratore in parole semplici

Pensate a un regalo e alla carta da regalo. Il regalo (la funzione) resta lo stesso, ma intorno compare uno strato che entra in azione per primo. Il decoratore è proprio questo involucro: quando la funzione viene chiamata, per prima cosa esegue il codice dell'involucro, che richiama la funzione originale e può fare qualcosa con il suo risultato.

Funziona perché in Python le funzioni sono oggetti normali. Si possono passare ad altre funzioni, restituire da funzioni e dichiarare dentro altre funzioni. Su queste tre proprietà si basano i decoratori.

Come funziona un decoratore: la @ è una scorciatoia

Prendiamo un decoratore semplicissimo, che stampa un messaggio prima e dopo la chiamata:

def log_calls(func):
    def wrapper():
        print(f"Chiamo {func.__name__}")
        result = func()
        print(f"{func.__name__} completata")
        return result
    return wrapper

@log_calls
def hello():
    print("Ciao!")

hello()

Chiamo hello
Ciao!
hello completata

La scrittura @log_calls sopra def è del tutto equivalente a questa riga, scritta dopo la dichiarazione:

def hello():
    print("Ciao!")

hello = log_calls(hello)

Ora il nome hello punta a wrapper, mentre la funzione originale vive dentro la closure: wrapper ricorda la variabile func della funzione esterna. Un dettaglio importante: il decoratore viene applicato una sola volta, nel momento in cui viene eseguito il def, cioè all'import del modulo; l'involucro invece entra in azione a ogni chiamata.

Closure e decoratori

Una closure è una funzione annidata che ricorda le variabili della funzione esterna anche dopo che questa è terminata. Senza le closure i decoratori non esisterebbero: è così che wrapper accede a func. Dentro una closure si può conservare anche uno stato, per esempio un contatore di chiamate:

def count_calls(func):
    calls = 0
    def wrapper(*args, **kwargs):
        nonlocal calls
        calls += 1
        print(f"{func.__name__}: chiamata n. {calls}")
        return func(*args, **kwargs)
    return wrapper

Come scrivere un decoratore in Python: schema universale

Il primo esempio ha due difetti: l'involucro non accetta argomenti e «cancella» il nome della funzione originale. Lo schema funzionante, da cui conviene partire per qualsiasi decoratore, è questo:

import functools

def my_decorator(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        # codice prima della chiamata
        result = func(*args, **kwargs)
        # codice dopo la chiamata
        return result
    return wrapper

Tre regole dello schema:

1. *args, **kwargs — l'involucro accetta qualsiasi argomento e lo inoltra senza modifiche.
2. return result — non dimenticate di restituire il risultato, altrimenti la funzione decorata restituirà sempre None.
3. @functools.wraps(func) — trasferisce i metadati della funzione originale all'involucro.

Esempio di decoratore: misura del tempo di esecuzione:

import functools
import time

def timer(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        start = time.perf_counter()
        result = func(*args, **kwargs)
        elapsed = time.perf_counter() - start
        print(f"{func.__name__} ha impiegato {elapsed:.3f} s")
        return result
    return wrapper

@timer
def slow_sum(n):
    return sum(range(n))

slow_sum(10_000_000)   # slow_sum ha impiegato 0.142 s

A che cosa serve functools.wraps

Senza wraps la funzione decorata perde il nome, la docstring e gli altri attributi: all'esterno si vede wrapper:

def plain(func):
    def wrapper(*args, **kwargs):
        return func(*args, **kwargs)
    return wrapper

@plain
def add(a, b):
    """Somma due numeri."""
    return a + b

print(add.__name__, add.__doc__)   # wrapper None

Con @functools.wraps(func) l'involucro riceve __name__, __doc__, __module__, __qualname__, __annotations__ della funzione originale, e nell'attributo __wrapped__ resta il riferimento all'originale. È importante per il debug e per i traceback, per help(), per i framework che registrano le funzioni per nome e per inspect.signature, che mostra la firma reale.

Decoratore con parametri (con argomenti)

A volte il decoratore ha bisogno di impostazioni: @retry(times=3), @app.route("/"). Per questo si aggiunge un livello di annidamento in più. La funzione esterna accetta i parametri e restituisce il vero decoratore: questa costruzione si chiama fabbrica di decoratori.

import functools

def repeat(times):
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            result = None
            for _ in range(times):
                result = func(*args, **kwargs)
            return result
        return wrapper
    return decorator

@repeat(times=3)
def ping():
    print("ping")

ping()   # ping, ping, ping — tre righe

Ordine delle chiamate: repeat(times=3) restituisce decorator, che viene applicato a ping e restituisce wrapper. In altre parole, @repeat(times=3) equivale a ping = repeat(times=3)(ping).

Un esempio pratico: ripetere la chiamata in caso di errore:

import functools
import time

def retry(times=3, delay=1.0, exceptions=(Exception,)):
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            for attempt in range(1, times + 1):
                try:
                    return func(*args, **kwargs)
                except exceptions:
                    if attempt == times:
                        raise
                    time.sleep(delay)
        return wrapper
    return decorator

@retry(times=5, delay=0.5, exceptions=(ConnectionError,))
def fetch_rate():
    ...

Più decoratori sulla stessa funzione

I decoratori si possono impilare uno sopra l'altro. Vengono applicati dal basso verso l'alto: quello più vicino a def è il primo.

@timer
@log_calls
def report():
    ...

# equivale a:
report = timer(log_calls(report))

Durante la chiamata lo strato esterno (timer) entra in azione per primo, quindi misurerà anche il tempo di lavoro di log_calls. L'ordine conta: per esempio, se un decoratore verifica i permessi e un altro mette in cache il risultato, la sequenza cambia il comportamento.

Decoratori standard e integrati di Python

Molti decoratori utili sono già nel linguaggio o nella libreria standard:

Cache: functools.cache e lru_cache

Un decoratore di cache ricorda il risultato per ogni insieme di argomenti e, alla chiamata successiva con gli stessi argomenti, lo restituisce senza ricalcolarlo. L'esempio classico sono i numeri di Fibonacci ricorsivi, che senza cache richiedono un tempo esponenziale:

import functools

@functools.cache
def fib(n):
    return n if n < 2 else fib(n - 1) + fib(n - 2)

print(fib(100))   # 354224848179261915075

functools.cache (comparso in Python 3.9) conserva tutti i risultati senza limiti. @functools.lru_cache(maxsize=128) tiene solo le ultime voci ed elimina le più vecchie: è più sicuro per i servizi che girano a lungo. Le statistiche si leggono con fib.cache_info(), la cache si svuota con fib.cache_clear(). Gli argomenti di queste funzioni devono essere hashable: una lista come argomento genera TypeError: unhashable type: 'list'. Inoltre la cache ha senso solo per le funzioni pure, cioè quelle che con gli stessi argomenti restituiscono sempre lo stesso risultato e non hanno effetti collaterali.

Che cosa fa il decoratore property

@property permette di usare un metodo come un attributo, senza parentesi, e di controllare l'assegnazione se serve:

class Account:
    def __init__(self, balance):
        self._balance = balance

    @property
    def balance(self):
        return self._balance

    @balance.setter
    def balance(self, value):
        if value < 0:
            raise ValueError("Il saldo non può essere negativo")
        self._balance = value

acc = Account(100)
print(acc.balance)   # 100
acc.balance = -5     # ValueError

staticmethod e classmethod

class Money:
    def __init__(self, cents):
        self.cents = cents

    @classmethod
    def from_euros(cls, euros):
        return cls(round(euros * 100))

    @staticmethod
    def is_valid(value):
        return value >= 0

m = Money.from_euros(12.5)
print(m.cents, Money.is_valid(-1))   # 1250 False

Proprio @classmethod permette al metodo di lavorare con la classe stessa e non con le sue istanze: from_euros crea correttamente anche un oggetto di una sottoclasse.

Decoratori di classe e classi usate come decoratori

Un decoratore si può applicare a una classe: riceve la classe e restituisce una classe (la stessa o modificata). È così che funziona @dataclass. Un esempio semplice è un registro di classi:

registry = {}

def register(cls):
    registry[cls.__name__] = cls
    return cls

@register
class CsvExporter:
    pass

print(registry)   # {'CsvExporter': <class '__main__.CsvExporter'>}

Il caso inverso è una classe usata come decoratore. Va bene qualsiasi oggetto con il metodo __call__; lo stato è comodo da conservare negli attributi dell'istanza:

import functools

class CountCalls:
    def __init__(self, func):
        functools.update_wrapper(self, func)
        self.func = func
        self.calls = 0

    def __call__(self, *args, **kwargs):
        self.calls += 1
        return self.func(*args, **kwargs)

@CountCalls
def tick():
    pass

tick(); tick()
print(tick.calls)   # 2

Decoratore asincrono

Per le funzioni async def anche l'involucro deve essere una corrutina e attendere il risultato con await; altrimenti restituirebbe un oggetto corrutina non eseguito:

import functools

def log_async(func):
    @functools.wraps(func)
    async def wrapper(*args, **kwargs):
        print(f"Avvio {func.__name__}")
        result = await func(*args, **kwargs)
        print(f"Fatto {func.__name__}")
        return result
    return wrapper

A che cosa servono i decoratori in Python

• Logica trasversale — logging, metriche, misura dei tempi senza copiare il codice in ogni funzione.
• Cache — @functools.cache per i calcoli costosi e puri.
• Controlli — permessi, validazione degli argomenti, autorizzazione nei gestori web.
• Registrazione — rotte in Flask e FastAPI (@app.get("/")), fixture di pytest.
• Affidabilità — ripetizioni dei tentativi, timeout, gestione degli errori.

Il vantaggio principale è la separazione delle responsabilità: la funzione si occupa del proprio compito, mentre il comportamento accessorio si aggiunge con una sola riga e si rimuove con la stessa facilità.

Errori tipici

• L'involucro non restituisce il risultato — dopo la decorazione la funzione restituisce None.
• Manca *args, **kwargs — TypeError quando si chiama la funzione con argomenti.
• Dimenticato wraps — nomi e docstring sbagliati, confusione nei log.
• Parentesi della fabbrica — @repeat al posto di @repeat(3): la funzione finisce nel parametro times.
• Codice pesante nel corpo del decoratore — viene eseguito all'import del modulo, non alla chiamata.

Conclusioni

I decoratori in Python sono funzioni di ordine superiore: ricevono una funzione, restituiscono un involucro, e la @ è solo una forma breve di assegnazione. Partite dallo schema con *args, **kwargs, return result e functools.wraps; per le impostazioni aggiungete il livello della fabbrica. Funzioni, closure e annotazioni, su cui si reggono i decoratori, sono trattati in pratica nel corso di Python.