Backon – Pythonのリトライ（依存関係ゼロ、サーキットブレーカー、ネイティブ非同期対応）

Backon 関数デコレーターによるバックオフとリトライ — モダン、高速、依存関係ゼロ。 Backonは、バックオフのためのモダンな進化形であり、指数関数的バックオフによるリトライのための依存関係ゼロのPythonライブラリです。同期コードと非同期コードの両方に対して、デコレーター、関数型、コンテキストマネージャーのAPIを提供します。 目次 機能 インストール クイックスタート APIリファレンス デコレーター 関数型API コンテキストマネージャー 呼び出し側 待機ジェネレーター 停止条件 リトライ条件 ジッター ハンドラー グローバルトグル 非同期サポート カスタムスリープ 高度な機能 サーキットブレーカー ヘッジング メトリクス テストユーティリティ Trioサポート リトライコンテキストの検査 動的なバックオフ ホットループ検出 リトライ統計 演算子の合成 イテレーターAPI backoffからの移行 コントリビューション ライセンス 機能 依存関係ゼロ — 純粋なPython、標準ライブラリのみ 4つのAPI — デコレーター（@on_exception、@on_predicate）、関数型（retry()）、コンテキストマネージャー（Retrying）、呼び出し可能（RetryingCaller / AsyncRetryingCaller） 非同期ネイティブ — 同じAPIがasync def関数でも動作します 完全な型ヒント — mypyで検証済み、strictモード互換 グローバルトグル — テスト用にbackon.disable() / backon.enable() を使用 カスタムスリープ — 独自のsleep関数を注入（asyncio.Eventを使用したテストに便利） 複数の待機戦略 — 指数関数的、定数、フィボナッチ、減衰、実行時、ランダム化、増分、および合成チェーン ジッター — フルジッター、ランダムジッター、またはなし 豊富なコールバック — on_attempt、on_backoff、on_success、on_giveup、before_sleep、before、after サーキットブレーカー — CLOSED/OPEN/HALF_OPEN状態と自動復旧 ヘッジング — 同時リトライリクエスト、最初に成功したものが勝ち Prometheus / OpenTelemetryメトリクス — オプション、ハード依存関係なし テストモジュール — disable_retries()、limit_retries()、remove_backoff()、assert_retried() Trioサポート — trio非同期フレームワークでのリトライ 演算子のオーバーロード — | / & で停止条件を合成、+ で待機ジェネレーターを合成 イテレーターAPI — attempt in Retrying(...) のように使用 モダンなパッケージング — PEP 621、PDM、py.typed インストール pip install backon Python 3.10+ が必要です。 クイックスタート 例外でリトライ import backon @backon.on_exception(backon.expo, ValueError, max_tries=3) def fetch_data(): return api.call() 述語でリトライ @backon.on_predicate(backon.constant, max_tries=5, interval=0.5) def poll_status(): return check_ready() 関数型API result = backon.retry( fetch_data, backon.expo, exception=ValueError, max_tries=3, ) コンテキストマネージャー with backon.Retrying(backon.expo, exception=ValueError, max_tries=3) as r: result = r.call(fetch_data) 非同期バリアント: async with backon.Retrying(backon.constant, exception=ValueError, max_tries=3, interval=0.5) as r: result = await r.async_call(fetch_data) APIリファレンス デコレーター @backon.on_exception(wait_gen, exception, ...) 指定された例外のいずれかをデコレートされた関数が発生させた場合にリトライします。 @backon.on_exception(backon.expo, (ValueError, TimeoutError), max_tries=5) def fetch(): ... 引数 タイプ デフォルト 説明 wait_gen WaitGenerator — 待機戦略（expo、constant、fiboなど） exception type または tuple[type] — リトライする例外クラス max_tries int または Callable[[], int] None 最大試行回数 max_time float、timedelta、または Callable None 最大総経過時間 jitter Jitterer または None — フルジッター Jitterer または None — ランダムジッター関数 giveup Callable[[Exception], bool or float] lambda e: False 一致する例外のリトライを停止します。floatを返すと待機時間を上書きします。 on_success Handler または list None 成功した試行の後に呼び出されます。 on_backoff Handler または list None 各リトライの前に呼び出されます。 on_giveup Handler または list None リトライが尽きたときに呼び出されます。 on_attempt Handler または list None 各試行の前に呼び出されます。 before_sleep Handler または list None スリープの前に呼び出されます。 before Handler または list None 各試行の前に呼び出されます（on_attemptより低レベル）。 after Handler または list None 各試行の後に呼び出されます（on_success/on_giveupより低レベル）。 retry_error_callback Callable[[dict], Any] None リトライが諦めたときに呼び出されます。 raise_on_giveup bool True 諦めたときに最終的な例外を発生させます。 logger str または Logger "backon" Logger名またはインスタンス backoff_log_level int logging.INFO バックオフメッセージのログレベル giveup_log_level int logging.ERROR ギブアップメッセージのログレベル sleep Callable[[float], Any] None カスタムスリープ関数 **wait_gen_kwargs 変動 — 待機ジェネレーターに渡される追加のキーワード引数（例: base=3, interval=0.5） @backon.on_predicate(wait_gen, predicate, ...) 述語が戻り値と一致する場合にリトライします。 @backon.on_predicate(backon.constant, predicate=lambda x: x is None, max_tries=5) def poll(): ... on_exceptionのすべてのパラメータに加えて、on_predicateの追加パラメータを受け入れます。 引数 タイプ デフォルト 説明 predicate Callable[[Any], bool] operator.not_ 戻り値に対してこれがTrueを返す場合にリトライします。 関数型API backon.retry(target, wait_gen, ...) result = backon.retry( target=my_function, wait_gen=backon.expo, exception=ValueError, max_tries=3, ) on_exceptionのすべてのパラメータに加えて、on_predicateの追加パラメータを受け入れます。 引数 タイプ デフォルト 説明 condition RetryCondition None 高度なリトライ条件オブジェクト stop Stop None 高度な停止条件オブジェクト name str "" リトライ呼び出しの識別子 **wait_gen_kwargs 変動 — 待機ジェネレーターに渡される追加のキーワード引数 ターゲットがコルーチン関数である場合、retry()はコルーチンを返します。それ以外の場合は同期的に結果を返します。 コンテキストマネージャー backon.Retrying(wait_gen, ...) with backon.Retrying(backon.expo, exception=ValueError, max_tries=3) as r: r.call(my_function) async with backon.Retrying(backon.constant, exception=ValueError, max_tries=3, interval=0.5) as r: await r.async_call(my_async_function) メソッド 説明 call(target, *args, **kwargs) 同期的に実行します。 async_call(target, *args, **kwargs) 非同期的に実行します。 copy() Retryingインスタンスの変更されたコピーを返します。 statistics プロパティ。attempt_number、elapsed、idle_for、start_timeを含む辞書を返します。 call_state プロパティ。現在のRetryCallStateを返します。 enabled プロパティ。インスタンスごとにリトライを有効/無効にするためのものです。 引数: retry()と同じですが、enabled（デフォルトTrue）が追加されます。 呼び出し側 backon.RetryingCaller(wait_gen, ...) .on() を介して事前にバインドされた例外タイプを持つ呼び出し可能なオブジェクトです。 caller = backon.RetryingCaller(backon.expo, max_tries=3) caller = caller.on(ValueError) result = caller(my_function, arg1, arg2) backon.AsyncRetryingCaller(wait_gen, ...) RetryingCallerの非同期バリアントです。 caller = backon.AsyncRetryingCaller(backon.expo, max_tries=3).on(ValueError) result = await caller(my_async_function, arg1, arg2) メソッド 説明 .on(exception) 指定された例外タイプにバインドされたコピーを返します。 .copy() 変更されたコピーを返します。 .__call__(target, *args, **kwargs) リトライして実行します。 待機ジェネレーター すべての待機ジェネレーターは、一連の待機時間を生成する呼び出し可能です。追加のキーワード引数（例: interval=0.5、base=3）をデコレーターや関数に **wait_gen_kwargs として渡します。 ジェネレーターシグネチャ 説明 expo (base=2, factor=1, max_value=None) 指数関数的バックオフ: factor * base^n constant (interval=1) 固定間隔。floatまたはSequence[float]（変動間隔用）を受け入れます。 fibo (max_value=None) フィボナッチ数列: 1, 1, 2, 3, 5, 8, ... runtime (value=Callable) 戻り値または例外からの動的な待機 — Retry-Afterヘッダーに便利です。 decay (initial_value=1, decay_factor=1, min_value=None) 指数関数的減衰: initial * e^(-t * decay_factor) wait_random_exponential (multiplier=1, max_value=None, exp_base=2, min_value=0) 指数関数値の間の均一なランダム値を持つランダム指数関数。 wait_incrementing (start=1, increment=1, max_value=None) 線形増分: start + n * increment wait_chain (*generators) 複数のジェネレーターを順番に再生します。 wait_exception (value=Callable) キャッチされた例外に基づく動的な待機。 wait_random (min=0, max=1) minとmaxの間の均一なランダム待機。 wait_exponential_jitter (initial=1, max=60, exp_base=2, jitter=1) ランダムジッターが追加された指数関数的バックオフ。 wait_none () 常に0を返します（待機なし）。 合成: 待機ジェネレーターを組み合わせます。