Python SDK 2.0: asyncio-Unterstützung und Python 3.12+

Kevin van Zonneveld

Mitgründer · Amsterdam, Niederlande ·

Version 2.0.0 unseres Python-SDKs, pytransloadit, ergänzt mit AsyncTransloadit einen asyncio-Client neben dem synchronen Client, den Sie bereits nutzen. Außerdem steigt die erforderliche Python-Mindestversion auf 3.12. Hier zeigen wir, wofür der asynchrone Client geeignet ist und was Sie vor dem Upgrade von 1.x prüfen sollten.

Warum ein asynchroner Client?

Der Client aus 1.x kommuniziert über Requests mit unserer API und blockiert dabei. In einer FastAPI- oder aiohttp-App hält jeder Aufruf den Event-Loop auf. Während eine Anfrage auf den Abschluss einer Assembly wartet, warten auch andere Anfragen auf diesem Worker, sofern Sie den Aufruf nicht selbst in einen Thread-Pool auslagern.

AsyncTransloadit sendet seine API-Aufrufe über aiohttp und fragt den Assembly-Status mit asyncio.sleep wiederholt ab. So können Sie mit await auf eine Assembly wie auf jeden anderen I/O-Vorgang warten. Damit lassen sich auch mehrere Assemblies zugleich in einem Skript oder einem Hintergrund-Worker ausführen.

Dateien parallel verarbeiten

Installieren Sie 2.0 unter Python 3.12 oder neuer:

python -m pip install --upgrade 'pytransloadit>=2,<3'

Dieses Skript ändert die Größe von drei Fotos parallel mit 🤖 /image/resize und nutzt dafür einen gemeinsamen Client und eine gemeinsame HTTP-Sitzung. Es liest Ihre Zugangsdaten aus TRANSLOADIT_KEY und 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())

Laden Sie die Beispielfotos herunter und führen Sie das Skript aus:

for photo in chameleon prinsengracht desert; do
  curl -fsSLo "$photo.jpg" \
    "https://demos.transloadit.com/inputs/$photo.jpg"
done
python resize_many.py

Das Skript gibt eine URL pro Thumbnail aus. Auf unserem Rechner waren die drei Assemblies (25 MB Fotos) nach etwa 3 Sekunden abgeschlossen. Dieselbe Schleife mit dem synchronen Client benötigte etwa 8 Sekunden.

wait=True kehrt zurück, sobald die Assembly abgeschlossen ist. API-Fehler werden weiterhin in der Antwort zurückgegeben, deshalb prüft das Skript auf error. Mit resumable=False wird jede Datei in der Anfrage zur Erstellung gesendet. Belassen Sie diese Einstellung bei großen Dateien auf dem Standardwert True: Fortsetzbare Uploads erfolgen über tus. Das SDK führt sie in Worker-Threads aus, sodass der Event-Loop während der Uploads reaktionsfähig bleibt.

In FastAPI verwenden

Installieren Sie FastAPI, Uvicorn und den Multipart-Parser, den FastAPI für Uploads benötigt:

python -m pip install fastapi uvicorn python-multipart

Erstellen Sie den Client einmal pro App und nutzen Sie ihn für alle Anfragen gemeinsam:

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

Wir haben drei Uploads gleichzeitig an diesen Endpunkt gesendet. Ein einzelner Uvicorn-Worker beantwortete alle drei in unter 4 Sekunden. Innerhalb der Anfrage auf das Ergebnis zu warten, eignet sich für kurze Bildverarbeitungsaufgaben. Für Videos und andere länger laufende Aufgaben erstellen Sie die Assembly ohne wait=True und übergeben Sie einen Wert für notify_url an new_assembly(), damit Transloadit Ihre App aufruft, sobald die Aufgabe abgeschlossen ist.

Was der asynchrone Client abdeckt

AsyncTransloadit bietet dieselben Funktionen wie der synchrone Client: Assemblies erstellen, abrufen, auflisten und abbrechen, Templates verwalten, die monatliche Abrechnung abrufen und URLs für Smart CDN signieren. Verwenden Sie await für Methoden, die auf das Netzwerk zugreifen. new_assembly(), new_template() und get_signed_smart_cdn_url() bleiben synchron.

Verwenden Sie den Client mit async with oder rufen Sie await client.aclose() auf, wenn Sie fertig sind. Mit session= können Sie Ihre eigene aiohttp-Sitzung übergeben. Fortsetzbare Übertragungen nutzen diese Sitzung jedoch nicht, deshalb gelten deren Proxy- und TLS-Einstellungen nicht für sie. Konfigurieren Sie diese stattdessen über die Requests-Umgebung.

Upgrade von 1.x

Ihr synchroner Code funktioniert weiterhin: from transloadit import client und die zugehörigen Methoden bleiben in 2.0 unverändert. Das sollten Sie prüfen:

Python 3.12 oder neuer. Aktualisieren Sie zuerst die Python-Interpreter für Entwicklung, CI und Deployment. Unter Python 3.9 bis 3.11 installiert pip weiterhin 1.0.4, die neueste Version aus der Reihe 1.x. Legen Sie pytransloadit<2 fest, um diese Versionswahl explizit zu machen.
Mindestversionen der Abhängigkeiten. 2.0 erfordert requests>=2.33,<3 und urllib3>=2.7,<3. Lockern Sie ältere Versionsbindungen in Ihren Constraints und erstellen Sie Ihre Lockdatei neu.
Weiterleitungen. Das SDK gibt HTTP-Weiterleitungen an Sie zurück, statt ihnen automatisch zu folgen.
Eingabevalidierung. Ungültige Dienst-URLs und leere Template-IDs lösen ValueError aus.
Templates. Wenn Sie eine Option template mit add_step() kombinieren, übergeben Sie den Wert für template als Dictionary statt als JSON-String.
Antworten. Bei einer Antwort ohne JSON enthält Response.data Text oder Bytes. Ein leerer Antwortkörper ergibt einen leeren String.
Polling. Wenn mit wait=True die Retries für Statusabfragen mit Ratenbegrenzung aufgebraucht sind, wird AssemblyPollingError ausgelöst. Die Assembly läuft möglicherweise noch: Nutzen Sie assembly_url aus dem Fehler, um den Status erneut abzufragen oder die Assembly abzubrechen.
Assembly-URLs. Status- und Abbruchanfragen werden nur an vertrauenswürdige Assembly-URLs gesendet. Der Standardclient lehnt andere Hosts ab.
Smart CDN. Boolesche Parameter werden als true und false signiert, entsprechend unserer Node.js-Referenzimplementierung. Workspace-Slugs müssen DNS-konform sein. auth_key, exp und sig sind reservierte Query-Schlüssel.

Die README und das Änderungsprotokoll zu 2.0.0 enthalten die vollständigen Upgrade-Hinweise.

Erste Schritte

python -m pip install --upgrade 'pytransloadit>=2,<3'

Sie finden das Paket auf PyPI, ausführbare synchrone und asynchrone Skripte im Beispielordner und die API-Referenz auf Read the Docs. Unsere Python-SDK-Dokumentation erklärt die Grundlagen. Noch kein Konto? Registrieren Sie sich kostenlos, dann können Sie die obigen Beispiele in wenigen Minuten ausführen. Im kostenlosen Community-Tarif werden Bildergebnisse mit Wasserzeichen versehen; unsere FAQ erklärt, warum. Fragen oder Probleme beim Upgrade können Sie im Issue-Tracker von python-sdk melden.