abysshub 0.1.1.dev1__tar.gz → 0.1.1.dev3__tar.gz

{abysshub-0.1.1.dev1 → abysshub-0.1.1.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: abysshub
-Version: 0.1.1.dev1
+Version: 0.1.1.dev3
 Summary: The official Python library for the Abyss API.
 Project-URL: Homepage, https://abysshub.com
 Project-URL: Source, https://github.com/Abysshub/abysshub-sdk
@@ -133,6 +133,9 @@ A refusal, a failed run, a timeout and a lost connection all raise one class, `A
 | `param` | the Field, body key, query key or header at fault, else `None` |
 | `doc_url` | the code on the API access page, else `None` |
 | `request_id` | quote it to support, else `None` |
+| `shortfall` | with `insufficient_funds`: how much Byssium the wallet is short, else `None` |
+| `price` | with `price_above_max`: what the run costs now, else `None` |
+| `run_id` | the id of the run the call started or read, once the press's `Location` or a run body named it, else `None` |
 | `run` | the run, for a failed run or a timeout, else `None`; an `AsyncRun` from `AsyncAbyss` |
 
 - **Refusals:** `invalid_api_key` (401), `not_found` (404), `invalid_request`, `invalid_input`, `held_input_*`, `input_unreachable` and `idempotency_key_reused` (422), `insufficient_funds` (402), `spend_cap_reached` and `price_above_max` (400), `idempotency_key_in_use` (409), `rate_limited` (429), `server_error` (500).
@@ -159,11 +162,12 @@ There is no timeout by default: `run()` waits as long as the run takes. `timeout
 try:
     run = abyss.run("widget_131", input, timeout=60)
 except AbyssError as error:
-    if error.code == "timeout":
-        ...  # The run goes on. error.run is the run as last seen, or None when none was seen yet.
+    if error.code == "timeout" and error.run_id:
+        # The run goes on: wait for it again, without pressing (and paying) twice.
+        run = abyss.runs.get(error.run_id, wait=True)
 ```
 
-It raises `AbyssError` with `code == "timeout"` and `run`, the run as last seen. During the press's first hold the run has not been seen yet, so `run` is `None`; to keep its `id` whatever happens, press with `runs.create()` and wait with `runs.get(id, wait=True, timeout=...)`.
+It raises `AbyssError` with `code == "timeout"`, `run`, the run as last seen or `None`, and `run_id`, the run's id. The press answers its `Location` at once, so `run_id` is set as soon as the press has answered, even while no run has been seen yet; it is `None` only when the waiting stopped before that. Nothing is sent after the waiting stops.
 
 ## Async
 

{abysshub-0.1.1.dev1 → abysshub-0.1.1.dev3}/README.md

@@ -116,6 +116,9 @@ A refusal, a failed run, a timeout and a lost connection all raise one class, `A
 | `param` | the Field, body key, query key or header at fault, else `None` |
 | `doc_url` | the code on the API access page, else `None` |
 | `request_id` | quote it to support, else `None` |
+| `shortfall` | with `insufficient_funds`: how much Byssium the wallet is short, else `None` |
+| `price` | with `price_above_max`: what the run costs now, else `None` |
+| `run_id` | the id of the run the call started or read, once the press's `Location` or a run body named it, else `None` |
 | `run` | the run, for a failed run or a timeout, else `None`; an `AsyncRun` from `AsyncAbyss` |
 
 - **Refusals:** `invalid_api_key` (401), `not_found` (404), `invalid_request`, `invalid_input`, `held_input_*`, `input_unreachable` and `idempotency_key_reused` (422), `insufficient_funds` (402), `spend_cap_reached` and `price_above_max` (400), `idempotency_key_in_use` (409), `rate_limited` (429), `server_error` (500).
@@ -142,11 +145,12 @@ There is no timeout by default: `run()` waits as long as the run takes. `timeout
 try:
     run = abyss.run("widget_131", input, timeout=60)
 except AbyssError as error:
-    if error.code == "timeout":
-        ...  # The run goes on. error.run is the run as last seen, or None when none was seen yet.
+    if error.code == "timeout" and error.run_id:
+        # The run goes on: wait for it again, without pressing (and paying) twice.
+        run = abyss.runs.get(error.run_id, wait=True)
 ```
 
-It raises `AbyssError` with `code == "timeout"` and `run`, the run as last seen. During the press's first hold the run has not been seen yet, so `run` is `None`; to keep its `id` whatever happens, press with `runs.create()` and wait with `runs.get(id, wait=True, timeout=...)`.
+It raises `AbyssError` with `code == "timeout"`, `run`, the run as last seen or `None`, and `run_id`, the run's id. The press answers its `Location` at once, so `run_id` is set as soon as the press has answered, even while no run has been seen yet; it is `None` only when the waiting stopped before that. Nothing is sent after the waiting stops.
 
 ## Async
 

{abysshub-0.1.1.dev1 → abysshub-0.1.1.dev3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "abysshub"
-version = "0.1.1.dev1"
+version = "0.1.1.dev3"
 description = "The official Python library for the Abyss API."
 readme = "README.md"
 license = "MIT"

{abysshub-0.1.1.dev1 → abysshub-0.1.1.dev3}/src/abysshub/_async_client.py

@@ -14,6 +14,7 @@ from ._client import (
     _Call,
     _expect,
     _has_ended,
+    _heard,
     _is_key,
     _is_run,
     _is_run_list,
@@ -260,7 +261,14 @@ class AsyncAbyss(_Base[AsyncRun]):
             self._check(call)
             try:
                 answer = await arequest(
-                    self._http, method, url, sent_headers, content, self._timeouts(call), call.deadline
+                    self._http,
+                    method,
+                    url,
+                    sent_headers,
+                    content,
+                    self._timeouts(call),
+                    call.deadline,
+                    lambda headers: _heard(call, headers),
                 )
             except Stopped:
                 raise self._timed_out(call) from None

{abysshub-0.1.1.dev1 → abysshub-0.1.1.dev3}/src/abysshub/_client.py

@@ -4,6 +4,7 @@ import json
 import math
 import os
 import platform
+import re
 import time
 import uuid
 from collections.abc import Callable, Mapping
@@ -25,6 +26,9 @@ API = "https://api.abysshub.com"
 DEV_API = "https://api.dev.abysshub.com"
 DEV_KEY_PREFIX = "abyss_sk_dev_"
 
+RUN_LOCATION = re.compile(r"/v1/runs/([^/?#]+)/?(?:[?#]|$)")
+"""A ``Location`` naming a run, ``…/v1/runs/{id}``, with the id as its group."""
+
 REATTACH_PAUSE = 1.0
 """Seconds between two re-attaches that both ended without the run's ending."""
 
@@ -55,16 +59,21 @@ class _Reply:
     """Whether the connection was cut, or went silent, after the headers."""
     location: str | None
     request_id: str | None
+    run_id: str | None
+    """The id of the call's run, as far as the call knew it when this reply arrived."""
 
 
 @dataclass
 class _Call:
-    """One call's waiting: when it stops, and the run as last seen, for a timeout to carry."""
+    """One call's waiting: when it stops, and what a timeout carries: the run as last
+    seen, the run's id once known, and the latest ``Request-Id``."""
 
     timeout: float | None
     deadline: float | None
     """A ``time.monotonic()`` reading, or None to wait as long as it takes."""
     seen: dict[str, Any] | None = None
+    run_id: str | None = None
+    request_id: str | None = None
 
     def left(self) -> float | None:
         return None if self.deadline is None else self.deadline - time.monotonic()
@@ -182,6 +191,8 @@ class _Base(Generic[R]):
         return AbyssError(
             "timeout",
             f"Stopped waiting after {call.timeout} s. The run goes on.",
+            request_id=call.request_id,
+            run_id=call.run_id,
             run=self._run(call.seen) if call.seen is not None else None,
         )
 
@@ -268,6 +279,7 @@ class _Base(Generic[R]):
                 "unexpected_response",
                 "The press answered without a Location to read the run at.",
                 request_id=reply.request_id,
+                run_id=reply.run_id,
             )
         return str(httpx.URL(f"{self.base_url}/").join(location).copy_set_param("wait", "true"))
 
@@ -290,6 +302,7 @@ class _Base(Generic[R]):
             raise AbyssError(
                 "connection_error",
                 "The connection dropped, or timed out, before the API answered.",
+                run_id=call.run_id,
             ) from error
         return _backoff(attempt)
 
@@ -302,10 +315,12 @@ class _Base(Generic[R]):
             run = parsed if _is_run(parsed) else None
             if run is not None:
                 call.seen = run
-            return _Reply(parsed, run, answer.text is None, answer.headers.get("location"), request_id)
+                call.run_id = run["id"]
+            location = answer.headers.get("location")
+            return _Reply(parsed, run, answer.text is None, location, request_id, call.run_id)
         pause = _retry_pause(answer, attempt)
         if pause is None or attempt >= limit:
-            raise _refusal(answer.status, parsed, request_id)
+            raise _refusal(answer.status, parsed, request_id, call.run_id)
         return pause
 
     def _ended(self, reply: _Reply) -> R:
@@ -314,7 +329,7 @@ class _Base(Generic[R]):
         run = self._run(reply.run)
         if run.status == "failed":
             error = run.error or RunError("platform_fault", "The run failed.")
-            raise AbyssError(error.code, error.message, request_id=reply.request_id, run=run)
+            raise AbyssError(error.code, error.message, request_id=reply.request_id, run_id=run.id, run=run)
         return run
 
 
@@ -481,7 +496,16 @@ class Abyss(_Base[Run]):
         while True:
             self._check(call)
             try:
-                answer = request(self._http, method, url, sent_headers, content, self._timeouts(call), call.deadline)
+                answer = request(
+                    self._http,
+                    method,
+                    url,
+                    sent_headers,
+                    content,
+                    self._timeouts(call),
+                    call.deadline,
+                    lambda headers: _heard(call, headers),
+                )
             except Stopped:
                 raise self._timed_out(call) from None
             except httpx.TransportError as error:
@@ -495,6 +519,14 @@ class Abyss(_Base[Run]):
             attempt += 1
 
 
+def _heard(call: _Call, headers: httpx.Headers) -> None:
+    """Notes a response's headers as they arrive: its ``Request-Id``, and the run its ``Location`` names."""
+    call.request_id = headers.get("request-id", call.request_id)
+    match = RUN_LOCATION.search(headers.get("location", ""))
+    if match is not None:
+        call.run_id = match.group(1)
+
+
 def _retry_pause(answer: Answer, attempt: int) -> float | None:
     """How long to wait before sending a refused request again, or None when it is not retried."""
     if answer.status in (409, 429):
@@ -516,10 +548,10 @@ def _expect(reply: _Reply, is_: Callable[[Any], bool], message: str) -> Any:
     """The reply's body when it is what the route answers, else ``unexpected_response``."""
     if is_(reply.body):
         return reply.body
-    raise AbyssError("unexpected_response", message, request_id=reply.request_id)
+    raise AbyssError("unexpected_response", message, request_id=reply.request_id, run_id=reply.run_id)
 
 
-def _refusal(status: int, body: Any, request_id: str | None) -> AbyssError:
+def _refusal(status: int, body: Any, request_id: str | None, run_id: str | None) -> AbyssError:
     error = body.get("error") if isinstance(body, dict) else None
     if not isinstance(error, dict) or not isinstance(error.get("code"), str):
         return AbyssError(
@@ -527,6 +559,7 @@ def _refusal(status: int, body: Any, request_id: str | None) -> AbyssError:
             f"The API answered {status} without an error body.",
             status=status,
             request_id=request_id,
+            run_id=run_id,
         )
     body_request_id = body.get("request_id")
     return AbyssError(
@@ -535,7 +568,10 @@ def _refusal(status: int, body: Any, request_id: str | None) -> AbyssError:
         status=status,
         param=_text(error.get("param")),
         doc_url=_text(error.get("doc_url")),
+        shortfall=_number(error.get("shortfall")),
+        price=_number(error.get("price")),
         request_id=body_request_id if isinstance(body_request_id, str) else request_id,
+        run_id=run_id,
     )
 
 
@@ -543,6 +579,12 @@ def _text(value: Any) -> str | None:
     return value if isinstance(value, str) else None
 
 
+def _number(value: Any) -> float | None:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    return float(value)
+
+
 def _parse(text: str | None) -> Any:
     if text is None:
         return None

{abysshub-0.1.1.dev1 → abysshub-0.1.1.dev3}/src/abysshub/_error.py

@@ -19,6 +19,14 @@ class AbyssError(Exception):
     param: str | None
     doc_url: str | None
     request_id: str | None
+    run_id: str | None
+    """The id of the run the call started or read, once the call has learned it from a
+    ``Location`` header or a run body; else None. A ``timeout`` carries it even when no
+    run body has arrived, so ``runs.get(run_id, wait=True)`` finds the run again."""
+    shortfall: float | None
+    """With ``insufficient_funds``: how much Byssium the wallet is short; else None."""
+    price: float | None
+    """With ``price_above_max``: what the run costs now; else None."""
     run: Run | AsyncRun | None
     """The run, for a failed run or a timeout: an ``AsyncRun`` from ``AsyncAbyss``."""
 
@@ -31,6 +39,9 @@ class AbyssError(Exception):
         param: str | None = None,
         doc_url: str | None = None,
         request_id: str | None = None,
+        run_id: str | None = None,
+        shortfall: float | None = None,
+        price: float | None = None,
         run: Run | AsyncRun | None = None,
     ) -> None:
         super().__init__(message)
@@ -40,6 +51,9 @@ class AbyssError(Exception):
         self.param = param
         self.doc_url = doc_url
         self.request_id = request_id
+        self.run_id = run_id
+        self.shortfall = shortfall
+        self.price = price
         self.run = run
 
     def __repr__(self) -> str:

{abysshub-0.1.1.dev1 → abysshub-0.1.1.dev3}/src/abysshub/_http.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import time
+from collections.abc import Callable
 from dataclasses import dataclass
 
 import httpx
@@ -37,16 +38,21 @@ def request(
     content: bytes | None = None,
     timeout: httpx.Timeout | None = None,
     deadline: float | None = None,
+    heard: Callable[[httpx.Headers], None] | None = None,
 ) -> Answer:
     """Sends one request and reads its whole body.
 
     A failure before the headers raises ``httpx.TransportError``; a cut after them
     answers ``text=None``, so the caller can re-attach. Past ``deadline`` (a
     ``time.monotonic()`` reading), a hold that still sends its spaces raises ``Stopped``.
+    ``heard`` is handed the headers as soon as they arrive, so a stop during the body
+    still leaves them known.
     """
     with client.stream(
         method, url, headers=headers, content=content, timeout=timeout or client.timeout
     ) as response:
+        if heard is not None:
+            heard(response.headers)
         chunks = []
         try:
             for chunk in response.iter_bytes():
@@ -66,11 +72,14 @@ async def arequest(
     content: bytes | None = None,
     timeout: httpx.Timeout | None = None,
     deadline: float | None = None,
+    heard: Callable[[httpx.Headers], None] | None = None,
 ) -> Answer:
     """``request()`` on httpx's async client."""
     async with client.stream(
         method, url, headers=headers, content=content, timeout=timeout or client.timeout
     ) as response:
+        if heard is not None:
+            heard(response.headers)
         chunks = []
         try:
             async for chunk in response.aiter_bytes():

{abysshub-0.1.1.dev1 → abysshub-0.1.1.dev3}/tests/test_client.py

@@ -67,3 +67,17 @@ def test_every_request_sends_the_user_agent() -> None:
         assert server.problems == []
     finally:
         server.close()
+
+
+def test_a_refusal_without_shortfall_or_price_carries_none_for_both() -> None:
+    recording = load_exchanges("run-refused-invalid-input.json")[0]
+    server = Replay(recording, "abyss_sk_x")
+    try:
+        with Abyss(api_key="abyss_sk_x", base_url=server.base) as abyss, pytest.raises(AbyssError) as raised:
+            abyss.run(recording["call"]["widget"], recording["call"]["input"])
+        assert raised.value.code == "invalid_input"
+        assert raised.value.shortfall is None
+        assert raised.value.price is None
+        assert server.problems == []
+    finally:
+        server.close()

{abysshub-0.1.1.dev1 → abysshub-0.1.1.dev3}/tests/test_timeout.py

@@ -33,6 +33,7 @@ def test_the_clients_timeout_applies_to_every_call() -> None:
                 abyss.run(WIDGET, INPUT)
         assert raised.value.code == "timeout"
         assert raised.value.run is not None and raised.value.run.id == ID
+        assert raised.value.run_id == ID
 
     against(work)
 
@@ -62,5 +63,6 @@ def test_async_the_clients_timeout_applies_and_a_calls_overrides_it(client: floa
         assert raised.value.code == "timeout"
         error_run = raised.value.run
         assert isinstance(error_run, AsyncRun) and error_run.id == ID and error_run.status == "queued"
+        assert raised.value.run_id == ID
 
     against(lambda base: asyncio.run(run(base)))