functools — Функции высшего порядка и операции над вызываемыми объектами

Исходный код: Lib/functools.py

Модуль functools предназначен для функций высшего порядка: функций, которые действуют на или возвращают другие функции. В общем случае любой вызываемый объект может рассматриваться как функция для целей данного модуля.

Модуль functools определяет следующие функции:

functools.cmp_to_key(func)

Преобразование функции сравнения старой версии в функцию функцию-ключ. Используется с инструментами, принимающими функции-ключи (такими как sorted(), min(), max(), heapq.nlargest(), heapq.nsmallest(), itertools.groupby()). Эта функция в основном используется как инструмент перехода для программ, которые конвертируются в Python 3, где функции сравнения больше не поддерживаются.

Функция сравнения — это любая вызываемая функция, которая принимает два аргумента, сравнивает их и возвращает отрицательное число для «меньше», ноль для «равно» или положительное число для «больше». Функция-ключ — это вызываемая функция, которая принимает один аргумент и возвращает другое значение, используемое в качестве ключа сортировки.

Пример:

sorted(iterable, key=cmp_to_key(locale.strcoll))  # locale-aware sort order

Примеры сортировки и краткое руководство по сортировке см. в Руководстве по сортировке.

Новая в версии 2.7.

functools.total_ordering(cls)

Для класса, определяющего один или несколько методов упорядочения сравнения, этот декоратор класса предоставляет остальные. Это упрощает задачу определения всех возможных операций богатого сравнения:

Класс должен определить один из __lt__(), __le__(), __gt__() или __ge__(). Кроме того, класс должен предоставить метод __eq__().

Например:

@total_ordering
class Student:
    def __eq__(self, other):
        return ((self.lastname.lower(), self.firstname.lower()) ==
                (other.lastname.lower(), other.firstname.lower()))
    def __lt__(self, other):
        return ((self.lastname.lower(), self.firstname.lower()) <
                (other.lastname.lower(), other.firstname.lower()))

Новая в версии 2.7.

functools.reduce(function, iterable[, initializer])

Эта функция такая же, как и reduce(). Она доступна в этом модуле, чтобы позволить писать код, более совместимый с Python 3.

Новая в версии 2.6.

functools.partial(func[,*args][, **keywords])

Возвращает новый объект partial, который при вызове будет вести себя как func, вызванный с позиционными аргументами args и именованными аргументами keywords. Если предоставлены дополнительные аргументы, они добавляются к args. Если предоставлены дополнительные именованные аргументы, они расширяют и переопределяют keywords. Примерно эквивалентно:

def partial(func, *args, **keywords):
    def newfunc(*fargs, **fkeywords):
        newkeywords = keywords.copy()
        newkeywords.update(fkeywords)
        return func(*(args + fargs), **newkeywords)
    newfunc.func = func
    newfunc.args = args
    newfunc.keywords = keywords
    return newfunc

Объект partial() используется для частичного применения функций, «замораживая» часть аргументов и/или именованных аргументов функции, что приводит к новому объекту с упрощенной сигнатурой. Например, partial() можно использовать для создания вызываемого объекта, который ведет себя как функция int(), где аргумент base по умолчанию равен двум:

>>> from functools import partial
>>> basetwo = partial(int, base=2)
>>> basetwo.__doc__ = 'Convert base 2 string to an int.'
>>> basetwo('10010')
18

functools.update_wrapper(wrapper, wrapped[, assigned][, updated])

Обновление функции-обертки, чтобы она выглядела как функция-обертываемый объект. Дополнительные аргументы — это кортежи, которые указывают, какие атрибуты исходной функции должны быть присвоены напрямую соответствующим атрибутам функции-обертки, а какие атрибуты функции-обертки должны быть обновлены соответствующими атрибутами исходной функции. Значения по умолчанию для этих аргументов — константы уровня модуля WRAPPER_ASSIGNMENTS (которая присваивает функции-обертке __name__, __module__ и __doc__, строку документации) и WRAPPER_UPDATES (которая обновляет словарь экземпляра функции-обертки __dict__).

Основное предполагаемое использование этой функции — в функциях-декораторах, которые обертывают декорируемую функцию и возвращают функцию-обертку. Если функция-обертка не обновляется, метаданные возвращаемой функции будут отражать определение функции-обертки, а не определение исходной функции, что обычно менее полезно.

functools.wraps(wrapped[, assigned][, updated])

Это вспомогательная функция для вызова update_wrapper() в качестве декоратора функции при определении функции-обертки. Она эквивалентна partial(update_wrapper, wrapped=wrapped, assigned=assigned, updated=updated). Например:

>>> from functools import wraps
>>> def my_decorator(f):
...     @wraps(f)
...     def wrapper(*args, **kwds):
...         print 'Calling decorated function'
...         return f(*args, **kwds)
...     return wrapper
...
>>> @my_decorator
... def example():
...     """Docstring"""
...     print 'Called example function'
...
>>> example()
Calling decorated function
Called example function
>>> example.__name__
'example'
>>> example.__doc__
'Docstring'

Без использования этой фабрики декораторов имя функции-примера было бы 'wrapper', и строка документации исходной функции example() была бы потеряна.

1. Объекты partial

partial — это вызываемые объекты, созданные с помощью partial(). У них есть три только для чтения атрибута:

partial.func

Вызываемый объект или функция. Вызовы объекта partial будут перенаправлены в func с новыми аргументами и именованными аргументами.

partial.args

Позиционные аргументы, которые будут добавлены перед позиционными аргументами, предоставленными при вызове объекта partial.

partial.keywords

Именованные аргументы, которые будут предоставлены при вызове объекта partial.

Объекты partial похожи на объекты function, поскольку они вызываемые, поддерживают слабые ссылки и могут иметь атрибуты. Существуют некоторые важные различия. Например, атрибуты __name__ и __doc__ не создаются автоматически. Кроме того, объекты partial, определенные в классах, ведут себя как статические методы и не преобразуются в связанные методы во время поиска атрибутов экземпляра.