Python SDK (polylingo)

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

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

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

التثبيت

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

استخدم 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.2

• صيانة: عنوان API الأساسي الافتراضي هو https://api.usepolylingo.com/v1.

0.1.0

• الإصدار الأولي: PolyLingo المتزامن، AsyncPolyLingo غير المتزامن، تغطية كاملة للنقاط النهائية بما في ذلك مساعد استطلاع jobs.translate.