acceldata-sdk-python 26.7.0__py3-none-any.whl

acceldata/client/http_client.py

@@ -0,0 +1,346 @@
+import json
+import logging
+import time
+from collections.abc import Mapping
+from typing import cast
+
+from pydantic import JsonValue, ValidationError
+import requests
+from requests_toolbelt import MultipartEncoder
+
+from acceldata.constants import CONNECTION_TIMEOUT_MS, READ_TIMEOUT_MS, CATALOG_API_PATH, PIPELINE_API_PATH, \
+    ADMIN_API_PATH, \
+    MS_TO_SECONDS, ADOC_BASE_PATH_SEGMENT
+from acceldata.constants import USER_AGENT
+from acceldata.exceptions import APIError, http_api_error_for_status
+from acceldata.exceptions.exceptions import ApiException
+from acceldata.urls import CatalogUrls
+from acceldata.urls.pipeline_urls import PipelineUrls
+from acceldata.utils.operation_ack import ack_failure
+
+
+def _profile_cancel_is_noop_already_finished(message: str) -> bool:
+    """Catalog may return 405 when the profile run is already terminal."""
+    m = (message or "").lower()
+    return "already finished" in m or "cannot be cancelled" in m
+
+
+class BaseHttpClient:
+    logger = logging.getLogger("sdk")
+    logger.setLevel(logging.INFO)
+
+    def __init__(
+            self,
+            url: str,
+            access_key: str,
+            secret_key: str,
+            connection_timeout_ms: int | None = CONNECTION_TIMEOUT_MS,
+            read_timeout_ms: int | None = READ_TIMEOUT_MS,
+            verify_ssl: bool | str = True,
+    ) -> None:
+        # ensure valid timeouts (avoid None issues)
+        url = url.rstrip("/")
+        connection_timeout_ms = connection_timeout_ms or CONNECTION_TIMEOUT_MS
+        read_timeout_ms = read_timeout_ms or READ_TIMEOUT_MS
+
+        self._connection_timeout = connection_timeout_ms / MS_TO_SECONDS
+        self._read_timeout = read_timeout_ms / MS_TO_SECONDS
+        # requests `verify` accepts bool or a CA bundle path.
+        self._verify_ssl = verify_ssl
+
+        self._catalog_api_base = f"{url}{CATALOG_API_PATH}"
+        self._pipeline_api_base = f"{url}{PIPELINE_API_PATH}"
+        self._admin_api_base = f"{url}{ADMIN_API_PATH}"
+        self.catalog_urls = CatalogUrls(self._catalog_api_base)
+        self.pipeline_urls = PipelineUrls(self._pipeline_api_base)
+
+        if ADOC_BASE_PATH_SEGMENT in url:
+            loc = url.rfind(ADOC_BASE_PATH_SEGMENT)
+            self._admin_api_base = f"{url[:loc]}{ADMIN_API_PATH}"
+        else:
+            self._admin_api_base = f"{url}{ADMIN_API_PATH}"
+
+        # validate credentials
+        if not access_key or not secret_key:
+            raise ValueError(
+                "ADOC credentials are missing. Please provide both access_key and secret_key."
+            )
+
+        # headers (instance scoped)
+        # add headers to distinguish between sdk calls
+        self._headers = {
+            "User-Agent": USER_AGENT,
+            "accessKey": access_key,
+            "secretKey": secret_key,
+            "Content-Type": "application/json",
+        }
+
+    def now_ms(self) -> int:
+        return int(time.time() * 1000)
+
+    def _request(
+            self,
+            method: str,
+            url: str,
+            *,
+            params: Mapping[str, object] | None = None,
+            json_body: JsonValue | None = None,
+            data: object | None = None,
+            headers: Mapping[str, str] | None = None,
+            as_json: bool = True,
+    ) -> JsonValue | str:
+        req_headers = dict(headers) if headers is not None else self._headers
+
+        now_ms = self.now_ms()
+        self.logger.debug(f"{method.upper()} {url}")
+
+        try:
+            response = requests.request(
+                method=method,
+                url=url,
+                headers=req_headers,
+                timeout=(self._connection_timeout, self._read_timeout),
+                verify=self._verify_ssl,
+                params=params,
+                json=json_body,
+                data=data,
+            )
+        except requests.exceptions.RequestException as e:
+            ack_failure(
+                self.logger,
+                "http_request",
+                "transport_error",
+                method=method.upper(),
+                url=url,
+                error=str(e),
+            )
+            self.logger.error(f"{method.upper()} {url} failed: {str(e)}")
+            raise ApiException(
+                status=None,
+                reason=f"{method.upper()} {url} failed: {e!s}",
+            ) from e
+
+        payload_for_log: object | None = json_body if json_body is not None else data
+        payload_str = (
+            json.dumps(payload_for_log) if payload_for_log is not None else None
+        )
+
+        self.logger.debug(
+            f"{method.upper()} {url} "
+            f"{f'payload={payload_str} ' if payload_str else ''}"
+            f"duration_ms={self.now_ms() - now_ms}"
+        )
+
+        return self._response(response, as_json)
+
+    def _get(
+            self,
+            url: str,
+            params: Mapping[str, object] | None = None,
+            as_json: bool = True,
+    ) -> JsonValue | str:
+        return self._request("get", url, params=params, as_json=as_json)
+
+    def _put(
+            self,
+            url: str,
+            payload: dict[str, JsonValue] | None = None,
+            as_json: bool = True,
+    ) -> JsonValue | str:
+        return self._request("put", url, json_body=payload, as_json=as_json)
+
+    def _post(
+            self,
+            url: str,
+            payload: dict[str, JsonValue] | None = None,
+            as_json: bool = True,
+            params: Mapping[str, object] | None = None,
+    ) -> JsonValue | str:
+        return self._request("post", url, params=params, json_body=payload, as_json=as_json)
+
+    def _delete(
+            self,
+            url: str,
+            params: Mapping[str, object] | None = None,
+            as_json: bool = True,
+    ) -> JsonValue | str:
+        return self._request("delete", url, params=params, as_json=as_json)
+
+    def _post_form_data(
+            self,
+            url: str,
+            payload: dict[str, JsonValue] | None = None,
+            as_json: bool = True,
+    ) -> JsonValue | str:
+        data = MultipartEncoder(fields={"request": json.dumps(payload)})
+
+        headers = dict(self._headers)
+        headers["Content-Type"] = data.content_type
+
+        return self._request(
+            "post",
+            url,
+            data=data,
+            headers=headers,
+            as_json=as_json,
+        )
+
+    def _put_form_data(
+            self,
+            url: str,
+            payload: dict[str, JsonValue] | None = None,
+            as_json: bool = True,
+    ) -> JsonValue | str:
+        data = MultipartEncoder(fields={"request": json.dumps(payload)})
+
+        headers = dict(self._headers)
+        headers["Content-Type"] = data.content_type
+
+        return self._request(
+            "put",
+            url,
+            data=data,
+            headers=headers,
+            as_json=as_json,
+        )
+
+    def cancel_profile(self, profile_req_id: int):
+        """PUT ``/assets/profile/{id}/cancel`` and return a response with a user-readable message."""
+        from acceldata.models.api.catalog.profile_cancellation_response import (
+            ProfileCancellationResponse,
+        )
+        from acceldata.models.api.catalog.connection_test_result import ConnectionTestResult
+
+        url = self.catalog_urls.profile_cancel(profile_req_id)
+        try:
+            response = self._put(url, payload={})
+        except APIError as e:
+            # Latest-status can race with completion; catalog rejects cancel with 405.
+            if e.status_code == 405 and _profile_cancel_is_noop_already_finished(e.message):
+                self.logger.debug(
+                    "cancel_profile(%s): skipping no-op cancel — %s",
+                    profile_req_id,
+                    e.message,
+                )
+                return ProfileCancellationResponse(
+                    result=ConnectionTestResult(
+                        isParentAvailable=True,
+                        parentList={},
+                        requestId=str(profile_req_id),
+                        status="NO_OP",
+                        message=f"Profile request {profile_req_id} is already in terminal state; nothing to cancel.",
+                    )
+                )
+            raise
+        if not isinstance(response, dict):
+            return ProfileCancellationResponse(
+                result=ConnectionTestResult(
+                    isParentAvailable=True,
+                    parentList={},
+                    requestId=str(profile_req_id),
+                    status="UNKNOWN",
+                    message=f"Profile request {profile_req_id} cancellation was submitted but response could not be parsed.",
+                )
+            )
+        try:
+            parsed = ProfileCancellationResponse.from_dict(response)
+            if parsed is None:
+                raise ValueError("empty profile cancellation response")
+            if parsed.result.message is None:
+                parsed.result.message = (
+                    f"Profile request {profile_req_id} cancellation request was accepted "
+                    f"(status={parsed.result.status})."
+                )
+            if parsed.result.request_id is None:
+                parsed.result.request_id = str(profile_req_id)
+            return parsed
+        except (ValidationError, ValueError, TypeError):
+            self.logger.debug(
+                "cancel_profile(%s): response did not match ProfileCancellationResponse",
+                profile_req_id,
+                exc_info=True,
+            )
+            return ProfileCancellationResponse(
+                result=ConnectionTestResult(
+                    isParentAvailable=True,
+                    parentList={},
+                    requestId=str(profile_req_id),
+                    status="UNKNOWN",
+                    message=f"Profile request {profile_req_id} cancellation was submitted but response format was unexpected.",
+                )
+            )
+
+    def _response(self, response: requests.Response, as_json: bool) -> JsonValue | str:
+        try:
+            response.raise_for_status()
+        except requests.exceptions.HTTPError as e:
+            self._handle_http_error(response, e)
+
+        if as_json:
+            # DELETE and some other endpoints return 2xx with an empty body; avoid json() on empty content.
+            if not response.content or not response.content.strip():
+                return {}
+            return cast(JsonValue, response.json())
+        return response.text
+
+    def _handle_http_error(self, response: requests.Response, exception: Exception) -> None:
+        status_code = response.status_code
+        url = response.url
+
+        try:
+            error_body: JsonValue | str = response.json()
+        except ValueError:
+            error_body = response.text
+
+        message = self._extract_error_message(error_body)
+        ack_failure(
+            self.logger,
+            "http_request",
+            "http_error",
+            status_code=status_code,
+            url=url,
+            message=message,
+        )
+
+        # 409 conflicts are often retried by callers; avoid ERROR noise (still raises).
+        if status_code == 409:
+            self.logger.warning(
+                "HTTP %s error for %s: %s",
+                status_code,
+                url,
+                message,
+            )
+        else:
+            self.logger.error(
+                "HTTP %s error for %s: %s",
+                status_code,
+                url,
+                message,
+            )
+
+        raise http_api_error_for_status(
+            status_code=status_code,
+            message=message,
+            response=error_body,
+            url=url,
+        ) from exception
+
+    def _extract_error_message(self, error_body: JsonValue | str) -> str:
+        if isinstance(error_body, dict):
+            for key in ("message", "error", "detail"):
+                v = error_body.get(key)
+                if v is not None:
+                    return str(v)
+            # Catalog often returns { "errors": [ { "message": "...", "status": 422 } ] }
+            errors = error_body.get("errors")
+            if isinstance(errors, list):
+                parts: list[str] = []
+                for item in errors:
+                    if isinstance(item, dict):
+                        m = item.get("message")
+                        if m is not None:
+                            parts.append(str(m))
+                if parts:
+                    return "; ".join(parts)
+            return str(error_body)
+        return str(error_body)

