abysshub 0.0.1.dev14__tar.gz → 0.0.1.dev16__tar.gz

{abysshub-0.0.1.dev14 → abysshub-0.0.1.dev16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: abysshub
-Version: 0.0.1.dev14
+Version: 0.0.1.dev16
 Summary: The official Python library for the Abyss API.
 Project-URL: Homepage, https://abysshub.com
 Project-URL: Source, https://github.com/Abysshub/abysshub-sdk
@@ -17,10 +17,10 @@ Description-Content-Type: text/markdown
 
 # abysshub
 
-The official Python library for the [Abyss](https://abysshub.com) API.
-
 Pre-release: the Abyss API opens soon.
 
+The official Python library for the [Abyss](https://abysshub.com) API.
+
 ```python
 from abysshub import Abyss, AbyssError
 
@@ -68,7 +68,7 @@ run = abyss.run(widget, input, max_price=None, idempotency_key=None, timeout=Non
 - **`idempotency_key`:** each call presses with a fresh UUID `Idempotency-Key` unless you give one. Retries send the same one, so a run is never made or charged twice.
 - **`timeout`:** the seconds to wait at most (see [Timeouts](#timeouts)).
 
-The press holds until the run ends. When the hold ends early (a deploy cuts it, the API's holds are all taken, or an hour passes), `run()` re-attaches with `GET <Location>?wait=true` until the run ends. Re-attaching has no limit and is not a retry. Connecting has 10 s, and 30 s of silence counts as a cut.
+The press holds until the run ends. When the hold ends early (a deploy cuts it, the network goes down, the API's holds are all taken, or an hour passes), `run()` re-attaches with `GET <Location>?wait=true` until the run ends. Re-attaching has no limit and is not a retry. Connecting has 10 s, and 30 s of silence counts as a cut.
 
 A **run** is a dataclass with `/v1`'s fields: `id`, `widget`, `status` (`queued`, `running`, `succeeded` or `failed`), `price`, `result` (the Widget's JSON, a `dict` when it wrote an object), `output_files`, `error`, `created_at`, `started_at` and `ended_at`.
 
@@ -146,7 +146,9 @@ A request is sent again, at most `max_retries` times (2 by default), only after:
 - **`429 rate_limited` and `409 idempotency_key_in_use`:** after the `Retry-After` seconds;
 - **a `5xx`:** a short backoff (0.5 s, then 1 s).
 
-When the last try fails too, it raises. Every other refusal raises at once, and re-attaching never counts as a retry.
+When the last try fails too, it raises. Every other refusal raises at once.
+
+**Re-attaching never counts as a retry.** A re-attach that drops, or meets a `429`, `409` or `5xx`, is tried again with no limit until the network is back, pausing 0.5 s and doubling to at most 10 s (or the `Retry-After` seconds). Only `timeout` stops it.
 
 ## Timeouts
 

{abysshub-0.0.1.dev14 → abysshub-0.0.1.dev16}/README.md

@@ -1,9 +1,9 @@
 # abysshub
 
-The official Python library for the [Abyss](https://abysshub.com) API.
-
 Pre-release: the Abyss API opens soon.
 
+The official Python library for the [Abyss](https://abysshub.com) API.
+
 ```python
 from abysshub import Abyss, AbyssError
 
@@ -51,7 +51,7 @@ run = abyss.run(widget, input, max_price=None, idempotency_key=None, timeout=Non
 - **`idempotency_key`:** each call presses with a fresh UUID `Idempotency-Key` unless you give one. Retries send the same one, so a run is never made or charged twice.
 - **`timeout`:** the seconds to wait at most (see [Timeouts](#timeouts)).
 
-The press holds until the run ends. When the hold ends early (a deploy cuts it, the API's holds are all taken, or an hour passes), `run()` re-attaches with `GET <Location>?wait=true` until the run ends. Re-attaching has no limit and is not a retry. Connecting has 10 s, and 30 s of silence counts as a cut.
+The press holds until the run ends. When the hold ends early (a deploy cuts it, the network goes down, the API's holds are all taken, or an hour passes), `run()` re-attaches with `GET <Location>?wait=true` until the run ends. Re-attaching has no limit and is not a retry. Connecting has 10 s, and 30 s of silence counts as a cut.
 
 A **run** is a dataclass with `/v1`'s fields: `id`, `widget`, `status` (`queued`, `running`, `succeeded` or `failed`), `price`, `result` (the Widget's JSON, a `dict` when it wrote an object), `output_files`, `error`, `created_at`, `started_at` and `ended_at`.
 
@@ -129,7 +129,9 @@ A request is sent again, at most `max_retries` times (2 by default), only after:
 - **`429 rate_limited` and `409 idempotency_key_in_use`:** after the `Retry-After` seconds;
 - **a `5xx`:** a short backoff (0.5 s, then 1 s).
 
-When the last try fails too, it raises. Every other refusal raises at once, and re-attaching never counts as a retry.
+When the last try fails too, it raises. Every other refusal raises at once.
+
+**Re-attaching never counts as a retry.** A re-attach that drops, or meets a `429`, `409` or `5xx`, is tried again with no limit until the network is back, pausing 0.5 s and doubling to at most 10 s (or the `Retry-After` seconds). Only `timeout` stops it.
 
 ## Timeouts
 

{abysshub-0.0.1.dev14 → abysshub-0.0.1.dev16}/pyproject.toml

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

{abysshub-0.0.1.dev14 → abysshub-0.0.1.dev16}/src/abysshub/_client.py

@@ -31,6 +31,9 @@ REATTACH_PAUSE = 1.0
 RETRY_PAUSE = 0.5
 """Seconds before the first retry after a drop or a 5xx; the pause doubles with each retry."""
 
+RETRY_PAUSE_CEILING = 10.0
+"""The longest pause between two tries, in seconds, which only re-attaching, with no limit, reaches."""
+
 
 def _version() -> str:
     try:
@@ -348,11 +351,13 @@ class Abyss:
         return _expect(self._send(call, "GET", url), is_, message)
 
     def _hold(self, call: _Call, url: str, done: Callable[[_Reply], bool]) -> _Reply:
-        """Reads ``url`` until ``done``. Re-attaching has no limit and is not a retry."""
-        reply = self._send(call, "GET", url)
+        """Reads ``url`` until ``done``. Re-attaching has no limit and is not a retry: a
+        re-attach that drops, or meets a 429, 409 or 5xx, is tried again until the network
+        is back, and only the call's ``timeout`` stops it."""
+        reply = self._send(call, "GET", url, retries=math.inf)
         while not done(reply):
             self._sleep(call, REATTACH_PAUSE)
-            reply = self._send(call, "GET", url)
+            reply = self._send(call, "GET", url, retries=math.inf)
         return reply
 
     def _widget_url(self, widget: str) -> str:
@@ -375,9 +380,12 @@ class Abyss:
         url: str,
         headers: dict[str, str] | None = None,
         content: bytes | None = None,
+        retries: float | None = None,
     ) -> _Reply:
         """Sends one request to `/v1`. A drop before any headers, a 429, a 409 and a 5xx
-        are sent again, at most ``max_retries`` times; every other refusal raises at once."""
+        are sent again, at most ``retries`` times (``max_retries`` when left out); every
+        other refusal raises at once."""
+        limit = self.max_retries if retries is None else retries
         sent_headers = {
             "Authorization": f"Bearer {self._api_key}",
             "Accept": "application/json",
@@ -393,7 +401,7 @@ class Abyss:
                 raise self._timed_out(call) from None
             except httpx.TransportError as error:
                 self._check(call)
-                if attempt >= self.max_retries:
+                if attempt >= limit:
                     raise AbyssError(
                         "connection_error",
                         "The connection dropped, or timed out, before the API answered.",
@@ -409,7 +417,7 @@ class Abyss:
                     call.seen = run
                 return _Reply(parsed, run, answer.text is None, answer.headers.get("location"), request_id)
             pause = _retry_pause(answer, attempt)
-            if pause is None or attempt >= self.max_retries:
+            if pause is None or attempt >= limit:
                 raise _refusal(answer.status, parsed, request_id)
             self._sleep(call, pause)
             attempt += 1
@@ -427,7 +435,9 @@ def _retry_pause(answer: Answer, attempt: int) -> float | None:
 
 
 def _backoff(attempt: int) -> float:
-    return RETRY_PAUSE * 2**attempt
+    # The exponent stops growing once the ceiling is reached, so an unlimited re-attach
+    # never makes a float too large.
+    return min(RETRY_PAUSE * 2 ** min(attempt, 16), RETRY_PAUSE_CEILING)
 
 
 def _expect(reply: _Reply, is_: Callable[[Any], bool], message: str) -> Any: