Python SDK (polylingo)

کلاینت رسمی پایتون برای PolyLingo REST API. از httpx استفاده می‌کند و هر دو کلاینت همزمان و غیرهمزمان را با نام‌های متد یکسان ارائه می‌دهد.

• 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="# Hello", targets=["es", "fr"], format="markdown")
print(result["translations"]["es"])

client.close()

مدیریت‌کننده زمینه:

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

کلاینت غیرهمزمان

import polylingo

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

اگر از async with استفاده نمی‌کنید، از await client.aclose() استفاده کنید.

نام متدها با کلاینت همزمان مطابقت دارد؛ همه متدهای شبکه async def هستند.

متدها (همزمان و غیرهمزمان)

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",  # اختیاری
    source="en",        # اختیاری
    model="standard",   # اختیاری: "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()

شغل‌ها — 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"Queue: {pos}"),
)
done["translations"]["de"]

غیرهمزمان:

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)

الگوی شغل‌های غیرهمزمان (خلاصه)

1. دستی: jobs.create → حلقه jobs.get تا وضعیت نهایی.
2. کمک‌کننده: jobs.translate با poll_interval، timeout و اختیاری on_progress.

برای محتوای بسیار بزرگ که ممکن است translate همزمان به تایم‌اوت کلاینت یا سرور برسد، شغل‌ها را ترجیح دهید.

نوع‌ها

بسته شامل py.typed است. اشیاء پاسخ مقادیر ساده dict همسو با API هستند؛ در صورت تمایل از حاشیه‌نویسی‌های TypedDict در کد خود استفاده کنید.

تغییرات

0.1.0

• انتشار اولیه: PolyLingo همزمان، AsyncPolyLingo غیرهمزمان، پوشش کامل endpointها از جمله کمک‌کننده polling jobs.translate.