Python SDK (polylingo)

PolyLingo REST API-এর জন্য অফিসিয়াল পাইথন ক্লায়েন্ট। এটি 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()

কাজসমূহ (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।

এক্সসেপশনসমূহ

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 কাজের প্যাটার্ন (সারাংশ)

1. ম্যানুয়াল: jobs.create → লুপ jobs.get যতক্ষণ না টার্মিনাল স্টেট।
2. হেল্পার: jobs.translate poll_interval, timeout, এবং ঐচ্ছিক on_progress সহ।

খুব বড় কনটেন্টের জন্য কাজগুলো প্রেফার করুন যেখানে synchronous translate ক্লায়েন্ট বা সার্ভার টাইমআউট পেতে পারে।

টাইপসমূহ

প্যাকেজটি py.typed নিয়ে আসে। রেসপন্স অবজেক্টগুলো সাধারণ dict মান যা API এর সাথে সামঞ্জস্যপূর্ণ; আপনার কোডে TypedDict-স্টাইল অ্যানোটেশন ব্যবহার করুন যদি ইচ্ছা হয়।

চেঞ্জলগ

0.1.2

• রক্ষণাবেক্ষণ: ডিফল্ট API বেস URL হল https://api.usepolylingo.com/v1।

0.1.0

• প্রাথমিক রিলিজ: sync PolyLingo, async AsyncPolyLingo, সম্পূর্ণ এন্ডপয়েন্ট কভারেজ সহ jobs.translate পোলিং হেল্পার।