Python SDK (polylingo)

Client Python officiel pour l'API REST PolyLingo. Il utilise httpx et fournit des clients synchrone et asynchrone avec les mêmes noms de méthodes.

• PyPI : polylingo
• Source : UsePolyLingo/polylingo-python

Pour les détails HTTP bruts, voir API reference.

Installation

pip install polylingo

Python : >= 3.9

Client synchrone

import os
import polylingo

client = polylingo.PolyLingo(
    api_key=os.environ["POLYLINGO_API_KEY"],
    base_url="https://api.usepolylingo.com/v1",  # optionnel ; valeur par défaut affichée
    timeout=120.0,  # optionnel ; secondes par requête (par défaut 120)
)

result = client.translate(content="# Hello", targets=["es", "fr"], format="markdown")
print(result["translations"]["es"])

client.close()

Gestionnaire de contexte :

with polylingo.PolyLingo(api_key="...") as client:
    print(client.languages())

Client asynchrone

import polylingo

async with polylingo.AsyncPolyLingo(api_key="...") as client:
    r = await client.translate(content="Hi", targets=["de"])

Utilisez await client.aclose() si vous n'utilisez pas async with.

Les noms des méthodes correspondent au client synchrone ; toutes les méthodes réseau sont async def.

Méthodes (synchrone et asynchrone)

health() / await health()

GET /health

h = client.health()
# async : h = await client.health()

languages() / await languages()

GET /languages

data = client.languages()
langs = data["languages"]

translate(...)

POST /translate

r = client.translate(
    content="# Hello",
    targets=["es", "fr"],
    format="markdown",  # optionnel
    source="en",        # optionnel
    model="standard",   # optionnel : "standard" | "advanced"
)
r["translations"]["es"]
r["usage"]["total_tokens"]

batch(...)

POST /translate/batch

b = client.batch(
    items=[
        {"id": "a", "content": "Hello"},
        {"id": "b", "content": "## Title", "format": "markdown"},
    ],
    targets=["de"],
)
b["results"][0]["translations"]["de"]

usage() / await usage()

GET /usage

u = client.usage()

Jobs — client.jobs

create / await create

POST /jobs — renvoie le corps 202 (job_id, status, …).

job = client.jobs.create(content=long_md, targets=["de", "fr"], format="markdown")
# kwargs également acceptés : client.jobs.create(**{"content": ..., "targets": [...]})

get(job_id) / await get(job_id)

GET /jobs/:id. Lorsque status == "completed", les réponses incluent translations et usage au niveau supérieur.

translate(...) — commodité

Interroge jusqu'à ce que ce soit completed ou failed, ou jusqu'à expiration du temps.

done = client.jobs.translate(
    content=long_md,
    targets=["de", "fr", "es"],
    format="markdown",
    poll_interval=10.0,   # secondes entre les sondages ; défaut 5.0
    timeout=600.0,        # budget **total** en secondes ; défaut 1200 (20 min)
    on_progress=lambda pos: print(f"Queue: {pos}"),
)
done["translations"]["de"]

Asynchrone :

done = await client.jobs.translate(
    content=long_md,
    targets=["de"],
    poll_interval=2.0,
    timeout=300.0,
)

Statuts API : pending, processing, completed, failed.

Exceptions

import polylingo

try:
    client.translate(content="x", targets=["es"])
except polylingo.AuthError as e:
    print(e.status, e.error)
except polylingo.RateLimitError as e:
    print(e.retry_after)
except polylingo.JobFailedError as e:
    print(e.job_id)
except polylingo.PolyLingoError as e:
    print(e.status, e.error)

Modèle de jobs asynchrones (résumé)

1. Manuel : jobs.create → boucle jobs.get jusqu'à l'état terminal.
2. Assistant : jobs.translate avec poll_interval, timeout et optionnel on_progress.

Préférez les jobs pour les contenus très volumineux où translate synchrone pourrait atteindre des timeouts client ou serveur.

Types

Le paquet inclut py.typed. Les objets de réponse sont des valeurs dict simples alignées avec l'API ; utilisez des annotations de style TypedDict dans votre code si vous le souhaitez.

Journal des modifications

0.1.0

• Première version : PolyLingo synchrone, AsyncPolyLingo asynchrone, couverture complète des endpoints incluant l'assistant de sondage jobs.translate.