Transloadit

SDK para Python

transloadit/python-sdk

Instalar

O SDK é publicado no PyPI como pytransloadit. A versão 2 exige Python 3.12 ou mais recente:

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

Esse comando falha no Python 3.9 a 3.11. Nesses interpretadores, um pip install pytransloadit simples instala a 1.0.4, a última versão 1.x. Para permanecer explicitamente na 1.x, fixe-a abaixo da versão 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) retorna assim que a Assembly termina. Os erros da API vêm na resposta em vez de serem lançados, e é por isso que o exemplo verifica se há uma chave error antes de usar os resultados.

Uso assíncrono

AsyncTransloadit é um cliente asyncio para apps criados com FastAPI, aiohttp ou outros frameworks assíncronos. Ele envia as requisições da API pelo aiohttp e consulta o status da Assembly com asyncio.sleep, então aguardar uma Assembly não bloqueia o event loop:

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

O cliente assíncrono espelha o síncrono: Assemblies, Templates, faturamento mensal e assinatura de URLs da Smart CDN. Use await nos métodos que fazem requisições de rede. new_assembly(), new_template() e get_signed_smart_cdn_url() continuam síncronos. Mantenha o arquivo aberto até a chamada create() aguardada retornar.

Use o cliente com async with ou chame await tl.aclose() quando terminar de usá-lo. Você pode passar sua própria sessão do aiohttp com session=. Os uploads retomáveis, o padrão de create(), passam pelo tus em threads de trabalho, então o event loop continua responsivo enquanto arquivos grandes são enviados. No entanto, essas transferências não usam sua sessão do aiohttp: configure o proxy e as definições de TLS delas pelo ambiente do Requests.

Atualizar da versão 1.x

O código síncrono escrito para a 1.x continua funcionando: from transloadit import client e seus métodos não mudam na versão 2. Antes de atualizar, verifique:

  • Python 3.12 ou mais recente. Atualize primeiro os interpretadores de desenvolvimento, CI e implantação.
  • Versões mínimas de dependências. A versão 2 exige requests>=2.33,<3 e urllib3>=2.7,<3. Afrouxe as fixações mais antigas nas suas restrições e gere o lockfile novamente.
  • Redirecionamentos. Os redirecionamentos HTTP são retornados a você em vez de seguidos.
  • Validação de entrada. URLs de serviço inválidas e IDs de Template vazios geram ValueError.
  • Templates. Ao combinar uma opção template com add_step(), passe o valor de template como um dict, não como uma string JSON.
  • Respostas. Uma resposta que não seja JSON coloca texto ou bytes em Response.data, e um corpo vazio resulta em uma string vazia.
  • Polling. Com wait=True, esgotar as tentativas em verificações de status limitadas por taxa gera AssemblyPollingError. A Assembly ainda pode estar em execução: use o assembly_url do erro para consultar novamente ou cancelá-la.
  • URLs de Assembly. As requisições de status e cancelamento só vão para URLs de Assembly confiáveis, e o cliente padrão rejeita outros hosts.
  • Smart CDN. Os parâmetros booleanos são assinados como true e false, como na nossa implementação de referência em Node.js. Os slugs de Workspace devem ser seguros para DNS, e auth_key, exp e sig são chaves de consulta reservadas.

O README e o changelog trazem as notas de atualização completas.

Exemplo

Para ver exemplos síncronos e assíncronos totalmente funcionais, confira examples/.

Documentação

Consulte o Read the Docs para ver a referência completa da API dos dois clientes. O código-fonte e o rastreador de issues ficam no GitHub, e as versões publicadas, no PyPI.