Transloadit

SDK de Python

transloadit/python-sdk

Instalación

El SDK se publica en PyPI como pytransloadit. La versión 2 requiere Python 3.12 o posterior:

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

Ese comando falla en Python 3.9 a 3.11. En esas versiones, un pip install pytransloadit simple instala 1.0.4, la última versión 1.x. Para mantenerte explícitamente en 1.x, fíjala por debajo de la versión 2:

python -m pip install 'pytransloadit<2'

Uso

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) devuelve el resultado cuando la Assembly ha terminado. Los errores de la API se devuelven en la respuesta en lugar de lanzarse, por lo que el ejemplo comprueba si hay una clave error antes de usar los resultados.

Uso asíncrono

AsyncTransloadit es un cliente asyncio para apps creadas con FastAPI, aiohttp u otros frameworks asíncronos. Envía las solicitudes a la API a través de aiohttp y consulta el estado de la Assembly con asyncio.sleep, de modo que esperar a una Assembly no bloquea el bucle de eventos:

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

El cliente asíncrono replica al síncrono: Assemblies, Templates, facturación mensual y firma de URL de Smart CDN. Usa await con los métodos que realizan solicitudes de red. new_assembly(), new_template() y get_signed_smart_cdn_url() siguen siendo síncronos. Mantén el archivo abierto hasta que la llamada a create() con await termine.

Usa el cliente con async with, o llama a await tl.aclose() cuando termines de usarlo. Puedes pasar tu propia sesión de aiohttp con session=. Las subidas reanudables, el valor predeterminado de create(), se realizan mediante el protocolo tus en hilos de trabajo, por lo que el bucle de eventos sigue respondiendo mientras se suben archivos grandes. Sin embargo, esas transferencias no usan tu sesión de aiohttp: configura su proxy y sus ajustes de TLS mediante el entorno de Requests.

Actualizar desde 1.x

El código síncrono escrito para 1.x sigue funcionando: from transloadit import client y sus métodos no cambian en la versión 2. Antes de actualizar, comprueba lo siguiente:

  • Python 3.12 o posterior. Actualiza primero los intérpretes de desarrollo, CI y despliegue.
  • Versiones mínimas de dependencias. La versión 2 requiere requests>=2.33,<3 y urllib3>=2.7,<3. Flexibiliza las fijaciones anteriores en tus restricciones y regenera tu archivo de bloqueo.
  • Redirecciones. Las redirecciones HTTP se te devuelven en lugar de seguirse.
  • Validación de entrada. Las URL de servicio no válidas y los IDs de Template vacíos generan ValueError.
  • Templates. Cuando combines una opción template con add_step(), pasa el valor de template como dict, no como cadena JSON.
  • Respuestas. Una respuesta que no sea JSON coloca texto o bytes en Response.data, y un cuerpo vacío da una cadena vacía.
  • Sondeo. Con wait=True, agotar los reintentos en las comprobaciones de estado limitadas por tasa genera AssemblyPollingError. Es posible que la Assembly siga en ejecución: usa el assembly_url del error para volver a sondear o cancelarla.
  • URL de Assembly. Las solicitudes de estado y cancelación solo se envían a URL de Assembly de confianza, y el cliente predeterminado rechaza otros hosts.
  • Smart CDN. Los parámetros booleanos se firman como true y false, igual que nuestra implementación de referencia en Node.js. Los slugs de Workspace deben ser seguros para DNS, y auth_key, exp y sig son claves de consulta reservadas.

El README y el registro de cambios incluyen las notas completas de actualización.

Ejemplo

Para ver ejemplos síncronos y asíncronos totalmente funcionales, consulta examples/.

Documentación

Consulta Read the Docs para acceder a la referencia completa de la API de ambos clientes. El código fuente y el sistema de seguimiento de incidencias están en GitHub, y las versiones publicadas, en PyPI.