A la lliçó anterior les signatures de magatzem.py van quedar anotades, i en escriure-les va aparèixer una necessitat nova: l'Anna vol saber quant triga tancament_de_caixa() amb un any de vendes, i vol que cada crida a vendre() quedi auditada a papyrus.log. Podries obrir cada funció i afegir-hi dins el cronòmetre i el log... però això barreja la lògica de negoci amb la fontaneria, i caldria repetir-ho a cada funció. Els decoradors resolen això: emboliquen una funció amb comportament extra sense tocar-ne el codi. Ja els fas servir des del mòdul 5 (@property, @dataclass) sense saber com funcionen per dins; avui els desmuntem peça a peça.

1. Funcions com a objectes de primera classe
2. Closures: funcions que recorden
3. Un decorador des de zero, sense sucre sintàctic
4. La sintaxi @
5. *args i **kwargs: embolicar qualsevol signatura
6. functools.wraps: no perdre la identitat
7. Decoradors per a Papyrus: @cronometrar i @registrar_crida
8. Decoradors amb arguments: @reintentar(cops=3)
9. Els decoradors que ja coneixies, amb una altra llum
10. No sobredecorar

Tot el que ve a continuació es recolza en un fet que ja vas fregar a M3 amb sorted(key=...) i les lambdes: en Python, una funció és un objecte com qualsevol altre. Es pot assignar, passar com a argument i retornar:

