Python SDK (polylingo)

Klien Python rasmi untuk PolyLingo REST API. Ia menggunakan httpx dan menyediakan klien sync dan async dengan nama kaedah yang sama.

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

Untuk butiran HTTP mentah, lihat rujukan API.

Pemasangan

pip install polylingo

Python: >= 3.9

Klien Sync

import os
import polylingo

client = polylingo.PolyLingo(
    api_key=os.environ["POLYLINGO_API_KEY"],
    base_url="https://api.usepolylingo.com/v1",  # pilihan; lalai ditunjukkan
    timeout=120.0,  # pilihan; saat setiap permintaan (lalai 120)
)

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

client.close()

Pengurus konteks:

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

Klien Async

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 kaedah sepadan dengan klien sync; semua kaedah rangkaian adalah async def.

Kaedah (sync dan async)

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",  # pilihan
    source="en",        # pilihan
    model="standard",   # pilihan: "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 badan 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. Apabila status == "completed", respons termasuk translations dan usage di peringkat atas.

translate(...) — kemudahan

Polling sehingga completed atau failed, atau sehingga masa tamat.

done = client.jobs.translate(
    content=long_md,
    targets=["de", "fr", "es"],
    format="markdown",
    poll_interval=10.0,   # saat antara polling; lalai 5.0
    timeout=600.0,        # bajet **jumlah** saat; lalai 1200 (20 minit)
    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.

Pengecualian

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)

Corak kerja async (ringkasan)

1. Manual: jobs.create → ulang jobs.get sehingga keadaan terminal.
2. Pembantu: jobs.translate dengan poll_interval, timeout, dan pilihan on_progress.

Utamakan jobs untuk kandungan sangat besar di mana translate sinkron mungkin terkena tamat masa klien atau pelayan.

Jenis

Pakej ini mengandungi py.typed. Objek respons adalah nilai dict biasa yang selaras dengan API; gunakan anotasi gaya TypedDict dalam kod anda jika mahu.

Log Perubahan

0.1.0

• Siaran awal: sync PolyLingo, async AsyncPolyLingo, liputan penuh titik akhir termasuk pembantu polling jobs.translate.