langbly 0.1.0__tar.gz

langbly-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build dependencies
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

langbly-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Langbly
+
+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.

langbly-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: langbly
+Version: 0.1.0
+Summary: Official Python SDK for the Langbly translation API
+Project-URL: Homepage, https://langbly.com
+Project-URL: Documentation, https://langbly.com/docs
+Project-URL: Repository, https://github.com/Langbly/langbly-python
+Project-URL: Issues, https://github.com/Langbly/langbly-python/issues
+Author-email: Jasper de Winter <jasper@langbly.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,google-translate,i18n,langbly,localization,translation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.8
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# langbly-python
+
+Official Python SDK for the [Langbly](https://langbly.com) translation API — a drop-in replacement for Google Translate v2.
+
+## Installation
+
+```bash
+pip install langbly
+```
+
+## Quick Start
+
+```python
+from langbly import Langbly
+
+client = Langbly(api_key="your-api-key")
+
+# Translate text
+result = client.translate("Hello world", target="nl")
+print(result.text)  # "Hallo wereld"
+
+# Batch translate
+results = client.translate(["Hello", "Goodbye"], target="nl")
+for r in results:
+    print(r.text)
+
+# Detect language
+detection = client.detect("Bonjour le monde")
+print(detection.language)  # "fr"
+```
+
+## Google Translate Migration
+
+If you're using `google-cloud-translate`, switching is simple:
+
+```python
+# Before (Google)
+from google.cloud import translate_v2 as translate
+client = translate.Client()
+result = client.translate("Hello", target_language="nl")
+
+# After (Langbly)
+from langbly import Langbly
+client = Langbly(api_key="your-key")
+result = client.translate("Hello", target="nl")
+```
+
+## API Reference
+
+### `Langbly(api_key, base_url=None)`
+
+Create a client instance.
+
+- `api_key` (str): Your Langbly API key
+- `base_url` (str, optional): Override the API URL (default: `https://api.langbly.com`)
+
+### `client.translate(text, target, source=None, format=None)`
+
+Translate text.
+
+- `text` (str | list[str]): Text(s) to translate
+- `target` (str): Target language code (e.g., "nl", "de", "fr")
+- `source` (str, optional): Source language code (auto-detected if omitted)
+- `format` (str, optional): "text" or "html"
+
+### `client.detect(text)`
+
+Detect the language of text.
+
+- `text` (str): Text to analyze
+
+### `client.languages(target=None)`
+
+List supported languages.
+
+- `target` (str, optional): Language code to return names in
+
+## License
+
+MIT

langbly-0.1.0/README.md

@@ -0,0 +1,80 @@
+# langbly-python
+
+Official Python SDK for the [Langbly](https://langbly.com) translation API — a drop-in replacement for Google Translate v2.
+
+## Installation
+
+```bash
+pip install langbly
+```
+
+## Quick Start
+
+```python
+from langbly import Langbly
+
+client = Langbly(api_key="your-api-key")
+
+# Translate text
+result = client.translate("Hello world", target="nl")
+print(result.text)  # "Hallo wereld"
+
+# Batch translate
+results = client.translate(["Hello", "Goodbye"], target="nl")
+for r in results:
+    print(r.text)
+
+# Detect language
+detection = client.detect("Bonjour le monde")
+print(detection.language)  # "fr"
+```
+
+## Google Translate Migration
+
+If you're using `google-cloud-translate`, switching is simple:
+
+```python
+# Before (Google)
+from google.cloud import translate_v2 as translate
+client = translate.Client()
+result = client.translate("Hello", target_language="nl")
+
+# After (Langbly)
+from langbly import Langbly
+client = Langbly(api_key="your-key")
+result = client.translate("Hello", target="nl")
+```
+
+## API Reference
+
+### `Langbly(api_key, base_url=None)`
+
+Create a client instance.
+
+- `api_key` (str): Your Langbly API key
+- `base_url` (str, optional): Override the API URL (default: `https://api.langbly.com`)
+
+### `client.translate(text, target, source=None, format=None)`
+
+Translate text.
+
+- `text` (str | list[str]): Text(s) to translate
+- `target` (str): Target language code (e.g., "nl", "de", "fr")
+- `source` (str, optional): Source language code (auto-detected if omitted)
+- `format` (str, optional): "text" or "html"
+
+### `client.detect(text)`
+
+Detect the language of text.
+
+- `text` (str): Text to analyze
+
+### `client.languages(target=None)`
+
+List supported languages.
+
+- `target` (str, optional): Language code to return names in
+
+## License
+
+MIT

langbly-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "langbly"
+version = "0.1.0"
+description = "Official Python SDK for the Langbly translation API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.8"
+authors = [
+    { name = "Jasper de Winter", email = "jasper@langbly.com" },
+]
+keywords = ["translation", "api", "langbly", "google-translate", "i18n", "localization"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Text Processing :: Linguistic",
+]
+dependencies = [
+    "httpx>=0.24.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+    "respx>=0.20",
+]
+
+[project.urls]
+Homepage = "https://langbly.com"
+Documentation = "https://langbly.com/docs"
+Repository = "https://github.com/Langbly/langbly-python"
+Issues = "https://github.com/Langbly/langbly-python/issues"

langbly-0.1.0/src/langbly/__init__.py

@@ -0,0 +1,22 @@
+"""Langbly — Official Python SDK for the Langbly translation API."""
+
+from .client import (
+    AuthenticationError,
+    Detection,
+    Langbly,
+    LangblyError,
+    Language,
+    RateLimitError,
+    Translation,
+)
+
+__all__ = [
+    "AuthenticationError",
+    "Detection",
+    "Langbly",
+    "LangblyError",
+    "Language",
+    "RateLimitError",
+    "Translation",
+]
+__version__ = "0.1.0"

langbly-0.1.0/src/langbly/client.py

@@ -0,0 +1,304 @@
+"""Langbly API client."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import List, Optional, Union
+
+import httpx
+
+
+@dataclass
+class Translation:
+    """A single translation result."""
+
+    text: str
+    source: str
+    model: Optional[str] = None
+
+
+@dataclass
+class Detection:
+    """A language detection result."""
+
+    language: str
+    confidence: float
+
+
+@dataclass
+class Language:
+    """A supported language."""
+
+    code: str
+    name: Optional[str] = None
+
+
+class LangblyError(Exception):
+    """Base exception for Langbly API errors."""
+
+    def __init__(self, message: str, status_code: int = 0, code: str = ""):
+        super().__init__(message)
+        self.status_code = status_code
+        self.code = code
+
+
+class RateLimitError(LangblyError):
+    """Raised when the API returns 429 Too Many Requests."""
+
+    def __init__(self, message: str, retry_after: Optional[float] = None):
+        super().__init__(message, status_code=429, code="RATE_LIMITED")
+        self.retry_after = retry_after
+
+
+class AuthenticationError(LangblyError):
+    """Raised when the API key is invalid or missing."""
+
+    def __init__(self, message: str):
+        super().__init__(message, status_code=401, code="UNAUTHENTICATED")
+
+
+_RETRIABLE_STATUS_CODES = frozenset({429, 500, 502, 503, 504})
+
+
+class Langbly:
+    """Client for the Langbly translation API.
+
+    A drop-in replacement for Google Translate v2 — powered by LLMs.
+
+    Args:
+        api_key: Your Langbly API key.
+        base_url: Override the API base URL (default: https://api.langbly.com).
+        timeout: Request timeout in seconds (default: 30).
+        max_retries: Number of retries for transient errors (default: 2).
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api.langbly.com",
+        timeout: float = 30.0,
+        max_retries: int = 2,
+    ):
+        if not api_key:
+            raise ValueError("api_key is required")
+
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._max_retries = max_retries
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "User-Agent": "langbly-python/0.1.0",
+            },
+            timeout=timeout,
+        )
+
+    def translate(
+        self,
+        text: Union[str, List[str]],
+        target: str,
+        source: Optional[str] = None,
+        format: Optional[str] = None,
+    ) -> Union[Translation, List[Translation]]:
+        """Translate text to the target language.
+
+        Args:
+            text: A string or list of strings to translate.
+            target: Target language code (e.g., "nl", "de", "fr").
+            source: Source language code. Auto-detected if omitted.
+            format: "text" or "html". Default: "text".
+
+        Returns:
+            A Translation object, or a list if input was a list.
+
+        Raises:
+            LangblyError: On API error.
+            RateLimitError: When rate limited (429).
+            AuthenticationError: When API key is invalid (401).
+        """
+        q = [text] if isinstance(text, str) else text
+
+        body: dict = {"q": q, "target": target}
+        if source:
+            body["source"] = source
+        if format:
+            body["format"] = format
+
+        data = self._post("/language/translate/v2", body)
+
+        translations = []
+        for item in data["data"]["translations"]:
+            translations.append(
+                Translation(
+                    text=item["translatedText"],
+                    source=item.get("detectedSourceLanguage", source or ""),
+                    model=item.get("model"),
+                )
+            )
+
+        if isinstance(text, str):
+            return translations[0]
+        return translations
+
+    def detect(self, text: str) -> Detection:
+        """Detect the language of text.
+
+        Args:
+            text: The text to analyze.
+
+        Returns:
+            A Detection object with language code and confidence.
+
+        Raises:
+            LangblyError: On API error.
+        """
+        body = {"q": text}
+        data = self._post("/language/translate/v2/detect", body)
+
+        det = data["data"]["detections"][0][0]
+        return Detection(
+            language=det["language"],
+            confidence=det.get("confidence", 0.0),
+        )
+
+    def languages(self, target: Optional[str] = None) -> List[Language]:
+        """List supported languages.
+
+        Args:
+            target: If set, return language names in this language.
+
+        Returns:
+            A list of Language objects.
+
+        Raises:
+            LangblyError: On API error.
+        """
+        params: dict = {}
+        if target:
+            params["target"] = target
+
+        resp = self._request("GET", "/language/translate/v2/languages", params=params)
+        data = resp.json()
+
+        return [
+            Language(code=lang["language"], name=lang.get("name"))
+            for lang in data["data"]["languages"]
+        ]
+
+    def _post(self, path: str, body: dict) -> dict:
+        resp = self._request("POST", path, json=body)
+        return resp.json()
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        **kwargs,
+    ) -> httpx.Response:
+        """Make an HTTP request with automatic retries for transient errors."""
+        last_exc: Optional[Exception] = None
+
+        for attempt in range(self._max_retries + 1):
+            try:
+                resp = self._client.request(method, path, **kwargs)
+            except httpx.TimeoutException as exc:
+                last_exc = exc
+                if attempt < self._max_retries:
+                    time.sleep(self._backoff_delay(attempt))
+                    continue
+                raise LangblyError(
+                    f"Request timed out after {self._max_retries + 1} attempts",
+                    status_code=0,
+                    code="TIMEOUT",
+                ) from exc
+            except httpx.ConnectError as exc:
+                last_exc = exc
+                if attempt < self._max_retries:
+                    time.sleep(self._backoff_delay(attempt))
+                    continue
+                raise LangblyError(
+                    f"Connection failed after {self._max_retries + 1} attempts",
+                    status_code=0,
+                    code="CONNECTION_ERROR",
+                ) from exc
+
+            if resp.is_success:
+                return resp
+
+            # Don't retry client errors (except 429)
+            if resp.status_code not in _RETRIABLE_STATUS_CODES:
+                self._raise_for_status(resp)
+
+            # Retriable error
+            if attempt < self._max_retries:
+                delay = self._get_retry_delay(resp, attempt)
+                time.sleep(delay)
+                continue
+
+            # Final attempt failed
+            self._raise_for_status(resp)
+
+        # Should not reach here, but just in case
+        if last_exc:
+            raise last_exc
+        raise LangblyError("Request failed")
+
+    def _raise_for_status(self, resp: httpx.Response) -> None:
+        """Parse error response and raise appropriate exception."""
+        try:
+            err = resp.json()
+            msg = err.get("error", {}).get("message", resp.text)
+            code = err.get("error", {}).get("status", "")
+        except Exception:
+            msg = resp.text or resp.reason_phrase
+            code = ""
+
+        if resp.status_code == 401:
+            raise AuthenticationError(msg)
+        if resp.status_code == 429:
+            retry_after = self._parse_retry_after(resp)
+            raise RateLimitError(msg, retry_after=retry_after)
+
+        raise LangblyError(msg, status_code=resp.status_code, code=code)
+
+    @staticmethod
+    def _parse_retry_after(resp: httpx.Response) -> Optional[float]:
+        """Parse Retry-After header if present."""
+        header = resp.headers.get("retry-after")
+        if header is None:
+            return None
+        try:
+            return float(header)
+        except (ValueError, TypeError):
+            return None
+
+    @staticmethod
+    def _get_retry_delay(resp: httpx.Response, attempt: int) -> float:
+        """Calculate retry delay, respecting Retry-After header."""
+        retry_after = resp.headers.get("retry-after")
+        if retry_after:
+            try:
+                return min(float(retry_after), 30.0)
+            except (ValueError, TypeError):
+                pass
+        return min(0.5 * (2**attempt), 10.0)
+
+    @staticmethod
+    def _backoff_delay(attempt: int) -> float:
+        """Exponential backoff delay for connection/timeout errors."""
+        return min(0.5 * (2**attempt), 10.0)
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"Langbly(base_url={self._base_url!r})"