Python SDK (polylingo)

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

• PyPI: polylingo
• کد منبع: UsePolyLingo/polylingo-python

برای جزئیات خام HTTP، به API reference مراجعه کنید.

نصب

pip install polylingo

پایتون: >= 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.2

• نگهداری: URL پایه پیش‌فرض API https://api.usepolylingo.com/v1 است.

0.1.0

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