# `functools` --- 高階関数と呼び出し可能オブジェクトの操作

ソースコード: Lib/functools.py

`functools` モジュールは高階関数、つまり関数に影響を及ぼしたり他の関数を返したりする関数のためのものです。一般に、どんな呼び出し可能オブジェクトでもこのモジュールの目的には関数として扱えます。

モジュール `functools` は以下の関数を定義します:

`@``functools.``cached_property`(func)

  クラスのメソッドを、値を一度だけ計算して通常の属性としてキャッシュするプロパティに変換します。キャッシュはインスタンスの生存期間にわたって有効です。計算コストが高く、一度計算すればその後は不変であるようなインスタンスのプロパティに対して有用です。

  以下はプログラム例です:

      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 に変換します。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つの別個のキャッシュエントリーになります。

  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 機能は無効化され、キャッシュは際限無く大きくなります。

  typed が真に設定された場合は、関数の異なる型の引数が別々にキャッシュされます。例えば、`f(3)` と `f(3.0)` は別の結果をもたらす別の呼び出しとして扱われます。

  キャッシュ効率の測定や maxsize パラメータの調整をしやすくするため、ラップされた関数には `cache_info()` 関数が追加されます。この関数は hits, misses, maxsize, currsize を示す named tuple を返します。マルチスレッド環境では、hits と misses は概算です。

  このデコレータは、キャッシュの削除と無効化のための `cache_clear()` 関数も提供します。

  元々の基底の関数には、 `__wrapped__` 属性を通してアクセスできます。これはキャッシュを回避して、または関数を別のキャッシュでラップして、内観するのに便利です。

  LRU (least recently used) キャッシュ は、最新の呼び出しが次も呼び出される可能性が最も高い場合 (例えば、ニュースサーバーの最も人気のある記事は、毎日変わる傾向にあります) に最も効率が良くなります。キャッシュのサイズ制限は、キャッシュがウェブサーバーなどの長期間に渡るプロセスにおける限界を超えては大きくならないことを保証します。

  一般的には、 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 で変更: user_function オプションが追加されました。

`@``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(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])

  iterable の要素に対して、iterable を単一の値に短縮するような形で 2 つの引数をもつ function を左から右に累積的に適用します。例えば、 `reduce(lambda x, y: x+y, [1, 2, 3, 4, 5])` は `((((1+2)+3)+4)+5)` を計算します。左引数 x は累計の値になり、右引数 y は `iterable` から取り出した更新値になります。オプションの initializer が存在する場合、計算の際に iterable の先頭に置かれます。また、 iterable が空の場合には標準の値になります。 initializer が与えられておらず、 iterable が単一の要素しか持っていない場合、最初の要素が返されます。

  およそ次と等価です:

      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`

  関数を シングルディスパッチ ジェネリック関数 に変換します。

  ジェネリック関数を定義するには、 `@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` 型に登録されます。これは、他によりよい実装が見つからないことを意味します。

  指定された型に対して、汎用関数がどの実装を選択するかを確認するには、`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)

  メソッドを シングルディスパッチ ジェネリック関数 に変換します。

  ジェネリックメソッドを定義するには、 `@singledispatchmethod` デコレータを付けます。ディスパッチは 1 つ目の引数の型で行われることに注意して、関数を次のように作成してください:

      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 for `dispatcher.register`, `singledispatchmethod` must be the outer most decorator. Here is the `Negator` class with the `neg` 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()` のドキュメンテーション文字列は失われてしまいます。

## `partial` オブジェクト

`partial` オブジェクトは、 `partial()` 関数によって作られる呼び出し可能オブジェクトです。オブジェクトには読み出し専用の属性が三つあります:

`partial.``func`

  呼び出し可能オブジェクトまたは関数です。 `partial` オブジェクトの呼び出しは新しい引数とキーワードと共に `func` に転送されます。

`partial.``args`

  最左の位置引数で、 `partial` オブジェクトの呼び出し時にその呼び出しの際の位置引数の前に追加されます。

`partial.``keywords`

  `partial` オブジェクトの呼び出し時に渡されるキーワード引数です。

`partial` オブジェクトは `function` オブジェクトのように呼び出し可能で、弱参照可能で、属性を持つことができます。重要な相違点もあります。例えば、 `__name__` と `__doc__` 両属性は自動では作られません。また、クラス中で定義された `partial` オブジェクトはスタティックメソッドのように振る舞い、インスタンスの属性問い合わせの中で束縛メソッドに変換されません。