Transloadit

Python SDK

transloadit/python-sdk

Installation

Das SDK ist auf PyPI als pytransloadit veröffentlicht. Version 2 erfordert Python 3.12 oder neuer:

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

Dieser Befehl schlägt unter Python 3.9 bis 3.11 fehl. Dort installiert ein einfaches pip install pytransloadit 1.0.4, die neueste 1.x-Version. Um ausdrücklich bei 1.x zu bleiben, legen Sie die Version unterhalb von Version 2 fest:

python -m pip install 'pytransloadit<2'

Verwendung

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) kehrt zurück, sobald die Assembly abgeschlossen ist. API-Fehler kommen in der Antwort zurück, statt ausgelöst zu werden. Deshalb prüft das Beispiel auf einen error-Schlüssel, bevor es die Ergebnisse verwendet.

Asynchrone Verwendung

AsyncTransloadit ist ein asyncio-Client für Apps auf Basis von FastAPI, aiohttp oder anderen asynchronen Frameworks. Er sendet API-Anfragen über aiohttp und fragt den Assembly-Status mit asyncio.sleep ab, sodass das Warten auf eine Assembly die Event-Loop nicht blockiert:

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())

Der asynchrone Client spiegelt den synchronen wider: Assemblies, Templates, monatliche Abrechnung und das Signieren von Smart-CDN-URLs. Rufen Sie die Methoden, die Netzwerkanfragen ausführen, mit await auf. new_assembly(), new_template() und get_signed_smart_cdn_url() bleiben synchron. Lassen Sie die Datei geöffnet, bis der mit await aufgerufene create() zurückkehrt.

Verwenden Sie den Client mit async with, oder rufen Sie await tl.aclose() auf, wenn Sie fertig sind. Mit session= können Sie Ihre eigene aiohttp-Sitzung übergeben. Fortsetzbare Uploads, der Standard für create(), laufen über tus in Worker-Threads, sodass die Event-Loop auch beim Upload großer Dateien reaktionsfähig bleibt. Diese Übertragungen nutzen Ihre aiohttp-Sitzung jedoch nicht: Konfigurieren Sie deren Proxy- und TLS-Einstellungen stattdessen über die Requests-Umgebung.

Upgrade von 1.x

Synchroner Code für 1.x funktioniert weiterhin: from transloadit import client und seine Methoden sind in Version 2 unverändert. Prüfen Sie vor dem Upgrade Folgendes:

  • Python 3.12 oder neuer. Aktualisieren Sie zuerst Ihre Interpreter für Entwicklung, CI und Deployment.
  • Mindestversionen von Abhängigkeiten. Version 2 erfordert requests>=2.33,<3 und urllib3>=2.7,<3. Lockern Sie ältere Pins in Ihren Constraints und generieren Sie Ihre Lockfile neu.
  • Weiterleitungen. HTTP-Weiterleitungen werden an Sie zurückgegeben, statt ihnen zu folgen.
  • Eingabevalidierung. Ungültige Service-URLs und leere Template-IDs lösen ValueError aus.
  • Templates. Wenn Sie eine template-Option mit add_step() kombinieren, übergeben Sie den template-Wert als Dict, nicht als JSON-String.
  • Antworten. Eine Antwort ohne JSON legt Text oder Bytes in Response.data ab, und ein leerer Body ergibt einen leeren String.
  • Polling. Mit wait=True löst es AssemblyPollingError aus, wenn bei Statusabfragen mit Ratenbegrenzung die Wiederholungsversuche ausgehen. Die Assembly läuft möglicherweise noch: Verwenden Sie assembly_url des Fehlers, um erneut abzufragen oder sie abzubrechen.
  • Assembly-URLs. Status- und Abbruchanfragen gehen nur an vertrauenswürdige Assembly-URLs, und der Standard-Client weist andere Hosts ab.
  • Smart CDN. Boolesche Parameter werden als true und false signiert, passend zu unserer Node.js-Referenzimplementierung. Workspace-Slugs müssen DNS-tauglich sein, und auth_key, exp sowie sig sind reservierte Query-Schlüssel.

Das README und das Changelog enthalten die vollständigen Upgrade-Hinweise.

Beispiel

Vollständig funktionsfähige synchrone und asynchrone Beispiele finden Sie unter examples/.

Dokumentation

Die vollständige API-Referenz beider Clients finden Sie auf Read the Docs. Den Quellcode und den Issue-Tracker finden Sie auf GitHub, die Releases auf PyPI.