functools na prática: lru_cache, cached_property, partial e singledispatch

O que é

O functools reúne funções auxiliares de ordem superior. @lru_cache(maxsize=128) memoiza uma função com base nos argumentos, que precisam ser hashable; @cache é a variante sem limite de tamanho. cache_info() retorna hits, misses, maxsize e o tamanho atual, cache_clear() esvazia o cache e __wrapped__ dá acesso à função original. @cached_property calcula um atributo uma única vez por instância e o armazena no dicionário da instância. partial(f, *args, **kw) fixa argumentos e devolve um callable que expõe .func, .args e .keywords. @singledispatch transforma uma função em função genérica, que despacha de acordo com a classe do primeiro argumento; register aceita uma anotação de tipo e, desde a versão 3.11, também um Union; @singledispatchmethod despacha pelo primeiro argumento depois de self. @wraps copia nome, docstring e outros metadados para o wrapper de um decorador.

Por que importa

Cada uma dessas ferramentas substitui algo que normalmente se escreve à mão (um dicionário de cache no nível do módulo, um adaptador com lambda, uma cadeia de isinstance) por uma ferramenta padrão, cujo comportamento diante de introspecção, threads e limites de cache está documentado.

Como aplicar

• Faça cache apenas de funções puras, cujo resultado não dependa do tempo nem de estado externo; limite maxsize em processos de longa duração e leia cache_info() em um teste para confirmar que o cache está de fato sendo usado.
• Não use lru_cache em métodos de instância. O FAQ do Python explica que ele cria uma referência à instância, de modo que as instâncias permanecem vivas até saírem do cache por envelhecimento; para valores por instância sem argumentos, use cached_property, que, segundo o FAQ, mantém os resultados apenas enquanto a instância existir.
• Use partial para adaptar callbacks; ao contrário de um lambda, ele expõe .func, .args e .keywords, de modo que logs e testes conseguem ver o que foi fixado.
• Com singledispatch, registre as implementações a partir dos módulos que definem os tipos (um serializador passa a conhecer um novo tipo sem que a função central seja editada); a implementação de fallback deve lançar TypeError ou NotImplementedError de forma explícita.
• Aplique sempre @wraps(func) em decoradores escritos à mão, para que help(), tracebacks e __wrapped__ funcionem.

Armadilhas

A documentação alerta que padrões de argumentos diferentes são chaves diferentes: f(a=1, b=2) e f(b=2, a=1) podem ter entradas de cache separadas. cached_property precisa do __dict__ da instância e por isso não funciona em classes com __slots__; a documentação sugere, nesse caso, empilhar @property sobre @lru_cache. Com threads, a função em cache pode ser executada mais de uma vez para os mesmos argumentos antes de a primeira chamada terminar. As anotações de singledispatch devem nomear classes (ou um Union de classes); o despacho ignora completamente os demais argumentos.