runapi-core 0.1.0__py3-none-any.whl

runapi/core/errors.py

@@ -0,0 +1,254 @@
+"""Error hierarchy and HTTP-response-to-error mapping for the RunAPI SDK."""
+
+from __future__ import annotations
+
+import json
+import re
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+from typing import Any, Dict, Optional
+
+_HTML_MARKER = re.compile(r"<!doctype|<html", re.IGNORECASE)
+_TITLE = re.compile(r"<title>(.*?)</title>", re.IGNORECASE | re.DOTALL)
+_H1 = re.compile(r"<h1>(.*?)</h1>", re.IGNORECASE | re.DOTALL)
+_ENTITY = re.compile(r"&[a-z]+;", re.IGNORECASE)
+_TAG = re.compile(r"<[^>]+>")
+
+
+class Error(Exception):
+    """Base error for all RunAPI SDK failures.
+
+    Carries the HTTP status, request id, and parsed response details when
+    available.
+    """
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        *,
+        status: Optional[int] = None,
+        request_id: Optional[str] = None,
+        details: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.request_id = request_id
+        self.details = details
+
+    def to_dict(self) -> Dict[str, Any]:
+        data = {
+            "error": type(self).__name__,
+            "message": self.message,
+            "status": self.status,
+            "request_id": self.request_id,
+            "details": self.details,
+        }
+        return {key: value for key, value in data.items() if value is not None}
+
+
+class AuthenticationError(Error):
+    """API key is missing or invalid (HTTP 401)."""
+
+    def __init__(self, message: str = "Unauthorized", *, status: int = 401, **kwargs: Any) -> None:
+        super().__init__(message, status=status, **kwargs)
+
+
+class RateLimitError(Error):
+    """Rate limit exceeded (HTTP 429). Includes the retry-after delay."""
+
+    def __init__(
+        self,
+        message: str = "Too many requests",
+        *,
+        status: int = 429,
+        retry_after: Optional[float] = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(message, status=status, **kwargs)
+        self.retry_after = retry_after
+
+
+class InsufficientCreditsError(Error):
+    """Account has insufficient credits (HTTP 402)."""
+
+    def __init__(self, message: str = "Insufficient credits", *, status: int = 402, **kwargs: Any) -> None:
+        super().__init__(message, status=status, **kwargs)
+
+
+class NotFoundError(Error):
+    """Requested resource does not exist (HTTP 404)."""
+
+    def __init__(self, message: str = "Not found", *, status: int = 404, **kwargs: Any) -> None:
+        super().__init__(message, status=status, **kwargs)
+
+
+class ValidationError(Error):
+    """Request validation failed (HTTP 400 / 422), or a client-side check failed."""
+
+    def __init__(self, message: str = "Validation failed", **kwargs: Any) -> None:
+        super().__init__(message, **kwargs)
+
+
+class ServiceUnavailableError(Error):
+    """Service is temporarily unavailable (HTTP 503)."""
+
+    def __init__(self, message: str = "Service unavailable", *, status: Optional[int] = None, **kwargs: Any) -> None:
+        super().__init__(message, status=503 if status is None else status, **kwargs)
+
+
+class ConflictError(Error):
+    """Request conflicts with the current resource state (HTTP 409)."""
+
+    def __init__(self, message: str = "Conflict", *, status: int = 409, **kwargs: Any) -> None:
+        super().__init__(message, status=status, **kwargs)
+
+
+class ServerError(Error):
+    """Server encountered an internal error (HTTP 5xx)."""
+
+    def __init__(self, message: str = "Server error", *, status: Optional[int] = None, **kwargs: Any) -> None:
+        super().__init__(message, status=500 if status is None else status, **kwargs)
+
+
+class NetworkError(Error):
+    """Network connection failed or the request could not be sent."""
+
+    def __init__(self, message: str = "Network error", **kwargs: Any) -> None:
+        super().__init__(message, **kwargs)
+
+
+class TimeoutError(Error):  # noqa: A001 - intentional SDK error name, parallels other SDKs
+    """HTTP request exceeded the configured timeout."""
+
+    def __init__(self, message: str = "Request timed out", **kwargs: Any) -> None:
+        super().__init__(message, **kwargs)
+
+
+class TaskTimeoutError(Error):
+    """Polling for task completion exceeded the maximum wait time."""
+
+    def __init__(self, message: str = "Task polling timed out", **kwargs: Any) -> None:
+        super().__init__(message, **kwargs)
+
+
+class TaskFailedError(Error):
+    """Async task failed during processing."""
+
+    def __init__(self, message: str = "Task failed", **kwargs: Any) -> None:
+        super().__init__(message, **kwargs)
+
+
+STATUS_MAP = {
+    400: ValidationError,
+    401: AuthenticationError,
+    402: InsufficientCreditsError,
+    404: NotFoundError,
+    409: ConflictError,
+    422: ValidationError,
+    429: RateLimitError,
+    500: ServerError,
+    501: ServerError,
+    502: ServerError,
+    503: ServiceUnavailableError,
+    504: ServerError,
+    505: ServerError,
+}
+
+DEFAULT_MESSAGES = {
+    400: "Bad request",
+    401: "Unauthorized",
+    402: "Insufficient credits",
+    404: "Not found",
+    408: "Request timeout",
+    409: "Conflict",
+    413: "Payload too large",
+    415: "Unsupported media type",
+    422: "Validation failed",
+    429: "Too many requests",
+    503: "Service unavailable",
+}
+
+
+def error_from_response(response: "Any") -> Error:
+    """Build the appropriate error from an ``httpx.Response``.
+
+    Maps the status code to a specific error class and extracts the message,
+    request id, response details, and (for 429) the retry-after delay.
+    """
+    status = response.status_code
+    request_id = response.headers.get("x-request-id")
+
+    parsed_body = _parse_body(response.text)
+    message = _extract_message(parsed_body) or DEFAULT_MESSAGES.get(status) or "Request failed"
+
+    error_class = STATUS_MAP.get(status, Error)
+
+    kwargs: Dict[str, Any] = {"status": status, "request_id": request_id, "details": parsed_body}
+    if error_class is RateLimitError:
+        kwargs["retry_after"] = _parse_retry_after(response.headers.get("retry-after"))
+
+    return error_class(message, **kwargs)
+
+
+def _parse_body(body: Optional[str]) -> Any:
+    if not body:
+        return None
+    if _HTML_MARKER.search(body):
+        return _extract_html_error(body)
+    try:
+        return json.loads(body)
+    except ValueError:
+        return body
+
+
+def _extract_html_error(html: str) -> Dict[str, Any]:
+    match = _TITLE.search(html) or _H1.search(html)
+    error_text = match.group(1) if match else "HTML Error Page"
+    error_text = _TAG.sub("", _ENTITY.sub(" ", error_text)).strip()
+    return {
+        "error": error_text,
+        "is_html_error": True,
+        "message": f"Server returned HTML error page: {error_text}",
+    }
+
+
+def _extract_message(body: Any) -> Optional[str]:
+    if not isinstance(body, dict):
+        return None
+
+    error = body.get("error")
+    if isinstance(error, dict):
+        message = error.get("message")
+    else:
+        message = error
+
+    if message:
+        return message
+
+    errors = body.get("errors")
+    if isinstance(errors, list) and errors:
+        first = errors[0]
+        return first.get("message") if isinstance(first, dict) else first
+
+    return body.get("message") or body.get("detail") or body.get("errorMessage") or body.get("msg")
+
+
+def _parse_retry_after(value: Optional[str]) -> Optional[float]:
+    if value is None:
+        return None
+
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        pass
+
+    try:
+        parsed = parsedate_to_datetime(value)
+    except (TypeError, ValueError):
+        return None
+    if parsed is None:
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return (parsed - datetime.now(timezone.utc)).total_seconds()

runapi/core/files.py

@@ -0,0 +1,101 @@
+"""File upload client.
+
+Shared infrastructure for every model line that takes file inputs: upload a
+local file or register a remote URL and receive a usable file reference.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Optional
+
+from . import auth
+from .http_client import HttpClient
+from .models import BaseModel, optional, required
+from .multipart import MultipartBody, MultipartFile
+from .options import ClientOptions, RequestOptions
+from .resource import Resource
+
+
+class UploadResponse(BaseModel):
+    file_name = required(str)
+    url = required(str)
+    size_bytes = required(int)
+    mime_type = required(str)
+    created_at = required(str)
+    expires_at = required(str)
+
+
+class FilesClient(Resource):
+    ENDPOINT = "/api/v1/files"
+
+    RESPONSE_CLASS = UploadResponse
+
+    def __init__(self, api_key: Optional[str] = None, **options: Any) -> None:
+        resolved_api_key = auth.resolve_api_key(api_key)
+        client_options = ClientOptions(api_key=resolved_api_key, **options)
+        http = client_options.http_client or HttpClient(client_options)
+        super().__init__(http)
+
+    def create(
+        self,
+        file: Any = None,
+        source: Optional[str] = None,
+        file_name: Optional[str] = None,
+        options: Optional[RequestOptions] = None,
+    ) -> Any:
+        """Upload a local ``file`` (path or file-like) or register a remote ``source`` URL.
+
+        Exactly one of ``file`` or ``source`` is required.
+
+        Args:
+            file: Local file path or file-like object to upload.
+            source: Remote URL to register instead of uploading a local file.
+            file_name: Optional name to record for the uploaded file.
+            options: Optional per-request options.
+
+        Returns:
+            The upload response with the usable file reference.
+        """
+        self._validate_source(file, source)
+
+        if file is not None:
+            body: Any = self._multipart_body(file, file_name)
+        else:
+            body = self._compact_params({"source": source, "file_name": file_name})
+
+        return self._request("post", self.ENDPOINT, body=body, options=options)
+
+    @staticmethod
+    def _validate_source(file: Any, source: Optional[str]) -> None:
+        def present(value: Any) -> bool:
+            if value is None:
+                return False
+            if isinstance(value, str):
+                return value.strip() != ""
+            return True
+
+        provided = sum(1 for value in (file, source) if present(value))
+        if provided != 1:
+            raise ValueError("Exactly one source is required: file or source")
+
+    def _multipart_body(self, file: Any, file_name: Optional[str]) -> MultipartBody:
+        path = self._file_path(file)
+        filename = file_name or os.path.basename(path)
+        return MultipartBody(
+            fields=self._compact_params({"file_name": file_name}),
+            files={"file": MultipartFile(path=path, filename=filename)},
+        )
+
+    @staticmethod
+    def _file_path(file: Any) -> str:
+        if isinstance(file, str):
+            return file
+        # pathlib.Path (and any os.PathLike) must keep their full path; Path.name
+        # would return only the basename, breaking the later open().
+        if isinstance(file, os.PathLike):
+            return os.fspath(file)
+        name = getattr(file, "name", None)
+        if name:
+            return name
+        raise ValueError("file must be a file path or a file-like object with a name")

runapi/core/http_client.py

@@ -0,0 +1,130 @@
+"""HTTP transport built on ``httpx.Client`` with retries and multipart support."""
+
+from __future__ import annotations
+
+import json
+import random
+import time
+from typing import Any, Dict, List, Optional, Tuple
+
+import httpx
+
+from . import constants
+from .errors import NetworkError, RateLimitError, TimeoutError, error_from_response
+from .multipart import MultipartBody
+from .options import ClientOptions, RequestOptions
+
+_NO_BODY = object()
+
+
+class HttpClient:
+    """Synchronous HTTP client.
+
+    ``httpx.Client`` keeps connections alive across requests, so no explicit
+    connection pool is needed. Pass ``transport`` to inject an
+    ``httpx.MockTransport`` in tests.
+    """
+
+    def __init__(self, options: ClientOptions, *, transport: Optional[httpx.BaseTransport] = None) -> None:
+        self._options = options
+        self._client = httpx.Client(
+            base_url=options.base_url,
+            timeout=options.timeout,
+            transport=transport,
+            headers={
+                "Authorization": f"Bearer {options.api_key}",
+                "Accept": "application/json",
+                "User-Agent": constants.SDK_USER_AGENT,
+            },
+        )
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        body: Any = None,
+        options: Optional[RequestOptions] = None,
+    ) -> Any:
+        max_retries = self._options.max_retries
+        if options is not None and options.max_retries is not None:
+            max_retries = options.max_retries
+
+        headers = {str(key): str(value) for key, value in (options.headers or {}).items()} if options else {}
+        timeout = options.timeout if (options and options.timeout is not None) else httpx.USE_CLIENT_DEFAULT
+
+        json_body, data, files, opened = self._build_payload(body)
+        method = method.upper()
+        retries = 0
+
+        try:
+            while True:
+                try:
+                    response = self._client.request(
+                        method,
+                        path,
+                        json=json_body,
+                        data=data,
+                        files=files,
+                        headers=headers,
+                        timeout=timeout,
+                    )
+                except httpx.TimeoutException as exc:
+                    raise TimeoutError(str(exc))
+                except httpx.TransportError as exc:
+                    raise NetworkError(str(exc))
+
+                if response.is_success:
+                    return self._parse_body(response.text)
+
+                error = error_from_response(response)
+                if self._retryable(method, response.status_code) and retries < max_retries:
+                    retries += 1
+                    time.sleep(self._retry_delay(retries, error))
+                    continue
+
+                raise error
+        finally:
+            for handle in opened:
+                handle.close()
+
+    def close(self) -> None:
+        self._client.close()
+
+    def _build_payload(
+        self, body: Any
+    ) -> Tuple[Any, Optional[Dict[str, Any]], Optional[Dict[str, Any]], List[Any]]:
+        if isinstance(body, MultipartBody):
+            data = {key: str(value) for key, value in body.fields.items()}
+            files: Dict[str, Any] = {}
+            opened: List[Any] = []
+            for key, part in body.files.items():
+                handle = open(part.path, "rb")
+                opened.append(handle)
+                filename = part.filename
+                if part.content_type:
+                    files[key] = (filename, handle, part.content_type)
+                else:
+                    files[key] = (filename, handle)
+            return None, data, files, opened
+        if body is not None:
+            return body, None, None, []
+        return None, None, None, []
+
+    def _retryable(self, method: str, status: int) -> bool:
+        return method in constants.IDEMPOTENT_METHODS and status in constants.RETRYABLE_STATUS_CODES
+
+    def _retry_delay(self, attempt: int, error: Any) -> float:
+        if isinstance(error, RateLimitError) and error.retry_after and error.retry_after > 0:
+            return error.retry_after
+        base = self._options.retry_base_delay * (2 ** (attempt - 1))
+        jitter = random.random() * base * 0.5
+        return min(base + jitter, self._options.retry_max_delay)
+
+    @staticmethod
+    def _parse_body(body: Optional[str]) -> Any:
+        if not body:
+            return None
+        try:
+            return json.loads(body)
+        except ValueError:
+            return body