acceldata/client/transient_retry.py

@@ -0,0 +1,142 @@
+"""Transient retries for selected SDK operations.
+
+Some calls wrap work in :func:`transient_retry_call`. When retry is active, a
+failed attempt may be followed by further attempts instead of failing immediately.
+
+**What gets retried**
+
+* **HTTP (``APIError``):** only when ``status_code`` is one of the configured
+  retryable codes (default set ``_DEFAULT_RETRY_STATUS_CODES``: **408, 409, 422, 429, 500, 502, 503, 504**).
+  Responses with no status code or other codes are not retried. Pass
+  ``RetryConfig(retry_status_codes=...)`` to replace or extend that set (for example
+  ``frozenset(_DEFAULT_RETRY_STATUS_CODES) | {418}``).
+* **Transport (``ApiException``):** low-level failures before a normal API
+  response (e.g. connection errors). These are retried while attempts remain.
+
+**Default :class:`RetryConfig`**
+
+* ``enabled=True``
+* ``max_attempts=10`` — at most ten tries in total (first call plus up to nine retries).
+* Backoff: wait **30s** before the 2nd attempt, then **60s**, **120s**, … doubling each
+  time, capped at **600s** (10 minutes) between attempts.
+* ``retry_status_codes`` defaults to ``_DEFAULT_RETRY_STATUS_CODES``; pass a custom
+  ``frozenset[int]`` to override which HTTP statuses count as transient.
+
+**Disabling / no config**
+
+* ``RetryConfig(enabled=False)`` or ``max_attempts < 1``: run once with no retries.
+* ``config is None``: same as disabled (often when no ``RetryConfig`` is passed).
+
+**Merging two optional configs**
+
+:func:`effective_transient_retry(override, default)` returns ``override`` when it
+is a ``RetryConfig`` instance; otherwise ``default`` when that is a
+``RetryConfig``; otherwise ``None``. Policy polling uses this so per-call kwargs
+can override an ``Executor``-level default. Crawler and profiling calls use
+``effective_transient_retry(explicit, None)`` — only an explicit per-call
+``RetryConfig`` enables retries there.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import dataclass, field
+from typing import Callable, TypeVar
+
+from acceldata.exceptions import APIError
+from acceldata.exceptions.exceptions import ApiException
+
+T = TypeVar("T")
+
+_DEFAULT_RETRY_STATUS_CODES: frozenset[int] = frozenset(
+    {408,409, 422, 429, 500, 502, 503, 504}
+)
+
+
+@dataclass(frozen=True)
+class RetryConfig:
+    """Settings for :func:`transient_retry_call` (enabled, caps, backoff, HTTP codes).
+
+    ``retry_status_codes`` defaults to ``_DEFAULT_RETRY_STATUS_CODES``; supply your own
+    ``frozenset`` to override (merge with the default if you only need to add or remove codes).
+    """
+
+    enabled: bool = True
+    max_attempts: int = 10
+    initial_interval_seconds: float = 30.0
+    max_interval_seconds: float = 600.0
+    retry_status_codes: frozenset[int] = field(
+        default_factory=lambda: frozenset(_DEFAULT_RETRY_STATUS_CODES)
+    )
+
+    def sleep_after_failed_attempt(self, failed_attempt: int) -> None:
+        """Wait before the next try. ``failed_attempt`` is 1-based (1 = first try failed)."""
+        delay = min(
+            self.initial_interval_seconds * (2 ** (failed_attempt - 1)),
+            self.max_interval_seconds,
+        )
+        time.sleep(delay)
+
+
+def _retry_http_error(exc: APIError, config: RetryConfig) -> bool:
+    code = exc.status_code
+    return code is not None and code in config.retry_status_codes
+
+
+def _retries_active(config: RetryConfig | None) -> bool:
+    return config is not None and config.enabled and config.max_attempts >= 1
+
+
+def transient_retry_call(
+    operation: Callable[[], T],
+    config: RetryConfig | None,
+    *,
+    logger: logging.Logger,
+    operation_name: str,
+) -> T:
+    """Run ``operation``, optionally retrying on transient ``APIError`` / ``ApiException``."""
+    if not _retries_active(config):
+        return operation()
+
+    assert config is not None  # for type checkers; _retries_active ensures this
+
+    for attempt in range(1, config.max_attempts + 1):
+        try:
+            return operation()
+        except APIError as e:
+            last = attempt >= config.max_attempts or not _retry_http_error(e, config)
+            if last:
+                raise
+            logger.warning(
+                "%s: transient HTTP error (attempt %s/%s) status=%s: %s — retrying",
+                operation_name,
+                attempt,
+                config.max_attempts,
+                e.status_code,
+                e.message,
+            )
+            config.sleep_after_failed_attempt(attempt)
+        except ApiException as e:
+            if attempt >= config.max_attempts:
+                raise
+            logger.warning(
+                "%s: transport error (attempt %s/%s): %s — retrying",
+                operation_name,
+                attempt,
+                config.max_attempts,
+                e.reason,
+            )
+            config.sleep_after_failed_attempt(attempt)
+
+
+def effective_transient_retry(
+    override: RetryConfig | None,
+    default: RetryConfig | None,
+) -> RetryConfig | None:
+    """Prefer an explicit per-call ``override``; else use ``default`` if it is a ``RetryConfig``."""
+    if isinstance(override, RetryConfig):
+        return override
+    if isinstance(default, RetryConfig):
+        return default
+    return None

acceldata/constants/__init__.py

@@ -0,0 +1 @@
+from .constants import *

acceldata/constants/constants.py

@@ -0,0 +1,13 @@
+CONNECTION_TIMEOUT_MS = 5000
+READ_TIMEOUT_MS = 15000
+
+# Control-plane URL path segments (same wire paths as the deployed product).
+_CP = bytes.fromhex("746f726368").decode("ascii")
+CATALOG_API_PATH = "/catalog-server/api"
+PIPELINE_API_PATH = f"/{_CP}-pipeline/api"
+ADMIN_API_PATH = "/admin/api"
+
+# When the base URL includes this path segment, admin API calls use the host above it.
+ADOC_BASE_PATH_SEGMENT = f"/{_CP}"
+MS_TO_SECONDS = 1000
+USER_AGENT = "Acceldata-sdk"

acceldata/exceptions/__init__.py

@@ -0,0 +1,52 @@
+"""Public SDK exceptions.
+
+* **HTTP errors** — :mod:`acceldata.exceptions.api_errors` (subclasses of
+  :class:`~acceldata.exceptions.exceptions.OpenApiException`): raised from
+  :class:`~acceldata.client.http_client.BaseHttpClient` on non-2xx responses.
+* **Workflow / validation** — :mod:`acceldata.exceptions.sdk_exceptions`: raised
+  for invalid SDK usage or policy/pipeline outcomes (not transport failures).
+* **OpenAPI helpers** — :mod:`acceldata.exceptions.exceptions`: generator-owned
+  base types (e.g. :class:`~acceldata.exceptions.exceptions.ApiException` for
+  transport failures before an HTTP response).
+"""
+
+from .api_errors import (
+    APIError,
+    BadRequestError,
+    ConflictError,
+    ForbiddenError,
+    NotFoundError,
+    ServiceError,
+    UnauthorizedError,
+    http_api_error_for_status,
+)
+from .exceptions import ApiException, OpenApiException
+from .sdk_exceptions import (
+    AcceldataSdkException,
+    InvalidPipelineRunLookupError,
+    InvalidPolicyTypeError,
+    InvalidRuleTypeError,
+    PipelineRunNotFoundError,
+    PolicyExecutionCompletedWithErrorResultError,
+    PolicyExecutionCompletedWithWarningError,
+)
+
+__all__ = [
+    "APIError",
+    "AcceldataSdkException",
+    "ApiException",
+    "BadRequestError",
+    "ConflictError",
+    "ForbiddenError",
+    "http_api_error_for_status",
+    "InvalidPipelineRunLookupError",
+    "InvalidPolicyTypeError",
+    "InvalidRuleTypeError",
+    "NotFoundError",
+    "OpenApiException",
+    "PipelineRunNotFoundError",
+    "PolicyExecutionCompletedWithErrorResultError",
+    "PolicyExecutionCompletedWithWarningError",
+    "ServiceError",
+    "UnauthorizedError",
+]

acceldata/exceptions/api_errors.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from acceldata.exceptions.exceptions import OpenApiException
+
+
+class APIError(OpenApiException):
+    """Raised when the ADOC HTTP API returns an error response."""
+
+    def __init__(
+        self,
+        *,
+        message: str,
+        status_code: int,
+        response: object,
+        url: str,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.response = response
+        self.url = url
+
+    def __str__(self) -> str:
+        return f"{self.status_code} {type(self).__name__} for {self.url}: {self.message}"
+
+
+class BadRequestError(APIError):
+    """HTTP 400 — bad request."""
+
+
+class UnauthorizedError(APIError):
+    """HTTP 401 — unauthorized."""
+
+
+class ForbiddenError(APIError):
+    """HTTP 403 — forbidden."""
+
+
+class NotFoundError(APIError):
+    """HTTP 404 — resource not found."""
+
+
+class ConflictError(APIError):
+    """HTTP 409 — resource conflict."""
+
+
+class ServiceError(APIError):
+    """HTTP 5xx — server error."""
+
+
+def http_api_error_for_status(
+    *,
+    status_code: int,
+    message: str,
+    response: object,
+    url: str,
+) -> APIError:
+    """Return the most specific :class:`APIError` subclass for ``status_code``."""
+    if status_code == 400:
+        return BadRequestError(
+            message=message, status_code=status_code, response=response, url=url
+        )
+    if status_code == 401:
+        return UnauthorizedError(
+            message=message, status_code=status_code, response=response, url=url
+        )
+    if status_code == 403:
+        return ForbiddenError(
+            message=message, status_code=status_code, response=response, url=url
+        )
+    if status_code == 404:
+        return NotFoundError(
+            message=message, status_code=status_code, response=response, url=url
+        )
+    if status_code == 409:
+        return ConflictError(
+            message=message, status_code=status_code, response=response, url=url
+        )
+    if 500 <= status_code < 600:
+        return ServiceError(
+            message=message, status_code=status_code, response=response, url=url
+        )
+    return APIError(
+        message=message, status_code=status_code, response=response, url=url
+    )