logion-client 0.1.0__py3-none-any.whl

logion/__init__.py

@@ -0,0 +1,32 @@
+# SPDX-License-Identifier: MIT
+"""Logion Python client SDK."""
+
+from logion._client import LogionClient
+from logion._errors import (
+    APIError,
+    AuthenticationError,
+    ClientError,
+    ConflictError,
+    ForbiddenError,
+    LogionError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    TransportError,
+    ValidationError,
+)
+
+__all__ = [
+    "APIError",
+    "AuthenticationError",
+    "ClientError",
+    "ConflictError",
+    "ForbiddenError",
+    "LogionClient",
+    "LogionError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServerError",
+    "TransportError",
+    "ValidationError",
+]

logion/_client.py

@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: MIT
+"""Logion client — entry point for the SDK."""
+
+from __future__ import annotations
+
+from logion._config import resolve_config
+from logion._http import HttpClient
+from logion._versioning import VersionedNamespaces
+from logion.v1 import V1Namespace
+
+
+class LogionClient:
+    """Python client for the Logion API.
+
+    Configuration can be provided via constructor arguments or
+    environment variables (``LOGION_API_KEY``, ``LOGION_BASE_URL``).
+    Omitted arguments fall back to the corresponding environment
+    variable, then to built-in defaults.
+
+    Usage::
+
+        from logion import LogionClient
+
+        client = LogionClient(api_key="lgk_...")
+        client.v1.health.check()
+        client.v1.listings.search(query="rag")
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+        extra_headers: dict[str, str] | None = None,
+    ) -> None:
+        config = resolve_config(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            extra_headers=extra_headers,
+        )
+        self._http = HttpClient(config)
+        self._namespaces = VersionedNamespaces(self._http)
+
+    @property
+    def v1(self) -> V1Namespace:
+        """Access the v1 API namespace."""
+        return self._namespaces.v1
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection."""
+        self._http.close()
+
+    def __enter__(self) -> LogionClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()

logion/_config.py

