Python SDK (polylingo)

Klien Python resmi untuk PolyLingo REST API. Menggunakan httpx dan menyediakan klien sinkron dan asinkron dengan nama metode yang sama.

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

Untuk detail HTTP mentah, lihat API reference.

Instalasi

pip install polylingo

Python: >= 3.9

Klien Sinkron

import os
import polylingo

client = polylingo.PolyLingo(
    api_key=os.environ["POLYLINGO_API_KEY"],
    base_url="https://api.usepolylingo.com/v1",  # opsional; default ditampilkan
    timeout=120.0,  # opsional; detik per permintaan (default 120)
)

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

client.close()

Manajer konteks:

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

Klien Asinkron

import polylingo

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

Gunakan await client.aclose() jika tidak menggunakan async with.

Nama metode cocok dengan klien sinkron; semua metode jaringan adalah async def.

Metode (sinkron dan asinkron)

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",  # opsional
    source="en",        # opsional
    model="standard",   # opsional: "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 — mengembalikan body 202 (job_id, status, …).

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

get(job_id) / await get(job_id)

GET /jobs/:id. Saat status == "completed", respons menyertakan translations dan usage di tingkat atas.

translate(...) — kemudahan

Melakukan polling sampai completed atau failed, atau sampai waktu habis.

done = client.jobs.translate(
    content=long_md,
    targets=["de", "fr", "es"],
    format="markdown",
    poll_interval=10.0,   # detik antara polling; default 5.0
    timeout=600.0,        # anggaran detik **total**; default 1200 (20 menit)
    on_progress=lambda pos: print(f"Queue: {pos}"),
)
done["translations"]["de"]

Async:

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

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

Pola pekerjaan Async (ringkasan)

1. Manual: jobs.create → loop jobs.get sampai status terminal.
2. Bantuan: jobs.translate dengan poll_interval, timeout, dan on_progress opsional.

Utamakan jobs untuk konten sangat besar di mana translate sinkron mungkin terkena timeout klien atau server.

Tipe

Paket mengirimkan py.typed. Objek respons adalah nilai dict biasa yang selaras dengan API; gunakan anotasi gaya TypedDict dalam kode Anda jika diinginkan.

Changelog

0.1.0

• Rilis awal: sync PolyLingo, async AsyncPolyLingo, cakupan endpoint penuh termasuk pembantu polling jobs.translate.