Python SDK
インストール
SDK は PyPI で
pytransloaditとして公開されています。バージョン 2 には Python 3.12 以降が必要です。
python -m pip install --upgrade 'pytransloadit>=2,<3'
このコマンドは Python 3.9 から 3.11 では失敗します。これらの環境では、単に pip install pytransloadit を実行すると、1.x の最新リリースである 1.0.4 がインストールされます。明示的に 1.x を使い続けるには、バージョン 2 未満に固定します。
python -m pip install 'pytransloadit<2'
使い方
import os
from transloadit import client
tl = client.Transloadit(os.environ['TRANSLOADIT_KEY'], os.environ['TRANSLOADIT_SECRET'])
assembly = tl.new_assembly()
assembly.add_step('resize', '/image/resize', {'width': 70, 'height': 70})
with open('PATH/TO/FILE.jpg', 'rb') as upload:
assembly.add_file(upload)
assembly_response = assembly.create(retries=5, wait=True)
if 'error' in assembly_response.data:
raise RuntimeError(assembly_response.data['error'])
print(assembly_response.data['assembly_id'])
create(wait=True) は Assembly が完了すると戻ります。API エラーは例外として送出されず、レスポンスに含まれます。そのため、この例では結果を使う前に error キーの有無を確認しています。
非同期での使い方
AsyncTransloadit は、FastAPI、aiohttp などの非同期フレームワークで構築したアプリ向けの asyncio クライアントです。aiohttp 経由で API リクエストを送信し、asyncio.sleep で Assembly の状態をポーリングするため、Assembly の完了を待っている間もイベントループをブロックしません。
import asyncio
import os
from transloadit.async_client import AsyncTransloadit
async def main():
key = os.environ['TRANSLOADIT_KEY']
secret = os.environ['TRANSLOADIT_SECRET']
async with AsyncTransloadit(key, secret) as tl:
assembly = tl.new_assembly()
assembly.add_step('resize', '/image/resize', {'width': 70, 'height': 70})
with open('PATH/TO/FILE.jpg', 'rb') as upload:
assembly.add_file(upload)
response = await assembly.create(wait=True, resumable=False)
if 'error' in response.data:
raise RuntimeError(response.data['error'])
print(response.data['assembly_id'])
asyncio.run(main())
非同期クライアントは同期クライアントと同様に、Assembly、Template、月次請求、Smart CDN の URL 署名に対応しています。ネットワークリクエストを行うメソッドには await を使います。new_assembly()、new_template()、get_signed_smart_cdn_url() は同期のままです。await する create() の呼び出しが戻るまで、ファイルを開いたままにしてください。
クライアントは async with と組み合わせて使うか、使い終わったら await tl.aclose() を呼び出してください。session= で独自の aiohttp セッションを渡せます。create() でデフォルトとなる再開可能なアップロードは、ワーカースレッド内で tus を使って転送するため、大きなファイルのアップロード中もイベントループの応答性を維持します。ただし、この転送には指定した aiohttp セッションは使われません。転送のプロキシと TLS の設定は、Requests の環境設定で行ってください。
1.x からのアップグレード
1.x 向けに書かれた同期コードは、そのまま動作します。from transloadit import client とそのメソッドは、バージョン 2 でも変更されていません。アップグレード前に、次の点を確認してください。
- Python 3.12 以降。 まず開発、CI、デプロイ環境のインタープリターをアップグレードしてください。
- 依存関係の下限。 バージョン 2 には
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 と変更履歴を参照してください。
サンプル
そのまま動作する同期と非同期のサンプルは、examples/を参照してください。
ドキュメント
両クライアントの完全な API リファレンスは、Read the Docsを参照してください。ソースコードと課題トラッカーは GitHub、リリースは PyPIで公開しています。