functools.md
1> **Источник:** https://python-all.ru/3.2/library/functools.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 9.2. [`functools`](https://python-all.ru/3.2/library/functools.html#module-functools) – функции высшего порядка и операции над вызываемыми объектами89**Исходный код:** [Lib/functools.py](https://python-all.ru/src/3.2/Lib/functools.py)1011---1213Модуль [`functools`](https://python-all.ru/3.2/library/functools.html#module-functools) предназначен для функций высшего порядка: функций, которые действуют на другие функции или возвращают их. В общем случае любой вызываемый объект может рассматриваться как функция для целей этого модуля.1415Модуль [`functools`](https://python-all.ru/3.2/library/functools.html#module-functools) определяет следующие функции:1617#### `functools.cmp_to_key(func)`1819Преобразует функцию сравнения старого образца в ключевую функцию. Используется с инструментами, которые принимают ключевые функции (такими как [`sorted()`](https://python-all.ru/3.2/library/functions.html#sorted), [`min()`](https://python-all.ru/3.2/library/functions.html#min), [`max()`](https://python-all.ru/3.2/library/functions.html#max), [`heapq.nlargest()`](https://python-all.ru/3.2/library/heapq.html#heapq.nlargest), [`heapq.nsmallest()`](https://python-all.ru/3.2/library/heapq.html#heapq.nsmallest), [`itertools.groupby()`](https://python-all.ru/3.2/library/itertools.html#itertools.groupby)). Эта функция в основном используется как средство перехода для программ, переносимых с Python 2, в котором поддерживались функции сравнения.2021Функция сравнения – это любой вызываемый объект, который принимает два аргумента, сравнивает их и возвращает отрицательное число для случая «меньше», ноль для равенства или положительное число для случая «больше». Ключевая функция – это вызываемый объект, который принимает один аргумент и возвращает другое значение, указывающее позицию в желаемой последовательности сортировки.2223Пример:2425```python26sorted(iterable, key=cmp_to_key(locale.strcoll)) # порядок сортировки с учётом локали27```2829Новое в версии 3.2.3031#### `@functools.lru_cache(maxsize=100)`3233Декоратор для обёртывания функции запоминающим вызываемым объектом, который сохраняет до *maxsize* последних вызовов. Это может сэкономить время, когда дорогостоящая или связанная с вводом-выводом функция периодически вызывается с одними и теми же аргументами.3435Поскольку для кеширования результатов используется словарь, позиционные и именованные аргументы функции должны быть хешируемыми.3637Если *maxsize* установлено в None, механизм LRU отключается, и кеш может расти без ограничений.3839Чтобы оценить эффективность кэша и настроить параметр *maxsize*, обёрнутая функция оснащается функцией `cache_info()`, которая возвращает [*именованный кортеж*](https://python-all.ru/3.2/glossary.html#term-named-tuple), показывающий *попаданий*, *промахов*, *maxsize* и *currsize*. В многопоточной среде попадания и промахи являются приблизительными.4041Декоратор также предоставляет функцию `cache_clear()` для очистки или инвалидации кэша.4243Исходная базовая функция доступна через атрибут `__wrapped__`. Это полезно для интроспекции, обхода кэша или переоборачивания функции другим кэшем.4445[LRU-кеш (least recently used – давно не использовавшийся)](https://python-all.ru/3.2/library/functools.html) лучше всего работает, когда недавние вызовы являются наилучшими предсказателями будущих вызовов (например, самые популярные статьи на новостном сервере, как правило, меняются ежедневно). Ограничение размера кеша гарантирует, что кеш не будет расти без ограничений в долго работающих процессах, таких как веб-серверы.4647Пример LRU-кэша для статического веб-контента:4849```python50@lru_cache(maxsize=20)51def get_pep(num):52 'Retrieve text of a Python Enhancement Proposal'53 resource = 'http://www.python.org/dev/peps/pep-%04d/' % num54 try:55 with urllib.request.urlopen(resource) as s:56 return s.read()57 except urllib.error.HTTPError:58 return 'Not Found'5960>>> for n in 8, 290, 308, 320, 8, 218, 320, 279, 289, 320, 9991:61... pep = get_pep(n)62... print(n, len(pep))6364>>> print(get_pep.cache_info())65CacheInfo(hits=3, misses=8, maxsize=20, currsize=8)66```6768Пример эффективного вычисления [чисел Фибоначчи](https://python-all.ru/3.2/library/functools.html) с использованием кэша для реализации техники [динамического программирования](https://python-all.ru/3.2/library/functools.html):6970```python71@lru_cache(maxsize=None)72def fib(n):73 if n < 2:74 return n75 return fib(n-1) + fib(n-2)7677>>> print([fib(n) for n in range(16)])78[0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233, 377, 610]7980>>> print(fib.cache_info())81CacheInfo(hits=28, misses=16, maxsize=None, currsize=16)82```8384Новое в версии 3.2.8586#### `@functools.total_ordering`8788Для класса, определяющего один или несколько методов расширенного сравнения, этот декоратор класса предоставляет остальные. Это упрощает задачу определения всех возможных операций расширенного сравнения:8990Класс должен определить один из методов: [`__lt__()`](https://python-all.ru/3.2/reference/datamodel.html#object.__lt__), [`__le__()`](https://python-all.ru/3.2/reference/datamodel.html#object.__le__), [`__gt__()`](https://python-all.ru/3.2/reference/datamodel.html#object.__gt__) или [`__ge__()`](https://python-all.ru/3.2/reference/datamodel.html#object.__ge__). Кроме того, класс должен предоставлять метод [`__eq__()`](https://python-all.ru/3.2/reference/datamodel.html#object.__eq__).9192Например:9394```python95@total_ordering96class Student:97 def __eq__(self, other):98 return ((self.lastname.lower(), self.firstname.lower()) ==99 (other.lastname.lower(), other.firstname.lower()))100 def __lt__(self, other):101 return ((self.lastname.lower(), self.firstname.lower()) <102 (other.lastname.lower(), other.firstname.lower()))103```104105Новое в версии 3.2.106107#### `functools.partial(func, *args, **keywords)`108109Возвращает новый объект [`partial`](https://python-all.ru/3.2/library/functools.html#functools.partial), который при вызове будет вести себя как *func*, вызванная с позиционными аргументами *args* и именованными аргументами *keywords*. Если в вызов передаётся больше аргументов, они добавляются к *args*. Если передаются дополнительные именованные аргументы, они расширяют и переопределяют *keywords*. Примерно эквивалентно:110111```python112def partial(func, *args, **keywords):113 def newfunc(*fargs, **fkeywords):114 newkeywords = keywords.copy()115 newkeywords.update(fkeywords)116 return func(*(args + fargs), **newkeywords)117 newfunc.func = func118 newfunc.args = args119 newfunc.keywords = keywords120 return newfunc121```122123[`partial()`](https://python-all.ru/3.2/library/functools.html#functools.partial) используется для частичного применения функции, которое «замораживает» некоторую часть аргументов и/или ключевых слов функции, создавая новый объект с упрощённой сигнатурой. Например, [`partial()`](https://python-all.ru/3.2/library/functools.html#functools.partial) можно использовать для создания вызываемого объекта, который ведёт себя как функция [`int()`](https://python-all.ru/3.2/library/functions.html#int), где аргумент *base* по умолчанию равен двум:124125```python126>>> from functools import partial127>>> basetwo = partial(int, base=2)128>>> basetwo.__doc__ = 'Convert base 2 string to an int.'129>>> basetwo('10010')13018131```132133#### `functools.reduce(function, iterable[, initializer])`134135Применяет *function* с двумя аргументами последовательно к элементам *sequence* слева направо, сводя последовательность к одному значению. Например, `reduce(lambda x, y: x+y, [1, 2, 3, 4, 5])` вычисляет `((((1+2)+3)+4)+5)`. Левый аргумент, *x*, является накопленным значением, а правый аргумент, *y*, – обновляемым значением из *sequence*. Если присутствует необязательный *initializer*, он помещается перед элементами последовательности в вычислении и служит значением по умолчанию, когда последовательность пуста. Если *initializer* не задан и *sequence* содержит только один элемент, возвращается первый элемент.136137#### `functools.update_wrapper(wrapper, wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)`138139Обновляет функцию-*обёртку* так, чтобы она выглядела как *обёрнутая* функция. Необязательные аргументы – кортежи, определяющие, какие атрибуты исходной функции напрямую присваиваются соответствующим атрибутам функции-обёртки и какие атрибуты функции-обёртки обновляются соответствующими атрибутами исходной функции. Значения по умолчанию для этих аргументов – константы уровня модуля *WRAPPER\_ASSIGNMENTS* (которая присваивает функции-обёртке атрибуты *\_\_name\_\_*, *\_\_module\_\_*, *\_\_annotations\_\_* и *\_\_doc\_\_*, т.е. строку документации) и *WRAPPER\_UPDATES* (которая обновляет у функции-обёртки атрибут *\_\_dict\_\_*, т.е. словарь экземпляра).140141Чтобы обеспечить доступ к исходной функции для интроспекции и других целей (например, для обхода кеширующего декоратора, такого как [`lru_cache()`](https://python-all.ru/3.2/library/functools.html#functools.lru_cache)), эта функция автоматически добавляет атрибут \_\_wrapped\_\_ к обёртке, который ссылается на исходную функцию.142143Основное назначение этой функции – использование в [*decorator*](https://python-all.ru/3.2/glossary.html#term-decorator)-функциях, которые оборачивают декорированную функцию и возвращают обёртку. Если функция-обёртка не обновляется, метаданные возвращаемой функции будут отражать определение обёртки, а не исходной функции, что обычно не очень полезно.144145[`update_wrapper()`](https://python-all.ru/3.2/library/functools.html#functools.update_wrapper) может использоваться с вызываемыми объектами, не являющимися функциями. Любые атрибуты, указанные в *assigned* или *updated*, отсутствующие у обёртываемого объекта, игнорируются (т.е. эта функция не будет пытаться установить их у функции-обёртки). [`AttributeError`](https://python-all.ru/3.2/library/exceptions.html#AttributeError) по-прежнему возбуждается, если сама функция-обёртка не имеет каких-либо атрибутов, указанных в *updated*.146147Новое в версии 3.2: Автоматическое добавление атрибута `__wrapped__`.148149Новое в версии 3.2: Копирование атрибута `__annotations__` по умолчанию.150151Изменено в версии 3.2: Отсутствующие атрибуты больше не вызывают [`AttributeError`](https://python-all.ru/3.2/library/exceptions.html#AttributeError).152153#### `@functools.wraps(wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)`154155Это удобная функция для вызова `partial(update_wrapper, wrapped=wrapped, assigned=assigned, updated=updated)` в качестве декоратора функции при определении функции-обёртки. Например:156157```python158>>> from functools import wraps159>>> def my_decorator(f):160... @wraps(f)161... def wrapper(*args, **kwds):162... print('Calling decorated function')163... return f(*args, **kwds)164... return wrapper165...166>>> @my_decorator167... def example():168... """докстринг"""169... print('Called example function')170...171>>> example()172Calling decorated function173Called example function174>>> example.__name__175'example'176>>> example.__doc__177'Docstring'178```179180Без использования этой фабрики декораторов имя примерной функции было бы `'wrapper'`, а строка документации исходной `example()` была бы потеряна.181182## 9.2.1. [`partial`](https://python-all.ru/3.2/library/functools.html#functools.partial) Объекты183184[`partial`](https://python-all.ru/3.2/library/functools.html#functools.partial) объекты – это вызываемые объекты, создаваемые с помощью [`partial()`](https://python-all.ru/3.2/library/functools.html#functools.partial). Они имеют три атрибута только для чтения:185186#### `partial.func`187188Вызываемый объект или функция. Вызовы объекта [`partial`](https://python-all.ru/3.2/library/functools.html#functools.partial) будут перенаправлены к [`func`](https://python-all.ru/3.2/library/functools.html#functools.partial.func) с новыми аргументами и ключевыми словами.189190#### `partial.args`191192Крайние слева позиционные аргументы, которые будут добавлены в начало позиционных аргументов, передаваемых при вызове объекта [`partial`](https://python-all.ru/3.2/library/functools.html#functools.partial).193194#### `partial.keywords`195196Ключевые аргументы, которые будут предоставлены, когда объект [`partial`](https://python-all.ru/3.2/library/functools.html#functools.partial) будет вызван.197198Объекты [`partial`](https://python-all.ru/3.2/library/functools.html#functools.partial) похожи на объекты `function` в том, что они являются вызываемыми, могут быть слабыми ссылками и могут иметь атрибуты. Есть несколько важных отличий. Например, атрибуты `__name__` и `__doc__` не создаются автоматически. Кроме того, объекты [`partial`](https://python-all.ru/3.2/library/functools.html#functools.partial), определённые в классах, ведут себя как статические методы и не превращаются в связанные методы при поиске атрибутов экземпляра.199