Funkycache: SQLiteで関数をキャッシュするPythonライブラリ
Funkycache: A Python library to cache functions in SQLite (alexwlchan.net)
要約
この記事では、Pythonで関数呼び出しの結果をSQLiteデータベースにキャッシュする新しいライブラリ「funkycache」を紹介しています。funkycacheは、関数の引数をキーとして、実行結果を保存し、次回以降の呼び出しで再計算をスキップすることで、処理の高速化を図ります。ソースコードの変更や依存値の更新を検知してキャッシュを無効化する機能も備えています。
全文翻訳
funkycache: SQLiteで関数をキャッシュするPythonライブラリ
6ヶ月前、私はこのサイトのビルドシステムを高速化するために、SQLiteベースのキャッシュを作成しました。静的サイトジェネレーターはキャッシュの理想的な候補です。なぜなら、決定論的な振る舞いを持ち、副作用のないステップがたくさんあるからです。数百ページを持つサイトでは、ステップごとに数ミリ秒の節約でも、意味のある改善につながります。
最初のキャッシュはかなり基本的なものでした。名前空間とキーを指定して文字列を取得・設定する機能があり、それ以上の機能はありませんでした。
from mosaic.cache import SQLiteCache
cache = SQLiteCache("example.db")
cache.set(namespace="fibonacci", key="10", value="55")
print(cache.get(namespace="fibonacci", key="10"))
これはキャッシュの価値を示しましたが、提供したのはキャッシュのストレージであり、キャッシュのロジックではありませんでした。関数をキャッシュしたい場合、値をキャッシュに保存し、後で取得するための関数ごとのロジックを自分で書く必要がありました。そのコードの多くはテストが難しく、微妙なバグがありました。私はこのコードに自信が持てず、公開用にサイトをビルドするたびにキャッシュを削除していました。
もっと良いものが欲しかったので、先週、私のキャッシュロジックをすべてカプセル化し、はるかに使いやすくテストしやすくした新しいライブラリfunkycacheを作成しました。任意のPythonオブジェクトを入力と出力の両方として格納でき、呼び出し元にとってインターフェースははるかにシンプルです。
関数をキャッシュするには、FunkyCacheインスタンスを作成し、関数にデコレーターを追加します。
from funkycache import FunkyCache
cache = FunkyCache(storage="sqlite")
@cache.register
def expensive_function(arg1: str, arg2: int, arg3: date) -> tuple[str, date]:
...
これは標準ライブラリのfunctools.cacheに似ています。高コストな関数の出力はSQLiteデータベースに書き込まれるため、Pythonプロセスが終了した後も利用可能です。
キャッシュは無効化に関して賢くあろうとします。expensive_functionを含むソースファイルが変更された場合、その関数のキャッシュは無効化され、次回の呼び出し時に再構築されます。
他のファイルや静的な値への依存関係を指定することもできます。これらの変更もキャッシュの無効化を引き起こします。
from funkycache import FunkyCache
cache = FunkyCache(storage="sqlite")
@cache.register(
files=["data/input.yml", "templates/example.html"],
values=[pygments.__version__],
)
def expensive_function(arg1: str, arg2: int, arg3: datetime) -> tuple[str, datetime]:
...
funkycacheを開発するにあたり、1週間かけてキャッシュロジックについて深く考え、徹底的にテストし、その後数ヶ月は考えないようにしたいと思っていました。funkycacheは、その仕組みを理解しなくても使用できるはずです。もし理解したいのであれば、それがこの記事の残りの部分で説明することです。
自分で試してみたい場合は、funkycacheはPyPIにあり、ソースコードはこのウェブサイトにあります。
目次
キャッシュキーは関数引数をハッシュ化・JSONエンコードしたもの
関数の引数をすべて取得する
このキャッシュは、与えられた入力に対して常に同じ出力を生成する関数を対象としています。そのため、入力がキャッシュキーとなります。関数をデコレートする際に、各呼び出しで渡される引数を確認できます。
from functools import wraps
def my_decorator(func):
@wraps(func)
def wrapper(*args, **kwargs):
print({"args": args, "kwargs": kwargs})
return func(*args, **kwargs)
return wrapper
これは、同じ関数を異なるスタイルで呼び出す場合(例えば、位置引数とキーワード引数、デフォルト引数の省略や上書きなど)を考慮していません。
完全で一貫した引数のセットを取得するために、inspectモジュールを使用します。
import inspect
sig = inspect.signature(func)
bound = sig.bind(*args, **kwargs)
bound.apply_defaults()
cache_key = bound.arguments # {"arg1": val1, "arg2": val2, ...}
これにより、関数の完全な引数のPython辞書が得られ、呼び出しスタイルに関係なく同じになります。
引数をJSONに変換する
Pythonの辞書はハッシュ可能ではないため、辞書のキーとして、またSQLiteデータベースのキーとしても使用できません。これらを文字列またはバイトシーケンスとしてシリアライズする必要があります。
このシリアライズには、pickleとJSONの2つのオプションを検討しました。私の限定的なテストでは、JSONはpickleよりも高速だったので、JSONを選択しました。JSONを使用することで、シリアライズを高速化するための柔軟性も得られました。
最初のシリアライズは、単純なjson.dumps呼び出しで、順序の一貫性を確保し、標準ライブラリがエンコード方法を知らない型を処理するためのいくつかのオプションを追加しました。
json_key = json.dumps(cache_key, sort_keys=True, default=str)
funkycacheを使い始めたとき、このエンコードステップはすぐに最も遅い部分であることが判明したため、このステップを高速化するために引数を「削減」し始めました。この削減には以下が含まれます。
- 関数引数を再帰的にウォークし、大きな文字列をハッシュ化する
- Pydanticを使用して、Pydanticモデルやdataclassesを文字列変換ではなくPythonオブジェクトに変換する
- コードをリファクタリングして、各関数が最小限の必須データのみを受け取るようにする
これらはすべてロスのある変換ですが、キャッシュキーとしては問題ありません。元の値を取得する必要は決してないからです。理論的には異なる値が衝突するハッシュキーを取得する可能性がありますが、私の規模では可能性は低いです。(私のサイトのクリーンビルドでは32,000キーしか使用しません。)
より小さなキーのためのハッシュ化
私の静的サイトジェネレーターの関数は、記事のコンテンツのようなものを処理するため、個々の関数引数はキロバイト単位になる可能性があります。SQLiteでマルチキロバイトのキーを使用することは可能ですが、おそらく避けるべきです。大きなキーではパフォーマンスが低下します。
私は3つのアプローチを比較するために小さなベンチマークを作成しました。JSONエンコードされた引数を直接格納する、MD5でハッシュ化する、XXH64でハッシュ化する、というものです。結果は小さなキーサイズでは大差ありませんでしたが、大きなキーではXXH64が大幅に高速になり、MD5はSQLiteに直接キーを格納するよりも遅くなりました。
[画像: Graph comparing the insert/lookup performance of identity, MD5 and XXH64]
このベンチマークに基づき、funkycacheはJSONキャッシュキーをXXH64でハッシュ化してからSQLiteに挿入します。
xxHashアルゴリズム群は、このプロジェクト中に私にとって嬉しい発見でした。それらは暗号学的に安全であることではなく、高速であることを意図して設計されています。以前はMD5をこの目的で使用していましたが、それは広く利用可能であり、「弱い」と「高速」を混同していました。実際にベンチマークを実行したことで、私の間違いが明らかになりました。
キャッシュ値はJSONエンコードされる
キャッシュキーのシリアライズは一方通行の操作ですが、キャッシュされた値は取得可能である必要があります。このために、inspectモジュールを使用してキャッシュされた関数から戻り値の型を取得し、Pydanticにシリアライズを任せます。
import inspect
import pydantic
# 関数の戻り値の型を取得します。
sig = inspect.signature(func)
return_type = sig.ret_annotation
# PydanticのTypeAdapterを作成します
adapter = TypeAdapter(return_type)
# JSONとしてシリアライズします
json_str = adapter.dumper_json(value)
# JSONからデシリアライズします
retrieved_value = adapter.validate_json(stored_value)
私はPythonすべてに型ヒントと型アノテーションを使用しているため、この情報は必ず存在します。型指定のないPythonでは機能しませんが、私には十分です。
代替案はpickleを使用することです。これは任意のPythonオブジェクトを格納できます。セキュリティリスクを気にする必要はありません。なぜなら、信頼できるデータのみをpickle/unpickleするためですが、キャッシュキーのためにすでにJSONを使用しており、デバッグが容易なため、JSONを使い続けました。
遅延ジェネレーターのキャッシュ
キャッシュしたい関数の一つに遅延ジェネレーターがあり、これは少しトリッキーでした。
functools.cacheを使用すると、ジェネレーターオブジェクトがキャッシュされるため、すべての呼び出しが同じジェネレーターインスタンスを取得し、それらがすべて一緒にステップします。これは潜在的に混乱を招くと思われます。
import functools
@functools.cache
def even_numbers():
for i in range(10):
yield i * 2
n1 = even_numbers()
n2 = even_numbers()
print(next(n1)) # 0
print(next(n1)) # 2
print(next(n2)) # 4
funkycacheは異なるアプローチを取ります。ジェネレーターをリストに具体化し、そのリストを格納します。取得されるとき、リストはiterでラップすることによってジェネレーターに変換されます。
大きなまたは無限のジェネレーターによる無制限のメモリ使用を防ぐために、ソフトメモリバジェットがあります。具体化されたリストがこのバジェットを超えた場合、リストへの出力の収集を停止し、キャッシュに何も保存しません。リストとそれに続く生成されたアイテムは、元の関数から呼び出し元に直接渡されます。
依存関係の追跡
依存ファイル
私の静的サイトジェネレーターの一部の関数は、テンプレートファイルの内容に依存しています。それらのファイルが変更された場合、キャッシュを無効化し、それらのテンプレートを使用したページを再構築したいと考えています。
関数をfunkycacheに登録する際に、依存するファイルまたはフォルダのリストを指定できます。
@cache.register(files=["mosaic/text", "templates"])
def render_html(content: str, content_vars: dict[str, Any],) -> str:
...
funkycacheは、それらの各ファイルのコンテンツを読み取り、キャッシュキーに含めます。ファイルが変更されると、ファイルのリストを再評価し、キャッシュを保持するか無効化するかを決定します。
funkycache自体にファイル変更追跡を実装しないことにしました。私はすでにそのためのコードを持っていますし、このプロジェクトを小さく集中させたいと思いました。
依存値
関数のキャッシュは、静的な値に基づいても構いません。私はこれを重要なライブラリのバージョンを含めるために使用しており、ライブラリを更新するとキャッシュが無効化されます。以下に短い例を示します。
import pygments
@cache.register(values=[pygments.__version__])
def apply_syntax_highlighting(src: str, lang: str) -> str:
...
リアクティブな野心
このプロジェクトは、リアクティブプログラミングについて考えていたことから始まりました。
リアクティブプログラミングは、スプレッドシートを使用するのに似ています。入力セルがあり、そこにデータを入力し、他のセルがそのデータを読み取って入力が変更されると自動的に更新されます。それらのセルは他のセルの入力になることができ、その逆も同様です。
静的サイトを構築することを想像してください。Markdownファイルは入力セルとして機能し、レンダリングされたHTMLページは依存セルです。タスクは有向非巡回グラフ(DAG)を形成し、更新はグラフ全体に伝播します。
[画像: Flow chart showing the build dependencies of three Markdown articles (inputs), three HTML pages that depend on them, and a list of articles that depend on all three HTML pages]
例えば、上記の図では、article1.mdが変更されると、システムはarticle1.htmlを再構築する必要があることを認識し、その更新をlist_of_articles.htmlに波及させます。しかし、入力に変更がないため、記事2と3をレンダリングするタスクはまったく実行されません。
正しく行われた場合、これは非常に効率的なプログラミングスタイルになり得ます。なぜなら、ステップは入力に変更があった場合にのみ実行されるからです。
Apache Airflowのようなツールがこれを実行してくれますが、私は自分で構築したいと思いました。私のウェブサイトは、他人のライブラリを使用するのではなく、学習演習として自分で物事を構築するのが好きなサンドボックスです。
APIの設計に数週間費やしましたが、満足のいくものは見つかりませんでした。しかし、デコレーターベースのAPIを試したところ、それがfunkycacheの構築につながり、複雑さの多くを軽減しながら多くのメリットを提供しています。
私のウェブサイトをウォームキャッシュで構築すると、約0.5秒かかります。その時間の大部分は、Markdownファイルをスキャンするためにファイルシステムをトラバースすることに費やされています。そのステップをさらに高速化するアイデアもありますが、それは別の日のタスクです。
funkycacheは、テストを含めてもわずか数百行のコードです。この問題が興味深いと思ったら、たとえ使用する予定のないライブラリであっても、読むことをお勧めします。