tarjamli 0.1.0__tar.gz

tarjamli-0.1.0/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Omneity Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

tarjamli-0.1.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: tarjamli
+Version: 0.1.0
+Summary: Python client for Tarjamli translation through Sawalni API
+Author-email: Omar Kamali <omar@omneitylabs.com>
+License-Expression: MIT
+Project-URL: Homepage, https://api.sawalni.com
+Project-URL: Issues, https://github.com/omneity-labs/starter-translation/issues
+Project-URL: Examples, https://github.com/omneity-labs/starter-translation
+Keywords: translation,darija,amazigh,tarjamli,sawalni
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# tarjamli
+
+A small Python client for Tarjamli translation through the [Sawalni API](https://api.sawalni.com). Translate text, convert Darija between Arabic and Latin scripts, and give the translation context about tone, gender or address forms.
+
+Python 3.10+. No runtime dependencies.
+
+## Install
+
+```sh
+pip install tarjamli
+```
+
+Set your Sawalni API key:
+
+```sh
+export SAWALNI_API_KEY="your-key"
+```
+
+## Translate
+
+```python
+from tarjamli import Tarjamli
+
+client = Tarjamli()
+result = client.translate(
+    "واش تقدر تصيفط ليا الدوسي؟",
+    source="ary_Arab",
+    target="fra_Latn",
+    instructions="Address one person formally using vous.",
+)
+print(result.text)
+```
+
+Pass your own text. Remove `instructions` for ordinary translation, or change it to supply context. The API field is `instructions`; tone and gender are not separate parameters.
+
+## Convert Darija scripts
+
+```python
+result = client.translate(
+    "سلام، كيف داير؟",
+    source="ary_Arab",
+    target="ary_Latn",
+)
+print(result.text)
+```
+
+Reverse the source and target for Latin → Arabic. Use `client.languages()` to list supported language and script codes, including `shi_Latn` for Tachelhit and `zgh_Tfng` for Tamazight in Tifinagh.
+
+## CLI
+
+```sh
+tarjamli translate --text 'واش تقدر تصيفط ليا الدوسي؟' --source ary_Arab --target fra_Latn --instructions 'Address one person formally using vous.'
+tarjamli languages
+```
+
+Use `--text -` to read standard input. Add `--json` for the full API response.
+
+## Configuration and results
+
+`Tarjamli(api_key=None, timeout=180)` reads `SAWALNI_API_KEY` when no key is passed. Keep keys in server-side code or your terminal environment. The package does not load `.env` files.
+
+`translate(text, *, source, target, instructions="", model="tarjamli-mini-v4")` returns a `Translation` with `text`, `source`, `target`, `model`, and `raw` (the full response, including usage when supplied). This release supports the checked Mini model only.
+
+Each call sends one request to `POST https://api.sawalni.com/v1/language/translate`. Live requests use your API balance. There are no automatic retries.
+
+## Errors
+
+```python
+from tarjamli import AuthenticationError, RateLimitError, TranslationError
+
+try:
+    result = client.translate("Hello", source="eng_Latn", target="ary_Arab")
+except AuthenticationError:
+    # Check your key and model access.
+    raise
+except RateLimitError:
+    # Decide when to retry in your application.
+    raise
+except TranslationError:
+    # Includes incomplete responses, connection errors and unexpected identities.
+    raise
+```
+
+Invalid local input raises `ValueError`. Incomplete output raises `IncompleteTranslationError`, a subclass of `TranslationError`. The client checks the returned model and language codes before returning a result.
+
+[More examples](https://github.com/omneity-labs/starter-translation) · [API documentation](https://api.sawalni.com/docs) · [MIT license](LICENSE).

tarjamli-0.1.0/README.md

@@ -0,0 +1,86 @@
+# tarjamli
+
+A small Python client for Tarjamli translation through the [Sawalni API](https://api.sawalni.com). Translate text, convert Darija between Arabic and Latin scripts, and give the translation context about tone, gender or address forms.
+
+Python 3.10+. No runtime dependencies.
+
+## Install
+
+```sh
+pip install tarjamli
+```
+
+Set your Sawalni API key:
+
+```sh
+export SAWALNI_API_KEY="your-key"
+```
+
+## Translate
+
+```python
+from tarjamli import Tarjamli
+
+client = Tarjamli()
+result = client.translate(
+    "واش تقدر تصيفط ليا الدوسي؟",
+    source="ary_Arab",
+    target="fra_Latn",
+    instructions="Address one person formally using vous.",
+)
+print(result.text)
+```
+
+Pass your own text. Remove `instructions` for ordinary translation, or change it to supply context. The API field is `instructions`; tone and gender are not separate parameters.
+
+## Convert Darija scripts
+
+```python
+result = client.translate(
+    "سلام، كيف داير؟",
+    source="ary_Arab",
+    target="ary_Latn",
+)
+print(result.text)
+```
+
+Reverse the source and target for Latin → Arabic. Use `client.languages()` to list supported language and script codes, including `shi_Latn` for Tachelhit and `zgh_Tfng` for Tamazight in Tifinagh.
+
+## CLI
+
+```sh
+tarjamli translate --text 'واش تقدر تصيفط ليا الدوسي؟' --source ary_Arab --target fra_Latn --instructions 'Address one person formally using vous.'
+tarjamli languages
+```
+
+Use `--text -` to read standard input. Add `--json` for the full API response.
+
+## Configuration and results
+
+`Tarjamli(api_key=None, timeout=180)` reads `SAWALNI_API_KEY` when no key is passed. Keep keys in server-side code or your terminal environment. The package does not load `.env` files.
+
+`translate(text, *, source, target, instructions="", model="tarjamli-mini-v4")` returns a `Translation` with `text`, `source`, `target`, `model`, and `raw` (the full response, including usage when supplied). This release supports the checked Mini model only.
+
+Each call sends one request to `POST https://api.sawalni.com/v1/language/translate`. Live requests use your API balance. There are no automatic retries.
+
+## Errors
+
+```python
+from tarjamli import AuthenticationError, RateLimitError, TranslationError
+
+try:
+    result = client.translate("Hello", source="eng_Latn", target="ary_Arab")
+except AuthenticationError:
+    # Check your key and model access.
+    raise
+except RateLimitError:
+    # Decide when to retry in your application.
+    raise
+except TranslationError:
+    # Includes incomplete responses, connection errors and unexpected identities.
+    raise
+```
+
+Invalid local input raises `ValueError`. Incomplete output raises `IncompleteTranslationError`, a subclass of `TranslationError`. The client checks the returned model and language codes before returning a result.
+
+[More examples](https://github.com/omneity-labs/starter-translation) · [API documentation](https://api.sawalni.com/docs) · [MIT license](LICENSE).

tarjamli-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tarjamli"
+version = "0.1.0"
+description = "Python client for Tarjamli translation through Sawalni API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{name = "Omar Kamali", email = "omar@omneitylabs.com"}]
+keywords = ["translation", "darija", "amazigh", "tarjamli", "sawalni"]
+classifiers = ["Development Status :: 3 - Alpha", "Intended Audience :: Developers", "Programming Language :: Python :: 3", "Topic :: Text Processing :: Linguistic"]
+dependencies = []
+
+[project.scripts]
+tarjamli = "tarjamli.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+tarjamli = ["languages.json", "py.typed"]
+
+[project.urls]
+Homepage = "https://api.sawalni.com"
+Issues = "https://github.com/omneity-labs/starter-translation/issues"
+Examples = "https://github.com/omneity-labs/starter-translation"

tarjamli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tarjamli-0.1.0/src/tarjamli/__init__.py

@@ -0,0 +1,5 @@
+"""Tarjamli translation client for Sawalni API."""
+from .client import (Tarjamli, Translation, TranslationError, AuthenticationError,
+                     RateLimitError, IncompleteTranslationError)
+__all__ = ["Tarjamli", "Translation", "TranslationError", "AuthenticationError",
+           "RateLimitError", "IncompleteTranslationError"]

tarjamli-0.1.0/src/tarjamli/__main__.py

@@ -0,0 +1,2 @@
+from .cli import main
+main()

tarjamli-0.1.0/src/tarjamli/cli.py

@@ -0,0 +1,26 @@
+import argparse
+import json
+import sys
+from . import Tarjamli, TranslationError
+
+def main():
+    parser = argparse.ArgumentParser(prog="tarjamli")
+    commands = parser.add_subparsers(dest="command", required=True)
+    commands.add_parser("languages", help="List language and script codes")
+    command = commands.add_parser("translate", help="Translate text; use --text - to read stdin")
+    command.add_argument("--text", required=True)
+    command.add_argument("--source", required=True)
+    command.add_argument("--target", required=True)
+    command.add_argument("--instructions", default="")
+    command.add_argument("--json", action="store_true", help="Print the full API response")
+    args = parser.parse_args()
+    if args.command == "languages":
+        print(json.dumps(Tarjamli.languages(), ensure_ascii=False, indent=2))
+        return
+    try:
+        text = sys.stdin.read() if args.text == "-" else args.text
+        result = Tarjamli().translate(text, source=args.source, target=args.target, instructions=args.instructions)
+        print(json.dumps(result.raw, ensure_ascii=False, indent=2) if args.json else result.text)
+    except (TranslationError, ValueError) as error:
+        print(str(error), file=sys.stderr)
+        raise SystemExit(1)

tarjamli-0.1.0/src/tarjamli/client.py

@@ -0,0 +1,95 @@
+"""Small standard-library client for Tarjamli Mini v4. Python 3.10+."""
+import json
+import os
+import urllib.error
+import urllib.request
+from importlib.resources import files
+
+ENDPOINT = "https://api.sawalni.com/v1/language/translate"
+LANGUAGES = json.loads(files("tarjamli").joinpath("languages.json").read_text())
+
+class TranslationError(RuntimeError):
+    """A request failed or returned an unusable translation."""
+
+class AuthenticationError(TranslationError):
+    pass
+
+class RateLimitError(TranslationError):
+    pass
+
+class IncompleteTranslationError(TranslationError):
+    pass
+
+def make_request(text, source, target, instructions="", *, model="tarjamli-mini-v4"):
+    if model not in ("tarjamli-mini-v4",):
+        raise ValueError("Unsupported model")
+    if not isinstance(text, str) or not text.strip():
+        raise ValueError("text must be nonempty")
+    if len(text.encode("utf-8")) > 262144:
+        raise ValueError("text exceeds 262144 UTF-8 bytes")
+    if source not in LANGUAGES or target not in LANGUAGES:
+        raise ValueError("Use explicit supported source and target codes from languages.json")
+    if not isinstance(instructions, str) or len(instructions.encode("utf-8")) > 32768:
+        raise ValueError("instructions must be a string of at most 32768 UTF-8 bytes")
+    payload = dict(model=model, text=text, source=source, target=target)
+    if instructions.strip():
+        payload["instructions"] = instructions
+    return payload
+
+def translate(text, source, target, instructions="", *, api_key=None, timeout=180, model="tarjamli-mini-v4"):
+    payload = make_request(text, source, target, instructions, model=model)
+    key = api_key or os.environ.get("SAWALNI_API_KEY")
+    if not key:
+        raise AuthenticationError("Set SAWALNI_API_KEY in your shell or pass api_key")
+    request = urllib.request.Request(ENDPOINT, data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
+        headers={"Authorization": "Bearer " + key, "Content-Type": "application/json", "User-Agent": "Sawalni-Tarjamli-Starter/1.0"})
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            body = json.load(response)
+    except urllib.error.HTTPError as error:
+        error_type = AuthenticationError if error.code in (401, 403) else RateLimitError if error.code == 429 else TranslationError
+        raise error_type(f"Translation HTTP {error.code}; check access, input and API status. No automatic retry.") from None
+    except (urllib.error.URLError, TimeoutError):
+        raise TranslationError("Translation connection failed or timed out. Check before retrying; the request may have run.") from None
+    except (ValueError, UnicodeError):
+        raise TranslationError("API returned invalid JSON") from None
+    data = body.get("data") if isinstance(body, dict) else None
+    if not isinstance(data, dict) or not isinstance(data.get("translated"), str) or not data["translated"].strip():
+        raise TranslationError("API returned no translation")
+    if data.get("complete") is not True:
+        raise IncompleteTranslationError("Translation is incomplete; shorten the input before trying again")
+    if data.get("source") != source or data.get("target") != target or data.get("model") != payload["model"]:
+        raise TranslationError("Unexpected response model or language identity")
+    return body
+
+
+from dataclasses import dataclass
+from typing import Any
+
+@dataclass(frozen=True)
+class Translation:
+    """Translation text and the full API response, including usage when provided."""
+    text: str
+    source: str
+    target: str
+    model: str
+    raw: dict[str, Any]
+
+class Tarjamli:
+    """Synchronous client. Requests are never retried automatically."""
+    def __init__(self, api_key: str | None = None, *, timeout: float = 180) -> None:
+        if timeout <= 0:
+            raise ValueError("timeout must be positive")
+        self._api_key = api_key
+        self.timeout = timeout
+
+    @staticmethod
+    def languages() -> dict[str, str]:
+        """Return a copy of the supported language-code mapping."""
+        return dict(LANGUAGES)
+
+    def translate(self, text: str, *, source: str, target: str, instructions: str = "", model: str = "tarjamli-mini-v4") -> Translation:
+        body = translate(text, source, target, instructions, api_key=self._api_key,
+                         timeout=self.timeout, model=model)
+        data = body["data"]
+        return Translation(data["translated"], data["source"], data["target"], data["model"], body)

tarjamli-0.1.0/src/tarjamli/languages.json

@@ -0,0 +1,56 @@
+{
+  "ary_Arab": "Moroccan Arabic",
+  "ary_Latn": "Moroccan Arabic written in Latin script",
+  "shi_Latn": "Tachelhit written in Latin script",
+  "zgh_Tfng": "Standard Moroccan Tamazight written in Tifinagh script",
+  "amh_Ethi": "Amharic",
+  "arb_Arab": "Modern Standard Arabic",
+  "ben_Beng": "Bengali",
+  "ces_Latn": "Czech",
+  "cmn_Hans": "Simplified Chinese",
+  "dan_Latn": "Danish",
+  "deu_Latn": "German",
+  "ell_Grek": "Greek",
+  "eng_Latn": "English",
+  "fin_Latn": "Finnish",
+  "fra_Latn": "French",
+  "guj_Gujr": "Gujarati",
+  "hau_Latn": "Hausa",
+  "heb_Hebr": "Hebrew",
+  "hin_Deva": "Hindi",
+  "hun_Latn": "Hungarian",
+  "ind_Latn": "Indonesian",
+  "ita_Latn": "Italian",
+  "jpn_Jpan": "Japanese",
+  "kan_Knda": "Kannada",
+  "khm_Khmr": "Khmer",
+  "kor_Hang": "Korean",
+  "lao_Laoo": "Lao",
+  "mal_Mlym": "Malayalam",
+  "mar_Deva": "Marathi",
+  "mya_Mymr": "Burmese",
+  "nld_Latn": "Dutch",
+  "nob_Latn": "Norwegian Bokmål",
+  "npi_Deva": "Nepali",
+  "pan_Guru": "Punjabi written in Gurmukhi",
+  "pes_Arab": "Persian",
+  "pol_Latn": "Polish",
+  "por_Latn": "Portuguese",
+  "ron_Latn": "Romanian",
+  "rus_Cyrl": "Russian",
+  "sin_Sinh": "Sinhala",
+  "som_Latn": "Somali",
+  "spa_Latn": "Spanish",
+  "swe_Latn": "Swedish",
+  "swh_Latn": "Swahili",
+  "tam_Taml": "Tamil",
+  "tel_Telu": "Telugu",
+  "tha_Thai": "Thai",
+  "tur_Latn": "Turkish",
+  "ukr_Cyrl": "Ukrainian",
+  "urd_Arab": "Urdu",
+  "vie_Latn": "Vietnamese",
+  "yor_Latn": "Yoruba",
+  "zsm_Latn": "Malay",
+  "zul_Latn": "Zulu"
+}

tarjamli-0.1.0/src/tarjamli.egg-info/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: tarjamli
+Version: 0.1.0
+Summary: Python client for Tarjamli translation through Sawalni API
+Author-email: Omar Kamali <omar@omneitylabs.com>
+License-Expression: MIT
+Project-URL: Homepage, https://api.sawalni.com
+Project-URL: Issues, https://github.com/omneity-labs/starter-translation/issues
+Project-URL: Examples, https://github.com/omneity-labs/starter-translation
+Keywords: translation,darija,amazigh,tarjamli,sawalni
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# tarjamli
+
+A small Python client for Tarjamli translation through the [Sawalni API](https://api.sawalni.com). Translate text, convert Darija between Arabic and Latin scripts, and give the translation context about tone, gender or address forms.
+
+Python 3.10+. No runtime dependencies.
+
+## Install
+
+```sh
+pip install tarjamli
+```
+
+Set your Sawalni API key:
+
+```sh
+export SAWALNI_API_KEY="your-key"
+```
+
+## Translate
+
+```python
+from tarjamli import Tarjamli
+
+client = Tarjamli()
+result = client.translate(
+    "واش تقدر تصيفط ليا الدوسي؟",
+    source="ary_Arab",
+    target="fra_Latn",
+    instructions="Address one person formally using vous.",
+)
+print(result.text)
+```
+
+Pass your own text. Remove `instructions` for ordinary translation, or change it to supply context. The API field is `instructions`; tone and gender are not separate parameters.
+
+## Convert Darija scripts
+
+```python
+result = client.translate(
+    "سلام، كيف داير؟",
+    source="ary_Arab",
+    target="ary_Latn",
+)
+print(result.text)
+```
+
+Reverse the source and target for Latin → Arabic. Use `client.languages()` to list supported language and script codes, including `shi_Latn` for Tachelhit and `zgh_Tfng` for Tamazight in Tifinagh.
+
+## CLI
+
+```sh
+tarjamli translate --text 'واش تقدر تصيفط ليا الدوسي؟' --source ary_Arab --target fra_Latn --instructions 'Address one person formally using vous.'
+tarjamli languages
+```
+
+Use `--text -` to read standard input. Add `--json` for the full API response.
+
+## Configuration and results
+
+`Tarjamli(api_key=None, timeout=180)` reads `SAWALNI_API_KEY` when no key is passed. Keep keys in server-side code or your terminal environment. The package does not load `.env` files.
+
+`translate(text, *, source, target, instructions="", model="tarjamli-mini-v4")` returns a `Translation` with `text`, `source`, `target`, `model`, and `raw` (the full response, including usage when supplied). This release supports the checked Mini model only.
+
+Each call sends one request to `POST https://api.sawalni.com/v1/language/translate`. Live requests use your API balance. There are no automatic retries.
+
+## Errors
+
+```python
+from tarjamli import AuthenticationError, RateLimitError, TranslationError
+
+try:
+    result = client.translate("Hello", source="eng_Latn", target="ary_Arab")
+except AuthenticationError:
+    # Check your key and model access.
+    raise
+except RateLimitError:
+    # Decide when to retry in your application.
+    raise
+except TranslationError:
+    # Includes incomplete responses, connection errors and unexpected identities.
+    raise
+```
+
+Invalid local input raises `ValueError`. Incomplete output raises `IncompleteTranslationError`, a subclass of `TranslationError`. The client checks the returned model and language codes before returning a result.
+
+[More examples](https://github.com/omneity-labs/starter-translation) · [API documentation](https://api.sawalni.com/docs) · [MIT license](LICENSE).

tarjamli-0.1.0/src/tarjamli.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+src/tarjamli/__init__.py
+src/tarjamli/__main__.py
+src/tarjamli/cli.py
+src/tarjamli/client.py
+src/tarjamli/languages.json
+src/tarjamli/py.typed
+src/tarjamli.egg-info/PKG-INFO
+src/tarjamli.egg-info/SOURCES.txt
+src/tarjamli.egg-info/dependency_links.txt
+src/tarjamli.egg-info/entry_points.txt
+src/tarjamli.egg-info/top_level.txt
+tests/test_client.py
+tests/test_public_api.py

tarjamli-0.1.0/src/tarjamli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

tarjamli-0.1.0/src/tarjamli.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tarjamli = tarjamli.cli:main

tarjamli-0.1.0/src/tarjamli.egg-info/top_level.txt

@@ -0,0 +1 @@
+tarjamli

tarjamli-0.1.0/tests/test_client.py

@@ -0,0 +1,40 @@
+import io, json, sys, unittest, urllib.error
+from pathlib import Path
+from unittest.mock import patch
+
+from tarjamli.client import translate, make_request, TranslationError
+
+def body(**change):
+    data = dict(translated="Pouvez-vous m'envoyer le document ?", complete=True, source="eng_Latn", target="fra_Latn", model="tarjamli-mini-v4")
+    data.update(change)
+    return io.BytesIO(json.dumps(dict(data=data)).encode())
+
+class ClientTests(unittest.TestCase):
+    def test_wire_request_and_auth(self):
+        with patch("urllib.request.urlopen", return_value=body()) as call:
+            result = translate("واش؟", "eng_Latn", "fra_Latn", "Use vous.", api_key="test-only")
+        request = call.call_args.args[0]
+        self.assertEqual(request.full_url, "https://api.sawalni.com/v1/language/translate")
+        self.assertEqual(request.get_header("Authorization"), "Bearer test-only")
+        payload = json.loads(request.data)
+        self.assertEqual(payload["text"], "واش؟")
+        self.assertEqual(payload["instructions"], "Use vous.")
+        self.assertNotIn("test-only", request.data.decode())
+        self.assertTrue(result["data"]["complete"])
+    def test_incomplete_and_identity_mismatch(self):
+        for changes in [dict(complete=False),dict(target="deu_Latn"),dict(model="other"),dict(translated="")]:
+            with self.subTest(changes=changes), patch("urllib.request.urlopen", return_value=body(**changes)):
+                with self.assertRaises(TranslationError): translate("hello", "eng_Latn", "fra_Latn", api_key="test-only")
+    def test_utf8_limit_and_explicit_language(self):
+        for args in [("x", "auto", "fra_Latn"),("é"*131073,"eng_Latn","fra_Latn")]:
+            with self.assertRaises(ValueError): make_request(*args)
+        with self.assertRaises(ValueError): make_request("x","eng_Latn","fra_Latn","é"*16385)
+    def test_no_silent_retry_or_secret_in_error(self):
+        error = urllib.error.HTTPError("https://api.sawalni.com",429,"busy",{},None)
+        with patch("urllib.request.urlopen", side_effect=error) as call:
+            with self.assertRaisesRegex(TranslationError,"HTTP 429") as caught:
+                translate("hello","eng_Latn","fra_Latn",api_key="test-only")
+        self.assertEqual(call.call_count,1)
+        self.assertNotIn("test-only",str(caught.exception))
+
+if __name__ == "__main__": unittest.main()

tarjamli-0.1.0/tests/test_public_api.py

@@ -0,0 +1,44 @@
+import io
+import json
+import unittest
+import urllib.error
+from unittest.mock import patch
+from tarjamli import Tarjamli, TranslationError, AuthenticationError, RateLimitError, IncompleteTranslationError
+
+class PublicAPI(unittest.TestCase):
+    def response(self, **changes):
+        data = dict(translated='Bonjour', source='eng_Latn', target='fra_Latn', model='tarjamli-mini-v4', complete=True)
+        data.update(changes)
+        return io.BytesIO(json.dumps({'data': data, 'usage': {'tokens': 4}}).encode())
+
+    def test_public_result_and_environment_key(self):
+        with patch.dict('os.environ', {'SAWALNI_API_KEY':'private-test-key'}), patch('urllib.request.urlopen', return_value=self.response()) as call:
+            result = Tarjamli(timeout=10).translate('Hello', source='eng_Latn', target='fra_Latn')
+        self.assertEqual(result.text, 'Bonjour')
+        self.assertEqual(result.raw['usage']['tokens'], 4)
+        self.assertEqual(call.call_args.kwargs['timeout'], 10)
+
+    def test_typed_errors_without_retries(self):
+        for status, expected in [(401, AuthenticationError), (403, AuthenticationError), (429, RateLimitError), (500, TranslationError)]:
+            with patch('urllib.request.urlopen', side_effect=urllib.error.HTTPError('https://api.sawalni.com', status, '', {}, None)) as call:
+                with self.assertRaises(expected):
+                    Tarjamli('secret').translate('Hello', source='eng_Latn', target='fra_Latn')
+                self.assertEqual(call.call_count, 1)
+        with patch('urllib.request.urlopen', return_value=self.response(complete=False)):
+            with self.assertRaises(IncompleteTranslationError):
+                Tarjamli('secret').translate('Hello', source='eng_Latn', target='fra_Latn')
+
+    def test_language_copy_and_model_guard(self):
+        languages = Tarjamli.languages()
+        languages.clear()
+        self.assertIn('zgh_Tfng', Tarjamli.languages())
+        with patch('urllib.request.urlopen') as call:
+            with self.assertRaises(ValueError):
+                Tarjamli('secret').translate('Hello', source='eng_Latn', target='fra_Latn', model='unknown')
+            call.assert_not_called()
+
+    def test_cli_stdin(self):
+        from tarjamli.cli import main
+        with patch('sys.argv', ['tarjamli','translate','--text','-','--source','eng_Latn','--target','fra_Latn']), patch('sys.stdin', io.StringIO('Hello')), patch('sys.stdout', new_callable=io.StringIO) as stdout, patch('urllib.request.urlopen', return_value=self.response()), patch.dict('os.environ', {'SAWALNI_API_KEY':'test'}):
+            main()
+        self.assertEqual(stdout.getvalue(), 'Bonjour\n')