Transloadit

SDK Python

transloadit/python-sdk

Installation

Le SDK est publié sur PyPI sous le nom pytransloadit. La version 2 nécessite Python 3.12 ou une version plus récente :

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

Cette commande échoue sous Python 3.9 à Python 3.11. Sur ces versions, un simple pip install pytransloadit installe la version 1.0.4, la dernière version 1.x. Pour rester explicitement sur 1.x, épinglez-la en dessous de la version 2 :

python -m pip install 'pytransloadit<2'

Utilisation

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) rend la main une fois l’Assembly terminée. Les erreurs d’API sont renvoyées dans la réponse au lieu d’être levées, c’est pourquoi l’exemple vérifie la présence d’une clé error avant d’utiliser les résultats.

Utilisation asynchrone

AsyncTransloadit est un client asyncio destiné aux applications construites avec FastAPI, aiohttp ou d’autres frameworks asynchrones. Il envoie les requêtes d’API via aiohttp et interroge le statut de l’Assembly avec asyncio.sleep, de sorte que l’attente d’une Assembly ne bloque pas la boucle d’événements :

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

Le client asynchrone reproduit le client synchrone : Assemblies, Templates, facturation mensuelle et signature d’URL Smart CDN. Utilisez await avec les méthodes qui effectuent des requêtes réseau. new_assembly(), new_template() et get_signed_smart_cdn_url() restent synchrones. Gardez le fichier ouvert jusqu’à ce que l’appel create() attendu avec await rende la main.

Utilisez le client avec async with, ou appelez await tl.aclose() lorsque vous n’en avez plus besoin. Vous pouvez transmettre votre propre session aiohttp avec session=. Les téléversements avec reprise, le mode par défaut de create(), passent par tus dans des threads de travail, si bien que la boucle d’événements reste réactive pendant le téléversement de fichiers volumineux. Ces transferts n’utilisent toutefois pas votre session aiohttp : configurez plutôt leurs paramètres de proxy et TLS via l’environnement de Requests.

Migrer depuis 1.x

Le code synchrone écrit pour 1.x continue de fonctionner : from transloadit import client et ses méthodes sont inchangés dans la version 2. Avant de migrer, vérifiez les points suivants :

  • Python 3.12 ou plus récent. Mettez d’abord à jour vos interpréteurs de développement, de CI et de déploiement.
  • Versions minimales des dépendances. La version 2 nécessite requests>=2.33,<3 et urllib3>=2.7,<3. Assouplissez les anciennes contraintes de version dans votre fichier de contraintes et régénérez votre fichier de verrouillage.
  • Redirections. Les redirections HTTP vous sont renvoyées au lieu d’être suivies.
  • Validation des entrées. Les URL de service non valides et les identifiants de Template vides lèvent ValueError.
  • Templates. Lorsque vous combinez une option template avec add_step(), transmettez la valeur template sous forme de dict, et non de chaîne JSON.
  • Réponses. Une réponse non JSON place du texte ou des octets dans Response.data, et un corps vide donne une chaîne vide.
  • Interrogation. Avec wait=True, l’épuisement des nouvelles tentatives lors de vérifications de statut limitées en débit lève AssemblyPollingError. L’Assembly peut encore être en cours d’exécution : utilisez la propriété assembly_url de l’erreur pour l’interroger à nouveau ou l’annuler.
  • URL d’Assembly. Les requêtes de statut et d’annulation ne sont envoyées qu’à des URL d’Assembly de confiance, et le client par défaut rejette les autres hôtes.
  • Smart CDN. Les paramètres booléens sont signés sous la forme true et false, conformément à notre implémentation de référence Node.js. Les slugs de Workspace doivent être compatibles DNS, et auth_key, exp et sig sont des clés de requête réservées.

Le README et le journal des modifications contiennent l’ensemble des notes de migration.

Exemple

Pour des exemples synchrones et asynchrones entièrement fonctionnels, consultez examples/.

Documentation

Consultez Read the Docs pour la référence complète de l’API des deux clients. Le code source et le suivi des tickets se trouvent sur GitHub, et les versions publiées sur PyPI.