functools
--- 高階関数と呼び出し可能オブジェクトの操作¶
ソースコード: Lib/functools.py
functools
モジュールは高階関数、つまり関数に影響を及ぼしたり他の関数を返したりする関数のためのものです。一般に、どんな呼び出し可能オブジェクトでもこのモジュールの目的には関数として扱えます。
モジュール functools
は以下の関数を定義します:
-
@
functools.
cache
(user_function)¶ Simple lightweight unbounded function cache. Sometimes called "memoize".
Returns the same as
lru_cache(maxsize=None)
, creating a thin wrapper around a dictionary lookup for the function arguments. Because it never needs to evict old values, this is smaller and faster thanlru_cache()
with a size limit.例えば:
@cache def factorial(n): return n * factorial(n-1) if n else 1 >>> factorial(10) # no previously cached result, makes 11 recursive calls 3628800 >>> factorial(5) # just looks up cached value result 120 >>> factorial(12) # makes two new recursive calls, the other 10 are cached 479001600
バージョン 3.9 で追加.
-
@
functools.
cached_property
(func)¶ Transform a method of a class into a property whose value is computed once and then cached as a normal attribute for the life of the instance. Similar to
property()
, with the addition of caching. Useful for expensive computed properties of instances that are otherwise effectively immutable.以下はプログラム例です:
class DataSet: def __init__(self, sequence_of_numbers): self._data = tuple(sequence_of_numbers) @cached_property def stdev(self): return statistics.stdev(self._data)
The mechanics of
cached_property()
are somewhat different fromproperty()
. A regular property blocks attribute writes unless a setter is defined. In contrast, a cached_property allows writes.The cached_property decorator only runs on lookups and only when an attribute of the same name doesn't exist. When it does run, the cached_property writes to the attribute with the same name. Subsequent attribute reads and writes take precedence over the cached_property method and it works like a normal attribute.
The cached value can be cleared by deleting the attribute. This allows the cached_property method to run again.
Note, this decorator interferes with the operation of PEP 412 key-sharing dictionaries. This means that instance dictionaries can take more space than usual.
Also, 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).If a mutable mapping is not available or if space-efficient key sharing is desired, an effect similar to
cached_property()
can be achieved by a stackingproperty()
on top ofcache()
:class DataSet: def __init__(self, sequence_of_numbers): self._data = sequence_of_numbers @property @cache def stdev(self): return statistics.stdev(self._data)
バージョン 3.8 で追加.
-
functools.
cmp_to_key
(func)¶ 古いスタイルの比較関数を key function に変換します。key 関数を受け取るツール (
sorted()
,min()
,max()
,heapq.nlargest()
,heapq.nsmallest()
,itertools.groupby()
など) と共に使用します。この関数は、主に比較関数を使っていた Python 2 からプログラムの移行のための変換ツールとして使われます。比較関数は2つの引数を受け取り、それらを比較し、 "より小さい" 場合は負の数を、同値の場合には 0 を、 "より大きい" 場合には正の数を返す、あらゆる呼び出し可能オブジェクトです。key 関数は呼び出し可能オブジェクトで、1つの引数を受け取り、ソートキーとして使われる値を返します。
以下はプログラム例です:
sorted(iterable, key=cmp_to_key(locale.strcoll)) # locale-aware sort order
ソートの例と簡単なチュートリアルは ソート HOW TO を参照して下さい。
バージョン 3.2 で追加.
-
@
functools.
lru_cache
(user_function)¶ -
@
functools.
lru_cache
(maxsize=128, typed=False) 関数をメモ化用の呼び出し可能オブジェクトでラップし、最近の呼び出し最大 maxsize 回まで保存するするデコレータです。高価な関数や I/O に束縛されている関数を定期的に同じ引数で呼び出すときに、時間を節約できます。
結果のキャッシュには辞書が使われるので、関数の位置引数およびキーワード引数はハッシュ可能でなくてはなりません。
引数のパターンが異なる場合は、異なる呼び出しと見なされ別々のキャッシュエントリーとなります。 例えば、 f(a=1, b=2) と f(b=2, a=1) はキーワード引数の順序が異なっているので、2つの別個のキャッシュエントリーになります。
If user_function is specified, it must be a callable. This allows the lru_cache decorator to be applied directly to a user function, leaving the maxsize at its default value of 128:
@lru_cache def count_vowels(sentence): sentence = sentence.casefold() return sum(sentence.count(vowel) for vowel in 'aeiou')
If maxsize is set to
None
, the LRU feature is disabled and the cache can grow without bound.typed が真に設定された場合は、関数の異なる型の引数が別々にキャッシュされます。例えば、
f(3)
とf(3.0)
は別の結果をもたらす別の呼び出しとして扱われます。The wrapped function is instrumented with a
cache_parameters()
function that returns a newdict
showing the values for maxsize and typed. This is for information purposes only. Mutating the values has no effect.キャッシュ効率の測定や maxsize パラメータの調整をしやすくするため、ラップされた関数には
cache_info()
関数が追加されます。この関数は hits, misses, maxsize, currsize を示す named tuple を返します。マルチスレッド環境では、hits と misses は概算です。このデコレータは、キャッシュの削除と無効化のための
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.
一般的には、 LRU キャッシュは前回計算した値を再利用したいときにのみ使うべきです。 そのため、副作用のある関数、呼び出すごとに個別の可変なオブジェクトを作成する必要がある関数、 time() や random() のような純粋でない関数をキャッシュする意味はありません。
静的 web コンテンツ の 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 で変更: typed オプションが追加されました。
バージョン 3.8 で変更: Added the user_function option.
バージョン 3.9 で追加: Added the function
cache_parameters()
-
@
functools.
total_ordering
¶ ひとつ以上の拡張順序比較メソッド (rich comparison ordering methods) を定義したクラスを受け取り、残りを実装するクラスデコレータです。このデコレータは全ての拡張順序比較演算をサポートするための労力を軽減します:
引数のクラスは、
__lt__()
,__le__()
,__gt__()
,__ge__()
の中からどれか1つと、__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()))
注釈
このデコレータにより、完全に順序の付いた振る舞いの良い型を簡単に作ることができますが、実行速度は遅くなり、派生した比較メソッドのスタックトレースは複雑になります。性能ベンチマークにより、これがアプリケーションのボトルネックになっていることがわかった場合は、代わりに 6 つの拡張比較メソッドをすべて実装すれば、簡単にスピードアップを図れるでしょう。
バージョン 3.2 で追加.
バージョン 3.4 で変更: 認識できない型に対して下層の比較関数から NotImplemented を返すことがサポートされるようになりました。
-
functools.
partial
(func, /, *args, **keywords)¶ 新しい partial オブジェクト を返します。このオブジェクトは呼び出されると位置引数 args とキーワード引数 keywords 付きで呼び出された func のように振る舞います。呼び出しに際してさらなる引数が渡された場合、それらは args に付け加えられます。追加のキーワード引数が渡された場合には、それらで keywords を拡張または上書きします。おおよそ次のコードと等価です:
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()
を使って base 引数のデフォルトが 2 であるint()
関数のように振る舞う呼び出し可能オブジェクトを作ることができます:>>> 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)¶ partial
と似た動作をする新しいpartialmethod
記述子 (デスクリプタ) を返します。直接呼び出しではなく、メソッド定義としての使用が目的であることのみが、partial とは異なります。func は、descriptor または呼び出し可能オブジェクトである必要があります (通常の関数など、両方の性質を持つオブジェクトは記述子として扱われます。)
func が記述子 (Python の通常の関数、
classmethod()
、staticmethod()
、abstractmethod()
または別のpartialmethod
のインスタンスなど) の場合、__get__
への呼び出しは下層の記述子に委譲され、返り値として適切な partial オブジェクト が返されます。func が記述子以外の呼び出し可能オブジェクトである場合、適切な束縛メソッドが動的に作成されます。この func は、メソッドとして使用された場合、Python の通常の関数と同様に動作します。
partialmethod
コンストラクタに args と keywords が渡されるよりも前に、 self 引数が最初の位置引数として挿入されます。以下はプログラム例です:
>>> class Cell: ... 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
See
itertools.accumulate()
for an iterator that yields all intermediate values.
-
@
functools.
singledispatch
¶ 関数を シングルディスパッチ ジェネリック関数 に変換します。
ジェネリック関数を定義するには、
@singledispatch
デコレータを付けます。ディスパッチは 1 つ目の引数の型で行われることに注意して、関数を次のように作成してください:>>> from functools import singledispatch >>> @singledispatch ... def fun(arg, verbose=False): ... if verbose: ... print("Let me just say,", end=" ") ... print(arg)
関数にオーバーロード実装を追加するには、ジェネリック関数の
register()
属性を使用します。 この属性はデコレータです。 型アノテーションが付いている関数については、このデコレータは1つ目の引数の型を自動的に推測します。>>> @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) ...
register()
属性を関数形式で使用すると、lambda 関数と既存の関数の登録を有効にできます:>>> 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
汎用関数は、呼び出されると 1 つ目の引数の型でディスパッチします:
>>> 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
特定の型について登録された実装が存在しない場合、その型のメソッド解決順序が、汎用の実装をさらに検索するために使用されます。
@singledispatch
でデコレートされた元の関数は基底のobject
型に登録されます。これは、他によりよい実装が見つからないことを意味します。If an implementation registered to abstract base class, virtual subclasses will be dispatched to that implementation:
>>> from collections.abc import Mapping >>> @fun.register ... def _(arg: Mapping, verbose=False): ... if verbose: ... print("Keys & Values") ... for key, value in arg.items(): ... print(key, "=>", value) ... >>> fun({"a": "b"}) a => b
指定された型に対して、汎用関数がどの実装を選択するかを確認するには、
dispatch()
属性を使用します:>>> 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 で変更:
register()
属性が型アノテーションの使用をサポートするようになりました。
-
class
functools.
singledispatchmethod
(func)¶ Transform a method into a 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)¶ wrapper 関数を wrapped 関数に見えるようにアップデートします。オプション引数はタプルで、元の関数のどの属性がラッパー関数の対応する属性に直接代入されるか、またラッパー関数のどの属性が元の関数の対応する属性でアップデートされるか、を指定します。これらの引数のデフォルト値は、モジュールレベル定数
WRAPPER_ASSIGNMENTS
(これはラッパー関数の__module__
,__name__
,__qualname__
,__annotations__
そしてドキュメンテーション文字列__doc__
に代入する) とWRAPPER_UPDATES
(これはラッパー関数の__dict__
すなわちインスタンス辞書をアップデートする) です。内観や別の目的 (例えば、
lru_cache()
のようなキャッシュするデコレータの回避) のために元の関数にアクセスできるように、この関数はラップされている関数を参照するラッパーに自動的に__wrapped__
属性を追加します。この関数は主に関数を包んでラッパーを返す デコレータ 関数の中で使われるよう意図されています。もしラッパー関数がアップデートされないとすると、返される関数のメタデータは元の関数の定義ではなくラッパー関数の定義を反映してしまい、これは通常あまり有益ではありません。
update_wrapper()
は、関数以外の呼び出し可能オブジェクトにも使えます。 assigned または updated で指名され、ラップされるオブジェクトに存在しない属性は、すべて無視されます (すなわち、ラッパー関数にそれらの属性を設定しようとは試みられません)。しかし、 updated で指名された属性がラッパー関数自身に存在しないならAttributeError
が送出されます。バージョン 3.2 で追加:
__wrapped__
属性の自動的な追加。バージョン 3.2 で追加: デフォルトで
__annotations__
属性がコピーされます。バージョン 3.2 で変更: 存在しない属性によって
AttributeError
を発生しなくなりました。バージョン 3.4 で変更: ラップされた関数が
__wrapped__
を定義していない場合でも、__wrapped__
が常にラップされた関数を参照するようになりました。(bpo-17482 を参照)
-
@
functools.
wraps
(wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)¶ これはラッパー関数を定義するときに
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()
のドキュメンテーション文字列は失われてしまいます。