@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: MIT
+"""Client configuration."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+DEFAULT_BASE_URL = "https://api.logion.sh"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 3
+
+
+def resolve_env_or(key: str, default: str) -> str:
+    """Return *os.environ[key]* if set, otherwise *default*."""
+    return os.environ.get(key, default)
+
+
+@dataclass
+class ClientConfig:
+    """Resolved configuration for the Logion HTTP client."""
+
+    base_url: str = DEFAULT_BASE_URL
+    api_key: str = ""
+    timeout: float = DEFAULT_TIMEOUT
+    max_retries: int = DEFAULT_MAX_RETRIES
+    extra_headers: dict[str, str] = field(default_factory=dict)
+
+
+def resolve_config(
+    *,
+    api_key: str | None = None,
+    base_url: str | None = None,
+    timeout: float | None = None,
+    max_retries: int | None = None,
+    extra_headers: dict[str, str] | None = None,
+) -> ClientConfig:
+    """Resolve SDK configuration from explicit values, env vars, or
+    defaults — in that priority order."""
+    return ClientConfig(
+        base_url=(
+            base_url
+            if base_url is not None
+            else resolve_env_or("LOGION_BASE_URL", DEFAULT_BASE_URL)
+        ),
+        api_key=(
+            api_key
+            if api_key is not None
+            else resolve_env_or("LOGION_API_KEY", "")
+        ),
+        timeout=timeout if timeout is not None else DEFAULT_TIMEOUT,
+        max_retries=(
+            max_retries if max_retries is not None else DEFAULT_MAX_RETRIES
+        ),
+        extra_headers=extra_headers if extra_headers is not None else {},
+    )

logion/_errors.py

@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: MIT
+"""Error hierarchy for the Logion SDK."""
+
+from __future__ import annotations
+
+
+class LogionError(Exception):
+    """Base exception for all SDK errors."""
+
+
+class APIError(LogionError):
+    """Error returned by the Logion API."""
+
+    def __init__(
+        self,
+        status_code: int,
+        detail: str | list[dict[str, object]],
+        request_id: str | None = None,
+    ) -> None:
+        self.status_code = status_code
+        self.detail = detail
+        self.request_id = request_id
+        msg = f"{status_code}"
+        if request_id:
+            msg += f" (request_id={request_id})"
+        msg += f": {detail}"
+        super().__init__(msg)
+
+
+class ClientError(APIError):
+    """4xx response that isn't mapped to a specific error class."""
+
+
+class AuthenticationError(APIError):
+    """401 — Invalid or missing API key."""
+
+
+class ForbiddenError(APIError):
+    """403 — Insufficient permissions."""
+
+
+class NotFoundError(APIError):
+    """404 — Resource not found."""
+
+
+class ConflictError(APIError):
+    """409 — Resource already exists."""
+
+
+class ValidationError(APIError):
+    """422 — Request body or parameters invalid."""
+
+
+class RateLimitError(APIError):
+    """429 — Too many requests."""
+
+
+class ServerError(APIError):
+    """5xx — Server-side error."""
+
+
+class TransportError(LogionError):
+    """Network-level failure (DNS, connection, timeout, etc.).
+
+    Wraps an ``httpx.TransportError`` after retries are exhausted.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        original: Exception | None = None,
+    ) -> None:
+        self.original = original
+        super().__init__(message)

logion/_http.py

@@ -0,0 +1,187 @@
+# SPDX-License-Identifier: MIT
+"""HTTP transport wrapper with retry and auth."""
+
+from __future__ import annotations
+
+import time
+import uuid
+from typing import Any, TypeVar, cast
+
+import httpx
+from pydantic import BaseModel
+
+from logion._config import ClientConfig
+from logion._errors import (
+    APIError,
+    AuthenticationError,
+    ClientError,
+    ConflictError,
+    ForbiddenError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    TransportError,
+    ValidationError,
+)
+
+_RETRYABLE_STATUS_CODES = {429, 502, 503, 504}
+_RETRYABLE_METHODS = {"GET", "HEAD", "OPTIONS"}
+_STATUS_ERROR_MAP: dict[int, type[APIError]] = {
+    401: AuthenticationError,
+    403: ForbiddenError,
+    404: NotFoundError,
+    409: ConflictError,
+    422: ValidationError,
+    429: RateLimitError,
+}
+
+T = TypeVar("T", bound=BaseModel)
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    """Raise a typed SDK error for non-2xx responses."""
+    if response.is_success:
+        return
+
+    status_code = response.status_code
+    request_id: str | None = response.headers.get("x-request-id")
+    detail: str | list[dict[str, object]] = response.text
+
+    try:
+        body = response.json()
+        detail = body.get("detail", detail)
+    except Exception:  # nosec B110 — intentional: non-JSON responses are fine as plain text
+        pass
+
+    error_cls = _STATUS_ERROR_MAP.get(status_code)
+    if error_cls is None:
+        error_cls = ServerError if status_code >= 500 else ClientError
+
+    raise error_cls(
+        status_code=status_code,
+        detail=detail,
+        request_id=request_id,
+    )
+
+
+class HttpClient:
+    """Wraps httpx.Client with retry, auth, and error mapping."""
+
+    def __init__(self, config: ClientConfig) -> None:
+        self._config = config
+        self._client = httpx.Client(
+            base_url=config.base_url,
+            timeout=config.timeout,
+            headers=self._build_headers(config),
+        )
+
+    @staticmethod
+    def _build_headers(config: ClientConfig) -> dict[str, str]:
+        headers: dict[str, str] = {
+            "Accept": "application/json",
+            **config.extra_headers,
+        }
+        if config.api_key:
+            headers["Authorization"] = f"Bearer {config.api_key}"
+        return headers
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Send a request and return raw JSON dict."""
+        if self._config.max_retries < 0:
+            msg = f"max_retries must be >= 0, got {self._config.max_retries}"
+            raise ValueError(msg)
+        can_retry = method.upper() in _RETRYABLE_METHODS
+        last_exc: httpx.TransportError | None = None
+        max_attempts = self._config.max_retries + 1 if can_retry else 1
+
+        for attempt in range(max_attempts):
+            request_id = str(uuid.uuid4())
+            headers = {"X-Request-ID": request_id}
+
+            try:
+                response = self._client.request(
+                    method,
+                    path,
+                    params=params,
+                    json=json,
+                    headers=headers,
+                )
+            except httpx.TransportError as exc:
+                last_exc = exc
+                if can_retry and attempt < max_attempts - 1:
+                    backoff = 0.5 * (2**attempt)
+                    time.sleep(backoff)
+                    continue
+                raise TransportError(
+                    f"Request failed after {attempt + 1} attempt(s): {exc}",
+                    original=exc,
+                ) from exc
+
+            if (
+                response.status_code in _RETRYABLE_STATUS_CODES
+                and can_retry
+                and attempt < max_attempts - 1
+            ):
+                backoff = 0.5 * (2**attempt)
+                time.sleep(backoff)
+                continue
+
+            _raise_for_status(response)
+            return response.json()
+
+        assert last_exc is not None  # for type checker
+        raise TransportError(
+            f"Request failed after {max_attempts} attempts",
+            original=last_exc,
+        ) from last_exc
+
+    def request_model(
+        self,
+        method: str,
+        path: str,
+        model_type: type[T],
+        *,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+    ) -> T:
+        """Send a request and parse the response into a Pydantic model."""
+        data = self.request(
+            method,
+            path,
+            params=params,
+            json=json,
+        )
+        return cast(T, model_type.model_validate(data))
+
+    def request_list(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+    ) -> list[dict[str, Any]]:
+        """Send a request and return raw JSON as a list of dicts.
+
+        Use this for endpoints whose OpenAPI contract defines an array
+        response (``[...]``) rather than a JSON object.
+        """
+        data = self.request(method, path, params=params, json=json)
+        if not isinstance(data, list):
+            msg = (
+                f"Expected a JSON array from "
+                f"{method} {path}, got {type(data).__name__}"
+            )
+            raise TypeError(msg)
+        return data
+
+    def close(self) -> None:
+        """Close the underlying httpx client."""
+        self._client.close()

