functools en la práctica: lru_cache, cached_property, partial y singledispatch

Qué es

functools agrupa utilidades de orden superior. @lru_cache(maxsize=128) memoiza una función en función de sus argumentos, que deben ser hashables; @cache es la variante sin límite de tamaño; cache_info() devuelve aciertos (hits), fallos (misses), maxsize y el tamaño actual, cache_clear() vacía la cache y __wrapped__ da acceso a la función original. @cached_property calcula un atributo una sola vez por instancia y lo almacena en el diccionario de la instancia. partial(f, *args, **kw) fija argumentos y devuelve un objeto invocable que expone .func, .args y .keywords. @singledispatch convierte una función en una función genérica que despacha según la clase de su primer argumento; register acepta una anotación de tipo y, desde la versión 3.11, también un Union; @singledispatchmethod despacha según el primer argumento posterior a self. @wraps copia el nombre, la docstring y otros metadatos al wrapper de un decorador.

Por qué importa

Cada una de estas herramientas sustituye algo que se suele escribir a mano (un diccionario de cache a nivel de módulo, un adaptador con lambda, una cadena de isinstance) por una herramienta estándar cuyo comportamiento ante la introspección, los hilos y los límites de cache está documentado.

Cómo aplicarlo

• Almacena en cache solo funciones puras cuyo resultado no dependa del tiempo ni de un estado externo; limita maxsize en procesos de larga duración y consulta cache_info() en una prueba para confirmar que la cache realmente se aprovecha.
• No uses lru_cache en métodos de instancia. Las preguntas frecuentes (FAQ) de Python explican que crea una referencia a la instancia, de modo que las instancias siguen vivas hasta que la cache las expulsa por antigüedad; para valores por instancia que no dependen de argumentos usa cached_property, que según la FAQ conserva los resultados solo mientras viva la instancia.
• Usa partial para adaptar callbacks; a diferencia de una lambda, expone .func, .args y .keywords, de modo que los logs y las pruebas pueden ver qué se ha fijado.
• Con singledispatch, registra las implementaciones desde los módulos propietarios de los tipos (un serializador aprende a manejar un tipo nuevo sin editar la función central); la implementación por defecto debería lanzar de forma explícita TypeError o NotImplementedError.
• Aplica siempre @wraps(func) en los decoradores escritos a mano para que help(), los tracebacks y __wrapped__ funcionen correctamente.

Trampas

La documentación advierte de que los patrones de argumentos distintos son claves distintas: f(a=1, b=2) y f(b=2, a=1) pueden tener entradas de cache separadas. cached_property necesita un __dict__ de instancia, por lo que no funciona en clases con __slots__; en ese caso la documentación sugiere apilar @property sobre @lru_cache. Con hilos, la función en cache puede ejecutarse más de una vez con los mismos argumentos antes de que termine la primera llamada. Las anotaciones de singledispatch deben nombrar clases (o un Union de clases); el despacho ignora por completo los demás argumentos.