La distinció crucial és saludar (l'objecte funció) davant de saludar() (el resultat de cridar-la). Tot el mecanisme dels decoradors gira sobre aquesta diferència.

I també es poden definir i retornar funcions dins de funcions:

Fixa't en una cosa sorprenent de l'exemple anterior: quan crear_salutacio("Papyrus") acaba, la seva variable local botiga hauria de desaparèixer... i tanmateix saluda_papyrus la continua fent servir. Una funció interna que captura variables de la funció que la va crear s'anomena closure (clausura). Pas a pas:

1. Crides crear_salutacio("Papyrus") → es crea botiga = "Papyrus".
2. Es defineix salutacio, que esmenta botiga — Python pren nota que la necessita.
3. crear_salutacio retorna salutacio i acaba, però botiga no es destrueix: viatja de "motxilla" dins de la funció retornada.
4. Cada crida posterior a saluda_papyrus(...) troba botiga intacta.

Els closures són la memòria dels decoradors: així és com la funció embolcall "recorda" quina funció embolica.

Un decorador és simplement una funció que rep una funció i en retorna una altra que l'embolica. Sense @, a mà:

La línia clau és obrir_botiga = anunciar(obrir_botiga): el nom obrir_botiga deixa d'apuntar a la funció original i passa a apuntar a l'embolcall, que desa l'original al seu closure. Ningú no ha tocat el cos d'obrir_botiga; només se li ha posat una capa al voltant.

Com que aquest patró de reassignació és tan comú, Python li dona sucre sintàctic:

@anunciar just a sobre del def significa exactament obrir_botiga = anunciar(obrir_botiga) executat després de definir la funció. No hi ha més màgia: si entens la reassignació, entens el @.

L'embolcall() de dalt no accepta arguments, així que no pot embolicar vendre(cataleg, titol, unitats). La solució és el duo de M3 *args/**kwargs, que aquí troba el seu ús estrella — recollir el que sigui i passar-ho tal qual:

Amb això el decorador és universal: serveix per a funcions amb zero, tres o vint paràmetres, posicionals o amb nom. És la signatura estàndard de tot embolcall.

Hi ha un efecte secundari subtil. Un cop decorada, vendre.__name__ ja no és "vendre" sinó "embolcall", i la seva docstring — el contracte que tant hem cuidat a 08-01 — desapareix. Per al logger.exception() de M7, que registra noms de funcions, això és un problema real. functools.wraps copia la identitat de l'original a l'embolcall:

Regla sense excepcions: tot decorador porta @functools.wraps.

Després d'executar el tancament, a dades/papyrus.log apareix amb el format de M7:

El try/finally garanteix la mesura encara que tancament_de_caixa llanci: la mateixa disciplina de neteja de 07-02.

L'Anna vol poder reconstruir què s'ha venut i què ha fallat. En comptes de ficar logs dins de vendre(), s'embolica:

Una venda de Hamlet x2 deixa ok: vendre → 20.7; un intent de vendre 9 exemplars de L'Odissea amb 4 en estoc deixa la traça completa d'EstocInsuficientError. I atenció al raise nu: el decorador observa i rellança. Atrapar i silenciar aquí violaria la regla de les tres anelles de 07-04 — la decisió sobre l'excepció pertany al taulell o a la frontera, no a l'embolcall.

I si desar el catàleg falla esporàdicament (disc de xarxa, antivirus) i vols reintentar? Voldríem escriure @reintentar(cops=3). Però això vol dir que reintentar(cops=3) es crida primer i ha de retornar un decorador: és una fàbrica de decoradors. Tres nivells:

Lectura en cadena: @reintentar(cops=3) → s'executa reintentar(cops=3) → retorna decorador → decorador(desar_cataleg) → retorna embolcall → desar_cataleg = embolcall. Cada nivell és un closure: embolcall recorda alhora funcio, cops i pausa. Fixa't en la tria d'except OSError: es reintenta allò transitori; un TypeError és un bug i ha de petar a la primera (07-04).

Cap no era màgia: tots són "funció (o classe) entra, versió embolicada o transformada surt".

Un advertiment abans que decoris tota la botiga: cada decorador afegeix una capa a travessar quan depures. Si vendre porta @cronometrar, @registrar_crida i @reintentar, una traça d'error mostra tres embolcalls abans d'arribar al codi real, i l'ordre d'apilament comença a importar (s'apliquen de baix a dalt). Criteri pràctic: decora quan el comportament sigui transversal i repetit (logging, mesura, reintents); no decoris per a lògica de negoci d'una sola funció — això va dins de la funció, on es veu.

• Decorar amb parèntesis de més o de menys: @cronometrar() falla si cronometrar és un decorador simple, i @reintentar (sense parèntesis) falla si és una fàbrica. Regla: fàbrica → sempre amb parèntesis, encara que facis servir els valors per defecte (@reintentar()).
• Oblidar return funcio(...) a l'embolcall: la funció decorada passa a retornar None silenciosament. Si vendre decorada deixa de retornar la quantia, revisa l'embolcall abans que la funció.
• Oblidar @functools.wraps: els logs de 07-05 comencen a dir embolcall en comptes de vendre i la depuració es torna un laberint.
• Empassar-se excepcions al decorador: un except Exception: pass en un embolcall és el "silenci" que 07-04 va prohibir, ara camuflat. Observa, registra amb logger.exception, i rellança.
• Consell: escriu primer el decorador sense @, amb la reassignació explícita, fins que el flux et resulti obvi. El @ arriba sol.
• Consell: els embolcalls es beneficien dels type hints de 08-01 — def embolcall(*args, **kwargs) -> ... es pot anotar amb precisió fent servir typing.Callable; guarda-t'ho com a lectura opcional, encara no ho necessites.

1. Escriu @nomes_socis, un decorador per a funcions el primer argument de les quals és un codi de soci ("LLUIS-001", "MARTA-002", "PAU-003"). Si el codi no és al conjunt de socis vàlids, ha de llançar SociInvalidError(codi) sense cridar la funció; si és vàlid, la crida normalment. No oblidis functools.wraps.
2. Sense fer servir la sintaxi @, decora tancament_de_caixa amb el cronometrar de la lliçó mitjançant reassignació explícita, i explica en un comentari per què tancament_de_caixa.__name__ continua sent "tancament_de_caixa".
3. Converteix @cronometrar en una fàbrica @cronometrar(llindar=1.0) que només escrigui al log si la funció ha trigat més de llindar segons (per no omplir papyrus.log amb tancaments ràpids).

1. import functools
   from errors import SociInvalidError
   
   SOCIS_VALIDS: set[str] = {"LLUIS-001", "MARTA-002", "PAU-003"}
   
   def nomes_socis(funcio):
       @functools.wraps(funcio)
       def embolcall(codi, *args, **kwargs):
           if codi not in SOCIS_VALIDS:
               raise SociInvalidError(codi)   # guard clause de 07-03, ara reutilitzable
           return funcio(codi, *args, **kwargs)
       return embolcall
   

   L'embolcall anomena codi explícitament (el necessita per validar) i reenvia la resta amb *args, **kwargs.

2. tancament_de_caixa = cronometrar(tancament_de_caixa)
   # __name__ segueix sent "tancament_de_caixa" perque l'embolcall porta
   # @functools.wraps(funcio), que copia __name__ i la docstring de la
   # funcio original a l'embolcall abans de retornar-lo.
   

3. def cronometrar(llindar: float = 0.0):
       def decorador(funcio):
           @functools.wraps(funcio)
           def embolcall(*args, **kwargs):
               inici = time.perf_counter()
               try:
                   return funcio(*args, **kwargs)
               finally:
                   durada = time.perf_counter() - inici
                   if durada > llindar:
                       logger.info("%s ha trigat %.3f s", funcio.__name__, durada)
           return embolcall
       return decorador
   
   @cronometrar(llindar=1.0)
   def tancament_de_caixa(ruta_vendes): ...
   

   llindar viatja al closure a través dels tres nivells. Error comú aquí: deixar @cronometrar sense parèntesis — ara és fàbrica i cal cridar-la sempre.

Un decorador no té res de màgic: funcions que són objectes, closures que recorden, i una reassignació que el @ abreuja. Amb @cronometrar, @registrar_crida i @reintentar(cops=3), Papyrus afegeix mesura, auditoria i resiliència sense embrutar vendre() ni tancament_de_caixa() — i de passada @property i @dataclass han deixat de ser encanteris. Precisament en cronometrar el tancament apareix la pregunta següent: tancament_de_caixa() llegeix vendes.csv sencer per sumar-lo, i el fitxer creix cada dia. Cal carregar en memòria un any de vendes per sumar les d'avui? No: es poden produir i consumir les files sota demanda, d'una en una. Aquest és el terreny dels generadors i del yield, la propera lliçó.