xoople-sdk 0.1.0__tar.gz

xoople_sdk-0.1.0/LICENSE

@@ -0,0 +1,23 @@
+Xoople SDK License
+
+Copyright (c) 2026 Xoople S.L. All rights reserved.
+
+This software is the confidential and proprietary property of Xoople S.L.
+
+Permission is granted, free of charge, to any person or organisation holding a
+valid subscription to the Xoople Products API to use, copy, and distribute this
+software, and to modify it for their own internal use, solely for the purpose of
+accessing that API.
+
+No other rights are granted. In particular, no right is granted to sell,
+sublicense, or otherwise distribute this software or any derivative work as a
+standalone product, or to use it to develop, operate, or market a service that
+competes with the Xoople Products API. The Xoople name and marks are not
+licensed hereunder.
+
+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 XOOPLE S.L. 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.

xoople_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: xoople-sdk
+Version: 0.1.0
+Summary: Official Python SDK for the Xoople Products API.
+License-Expression: LicenseRef-Xoople-Proprietary
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: requests>=2.28.1,<3
+Requires-Dist: pydantic>=2.8.2
+Requires-Dist: azure-identity>=1.16 ; extra == 'entra'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://xoople.com
+Provides-Extra: entra
+Description-Content-Type: text/markdown
+
+# xoople-sdk
+
+Official Python SDK for the Xoople Products API.
+
+```python
+from xoople.sdk import Config, XoopleClient, StaticToken, models
+
+client = XoopleClient.from_credentials(
+    "https://api.xoople.com", StaticToken("...")
+)
+# Or pass the complete transport configuration directly:
+# client = XoopleClient(Config.from_env())
+
+estimate = client.analyses.estimate(request)
+analysis = client.analyses.create(request)
+
+# `list` returns a paginator: iterate it for items across every page.
+for run in client.analyses.runs.list(analysis.uid):
+    print(run.state)
+
+# Sub-resources take the parent analysis uid:
+output = client.analyses.outputs.get(analysis.uid, output_uid)
+access = client.analyses.outputs.generate_access_url(analysis.uid, output_uid, ttl_seconds=900)
+
+# Custom verbs are plain methods:
+client.analyses.cancel(analysis.uid)
+client.analyses.schedules.pause(analysis.uid, schedule_uid)
+
+# Cross-analysis reads and catalogs are top-level:
+client.schedules.list(state=models.ScheduleStatus.ACTIVE)
+client.usage.limits()
+client.catalog.measures(product="tabular_time_series")
+```
+
+`Config.from_env()` reads `XOOPLE_API_URL` and `XOOPLE_TOKEN`.
+
+Every failure raises a subclass of `xoople.sdk.errors.XoopleError`.

xoople_sdk-0.1.0/README.md

@@ -0,0 +1,37 @@
+# xoople-sdk
+
+Official Python SDK for the Xoople Products API.
+
+```python
+from xoople.sdk import Config, XoopleClient, StaticToken, models
+
+client = XoopleClient.from_credentials(
+    "https://api.xoople.com", StaticToken("...")
+)
+# Or pass the complete transport configuration directly:
+# client = XoopleClient(Config.from_env())
+
+estimate = client.analyses.estimate(request)
+analysis = client.analyses.create(request)
+
+# `list` returns a paginator: iterate it for items across every page.
+for run in client.analyses.runs.list(analysis.uid):
+    print(run.state)
+
+# Sub-resources take the parent analysis uid:
+output = client.analyses.outputs.get(analysis.uid, output_uid)
+access = client.analyses.outputs.generate_access_url(analysis.uid, output_uid, ttl_seconds=900)
+
+# Custom verbs are plain methods:
+client.analyses.cancel(analysis.uid)
+client.analyses.schedules.pause(analysis.uid, schedule_uid)
+
+# Cross-analysis reads and catalogs are top-level:
+client.schedules.list(state=models.ScheduleStatus.ACTIVE)
+client.usage.limits()
+client.catalog.measures(product="tabular_time_series")
+```
+
+`Config.from_env()` reads `XOOPLE_API_URL` and `XOOPLE_TOKEN`.
+
+Every failure raises a subclass of `xoople.sdk.errors.XoopleError`.

