translatarr-client 0.2.1__tar.gz

translatarr_client-0.2.1/.gitignore

@@ -0,0 +1,208 @@
+# Based on https://raw.githubusercontent.com/github/gitignore/main/Node.gitignore
+
+# Logs
+
+logs
+_.log
+npm-debug.log_
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+.pnpm-debug.log*
+
+# Caches
+
+.cache
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+
+report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
+
+# Runtime data
+
+pids
+_.pid
+_.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+
+lib-cov
+
+# Coverage directory used by tools like istanbul
+
+coverage
+*.lcov
+
+# nyc test coverage
+
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+
+bower_components
+
+# node-waf configuration
+
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+
+build/Release
+
+# Dependency directories
+
+node_modules/
+jspm_packages/
+
+# Snowpack dependency directory (https://snowpack.dev/)
+
+web_modules/
+
+# TypeScript cache
+
+*.tsbuildinfo
+
+# Optional npm cache directory
+
+.npm
+
+# Optional eslint cache
+
+.eslintcache
+
+# Optional stylelint cache
+
+.stylelintcache
+
+# Microbundle cache
+
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+
+# Optional REPL history
+
+.node_repl_history
+
+# Output of 'npm pack'
+
+*.tgz
+
+# Yarn Integrity file
+
+.yarn-integrity
+
+# dotenv environment variable files
+
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# parcel-bundler cache (https://parceljs.org/)
+
+.parcel-cache
+
+# Next.js build output
+
+.next
+out
+next-env.d.ts
+
+# Nuxt.js build / generate output
+
+.nuxt
+dist
+
+# Gatsby files
+
+# Comment in the public line in if your project uses Gatsby and not Next.js
+
+# https://nextjs.org/blog/next-9-1#public-directory-support
+
+# public
+
+# vuepress build output
+
+.vuepress/dist
+
+# vuepress v2.x temp and cache directory
+
+.temp
+
+# Docusaurus cache and generated files
+
+.docusaurus
+
+# Serverless directories
+
+.serverless/
+
+# FuseBox cache
+
+.fusebox/
+
+# DynamoDB Local files
+
+.dynamodb/
+
+# TernJS port file
+
+.tern-port
+
+# Stores VSCode versions used for testing VSCode extensions
+
+.vscode-test
+
+# yarn v2
+
+.yarn/cache
+.yarn/unplugged
+.yarn/build-state.yml
+.yarn/install-state.gz
+.pnp.*
+
+# IntelliJ based IDEs
+.idea
+
+# Finder (MacOS) folder config
+.DS_Store
+
+
+# app data
+data
+
+# generated Swagger UI assets (copied from swagger-ui-dist at dev/build time)
+.swagger-ui
+
+clients/python/.venv
+clients/python/openapi.json
+
+# TypeScript client: regenerated spec, build output, deps, packed tarballs
+clients/typescript/openapi.json
+clients/typescript/dist/
+clients/typescript/node_modules/
+clients/typescript/*.tgz
+
+# Rust client: regenerated spec/schema, build output, lockfile (library crate)
+clients/rust/openapi.json
+clients/rust/schema.json
+clients/rust/target/
+clients/rust/Cargo.lock
+__pycache__
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+build/
+dist/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/

translatarr_client-0.2.1/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: translatarr-client
+Version: 0.2.1
+Summary: Synchronous and asynchronous Python client for the Translatarr API.
+Author: joshrmcdaniel
+License: AGPL-3.0-or-later
+Keywords: api,client,llm,translatarr,translation
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.24
+Requires-Dist: pydantic>=2.4
+Provides-Extra: codegen
+Requires-Dist: datamodel-code-generator>=0.65; extra == 'codegen'
+Description-Content-Type: text/markdown
+
+# translatarr-client
+
+A typed Python client for the [Translatarr](../../README.md) API — synchronous
+and asynchronous, with pydantic response models generated from the server's
+OpenAPI spec.
+
+## Install
+
+```bash
+pip install translatarr-client
+```
+
+Published to [PyPI](https://pypi.org/project/translatarr-client/) for each `v*`
+tag (the version matches the app's tag). The same wheel + sdist are also
+attached to the corresponding GitHub Release, and you can install straight from
+this repo:
+
+```bash
+# from a published GitHub Release (version matches the app's v* tag)
+pip install https://github.com/joshrmcdaniel/translatarr/releases/download/v1.2.3/translatarr_client-1.2.3-py3-none-any.whl
+
+# or straight from this repo
+pip install -e clients/python
+```
+
+Requires Python 3.10+.
+
+## Authentication
+
+Mint a personal API key in the web UI under **Settings → API keys** (tokens are
+prefixed `tra_` and shown only once). Pass it as `token`:
+
+```python
+from translatarr import TranslatarrClient
+
+with TranslatarrClient("https://translatarr.example", token="tra_…") as tra:
+    result = tra.translate("Good morning", source_lang="en", target_lang="ja")
+    best = result.translations[0]
+    print(best.text, best.romanization)
+```
+
+A browser session cookie works too, via `session_cookie="…"` instead of `token`.
+
+## Async
+
+`AsyncTranslatarrClient` mirrors the sync client method-for-method:
+
+```python
+import asyncio
+from translatarr import AsyncTranslatarrClient
+
+async def main() -> None:
+    async with AsyncTranslatarrClient("https://translatarr.example", token="tra_…") as tra:
+        result = await tra.translate("Bonjour", source_lang="auto", target_lang="en")
+        print(result.detected_source_language, result.translations[0].text)
+
+asyncio.run(main())
+```
+
+## What you can do
+
+| Area      | Methods |
+| --------- | ------- |
+| Translate | `translate` |
+| Chats     | `list_chats`, `create_chat`, `get_chat`, `rename_chat`, `clear_chat`, `delete_chat` |
+| Turns     | `add_turn`, `select_option`, `retranslate_turn`, `switch_branch` |
+| Speech    | `transcribe`, `synthesize` |
+| API keys  | `list_keys`, `create_key`, `revoke_key` |
+
+### Persisting a chat without paying for a second translation
+
+`translate` does not store anything; `add_turn` translates *and* persists. To
+avoid a duplicate LLM call, pass the `result` you already have:
+
+```python
+chat = tra.create_chat(source_lang="en", target_lang="ja")
+preview = tra.translate("Let's ship it", source_lang="en", target_lang="ja", chat_id=chat.id)
+chat = tra.add_turn(chat.id, "Let's ship it", source_lang="en", target_lang="ja", result=preview)
+```
+
+### Errors
+
+Failures raise a subclass of `translatarr.APIError`, each carrying `status_code`,
+the server's `code` (when present), and the raw `response`:
+
+| Exception | Status |
+| --------- | ------ |
+| `InvalidRequestError`   | 400 |
+| `AuthenticationError`   | 401 |
+| `ForbiddenError`        | 403 |
+| `NotFoundError`         | 404 |
+| `ConflictError`         | 409 |
+| `MalformedResponseError`| 422 |
+| `ProviderError`         | 502 |
+
+```python
+from translatarr import NotFoundError
+
+try:
+    tra.get_chat("does-not-exist")
+except NotFoundError:
+    ...
+```
+
+## Development
+
+The response models in `src/translatarr/_models.py` are **generated** from the
+server's OpenAPI document — do not edit them by hand. To regenerate after the
+API schema changes:
+
+```bash
+# one-time tooling install
+python -m venv clients/python/.venv
+clients/python/.venv/bin/pip install -e 'clients/python[codegen]'
+
+# regenerate openapi.json + _models.py
+clients/python/scripts/regenerate.sh
+```
+
+The script dumps the spec via `bun scripts/dump-openapi.ts` (the same document
+served at `/api/docs/openapi.json`) and runs `datamodel-codegen` over it. Only
+`_models.py` is committed, so the client builds and installs without a running
+server; `openapi.json` is a regenerated, gitignored artifact.

translatarr_client-0.2.1/README.md

@@ -0,0 +1,123 @@
+# translatarr-client
+
+A typed Python client for the [Translatarr](../../README.md) API — synchronous
+and asynchronous, with pydantic response models generated from the server's
+OpenAPI spec.
+
+## Install
+
+```bash
+pip install translatarr-client
+```
+
+Published to [PyPI](https://pypi.org/project/translatarr-client/) for each `v*`
+tag (the version matches the app's tag). The same wheel + sdist are also
+attached to the corresponding GitHub Release, and you can install straight from
+this repo:
+
+```bash
+# from a published GitHub Release (version matches the app's v* tag)
+pip install https://github.com/joshrmcdaniel/translatarr/releases/download/v1.2.3/translatarr_client-1.2.3-py3-none-any.whl
+
+# or straight from this repo
+pip install -e clients/python
+```
+
+Requires Python 3.10+.
+
+## Authentication
+
+Mint a personal API key in the web UI under **Settings → API keys** (tokens are
+prefixed `tra_` and shown only once). Pass it as `token`:
+
+```python
+from translatarr import TranslatarrClient
+
+with TranslatarrClient("https://translatarr.example", token="tra_…") as tra:
+    result = tra.translate("Good morning", source_lang="en", target_lang="ja")
+    best = result.translations[0]
+    print(best.text, best.romanization)
+```
+
+A browser session cookie works too, via `session_cookie="…"` instead of `token`.
+
+## Async
+
+`AsyncTranslatarrClient` mirrors the sync client method-for-method:
+
+```python
+import asyncio
+from translatarr import AsyncTranslatarrClient
+
+async def main() -> None:
+    async with AsyncTranslatarrClient("https://translatarr.example", token="tra_…") as tra:
+        result = await tra.translate("Bonjour", source_lang="auto", target_lang="en")
+        print(result.detected_source_language, result.translations[0].text)
+
+asyncio.run(main())
+```
+
+## What you can do
+
+| Area      | Methods |
+| --------- | ------- |
+| Translate | `translate` |
+| Chats     | `list_chats`, `create_chat`, `get_chat`, `rename_chat`, `clear_chat`, `delete_chat` |
+| Turns     | `add_turn`, `select_option`, `retranslate_turn`, `switch_branch` |
+| Speech    | `transcribe`, `synthesize` |
+| API keys  | `list_keys`, `create_key`, `revoke_key` |
+
+### Persisting a chat without paying for a second translation
+
+`translate` does not store anything; `add_turn` translates *and* persists. To
+avoid a duplicate LLM call, pass the `result` you already have:
+
+```python
+chat = tra.create_chat(source_lang="en", target_lang="ja")
+preview = tra.translate("Let's ship it", source_lang="en", target_lang="ja", chat_id=chat.id)
+chat = tra.add_turn(chat.id, "Let's ship it", source_lang="en", target_lang="ja", result=preview)
+```
+
+### Errors
+
+Failures raise a subclass of `translatarr.APIError`, each carrying `status_code`,
+the server's `code` (when present), and the raw `response`:
+
+| Exception | Status |
+| --------- | ------ |
+| `InvalidRequestError`   | 400 |
+| `AuthenticationError`   | 401 |
+| `ForbiddenError`        | 403 |
+| `NotFoundError`         | 404 |
+| `ConflictError`         | 409 |
+| `MalformedResponseError`| 422 |
+| `ProviderError`         | 502 |
+
+```python
+from translatarr import NotFoundError
+
+try:
+    tra.get_chat("does-not-exist")
+except NotFoundError:
+    ...
+```
+
+## Development
+
+The response models in `src/translatarr/_models.py` are **generated** from the
+server's OpenAPI document — do not edit them by hand. To regenerate after the
+API schema changes:
+
+```bash
+# one-time tooling install
+python -m venv clients/python/.venv
+clients/python/.venv/bin/pip install -e 'clients/python[codegen]'
+
+# regenerate openapi.json + _models.py
+clients/python/scripts/regenerate.sh
+```
+
+The script dumps the spec via `bun scripts/dump-openapi.ts` (the same document
+served at `/api/docs/openapi.json`) and runs `datamodel-codegen` over it. Only
+`_models.py` is committed, so the client builds and installs without a running
+server; `openapi.json` is a regenerated, gitignored artifact.

translatarr_client-0.2.1/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "translatarr-client"
+version = "0.2.1"
+description = "Synchronous and asynchronous Python client for the Translatarr API."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "AGPL-3.0-or-later" }
+authors = [{ name = "joshrmcdaniel" }]
+keywords = ["translatarr", "translation", "llm", "api", "client"]
+dependencies = [
+    "httpx>=0.24",
+    "pydantic>=2.4",
+]
+
+[project.optional-dependencies]
+# Tooling for regenerating the pydantic models from the OpenAPI spec
+# (clients/python/scripts/regenerate.sh).
+codegen = ["datamodel-code-generator>=0.65"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/translatarr"]

translatarr_client-0.2.1/scripts/model_header.txt

@@ -0,0 +1,5 @@
+# AUTO-GENERATED FILE — DO NOT EDIT.
+#
+# Pydantic models for the Translatarr API, rendered from
+# clients/python/openapi.json (dumped from the server's Zod schemas in app/lib).
+# Regenerate with: clients/python/scripts/regenerate.sh

translatarr_client-0.2.1/scripts/regenerate.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+#
+# Regenerate the Python client's pydantic models from the server's OpenAPI spec.
+#
+# Step 1 dumps the spec (built from the Zod schemas in app/lib) to
+# clients/python/openapi.json; step 2 renders it to src/translatarr/_models.py.
+# Both outputs are committed, so the client is usable without a running server.
+#
+# Requires: bun (to run the dump script) and datamodel-code-generator (installed
+# in clients/python/.venv, or otherwise on PATH).
+
+set -euo pipefail
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+repo_root="$(cd "$script_dir/../../.." && pwd)"
+client_dir="$repo_root/clients/python"
+spec="$client_dir/openapi.json"
+out="$client_dir/src/translatarr/_models.py"
+
+echo "==> Dumping OpenAPI spec to $spec"
+bun "$repo_root/scripts/dump-openapi.ts" "$spec"
+
+codegen="$client_dir/.venv/bin/datamodel-codegen"
+if [ ! -x "$codegen" ]; then
+  codegen="datamodel-codegen"
+fi
+
+echo "==> Generating pydantic models with $codegen"
+"$codegen" \
+  --input "$spec" \
+  --input-file-type openapi \
+  --output-model-type pydantic_v2.BaseModel \
+  --output-datetime-class datetime \
+  --enum-field-as-literal all \
+  --collapse-root-models \
+  --snake-case-field \
+  --use-union-operator \
+  --use-standard-collections \
+  --use-annotated \
+  --use-schema-description \
+  --disable-timestamp \
+  --custom-file-header-path "$script_dir/model_header.txt" \
+  --target-python-version 3.10 \
+  --output "$out"
+
+echo "==> Wrote $out"

translatarr_client-0.2.1/src/translatarr/__init__.py

@@ -0,0 +1,76 @@
+"""Python client for the Translatarr API.
+
+Synchronous and asynchronous clients over the documented REST endpoints, with
+pydantic response models generated from the server's OpenAPI spec.
+
+    from translatarr import TranslatarrClient
+
+    with TranslatarrClient("https://translatarr.example", token="tra_…") as tra:
+        result = tra.translate("Good morning", source_lang="en", target_lang="ja")
+        print(result.translations[0].text)
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version as _package_version
+
+from ._errors import (
+    APIError,
+    AuthenticationError,
+    ConflictError,
+    ForbiddenError,
+    InvalidRequestError,
+    MalformedResponseError,
+    NotFoundError,
+    ProviderError,
+    TranslatarrError,
+)
+from ._models import (
+    ApiKey,
+    ChatDetail,
+    ChatSummary,
+    ChatTurn,
+    CreatedApiKey,
+    KeyWord,
+    Translation,
+    TranslationResponse,
+)
+from .aio import AsyncTranslatarrClient
+from .client import TranslatarrClient
+from .languages import AUTO_DETECT, SUPPORTED_LANGUAGE_CODES, SourceLang, TargetLang
+
+try:
+    __version__ = _package_version("translatarr-client")
+except PackageNotFoundError:  # running from a source checkout without an install
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "__version__",
+    # clients
+    "TranslatarrClient",
+    "AsyncTranslatarrClient",
+    # models
+    "ApiKey",
+    "ChatDetail",
+    "ChatSummary",
+    "ChatTurn",
+    "CreatedApiKey",
+    "KeyWord",
+    "Translation",
+    "TranslationResponse",
+    # languages
+    "AUTO_DETECT",
+    "SUPPORTED_LANGUAGE_CODES",
+    "SourceLang",
+    "TargetLang",
+    # errors
+    "TranslatarrError",
+    "APIError",
+    "InvalidRequestError",
+    "AuthenticationError",
+    "ForbiddenError",
+    "NotFoundError",
+    "ConflictError",
+    "MalformedResponseError",
+    "ProviderError",
+]