functools на практике: lru_cache, cached_property, partial и singledispatch

Что это такое

functools объединяет вспомогательные средства высшего порядка. @lru_cache(maxsize=128) запоминает результат функции по её аргументам, которые должны быть хешируемыми; @cache — неограниченная форма; cache_info() возвращает попадания, промахи, maxsize и текущий размер, cache_clear() очищает кеш, а __wrapped__ даёт доступ к исходной функции. @cached_property вычисляет атрибут один раз для экземпляра и сохраняет его в словаре экземпляра. partial(f, *args, **kw) фиксирует аргументы и возвращает вызываемый объект с доступными .func, .args и .keywords. @singledispatch превращает функцию в обобщённую функцию, выбирающую реализацию по классу первого аргумента; register принимает аннотацию типа и, начиная с 3.11, Union; @singledispatchmethod выбирает по первому аргументу после self. @wraps копирует имя, строку документации и другие метаданные в обёртку декоратора.

Почему это важно

Каждое средство заменяет обычно написанный вручную код — словарь кеша уровня модуля, лямбда-адаптер, цепочку isinstance — стандартным инструментом с документированным поведением при интроспекции, работе потоков и ограничениях кеша.

Как применять

• Кешируйте только чистые функции, результат которых не зависит от времени или внешнего состояния; ограничивайте maxsize в долгоживущих процессах и читайте cache_info() в тесте, чтобы подтвердить реальные попадания в кеш.
• Не применяйте lru_cache к методам экземпляра. Python FAQ объясняет, что он создаёт ссылку на экземпляр, поэтому экземпляры остаются живы до вытеснения из кеша; для значений экземпляра без аргументов используйте cached_property, который, как отмечает FAQ, хранит результаты только пока жив экземпляр.
• Используйте partial для адаптации обратных вызовов; в отличие от лямбды, он предоставляет .func, .args и .keywords, поэтому журналы и тесты могут видеть, что было привязано.
• С singledispatch регистрируйте реализации из модулей, владеющих типами: сериализатор узнаёт о новом типе без изменения центральной функции; резервная реализация должна явно возбуждать TypeError или NotImplementedError.
• Всегда применяйте @wraps(func) в собственных декораторах, чтобы работали help(), трассировки и __wrapped__.

Подводные камни

Документация предупреждает, что разные способы передачи аргументов дают разные ключи: f(a=1, b=2) и f(b=2, a=1) могут иметь отдельные записи кеша. cached_property нужен __dict__ экземпляра, поэтому он не работает с классами __slots__; документация предлагает в этом случае поставить @property над @lru_cache. При работе потоков кешируемая функция может выполниться для тех же аргументов более одного раза до завершения первого вызова. Аннотации singledispatch должны обозначать классы (или Union классов); остальные аргументы при выборе реализации полностью игнорируются.