Python SDK (polylingo)

العميل الرسمي لـ Python لواجهة برمجة تطبيقات PolyLingo REST. يستخدم httpx ويوفر عملاء متزامنين وغير متزامنين بنفس أسماء الطرق.

• PyPI: polylingo
• المصدر: UsePolyLingo/polylingo-python

للحصول على تفاصيل HTTP الخام، راجع مرجع API.

التثبيت

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"])

استخدم await client.aclose() إذا لم تستخدم async with.

أسماء الطرق تطابق العميل المتزامن؛ جميع طرق الشبكة هي 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 غير المتزامن، تغطية كاملة للنقاط النهائية بما في ذلك مساعد استطلاع jobs.translate.