runapi-core 0.9.0__tar.gz → 0.10.0__tar.gz

{runapi_core-0.9.0 → runapi_core-0.10.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.5
 Name: runapi-core
-Version: 0.9.0
+Version: 0.10.0
 Summary: RunAPI core SDK for JavaScript, Python, Ruby, Go, Java, and PHP
 Project-URL: Homepage, https://runapi.ai/models
 Project-URL: Documentation, https://runapi.ai/docs/resources/sdks
 Project-URL: Source, https://github.com/runapi-ai/core-sdk
 Project-URL: Issues, https://github.com/runapi-ai/core-sdk/issues
 Project-URL: Changelog, https://github.com/runapi-ai/core-sdk/blob/main/CHANGELOG.md
-Project-URL: Release Notes, https://github.com/runapi-ai/core-sdk/releases/tag/python%2Fv0.9.0
+Project-URL: Release Notes, https://github.com/runapi-ai/core-sdk/releases/tag/python%2Fv0.10.0
 Author-email: RunAPI <contact@runapi.ai>
 License-Expression: Apache-2.0
 Keywords: api,core,golang,gradle,java,maven,pypi,python,ruby,runapi,runapi-ai,sdk,typescript

{runapi_core-0.9.0 → runapi_core-0.10.0}/pyproject.toml

@@ -19,7 +19,7 @@ Documentation = "https://runapi.ai/docs/resources/sdks"
 Source = "https://github.com/runapi-ai/core-sdk"
 Issues = "https://github.com/runapi-ai/core-sdk/issues"
 Changelog = "https://github.com/runapi-ai/core-sdk/blob/main/CHANGELOG.md"
-"Release Notes" = "https://github.com/runapi-ai/core-sdk/releases/tag/python%2Fv0.9.0"
+"Release Notes" = "https://github.com/runapi-ai/core-sdk/releases/tag/python%2Fv0.10.0"
 
 [tool.hatch.version]
 path = "src/runapi/core/version.py"

{runapi_core-0.9.0 → runapi_core-0.10.0}/src/runapi/core/__init__.py

@@ -8,7 +8,6 @@ from . import config, errors, polling
 from .auth import resolve_api_key, resolve_optional_api_key
 from .account import Account, AccountBalanceResponse, AccountInfoResponse, AccountRecord
 from .config import configure
-from .contract_gen import CONTRACT
 from .errors import (
     AuthenticationError,
     ConflictError,
@@ -52,7 +51,6 @@ __all__ = [
     "configure",
     "errors",
     "polling",
-    "CONTRACT",
     "resolve_api_key",
     "resolve_optional_api_key",
     "Account",

runapi_core-0.10.0/src/runapi/core/resource.py

@@ -0,0 +1,192 @@
+"""Base class for API resources: request coercion, param helpers, polling."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from typing import Any, Callable, Dict, Optional
+from uuid import uuid4
+
+from . import polling
+from .errors import TaskFailedError, ValidationError, _parse_retry_after, error_from_response_data
+from .models import BaseModel, TaskResult, TaskResponse
+from .options import PollingOptions, RequestOptions
+from .response import ApiResponse
+
+
+class Resource:
+    """Shared behavior for resource classes.
+
+    Subclasses set ``RESPONSE_CLASS`` (the typed model for responses) and
+    optionally ``COMPLETED_RESPONSE_CLASS`` (a narrowed model that ``run()``
+    re-coerces to once the task completes).
+    """
+
+    RESPONSE_CLASS: Optional[type] = TaskResponse
+    COMPLETED_RESPONSE_CLASS: Optional[type] = None
+
+    def __init__(self, http: Any) -> None:
+        self._http = http
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: Any = None,
+        options: Optional[RequestOptions] = None,
+        response_class: Optional[type] = None,
+    ) -> Any:
+        response = self._http.request(method, path, body=body, options=options)
+        return self._coerce_response(response, response_class)
+
+    def _coerce_response(self, response: Any, response_class: Optional[type] = None) -> Any:
+        payload = response.body if isinstance(response, ApiResponse) else response
+        target = response_class or type(self).RESPONSE_CLASS
+        result = payload if target is None else BaseModel.coerce(payload, as_=target)
+        if isinstance(response, ApiResponse):
+            self._attach_response_headers(result, response.response_headers)
+        return result
+
+    def _run_hybrid(
+        self,
+        method: str,
+        path: str,
+        body: Any = None,
+        options: Optional[RequestOptions] = None,
+        polling_options: Optional[PollingOptions] = None,
+    ) -> Any:
+        """Run a terminal-or-accepted Task endpoint through one stable API."""
+        request_options = self._with_idempotency_key(options) if method.upper() == "POST" else options
+        response = self._http.request(method, path, body=body, options=request_options)
+        if isinstance(response, ApiResponse) and response.status_code == 202:
+            location = response.response_headers.get("Location")
+            if not location:
+                raise TaskFailedError(
+                    "Accepted Task response is missing Location",
+                    response_headers=response.response_headers,
+                )
+            return self.subscribe(
+                location,
+                options=request_options,
+                polling_options=polling_options,
+                initial_delay=self._retry_after(response.response_headers),
+            )
+        return self._coerce_response(response)
+
+    def subscribe(
+        self,
+        location: str,
+        *,
+        options: Optional[RequestOptions] = None,
+        polling_options: Optional[PollingOptions] = None,
+        initial_delay: Optional[float] = None,
+    ) -> Any:
+        """Follow an opaque Task Result URL until its stored terminal response is ready."""
+        return self._poll_until_complete(
+            lambda: self._request("get", location, options=options, response_class=TaskResult),
+            polling_options,
+            initial_delay=initial_delay,
+            completed=self._decode_task_result,
+            failed=self._task_result_error,
+        )
+
+    def _with_idempotency_key(self, options: Optional[RequestOptions]) -> RequestOptions:
+        headers = {}
+        idempotency_key = None
+        source_headers = (options.headers or {}) if options else {}
+        for name, value in source_headers.items():
+            if name.lower() != "idempotency-key":
+                headers[name] = value
+                continue
+
+            normalized = str(value).strip()
+            if not normalized:
+                continue
+            if idempotency_key is not None and idempotency_key != normalized:
+                raise ValidationError("conflicting Idempotency-Key headers")
+            idempotency_key = normalized
+
+        headers["Idempotency-Key"] = idempotency_key or str(uuid4())
+        return replace(options, headers=headers) if options else RequestOptions(headers=headers)
+
+    def _decode_task_result(self, task: TaskResult) -> Any:
+        response = task.response
+        if response is None:
+            raise TaskFailedError("Completed Task is missing its terminal response", details=task.to_dict())
+        if not 200 <= response.status < 300:
+            raise self._task_result_error(task)
+
+        body = self._plain_value(response.body)
+        content_type = response.content_type.lower().split(";", 1)[0].strip()
+        if content_type == "application/json" or content_type.endswith("+json"):
+            response_class = type(self).RESPONSE_CLASS
+            result = body if response_class is None else BaseModel.coerce(body, as_=response_class)
+            self._attach_response_headers(result, response.headers or {})
+            return result
+        if self._textual_content_type(content_type):
+            if isinstance(body, bytes):
+                return body.decode("utf-8")
+            return "" if body is None else str(body)
+        if isinstance(body, bytes):
+            return body
+        if isinstance(body, str):
+            return body.encode("utf-8")
+        return body
+
+    def _task_result_error(self, task: TaskResult) -> Exception:
+        response = task.response
+        if response is None:
+            return TaskFailedError("Task failed without a terminal response", details=task.to_dict())
+        return error_from_response_data(
+            response.status,
+            self._plain_value(response.body),
+            response.headers or {},
+        )
+
+    def _poll_until_complete(
+        self,
+        fetch: Callable[[], Any],
+        polling_opts: Optional[PollingOptions] = None,
+        **kwargs: Any,
+    ) -> Any:
+        response = polling.poll_until_complete(fetch, polling_opts or PollingOptions(), **kwargs)
+
+        if kwargs.get("completed"):
+            return response
+
+        completed_class = type(self).COMPLETED_RESPONSE_CLASS
+        if completed_class is None or isinstance(response, completed_class):
+            return response
+
+        payload = response.to_dict() if isinstance(response, BaseModel) else response
+        completed = completed_class.from_dict(payload)
+        if isinstance(response, BaseModel):
+            completed._with_response_headers(response.response_headers)
+        return completed
+
+    @staticmethod
+    def _plain_value(value: Any) -> Any:
+        return value.to_dict() if isinstance(value, BaseModel) else value
+
+    @staticmethod
+    def _textual_content_type(content_type: str) -> bool:
+        return content_type.startswith("text/") or content_type in {"application/srt", "application/x-subrip"}
+
+    @staticmethod
+    def _retry_after(headers: Any) -> Optional[float]:
+        delay = _parse_retry_after(headers.get("Retry-After") if headers else None)
+        return delay if delay and delay > 0 else None
+
+    @staticmethod
+    def _compact_params(params: Dict[str, Any]) -> Dict[str, Any]:
+        return {
+            key: value
+            for key, value in params.items()
+            if not (value is None or (isinstance(value, str) and value.strip() == ""))
+        }
+
+    def _attach_response_headers(self, result: Any, headers: Any) -> None:
+        if isinstance(result, BaseModel):
+            result._with_response_headers(headers)
+        elif isinstance(result, list):
+            for item in result:
+                self._attach_response_headers(item, headers)

runapi_core-0.10.0/src/runapi/core/version.py

@@ -0,0 +1 @@
+__version__ = "0.10.0"

{runapi_core-0.9.0 → runapi_core-0.10.0}/tests/test_files.py

@@ -3,8 +3,6 @@ import hashlib
 import os
 import tempfile
 
-import pytest
-
 from runapi.core import FilesClient
 
 
@@ -41,15 +39,6 @@ UPLOAD = {
 }
 
 
-def test_requires_exactly_one_source():
-    fake = FakeHttp(UPLOAD)
-    client = FilesClient(api_key="k", http_client=fake)
-    with pytest.raises(ValueError):
-        client.create()
-    with pytest.raises(ValueError):
-        client.create(file="x", source="y")
-
-
 def test_accepts_an_existing_http_client_without_resolving_auth_again():
     fake = FakeHttp(UPLOAD)
 
@@ -169,15 +158,6 @@ def test_create_with_pathlib_path_keeps_full_path():
     assert fake.uploads[0][2] == b"png"
 
 
-def test_create_rejects_blank_source():
-    # Regression: a blank source must fail locally, not POST an empty body.
-    client = FilesClient(api_key="k", http_client=FakeHttp(UPLOAD))
-    with pytest.raises(ValueError):
-        client.create(source="")
-    with pytest.raises(ValueError):
-        client.create(source="   ")
-
-
 def test_protocol_file_lifecycle_keeps_binary_content(tmp_path):
     path = tmp_path / "input.bin"
     path.write_bytes(b"\x00\xff\x01")

{runapi_core-0.9.0 → runapi_core-0.10.0}/tests/test_resource.py

@@ -79,114 +79,6 @@ def test_compact_params_drops_none_and_blank():
     assert Resource._compact_params({"a": 1, "b": None, "c": "", "d": "  ", "e": "x"}) == {"a": 1, "e": "x"}
 
 
-def test_validate_optional_passes_and_rejects():
-    Resource._validate_optional({"k": "a"}, "k", ["a", "b"])
-    Resource._validate_optional({}, "k", ["a", "b"])
-    with pytest.raises(ValidationError, match="Invalid k"):
-        Resource._validate_optional({"k": "z"}, "k", ["a", "b"])
-
-
-INT_SCHEMA = {
-    "models": ["m"],
-    "fields_by_model": {
-        "m": {
-            "duration_int": {"type": "integer", "min": 4, "max": 12},
-            "tolerance": {"type": "integer"}}
-    }}
-
-
-def _run_validate(params):
-    resource = SampleResource(FakeHttp())
-    try:
-        resource._validate_contract(INT_SCHEMA, params)
-        return ""
-    except ValidationError as err:
-        return str(err)
-
-
-def test_validate_integer_rejects_non_integer_within_range():
-    assert _run_validate({"model": "m", "duration_int": 11.5}) == "duration_int must be an integer between 4 and 12"
-
-
-def test_validate_integer_runs_before_range():
-    # A non-integer below the range reports the integer error, not the range one.
-    assert _run_validate({"model": "m", "duration_int": 2.5}) == "duration_int must be an integer between 4 and 12"
-
-
-def test_validate_bare_integer_has_no_range_detail():
-    assert _run_validate({"model": "m", "tolerance": 3.5}) == "tolerance must be an integer"
-
-
-def test_validate_integer_still_enforces_range_for_valid_int():
-    assert _run_validate({"model": "m", "duration_int": 13}) == "duration_int must be between 4 and 12"
-
-
-def test_validate_functional_action_uses_underscore_fields():
-    resource = SampleResource(FakeHttp())
-    schema = {
-        "models": [],
-        "fields_by_model": {
-            "_": {
-                "prompt": {"required": True},
-                "mode": {"enum": ["fast", "quality"]}}
-        }}
-    resource._validate_contract(schema, {"prompt": "hello", "mode": "fast"})
-    with pytest.raises(ValidationError, match="prompt is required"):
-        resource._validate_contract(schema, {"mode": "fast"})
-    with pytest.raises(ValidationError, match="mode must be one of: fast, quality"):
-        resource._validate_contract(schema, {"prompt": "hello", "mode": "slow"})
-
-
-def test_validate_integer_rejects_bool_and_whole_float():
-    # bool is an int subclass but is not a valid integer value.
-    assert _run_validate({"model": "m", "tolerance": True}) == "tolerance must be an integer"
-    # Python keeps the float/int distinction: a whole-valued float is still a float.
-    assert _run_validate({"model": "m", "tolerance": 5.0}) == "tolerance must be an integer"
-    assert _run_validate({"model": "m", "tolerance": 5}) == ""
-
-
-def test_validate_boolean_enum_requires_boolean_value():
-    schema = {"models": ["m"], "fields_by_model": {"m": {"flag": {"enum": [True, False]}}}}
-    resource = SampleResource(FakeHttp())
-
-    resource._validate_contract(schema, {"model": "m", "flag": True})
-    resource._validate_contract(schema, {"model": "m", "flag": False})
-    with pytest.raises(ValidationError, match="^flag must be one of: True, False$"):
-        resource._validate_contract(schema, {"model": "m", "flag": "true"})
-
-
-def test_validate_array_item_count_constraints():
-    schema = {
-        "models": ["m"],
-        "fields_by_model": {
-            "m": {
-                "reference_image_urls": {"min_items": 1, "max_items": 3}}
-        }}
-    resource = SampleResource(FakeHttp())
-
-    with pytest.raises(ValidationError, match="^reference_image_urls must be an array$"):
-        resource._validate_contract(schema, {"model": "m", "reference_image_urls": "image.png"})
-    with pytest.raises(ValidationError, match="^reference_image_urls must contain between 1 and 3 items$"):
-        resource._validate_contract(schema, {"model": "m", "reference_image_urls": []})
-    with pytest.raises(ValidationError, match="^reference_image_urls must contain between 1 and 3 items$"):
-        resource._validate_contract(schema, {"model": "m", "reference_image_urls": ["a", "b", "c", "d"]})
-    with pytest.raises(ValidationError, match="^reference_image_urls must contain between 1 and 3 items$"):
-        resource._validate_contract(schema, {"model": "m", "reference_image_urls": ("a", "b", "c", "d")})
-
-    resource._validate_contract(schema, {"model": "m", "reference_image_urls": ["a", "b", "c"]})
-    resource._validate_contract(schema, {"model": "m", "reference_image_urls": ("a", "b", "c")})
-
-
-def test_validate_contract_runs_rules_before_field_requirements():
-    schema = {
-        "models": ["m"],
-        "rules": [{"when": {"model": "m"}, "forbidden": ["source_task_id"]}],
-        "fields_by_model": {"m": {"source_image_urls": {"required": True}}}}
-    resource = SampleResource(FakeHttp())
-    with pytest.raises(ValidationError, match="source_task_id is not allowed when model is m"):
-        resource._validate_contract(schema, {"model": "m", "source_task_id": "src_1"})
-
-
 def test_poll_recoerces_to_completed_class():
     resource = SampleResource(FakeHttp())
     response = TaskResponse({"id": "1", "status": "completed", "usage": {"cost": 0.05}, "images": [{"url": "u"}]})