Python SDK (polylingo)

PolyLingo REST API를 위한 공식 Python 클라이언트입니다. httpx를 사용하며, 동일한 메서드 이름으로 동기(sync) 및 비동기(async) 클라이언트를 제공합니다.

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

async with를 사용하지 않을 경우 await client.aclose()를 사용하세요.

메서드 이름은 동기 클라이언트와 일치하며, 모든 네트워크 메서드는 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가 클라이언트 또는 서버 타임아웃에 걸릴 수 있는 매우 큰 콘텐츠에는 작업(jobs)을 권장합니다.

타입

패키지는 py.typed를 포함합니다. 응답 객체는 API와 일치하는 일반 dict 값이며, 필요에 따라 코드에서 TypedDict 스타일 주석을 사용하세요.

변경 로그

0.1.0

• 초기 릴리스: 동기 PolyLingo, 비동기 AsyncPolyLingo, jobs.translate 폴링 도우미를 포함한 전체 엔드포인트 지원.