Python SDK (polylingo)

ไคลเอนต์ Python อย่างเป็นทางการสำหรับ PolyLingo REST API ใช้ httpx และมีไคลเอนต์ทั้งแบบ sync และ async ที่มีชื่อเมธอดเหมือนกัน

• PyPI: polylingo
• ซอร์ส: UsePolyLingo/polylingo-python

สำหรับรายละเอียด HTTP ดิบ ดูที่ API reference

การติดตั้ง

pip install polylingo

Python: >= 3.9

ไคลเอนต์แบบซิงค์

import os
import polylingo

client = polylingo.PolyLingo(
    api_key=os.environ["POLYLINGO_API_KEY"],
    base_url="https://api.usepolylingo.com/v1",  # ตัวเลือก; ค่าเริ่มต้นที่แสดง
    timeout=120.0,  # ตัวเลือก; วินาทีต่อคำขอ (ค่าเริ่มต้น 120)
)

result = client.translate(content="# สวัสดี", targets=["es", "fr"], format="markdown")
print(result["translations"]["es"])

client.close()

ตัวจัดการบริบท:

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

ไคลเอนต์แบบ Async

import polylingo

async with polylingo.AsyncPolyLingo(api_key="...") as client:
    r = await client.translate(content="สวัสดี", targets=["de"])

ใช้ await client.aclose() หากไม่ได้ใช้ async with.

ชื่อเมธอดตรงกับไคลเอนต์แบบซิงค์; เมธอดเครือข่ายทั้งหมดเป็น async def.

เมธอด (sync และ 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="# สวัสดี",
    targets=["es", "fr"],
    format="markdown",  # ตัวเลือก
    source="en",        # ตัวเลือก
    model="standard",   # ตัวเลือก: "standard" | "advanced"
)
r["translations"]["es"]
r["usage"]["total_tokens"]

batch(...)

POST /translate/batch

b = client.batch(
    items=[
        {"id": "a", "content": "สวัสดี"},
        {"id": "b", "content": "## หัวข้อ", "format": "markdown"},
    ],
    targets=["de"],
)
b["results"][0]["translations"]["de"]

usage() / await usage()

GET /usage

u = client.usage()

งาน (client.jobs)

create / await create

POST /jobs คืนค่าร่างกาย 202 (job_id, status, …)

job = client.jobs.create(content=long_md, targets=["de", "fr"], format="markdown")
# kwargs ก็รับได้เช่นกัน: client.jobs.create(**{"content": ..., "targets": [...]})

get(job_id) / await get(job_id)

GET /jobs/:id เมื่อ status == "completed" การตอบสนองจะรวม translations และ usage ในระดับบนสุด

translate(...) (ความสะดวก)

รอจนกว่าจะ completed หรือ failed หรือจนกว่าจะหมดเวลา

done = client.jobs.translate(
    content=long_md,
    targets=["de", "fr", "es"],
    format="markdown",
    poll_interval=10.0,   # วินาทีระหว่างการตรวจสอบ; ค่าเริ่มต้น 5.0
    timeout=600.0,        # งบประมาณรวมเป็นวินาที; ค่าเริ่มต้น 1200 (20 นาที)
    on_progress=lambda pos: print(f"คิว: {pos}"),
)
done["translations"]["de"]

แบบ Async:

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

สถานะ API: pending, processing, completed, failed.

ข้อยกเว้น

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)

รูปแบบงาน Async (สรุป)

1. ด้วยตนเอง: jobs.create → วนลูป jobs.get จนถึงสถานะสุดท้าย
2. ตัวช่วย: jobs.translate พร้อม poll_interval, timeout และ on_progress (ถ้ามี)

แนะนำใช้ jobs สำหรับเนื้อหาขนาดใหญ่มากที่ translate แบบ synchronous อาจเจอปัญหา timeout ของไคลเอนต์หรือเซิร์ฟเวอร์

ประเภท

แพ็กเกจมี py.typed วัตถุตอบกลับเป็นค่า dict ธรรมดาที่สอดคล้องกับ API; ใช้การระบุชนิดแบบ TypedDict ในโค้ดของคุณถ้าต้องการ

ประวัติการเปลี่ยนแปลง

0.1.2

• บำรุงรักษา: URL พื้นฐานของ API เริ่มต้นเป็น https://api.usepolylingo.com/v1

0.1.0

• เวอร์ชันแรก: sync PolyLingo, async AsyncPolyLingo, ครอบคลุม endpoint ทั้งหมดรวมถึงตัวช่วย polling jobs.translate