Backon – Pythonのリトライ(依存関係ゼロ、サーキットブレーカー、ネイティブ非同期対応)
Backon – Python retry (zero deps, circuit breaker, async native) (github.com)
要約
Backonは、依存関係ゼロでモダンかつ高速なPythonのリトライライブラリです。デコレーター、関数型API、コンテキストマネージャーAPIを提供し、同期および非同期コードの両方に対応しています。指数関数的バックオフ、サーキットブレーカー、ヘッジングなどの高度な機能も備えています。
全文翻訳
backon
リトライとバックオフのための関数デコレーター — モダン、高速、依存関係ゼロ。
[画像][画像] [画像] [画像] [画像] [画像] [画像]
backon は backoff のモダンな進化形です — ゼロ依存のPythonライブラリで、指数関数的なバックオフを伴うリトライが可能です。同期および非同期コードの両方に対して、デコレーター、関数型、およびコンテキストマネージャーAPIを提供します。
目次
- 機能 (Features)
- インストール (Installation)
- クイックスタート (Quick Start)
- APIリファレンス (API Reference)
- デコレーター (Decorators)
- 関数型API (Functional API)
- コンテキストマネージャー (Context Manager)
- 呼び出し側 (Callers)
- 待機ジェネレーター (Wait Generators)
- 停止条件 (Stop Conditions)
- リトライ条件 (Retry Conditions)
- ジッター (Jitter)
- ハンドラー (Handlers)
- グローバルトグル (Global Toggle)
- ジェネレーターサポート (Generator Support)
- 非同期サポート (Async Support)
- カスタムスリープ (Custom Sleep)
- 高度な機能 (Advanced Features)
- サーキットブレーカー (Circuit Breaker)
- ヘッジング (Hedging)
- テストユーティリティ (Testing Utilities)
- Trioサポート (Trio Support)
- リトライコンテキストの検査 (Retry Context Inspection)
- 動的バックオフ (Dynamic Backoff)
- ホットループ検出 (Hot Loop Detection)
- リトライ統計 (Retry Statistics)
- 演算子の合成 (Operator Composition)
- イテレーターAPI (Iterator API)
- backoffからの移行 (Migrating from backoff)
- コントリビューション (Contributing)
- ライセンス (License)
機能 (Features)
- 依存関係ゼロ — 純粋なPython、標準ライブラリのみ
- 4つのAPI — デコレーター (
@on_exception,@on_predicate)、関数型 (retry())、コンテキストマネージャー (Retrying)、呼び出し可能 (RetryingCaller/AsyncRetryingCaller) - 非同期ネイティブ — 同じAPIが
async def関数でも動作します - ジェネレーターネイティブ — 同期・非同期ジェネレーターが透過的にリトライされます
- 完全な型ヒント — mypyで検証済み、
py.typedが含まれています - グローバルトグル — テスト用の
backon.disable()/backon.enable() - カスタムスリープ — 独自のsleep関数を注入できます(
asyncio.Eventを使ったテストに便利) - 複数の待機戦略 — 指数関数的、定数、フィボナッチ、減衰、実行時間、ランダム化、増分、および合成可能なチェーン
wait_combine()— リトライステップごとに複数の待機戦略を合計しますretry_with()— デコレートされた関数でリトライパラメータを呼び出しごとにオーバーライドできます- ジッター — フルジッター、ランダムジッター、またはなし
- 豊富なコールバック —
on_attempt、on_backoff、on_success、on_giveup、before_sleep、before、after - サーキットブレーカー — CLOSED/OPEN/HALF_OPEN状態と自動回復
- ヘッジング — 同時リトライリクエスト、最初の成功が勝ち
- テストモジュール —
disable_retries()、limit_retries()、remove_backoff()、assert_retried() - Trioサポート — trio非同期フレームワークでリトライ
- 演算子のオーバーロード —
|/&で停止条件、+で待機ジェネレーターを合成します - イテレーターAPI —
for attempt in Retrying(...): - モダンなパッケージング — PEP 621、PDM、py.typed
インストール (Installation)
pip install backon
Python 3.9+ が必要です。
クイックスタート (Quick Start)
例外発生時のリトライ
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)
with / async with ブロックは純粋にスコープを定義するものです。これにより Retrying オブジェクトが返され、r.call(...) / await r.async_call(...) を呼び出してリトライループを駆動できます。__exit__ / __aexit__ は最終的な例外を再発生させたり、ループに影響を与えたりしません — それは r.call / r.async_call の内部で行われます。呼び出し後に r.statistics を使用して、試行回数を確認できます。これは BreakerRetrying および HedgingRetrying コンテキストマネージャーにも同様に適用されます。
APIリファレンス (API Reference)
デコレーター (Decorators)
@backon.on_exception(wait_gen, exception, ...)
デコレートされた関数が指定された例外のいずれかを発生させた場合にリトライします。
@backon.on_exception(backon.expo, (ValueError, TimeoutError), max_tries=5)
def fetch():
...
| 引数 | タイプ | デフォルト | 説明 |
|---|---|---|---|
wait_gen | WaitGenerator | — | 待機戦略 (expo, constant, fibo, etc.) |
exception | type または tuple[type] | — | リトライ対象の例外クラス |
max_tries | int または Callable[[], int] | None | 最大試行回数 |
max_time | float, timedelta, または Callable | None | 最大総経過時間 |
jitter | Jitterer または None | full_jitter | ジッター関数 |
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 | ` |