lingva-sdk 0.1.0__py3-none-any.whl

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/_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/_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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,6 @@
+lingva/__init__.py,sha256=IofiScxexQBorrgU3gdHVzPH7ab4jhXRuaiBAAOo9XA,346
+lingva/_client.py,sha256=baxKPjEu3_5_TuyzuReVmSFgrwCve8A36j0Mn9xKC3Q,5292
+lingva/_delivery.py,sha256=IR2Q4xs0H7qMKsQ9VMhUy6HdX9yN-HHnD0Tf3kzsisc,1765
+lingva_sdk-0.1.0.dist-info/METADATA,sha256=wafaa5HCPgbwRaMshgliz7ER404RbKO35bMKWDJGM3s,3460
+lingva_sdk-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+lingva_sdk-0.1.0.dist-info/RECORD,,

lingva_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any