functools
— Higher-order functions and operations on callable objects¶
Вихідний код: Lib/functools.py
Модуль functools
призначений для функцій вищого порядку: функцій, які діють або повертають інші функції. Загалом, будь-який викликуваний об’єкт можна розглядати як функцію для цілей цього модуля.
Модуль functools
визначає такі функції:
-
@
functools.
cached_property
(func)¶ Перетворення методу класу на властивість, значення якого обчислюється один раз, а потім кешується як звичайний атрибут протягом життя екземпляра. Подібно до
property()
, з додаванням кешування. Корисно для дорогих обчислених властивостей екземплярів, які в іншому випадку є фактично незмінними.Приклад:
class DataSet: def __init__(self, sequence_of_numbers): self._data = sequence_of_numbers @cached_property def stdev(self): return statistics.stdev(self._data) @cached_property def variance(self): return statistics.variance(self._data)
Нове в версії 3.8.
Примітка
This decorator requires that the
__dict__
attribute on each instance be a mutable mapping. This means it will not work with some types, such as metaclasses (since the__dict__
attributes on type instances are read-only proxies for the class namespace), and those that specify__slots__
without including__dict__
as one of the defined slots (as such classes don’t provide a__dict__
attribute at all).
-
functools.
cmp_to_key
(func)¶ Перетворіть функцію порівняння старого стилю на key function. Використовується з інструментами, які приймають ключові функції (такі як
sorted()
,min()
,max()
,heapq.nlargest()
,heapq.nsmallest()
,itertools.groupby()
). Ця функція в основному використовується як інструмент переходу для програм, які перетворюються з Python 2, який підтримує використання функцій порівняння.A comparison function is any callable that accept two arguments, compares them, and returns a negative number for less-than, zero for equality, or a positive number for greater-than. A key function is a callable that accepts one argument and returns another value to be used as the sort key.
Приклад:
sorted(iterable, key=cmp_to_key(locale.strcoll)) # locale-aware sort order
Приклади сортування та короткий посібник із сортування див. Sorting HOW TO.
Нове в версії 3.2.
-
@
functools.
lru_cache
(user_function)¶ -
@
functools.
lru_cache
(maxsize=128, typed=False) Декоратор для обгортання функції викликом мемоізації, який зберігає до maxsize останніх викликів. Це може заощадити час, коли дорога функція або функція, пов’язана з вводом/виводом, періодично викликається з однаковими аргументами.
Since a dictionary is used to cache results, the positional and keyword arguments to the function must be hashable.
Distinct argument patterns may be considered to be distinct calls with separate cache entries. For example, f(a=1, b=2) and f(b=2, a=1) differ in their keyword argument order and may have two separate cache entries.
Якщо вказано user_function, вона має бути викликаною. Це дозволяє застосувати декоратор lru_cache безпосередньо до функції користувача, залишаючи значення maxsize за замовчуванням 128:
@lru_cache def count_vowels(sentence): sentence = sentence.casefold() return sum(sentence.count(vowel) for vowel in 'aeiou')
Якщо для параметра maxsize встановлено значення
None
, функція LRU вимкнена, і кеш може збільшуватися без обмежень.If typed is set to true, function arguments of different types will be cached separately. For example,
f(3)
andf(3.0)
will be treated as distinct calls with distinct results.To help measure the effectiveness of the cache and tune the maxsize parameter, the wrapped function is instrumented with a
cache_info()
function that returns a named tuple showing hits, misses, maxsize and currsize. In a multi-threaded environment, the hits and misses are approximate.Декоратор також надає функцію
cache_clear()
для очищення або анулювання кешу.Оригінальна базова функція доступна через атрибут
__wrapped__
. Це корисно для самоаналізу, для обходу кешу або для перезагортання функції в інший кеш.An LRU (least recently used) cache works best when the most recent calls are the best predictors of upcoming calls (for example, the most popular articles on a news server tend to change each day). The cache’s size limit assures that the cache does not grow without bound on long-running processes such as web servers.
In general, the LRU cache should only be used when you want to reuse previously computed values. Accordingly, it doesn’t make sense to cache functions with side-effects, functions that need to create distinct mutable objects on each call, or impure functions such as time() or random().
Приклад кешу LRU для статичного веб-контенту:
@lru_cache(maxsize=32) def get_pep(num): 'Retrieve text of a Python Enhancement Proposal' resource = 'http://www.python.org/dev/peps/pep-%04d/' % num try: with urllib.request.urlopen(resource) as s: return s.read() except urllib.error.HTTPError: return 'Not Found' >>> for n in 8, 290, 308, 320, 8, 218, 320, 279, 289, 320, 9991: ... pep = get_pep(n) ... print(n, len(pep)) >>> get_pep.cache_info() CacheInfo(hits=3, misses=8, maxsize=32, currsize=8)
Приклад ефективного обчислення чисел Фібоначчі з використанням кешу для реалізації техніки динамічного програмування:
@lru_cache(maxsize=None) def fib(n): if n < 2: return n return fib(n-1) + fib(n-2) >>> [fib(n) for n in range(16)] [0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233, 377, 610] >>> fib.cache_info() CacheInfo(hits=28, misses=16, maxsize=None, currsize=16)
Нове в версії 3.2.
Змінено в версії 3.3: Додано параметр введений.
Змінено в версії 3.8: Додано опцію user_function.
-
@
functools.
total_ordering
¶ Враховуючи клас, що визначає один або більше методів розширеного впорядкування порівняння, цей декоратор класу забезпечує решту. Це спрощує завдання, пов’язані з визначенням усіх можливих операцій розширеного порівняння:
Клас має визначати одне з
__lt__()
,__le__()
,__gt__()
або__ge__()
. Крім того, клас повинен надати метод__eq__()
.Наприклад:
@total_ordering class Student: def _is_valid_operand(self, other): return (hasattr(other, "lastname") and hasattr(other, "firstname")) def __eq__(self, other): if not self._is_valid_operand(other): return NotImplemented return ((self.lastname.lower(), self.firstname.lower()) == (other.lastname.lower(), other.firstname.lower())) def __lt__(self, other): if not self._is_valid_operand(other): return NotImplemented return ((self.lastname.lower(), self.firstname.lower()) < (other.lastname.lower(), other.firstname.lower()))
Примітка
Незважаючи на те, що цей декоратор дозволяє легко створювати повністю впорядковані типи, що добре ведуть себе, це ціна відбувається за рахунок повільнішого виконання та більш складних трасувань стека для похідних методів порівняння. Якщо порівняльний аналіз продуктивності вказує на те, що це вузьке місце для даної програми, впровадження всіх шести розширених методів порівняння натомість, ймовірно, забезпечить легке підвищення швидкості.
Нове в версії 3.2.
Змінено в версії 3.4: Returning NotImplemented from the underlying comparison function for unrecognised types is now supported.
-
functools.
partial
(func, /, *args, **keywords)¶ Повертає новий частковий об’єкт, який під час виклику поводитиметься як func, що викликається з позиційними аргументами args і ключовими аргументами keywords. Якщо до виклику надається більше аргументів, вони додаються до args. Якщо надаються додаткові ключові аргументи, вони розширюють і замінюють ключові слова. Приблизно еквівалентно:
def partial(func, /, *args, **keywords): def newfunc(*fargs, **fkeywords): newkeywords = {**keywords, **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
-
class
functools.
partialmethod
(func, /, *args, **keywords)¶ Повертає новий дескриптор
partialmethod
, який поводиться якpartial
, за винятком того, що він призначений для використання як визначення методу, а не для безпосереднього виклику.func має бути descriptor або викликаним (об’єкти, які, як і звичайні функції, обробляються як дескриптори).
Коли func є дескриптором (наприклад, звичайною функцією Python,
classmethod()
,staticmethod()
,abstractmethod()
або іншим екземпляромpartialmethod
), викликається__get__
делегуються базовому дескриптору, а в результаті повертається відповідний частковий об’єкт.Коли func є недескрипторним викликом, відповідний пов’язаний метод створюється динамічно. Це поводиться як звичайна функція Python, коли використовується як метод: аргумент self буде вставлено як перший позиційний аргумент, навіть перед args і keywords, наданими конструктору
partialmethod
.Приклад:
>>> class Cell(object): ... def __init__(self): ... self._alive = False ... @property ... def alive(self): ... return self._alive ... def set_state(self, state): ... self._alive = bool(state) ... set_alive = partialmethod(set_state, True) ... set_dead = partialmethod(set_state, False) ... >>> c = Cell() >>> c.alive False >>> c.set_alive() >>> c.alive True
Нове в версії 3.4.
-
functools.
reduce
(function, iterable[, initializer])¶ Apply function of two arguments cumulatively to the items of iterable, from left to right, so as to reduce the iterable to a single value. For example,
reduce(lambda x, y: x+y, [1, 2, 3, 4, 5])
calculates((((1+2)+3)+4)+5)
. The left argument, x, is the accumulated value and the right argument, y, is the update value from the iterable. If the optional initializer is present, it is placed before the items of the iterable in the calculation, and serves as a default when the iterable is empty. If initializer is not given and iterable contains only one item, the first item is returned.Приблизно еквівалентно:
def reduce(function, iterable, initializer=None): it = iter(iterable) if initializer is None: value = next(it) else: value = initializer for element in it: value = function(value, element) return value
Перегляньте
itertools.accumulate()
для ітератора, який видає всі проміжні значення.
-
@
functools.
singledispatch
¶ Перетворення функції на single-dispatch generic function.
To define a generic function, decorate it with the
@singledispatch
decorator. Note that the dispatch happens on the type of the first argument, create your function accordingly:>>> from functools import singledispatch >>> @singledispatch ... def fun(arg, verbose=False): ... if verbose: ... print("Let me just say,", end=" ") ... print(arg)
To add overloaded implementations to the function, use the
register()
attribute of the generic function. It is a decorator. For functions annotated with types, the decorator will infer the type of the first argument automatically:>>> @fun.register ... def _(arg: int, verbose=False): ... if verbose: ... print("Strength in numbers, eh?", end=" ") ... print(arg) ... >>> @fun.register ... def _(arg: list, verbose=False): ... if verbose: ... print("Enumerate this:") ... for i, elem in enumerate(arg): ... print(i, elem)
Для коду, який не використовує анотації типу, відповідний аргумент типу можна явно передати самому декоратору:
>>> @fun.register(complex) ... def _(arg, verbose=False): ... if verbose: ... print("Better than complicated.", end=" ") ... print(arg.real, arg.imag) ...
To enable registering lambdas and pre-existing functions, the
register()
attribute can be used in a functional form:>>> def nothing(arg, verbose=False): ... print("Nothing.") ... >>> fun.register(type(None), nothing)
The
register()
attribute returns the undecorated function which enables decorator stacking, pickling, as well as creating unit tests for each variant independently:>>> @fun.register(float) ... @fun.register(Decimal) ... def fun_num(arg, verbose=False): ... if verbose: ... print("Half of your number:", end=" ") ... print(arg / 2) ... >>> fun_num is fun False
Під час виклику загальна функція надсилає тип першого аргументу:
>>> fun("Hello, world.") Hello, world. >>> fun("test.", verbose=True) Let me just say, test. >>> fun(42, verbose=True) Strength in numbers, eh? 42 >>> fun(['spam', 'spam', 'eggs', 'spam'], verbose=True) Enumerate this: 0 spam 1 spam 2 eggs 3 spam >>> fun(None) Nothing. >>> fun(1.23) 0.615
Where there is no registered implementation for a specific type, its method resolution order is used to find a more generic implementation. The original function decorated with
@singledispatch
is registered for the baseobject
type, which means it is used if no better implementation is found.To check which implementation will the generic function choose for a given type, use the
dispatch()
attribute:>>> fun.dispatch(float) <function fun_num at 0x1035a2840> >>> fun.dispatch(dict) # note: default implementation <function fun at 0x103fe0000>
Щоб отримати доступ до всіх зареєстрованих реалізацій, використовуйте атрибут
registry
лише для читання:>>> fun.registry.keys() dict_keys([<class 'NoneType'>, <class 'int'>, <class 'object'>, <class 'decimal.Decimal'>, <class 'list'>, <class 'float'>]) >>> fun.registry[float] <function fun_num at 0x1035a2840> >>> fun.registry[object] <function fun at 0x103fe0000>
Нове в версії 3.4.
Змінено в версії 3.7: The
register()
attribute supports using type annotations.
-
class
functools.
singledispatchmethod
(func)¶ Перетворення методу на single-dispatch generic function.
To define a generic method, decorate it with the
@singledispatchmethod
decorator. Note that the dispatch happens on the type of the first non-self or non-cls argument, create your function accordingly:class Negator: @singledispatchmethod def neg(self, arg): raise NotImplementedError("Cannot negate a") @neg.register def _(self, arg: int): return -arg @neg.register def _(self, arg: bool): return not arg
@singledispatchmethod
supports nesting with other decorators such as@classmethod
. Note that to allow fordispatcher.register
,singledispatchmethod
must be the outer most decorator. Here is theNegator
class with theneg
methods being class bound:class Negator: @singledispatchmethod @classmethod def neg(cls, arg): raise NotImplementedError("Cannot negate a") @neg.register @classmethod def _(cls, arg: int): return -arg @neg.register @classmethod def _(cls, arg: bool): return not arg
The same pattern can be used for other similar decorators:
staticmethod
,abstractmethod
, and others.Нове в версії 3.8.
-
functools.
update_wrapper
(wrapper, wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)¶ Update a wrapper function to look like the wrapped function. The optional arguments are tuples to specify which attributes of the original function are assigned directly to the matching attributes on the wrapper function and which attributes of the wrapper function are updated with the corresponding attributes from the original function. The default values for these arguments are the module level constants
WRAPPER_ASSIGNMENTS
(which assigns to the wrapper function’s__module__
,__name__
,__qualname__
,__annotations__
and__doc__
, the documentation string) andWRAPPER_UPDATES
(which updates the wrapper function’s__dict__
, i.e. the instance dictionary).Щоб дозволити доступ до оригінальної функції для самоаналізу та інших цілей (наприклад, обхід декоратора кешування, такого як
lru_cache()
), ця функція автоматично додає атрибут__wrapped__
до оболонки, яка посилається на функцію, яку обгортають.Основним призначенням цієї функції є функції decorator, які обертають декоровану функцію та повертають оболонку. Якщо функція-оболонка не оновлена, метадані повернутої функції відображатимуть визначення оболонки, а не початкове визначення функції, що зазвичай не дуже корисно.
update_wrapper()
можна використовувати з іншими викликами, ніж функції. Будь-які атрибути з іменами assigned або updated, яких немає в об’єкті, що обгортається, ігноруються (тобто ця функція не намагатиметься встановити їх у функції обгортки).AttributeError
все ще виникає, якщо в самій функції-обгортки відсутні будь-які атрибути, названі в updated.Нове в версії 3.2: Automatic addition of the
__wrapped__
attribute.Нове в версії 3.2: Copying of the
__annotations__
attribute by default.Змінено в версії 3.2: Missing attributes no longer trigger an
AttributeError
.Змінено в версії 3.4: Атрибут
__wrapped__
тепер завжди посилається на обгорнуту функцію, навіть якщо ця функція визначила атрибут__wrapped__
. (див. bpo-17482)
-
@
functools.
wraps
(wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)¶ Це зручна функція для виклику
update_wrapper()
як декоратора функції під час визначення функції-огортки. Це еквівалентноpartial(update_wrapper, wrapped=wrapped, 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()
було б втрачено.
partial
Об’єкти¶
partial
об’єкти – це викликані об’єкти, створені partial()
. Вони мають три атрибути лише для читання:
-
partial.
func
¶ Викликаний об’єкт або функція. Виклики об’єкта
partial
будуть перенаправлені доfunc
з новими аргументами та ключовими словами.
-
partial.
args
¶ Крайні ліві позиційні аргументи, які будуть додані до позиційних аргументів, наданих до виклику об’єкта
partial
.
partial
objects are like function
objects in that they are
callable, weak referencable, and can have attributes. There are some important
differences. For instance, the __name__
and __doc__
attributes
are not created automatically. Also, partial
objects defined in
classes behave like static methods and do not transform into bound methods
during instance attribute look-up.