tracebloc 4.0.1__tar.gz → 4.0.2__tar.gz

{tracebloc-4.0.1 → tracebloc-4.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tracebloc
-Version: 4.0.1
+Version: 4.0.2
 Summary: Build AI with anyone. On data that can't move. SDK for the tracebloc collaborative AI workspace.
 Author-email: tracebloc <lukas@tracebloc.io>
 License-Expression: MIT

{tracebloc-4.0.1 → tracebloc-4.0.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tracebloc"
-version = "4.0.1"
+version = "4.0.2"
 description = "Build AI with anyone. On data that can't move. SDK for the tracebloc collaborative AI workspace."
 license = "MIT"
 license-files = ["license.txt"]

{tracebloc-4.0.1 → tracebloc-4.0.2}/tracebloc/client.py

@@ -23,6 +23,13 @@ are **not** automatically retried, because a server-side 500 on an
 upload might still have persisted the model and a retry would create
 a duplicate. POST failures bubble up as :class:`APIError`; callers can
 implement idempotent retry at their layer if they want.
+
+**Overload (HTTP 429):** the backend sheds load with ``429`` plus
+``Retry-After``. A rejected request was not processed, so reads
+(``GET``/``HEAD``/``OPTIONS``) and login wait the stated time and retry
+(:func:`_send_honouring_429`: each wait capped at :data:`MAX_RETRY_WAIT_SECONDS`,
+all waits at :data:`MAX_TOTAL_WAIT_SECONDS`). Past the budget, and at once for
+every other call, the failure says the service is busy (:data:`BUSY_MESSAGE`).
 """
 
 from __future__ import annotations
@@ -31,7 +38,11 @@ from typing import Any, Dict, Mapping, Optional
 
 import json as _json
 import platform
+import time
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
 from importlib import metadata as _metadata
+from typing import Callable
 
 import requests
 from requests.adapters import HTTPAdapter
@@ -76,13 +87,83 @@ SDK_VERSION = _sdk_version()
 USER_AGENT = f"tracebloc-sdk/{SDK_VERSION} (python/{platform.python_version()})"
 
 
+#: Longest single ``Retry-After`` wait, and the most an SDK call waits in total.
+MAX_RETRY_WAIT_SECONDS = 60.0
+MAX_TOTAL_WAIT_SECONDS = 180.0
+
+#: Wait when a 429 names no usable ``Retry-After``; also the shortest wait taken,
+#: so a ``Retry-After: 0`` still spends the budget and the loop ends.
+_DEFAULT_RETRY_WAIT_SECONDS = 1.0
+
+#: Methods that are re-sent on a 429 (reads); login is re-sent explicitly.
+_RETRY_ON_429_METHODS = frozenset({"GET", "HEAD", "OPTIONS"})
+
+#: What a 429 reads as once the SDK has stopped waiting, or does not wait.
+BUSY_MESSAGE = (
+    "The tracebloc service is busy right now (HTTP 429). "
+    "Please retry in a few minutes."
+)
+
+# Indirection so tests can run the waits without sleeping.
+_sleep = time.sleep
+
+
+def _retry_after_seconds(response: requests.Response) -> float:
+    """Seconds a 429 asks us to wait: ``Retry-After`` as delay-seconds or an
+    HTTP date; a default when absent or unreadable. Never negative."""
+    raw = response.headers.get("Retry-After")
+    if isinstance(raw, str) and raw.strip():
+        raw = raw.strip()
+        try:
+            return max(0.0, float(raw))
+        except ValueError:
+            pass
+        try:
+            when = parsedate_to_datetime(raw)
+            if when.tzinfo is None:
+                when = when.replace(tzinfo=timezone.utc)
+            return max(0.0, (when - datetime.now(timezone.utc)).total_seconds())
+        except (TypeError, ValueError):
+            pass
+    return _DEFAULT_RETRY_WAIT_SECONDS
+
+
+def _send_honouring_429(
+    send: Callable[[], requests.Response], *, retry: bool
+) -> requests.Response:
+    """Run ``send``; on a 429 with ``retry`` wait ``Retry-After`` and run it
+    again until the budget (:data:`MAX_TOTAL_WAIT_SECONDS`) is spent.
+
+    Returns the last response, which may still be a 429 for the caller's
+    error handling. The wait that would overrun the budget is not taken.
+    """
+    waited = 0.0
+    while True:
+        response = send()
+        if response.status_code != 429 or not retry:
+            return response
+        wait = min(
+            max(_retry_after_seconds(response), _DEFAULT_RETRY_WAIT_SECONDS),
+            MAX_RETRY_WAIT_SECONDS,
+        )
+        if waited + wait > MAX_TOTAL_WAIT_SECONDS:
+            return response
+        response.close()
+        _sleep(wait)
+        waited += wait
+
+
 def _error_message(response: requests.Response) -> str:
     """The user-facing message for a non-2xx response.
 
     A 426 is the backend refusing this SDK as older than the oldest it
     supports (``{"error": "upgrade_required", "min_version": ...}``); say
     that, with the fix, rather than the bare ``upgrade_required`` code.
+    A 429 is the backend shedding load: :data:`BUSY_MESSAGE`, never the
+    server's own wording.
     """
+    if response.status_code == 429:
+        return BUSY_MESSAGE
     if response.status_code == 426:
         try:
             body = response.json()
@@ -101,7 +182,21 @@ def _error_message(response: requests.Response) -> str:
     return _extract_error_message(response)
 
 
-_DEFAULT_RETRY = Retry(
+class _Retry(Retry):
+    """urllib3 ``Retry`` that leaves a 429 alone.
+
+    A 429's ``Retry-After`` is honoured, capped, by ``_send_honouring_429``;
+    urllib3's own sleep on it is uncapped and would stack on that budget. The
+    header still governs a 503's wait.
+    """
+
+    def is_retry(self, method, status_code, has_retry_after=False):
+        if status_code == 429:
+            return False
+        return super().is_retry(method, status_code, has_retry_after)
+
+
+_DEFAULT_RETRY = _Retry(
     total=3,
     backoff_factor=0.5,
     status_forcelist=(500, 502, 503, 504),
@@ -252,17 +347,21 @@ class TraceblocClient:
         # Only passed when asked for, so every existing call is issued exactly
         # as before.
         extra = {"stream": True} if stream else {}
+        verb = method.upper()
         try:
-            response = self._session.request(
-                method=method.upper(),
-                url=url,
-                data=data,
-                json=json,
-                files=files,
-                params=params,
-                headers=self._headers(headers),
-                timeout=request_timeout,
-                **extra,
+            response = _send_honouring_429(
+                lambda: self._session.request(
+                    method=verb,
+                    url=url,
+                    data=data,
+                    json=json,
+                    files=files,
+                    params=params,
+                    headers=self._headers(headers),
+                    timeout=request_timeout,
+                    **extra,
+                ),
+                retry=verb in _RETRY_ON_429_METHODS,
             )
         except requests.RequestException as error:
             raise APIError(
@@ -312,13 +411,16 @@ class TraceblocClient:
         """
         url = self._url("api-token-auth/")
         try:
-            response = self._session.post(
-                url,
-                data={"username": username, "password": password},
-                # Not self._headers(): login must never carry a previous
-                # session's Authorization, only who is calling.
-                headers={"User-Agent": USER_AGENT},
-                timeout=self._config.timeout_seconds,
+            response = _send_honouring_429(
+                lambda: self._session.post(
+                    url,
+                    data={"username": username, "password": password},
+                    # Not self._headers(): login must never carry a previous
+                    # session's Authorization, only who is calling.
+                    headers={"User-Agent": USER_AGENT},
+                    timeout=self._config.timeout_seconds,
+                ),
+                retry=True,
             )
         except requests.RequestException as error:
             raise APIError(

{tracebloc-4.0.1 → tracebloc-4.0.2}/tracebloc.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tracebloc
-Version: 4.0.1
+Version: 4.0.2
 Summary: Build AI with anyone. On data that can't move. SDK for the tracebloc collaborative AI workspace.
 Author-email: tracebloc <lukas@tracebloc.io>
 License-Expression: MIT