lingva-sdk 0.1.0__tar.gz

lingva_sdk-0.1.0/.gitignore

@@ -0,0 +1,57 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# Dependencies
+node_modules
+.pnp
+.pnp.js
+
+# Local env files
+.env*
+!.env*.example
+.npmrc.private
+
+# Testing
+coverage
+.lingva/local-remote/
+
+# Turbo
+.turbo
+
+# Vercel
+.vercel
+
+# Build Outputs
+.angular/
+.next/
+.nuxt/
+.output/
+.svelte-kit/
+.build/
+.dart_tool/
+.gradle/
+out/
+build
+dist
+
+# Python
+__pycache__/
+.pytest_cache/
+*.pyc
+.venv/
+venv/
+
+# Native SDK package-manager state
+.flutter-plugins
+.flutter-plugins-dependencies
+sdks/flutter/pubspec.lock
+
+
+# Debug
+npm-debug.log*
+
+# Misc
+.DS_Store
+*.pem
+.env*.local
+
+.pnpm-store/

lingva_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.5
+Name: lingva-sdk
+Version: 0.1.0
+Summary: Python client for the Lingva localization platform
+License: SEE LICENSE IN ../../LICENSE.md
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: http
+Requires-Dist: httpx>=0.27; extra == 'http'
+Description-Content-Type: text/markdown
+
+# lingva — Python SDK
+
+Python client for the [Lingva](https://lingva.dev) localization platform.
+
+**Requires Python 3.11+.**
+
+> This is a preview package. It follows the same conformance contract as the Swift, Kotlin, and Flutter SDKs but is not yet published to PyPI.
+
+---
+
+## Install
+
+```bash
+# From the monorepo root (editable install)
+pip install -e sdks/python
+
+# With async HTTP support (httpx)
+pip install -e "sdks/python[http]"
+```
+
+Once published:
+
+```bash
+pip install lingva-sdk
+pip install "lingva-sdk[http]"   # adds httpx for async delivery
+```
+
+---
+
+## Quickstart
+
+### Load from a local bundle file
+
+```python
+from lingva import LingvaClient
+
+client = LingvaClient.from_file(".lingva/translations/en.bundle.json")
+
+print(client.t("actions.continue"))           # Continue
+print(client.t("welcome.title", name="Alice")) # Welcome, Alice.
+```
+
+### Load from CDN (async)
+
+```python
+import asyncio
+from lingva import LingvaClient, LingvaDeliveryTarget
+
+target = LingvaDeliveryTarget(
+    base_url="https://api.lingva.dev",
+    project_id="my-project",
+    environment="production",
+)
+
+async def main():
+    client = await LingvaClient.from_url(target, locale="fr", fallback_locale="en")
+    print(client.t("welcome.title", name="Alice"))
+
+asyncio.run(main())
+```
+
+### Load from CDN (synchronous)
+
+```python
+from lingva import LingvaClient, LingvaDeliveryTarget
+
+target = LingvaDeliveryTarget(
+    base_url="https://api.lingva.dev",
+    project_id="my-project",
+    environment="production",
+)
+
+client = LingvaClient.from_url_sync(target, locale="fr", fallback_locale="en")
+print(client.t("welcome.title", name="Alice"))
+```
+
+---
+
+## API
+
+### `LingvaClient`
+
+| Method / Property | Description |
+|---|---|
+| `LingvaClient.from_bundle(bundle)` | Create from a parsed dict |
+| `LingvaClient.from_file(path, *, fallback_path=None)` | Load from filesystem |
+| `LingvaClient.from_url_sync(target, locale, ...)` | Synchronous HTTP fetch |
+| `await LingvaClient.from_url(target, locale, ...)` | Async HTTP fetch (requires `lingva[http]`) |
+| `.t(key, **variables)` | Translate a key with optional `{varname}` substitution |
+| `.has(key)` | Check if a key exists |
+| `.locale` | Active locale string |
+| `.fallback_locale` | Fallback locale string or `None` |
+| `.bundle()` | Raw bundle dict (for last-valid caching) |
+
+### `LingvaDeliveryTarget`
+
+```python
+LingvaDeliveryTarget(
+    base_url="https://api.lingva.dev",
+    project_id="my-project",
+    environment="production",          # default
+    uri_template="...",                # optional custom path template
+)
+target.resolve("fr")
+# -> "https://api.lingva.dev/bundles/my-project/production/latest/fr.bundle.json"
+```
+
+---
+
+## Bundle schema
+
+The SDK reads schemaVersion 1 bundles. Variables use `{varname}` syntax. Unknown variables pass through unchanged.
+
+```json
+{
+  "schemaVersion": 1,
+  "locale": "en",
+  "fallbackLocale": "en",
+  "fallbackKeys": [],
+  "messages": {
+    "actions.continue": "Continue",
+    "welcome.title": "Welcome, {name}."
+  }
+}
+```

lingva_sdk-0.1.0/README.md

@@ -0,0 +1,125 @@
+# lingva — Python SDK
+
+Python client for the [Lingva](https://lingva.dev) localization platform.
+
+**Requires Python 3.11+.**
+
+> This is a preview package. It follows the same conformance contract as the Swift, Kotlin, and Flutter SDKs but is not yet published to PyPI.
+
+---
+
+## Install
+
+```bash
+# From the monorepo root (editable install)
+pip install -e sdks/python
+
+# With async HTTP support (httpx)
+pip install -e "sdks/python[http]"
+```
+
+Once published:
+
+```bash
+pip install lingva-sdk
+pip install "lingva-sdk[http]"   # adds httpx for async delivery
+```
+
+---
+
+## Quickstart
+
+### Load from a local bundle file
+
+```python
+from lingva import LingvaClient
+
+client = LingvaClient.from_file(".lingva/translations/en.bundle.json")
+
+print(client.t("actions.continue"))           # Continue
+print(client.t("welcome.title", name="Alice")) # Welcome, Alice.
+```
+
+### Load from CDN (async)
+
+```python
+import asyncio
+from lingva import LingvaClient, LingvaDeliveryTarget
+
+target = LingvaDeliveryTarget(
+    base_url="https://api.lingva.dev",
+    project_id="my-project",
+    environment="production",
+)
+
+async def main():
+    client = await LingvaClient.from_url(target, locale="fr", fallback_locale="en")
+    print(client.t("welcome.title", name="Alice"))
+
+asyncio.run(main())
+```
+
+### Load from CDN (synchronous)
+
+```python
+from lingva import LingvaClient, LingvaDeliveryTarget
+
+target = LingvaDeliveryTarget(
+    base_url="https://api.lingva.dev",
+    project_id="my-project",
+    environment="production",
+)
+
+client = LingvaClient.from_url_sync(target, locale="fr", fallback_locale="en")
+print(client.t("welcome.title", name="Alice"))
+```
+
+---
+
+## API
+
+### `LingvaClient`
+
+| Method / Property | Description |
+|---|---|
+| `LingvaClient.from_bundle(bundle)` | Create from a parsed dict |
+| `LingvaClient.from_file(path, *, fallback_path=None)` | Load from filesystem |
+| `LingvaClient.from_url_sync(target, locale, ...)` | Synchronous HTTP fetch |
+| `await LingvaClient.from_url(target, locale, ...)` | Async HTTP fetch (requires `lingva[http]`) |
+| `.t(key, **variables)` | Translate a key with optional `{varname}` substitution |
+| `.has(key)` | Check if a key exists |
+| `.locale` | Active locale string |
+| `.fallback_locale` | Fallback locale string or `None` |
+| `.bundle()` | Raw bundle dict (for last-valid caching) |
+
+### `LingvaDeliveryTarget`
+
+```python
+LingvaDeliveryTarget(
+    base_url="https://api.lingva.dev",
+    project_id="my-project",
+    environment="production",          # default
+    uri_template="...",                # optional custom path template
+)
+target.resolve("fr")
+# -> "https://api.lingva.dev/bundles/my-project/production/latest/fr.bundle.json"
+```
+
+---
+
+## Bundle schema
+
+The SDK reads schemaVersion 1 bundles. Variables use `{varname}` syntax. Unknown variables pass through unchanged.
+
+```json
+{
+  "schemaVersion": 1,
+  "locale": "en",
+  "fallbackLocale": "en",
+  "fallbackKeys": [],
+  "messages": {
+    "actions.continue": "Continue",
+    "welcome.title": "Welcome, {name}."
+  }
+}
+```

lingva_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "lingva-sdk"
+version = "0.1.0"
+description = "Python client for the Lingva localization platform"
+readme = "README.md"
+license = { text = "SEE LICENSE IN ../../LICENSE.md" }
+requires-python = ">=3.11"
+dependencies = []
+
+[project.optional-dependencies]
+http = ["httpx>=0.27"]
+dev = ["pytest>=8", "pytest-asyncio>=0.24", "httpx>=0.27"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/lingva"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

lingva_sdk-0.1.0/src/lingva/__init__.py

@@ -0,0 +1,14 @@
+from lingva._client import LingvaClient, LingvaSchemaError
+from lingva._delivery import (
+    DEFAULT_REMOTE_BUNDLE_PATH_TEMPLATE,
+    LingvaDeliveryTarget,
+    load_bundle_from_file,
+)
+
+__all__ = [
+    "DEFAULT_REMOTE_BUNDLE_PATH_TEMPLATE",
+    "LingvaClient",
+    "LingvaDeliveryTarget",
+    "LingvaSchemaError",
+    "load_bundle_from_file",
+]

lingva_sdk-0.1.0/src/lingva/_client.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+from lingva._delivery import (
+    LingvaDeliveryTarget,
+    load_bundle_from_file,
+    load_bundle_from_url_async,
+    load_bundle_from_url_sync,
+)
+
+_SCHEMA_VERSION = 1
+_PLACEHOLDER_RE = re.compile(r"\{(\w+)\}")
+
+
+def _interpolate(template: str, variables: dict[str, str]) -> str:
+    """Replace {varname} tokens; unknown tokens pass through unchanged."""
+    def replace(m: re.Match[str]) -> str:
+        return variables.get(m.group(1), m.group(0))
+    return _PLACEHOLDER_RE.sub(replace, template)
+
+
+class LingvaSchemaError(ValueError):
+    """Raised when a bundle fails schema validation."""
+
+
+class LingvaClient:
+    """
+    Reads a Lingva locale bundle and provides key lookup with fallback and
+    variable interpolation.
+    """
+
+    def __init__(
+        self,
+        bundle: dict[str, Any],
+        fallback_bundle: dict[str, Any] | None = None,
+    ) -> None:
+        if bundle.get("schemaVersion") != _SCHEMA_VERSION:
+            raise LingvaSchemaError(
+                f"Unsupported bundle schemaVersion: {bundle.get('schemaVersion')!r}"
+            )
+        self._bundle = bundle
+        self._messages: dict[str, str] = bundle.get("messages") or {}
+        self._fallback_messages: dict[str, str] = (
+            fallback_bundle.get("messages") or {} if fallback_bundle else {}
+        )
+        self._fallback_keys: set[str] = set(bundle.get("fallbackKeys") or [])
+        self._locale: str = bundle.get("locale") or bundle.get("defaultLocale") or "en"
+        self._fallback_locale: str | None = bundle.get("fallbackLocale")
+        self._last_valid: dict[str, Any] = bundle
+
+    # ------------------------------------------------------------------
+    # Factory methods
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def from_bundle(cls, bundle: dict[str, Any]) -> "LingvaClient":
+        """Create a client from an already-parsed bundle dict."""
+        return cls(bundle)
+
+    @classmethod
+    def from_file(cls, path: str | Path, *, fallback_path: str | Path | None = None) -> "LingvaClient":
+        """Load a bundle from the local filesystem."""
+        bundle = load_bundle_from_file(path)
+        fallback = load_bundle_from_file(fallback_path) if fallback_path else None
+        return cls(bundle, fallback)
+
+    @classmethod
+    def from_url_sync(
+        cls,
+        target: LingvaDeliveryTarget,
+        locale: str,
+        *,
+        fallback_locale: str | None = None,
+        last_valid: dict[str, Any] | None = None,
+    ) -> "LingvaClient":
+        """Fetch a bundle synchronously; return a client over `last_valid` on error."""
+        try:
+            bundle = load_bundle_from_url_sync(target.resolve(locale))
+        except Exception:
+            if last_valid is not None:
+                return cls(last_valid)
+            raise
+        fallback = None
+        if fallback_locale and fallback_locale != locale:
+            try:
+                fallback = load_bundle_from_url_sync(target.resolve(fallback_locale))
+            except Exception:
+                pass
+        return cls(bundle, fallback)
+
+    @classmethod
+    async def from_url(
+        cls,
+        target: LingvaDeliveryTarget,
+        locale: str,
+        *,
+        fallback_locale: str | None = None,
+        last_valid: dict[str, Any] | None = None,
+    ) -> "LingvaClient":
+        """Fetch a bundle asynchronously; return a client over `last_valid` on error."""
+        try:
+            bundle = await load_bundle_from_url_async(target.resolve(locale))
+        except Exception:
+            if last_valid is not None:
+                return cls(last_valid)
+            raise
+        fallback = None
+        if fallback_locale and fallback_locale != locale:
+            try:
+                fallback = await load_bundle_from_url_async(target.resolve(fallback_locale))
+            except Exception:
+                pass
+        return cls(bundle, fallback)
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    @property
+    def locale(self) -> str:
+        return self._locale
+
+    @property
+    def fallback_locale(self) -> str | None:
+        return self._fallback_locale
+
+    def has(self, key: str) -> bool:
+        """Return True if the key exists in the primary or fallback messages."""
+        return key in self._messages or key in self._fallback_messages
+
+    def t(self, key: str, **variables: str) -> str:
+        """
+        Translate `key` with optional variable substitution.
+
+        Falls back to `fallback_bundle` when the key is missing from the
+        primary bundle or is listed in `fallbackKeys`.
+        """
+        if key in self._fallback_keys or key not in self._messages:
+            template = self._fallback_messages.get(key) or self._messages.get(key)
+        else:
+            template = self._messages.get(key)
+
+        if template is None:
+            return key
+
+        return _interpolate(template, variables) if variables else template
+
+    def bundle(self) -> dict[str, Any]:
+        """Return the raw bundle dict (useful for last-valid caching)."""
+        return self._bundle

lingva_sdk-0.1.0/src/lingva/_delivery.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import json
+import urllib.request
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+DEFAULT_REMOTE_BUNDLE_PATH_TEMPLATE = "/bundles/{projectId}/{environment}/latest/{locale}.bundle.json"
+
+_PLACEHOLDERS = {"projectId", "environment", "locale"}
+
+
+@dataclass(frozen=True)
+class LingvaDeliveryTarget:
+    """Resolves a Lingva CDN delivery URL for a given locale."""
+    base_url: str
+    uri_template: str = DEFAULT_REMOTE_BUNDLE_PATH_TEMPLATE
+    project_id: str = ""
+    environment: str = "production"
+
+    def resolve(self, locale: str) -> str:
+        path = (
+            self.uri_template
+            .replace("{projectId}", self.project_id)
+            .replace("{environment}", self.environment)
+            .replace("{locale}", locale)
+        )
+        return self.base_url.rstrip("/") + path
+
+
+def load_bundle_from_file(path: str | Path) -> dict[str, Any]:
+    """Read and parse a locale bundle JSON file."""
+    return json.loads(Path(path).read_text(encoding="utf-8"))
+
+
+def load_bundle_from_url_sync(url: str) -> dict[str, Any]:
+    """Fetch a locale bundle over HTTP (synchronous, no extra deps)."""
+    with urllib.request.urlopen(url) as resp:  # noqa: S310
+        return json.loads(resp.read().decode("utf-8"))
+
+
+async def load_bundle_from_url_async(url: str) -> dict[str, Any]:
+    """Fetch a locale bundle over HTTP using httpx (async)."""
+    try:
+        import httpx
+    except ImportError as exc:
+        raise ImportError(
+            "Install 'lingva[http]' (httpx) for async HTTP delivery."
+        ) from exc
+    async with httpx.AsyncClient() as client:
+        response = await client.get(url)
+        response.raise_for_status()
+        return response.json()

lingva_sdk-0.1.0/tests/test_client.py

@@ -0,0 +1,78 @@
+import json
+from pathlib import Path
+
+import pytest
+
+from lingva import LingvaClient, LingvaSchemaError
+
+FIXTURE_PATH = Path(__file__).parent.parent.parent / "fixtures" / "en.bundle.json"
+
+
+@pytest.fixture()
+def fixture_bundle() -> dict:
+    return json.loads(FIXTURE_PATH.read_text())
+
+
+def test_loads_fixture_bundle(fixture_bundle):
+    client = LingvaClient.from_bundle(fixture_bundle)
+    assert client.locale == "en"
+
+
+def test_translates_simple_key(fixture_bundle):
+    client = LingvaClient.from_bundle(fixture_bundle)
+    assert client.t("actions.continue") == "Continue"
+
+
+def test_interpolates_variable(fixture_bundle):
+    client = LingvaClient.from_bundle(fixture_bundle)
+    assert client.t("welcome.title", name="Alice") == "Welcome, Alice."
+
+
+def test_has_returns_true_for_known_key(fixture_bundle):
+    client = LingvaClient.from_bundle(fixture_bundle)
+    assert client.has("actions.continue") is True
+
+
+def test_has_returns_false_for_unknown_key(fixture_bundle):
+    client = LingvaClient.from_bundle(fixture_bundle)
+    assert client.has("nonexistent.key") is False
+
+
+def test_returns_key_for_missing_translation(fixture_bundle):
+    client = LingvaClient.from_bundle(fixture_bundle)
+    assert client.t("nonexistent.key") == "nonexistent.key"
+
+
+def test_rejects_wrong_schema_version():
+    with pytest.raises(LingvaSchemaError):
+        LingvaClient.from_bundle({"schemaVersion": 99, "messages": {}})
+
+
+def test_fallback_bundle_used_for_missing_key():
+    primary = {"schemaVersion": 1, "locale": "fr", "fallbackLocale": "en", "messages": {}, "fallbackKeys": []}
+    fallback = {"schemaVersion": 1, "locale": "en", "messages": {"greeting": "Hello"}, "fallbackKeys": []}
+    client = LingvaClient(primary, fallback)
+    assert client.t("greeting") == "Hello"
+
+
+def test_fallback_keys_list_forces_fallback():
+    primary = {
+        "schemaVersion": 1, "locale": "fr", "fallbackLocale": "en",
+        "messages": {"greeting": "Bonjour"},
+        "fallbackKeys": ["greeting"],
+    }
+    fallback = {"schemaVersion": 1, "locale": "en", "messages": {"greeting": "Hello"}, "fallbackKeys": []}
+    client = LingvaClient(primary, fallback)
+    assert client.t("greeting") == "Hello"
+
+
+def test_from_file_loads_fixture():
+    client = LingvaClient.from_file(FIXTURE_PATH)
+    assert client.t("actions.continue") == "Continue"
+
+
+def test_unknown_variable_passes_through(fixture_bundle):
+    client = LingvaClient.from_bundle(fixture_bundle)
+    # {name} is known but {extra} is not — {extra} should remain
+    result = client.t("welcome.title", name="Bob")
+    assert result == "Welcome, Bob."

lingva_sdk-0.1.0/tests/test_delivery.py

@@ -0,0 +1,35 @@
+from lingva._delivery import DEFAULT_REMOTE_BUNDLE_PATH_TEMPLATE, LingvaDeliveryTarget
+
+
+def test_default_template_constant():
+    assert DEFAULT_REMOTE_BUNDLE_PATH_TEMPLATE == "/bundles/{projectId}/{environment}/latest/{locale}.bundle.json"
+
+
+def test_resolve_builds_correct_url():
+    target = LingvaDeliveryTarget(
+        base_url="https://api.lingva.dev",
+        project_id="my-project",
+        environment="production",
+    )
+    url = target.resolve("fr")
+    assert url == "https://api.lingva.dev/bundles/my-project/production/latest/fr.bundle.json"
+
+
+def test_resolve_strips_trailing_slash():
+    target = LingvaDeliveryTarget(
+        base_url="https://api.lingva.dev/",
+        project_id="p1",
+        environment="dev",
+    )
+    url = target.resolve("en")
+    assert url == "https://api.lingva.dev/bundles/p1/dev/latest/en.bundle.json"
+
+
+def test_custom_uri_template():
+    target = LingvaDeliveryTarget(
+        base_url="https://cdn.example.com",
+        uri_template="/v2/{locale}/{projectId}.json",
+        project_id="abc",
+    )
+    url = target.resolve("de")
+    assert url == "https://cdn.example.com/v2/de/abc.json"