Python SDK (polylingo)

Επίσημος πελάτης Python για το PolyLingo REST API. Χρησιμοποιεί το httpx και παρέχει τόσο συγχρονισμένους όσο και ασύγχρονους πελάτες με τα ίδια ονόματα μεθόδων.

• PyPI: polylingo
• Πηγαίος κώδικας: UsePolyLingo/polylingo-python

Για λεπτομέρειες σχετικά με το πρωτόκολλο HTTP, δείτε API reference.

Εγκατάσταση

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.2

• Συντήρηση: προεπιλεγμένη βάση URL API είναι https://api.usepolylingo.com/v1.

0.1.0

• Αρχική έκδοση: συγχρονισμένο PolyLingo, ασύγχρονο AsyncPolyLingo, πλήρης κάλυψη endpoint συμπεριλαμβανομένου του βοηθητικού polling jobs.translate.