Python SDK (polylingo)

PolyLingo REST API के लिए आधिकारिक Python क्लाइंट। यह httpx का उपयोग करता है और समान मेथड नामों के साथ sync और async दोनों क्लाइंट प्रदान करता है।

• PyPI: polylingo
• स्रोत: UsePolyLingo/polylingo-python

कच्चे HTTP विवरण के लिए, देखें API reference।

इंस्टॉलेशन

pip install polylingo

Python: >= 3.9

Sync क्लाइंट

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())

Async क्लाइंट

import polylingo

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

यदि async with का उपयोग नहीं कर रहे हैं तो await client.aclose() का उपयोग करें।

मेथड नाम sync क्लाइंट से मेल खाते हैं; सभी नेटवर्क मेथड 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="# 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()

Jobs — 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"]

Async:

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

API स्टेटस: pending, processing, completed, failed।

Exceptions

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 jobs पैटर्न (सारांश)

1. मैनुअल: jobs.create → लूप jobs.get जब तक टर्मिनल स्टेट न हो।
2. हेल्पर: jobs.translate के साथ poll_interval, timeout, और वैकल्पिक on_progress।

बहुत बड़े कंटेंट के लिए jobs पसंद करें जहाँ synchronous translate क्लाइंट या सर्वर टाइमआउट से टकरा सकता है।

Types

पैकेज py.typed के साथ आता है। प्रतिक्रिया ऑब्जेक्ट्स साधारण dict मान हैं जो API के अनुरूप हैं; यदि चाहें तो अपने कोड में TypedDict-शैली एनोटेशन का उपयोग करें।

Changelog

0.1.0

• प्रारंभिक रिलीज़: sync PolyLingo, async AsyncPolyLingo, पूर्ण एंडपॉइंट कवरेज जिसमें jobs.translate पोलिंग हेल्पर शामिल है।