xoople_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "xoople-sdk"
+version = "0.1.0"
+description = "Official Python SDK for the Xoople Products API."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "LicenseRef-Xoople-Proprietary"
+license-files = ["LICENSE"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "requests<3,>=2.28.1",
+    "pydantic>=2.8.2",
+]
+
+[project.optional-dependencies]
+entra = ["azure-identity>=1.16"]
+
+[project.urls]
+Homepage = "https://xoople.com"
+
+[build-system]
+requires = ["uv_build>=0.11.6,<0.12"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "xoople.sdk"
+
+[dependency-groups]
+dev = [
+    "ruff>=0.15.7",
+    "pytest>=8.0",
+    "pytest-cov>=6.0",
+    "types-requests>=2.31",
+    "datamodel-code-generator>=0.28",
+    "azure-identity>=1.16",
+]

xoople_sdk-0.1.0/pyproject.toml.orig

@@ -0,0 +1,47 @@
+[project]
+name = "xoople-sdk"
+version = "0.1.0"
+description = "Official Python SDK for the Xoople Products API."
+readme = "README.md"
+requires-python = ">=3.12"
+# Proprietary: the SDK is licensed for use against the Xoople Products API, not
+# redistribution. `license-files` ships the text inside the wheel.
+license = "LicenseRef-Xoople-Proprietary"
+license-files = ["LICENSE"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+  "requests<3,>=2.28.1",
+  "pydantic>=2.8.2",
+]
+
+[project.optional-dependencies]
+# Internal-testing auth: EntraCredential wraps azure-identity. Not needed for
+# the customer API-key / OAuth paths, so kept out of the default install.
+entra = [
+  "azure-identity>=1.16",
+]
+
+[project.urls]
+Homepage = "https://xoople.com"
+
+[build-system]
+requires = ["uv_build>=0.11.6,<0.12"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "xoople.sdk"
+
+[dependency-groups]
+dev = [
+  "ruff>=0.15.7",
+  "pytest>=8.0",
+  "pytest-cov>=6.0",
+  "types-requests>=2.31",
+  "datamodel-code-generator>=0.28",
+  # Present in dev so `ty` can resolve the optional azure.identity import;
+  # shipped to users only via the `entra` extra above.
+  "azure-identity>=1.16",
+]

xoople_sdk-0.1.0/src/xoople/sdk/__init__.py

@@ -0,0 +1,21 @@
+from xoople.sdk import errors, models
+from xoople.sdk._version import version
+from xoople.sdk.auth import EntraCredential, StaticToken
+from xoople.sdk.client import Estimate, Output, Paginator, XoopleClient
+from xoople.sdk.config import Config, CredentialProvider
+
+__version__ = version()
+
+__all__ = [
+    "Config",
+    "CredentialProvider",
+    "EntraCredential",
+    "Estimate",
+    "Output",
+    "Paginator",
+    "StaticToken",
+    "XoopleClient",
+    "__version__",
+    "errors",
+    "models",
+]

xoople_sdk-0.1.0/src/xoople/sdk/_model_base.py

@@ -0,0 +1,12 @@
+from pydantic import BaseModel, ConfigDict
+
+
+class XoopleModel(BaseModel):
+    """Base for generated SDK models. Ignores unknown fields for forward-compat.
+
+    Codegen overrides ``extra`` to ``"forbid"`` on request-body schemas, where a
+    dropped field would silently send the wrong request — see
+    ``scripts/postprocess_models.py``.
+    """
+
+    model_config = ConfigDict(extra="ignore", populate_by_name=True)

xoople_sdk-0.1.0/src/xoople/sdk/_transport.py

@@ -0,0 +1,149 @@
+import json
+import random
+import time
+from collections.abc import Callable
+from datetime import date
+from typing import TypeVar
+
+import requests
+from pydantic import BaseModel
+from xoople.sdk._version import version
+from xoople.sdk.config import Config
+from xoople.sdk.errors import XoopleConnectionError, XoopleResponseError, error_from_response
+
+M = TypeVar("M", bound=BaseModel)
+
+_RETRY_STATUS = frozenset({429, 500, 502, 503, 504})
+_BACKOFF_CAP = 5.0
+
+
+def _json_or_text(raw: bytes) -> object:
+    try:
+        return json.loads(raw)
+    except ValueError:
+        return raw.decode(errors="replace")
+
+
+class _Transport:
+    def __init__(
+        self,
+        config: Config,
+        session: requests.Session | None = None,
+        sleep: Callable[[float], None] = time.sleep,
+        rand: Callable[[], float] = random.random,
+    ) -> None:
+        self._config = config
+        self._owns_session = session is None
+        self._session = session if session is not None else requests.Session()
+        self._sleep = sleep
+        self._rand = rand
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        model: type[M],
+        params: dict[str, str | int | date | list[str] | None] | None = None,
+        json_body: object | None = None,
+        headers: dict[str, str] | None = None,
+        replay_safe: bool = False,
+    ) -> M:
+        url = f"{self._config.base_url}{path}"
+        merged: dict[str, str] = {
+            "User-Agent": f"xoople-sdk/{version()}",
+            "Accept": "application/json",
+            **self._config.credentials.auth_header(),
+        }
+        if headers:
+            merged.update(headers)
+        payload = (
+            json_body.model_dump(mode="json", by_alias=True, exclude_none=True)
+            if isinstance(json_body, BaseModel)
+            else json_body
+        )
+        sanitized: dict[str, str | int | list[str]] = {
+            k: v.isoformat() if isinstance(v, date) else v
+            for k, v in (params or {}).items()
+            if v is not None
+        }
+
+        # A write is only safe to replay when the server can dedupe it or the
+        # operation has no side effect, so other non-GET requests never retry.
+        replayable = method.upper() == "GET" or "Idempotency-Key" in merged or replay_safe
+        retries = self._config.max_retries if replayable else 0
+
+        attempt = 0
+        while True:
+            try:
+                resp = self._session.request(
+                    method,
+                    url,
+                    params=sanitized or None,
+                    json=payload,
+                    headers=merged,
+                    timeout=self._config.timeout,
+                )
+            except (requests.Timeout, requests.ConnectionError) as exc:
+                if attempt < retries:
+                    self._sleep(self._backoff(attempt))
+                    attempt += 1
+                    continue
+                raise XoopleConnectionError(f"request to {url} failed: {exc}") from exc
+            except requests.RequestException as exc:
+                # ChunkedEncodingError, TooManyRedirects and friends: not
+                # retryable, but callers still only ever catch XoopleError.
+                raise XoopleConnectionError(f"request to {url} failed: {exc}") from exc
+
+            status = resp.status_code
+            if status in _RETRY_STATUS and attempt < retries:
+                self._sleep(self._retry_delay(resp, attempt))
+                attempt += 1
+                continue
+
+            # The body can still fail mid-stream — a truncated chunked response
+            # raises here, not from the call above.
+            try:
+                raw = resp.content
+            except requests.RequestException as exc:
+                raise XoopleConnectionError(
+                    f"reading the response from {url} failed: {exc}"
+                ) from exc
+
+            if status >= 400:
+                raise error_from_response(
+                    status, _json_or_text(raw), trace_id=resp.headers.get("X-Trace-ID")
+                )
+            try:
+                return model.model_validate_json(raw)
+            except ValueError as exc:
+                raise XoopleResponseError(status, raw.decode(errors="replace")) from exc
+
+    def _retry_delay(self, resp: requests.Response, attempt: int) -> float:
+        # The server's own backpressure hint wins wherever it sends one — the
+        # external spec attaches Retry-After to 429 and 503 alike.
+        retry_after = self._parse_retry_after(resp)
+        if retry_after is not None:
+            return min(max(retry_after, 0.0), _BACKOFF_CAP)
+        return self._backoff(attempt)
+
+    def _backoff(self, attempt: int) -> float:
+        # Jittered so concurrent clients recovering from one outage do not
+        # retry in lockstep.
+        return min(2**attempt * 0.1, _BACKOFF_CAP) * (0.5 + 0.5 * self._rand())
+
+    @staticmethod
+    def _parse_retry_after(resp: requests.Response) -> float | None:
+        # Only the delta-seconds form is honored; the HTTP-date form falls back
+        # to exponential backoff.
+        value = resp.headers.get("Retry-After")
+        if value is None:
+            return None
+        try:
+            return float(value)
+        except ValueError:
+            return None
+
+    def close(self) -> None:
+        if self._owns_session:
+            self._session.close()

xoople_sdk-0.1.0/src/xoople/sdk/_version.py

@@ -0,0 +1,17 @@
+from functools import cache
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _distribution_version
+
+
+@cache
+def version() -> str:
+    """The installed distribution version, reported in the ``User-Agent``.
+
+    Read from installed metadata so ``pyproject.toml`` stays the only place the
+    version is written. Falls back to ``0.0.0`` when the package is imported
+    from a source tree that was never installed.
+    """
+    try:
+        return _distribution_version("xoople-sdk")
+    except PackageNotFoundError:
+        return "0.0.0"

xoople_sdk-0.1.0/src/xoople/sdk/auth.py

@@ -0,0 +1,76 @@
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Protocol
+
+from xoople.sdk.errors import XoopleError
+
+
+@dataclass(frozen=True)
+class StaticToken:
+    token: str
+
+    def auth_header(self) -> dict[str, str]:
+        return {"Authorization": f"Bearer {self.token}"}
+
+
+class _AccessToken(Protocol):
+    @property
+    def token(self) -> str: ...
+
+    @property
+    def expires_on(self) -> int: ...
+
+
+class _TokenCredential(Protocol):
+    def get_token(self, *scopes: str) -> _AccessToken: ...
+
+
+def _default_azure_credential() -> _TokenCredential:
+    try:
+        from azure.identity import DefaultAzureCredential  # noqa: PLC0415 — optional extra
+    except ImportError as exc:
+        raise XoopleError(
+            "Entra auth requires the optional dependency. "
+            "Install it with: pip install 'xoople-sdk[entra]'"
+        ) from exc
+    return DefaultAzureCredential()
+
+
+class EntraCredential:
+    """Entra ID (Azure AD) bearer auth — for internal testing against the API.
+
+    Acquires a token from ``azure-identity`` (``DefaultAzureCredential`` by
+    default: `az login`, env service-principal creds, or managed identity) for
+    ``scope`` and caches it until shortly before expiry. ``scope`` is the API's
+    accepted audience as a token scope, e.g. ``api://<app-id>/.default``.
+
+    This is not the customer auth path (that is OAuth against the auth service,
+    still pending); it exists so internal callers can exercise the live API.
+    """
+
+    def __init__(
+        self,
+        scope: str,
+        credential: _TokenCredential | None = None,
+        *,
+        expiry_skew_seconds: int = 300,
+        now: Callable[[], float] = time.time,
+    ) -> None:
+        self._scope = scope
+        self._credential = credential
+        self._skew = expiry_skew_seconds
+        self._now = now
+        self._cached: tuple[str, int] | None = None
+
+    def auth_header(self) -> dict[str, str]:
+        return {"Authorization": f"Bearer {self._token()}"}
+
+    def _token(self) -> str:
+        if self._cached is not None and self._cached[1] - self._skew > self._now():
+            return self._cached[0]
+        if self._credential is None:
+            self._credential = _default_azure_credential()
+        access = self._credential.get_token(self._scope)
+        self._cached = (access.token, access.expires_on)
+        return access.token