logion/_types/__init__.py

@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: MIT
+"""Shared SDK types."""

logion/_version.py

@@ -0,0 +1,19 @@
+# SPDX-License-Identifier: MIT
+"""Runtime-accessible package version."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+try:
+    __version__: str = _pkg_version("logion-client")
+except PackageNotFoundError:  # local checkout / sdist
+    import tomllib
+    from pathlib import Path
+
+    _pyproject = Path(__file__).resolve().parents[2] / "pyproject.toml"
+    with _pyproject.open("rb") as _f:
+        __version__ = tomllib.load(_f)["project"]["version"]
+
+__all__ = ["__version__"]

logion/_versioning.py

@@ -0,0 +1,22 @@
+# SPDX-License-Identifier: MIT
+"""Versioned namespace factory."""
+
+from __future__ import annotations
+
+from logion._http import HttpClient
+from logion.v1 import V1Namespace
+
+
+class VersionedNamespaces:
+    """Lazy namespace accessors for each API version."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+        self._v1: V1Namespace | None = None
+
+    @property
+    def v1(self) -> V1Namespace:
+        """Access the v1 API namespace."""
+        if self._v1 is None:
+            self._v1 = V1Namespace(self._http)
+        return self._v1

logion/v1/__init__.py

@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: MIT
+"""V1 API namespace."""
+
+from __future__ import annotations
+
+from logion._http import HttpClient
+from logion.v1._resources.admin import AdminResource
+from logion.v1._resources.bounties import BountiesResource
+from logion.v1._resources.course_reviews import CourseReviewsResource
+from logion.v1._resources.courses import CoursesResource
+from logion.v1._resources.credits import CreditsResource
+from logion.v1._resources.health import HealthResource
+from logion.v1._resources.identity import IdentityResource
+from logion.v1._resources.listings import ListingsResource
+from logion.v1._resources.notifications import NotificationsResource
+from logion.v1._resources.payments import PaymentsResource
+from logion.v1._resources.referrals import ReferralsResource
+from logion.v1._resources.reports import ReportsResource
+
+
+class V1Namespace:
+    """Namespace for v1 API endpoints."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self.health = HealthResource(http)
+        self.identity = IdentityResource(http)
+        self.listings = ListingsResource(http)
+        self.courses = CoursesResource(http)
+        self.credits = CreditsResource(http)
+        self.payments = PaymentsResource(http)
+        self.course_reviews = CourseReviewsResource(http)
+        self.notifications = NotificationsResource(http)
+        self.reports = ReportsResource(http)
+        self.admin = AdminResource(http)
+        self.bounties = BountiesResource(http)
+        self.referrals = ReferralsResource(http)

logion/v1/_generated/__init__.py

@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: MIT
+"""Generated v1 API internals."""