Python SDK 2.0:asyncio 対応と Python 3.12 以降
Python SDK のバージョン 2.0.0、pytransloadit では、従来の同期クライアントに加え、asyncio クライアントの AsyncTransloadit を追加しました。また、最小 Python バージョンを 3.12 に引き上げました。非同期クライアントの用途と、1.x からアップグレードする前の確認事項を紹介します。
非同期クライアントが必要な理由は?
1.x クライアントは、ブロッキング処理を行う Requests 経由で API と通信します。FastAPI や aiohttp アプリでは、呼び出しのたびにイベントループが停止します。呼び出しを自分でスレッドプールに移さない限り、あるリクエストが Assembly の完了を待つ間、同じワーカー上のほかのリクエストも待たされます。
AsyncTransloadit は aiohttp 経由で API を呼び出し、asyncio.sleep で Assembly の状態をポーリングします。そのため、ほかの I/O と同様に Assembly を
await できます。スクリプトやバックグラウンドワーカーから複数の Assembly を同時に実行するのも簡単です。
ファイルの並行処理
Python 3.12 以降で 2.0 をインストールします。
python -m pip install --upgrade 'pytransloadit>=2,<3'
次のスクリプトは、🤖 /image/resize を使い、クライアントと HTTP セッションをそれぞれ共有して、3 枚の写真を並列にリサイズします。認証情報は TRANSLOADIT_KEY と TRANSLOADIT_SECRET から読み込みます。
import asyncio
import os
from transloadit.async_client import AsyncTransloadit
async def resize(client, path):
assembly = client.new_assembly()
thumb = {"use": ":original", "width": 400}
assembly.add_step("thumb", "/image/resize", thumb)
with open(path, "rb") as upload:
assembly.add_file(upload)
response = await assembly.create(wait=True, resumable=False)
if "error" in response.data:
raise RuntimeError(f"{path}: {response.data['error']}")
return response.data["results"]["thumb"][0]["ssl_url"]
async def main():
paths = ["chameleon.jpg", "prinsengracht.jpg", "desert.jpg"]
key = os.environ["TRANSLOADIT_KEY"]
secret = os.environ["TRANSLOADIT_SECRET"]
async with AsyncTransloadit(key, secret) as client:
urls = await asyncio.gather(*(resize(client, p) for p in paths))
print("\n".join(urls))
asyncio.run(main())
サンプル写真をダウンロードし、スクリプトを実行します。
for photo in chameleon prinsengracht desert; do
curl -fsSLo "$photo.jpg" \
"https://demos.transloadit.com/inputs/$photo.jpg"
done
python resize_many.py
スクリプトはサムネイルごとに URL を出力します。当社のマシンでは、3 件の Assembly(写真 25 MB)の完了に約 3 秒かかりました。同期クライアントで同じループを実行した場合は約 8 秒でした。
wait=True は Assembly が完了すると戻ります。API エラーは引き続きレスポンスに含まれるため、スクリプトでは error を確認しています。resumable=False は、作成リクエストで各ファイルを送信します。大きなファイルでは、デフォルトの True のままにしてください。再開可能なアップロードには tus を使用し、SDK がワーカースレッドで実行するため、アップロード中もイベントループの応答性が保たれます。
FastAPI での使用
FastAPI、Uvicorn、および FastAPI のアップロードに必要なマルチパートパーサーをインストールします。
python -m pip install fastapi uvicorn python-multipart
アプリごとにクライアントを一度だけ作成し、リクエスト間で共有します。
import os
from contextlib import asynccontextmanager
from fastapi import FastAPI, HTTPException, UploadFile
from transloadit.async_client import AsyncTransloadit
@asynccontextmanager
async def lifespan(app: FastAPI):
key = os.environ["TRANSLOADIT_KEY"]
secret = os.environ["TRANSLOADIT_SECRET"]
async with AsyncTransloadit(key, secret) as client:
app.state.transloadit = client
yield
app = FastAPI(lifespan=lifespan)
@app.post("/thumbnails")
async def create_thumbnail(file: UploadFile):
assembly = app.state.transloadit.new_assembly()
thumb = {"use": ":original", "width": 400}
assembly.add_step("thumb", "/image/resize", thumb)
assembly.add_file(file.file)
response = await assembly.create(wait=True, resumable=False)
thumbs = response.data.get("results", {}).get("thumb")
if "error" in response.data or not thumbs:
raise HTTPException(502, "Could not create a thumbnail")
return {"url": thumbs[0]["ssl_url"]}
uvicorn app:app
curl -fsSL -F file=@chameleon.jpg http://127.0.0.1:8000/thumbnails
このエンドポイントに 3 件のアップロードを同時に送信したところ、単一の Uvicorn ワーカーがすべてに 4 秒未満で応答しました。リクエスト内で結果を待つ方法は、短時間で終わる画像処理に適しています。動画など、時間のかかる処理では、wait=True を指定せずに
Assembly を作成し、notify_url を new_assembly() に渡してください。これにより、Transloadit が処理完了時にアプリを呼び出します。
非同期クライアントの対応範囲
AsyncTransloadit は同期クライアントと同じ機能を備えています。Assembly の作成、取得、一覧取得、キャンセル、Template の管理、月次請求情報の取得、Smart CDN URL の署名に対応しています。ネットワーク通信を行うメソッドは await で呼び出します。new_assembly()、new_template()、get_signed_smart_cdn_url() は引き続き同期処理です。
クライアントは async with で使用するか、使用後に await client.aclose() を呼び出してください。session= で独自の aiohttp セッションを渡せます。ただし、再開可能な転送にはそのセッションを使用しないため、そのプロキシ設定と TLS 設定は適用されません。これらは Requests の環境設定で構成してください。
1.x からのアップグレード
同期コードはそのまま動作します。2.0 でも from transloadit import client とそのメソッドに変更はありません。次の点を確認してください。
- Python 3.12 以降。 まず、開発環境、CI、デプロイ環境のインタープリターをアップグレードしてください。Python 3.9 から 3.11 では、pip は引き続き最新の 1.x リリースである 1.0.4 をインストールします。明示的に指定するには、
pytransloadit<2に固定してください。 - 依存パッケージの最小バージョン。 2.0 には
requests>=2.33,<3とurllib3>=2.7,<3が必要です。制約設定内の古いバージョン固定を緩和し、ロックファイルを再生成してください。 - リダイレクト。 HTTP リダイレクトには追従せず、そのまま返します。
- 入力検証。 無効なサービス URL や空の Template ID は
ValueErrorを発生させます。 - Template。
templateオプションとadd_step()を併用する場合、templateの値は JSON 文字列ではなく dict として渡してください。 - レスポンス。 JSON 以外のレスポンスでは
Response.dataにテキストまたはバイト列が入り、ボディが空の場合は空文字列になります。 - ポーリング。
wait=Trueを使用すると、レート制限された状態確認で再試行回数を使い切った際にAssemblyPollingErrorが発生します。Assembly はまだ実行中の可能性があります。エラーのassembly_urlを使い、再度ポーリングするかキャンセルしてください。 - Assembly URL。 状態確認とキャンセルのリクエストは、信頼された Assembly URL にのみ送信され、デフォルトのクライアントはほかのホストを拒否します。
- Smart CDN。 ブール値のパラメーターは、当社の Node.js 参照実装に合わせ、
trueとfalseとして署名されます。Workspace のスラッグは DNS で安全に使用できる必要があります。また、auth_key、exp、sigは予約済みのクエリキーです。
アップグレードに関する詳細は、README と 2.0.0 の変更履歴に記載しています。
はじめに
python -m pip install --upgrade 'pytransloadit>=2,<3'
パッケージは PyPI、実行可能な同期・非同期スクリプトは examples フォルダー、API リファレンスは Read the Docsで公開しています。基本的な使い方は Python SDK ドキュメントをご覧ください。アカウントがまだない場合は、無料登録すると、数分で上記のサンプルを実行できます。無料の Community プランでは、画像の処理結果に透かしが入ります。その理由は FAQ で説明しています。アップグレードに関する質問や問題は、python-sdk の課題トラッカーにお寄せください。
